permdock 0.1.0 → 0.2.0

package/dist/{types-D6Z6-rKJ.d.ts → types-BPxgszlT.d.ts}

@@ -1,4 +1,5 @@
-import { a as SqlMembershipSource } from "./sources-DOpW5Ila.js";
+import { n as RoleThrough } from "./types-yF5LmQVD.js";
+import { o as SqlMembershipSource } from "./sources-BcJgw0lt.js";
 //#region src/cli/types.d.ts
 type CollectConfig = {
   readonly srcPath?: readonly string[];
@@ -13,7 +14,11 @@ type RlsTarget = "sql" | "drizzle" | "prisma";
 type RlsMembershipTable = {
   readonly table: string;
   readonly user: string;
-  readonly role: string;
+  /**
+   * The role key column, a reference to a roles table that holds the key, or
+   * several of them: the row holds every non-null key.
+   */
+  readonly role: string | RoleThrough | readonly (string | RoleThrough)[];
   /** Per scope name, the column holding that scope's id: the table's own scope and its ancestors. */
   readonly columns?: Readonly<Record<string, string>>;
   /** Column of the first scope's id; shorthand for `columns[<first scope>]`. */
@@ -22,8 +27,14 @@ type RlsMembershipTable = {
   readonly team?: string;
   readonly id?: string;
   readonly expiresAt?: string;
-  /** Column holding the membership kind (`Membership.via`); roles with `for` need it. */
-  readonly via?: string;
+  readonly disabledAt?: string;
+  /**
+   * The membership kind (`Membership.via`) roles with `for` match: a column
+   * holding it, or `{ value }` when every row has the same kind.
+   */
+  readonly via?: string | {
+    readonly value: string;
+  };
 };
 type RlsMemberships = {
   /** The membership table of each named scope. */
@@ -45,11 +56,28 @@ type RlsActiveRow = {
   readonly status?: string;
   readonly active?: readonly string[];
 };
+/** A scope's active-row table, with the permissions its suspended instances keep. */
+type RlsSuspendedScope = RlsActiveRow & {
+  /**
+   * Permissions (references or keys) members of a suspended instance, and of
+   * every instance nested in it, still hold: restoring it, cancelling a
+   * scheduled deletion, exporting before a purge.
+   */
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
+type RlsSuspendedMembership = {
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
 type RlsSuspension = {
   /** A suspended user holds no role and no membership. */
   readonly users?: RlsActiveRow;
-  /** Per scope name: a suspended instance voids its memberships and every membership nested under it. */
-  readonly scopes?: Readonly<Record<string, RlsActiveRow>>;
+  /** Per scope name: a suspended instance voids its memberships and every membership nested under it, except for `keep`. */
+  readonly scopes?: Readonly<Record<string, RlsSuspendedScope>>;
+  readonly memberships?: RlsSuspendedMembership;
 };
 type RlsFunctionMapping = {
   readonly twin: unknown;
@@ -74,6 +102,14 @@ type RlsConfig = {
   readonly force?: boolean;
   readonly fixtures?: string;
   readonly tenantClaim?: string;
+  /**
+   * Which tenants the helpers and `memberOf` checks admit. `'active'`
+   * (default): when the token carries a non-empty `tenantClaim`, only that
+   * tenant; without one, every tenant the subject is a member of. `'all'`:
+   * every such tenant whatever the claim says, for apps whose tenant comes
+   * from the URL or the query.
+   */
+  readonly tenants?: "active" | "all";
   /** Postgres type of tenant columns (`uuid` by default); the tenant claim and helper results are cast to it. */
   readonly tenantType?: string;
   /** Postgres type of team columns; defaults to `tenantType`. */
@@ -87,12 +123,12 @@ type RlsConfig = {
   readonly drizzle?: {
     /** Module exporting the tables, as imported from `out`. Default `./schema`. */
     readonly schema?: string;
-    /** Export name per table name; defaults to the camelCased table name. */
+    /** Export name per table name; defaults to the camelCased table name without its schema. */
     readonly exports?: Readonly<Record<string, string>>;
   };
   /** `--target prisma`: the model each table maps to. */
   readonly prisma?: {
-    /** Model name per table name; defaults to the PascalCased table name. */
+    /** Model name per table name; defaults to the PascalCased table name without its schema. */
     readonly models?: Readonly<Record<string, string>>;
   };
   /** Schema of `role_permissions` and the RLS helpers (`permdock_has`, `permitted_<scope>_ids`, `member_<scope>_ids`) (and the RBAC scaffold). Default `permdock`; keep it out of `[api] schemas`. */
@@ -107,6 +143,25 @@ type RlsConfig = {
    * always intersected with the `permdock_ceiling` view. Off by default.
    */
   readonly customRoles?: boolean;
+  /** How the generated custom-role write functions check the caller (`database` mode with `customRoles`). */
+  readonly customRoleWrites?: {
+    /**
+     * Who may change custom roles at all, checked before the hand-out check:
+     * permission keys of which the caller must hold one in the tenant (or
+     * through a global role; only through a global role for a platform custom
+     * role), or `'manageRoles'` for any permission with `meta.manageRoles`.
+     * Unset, any member may write a role within what they may hand out.
+     */
+    readonly requires?: "manageRoles" | readonly string[];
+    /**
+     * The application's own roles table, one row per custom role. A trigger
+     * on it moves a role's grants and includes when the row's name, tenant,
+     * scope or instance changes, and deletes them with the row. A signed-in
+     * caller goes through the same checks as the write functions; a trusted
+     * path (a migration, a job, a nested trigger) moves the rows directly.
+     */
+    readonly roles?: RlsCustomRoleTable;
+  };
   /**
    * Let link capabilities reach resource-scoped grants: `anon` policies that call
    * `permdock_capability_ids`, which reads the `capability` claim `exchangeCapability`
@@ -121,6 +176,69 @@ type RlsConfig = {
    * too. Off by default.
    */
   readonly anonymousSignIns?: "deny";
+  /**
+   * Grant `anon` usage on the helper schema and `execute` on the helpers, for
+   * hand-written policies that apply to `public` or `anon` and call them. They
+   * find no subject for `anon` and return nothing. Off by default: a policy
+   * that calls a helper says `to authenticated`.
+   */
+  readonly anonExecute?: boolean;
+  /**
+   * Check role assignments in the database: a trigger on each scope's
+   * `rls.memberships` table, the global-roles table `rls.roles` and each
+   * table in `tables` (such as invitations) refuses a client write that
+   * assigns, changes or removes a role the caller may not assign there, by
+   * the policy's `assigns` graph or, for a custom role, by what the caller may
+   * hand out. Writes that do not run as a client role (the table owner, a
+   * `security definer` function, a backend role) are trusted. Needs a role
+   * that declares `assigns`.
+   */
+  readonly assignments?: true | {
+    readonly tables?: readonly RlsAssignmentTable[];
+    /**
+     * `'refuse'`: a client write to a row whose user is the caller is
+     * refused on every guarded table with a user column, whatever the
+     * role. A map refuses it on the tables it names (`schema.table` as
+     * configured). Unset, a caller may change their own row within what
+     * they may assign.
+     */
+    readonly ownRole?: "refuse" | Readonly<Record<string, "refuse">>;
+  };
+  /**
+   * Add the approval store `supabaseApprovalStore` reads and writes: the
+   * `approval_requests` table and one function per `ApprovalStore` method, in
+   * the helper schema, executable by no client role. Off by default. An
+   * object adopts a table the app already has instead.
+   */
+  readonly approvals?: boolean | RlsApprovalsAdopt;
+  /**
+   * A pg_jsonschema check constraint on generated `jsonb` columns: the
+   * approval store's `body` must match `approval-request-v1.json`. `true`
+   * installs the extension into `extensions`; `'auto'` adds the constraint
+   * only where `pg_available_extensions` lists it. Off by default.
+   */
+  readonly jsonSchema?: "auto" | boolean;
+  /**
+   * `false` leaves out the holder-count and transfer-only triggers `min`,
+   * `max` and `transferOnly` put on the membership tables; a map with
+   * `<scope>: false` leaves them out for those scopes only. Those rules are
+   * then checked by `decideRoleChange` alone. On by default.
+   */
+  readonly ownershipTriggers?: false | Readonly<Record<string, false>>;
+  /**
+   * Make a session acting for a user read-only in the database: one
+   * restrictive policy per table and write command the generated policies
+   * allow, refusing the write when the token's `act` claim names one of these
+   * actor kinds, unless `act.read_only` is `false`. `true` is
+   * `['support', 'impersonation']`; with `support`, an `act` with a
+   * `session_id` and no `kind` counts too. Off by default.
+   */
+  readonly readOnlyActors?: boolean | readonly string[];
+  readonly apiKeys?: true | RlsApiKeys;
+  /** Supabase Realtime: policies on `realtime.messages` for private channels. Supabase dialect only. */
+  readonly realtime?: RlsRealtime;
+  /** Supabase Storage: policies on `storage.objects` for buckets keyed by a scope folder. Supabase dialect only. */
+  readonly storage?: RlsStorage;
   /**
    * `'views'`: one `security_invoker` view `<table>_visible` per table with field-limited
    * read grants, whose restricted columns are `case when <permitted> then col end`. Off by default.
@@ -149,6 +267,14 @@ type RlsConfig = {
   readonly actions?: RlsActions;
   /** Emit only the helpers, their seeds and the scaffold; the table policies stay hand-written. */
   readonly helpersOnly?: boolean;
+  /**
+   * Emit `permitted_<resource>_rows(p_permission)` and its `_for` form for
+   * these resources, or for every resource a grant reaches with `true`: the
+   * row ids the caller may act on, as the generated policies decide them.
+   */
+  readonly rowHelpers?: true | readonly string[];
+  readonly trustedReaders?: readonly string[];
+  readonly treeValues?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   /** `rls migrate`: how existing helper calls map onto the generated helpers. */
   readonly migrate?: RlsMigrateConfig;
   /**
@@ -158,6 +284,72 @@ type RlsConfig = {
    */
   readonly shims?: boolean | RlsShimsConfig;
 };
+/**
+ * `rls.approvals` on a table the app already has: the store functions keep
+ * each request's body in `body` and its token in `token` (both added when
+ * missing) and read every field from the body; `mirror` copies request
+ * fields into the app's own columns on each write, converted to their types.
+ */
+type RlsApprovalsAdopt = {
+  /** `table` or `schema.table`. */
+  readonly table: string;
+  /** A text column unique per request. Default `token`. */
+  readonly token?: string;
+  /** A jsonb column holding the `ApprovalRequest`. Default `body`. */
+  readonly body?: string;
+  readonly open?: "insert" | "attach";
+  readonly schema?: string;
+  /** Request fields copied into the app's columns, field to column. */
+  readonly mirror?: {
+    readonly status?: string;
+    readonly permission?: string;
+    readonly tenant?: string;
+    readonly principalId?: string;
+    readonly actorId?: string;
+    readonly session?: string;
+    readonly approvals?: string;
+    readonly createdAt?: string;
+    readonly expiresAt?: string;
+    readonly resolvedAt?: string;
+    readonly resolvedBy?: string;
+    readonly consumedAt?: string;
+  };
+};
+type RlsApiKeys = {
+  readonly claim?: string;
+  readonly scopes?: string;
+  readonly tenant?: string;
+  readonly roles?: string;
+  readonly serviceRoles?: readonly string[];
+};
+/** One more table whose rows assign a role, such as invitations (`rls.assignments.tables`). */
+type RlsAssignmentTable = {
+  readonly table: string;
+  /** The declared scope the row assigns the role at. */
+  readonly scope: string;
+  /** The column holding the scope instance id. */
+  readonly id: string;
+  /** The tenant column for a scope below the first; defaults to `id` at the first scope. */
+  readonly tenant?: string;
+  /** The role key column, a reference to a roles table that holds the key, or several of them. */
+  readonly role: string | RoleThrough | readonly (string | RoleThrough)[];
+  /** The column holding the user the row assigns to, which `ownRole` compares with the caller. */
+  readonly user?: string;
+};
+/** `rls.customRoleWrites.roles`: the application's table of custom roles. */
+type RlsCustomRoleTable = {
+  readonly table: string;
+  /** The column holding the role name. */
+  readonly key: string;
+  /** The tenant column; a row with no tenant is a platform custom role (`scope: 'global'`). Without it every row is a platform role. */
+  readonly tenant?: string;
+  /** A text column holding the scope name; without it a row with a tenant lives at the first scope. */
+  readonly scope?: string;
+  /** A column pinning the role to one instance of its scope. */
+  readonly id?: string;
+  /** A boolean column marking rows that are not custom roles (declared or system roles); those rows are skipped. */
+  readonly skip?: string;
+};
 /** `rls.shims`: where the legacy-named wrappers go. */
 type RlsShimsConfig = {
   /** Schema of the legacy helpers. Default `public`. */
@@ -190,24 +382,44 @@ type RlsMigrateConfig = {
   /** For `scoped` helpers, a scope literal's PermDock scope when the names differ. */
   readonly scopes?: Readonly<Record<string, string>>;
 };
-/**
- * The role column of a global-roles table that holds a foreign key: the role
- * key is `column` of `through`, joined on `on` (`{ role_id: 'id' }`).
- */
-type RoleThrough = {
-  /** The roles table; unqualified, it is in the global-roles table's schema. */
-  readonly through: string;
-  /** One entry: the global-roles column to the roles table column it references. */
-  readonly on: Readonly<Record<string, string>>;
-  /** The roles table column that holds the role key. */
-  readonly column: string;
-};
 /** Where global roles live: `table (user, role)`. Defaults `user_id` and `role`. */
 type GlobalRoles = {
   readonly table: string;
   readonly user?: string;
   readonly role?: string | RoleThrough;
 };
+/** A permission reference from the app's definitions; only its `key` is read. */
+type RlsPermissionRef = {
+  readonly key: string;
+};
+/**
+ * One private Realtime topic pattern, such as `org:{organization}:chat`:
+ * `:`-separated segments, one of them `{<scope>}`, which holds the id of a
+ * scope instance.
+ */
+type RlsRealtimeTopic = {
+  /** Receive broadcast and presence messages: `select` on `realtime.messages`. */
+  readonly read: RlsPermissionRef;
+  /** Send broadcast messages and track presence: `insert`. Absent: nobody may. */
+  readonly write?: RlsPermissionRef;
+};
+type RlsRealtime = {
+  readonly topics: Readonly<Record<string, RlsRealtimeTopic>>;
+};
+/** One Storage bucket whose object paths start with a scope instance id. */
+type RlsStorageBucket = {
+  readonly scope: string;
+  /** The 1-based `storage.foldername(name)` entry that holds the id. Default 1. */
+  readonly folder?: number;
+  /** Download and list: `select` on `storage.objects`. */
+  readonly read?: RlsPermissionRef;
+  /** Upload and overwrite: `insert` and `update`. */
+  readonly write?: RlsPermissionRef;
+  readonly delete?: RlsPermissionRef;
+};
+type RlsStorage = {
+  readonly buckets: Readonly<Record<string, RlsStorageBucket>>;
+};
 /** `permdock supabase hook generate` input. */
 type SupabaseHookConfig = {
   /** The same `fromTable` / `fromJunction` sources the app passes as `memberships`. */
@@ -239,12 +451,19 @@ type SupabaseHookConfig = {
   };
   /**
    * Claims other packages own, each `claim: '<schema>.<function>'`, for
-   * example `{ features: 'better_supabase.feature_claims' }`. The function
+   * example `{ features: 'public.feature_claims' }`. The function
    * takes the user id (`uuid`) and returns `jsonb`; `null` omits the claim.
    * Reserved names are refused, the claims sit outside `budget`, and a
    * suspended user gets none.
    */
   readonly claims?: Readonly<Record<string, string>>;
+  readonly before?: string | readonly string[];
+  /**
+   * Check the claims the hook wrote against `supabase-claims-v1.json` with
+   * pg_jsonschema, and drop them all on a mismatch so the user signs in with
+   * no PermDock access instead of an error. Needs the extension. Default `false`.
+   */
+  readonly validate?: boolean;
   /** Bytes of JSON the `memberships` claim may use. Default `supabaseMembershipsBudget` (1024). */
   readonly budget?: number;
   /** Keep `permdock_authz_version` and write the `authz_ver` claim. Default `true`. */
@@ -259,6 +478,13 @@ type SupabaseConfig = {
   readonly hook?: SupabaseHookConfig;
 };
 type DoctorConfig = {
+  /**
+   * Directories or globs the source checks read (PD001, PD002, PD007 to
+   * PD015, PD044 and the other checks over files), default `collect.srcPath`.
+   * The catalog `collect` writes still comes from `collect.srcPath`, and PD004
+   * compares the catalog on disk with that one.
+   */
+  readonly srcPath?: readonly string[];
   readonly sensitiveActions?: readonly string[];
   readonly memberships?: string;
   /** A JSON fixture `{ credentials?, settings? }` of API-key credentials and per-tenant settings (the `memorySettings` input) for PD029. */
@@ -280,8 +506,20 @@ type PermDockConfig = {
   };
   readonly rls?: RlsConfig;
   readonly supabase?: SupabaseConfig;
+  readonly powersync?: PowerSyncConfig;
   readonly doctor?: DoctorConfig;
 };
+/** `permdock powersync generate` and `verify` input. Tables and memberships come from `rls`. */
+type PowerSyncConfig = {
+  /** The Sync Streams file; default `sync-config.yaml`. */
+  readonly out?: string;
+  /** Resources that get a stream; default every resource with a grant of `action`. */
+  readonly resources?: readonly string[];
+  /** The action whose grants decide which rows sync; default `read`. */
+  readonly action?: string;
+  /** Where `generate` writes `localSnapshotManifest(policy)` as JSON for `localSnapshot` and `powersyncSource`; none by default. */
+  readonly manifest?: string;
+};
 type CliIo = {
   readonly stdout: (text: string) => void;
   readonly stderr: (text: string) => void;
@@ -309,4 +547,4 @@ type PermDockPluginOptions = {
   readonly check?: boolean;
 };
 //#endregion
-export { PermDockPluginOptions as a, RlsDialect as c, RlsMemberships as d, RlsSuspension as f, PermDockConfig as i, RlsFunctionMapping as l, RunResult as m, CliIo as n, RlsActiveRow as o, RlsTarget as p, CollectConfig as r, RlsConfig as s, CatalogConfig as t, RlsMembershipTable as u };
+export { RunResult as _, PermDockPluginOptions as a, RlsConfig as c, RlsMembershipTable as d, RlsMemberships as f, RlsTarget as g, RlsSuspension as h, PermDockConfig as i, RlsDialect as l, RlsSuspendedScope as m, CliIo as n, RlsActiveRow as o, RlsSuspendedMembership as p, CollectConfig as r, RlsApiKeys as s, CatalogConfig as t, RlsFunctionMapping as u };

package/dist/{types-BvBk1wgn.d.ts → types-BVyImy5I.d.ts}

@@ -1,5 +1,5 @@
-import { C as Policy, Cn as ArazzoPlan, E as PolicyVocabulary, In as ExplainedDecision, Mn as Decision, Qt as PermDockOptions, Xt as DecideOptions, Zt as PermDock, en as SimulateOptions, hr as Subject, mr as Principal, pr as Membership, tn as WhereResult, wn as ArazzoSimulateInput } from "./policy-CInmNGkM.js";
-import { d as Permission, p as PermissionTree } from "./permissions-B4apnahQ.js";
+import { $n as ExplainedDecision, C as Policy, D as PolicyVocabulary, In as ArazzoPlan, Ln as ArazzoSimulateInput, Mr as Membership, Nr as Principal, Pr as Subject, Yn as Decision, cn as DeriveOptions, fn as SimulateOptions, ln as PermDock, mn as WhereResult, sn as DecideOptions, un as PermDockOptions } from "./policy-CFZAr_Al.js";
+import { f as Permission, m as PermissionTree } from "./permissions-DttnqqxC.js";
 //#region src/pdp/types.d.ts
 type RemotePdpAuth = {
   readonly bearer: string | (() => string | Promise<string>);
@@ -84,7 +84,9 @@ type SpiceDbOptions = {
   readonly cache?: RemotePdpCache;
   readonly fetch?: typeof fetch;
 };
-type PdpPermDock<V extends PolicyVocabulary = PolicyVocabulary> = Omit<PermDock<V>, "can" | "decide" | "assert" | "explain" | "filter" | "where" | "simulate" | "tenant" | "team"> & {
+type PdpPermDock<V extends PolicyVocabulary = PolicyVocabulary> = Omit<PermDock<V>, "can" | "decide" | "assert" | "explain" | "filter" | "where" | "simulate" | "tenant" | "team" | "derive"> & {
+  /** `permdock.derive` with the same providers: the result asks the PDP too. */
+  readonly derive: (options: DeriveOptions) => PdpPermDock<V> | Promise<PdpPermDock<V>>;
   /**
    * For a delegated permission whose provider lists ids, an `in` over them
    * (AND the local condition when local grants exist); otherwise the local

package/dist/{types-CxquUByI.d.ts → types-Bvc4oWT6.d.ts}

@@ -1,4 +1,4 @@
-import { d as Permission } from "./permissions-B4apnahQ.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
 //#region src/agent/types.d.ts
 type ToolBinding = {
   readonly permission: Permission;

package/dist/types-C3s9xVJG.d.ts

@@ -0,0 +1,48 @@
+import { Ft as TokenVerifier, Tt as Snapshot, Yn as Decision } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+import { ReactNode } from "react";
+//#region src/react/types.d.ts
+type PermDockProviderProps = ({
+  readonly snapshot: Snapshot | string;
+  readonly snapshotPromise?: never;
+} | {
+  /**
+   * An unawaited snapshot from a Server Component. Hooks never suspend on it: until it
+   * resolves they deny with `status: 'pending'`, then re-render. A rejection fails closed
+   * (`server-only`). Set `suspend` to suspend readers through `use()` instead.
+   */
+  readonly snapshotPromise: PromiseLike<Snapshot | string>;
+  readonly snapshot?: never;
+}) & {
+  /**
+   * With `snapshotPromise`: `true` suspends every hook to the nearest Suspense boundary until it
+   * resolves, and a rejection reaches the nearest error boundary. Defaults to `false`.
+   */
+  readonly suspend?: boolean;
+  /**
+   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer. `false` never
+   * fetches: those checks answer `denied` with reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  readonly tenant?: string;
+  readonly fetch?: typeof fetch;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly maxAge?: number;
+  readonly verifier?: TokenVerifier;
+  readonly children: ReactNode;
+};
+type ProtectedProps = {
+  readonly permission: Permission;
+  readonly data?: unknown;
+  readonly tenant?: string;
+  readonly pending?: ReactNode;
+  readonly fallback?: ReactNode | ((decision: Decision) => ReactNode);
+  readonly children: ReactNode | ((decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>) => ReactNode);
+};
+//#endregion
+export { ProtectedProps as n, PermDockProviderProps as t };

package/dist/{types-BBK-exvJ.d.ts → types-Dnemwd77.d.ts}

@@ -1,4 +1,4 @@
-import { b as ResourceRelation } from "./permissions-B4apnahQ.js";
+import { S as ResourceRelation } from "./permissions-DttnqqxC.js";
 //#region src/catalog/types.d.ts
 type CatalogUsage = {
   readonly file: string;
@@ -15,6 +15,8 @@ type CatalogPermission = {
   readonly usages: readonly CatalogUsage[];
   /** Keys the permission was renamed from (`definePermissions` `renamed`), sorted; absent when none. */
   readonly renamedFrom?: readonly string[];
+  /** Level names a custom role may pick for the permission (`resource(…, { levels })`); absent when none. */
+  readonly levels?: readonly string[];
   /** Present only when the policy lists the permission in `hostable`. */
   readonly hostable?: true;
   /**
@@ -61,6 +63,7 @@ type CatalogResource = {
   readonly version?: string;
   /** The boolean column that keeps ancestor grants out of a row. */
   readonly restricted?: string;
+  readonly restrictedStops?: readonly string[];
 };
 type CatalogRole = {
   readonly key: string;
@@ -134,6 +137,8 @@ type CatalogGrant = {
   readonly validity?: CatalogValidity;
   readonly name?: string;
   readonly purpose?: readonly string[];
+  /** The permission key the subject must also hold through a role on the row's scope instance (`requires`). */
+  readonly requires?: string | readonly string[];
   readonly limit?: {
     readonly count: number;
     readonly per: string;
@@ -169,6 +174,7 @@ type CatalogDelegation = {
   readonly to: {
     readonly kind: string;
     readonly id?: string;
+    readonly client?: string;
   };
   readonly permissions: readonly string[];
   readonly validity?: CatalogValidity;

package/dist/types-kxznc7cn.d.ts

@@ -0,0 +1,52 @@
+import { Cr as Actor, D as PolicyVocabulary, Nr as Principal, Yn as Decision, kr as Delegation, ln as PermDock } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+//#region src/client/types.d.ts
+type ClientStatus = "ready" | "pending" | "stale" | "server-only";
+type PermissionState = {
+  readonly allowed: boolean;
+  readonly status: ClientStatus;
+  readonly decision: Decision;
+};
+type PermissionSet = {
+  readonly granted: readonly Permission[];
+  get(permission: Permission): PermissionState | undefined;
+};
+type ClientPermDock<V extends PolicyVocabulary = PolicyVocabulary> = PermDock<V> & {
+  status(permission?: Permission, data?: unknown): ClientStatus;
+  invalidate(ref: Permission | {
+    readonly [key: string]: unknown;
+  }): void;
+  refresh(options?: {
+    readonly tenant?: string;
+  }): Promise<void>;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+};
+type ApprovalState = "not-needed" | "required" | "pending" | "approved" | "rejected" | "expired";
+type ApprovalHandle = {
+  readonly state: ApprovalState;
+  readonly token: string | undefined;
+  readonly request: (note?: string) => Promise<void>;
+};
+type SubjectView = {
+  readonly principal: Principal | null;
+  readonly actor: Actor | undefined;
+  readonly delegation: Delegation | undefined;
+  readonly expiresAt: number | undefined;
+  readonly simulated: boolean;
+};
+type TenantView = {
+  readonly tenant: string | null;
+  readonly tenants: readonly string[];
+  readonly switchTo: (id: string) => Promise<void>;
+  readonly status: ClientStatus;
+};
+type FilterResult<T> = readonly T[] & {
+  readonly partial: boolean;
+};
+type UseRolesOptions = {
+  readonly tenant?: string;
+  readonly team?: string;
+};
+//#endregion
+export { FilterResult as a, SubjectView as c, ClientStatus as i, TenantView as l, ApprovalState as n, PermissionSet as o, ClientPermDock as r, PermissionState as s, ApprovalHandle as t, UseRolesOptions as u };

package/dist/{types-B8w5PFtS.d.ts → types-vKyAMtcX.d.ts}

@@ -1,4 +1,4 @@
-import { U as Approver, hr as Subject, o as ApprovalStage, pr as Membership, qn as RelationGrantee, r as ApprovalMode } from "./policy-CInmNGkM.js";
+import { G as Approver, Mr as Membership, Pr as Subject, dr as RelationGrantee, o as ApprovalStage, r as ApprovalMode } from "./policy-CFZAr_Al.js";
 //#region src/approvals/types.d.ts
 type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
 type ApprovalApprovers = {
@@ -24,6 +24,7 @@ type ApprovalSignature = {
   readonly by: string;
   readonly at: string;
   readonly stage?: number;
+  readonly vouched?: string;
 };
 type ApprovalSubjectSummary = {
   readonly principal: {
@@ -63,6 +64,7 @@ type ApprovalRequest = {
   readonly resolvedAt?: string;
   /** The approver whose verdict resolved the request (the last of `approvals` on a quorum), or `system:<by>` for a cancellation. */
   readonly resolvedBy?: string;
+  readonly vouched?: string;
   readonly note?: string;
   readonly consumedAt?: string;
 };
@@ -77,6 +79,14 @@ type ApprovalVerdict = {
    * none, so relation approvers match nobody.
    */
   readonly relations?: readonly string[];
+  /**
+   * The `holder(permission)` approvers (by permission key) that `by` holds
+   * in the request's tenant, as `approverPermissions` read them from the
+   * approver's own instance. Server-side input, never from the request body.
+   * Absent means none, so permission approvers match nobody.
+   */
+  readonly permissions?: readonly string[];
+  readonly vouched?: string;
 };
 type ApprovalListFilter = {
   readonly status?: ApprovalStatus;
@@ -104,6 +114,12 @@ type ApprovalCancelMeta = {
   readonly note?: string;
 };
 type ApprovalStore = {
+  /**
+   * How long a request opened against this store stays open, in
+   * milliseconds, when the caller sets no `ttl`; absent means
+   * `DEFAULT_APPROVAL_TTL_MS`. A grant's `approval.ttl` still caps it.
+   */
+  readonly ttl?: number;
   create(request: ApprovalRequest): Promise<void> | void;
   get(token: string): Promise<ApprovalRequest | null> | ApprovalRequest | null;
   resolve(token: string, verdict: ApprovalVerdict): Promise<ApprovalRequest> | ApprovalRequest;

package/dist/{types-B9dmiiab.d.ts → types-vNSDF7Dq.d.ts}

@@ -1,4 +1,4 @@
-import { E as PolicyVocabulary, Z as DecisionEvent, Zt as PermDock } from "./policy-CInmNGkM.js";
+import { D as PolicyVocabulary, ln as PermDock, rt as DecisionEvent } from "./policy-CFZAr_Al.js";
 //#region src/otel/types.d.ts
 declare const GENAI_SEMCONV_PIN = "1.37.0";
 declare const GEN_AI_TOOL_NAME = "gen_ai.tool.name";