permdock 0.0.0 → 0.2.0

package/dist/testing/index.d.ts

@@ -0,0 +1,745 @@
+import { At as SnapshotSource, C as Policy, Ct as SettingsSource, Dr as CustomRole, Ft as TokenVerifier, Mr as Membership, Nr as Principal, Pr as Subject, Pt as TokenSigner, Rt as WhereCompiler, Tt as Snapshot, Wn as ApprovalPolicySource, at as DecisionSink, bn as PolicySource, bt as RelationSource, dt as LimitStore, gt as MembershipSource, jt as SubjectResolver, ln as PermDock, mn as WhereResult, nt as CredentialVerifier, st as EntitlementSource, un as PermDockOptions, xt as RoleSource } from "../policy-CFZAr_Al.js";
+import { f as Permission, g as ResourceInit, u as InferPermissionTree } from "../permissions-DttnqqxC.js";
+import { r as Role } from "../vocabulary-DA8a8zif.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as ToolMap } from "../types-Bvc4oWT6.js";
+import { n as SupabaseHookManifest } from "../manifest-uDS9y5de.js";
+import { t as supabaseMembershipsBudget } from "../budget-JqcRqyhK.js";
+import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
+import { g as ReplayStore } from "../types-9AWO9EGt.js";
+import { v as DirectoryStore } from "../index-A0YNL8jZ.js";
+import { a as SaasProject } from "../permissions-CDgvKG5L.js";
+import { n as saasPolicy } from "../policy-D8UFyERw.js";
+import { expectTypeOf } from "vitest";
+//#region src/testing/describe-policy.d.ts
+type MatrixOutcome = "granted" | "denied" | "approval-required";
+type MatrixCell = MatrixOutcome | {
+  readonly outcome?: MatrixOutcome;
+  readonly denials?: readonly {
+    readonly role?: string | null;
+    readonly reason: string;
+  }[];
+  readonly alternatives?: readonly string[];
+  /** Obligation kinds a granted decision carries, in order; `[]` asserts none. */
+  readonly obligations?: readonly string[];
+  /** The `name` of the deny grant `explain` reports as the one that won. */
+  readonly deniedBy?: string;
+};
+type DescribePolicyConfig<TSubject> = {
+  readonly subjects: Record<string, TSubject>;
+  readonly fixtures?: Record<string, unknown>;
+  readonly matrix: Record<string, Record<string, MatrixCell | Record<string, MatrixCell>>>;
+  readonly exhaustive?: boolean;
+  readonly options?: PermDockOptions;
+  /**
+   * Also assert every granted or denied cell against `fromSnapshot(permdock.snapshot())`,
+   * the client a Server Component hands down. Closures cannot cross a snapshot and deny on the client.
+   */
+  readonly snapshot?: boolean;
+};
+export declare function describePolicy<TSubject>(policy: Policy, config: DescribePolicyConfig<TSubject>): void;
+//#endregion
+//#region src/testing/rls-parity.d.ts
+type RlsDbOutcome = "allowed" | "filtered" | "rejected";
+type RlsParitySubject = {
+  readonly id: string;
+  readonly roles?: readonly string[];
+  readonly tenant?: string;
+  readonly memberships?: readonly Membership[];
+  /**
+   * Extra token claims, read in memory as `principal.claims.*`. They join the
+   * JWT claims (`supabase`, `neon`); under `guc` each top-level claim is its
+   * own `<prefix>.<name>` setting, strings as is and anything else as JSON.
+   */
+  readonly claims?: Readonly<Record<string, unknown>>;
+};
+type RlsParityFixture = {
+  readonly name: string;
+  readonly subject: RlsParitySubject;
+  readonly permission: Permission;
+  readonly row: Readonly<Record<string, unknown>>;
+  readonly table: string;
+};
+type RlsQueryResult = {
+  readonly rows: readonly Record<string, unknown>[];
+  readonly rowCount?: number;
+  readonly code?: string;
+};
+type RlsQueryFn = (sql: string, values?: readonly unknown[]) => Promise<RlsQueryResult>;
+type RlsParityOptions = {
+  readonly query: RlsQueryFn;
+  readonly fixtures: readonly RlsParityFixture[];
+  /**
+   * `supabase` and `neon` set `request.jwt.claims`; a test database stubs
+   * `auth.jwt()` / `auth.uid()` or `auth.session()` / `auth.user_id()` over it.
+   */
+  readonly dialect?: "supabase" | "neon" | "guc";
+  readonly gucPrefix?: string;
+  readonly tenantClaim?: string;
+  /** Claim (or `guc` setting) the RLS helpers read global roles from. Default `user_role`. */
+  readonly roleClaim?: string;
+  readonly role?: "authenticated" | "anon";
+  /**
+   * Tenant-defined roles the subjects' memberships may hold. `decide` resolves them through a
+   * `RoleSource`; each membership's claim carries them as the compact `grants` map, which the
+   * helpers read in `jwt` mode. Seeding the `database`-mode tables is the caller's job.
+   */
+  readonly customRoles?: readonly CustomRole[];
+  /** Also decide each case from the subject's serialized snapshot (`fromSnapshot`); it must agree. */
+  readonly snapshot?: boolean;
+  /**
+   * With `rls generate --fields views`: for each instance read, the row of
+   * `<table>_visible` must hold exactly the columns `pick` keeps (plus the key,
+   * which always passes through). A table with no view is read directly.
+   */
+  readonly fieldViews?: boolean;
+};
+/** Columns with a value in the view's row and in `pick`'s result, sorted. */
+type RlsFieldsOutcome = {
+  readonly app: readonly string[];
+  readonly database: readonly string[] | string;
+};
+type RlsParityCase = {
+  readonly name: string;
+  readonly granted: boolean;
+  readonly database: RlsDbOutcome;
+  /** The snapshot's decision, with `snapshot: true`. */
+  readonly snapshot?: boolean;
+  /** The field view check, with `fieldViews: true`; `database` is an error code when the read failed. */
+  readonly fields?: RlsFieldsOutcome;
+  readonly ok: boolean;
+};
+type RlsParityReport = {
+  readonly ok: boolean;
+  readonly results: readonly RlsParityCase[];
+};
+export declare function rlsParity<TUser>(policy: Policy<TUser>, options: RlsParityOptions): Promise<RlsParityReport>;
+//#endregion
+//#region src/testing/orm-parity.d.ts
+type OrmParityScenario<TUser = unknown> = {
+  readonly name: string;
+  /** What the policy's `subject` mapper receives, as in `createPermDock(policy, user)`. */
+  readonly user: TUser;
+  /** The active tenant and role sources, as in `createPermDock(policy, user, options)`. */
+  readonly options?: PermDockOptions;
+  /** An instance permission; its `where()` filters the table. */
+  readonly permission: Permission<string, unknown, "instance">;
+  /** Every row of the table, exactly as the database holds them. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+};
+type OrmParityRunInput<TUser = unknown> = {
+  readonly scenario: OrmParityScenario<TUser>;
+  readonly where: WhereResult;
+};
+type OrmParityOptions<TUser = unknown> = {
+  /** Runs `toWhere(where)` against the database and returns the matching row ids. */
+  readonly run: (input: OrmParityRunInput<TUser>) => Promise<readonly unknown[]>;
+  /** The row id field; default `id`. */
+  readonly id?: string;
+};
+type OrmParityCase = {
+  readonly name: string;
+  readonly expected: readonly string[];
+  readonly actual: readonly string[];
+  /**
+   * `where()` left out a non-portable grant. `toWhere` refusing it is
+   * fail-closed and passes; rows it does return must be a subset.
+   */
+  readonly partial: boolean;
+  readonly error?: string;
+  readonly ok: boolean;
+};
+type OrmParityReport = {
+  readonly ok: boolean;
+  readonly results: readonly OrmParityCase[];
+};
+/**
+ * ORM parity: for each scenario, the rows `permdock.filter()` keeps in memory
+ * must be exactly the rows the database returns for `toWhere(permdock.where())`.
+ * With a `relations` option, the graph is loaded for the rows first, so the
+ * in-memory side walks the same graph the database query does.
+ * A partial `where()` (a closure grant it cannot compile) may be refused or
+ * return fewer rows, never more.
+ */
+export declare function ormParity<TUser>(policy: Policy<TUser>, scenarios: readonly OrmParityScenario<TUser>[], options: OrmParityOptions<TUser>): Promise<OrmParityReport>;
+//#endregion
+//#region src/testing/client-parity.d.ts
+type ClientParityCase = {
+  readonly name: string;
+  /** The value the policy's `subject` function receives. */
+  readonly user: unknown;
+  readonly tenant?: string | undefined;
+  readonly permission: Permission;
+  readonly row?: unknown;
+  /**
+   * `true` when the client may deny what the server grants, because the
+   * outcome depends on a closure, a quota or an approval the snapshot omits.
+   */
+  readonly stricter?: boolean;
+};
+type ClientParityOptions = {
+  readonly customRoles?: RoleSource;
+};
+/**
+ * Asserts that `fromSnapshot(permdock.snapshot())` never grants what the
+ * server denies, and matches it exactly unless a case is marked `stricter`.
+ */
+export declare function testClientParity(policy: Policy, cases: readonly ClientParityCase[], options?: ClientParityOptions): void;
+//#endregion
+//#region src/testing/client-store.d.ts
+type ClientStoreStatus = "ready" | "pending" | "stale" | "server-only";
+/** The client surface every UI adapter hands to components. */
+type ClientStorePermDock = PermDock & {
+  status(permission?: Permission, data?: unknown): ClientStoreStatus;
+  refresh(query?: {
+    readonly tenant?: string;
+  }): Promise<void>;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+};
+type ClientStoreHandle = {
+  get(): ClientStorePermDock;
+  /** Hydrate from a server-pushed snapshot (a Server Action result, a socket message). */
+  replace(value: unknown): void;
+};
+type ClientStoreFactoryOptions = {
+  readonly snapshot: Snapshot | string;
+  readonly snapshotUrl?: string;
+  readonly endpoint?: string;
+  readonly tenant?: string;
+  readonly fetch: typeof fetch;
+  readonly verifier?: TokenVerifier;
+};
+type ClientStoreFactory = (options: ClientStoreFactoryOptions) => ClientStoreHandle;
+/**
+ * Race and cache scenarios for a client snapshot store: tenant switches,
+ * `replace` and `refresh`, logout and a second user during a refresh, stale
+ * and signed snapshots, and endpoint answers cached per tenant. Runs against
+ * the saas domain; `createStore` wraps the store an adapter ships.
+ */
+export declare function testClientStore(name: string, createStore: ClientStoreFactory): void;
+//#endregion
+//#region src/testing/snapshot-fixture.d.ts
+export declare function snapshotFixture(policy: Policy, subject: unknown, options?: {
+  readonly include?: readonly (Permission | {
+    readonly [key: string]: unknown;
+  })[];
+  readonly tenants?: "all";
+  readonly tenant?: string;
+  readonly simulated?: boolean;
+}): Promise<Snapshot>;
+//#endregion
+//#region src/testing/http-adapter.d.ts
+/**
+ * What a mount wires into its framework. Every value is server-side: the
+ * subject comes from a verified bearer token, memberships and plans from the
+ * seed, the tenant from the `:org` path segment.
+ */
+type HttpScenarioDomain = {
+  readonly policy: typeof saasPolicy;
+  /**
+   * The verified principal for an `Authorization` header, with the plans of
+   * the org in the first segment of `path`. The path, not a route param, so
+   * the answer is the same in a global middleware that runs before routing.
+   */
+  readonly subject: (authorization: string | null | undefined, path: string) => Promise<Principal | null>;
+  /** `subject` as a full `Subject` whose `expiresAt` is the token's `exp`. */
+  readonly session: (authorization: string | null | undefined, path: string) => Promise<Subject | null>;
+  /** The feed stream mounts pass as `revocations`. */
+  readonly revocations: RevocationFeed;
+  /**
+   * The seed projects of an org, one every 20 ms, round and round until
+   * `signal` aborts: the source of the events stream.
+   */
+  readonly ticks: (org: string | undefined, signal: AbortSignal) => AsyncIterable<SaasProject>;
+  /** The `:org` segment of a path; mounts may read their route param instead. */
+  readonly org: (path: string) => string | undefined;
+  readonly customRoles: RoleSource;
+  readonly store: ApprovalStore;
+  readonly limits: LimitStore;
+  /** A project row by id, whatever its org: tenant checks belong to the policy. */
+  readonly project: (id: string | undefined) => SaasProject | null;
+};
+type HttpOp = {
+  readonly op: "project.get";
+  readonly org: string;
+  readonly id: string;
+} | {
+  readonly op: "project.update";
+  readonly org: string;
+  readonly id: string;
+} | {
+  readonly op: "project.create";
+  readonly org: string;
+  readonly body: unknown;
+} | {
+  readonly op: "project.delete";
+  readonly org: string;
+  readonly id: string;
+} | {
+  readonly op: "project.upload";
+  readonly org: string;
+  readonly id: string;
+  readonly file: {
+    readonly name: string;
+    readonly content: string;
+  };
+} | {
+  readonly op: "analytics.read";
+  readonly org: string;
+} | {
+  readonly op: "apiKey.create";
+  readonly org: string;
+} | {
+  readonly op: "apiKey.revokeAll";
+  readonly org: string;
+} | {
+  readonly op: "admin.members";
+  readonly org: string;
+} | {
+  readonly op: "evaluations";
+  readonly org: string;
+  readonly body: unknown;
+};
+type HttpCall = HttpOp & {
+  /** `Bearer <token>` or `null` for an anonymous call. */
+  readonly authorization: string | null;
+  /** Sent as the `PermDock-Approval` header. */
+  readonly approval?: string;
+};
+type HttpResult = {
+  readonly status: number;
+  readonly body: unknown;
+};
+type HttpMounted = {
+  /**
+   * A fetch-shaped entry for REST adapters. It must serve:
+   *
+   * - `GET /:org/projects/:id`: `protect(project.read, row)`, 200 with the row
+   * - `PATCH /:org/projects/:id`: `protect(project.update, row)`, 200
+   * - `POST /:org/projects`: `protect(project.create, body, { trusted: false })`, 201 with the body
+   * - `DELETE /:org/projects/:id`: `protect(project.read, row)`, then the handler
+   *   calls `permdock.assert(project.delete, row)`; 204
+   * - `POST /:org/projects/:id/files`: `protect(project.update, row)`, then the
+   *   framework's own multipart parser reads field `file`; 201 `{ name, size }`
+   * - `GET /:org/analytics`: `protect(analytics.read)`, 200
+   * - `POST /:org/api-keys`: `protect(apiKey.create)`, 201
+   * - `POST /:org/api-keys/revoke-all`: `protect(apiKey.revokeAll)`, 204
+   * - `GET /:org/admin/members`: in a sub-app, router or group; `protect(member.list)`, 200
+   * - `POST /:org/permdock/access/v1/evaluations`: the adapter's decision endpoint
+   *
+   * A global `permdock()` middleware runs before every route.
+   *
+   * With `streams: true` it also serves `GET /:org/projects/:id/events`:
+   * `protect(project.read, row)` with the subject from `domain.session`,
+   * then a connection opened for `project.read` on the row with
+   * `revocations: domain.revocations`, streaming `domain.ticks(org)` as
+   * `text/event-stream` `data:` frames of JSON rows, dropping rows the
+   * subscriber cannot `project.update`, and ending with an
+   * `event: permdock` frame carrying the Problem Details when the connection aborts.
+   */
+  readonly fetch?: (request: Request) => Promise<Response>;
+  /** RPC adapters map a call to a procedure and its error to an HTTP status. */
+  readonly call?: (call: HttpCall) => Promise<HttpResult>;
+  readonly close?: () => Promise<void> | void;
+};
+type HttpScenarioName = "tenant" | "roles" | "custom-roles" | "plans" | "expired" | "limits" | "validation" | "assert" | "approval" | "stale-approval" | "evaluations" | "upload" | "sub-app" | "parallel" | "stream-revoked" | "stream-demoted" | "stream-filter" | "stream-expired";
+type HttpAdapterOptions = {
+  readonly name: string;
+  readonly mount: (domain: HttpScenarioDomain) => HttpMounted | Promise<HttpMounted>;
+  /** Scenarios the transport cannot express (multipart over RPC), each with a reason. */
+  readonly skip?: Readonly<Partial<Record<HttpScenarioName, string>>>;
+  /** The mount serves the events stream; the `stream-*` scenarios run only then. */
+  readonly streams?: boolean;
+};
+/**
+ * Real-life HTTP scenarios over the shared SaaS domain. `mount` builds the
+ * application once with the adapter under test; every expectation below is
+ * written by hand, never computed with PermDock.
+ */
+export declare function testHttpAdapter(options: HttpAdapterOptions): void;
+//#endregion
+//#region src/testing/agent-adapter.d.ts
+/** The user whose subject resolver throws. */
+export declare const AGENT_THROWING_USER = "throws";
+/** The project id whose loader throws. */
+export declare const AGENT_THROWING_ROW = "throws";
+type AgentToolName = "project_read" | "api_keys_revoke_all";
+/**
+ * What a mount wires into its adapter. The subject and the tenant come from
+ * the server-side context the mount builds for each call, never from the
+ * tool arguments.
+ */
+type AgentScenarioDomain = {
+  readonly policy: typeof saasPolicy;
+  /**
+   * The principal for `user` with the plans of `org`, or `null` for an
+   * anonymous call. Throws for `AGENT_THROWING_USER`.
+   */
+  readonly subject: (user: string | null, org: string) => Principal | null;
+  /**
+   * `project_read` loads the row named by `args.id`: `null` for an unknown
+   * id, a throw for `AGENT_THROWING_ROW`. `api_keys_revoke_all` needs
+   * approval.
+   */
+  readonly tools: ToolMap & { readonly [K in AgentToolName]: ToolMap[K]; };
+  readonly customRoles: RoleSource;
+  readonly store: ApprovalStore;
+};
+type AgentCall = {
+  /** `null` for a call with no authenticated user. */
+  readonly user: string | null;
+  readonly org: string;
+  readonly tool: AgentToolName;
+  readonly args: {
+    readonly id?: string;
+  };
+};
+type AgentOutcome = "granted" | "denied" | "approval-required";
+type AgentMounted = {
+  /** Runs one tool call through the adapter's own entry and reports its outcome. */
+  readonly call: (call: AgentCall) => Promise<AgentOutcome>;
+  readonly close?: () => Promise<void> | void;
+};
+type AgentScenarioName = "granted" | "denied" | "cross-tenant" | "anonymous" | "subject-throws" | "loader-throws" | "missing-row" | "approval-required";
+type AgentAdapterOptions = {
+  readonly name: string;
+  readonly mount: (domain: AgentScenarioDomain) => AgentMounted | Promise<AgentMounted>;
+  /** Scenarios the adapter cannot express, each with a reason. */
+  readonly skip?: Readonly<Partial<Record<AgentScenarioName, string>>>;
+};
+/**
+ * Runs the same tool calls through an agent adapter: a grant, the denials an
+ * attacker or an outage produces, and an approval. Every failure denies.
+ */
+export declare function testAgentAdapter(options: AgentAdapterOptions): void;
+//#endregion
+//#region src/testing/authzen.d.ts
+type Entity = {
+  readonly type: string;
+  readonly id?: string;
+  readonly properties?: Readonly<Record<string, unknown>>;
+};
+type AuthZenEvaluationVector = {
+  readonly request: {
+    readonly subject: Entity;
+    readonly action: {
+      readonly name: string;
+    };
+    readonly resource: Entity;
+    readonly context?: Readonly<Record<string, unknown>>;
+  };
+  readonly expected: boolean;
+};
+type AuthZenEvaluationsVector = {
+  readonly request: {
+    readonly subject?: Entity;
+    readonly action?: {
+      readonly name: string;
+    };
+    readonly resource?: Entity;
+    readonly evaluations: readonly {
+      readonly subject?: Entity;
+      readonly action?: {
+        readonly name: string;
+      };
+      readonly resource?: Entity;
+    }[];
+  };
+  readonly expected: readonly {
+    readonly decision: boolean;
+  }[];
+};
+type AuthZenSearchVector = {
+  readonly request: Readonly<Record<string, unknown>>;
+  readonly expected: {
+    readonly results: readonly Readonly<Record<string, unknown>>[];
+  };
+};
+/**
+ * Vectors in the layout of the OpenID AuthZEN interop harness
+ * (`decisions-*.json` for Basic and Batch, `search/{subject,resource,action}`
+ * `results.json` for Search), so the official files load unchanged.
+ */
+type AuthZenVectors = {
+  readonly evaluation?: readonly AuthZenEvaluationVector[];
+  readonly evaluations?: readonly AuthZenEvaluationsVector[];
+  readonly search?: {
+    readonly subject?: readonly AuthZenSearchVector[];
+    readonly resource?: readonly AuthZenSearchVector[];
+    readonly action?: readonly AuthZenSearchVector[];
+  };
+};
+type TestAuthZenOptions = {
+  readonly vectors: AuthZenVectors;
+  /** Origin the requests are addressed to; the discovery document must name it. */
+  readonly origin?: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Check `/.well-known/authzen-configuration`; on by default. */
+  readonly discovery?: boolean;
+};
+/** Runs AuthZEN 1.0 interop vectors against an Authorization API endpoint. */
+export declare function testAuthZen(handle: (request: Request) => Promise<Response>, options: TestAuthZenOptions): void;
+type TodoUser = {
+  readonly id: string;
+  readonly identity: string;
+  readonly roles: readonly ("admin" | "editor" | "viewer" | "evil_genius")[];
+};
+/** The AuthZEN interop Todo directory: each user is addressable by email or by identity. */
+export declare const authzenTodoUsers: readonly TodoUser[];
+type AuthzenTodoDefinition = {
+  readonly user: ResourceInit<unknown, readonly ["can_read_user"], readonly []>;
+  readonly todo: ResourceInit<unknown, readonly ["can_read_todos", "can_create_todo", "can_update_todo", "can_delete_todo"], readonly []>;
+};
+export declare const authzenTodoPermissions: InferPermissionTree<AuthzenTodoDefinition>;
+/** The interop Todo rules: viewers read, editors write their own, admins delete and evil geniuses update anything. */
+export declare const authzenTodoPolicy: Policy;
+/** Rows for `resources.todo.list` and records for `subjects.list` in the Todo domain. */
+export declare const authzenTodoData: {
+  readonly todos: readonly {
+    readonly id: string;
+    readonly ownerID: string;
+  }[];
+  readonly users: readonly {
+    readonly id: string;
+  }[];
+};
+/**
+ * PermDock's vectors over the interop Todo domain, in the interop layout:
+ * every user against every action on their own and on Rick's todo, one batch
+ * per user, and the three searches.
+ */
+export declare function authzenTodoVectors(): AuthZenVectors;
+//#endregion
+//#region src/testing/conformance.d.ts
+export declare function testSubjectResolver<TInput>(resolver: SubjectResolver<TInput>, options: {
+  readonly invalid: TInput;
+}): void;
+export declare function testMembershipSource(source: MembershipSource, options: {
+  readonly principals: readonly {
+    readonly id: string;
+    readonly kind?: string;
+  }[];
+  readonly expect?: Record<string, readonly Membership[]>;
+  /** With the policy, every membership must name one of its scopes and carry its parent ids. */
+  readonly policy?: Policy;
+  /** Passed to every `membershipsFor`; a source keyed by tenant answers nothing without one. */
+  readonly tenant?: string;
+}): void;
+/**
+ * A `RelationSource` answers facts only: well-formed chains nearest first and
+ * no longer than `depth`, holders with principal ids or group references and
+ * numeric instants, a `truncated` chain only when more ancestors exist, and
+ * empty answers (never a throw) for an object it does not know. `expect` pins
+ * the chains, holders and links for `objects`, keyed `resource:id`,
+ * `resource:id#relation` and `resource:id>link`; a group holder is written
+ * `resource:id#relation`.
+ */
+export declare function testRelationSource(source: RelationSource, options: {
+  readonly objects: readonly {
+    readonly resource: string;
+    readonly id: string;
+    readonly relation?: string;
+  }[];
+  readonly expect?: {
+    readonly ancestors?: Readonly<Record<string, readonly string[]>>;
+    readonly holders?: Readonly<Record<string, readonly string[]>>;
+    /** Keyed `resource:id>link`, the id the link leads to. */
+    readonly links?: Readonly<Record<string, string>>;
+  };
+}): void;
+export declare function testEntitlementSource(source: EntitlementSource, options: {
+  readonly principal: {
+    readonly id: string;
+  };
+  readonly tenant: string;
+  readonly expect?: readonly string[];
+}): void;
+export declare function testRoleSource(source: RoleSource, options: {
+  readonly tenant: string;
+  readonly declared: readonly (string | Role)[];
+  /** When set, every custom role's `grants` must resolve inside the ceiling. */
+  readonly policy?: Policy;
+  /**
+   * Names of every custom role the tenant has. When set, `rolesFor` must
+   * return each of them with nothing held, as role management needs.
+   */
+  readonly every?: readonly string[];
+}): void;
+export declare function testLimitStore(store: LimitStore): void;
+export declare function testDecisionSink(sink: DecisionSink): void;
+export declare function testSnapshotSource(source: SnapshotSource): void;
+export declare function testPolicySource(source: PolicySource, options?: {
+  readonly policy?: Policy;
+}): void;
+export declare function testReplayStore(store: ReplayStore): void;
+export declare function testRevocationFeed(feed: RevocationFeed): void;
+export declare function testDirectoryStore(store: DirectoryStore, options: {
+  readonly tenants: readonly [string, string];
+}): void;
+type ApprovalStoreOptions = {
+  /**
+   * Opens a second store over the same backing storage, as a restarted process
+   * would. Omit it for stores that do not persist (the resume-after-restart
+   * case is then skipped).
+   */
+  readonly reopen?: () => ApprovalStore | Promise<ApprovalStore>;
+};
+export declare function testApprovalStore(store: ApprovalStore, options?: ApprovalStoreOptions): void;
+export declare function testTokenVerifier(verifier: TokenVerifier, options?: {
+  readonly audience?: string;
+  readonly issuer?: string;
+}): void;
+/** Settings for `tenant`, or `undefined`; a thrown source fails the runner. */
+export declare function testSettingsSource(source: SettingsSource, options: {
+  readonly tenant: string;
+  readonly unknown?: string;
+}): void;
+/**
+ * Checks an `ApprovalPolicySource`: entries are plain JSON, belong to the
+ * queried tenant or to none, and every entry loads against `policy` (an
+ * entry that does not would deny every call).
+ */
+export declare function testApprovalPolicySource(source: ApprovalPolicySource, options: {
+  readonly policy: Policy;
+  readonly tenant: string;
+  readonly unknown?: string;
+}): void;
+/**
+ * `key` is a live key the verifier knows, or a function issuing one (called
+ * once). `revoke`, when given, revokes it; the runner then expects the key
+ * to stop verifying.
+ */
+export declare function testCredentialVerifier(verifier: CredentialVerifier, options: {
+  readonly key: string | (() => string | Promise<string>);
+  readonly revoke?: () => void | Promise<void>;
+}): void;
+export declare function testTokenSigner(signer: TokenSigner, options: {
+  readonly verifier: TokenVerifier;
+}): void;
+type WhereRow = Readonly<Record<string, unknown>>;
+/**
+ * `matches` answers whether the compiled output selects `row`, for example
+ * by running it against a table holding only that row. With it, every case
+ * must select the rows the in-memory evaluator keeps, including rows whose
+ * fields are NULL.
+ */
+export declare function testWhereCompiler<TTarget>(compiler: WhereCompiler<TTarget>, options: {
+  readonly target: TTarget;
+  readonly isFailClosed?: (compiled: unknown) => boolean;
+  readonly matches?: (compiled: unknown, row: WhereRow) => boolean | Promise<boolean>;
+}): void;
+//#endregion
+//#region src/testing/jwt-fixtures.d.ts
+export declare const jwtFixtureJwks: {
+  readonly keys: readonly [{
+    readonly crv: "Ed25519";
+    readonly x: "79ab4WR6Eb9LkefWpmh5ZlvjXg7wqVGNMwIEHQqduIQ";
+    readonly kty: "OKP";
+    readonly kid: "2026-09";
+    readonly alg: "Ed25519";
+    readonly use: "sig";
+  }];
+};
+export declare const jwtFixtureIssuer: "https://login.example.com";
+export declare const jwtFixtureAudience: "https://api.example.com";
+export declare const jwtFixtureTokens: {
+  readonly valid: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiJ1XzEiLCJjbGllbnRfaWQiOiJhcHAiLCJyb2xlcyI6WyJtZW1iZXIiXSwianRpIjoianRpLXZhbGlkIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5leGFtcGxlLmNvbSIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tIiwiaWF0IjoxNzAwMDAwMDAwLCJleHAiOjIwMDAwMDAwMDB9.ENFMmLSyVde-2s4Gdz4iP7srZvU0Xuy_ZLz-OJGHD_-W1lEayEBeSPTnab0L_TBdj8p5BmkFrT-7VE7o20GbAw";
+  readonly expired: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiJ1XzEiLCJpc3MiOiJodHRwczovL2xvZ2luLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJpYXQiOjEwMDAwMDAwMDAsImV4cCI6MTEwMDAwMDAwMH0.9X3d6kH3_2nmrbqMxuoxzFW-wsWJVCe-lR-aQ-MmsGGXlEUBMgQ-4MtAq1UR9lLE0h2b5JrE_GfjzuC04h5xCg";
+  readonly wrongAud: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiJ1XzEiLCJpc3MiOiJodHRwczovL2xvZ2luLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9vdGhlci5leGFtcGxlLmNvbSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoyMDAwMDAwMDAwfQ.PgWdzi56J31OwoMqH4ysHzVKSKUDhi-AtHFUp1ewFzi-qGE-tknzrNKnKhDOncVzj0okb_flyy3vQgfzJwG5AQ";
+  readonly wrongIss: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiJ1XzEiLCJpc3MiOiJodHRwczovL2V2aWwuZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoyMDAwMDAwMDAwfQ.tIcLHLa9JLtKz1gqjRGdr5DFbUzRDs5KsoPsJCxspvbBcsFfRFG2G0XJnd1h4QHyZ_5B4OhY3W_jIIsnOPD9Bg";
+  readonly unknownKid: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoibm9wZSIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiJ1XzEiLCJpc3MiOiJodHRwczovL2xvZ2luLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MjAwMDAwMDAwMH0.walgG5GvpCVBnkMtkdw-epi5c93JqfvAM_N4EWR9Tqhiw_cnzITnlQyoVfihECmV1fqtFrhwM1RCIRJvd38zAQ";
+  readonly none: "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ1XzEiLCJpc3MiOiJodHRwczovL2xvZ2luLmV4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJleHAiOjIwMDAwMDAwMDAsImlhdCI6MTcwMDAwMDAwMH0.";
+  readonly snapshot: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6InBlcm1kb2NrLXNuYXBzaG90K2p3dCJ9.eyJzbmFwc2hvdCI6eyJ2IjoyLCJpc3N1ZWRBdCI6MTcwMDAwMDAwMCwic3ViamVjdCI6eyJwcmluY2lwYWwiOnsiaWQiOiJ1XzEiLCJyb2xlcyI6WyJtZW1iZXIiXX0sImNvbnRleHQiOnt9fSwicm9sZXMiOlsibWVtYmVyIl0sImdyYW50cyI6W10sInRlbmFudHMiOltdfSwic3ViIjoidV8xIiwiaXNzIjoiaHR0cHM6Ly9hcHAuZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL2FwcC5leGFtcGxlLmNvbSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoyMDAwMDAwMDAwLCJqdGkiOiJzbmFwX2ZpeHR1cmUifQ.4itaYctluoCwU-syytUxArtS_FRyNAti2SZxuSH-nKIMr7-Sb3h1Q3xugn_vPR1eupV4fVNIe6dH27_EiyDvCA";
+  readonly approval: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6InBlcm1kb2NrLWFwcHJvdmFsK2p3dCJ9.eyJhcHByb3ZhbCI6eyJ0b2tlbiI6InBkMS5hYmMiLCJwZXJtaXNzaW9uIjoicG9zdC5kZWxldGUiLCJyZXNvdXJjZSI6eyJ0eXBlIjoicG9zdCIsImlkIjoiNDIifSwic3RhdHVzIjoiYXBwcm92ZWQifSwic3ViIjoidV8xIiwiaXNzIjoiaHR0cHM6Ly9hcHAuZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL2FwcC5leGFtcGxlLmNvbSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoyMDAwMDAwMDAwLCJqdGkiOiJhcHJfZml4dHVyZSJ9.UHsoSzQCo68G7ee-EFqdzMLvmqaKlFIMdQKFuqZEM4yUQnJsJJTXbld_aCXcyfN-IdjF9cj2F5EHzsV4nLKbBg";
+  readonly decisions: "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoiMjAyNi0wOSIsInR5cCI6InBlcm1kb2NrLWRlY2lzaW9ucytqd3QifQ.eyJldmVudHMiOltdLCJpc3MiOiJodHRwczovL2FwcC5leGFtcGxlLmNvbSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoyMDAwMDAwMDAwLCJqdGkiOiJkZWNfZml4dHVyZSJ9.UZhJd72yFGxHOdjYbzcGYUPgYjvLwOPCtHKxEbLu56SdKSKUDCREXmEBI9WaCPKWjlTBnnIKMYwjG8I8RATJCg";
+};
+//#endregion
+//#region src/testing/supabase-fixtures.d.ts
+/**
+ * Claim sets in the shape the Supabase custom access token hook produces (the RBAC guide's
+ * `user_role` claim, optionally mirrored into `app_metadata`, plus a `memberships` array for
+ * multi-org apps). `tenantPlans` has scoped memberships, `tenant_id` and per-tenant plans in
+ * `features`, read with `plans: 'features'`. `full` sets every field of the
+ * claim contract plus a `hook.claims` extra claim; `portalContact`, `oauthClient` and
+ * `actChain` cover a customer contact, a Supabase OAuth server token and an RFC 8693 chain.
+ * `supportSession`, `supportSessionReadOnly` and `impersonation` are the `act.kind` tokens
+ * of a support tool; `anonymousSignIn` is a `signInAnonymously()` token read with
+ * `anonymousSignIns: 'deny'`. Every fixture passes `supabaseClaims()` and
+ * `schemas/supabase-claims-v1.json`. Plain data: no Supabase types.
+ */
+type SupabaseClaimFixture = {
+  readonly claims: Readonly<Record<string, unknown>>;
+  /** `subjectFromSupabase` options the case needs. */
+  readonly options?: {
+    readonly plans?: string;
+    readonly anonymousSignIns?: "deny";
+  };
+  readonly expect: {
+    readonly id: string | null;
+    readonly roles: readonly string[];
+    readonly memberships: readonly {
+      readonly tenant?: string;
+      readonly scope?: string;
+      readonly id?: string;
+      readonly within?: Readonly<Record<string, string>>;
+      readonly on?: {
+        readonly resource: string;
+        readonly id: string;
+      };
+      readonly roles: readonly string[];
+      readonly via?: string;
+      readonly expiresAt?: number;
+      readonly grantedBy?: string;
+      readonly reason?: string;
+      readonly managedBy?: "idp";
+      readonly entitlements?: readonly string[];
+    }[];
+    readonly tenant?: string;
+    readonly plans?: readonly string[];
+    /** `subject.actor`, absent when the token has neither `act` nor `client_id`. */
+    readonly actor?: {
+      readonly id: string;
+      readonly kind: "oauth-client" | "impersonation";
+    } | {
+      readonly id: string;
+      readonly kind: "support";
+      readonly sessionId: string;
+      readonly readOnly: boolean;
+    };
+    /** `subject.delegation`: the `scope` claim and the `act` chain of an `oauth-client` actor. */
+    readonly delegation?: {
+      readonly scopes?: readonly string[];
+      readonly chain?: Readonly<Record<string, unknown>>;
+    };
+  };
+};
+type SupabaseClaimFixtureName = "topLevelRole" | "appMetadataRole" | "nullTopLevelFallsBack" | "arrayRoles" | "missingRole" | "nullRole" | "userMetadataIgnored" | "multiOrg" | "tenantPlans" | "full" | "portalContact" | "oauthClient" | "actChain" | "supportSession" | "supportSessionReadOnly" | "impersonation" | "anonymousSignIn" | "anon" | "serviceRole";
+export declare const supabaseClaimFixtures: Readonly<Record<SupabaseClaimFixtureName, SupabaseClaimFixture>>;
+/**
+ * `supabaseClaimFixtures` as a `supabase/sdk` conformance vector file
+ * (`schema/conformance.schema.json`): each case's `input` is a verified
+ * `getClaims()` payload and the `subjectFromSupabase` options, `expected` the
+ * subject fields it maps to. `JSON.stringify` it for a port in another language.
+ */
+type SupabaseClaimVectors = {
+  readonly feature: "auth.session.get_claims";
+  readonly cases: readonly {
+    readonly name: string;
+    readonly input: {
+      readonly claims: SupabaseClaimFixture["claims"];
+      readonly options?: SupabaseClaimFixture["options"];
+    };
+    readonly expected: SupabaseClaimFixture["expect"];
+  }[];
+};
+export declare const supabaseClaimVectors: SupabaseClaimVectors;
+/**
+ * The `permdock supabase inspect --json` manifest for a policy with one
+ * `tenant` scope, the default `supabase.hook` and a `features` claim from
+ * `public.feature_claims`. A package that reads the manifest tests its
+ * parser against this value.
+ */
+export declare const supabaseHookManifestFixture: SupabaseHookManifest;
+//#endregion
+export { type AgentAdapterOptions, type AgentCall, type AgentMounted, type AgentOutcome, type AgentScenarioDomain, type AgentScenarioName, type AgentToolName, type ApprovalStoreOptions, type AuthZenEvaluationVector, type AuthZenEvaluationsVector, type AuthZenSearchVector, type AuthZenVectors, type ClientParityCase, type ClientParityOptions, type ClientStoreFactory, type ClientStoreFactoryOptions, type ClientStoreHandle, type ClientStorePermDock, type ClientStoreStatus, type DescribePolicyConfig, type HttpAdapterOptions, type HttpCall, type HttpMounted, type HttpOp, type HttpResult, type HttpScenarioDomain, type HttpScenarioName, type MatrixCell, type MatrixOutcome, type OrmParityCase, type OrmParityOptions, type OrmParityReport, type OrmParityRunInput, type OrmParityScenario, type RlsDbOutcome, type RlsFieldsOutcome, type RlsParityCase, type RlsParityFixture, type RlsParityOptions, type RlsParityReport, type RlsParitySubject, type RlsQueryFn, type RlsQueryResult, type SupabaseClaimFixture, type SupabaseClaimFixtureName, type SupabaseClaimVectors, type TestAuthZenOptions, expectTypeOf, supabaseMembershipsBudget };