permdock 0.1.0 → 0.3.0

package/dist/{policy-CInmNGkM.d.ts → policy-IB6yxpC3.d.ts}

@@ -1,5 +1,5 @@
-import { _ as ResourceNode, d as Permission, f as PermissionKind, p as PermissionTree } from "./permissions-B4apnahQ.js";
-import { a as RoleTree, i as RoleMeta, n as PlanTree, r as Role, t as Plan } from "./vocabulary-Dk0fs-Jk.js";
+import { f as Permission, m as PermissionTree, p as PermissionKind, y as ResourceNode } from "./permissions-DttnqqxC.js";
+import { a as RoleTree, i as RoleMeta, n as PlanTree, r as Role, t as Plan } from "./vocabulary-DA8a8zif.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/conditions/ast.d.ts
 type ConditionRef = {
@@ -82,11 +82,21 @@ type RelatedCondition = {
    * the `relation` lookup (`relation` is then empty).
    */
   readonly ids?: readonly string[];
+  readonly permission?: string;
   /**
    * The row's boolean column that keeps ancestor grants out: with `parent` or
    * `hops`, a restricted row matches nothing; without, the walk stops at the row.
    */
   readonly restricted?: string;
+  readonly restrictedAncestors?: RestrictedAncestors;
+  readonly passRestricted?: true;
+};
+type RestrictedAncestors = {
+  readonly resource: string;
+  readonly id: string;
+  readonly parent: string;
+  readonly depth: number;
+  readonly field: string;
 };
 type RelatedHop = {
   readonly link: string;
@@ -107,7 +117,16 @@ type SqlFunctionCondition = {
   readonly args: readonly SqlFunctionArg[];
   readonly twin: Condition;
 };
-type Condition = ComparisonCondition | InCondition | IsNullCondition | AndCondition | OrCondition | NotCondition | MemberOfCondition | RelatedCondition | OpaqueCondition | SqlFunctionCondition;
+/**
+ * The request's session was checked against the Auth server while the
+ * subject was resolved (`liveSession: true`), not only verified from the
+ * token: a revoked session still verifies until `exp`. Written
+ * `{ subject: { session: { live: true } } }`.
+ */
+type LiveSessionCondition = {
+  readonly op: "liveSession";
+};
+type Condition = ComparisonCondition | InCondition | IsNullCondition | AndCondition | OrCondition | NotCondition | MemberOfCondition | RelatedCondition | OpaqueCondition | SqlFunctionCondition | LiveSessionCondition;
 declare function isConditionRef(value: unknown): value is ConditionRef;
 declare function isConditionDate(value: unknown): value is ConditionDate;
 declare function isCondition(value: unknown): value is Condition;
@@ -172,6 +191,12 @@ type Membership = {
   readonly managedBy?: "idp";
   /** Seats this membership holds (`dev-mode`, `editor`); `plan()` grantees match them inside the active tenant. */
   readonly entitlements?: readonly string[];
+  /**
+   * Set when the instance or an ancestor instance is suspended: the
+   * permission keys the membership still grants (`suspension.scopes.<scope>.keep`).
+   * Every other grant, allow or deny, ignores it, and so do role listings.
+   */
+  readonly keep?: readonly string[];
   /** Input only: an instance of the first scope. */
   readonly tenant?: string;
   /** Input only: an instance of the second scope, inside `tenant`. */
@@ -184,6 +209,8 @@ type Membership = {
 type CustomRoleGrant = {
   readonly permission: string;
   readonly effect?: "allow" | "deny";
+  /** A level the permission's resource declares (`resource(…, { levels })`); allows only. */
+  readonly level?: string;
 };
 type CustomRoleBody = {
   readonly name: string;
@@ -236,6 +263,8 @@ type Actor = {
   readonly binding?: Binding;
   /** `true` narrows every policy delegation to this actor to its read-only permissions (`readOnlyHint`). */
   readonly readOnly?: boolean;
+  /** The stable name the application gives this OAuth client (`ClientNames`), set by the subject resolver from the verified client id; policy delegations match it with `to: { kind, client }`. */
+  readonly client?: string;
   readonly [key: string]: unknown;
 };
 type AuthorizationDetail = {
@@ -259,6 +288,12 @@ type Subject<TPrincipal extends Principal = Principal> = {
   readonly expiresAt?: number;
   /** The token's memberships are behind the source's authorization version: `fresh` permissions deny. */
   readonly stale?: true;
+  /**
+   * The resolver checked the session against the Auth server for this request
+   * (`liveSession: true`), so `{ subject: { session: { live: true } } }` holds.
+   * Never read from claims.
+   */
+  readonly liveSession?: true;
 };
 //#endregion
 //#region src/core/scopes.d.ts
@@ -322,7 +357,13 @@ type AssuranceGrantee = {
   readonly amr?: readonly string[];
   readonly maxAge?: number;
 };
-type Grantee = RoleGrantee | AnyoneGrantee | AuthenticatedGrantee | RelationGrantee | PlanGrantee | ActorGrantee | AssuranceGrantee;
+type InheritGrantee = {
+  readonly kind: "inherit";
+  readonly permission: string;
+  readonly resource: string;
+  readonly through: "parent" | readonly string[];
+};
+type Grantee = RoleGrantee | InheritGrantee | AnyoneGrantee | AuthenticatedGrantee | RelationGrantee | PlanGrantee | ActorGrantee | AssuranceGrantee;
 type GranteeInput = Grantee | Role | Plan | string | readonly GranteeInput[];
 declare function anyone(): AnyoneGrantee;
 declare function authenticated(): AuthenticatedGrantee;
@@ -330,6 +371,9 @@ declare function relation(resource: Permission | PermissionTree, name: string, o
   readonly through?: "parent" | readonly string[];
   readonly depth?: number;
 }): RelationGrantee;
+declare function inherit(permission: Permission, options: {
+  readonly through: "parent" | readonly string[];
+}): InheritGrantee;
 declare function plan(name: Plan | string): PlanGrantee;
 declare function actor(kind: string): ActorGrantee;
 declare function assurance(options: {
@@ -466,11 +510,14 @@ type ApprovalPolicy = {
   readonly tenant?: string;
   /** Actor kinds it applies to (`['agent']`); absent: every call. A call without an actor never matches a list. */
   readonly actors?: readonly string[];
-  /** A portable condition over the row. */
+  /** A portable condition over the row; instance permissions only, since a collection action has no row. */
   readonly where?: Condition;
   /** A portable condition over the call's input (the proposed row). */
   readonly check?: Condition;
-  /** The same shape as `allow(..., { approval })`, without `escalation`. */
+  /**
+   * The same shape as `allow(..., { approval })`. An `escalation` here widens
+   * only this entry's stages, never the code's.
+   */
   readonly approval: ApprovalOption;
 };
 /**
@@ -484,7 +531,31 @@ type ApprovalPolicySource = {
     readonly tenants: readonly string[];
   }): readonly ApprovalPolicy[] | Promise<readonly ApprovalPolicy[]>;
 };
+/** The denial detail when an `ApprovalPolicySource` fails: every call an allow would grant denies with reason `approval`. */
+declare const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
 declare function memoryApprovalPolicies(policies: readonly ApprovalPolicy[]): ApprovalPolicySource;
+/**
+ * Why an `ApprovalPolicy` entry does not load. `unknown-permission`: the
+ * policy declares no such key (the entry applies to nothing). `invalid`: a
+ * field has the wrong shape or the approval option does not normalise.
+ * `where-on-collection`: `where` reads a row, which a collection action
+ * never has, so the entry could never match; use `check` over the input.
+ * `stale-on-without-version`: `staleOn` needs an instance permission whose
+ * resource declares `version`.
+ */
+type ApprovalPolicyProblem = "unknown-permission" | "invalid" | "where-on-collection" | "stale-on-without-version";
+type ApprovalPolicyValidation = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly problem: ApprovalPolicyProblem;
+};
+/**
+ * Checks one entry against the policy the way `approvalPoliciesFor` loads
+ * it, for an application to refuse a bad entry when it is saved instead of
+ * finding every call denied. Never throws.
+ */
+declare function validateApprovalPolicy(policy: Policy, entry: unknown): ApprovalPolicyValidation;
 //#endregion
 //#region src/core/arazzo.d.ts
 type ArazzoSimulateInput = {
@@ -558,13 +629,9 @@ type RoleChangeTarget = {
   /** `idp` when the identity provider owns the target's membership: the application cannot change it. */
   readonly managedBy?: "idp";
 };
-type RoleChange = {
+type RoleChangeBase = {
   readonly kind: "assign" | "revoke" | "transfer";
   readonly role: string | Role;
-  /** The scope the role is held at (a declared name or alias). */
-  readonly scope: string;
-  /** The scope instance. */
-  readonly id: string;
   /** Ids of the instance's ancestor scopes; a holder there may assign here. */
   readonly within?: Readonly<Record<string, string>>;
   readonly target: RoleChangeTarget;
@@ -575,6 +642,20 @@ type RoleChange = {
    */
   readonly holders?: number;
 };
+/**
+ * A role held at a named scope instance (`scope` is a declared name or alias
+ * and `id` the instance), or a global role: `scope: 'global'` with no `id`.
+ * A global change has no tenant, so `within` and `holders` do not apply to it.
+ */
+type RoleChange = RoleChangeBase & ({
+  /** The scope the role is held at (a declared name or alias). */
+  readonly scope: string;
+  /** The scope instance. */
+  readonly id: string;
+} | {
+  readonly scope: "global";
+  readonly id?: undefined;
+});
 /**
  * `granted` names the role that authorised the change (`null` when a
  * `meta.manageRoles` holder or the declared-role ceiling did); `denied` lists
@@ -712,6 +793,13 @@ type DecideOptions = {
   readonly field?: string;
   /** `true` attaches a `trace` to the decision: the grants evaluated, matched and skipped. Off by default and free when off. */
   readonly explain?: boolean;
+  /**
+   * A declared scope name: only memberships of that scope answer the check.
+   * Naming the first scope keeps nested memberships out of a tenant-level
+   * guard on a collection action. Global roles still apply; resource roles
+   * and memberships of other scopes are skipped with reason `scope`.
+   */
+  readonly scope?: string;
 };
 type SimulateOptions = {
   /** Decision clock in Unix seconds for the whole batch: grant validity, membership expiry and limits are read as of this instant. Defaults to the current time. */
@@ -738,14 +826,34 @@ type WhereResult = {
   /** The policy's resource graph, for `related`; not enumerable either. */
   readonly resources?: ReadonlyMap<string, ResourceNode>;
 };
+type SnapshotOptions = {
+  readonly include?: readonly (Permission | {
+    readonly [key: string]: unknown;
+  })[];
+  readonly tenants?: "all";
+  readonly signer?: TokenSigner;
+  readonly audience?: string | readonly string[];
+};
 type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   readonly can: {
     (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): boolean;
     (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): boolean;
+    /**
+     * A permission held as `Permission` at run time (from a list, a catalog
+     * or `findPermission`), whose kind the type does not say: pass `data`,
+     * or `undefined` for a check without a row.
+     */
+    (permission: Permission, data: unknown, options?: DecideOptions): boolean;
   };
   readonly decide: {
     (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): Decision;
     (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): Decision;
+    /**
+     * A permission held as `Permission` at run time (from a list, a catalog
+     * or `findPermission`), whose kind the type does not say: pass `data`,
+     * or `undefined` for a check without a row.
+     */
+    (permission: Permission, data: unknown, options?: DecideOptions): Decision;
   };
   readonly assert: {
     (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): Extract<Decision, {
@@ -754,6 +862,14 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
     (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): Extract<Decision, {
       readonly outcome: "granted";
     }>;
+    /**
+     * A permission held as `Permission` at run time (from a list, a catalog
+     * or `findPermission`), whose kind the type does not say: pass `data`,
+     * or `undefined` for a check without a row.
+     */
+    (permission: Permission, data: unknown, options?: DecideOptions): Extract<Decision, {
+      readonly outcome: "granted";
+    }>;
   };
   /**
    * `decide` with `explain: true`: the same decision, with a `trace` that
@@ -764,6 +880,7 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   readonly explain: {
     (permission: Permission<string, unknown, "instance">, data: unknown, options?: Omit<DecideOptions, "explain">): ExplainedDecision;
     (permission: Permission<string, unknown, "collection">, data?: unknown, options?: Omit<DecideOptions, "explain">): ExplainedDecision;
+    (permission: Permission, data: unknown, options?: Omit<DecideOptions, "explain">): ExplainedDecision;
   };
   readonly filter: <T>(permission: Permission<string, T, "instance">, rows: readonly T[], options?: DecideOptions) => T[];
   readonly pick: <T>(permission: Permission<string, T, "instance">, row: T, options?: DecideOptions) => Partial<T>;
@@ -780,14 +897,15 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
     }): PermDock<V>;
     (plan: ArazzoSimulateInput): ArazzoPlan;
   };
-  readonly snapshot: (options?: {
-    readonly include?: readonly (Permission | {
-      readonly [key: string]: unknown;
-    })[];
-    readonly tenants?: "all";
-    readonly signer?: TokenSigner;
-    readonly audience?: string | readonly string[];
-  }) => Snapshot | Promise<string>;
+  readonly snapshot: {
+    (options?: SnapshotOptions & {
+      readonly signer?: undefined;
+    }): Snapshot;
+    (options: SnapshotOptions & {
+      readonly signer: TokenSigner;
+    }): Promise<string>;
+    (options?: SnapshotOptions): Snapshot | Promise<string>;
+  };
   readonly on: (event: "decision" | "denied" | "approval" | "auth" | "error", handler: (payload: unknown) => void) => () => void;
   readonly tenant: (id: string) => PermDock<V>;
   readonly team: (id: string) => PermDock<V>;
@@ -805,8 +923,14 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   }) => readonly Role[];
   /** The distinct `meta.audience` values of the roles held in the active tenant, in rank order. */
   readonly audiences: () => readonly string[];
+  /**
+   * The roles the subject may hand out in a tenant (the active one by
+   * default), or with `scope: 'global'` the global roles it may hand out. A
+   * snapshot answers only the tenant form.
+   */
   readonly assignableRoles: (options?: {
     readonly tenant?: string;
+    readonly scope?: "global";
   }) => readonly Role[];
   /**
    * The custom-role ceiling the subject may hand out: in a tenant (empty
@@ -818,6 +942,15 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
     readonly tenant?: string;
     readonly scope?: "global";
   }) => readonly Permission[];
+  /**
+   * The levels of `permission` (`resource(…, { levels })`) the subject may
+   * hand out in a custom role: those it holds, or every level with
+   * `meta.manageRoles`. Empty when the permission is not assignable.
+   */
+  readonly assignableLevels: (permission: Permission, options?: {
+    readonly tenant?: string;
+    readonly scope?: "global";
+  }) => readonly string[];
   /**
    * Whether the subject may assign, revoke or transfer a role in one scope
    * instance: `assigns`, the ceiling, `for`, `exclusiveWith`, `min`, `max`
@@ -851,12 +984,22 @@ type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   readonly plans: V["plans"] extends PlanTree ? V["plans"] : PlanTree;
   readonly permissions: V["permissions"] extends Policy["permissions"] ? V["permissions"] : Policy["permissions"];
   readonly subject: Subject;
+  /**
+   * The same subject, tenant, team, actor, delegation, sink and limits with
+   * other sources: `customRoles`, `approvalPolicies` or `relations`. The
+   * sources it names are read again for the subject's tenants; the others
+   * keep what this instance loaded. Returns a promise when a source it names
+   * answers asynchronously.
+   */
+  readonly derive: (options: DeriveOptions) => PermDock<V> | Promise<PermDock<V>>;
 };
+/** What `permdock.derive` may replace: the sources read after the subject is resolved. */
+type DeriveOptions = Pick<PermDockOptions, "customRoles" | "approvalPolicies" | "relations">;
 type PermDockOptions = {
   readonly tenant?: string;
   /** One source, or several composed with `composeMemberships`. */
   readonly memberships?: MembershipSource | readonly MembershipSource[];
-  readonly customRoles?: RoleSource;
+  readonly customRoles?: RoleSource | RoleSourceFactory;
   /** Plans and seats from billing, merged into `principal.plans` for the active tenant. */
   readonly entitlements?: EntitlementSource;
   readonly actor?: Actor;
@@ -884,8 +1027,9 @@ type CredentialPermission = {
 /**
  * Credential v1: what a verified API key stands for, never the secret. A
  * `user` credential acts as its owner (`principal`) narrowed to
- * `permissions`; a `service` credential is its own `service` principal
- * holding `roles` in `tenant`, narrowed the same way.
+ * `permissions`, and to the memberships inside `tenant` when it names one;
+ * a `service` credential is its own `service` principal holding `roles` in
+ * `tenant`, narrowed the same way.
  */
 type Credential = {
   readonly v: 1;
@@ -893,7 +1037,11 @@ type Credential = {
   readonly kind: CredentialKind;
   /** The owner of a `user` credential, or the id of the service principal. */
   readonly principal: string;
-  /** Service only: the instance of the first scope its roles are held in. */
+  /**
+   * The instance of the first scope the key is held to. Required on a
+   * service credential, where its roles are held; optional on a user
+   * credential, where it keeps only the owner's memberships inside it.
+   */
   readonly tenant?: string;
   /** Service only: the roles it holds in `tenant`. */
   readonly roles?: readonly string[];
@@ -935,6 +1083,8 @@ type CredentialRequestBase = {
 };
 type CredentialRequest = (CredentialRequestBase & {
   readonly kind: "user";
+  /** Holds the key to the creator's memberships inside this tenant. */
+  readonly tenant?: string;
 }) | (CredentialRequestBase & {
   readonly kind: "service";
   /** The service principal's id; defaults to the credential id. */
@@ -972,7 +1122,7 @@ declare function credentialPolicyViolation(credential: Credential, policy: Crede
  * Validates an untrusted credential record and returns a frozen copy with
  * only the v1 fields, or `undefined`. Unknown fields are dropped; a wrong
  * type in a known field, a service credential without `tenant` and `roles`,
- * or a user credential with either, rejects the whole record.
+ * or a user credential with `roles`, rejects the whole record.
  */
 declare function parseCredential(input: unknown): Credential | undefined;
 /**
@@ -986,7 +1136,9 @@ declare function credentialDelegation(credential: Credential, permissions: Permi
  * The subject a verified credential acts as. A `user` credential is its
  * owner, passed live as `owner` (roles and memberships as of this request),
  * with the credential's delegation: every check is the owner's rights
- * intersected with the key's. A `service` credential is a `service`
+ * intersected with the key's. One that names a `tenant` makes it the active
+ * tenant, and `createPermDock` then keeps only the owner's memberships
+ * inside it and no global role. A `service` credential is a `service`
  * principal whose only membership is `roles` in `tenant`. An owner whose id
  * is not the credential's `principal`, or who is not a user, is anonymous.
  */
@@ -998,11 +1150,11 @@ declare function credentialSubject(credential: Credential, options: {
  * Decides whether the subject of `permdock` may create the credential in
  * `request`. The creator must be a signed-in user or service that is not
  * itself a link or a credential; a delegated creator hands out only what its
- * delegation covers. A service key's tenant must be one the creator is a
- * member of, its roles among the creator's `assignableRoles` there and its
+ * delegation covers. A key's tenant must be one the creator is a member of;
+ * a service key's roles among the creator's `assignableRoles` there and its
  * permissions within `assignablePermissions` there (`exceeds-creator`). The
- * `credentials` policy of the key's tenant (a service key's own, a user
- * key's the creator's active tenant) then applies (`credential-policy`; a
+ * `credentials` policy of the key's tenant (its own, or for a user key
+ * without one the creator's active tenant) then applies (`credential-policy`; a
  * settings source that throws denies with `rule: 'unavailable'`), and
  * `approval` makes the result `approval-required` until `approved` carries
  * its token. PermDock never stores the credential; the application does,
@@ -1049,11 +1201,31 @@ type DecisionProvider = {
   }): Promise<readonly string[] | null | undefined>;
 };
 type RoleSource = {
-  rolesFor(tenant: string): CustomRole[] | Promise<CustomRole[]>;
+  /**
+   * The custom roles of one tenant. `createPermDock` passes `held`, the role
+   * names the subject's live memberships hold there, declared or not, so a
+   * source can skip its read when none of them is a custom role.
+   */
+  rolesFor(tenant: string, context?: {
+    readonly held: readonly string[];
+  }): CustomRole[] | Promise<CustomRole[]>;
   assignable?(tenant: string): string[] | Promise<string[]>;
-  /** Platform custom roles (`scope: 'global'`), read once per signed-in subject. A role here with a tenant is ignored. */
-  globalRoles?(): CustomRole[] | Promise<CustomRole[]>;
+  /**
+   * Platform custom roles (`scope: 'global'`), read once per signed-in
+   * subject, with `held`, the global role names the subject holds. A role
+   * here with a tenant is ignored.
+   */
+  globalRoles?(context?: {
+    readonly held: readonly string[];
+  }): CustomRole[] | Promise<CustomRole[]>;
 };
+/**
+ * A `RoleSource` built for the subject the instance serves, for an adapter
+ * option shared by every request: it gets the resolved subject (principal,
+ * actor and delegation) and returns that subject's source, or `undefined`
+ * for none. A throw reads no custom roles and reports `source-threw`.
+ */
+type RoleSourceFactory = (subject: Subject) => RoleSource | undefined;
 /** One member of a scope instance, as `MembershipSource.list` returns it. */
 type MemberEntry = {
   readonly principal: {
@@ -1076,16 +1248,21 @@ type MembershipSource = {
   /**
    * The principal's current authorization version, bumped on every membership
    * change. A token whose `authzVersion` is behind it is stale for the
-   * policy's `fresh` permissions.
+   * policy's `fresh` permissions. `roles` and `memberships` are what the
+   * token claims, so a source can read more than the version in the same
+   * call when the claims show it will be needed.
    */
   version?(principal: {
     readonly id: string;
+    readonly roles?: readonly string[];
+    readonly memberships?: readonly Membership[];
   }): number | undefined | Promise<number | undefined>;
   /**
    * Keep the memberships the verified token carries and read this source only
    * when the token says they were truncated (`claimsFirst`).
    */
   readonly claimsFirst?: boolean;
+  readonly onStale?: "deny" | "reread";
 };
 /** An object's parent chain, as `RelationSource.ancestors` returns it. */
 type RelationChain = {
@@ -1144,6 +1321,10 @@ type RelationSource = {
     readonly id: string;
     readonly relation: string;
   }): RelationHolder[] | Promise<RelationHolder[]>;
+  row?(query: {
+    readonly resource: string;
+    readonly id: string;
+  }): Readonly<Record<string, unknown>> | null | undefined | Promise<Readonly<Record<string, unknown>> | null | undefined>;
 };
 /** Plan and seat names a principal holds in a tenant, from billing (Stripe Entitlements, a table). */
 type EntitlementSource = {
@@ -1236,6 +1417,11 @@ type Snapshot = {
    * from applying; they grant nothing and name the plan a denial asks for.
    */
   readonly notEntitled?: readonly SnapshotNotEntitled[];
+  /**
+   * The row id field per resource whose `id` option is not `id`, for the
+   * grants in `grants`. Absent when every one reads `id`.
+   */
+  readonly ids?: Readonly<Record<string, string>>;
   /**
    * The permission keys the policy's delegations let the actor use for the
    * principal, sorted; present only when one applies. Outside it a check is
@@ -1257,12 +1443,16 @@ type SnapshotScope = {
   readonly within?: string;
   /** Resources whose rows this scope's key partitions, from their `memberOf` relations. */
   readonly resources?: readonly string[];
+  /** Resource name to the field holding this scope's id, for a resource whose field is not `key` (its own `id`). */
+  readonly fields?: Readonly<Record<string, string>>;
 };
 /** The declared roles and the custom-role ceiling the subject may assign in one tenant. */
 type SnapshotAssignable = {
   readonly tenant: string;
   readonly roles: readonly string[];
   readonly permissions: readonly Permission[];
+  /** Permission key to the levels the subject may hand out; only permissions whose resource declares levels. */
+  readonly levels?: Readonly<Record<string, readonly string[]>>;
 };
 type SnapshotGrant = {
   readonly permission: string;
@@ -1282,6 +1472,34 @@ type SnapshotGrant = {
   /** When the grant applies (Unix seconds, `from` inclusive, `until` exclusive); absent means always. */
   readonly validity?: GrantValidity;
 };
+/**
+ * What a policy grants, as JSON a client builds snapshots from without the
+ * policy: `localSnapshotManifest(policy)` writes it, `localSnapshot` in
+ * `permdock/react-native` reads it.
+ */
+type LocalSnapshotManifest = {
+  readonly v: 1;
+  readonly scopes?: readonly SnapshotScope[];
+  readonly vocabulary?: Snapshot["vocabulary"];
+  /** Declared role names; a custom role cannot take one. */
+  readonly roles: readonly string[];
+  /** Declared role names in rank order, when an `assigns` graph ranks them. */
+  readonly rank?: readonly string[];
+  /** Every declared grant, without a membership. */
+  readonly grants: readonly SnapshotGrant[];
+  /** Per custom-role scope (`global` for platform roles): the grants each entry resolves to. */
+  readonly custom: Readonly<Record<string, LocalCustomRoleTable>>;
+};
+/** Grants a custom role entry resolves to, held by a placeholder role the client renames. */
+type LocalCustomRoleTable = {
+  /** `{ permission }` per permission key, and `{ permission, level }` per declared level. */
+  readonly permissions: Readonly<Record<string, {
+    readonly all: readonly SnapshotGrant[];
+    readonly levels?: Readonly<Record<string, readonly SnapshotGrant[]>>;
+  }>>;
+  /** `includes: [role]` per declared role. */
+  readonly includes: Readonly<Record<string, readonly SnapshotGrant[]>>;
+};
 type SnapshotSource = {
   get(): Promise<Snapshot | string> | Snapshot | string;
   subscribe?(listener: () => void): () => void;
@@ -1502,6 +1720,12 @@ type SettingsSource = {
   settingsFor(tenant: string): TenantSettings | undefined | Promise<TenantSettings | undefined>;
 };
 declare function memorySettings(settings: Readonly<Record<string, TenantSettings>>): SettingsSource;
+/** Memberships keyed by principal id; `tenant` is not a filter, as for a database source. */
+declare function memoryMembershipSource(entries: Readonly<Record<string, readonly Membership[]>>): MembershipSource;
+/** A snapshot held in memory; `set` replaces it and notifies every subscriber. */
+declare function memorySnapshotSource(initial: Snapshot | string): SnapshotSource & {
+  set(snapshot: Snapshot | string): void;
+};
 declare function memoryRoleSource(customRoles: readonly CustomRole[]): RoleSource;
 //#endregion
 //#region src/conditions/normalize.d.ts
@@ -1521,9 +1745,20 @@ type WhereShorthand<T = Record<string, unknown>> = {
   readonly and?: readonly WhereShorthand<T>[];
   readonly or?: readonly WhereShorthand<T>[];
   readonly not?: WhereShorthand<T>;
-} & { readonly [K in keyof T]?: T[K] | FieldOperator | {
+} & ("subject" extends keyof T ? { readonly [K in keyof T as Exclude<K, "subject">]?: FieldWhere<T[K]>; } & {
+  readonly subject?: SubjectWhere | FieldWhere<T["subject"]>;
+} : { readonly [K in keyof T]?: FieldWhere<T[K]>; } & {
+  /** Holds only when the resolver checked the session live (`liveSession: true`). */
+  readonly subject?: SubjectWhere;
+});
+type SubjectWhere = {
+  readonly session: {
+    readonly live: true;
+  };
+};
+type FieldWhere<V> = V | FieldOperator | {
   readonly ref: string;
-}; };
+};
 //#endregion
 //#region src/core/approvers.d.ts
 /** One named approver, by principal id. */
@@ -1531,13 +1766,41 @@ type UserApprover = {
   readonly kind: "user";
   readonly id: string;
 };
+/**
+ * Whoever holds `permission` in the request's tenant, through any role,
+ * custom roles included. Checked only through verdict facts
+ * (`ApprovalVerdict.permissions`) that the handler computes from the
+ * approver's own instance.
+ */
+type PermissionApprover = {
+  readonly kind: "permission";
+  readonly permission: string;
+};
+/** An approver who matches at least one item; an item that is a list matches when every entry does. */
+type AnyOfApprover = {
+  readonly kind: "any-of";
+  readonly of: readonly (Approver | readonly Approver[])[];
+};
 /**
  * Who may approve: a subject-only grantee, a `relation()` the approver holds
- * on the requested row (checked when the verdict is given), or `user(id)`.
- * A list matches an approver who satisfies every item.
+ * on the requested row (checked when the verdict is given), `user(id)`,
+ * `holder(permission)`, or `anyOf(...)`. A list (or `allOf(...)`) matches an
+ * approver who satisfies every item.
  */
-type Approver = Grantee | UserApprover;
-type ApproverInput = GranteeInput | UserApprover | readonly ApproverInput[];
+type Approver = Grantee | UserApprover | PermissionApprover | AnyOfApprover;
+type ApproverInput = GranteeInput | UserApprover | PermissionApprover | {
+  readonly kind: "any-of";
+  readonly of: readonly ApproverInput[];
+} | readonly ApproverInput[];
+/** Approves when the approver holds `permission` in the request's tenant (any role, custom roles included). */
+declare function holder(permission: Permission): PermissionApprover;
+/** Approves when the approver matches any one of `items`. */
+declare function anyOf(...items: readonly ApproverInput[]): {
+  readonly kind: "any-of";
+  readonly of: readonly ApproverInput[];
+};
+/** Approves when the approver matches every one of `items`; the same as a list. */
+declare function allOf(...items: readonly ApproverInput[]): readonly ApproverInput[];
 /** A named approver for `approval.by`, matched on the approver's principal id. */
 declare function user(id: string): UserApprover;
 //#endregion
@@ -1565,6 +1828,8 @@ type ApprovalStage = {
   readonly by: Approver | readonly Approver[];
   /** Absent means 1. */
   readonly quorum?: number;
+  /** After `after`, `to` may approve this stage as well as `by`; other stages are unaffected. */
+  readonly escalation?: ApprovalEscalation;
 };
 /**
  * `'any'`: `quorum` approvers from `by`. `'all'`: every stage completes, in
@@ -1596,6 +1861,11 @@ type ApprovalOption = "human" | {
   readonly stages?: readonly {
     readonly by: ApproverInput;
     readonly quorum?: number;
+    /** After `after`, `to` may approve this stage as well as `by`. */
+    readonly escalation?: {
+      readonly after: string;
+      readonly to: ApproverInput;
+    };
   }[];
   /** `false` lets the request's principal approve it; absent means `true`. */
   readonly distinct?: boolean;
@@ -1720,12 +1990,19 @@ type GrantOptions<T = Record<string, unknown>> = {
   readonly fields?: readonly (keyof T & string)[];
   /** A name a `breakGlass` override may lift; only meaningful on a deny. */
   readonly name?: string;
+  readonly group?: string;
   /** Purposes of use (`context.purpose`) that make the grant apply; non-portable. */
   readonly purpose?: readonly string[];
   /** The grant applies from this instant on (RFC 3339 string or Unix seconds); before it an allow denies with `inactive-grant` and a deny does not apply. */
   readonly validFrom?: string | number;
   /** The grant stops applying at this instant (exclusive; RFC 3339 string or Unix seconds). */
   readonly validUntil?: string | number;
+  /**
+   * An allow on an instance action counts only on rows whose scope instance
+   * (or the whole app, globally) is one where the subject also holds this
+   * permission through a role grant without a row condition.
+   */
+  readonly requires?: Permission | readonly Permission[];
 };
 /**
  * When a grant applies, in Unix seconds. `from` is inclusive, `until`
@@ -1736,10 +2013,15 @@ type GrantValidity = {
   readonly from?: number;
   readonly until?: number;
 };
-/** The actor a policy delegation is for: an actor kind, narrowed to one id when `id` is set. */
+/**
+ * The actor a policy delegation is for: an actor kind, narrowed to one id
+ * when `id` is set, or to one named client when `client` is set (the name
+ * the subject resolver gives a verified client id through `clients`).
+ */
 type DelegationTarget = {
   readonly kind: string;
   readonly id?: string;
+  readonly client?: string;
 };
 /**
  * A normalised policy delegation: holders of `from` let actors matching `to`
@@ -1757,7 +2039,7 @@ type PolicyDelegation = {
 type DelegationInput = {
   /** Who hands over: the same subject-only selectors as `approval.by` (a role, `authenticated()`, a plan, `assurance()`); not `relation()`. */
   readonly from: GranteeInput;
-  /** Which actor may act: `actor('eve')`, an actor kind, or `{ kind, id }` for one agent. */
+  /** Which actor may act: `actor('eve')`, an actor kind, `{ kind, id }` for one agent, or `{ kind, client }` for one named OAuth client. */
   readonly to: ActorGrantee | string | DelegationTarget;
   /** The leaves or subtrees the actor may use; a deny grant still applies. */
   readonly permissions: readonly (Permission | PermissionTree)[];
@@ -1811,6 +2093,7 @@ type Grant = {
   readonly scope: GrantScope;
   /** A name a `breakGlass` override may lift; only meaningful on a deny. */
   readonly name?: string;
+  readonly group?: string;
   /** Purposes of use that make the grant apply (`context.purpose`); non-portable. */
   readonly purpose?: readonly string[];
   /** Set on a break-glass allow: it overrides named denies and carries obligations. */
@@ -1821,6 +2104,10 @@ type Grant = {
   readonly hosted?: HostedGrantRef;
   /** When the grant applies; absent means always. */
   readonly validity?: GrantValidity;
+  /** Set on a custom-role grant narrowed by a resource level (`CustomRoleGrant.level`). */
+  readonly level?: string;
+  /** The permission key the subject must also hold, through a role, on the row's scope instance or globally. */
+  readonly requires?: readonly string[];
 };
 /** Which hosted policy document and grant a merged grant came from. */
 type HostedGrantRef = {
@@ -1878,8 +2165,21 @@ type Policy<TUser = unknown, TPrincipal extends Principal = Principal, V extends
   readonly fresh?: readonly string[];
   /** Policy delegations in declaration order; absent or empty when the policy declares none. */
   readonly delegations?: readonly PolicyDelegation[];
+  /** Grant levels by resource (`resource(…, { levels })`), normalised; absent when none are declared. */
+  readonly levels?: PolicyLevels;
+  /** Coarse OAuth scopes in declaration order; absent when the policy declares none. */
+  readonly oauthScopes?: readonly PolicyOAuthScope[];
   readonly index: PolicyIndex;
 };
+/**
+ * A coarse OAuth scope an authorization server issues (`mcp:read`) and the
+ * permission keys it covers, with their own scopes (`task:read`).
+ */
+type PolicyOAuthScope = {
+  readonly scope: string;
+  readonly permissions: readonly string[];
+  readonly scopes: readonly string[];
+};
 /** Lookups built once per policy, so a decision does not rescan every role and grant. */
 type PolicyIndex = {
   readonly declaredRoles: ReadonlySet<string>;
@@ -1901,6 +2201,8 @@ declare function role(name: string | Role, grants: RoleGrants, options?: RoleOpt
 /** Options built at runtime: the scope name is only checked by `definePolicy`. */
 declare function role(name: string | Role, grants: RoleGrants, options?: RoleOptions): RoleBinding;
 declare function normalizeAssurance(input: AssuranceRequirement | undefined): AssuranceRequirement | undefined;
+/** Resource name to level name to its normalised condition. */
+type PolicyLevels = Readonly<Record<string, Readonly<Record<string, Condition>>>>;
 type DefinePolicyOptions<TUser, TPrincipal extends Principal, S extends PolicyScopesInput = PolicyScopesInput> = {
   readonly roles?: readonly RoleBinding<ScopeNames<S>>[];
   readonly grants?: readonly (Omit<Grant, "role" | "scope"> | readonly Omit<Grant, "role" | "scope">[] | Grant)[];
@@ -1933,6 +2235,13 @@ type DefinePolicyOptions<TUser, TPrincipal extends Principal, S extends PolicySc
    * the call still applies as well; both must cover.
    */
   readonly delegations?: readonly DelegationInput[];
+  /**
+   * Coarse OAuth scopes the authorization server issues, each covering
+   * permissions: a token holding `mcp:read` is delegated every permission
+   * listed under it, as if it held each permission's own scope. Scope
+   * challenges name the first coarse scope that covers the permission.
+   */
+  readonly oauthScopes?: Readonly<Record<string, readonly (Permission | PermissionTree)[]>>;
 };
 declare function definePolicy<TUser, TPrincipal extends Principal, const Input extends PermissionTree | PolicyVocabulary, const S extends PolicyScopesInput = PolicyScopesInput>(permissions: Input, options: DefinePolicyOptions<TUser, TPrincipal, S>): Policy<TUser, TPrincipal, VocabularyFromInput<Input>>;
 type MembershipFixture = {
@@ -1956,4 +2265,4 @@ type SubjectOf<P> = {
   readonly expiresAt?: number;
 };
 //#endregion
-export { DecisionSink as $, relation as $n, RowPair as $t, RoleScope as A, memoryApprovalPolicies as An, isConditionRef as Ar, memoryEntitlementSource as At, normalizeAssurance as B, Obligation as Bn, CredentialPolicy as Bt, Policy as C, ArazzoPlan as Cn, RelatedCondition as Cr, TenantSettings as Ct, PrincipalOf as D, simulateArazzo as Dn, hasConditionOp as Dr, VerificationFailure as Dt, PolicyVocabulary as E, arazzoFindings as En, SqlFunctionCondition as Er, TokenVerifier as Et, ValidateMode as F, DeniedDecision as Fn, Credential as Ft, UserApprover as G, Grantee as Gn, credentialDelegation as Gt, separationConflicts as H, Trace as Hn, CredentialPrincipal as Ht, allow as I, ExplainedDecision as In, CredentialDecision as It, AuthEvent as J, actor as Jn, decideCredential as Jt, user as K, GranteeInput as Kn, credentialPolicyViolation as Kt, definePolicy as L, GrantedDecision as Ln, CredentialKind as Lt, SubjectOf as M, Decision as Mn, memorySettings as Mt, SupportAccessOptions as N, Denial as Nn, WireDecision as Nt, RoleBinding as O, ApprovalPolicy as On, isCondition as Or, VerifiedToken as Ot, SupportConsent as P, DenialReason as Pn, WireDenial as Pt, DecisionProvider as Q, plan as Qn, PermDockOptions as Qt, deny as R, LimitDetail as Rn, CredentialPermission as Rt, MembershipFixture as S, ArazzoFinding as Sn, OpaqueCondition as Sr, SubjectResolver as St, PolicyScopes as T, ArazzoStepResult as Tn, SqlFunctionArg as Tr, TokenSigner as Tt, Approver as U, TraceSkip as Un, CredentialRequest as Ut, role as V, Quota as Vn, CredentialPolicyViolation as Vt, ApproverInput as W, TraceSkipReason as Wn, DecideCredentialOptions as Wt, CredentialVerifier as X, assurance as Xn, DecideOptions as Xt, CredentialEvent as Y, anyone as Yn, parseCredential as Yt, DecisionEvent as Z, authenticated as Zn, PermDock as Zt, GrantLimit as _, RoleChangeOptions as _n, Condition as _r, SnapshotAssignable as _t, ApprovalRequirement as a, HostedGrantDropped as an, Assurance as ar, LimitStore as at, GrantValidity as b, breakGlass as bn, MemberOfCondition as br, SnapshotScope as bt, BreakGlassOptions as c, isPortableCondition as cn, CustomRole as cr, MembershipSource as ct, ClosureContext as d, parsePolicyDocument as dn, GnapAccess as dr, RelationHolder as dt, SimulateOptions as en, PolicyScopesInput as er, DirectoryEvent as et, ClosureGrantFn as f, Holder as fn, JsonWebKeyLike as fr, RelationSource as ft, GrantCondition as g, RoleChangeDecision as gn, VerifiedClaims as gr, Snapshot as gt, Grant as h, RoleChange as hn, Subject as hr, SinkEvent as ht, ApprovalOption as i, HostedGrantDropReason as in, Actor as ir, LimitRemaining as it, SeparationConflict as j, ApprovalRequiredDecision as jn, isSqlFunctionField as jr, memoryRoleSource as jt, RoleOptions as k, ApprovalPolicySource as kn, isConditionDate as kr, WhereCompiler as kt, BreakGlassRequirements as l, memoryPolicySource as ln, CustomRoleGrant as lr, RelationChain as lt, DelegationTarget as m, WhoCan as mn, Principal as mr, SettingsSource as mt, ApprovalEscalation as n, createPermDock as nn, ScopeDeclaration as nr, JwtClaims as nt, ApprovalStage as o, PolicyDocument as on, AuthorizationDetail as or, MemberEntry as ot, DelegationInput as p, HoldingVia as pn, Membership as pr, RoleSource as pt, AccessEvent as q, RelationGrantee as qn, credentialSubject as qt, ApprovalMode as r, HostedGrant as rn, ScopeNames as rr, LimitConsumeInput as rt, AssuranceRequirement as s, PolicySource as sn, Binding as sr, MembershipEvent as st, ActivationOption as t, WhereResult as tn, Scope as tr, EntitlementSource as tt, BreakGlassSpec as u, mergeHostedGrants as un, Delegation as ur, RelationGroup as ut, GrantOptions as v, RoleChangeTarget as vn, ConditionRef as vr, SnapshotGrant as vt, PolicyDelegation as w, ArazzoSimulateInput as wn, RelatedHop as wr, TokenFailureCause as wt, HostedGrantRef as x, supportAccess as xn, MemberOfParent as xr, SnapshotSource as xt, GrantScope as y, ActivateInput as yn, ConditionValue as yr, SnapshotNotEntitled as yt, normalizeApproval as z, MatchedGrant as zn, CredentialPermissionInput as zt };
+export { AccessEvent as $, ExplainedDecision as $n, CredentialPrincipal as $t, RoleOptions as A, RoleChangeOptions as An, GnapAccess as Ar, SnapshotSource as At, normalizeApproval as B, simulateArazzo as Bn, MemberOfParent as Br, memoryMembershipSource as Bt, Policy as C, mergeHostedGrants as Cn, Actor as Cr, SettingsSource as Ct, PolicyVocabulary as D, WhoCan as Dn, CustomRole as Dr, SnapshotGrant as Dt, PolicyScopes as E, HoldingVia as En, Binding as Er, SnapshotAssignable as Et, SupportConsent as F, ArazzoFinding as Fn, VerifiedClaims as Fr, TokenVerifier as Ft, Approver as G, ApprovalPolicyValidation as Gn, SqlFunctionArg as Gr, WireDenial as Gt, role as H, ApprovalPolicy as Hn, RelatedCondition as Hr, memorySettings as Ht, ValidateMode as I, ArazzoPlan as In, Condition as Ir, VerificationFailure as It, UserApprover as J, ApprovalRequiredDecision as Jn, isCondition as Jr, CredentialKind as Jt, ApproverInput as K, memoryApprovalPolicies as Kn, SqlFunctionCondition as Kr, Credential as Kt, allow as L, ArazzoSimulateInput as Ln, ConditionRef as Lr, VerifiedToken as Lt, SeparationConflict as M, ActivateInput as Mn, Membership as Mr, TenantSettings as Mt, SubjectOf as N, breakGlass as Nn, Principal as Nr, TokenFailureCause as Nt, PrincipalOf as O, RoleChange as On, CustomRoleGrant as Or, SnapshotNotEntitled as Ot, SupportAccessOptions as P, supportAccess as Pn, Subject as Pr, TokenSigner as Pt, user as Q, DeniedDecision as Qn, CredentialPolicyViolation as Qt, definePolicy as R, ArazzoStepResult as Rn, ConditionValue as Rr, WhereCompiler as Rt, MembershipFixture as S, memoryPolicySource as Sn, ScopeNames as Sr, RoleSourceFactory as St, PolicyOAuthScope as T, Holder as Tn, AuthorizationDetail as Tr, Snapshot as Tt, separationConflicts as U, ApprovalPolicyProblem as Un, RelatedHop as Ur, memorySnapshotSource as Ut, normalizeAssurance as V, APPROVAL_POLICY_UNAVAILABLE as Vn, OpaqueCondition as Vr, memoryRoleSource as Vt, AnyOfApprover as W, ApprovalPolicySource as Wn, RestrictedAncestors as Wr, WireDecision as Wt, anyOf as X, Denial as Xn, isConditionRef as Xr, CredentialPermissionInput as Xt, allOf as Y, Decision as Yn, isConditionDate as Yr, CredentialPermission as Yt, holder as Z, DenialReason as Zn, isSqlFunctionField as Zr, CredentialPolicy as Zt, GrantLimit as _, HostedGrantDropReason as _n, plan as _r, RelationChain as _t, ApprovalRequirement as a, decideCredential as an, Trace as ar, DecisionSink as at, GrantValidity as b, PolicySource as bn, Scope as br, RelationSource as bt, BreakGlassOptions as c, DeriveOptions as cn, Grantee as cr, JwtClaims as ct, ClosureContext as d, RowPair as dn, RelationGrantee as dr, LimitStore as dt, CredentialRequest as en, GrantedDecision as er, AuthEvent as et, ClosureGrantFn as f, SimulateOptions as fn, actor as fr, LocalCustomRoleTable as ft, GrantCondition as g, HostedGrant as gn, inherit as gr, MembershipSource as gt, Grant as h, createPermDock as hn, authenticated as hr, MembershipEvent as ht, ApprovalOption as i, credentialSubject as in, Quota as ir, DecisionProvider as it, RoleScope as j, RoleChangeTarget as jn, JsonWebKeyLike as jr, SubjectResolver as jt, RoleBinding as k, RoleChangeDecision as kn, Delegation as kr, SnapshotScope as kt, BreakGlassRequirements as l, PermDock as ln, GranteeInput as lr, LimitConsumeInput as lt, DelegationTarget as m, WhereResult as mn, assurance as mr, MemberEntry as mt, ApprovalEscalation as n, credentialDelegation as nn, MatchedGrant as nr, CredentialVerifier as nt, ApprovalStage as o, parseCredential as on, TraceSkip as or, DirectoryEvent as ot, DelegationInput as p, SnapshotOptions as pn, anyone as pr, LocalSnapshotManifest as pt, PermissionApprover as q, validateApprovalPolicy as qn, hasConditionOp as qr, CredentialDecision as qt, ApprovalMode as r, credentialPolicyViolation as rn, Obligation as rr, DecisionEvent as rt, AssuranceRequirement as s, DecideOptions as sn, TraceSkipReason as sr, EntitlementSource as st, ActivationOption as t, DecideCredentialOptions as tn, LimitDetail as tr, CredentialEvent as tt, BreakGlassSpec as u, PermDockOptions as un, InheritGrantee as ur, LimitRemaining as ut, GrantOptions as v, HostedGrantDropped as vn, relation as vr, RelationGroup as vt, PolicyDelegation as w, parsePolicyDocument as wn, Assurance as wr, SinkEvent as wt, HostedGrantRef as x, isPortableCondition as xn, ScopeDeclaration as xr, RoleSource as xt, GrantScope as y, PolicyDocument as yn, PolicyScopesInput as yr, RelationHolder as yt, deny as z, arazzoFindings as zn, MemberOfCondition as zr, memoryEntitlementSource as zt };