Explain schema — Security Protocol reference

Access-explanation contract — explain(principal, object, operation) as a first-class API.

[ADR-0090 D6] Access-explanation contract — explain(principal, object, operation) as a first-class API.

The explain engine (@objectstack/plugin-security) walks the SAME code paths as the enforcement middleware — the same permission-set resolution, the same evaluator, the same RLS compiler — and reports what each layer of the evaluation pipeline contributed to the final decision. "Explained by construction": the report can never drift from enforcement because it IS enforcement, minus the throw.

Layer order mirrors the runtime pipeline: tenant_isolation → principal → required_permissions → object_crud → fls → owd_baseline → depth → sharing → vama_bypass → rls.

[C2 / ADR-0095] Record-grained explanation. The contract carries an optional recordId on the request and, when present, a per-layer record attribution plus a top-level record verdict on the response — so the sharing / rls / owd layers can report the ROW-LEVEL story for one concrete record (which share admitted it, which filter excluded it, whether the effective row filter matches). Object-level requests (no recordId) stay byte-compatible.

[ADR-0095 D1/D2] The contract also reserves the kernel-chain vocabulary the β engine + UI will fill: the always-first tenant wall as tenant_isolation (Layer 0), a per-layer kernelTier marking Layer 0 vs. business RLS (Layer 1), and the monotonic posture ladder (PLATFORM_ADMIN > TENANT_ADMIN > MEMBER > EXTERNAL) on the resolved principal.

Source: packages/spec/src/security/explain.zod.ts

TypeScript Usage

import { AccessMatrixSchema, AccessMatrixEntrySchema, AuthzPostureSchema, ExplainDecisionSchema, ExplainLayerSchema, ExplainMatchedRuleSchema, ExplainOperationSchema, ExplainRecordAttributionSchema, ExplainRequestSchema } from '@objectstack/spec/security';
import type { AccessMatrix, AccessMatrixEntry, AuthzPosture, ExplainDecision, ExplainLayer, ExplainMatchedRule, ExplainOperation, ExplainRecordAttribution, ExplainRequest } from '@objectstack/spec/security';

// Validate data
const result = AccessMatrixSchema.parse(data);

AccessMatrix

Properties

Property	Type	Required	Description
version	`1`	optional (default: `1`)
entries	`{ permissionSet: string; object: string; create: boolean; read: boolean; … }[]`	optional (default: `[]`)

AccessMatrixEntry

Properties

Property	Type	Required
permissionSet	`string`	✅
object	`string`	✅
create	`boolean`	✅
read	`boolean`	✅
edit	`boolean`	✅
delete	`boolean`	✅
viewAllRecords	`boolean`	✅
modifyAllRecords	`boolean`	✅
readScope	`string`	optional
writeScope	`string`	optional
sharingModel	`string`	optional

AuthzPosture

ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object posture permits; TENANT_ADMIN sees all rows in the org; MEMBER gets business RLS; EXTERNAL sees only explicitly shared rows.

Allowed Values

PLATFORM_ADMIN
TENANT_ADMIN
MEMBER
EXTERNAL

ExplainDecision

Properties

Property	Type	Required	Description
allowed	`boolean`	✅
object	`string`	✅
operation	`Enum<'read' \| 'create' \| 'update' \| 'delete' \| 'transfer' \| 'restore' \| 'purge' \| 'export'>`	✅
principal	`{ userId: string \| null; positions?: string[]; permissionSets?: string[]; principalKind?: Enum<'human' \| 'agent' \| 'service' \| 'guest' \| 'system'>; … }`	✅
layers	`{ layer: Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …>; kernelTier?: Enum<'layer_0_tenant' \| 'layer_1_business'>; verdict: Enum<'grants' \| 'denies' \| 'narrows' \| 'widens' \| 'neutral' \| 'not_applicable'>; detail: string; … }[]`	✅
readFilter	`any`	optional	The composed row filter the caller would be served with — the machine artifact behind the prose (null = unrestricted). Two shapes mean zero rows — `{ id: "__deny_all__" }` and the fail-closed RLS denial (`__rls_deny__` plus a colon and a UUID-shaped suffix, which can also ride inside an $and composite) — so a consumer pattern-matching this payload alone must match both; the decision itself is allowed plus the rls layer verdict.
record	`{ recordId: string; visible: boolean; decidedBy?: Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …> }`	optional	Row-level verdict for the specific record; set only for singular record-grained requests. An id the asker (the caller of explain) cannot read answers as missing, like a filtered, deleted or never-existed id: visible false, decidedBy omitted. Explaining another principal, the asker cannot read an id its own by-id read finds no row for or refuses; a principal explaining itself cannot read an id its read finds no row for.
records	`{ recordId: string; visible: boolean; decidedBy?: Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …> }[]`	optional	Per-record verdicts for a batch request — records[i] answers recordIds[i]; set only when the request carried recordIds.

Nested Shape: `ExplainDecision.principal`

Property	Type	Required	Description
userId	`string \| null`	✅
positions	`string[]`	optional (default: `[]`)
permissionSets	`string[]`	optional (default: `[]`)
principalKind	`Enum<'human' \| 'agent' \| 'service' \| 'guest' \| 'system'>`	optional
onBehalfOf	`{ userId: string }`	optional
posture	`Enum<'PLATFORM_ADMIN' \| 'TENANT_ADMIN' \| 'MEMBER' \| 'EXTERNAL'>`	optional	ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object posture permits; TENANT_ADMIN sees all rows in the org; MEMBER gets business RLS; EXTERNAL sees only explicitly shared rows.

Nested Shape: `ExplainDecision.layers[number]`

Property	Type	Required	Description
layer	`Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …>`	✅
kernelTier	`Enum<'layer_0_tenant' \| 'layer_1_business'>`	optional	ADR-0095 kernel layer: layer_0_tenant = the always-first org wall; layer_1_business = business RLS/sharing/ownership.
verdict	`Enum<'grants' \| 'denies' \| 'narrows' \| 'widens' \| 'neutral' \| 'not_applicable'>`	✅
detail	`string`	✅
contributors	`{ kind: Enum<'permission_set' \| 'position' \| 'system'>; name: string; via?: string; state?: Enum<'active' \| 'expired' \| 'deactivated'> }[]`	optional (default: `[]`)
record	`{ outcome: Enum<'admitted' \| 'excluded' \| 'not_evaluated'>; rowFilter?: any; matchesRecord?: boolean; rules?: object[]; … }`	optional	Row-level determination for the specific record under explanation; set only for record-grained requests.

Nested Shape: `ExplainDecision.record`

Property	Type	Required	Description
recordId	`string`	✅	The concrete record id this verdict is about (echoes the request recordId or recordIds[i]).
visible	`boolean`	✅	Whether the operation is permitted on this specific record after all layers.
decidedBy	`Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …>`	optional	The pipeline layer that decided the record-level outcome (excluded it, or last admitted it); omitted for a missing record.

Nested Shape: `ExplainDecision.records[number]`

Property	Type	Required	Description
recordId	`string`	✅	The concrete record id this verdict is about (echoes the request recordId or recordIds[i]).
visible	`boolean`	✅	Whether the operation is permitted on this specific record after all layers.
decidedBy	`Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| …>`	optional	The pipeline layer that decided the record-level outcome (excluded it, or last admitted it); omitted for a missing record.

ExplainLayer

Properties

Property	Type	Required	Description
layer	`Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| 'fls' \| 'owd_baseline' \| 'depth' \| 'sharing' \| 'vama_bypass' \| 'rls'>`	✅
kernelTier	`Enum<'layer_0_tenant' \| 'layer_1_business'>`	optional	ADR-0095 kernel layer: layer_0_tenant = the always-first org wall; layer_1_business = business RLS/sharing/ownership.
verdict	`Enum<'grants' \| 'denies' \| 'narrows' \| 'widens' \| 'neutral' \| 'not_applicable'>`	✅
detail	`string`	✅
contributors	`{ kind: Enum<'permission_set' \| 'position' \| 'system'>; name: string; via?: string; state?: Enum<'active' \| 'expired' \| 'deactivated'> }[]`	optional (default: `[]`)
record	`{ outcome: Enum<'admitted' \| 'excluded' \| 'not_evaluated'>; rowFilter?: any; matchesRecord?: boolean; rules?: object[]; … }`	optional	Row-level determination for the specific record under explanation; set only for record-grained requests.

Nested Shape: `ExplainLayer.record`

Property	Type	Required	Description
outcome	`Enum<'admitted' \| 'excluded' \| 'not_evaluated'>`	✅	This layer's row-level outcome for the record: admitted, excluded, or not_evaluated (skipped/not row-scoped).
rowFilter	`any`	optional	The effective row predicate this layer contributed for the record set, published as composed (null = unrestricted). Two shapes mean zero rows — `{ id: "__deny_all__" }` and the fail-closed RLS denial (`__rls_deny__` plus a colon and a UUID-shaped suffix) — so a consumer pattern-matching this payload alone must match both; the decision itself is outcome/matchesRecord plus the layer verdict.
matchesRecord	`boolean`	optional	Whether the specific record satisfies rowFilter — the judgement behind outcome.
rules	`{ kind: Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| …>; name: string; grants?: Enum<'read' \| 'edit' \| 'full'>; via?: string; … }[]`	optional (default: `[]`)	Concrete rules, shares, or policies this layer evaluated against the record, in evaluation order.
detail	`string`	optional	Human-readable, record-specific explanation of this layer's outcome.

ExplainMatchedRule

Properties

Property	Type	Required	Description
kind	`Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| 'team' \| 'territory' \| 'rls_policy'>`	✅	The row-visibility source kind evaluated for this record at this layer.
name	`string`	✅	Stable identifier of the concrete rule, share, or policy that was evaluated.
grants	`Enum<'read' \| 'edit' \| 'full'>`	optional	Access level a sharing source grants on the record (authorable: read/edit; `full` appears only for legacy rows pending normalisation).
via	`string`	optional	How the rule reached the principal — recipient group/position, ownership, or the matching criteria.
predicate	`any`	optional	The row predicate this rule contributed, when it is filter-shaped (null = unrestricted).
effect	`Enum<'admits' \| 'excludes' \| 'neutral'>`	✅	The rule's effect on THIS record: admits, excludes, or neutral.

ExplainOperation

Allowed Values

read
create
update
delete
transfer
restore
purge
export

ExplainRecordAttribution

Properties

Property	Type	Required	Description
outcome	`Enum<'admitted' \| 'excluded' \| 'not_evaluated'>`	✅	This layer's row-level outcome for the record: admitted, excluded, or not_evaluated (skipped/not row-scoped).
rowFilter	`any`	optional	The effective row predicate this layer contributed for the record set, published as composed (null = unrestricted). Two shapes mean zero rows — `{ id: "__deny_all__" }` and the fail-closed RLS denial (`__rls_deny__` plus a colon and a UUID-shaped suffix) — so a consumer pattern-matching this payload alone must match both; the decision itself is outcome/matchesRecord plus the layer verdict.
matchesRecord	`boolean`	optional	Whether the specific record satisfies rowFilter — the judgement behind outcome.
rules	`{ kind: Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| …>; name: string; grants?: Enum<'read' \| 'edit' \| 'full'>; via?: string; … }[]`	optional (default: `[]`)	Concrete rules, shares, or policies this layer evaluated against the record, in evaluation order.
detail	`string`	optional	Human-readable, record-specific explanation of this layer's outcome.

Nested Shape: `ExplainRecordAttribution.rules[number]`

Property	Type	Required	Description
kind	`Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| …>`	✅	The row-visibility source kind evaluated for this record at this layer.
name	`string`	✅	Stable identifier of the concrete rule, share, or policy that was evaluated.
grants	`Enum<'read' \| 'edit' \| 'full'>`	optional	Access level a sharing source grants on the record (authorable: read/edit; `full` appears only for legacy rows pending normalisation).
via	`string`	optional	How the rule reached the principal — recipient group/position, ownership, or the matching criteria.
predicate	`any`	optional	The row predicate this rule contributed, when it is filter-shaped (null = unrestricted).
effect	`Enum<'admits' \| 'excludes' \| 'neutral'>`	✅	The rule's effect on THIS record: admits, excludes, or neutral.

ExplainRequest

Properties

Property	Type	Required	Description
object	`string`	✅
operation	`Enum<'read' \| 'create' \| 'update' \| 'delete' \| 'transfer' \| 'restore' \| 'purge' \| 'export'>`	✅
recordId	`string`	optional	Optional id of one concrete record to explain at row granularity; omitted = object-level (pre-C2) request. Mutually exclusive with recordIds.
recordIds	`string[]`	optional	Batch of record ids (1–200) to answer at row granularity in one round trip; records[i] answers recordIds[i]. Mutually exclusive with recordId.
userId	`string`	optional

Explain schema — Security Protocol reference

On this page