permdock 0.0.0 → 0.1.0

package/dist/testing/saas/index.d.ts

@@ -0,0 +1,194 @@
+import { Qt as PermDockOptions, at as LimitStore, cr as CustomRole, ft as RelationSource, hr as Subject, ir as Actor, mr as Principal, pr as Membership, ur as Delegation } from "../../policy-CInmNGkM.js";
+import { d as Permission } from "../../permissions-B4apnahQ.js";
+import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-B8vCg_bI.js";
+import { n as saasPolicy, t as SAAS_API_KEY_LIMIT } from "../../policy-Cq2fB8Q5.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/testing/saas/schema.d.ts
+type FieldKind = "string" | "boolean" | "nullable-string";
+type FieldValue<K extends FieldKind> = K extends "string" ? string : K extends "boolean" ? boolean : string | null;
+type Shape = {
+  readonly [field: string]: FieldKind;
+};
+type Infer<S extends Shape> = { [K in keyof S]: FieldValue<S[K]>; };
+/** A dependency-free Standard Schema for flat fixture rows. */
+export declare function rowSchema<const S extends Shape>(shape: S): StandardSchemaV1<Infer<S>>;
+//#endregion
+//#region src/testing/saas/seed.d.ts
+type SaasPlan = "free" | "pro";
+type SaasOrg = {
+  readonly id: string;
+  readonly name: string;
+  readonly plan: SaasPlan;
+  readonly customRoles: readonly CustomRole[];
+};
+type SaasMember = {
+  readonly user: string;
+  /** Absent on a resource-scoped membership, which carries only `on`. */
+  readonly tenant?: string;
+  readonly team?: string;
+  readonly on?: {
+    readonly resource: string;
+    readonly id: string;
+  };
+  readonly roles: readonly string[];
+  readonly expiresAt?: number;
+};
+/** One edge-table row: `user` holds `relation` on `folder`. */
+type SaasShare = {
+  readonly folder: string;
+  readonly user: string;
+  readonly relation: "viewer" | "editor";
+  readonly expiresAt?: number;
+};
+type SaasSeed = {
+  readonly orgs: readonly SaasOrg[];
+  readonly members: readonly SaasMember[];
+  readonly projects: readonly SaasProject[];
+  readonly docs: readonly SaasDoc[];
+  readonly folders: readonly SaasFolder[];
+  readonly shares: readonly SaasShare[];
+};
+/** Epoch seconds in the past, so the membership is expired for any clock. */
+export declare const SAAS_EXPIRED_AT = 1e9;
+/**
+ * Users, one hazard each:
+ * - alice: admin in acme, viewer in globex (different role per org)
+ * - bob: member in acme (owns p1, p3, p4)
+ * - carol: owner in acme
+ * - dave: custom `contractor` role in acme (includes member)
+ * - erin: admin in acme AND globex (same role in two orgs)
+ * - frank: expired acme membership
+ * - mallory: no memberships at all
+ * - gina: `lead` of team-a in acme
+ * - hank: viewer in acme, `collaborator` on project p3 only
+ * - `user-2` and `2`: members of `org-1`; `Date.parse` maps both ids to one instant
+ * - tina: member of `tenant-1`; `Date.parse('org-1') === Date.parse('tenant-1')`
+ * - ivan: viewer in acme who holds the team role `lead` on the tenant membership (the wrong scope)
+ *
+ * Acme's folders: `root` ─ `eng` ─ `platform` ─ `infra`, and `root` ─ `hr`
+ * (restricted) ─ `payroll`. bob views `root`, hank views `hr`, gina edits
+ * `eng`, frank's view of `root` expired.
+ */
+export declare const saasSeed: SaasSeed;
+/** The seed's folder tree and shares as a `RelationSource`, for `createPermDock({ relations })`. */
+export declare function saasRelations(seed?: SaasSeed): RelationSource;
+/** Every user id in the seed. */
+export declare const saasUsers: readonly string[];
+export declare function saasOrg(id: string): SaasOrg | undefined;
+/** Memberships of `user` as the PermDock `Membership` shape. */
+export declare function saasMemberships(user: string, members?: readonly SaasMember[]): Membership[];
+/** Custom roles of every org, as `createPermDock({ customRoles })` expects. */
+export declare const saasCustomRoles: readonly CustomRole[];
+/**
+ * The principal for `user`, with the plans of the requested `tenant`'s org.
+ * The tenant itself is passed to `createPermDock({ tenant })`, never trusted
+ * from here.
+ */
+export declare function saasPrincipal(user: string, tenant?: string): Principal;
+//#endregion
+//#region src/testing/saas/sql.d.ts
+/**
+ * Postgres tables for the SaaS domain. Column names match the resource
+ * fields (`"orgId"`, `"ownerId"`) so generated RLS and ORM filters compile
+ * against them without a column map. RLS is enabled and forced on the row
+ * tables; policies come from `permdock rls generate`.
+ */
+export declare const saasSchemaSql = "\ncreate table org (\n  id text primary key,\n  name text not null,\n  plan text not null check (plan in ('free', 'pro'))\n);\ncreate table org_member (\n  user_id text not null,\n  org_id text references org (id),\n  team_id text,\n  resource text,\n  resource_id text,\n  role text not null,\n  expires_at bigint\n);\ncreate table project (\n  id text primary key,\n  \"orgId\" text not null references org (id),\n  \"ownerId\" text not null,\n  name text not null,\n  archived boolean not null default false\n);\nalter table project enable row level security;\nalter table project force row level security;\ncreate table doc (\n  id text primary key,\n  \"orgId\" text not null references org (id),\n  \"teamId\" text,\n  title text not null,\n  locked boolean not null default false\n);\nalter table doc enable row level security;\nalter table doc force row level security;\ncreate table folder (\n  id text primary key,\n  \"orgId\" text not null references org (id),\n  \"parentId\" text references folder (id),\n  name text not null,\n  restricted boolean not null default false\n);\nalter table folder enable row level security;\nalter table folder force row level security;\ncreate table folder_share (\n  folder_id text not null references folder (id) on delete cascade,\n  user_id text not null,\n  expires_at timestamptz\n);\ncreate table folder_editor (\n  folder_id text not null references folder (id) on delete cascade,\n  user_id text not null\n);\n";
+/** `insert` statements for a seed; the default is the full shared seed. */
+export declare function saasSeedSql(seed?: SaasSeed): string;
+//#endregion
+//#region src/testing/saas/tokens.d.ts
+type EcJwk = {
+  readonly kty: "EC";
+  readonly crv: "P-256";
+  readonly x: string;
+  readonly y: string;
+  readonly kid: string;
+  readonly alg: "ES256";
+  readonly use: "sig";
+};
+export declare const saasPublicJwk: EcJwk;
+export declare const saasPrivateJwk: EcJwk & {
+  readonly d: string;
+};
+export declare const saasJwks: Readonly<{
+  keys: EcJwk[];
+}>;
+export declare const saasIssuer = "https://saas.permdock.test";
+export declare const saasAudience = "permdock-saas";
+export declare const SAAS_TOKEN_TTL_SECONDS = 3600;
+type SaasTokenOptions = {
+  /** Claim memberships; `false` omits the claim (database mode). Defaults to the seed. */
+  readonly memberships?: readonly Membership[] | false;
+  readonly ttl?: number;
+  /** Epoch seconds used for `iat`. */
+  readonly now?: number;
+  readonly issuer?: string;
+  readonly audience?: string;
+  readonly claims?: Readonly<Record<string, unknown>>;
+};
+/** Signs an ES256 access token for `sub` with WebCrypto; no dependency. */
+export declare function signSaasToken(sub: string, options?: SaasTokenOptions): Promise<string>;
+/**
+ * Verifies a token from `signSaasToken` (ES256, `kid`, `iss`, `aud`, `exp`)
+ * and returns its `sub`, or `null`; never throws. Identity only: memberships
+ * and plans come from the seed, never from the token.
+ */
+export declare function verifySaasToken(token: string | null | undefined, now?: number): Promise<string | null>;
+/** `verifySaasToken` plus the token's `exp` as `expiresAt` (epoch seconds). */
+export declare function verifySaasSession(token: string | null | undefined, now?: number): Promise<{
+  readonly sub: string;
+  readonly expiresAt: number;
+} | null>;
+//#endregion
+//#region src/testing/saas/scenarios.d.ts
+type SaasOutcome = "granted" | "denied" | "approval-required";
+type SaasScenario = {
+  readonly name: string;
+  readonly user: string;
+  /** The requested tenant, as a route or header would pass it. */
+  readonly tenant?: string;
+  readonly permission: Permission;
+  readonly row?: SaasProject | SaasDoc | SaasFolder;
+  readonly expected: {
+    readonly outcome: SaasOutcome;
+    /** One reason that must appear among the denials. */
+    readonly reason?: string;
+  };
+  /**
+   * `false` when the outcome depends on server-only inputs (a quota store,
+   * approvals), so a snapshot client is not expected to match.
+   */
+  readonly client?: boolean;
+  /**
+   * The client outcome when it is stricter than the server's: a snapshot
+   * cannot evaluate a closure deny, so it fails closed.
+   */
+  readonly clientOutcome?: SaasOutcome;
+  /** An agent acting for `user`; without `delegation` it reaches nothing. */
+  readonly actor?: Actor;
+  readonly delegation?: Delegation;
+  /** Units of the daily api-key quota this subject already used in the tenant. */
+  readonly quotaUsed?: number;
+};
+/** What the policy's `subject` receives: the principal, or a `Subject` carrying the actor. */
+export declare function saasUser(scenario: SaasScenario): Principal | Subject;
+/** A memory quota store in which every subject has already used `used` units. */
+export declare function saasLimitStore(used?: number): LimitStore;
+/** The `createPermDock` options a scenario runs with: tenant, custom roles, quota and folder tree. */
+export declare function saasScenarioOptions(scenario: SaasScenario): PermDockOptions;
+export declare function saasProject(id: string): SaasProject;
+export declare function saasDoc(id: string): SaasDoc;
+export declare function saasFolder(id: string): SaasFolder;
+/**
+ * The folder tree, decided with `createPermDock({ relations: saasRelations() })`.
+ * A snapshot carries no graph, so every graph grant is server-only on a client.
+ */
+export declare const saasFolderScenarios: readonly SaasScenario[];
+/**
+ * Hand-written expectations. Never derive `expected` from the engine: the
+ * list is the oracle every adapter, ORM and client suite runs against.
+ */
+export declare const saasScenarios: readonly SaasScenario[];
+//#endregion
+export { SAAS_API_KEY_LIMIT, type SaasDoc, SaasDocSchema, type SaasFolder, SaasFolderSchema, type SaasMember, type SaasOrg, type SaasOutcome, type SaasPlan, type SaasProject, SaasProjectSchema, type SaasScenario, type SaasSeed, type SaasShare, type SaasTokenOptions, saasPermissions, saasPlans, saasPolicy, saasRoles, saasTenantRoleNames };

package/dist/testing/saas/index.js

@@ -0,0 +1,3 @@
+import { a as saasPlans, c as rowSchema, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-CofRqesP.js";
+import { C as saasOrg, D as saasUsers, E as saasSeed, O as SAAS_API_KEY_LIMIT, S as saasMemberships, T as saasRelations, _ as verifySaasToken, a as saasProject, b as SAAS_EXPIRED_AT, c as saasUser, d as saasIssuer, f as saasJwks, g as verifySaasSession, h as signSaasToken, i as saasLimitStore, k as saasPolicy, l as SAAS_TOKEN_TTL_SECONDS, m as saasPublicJwk, n as saasFolder, o as saasScenarioOptions, p as saasPrivateJwk, r as saasFolderScenarios, s as saasScenarios, t as saasDoc, u as saasAudience, v as saasSchemaSql, w as saasPrincipal, x as saasCustomRoles, y as saasSeedSql } from "../../saas-BRrZzJkM.js";
+export { SAAS_API_KEY_LIMIT, SAAS_EXPIRED_AT, SAAS_TOKEN_TTL_SECONDS, SaasDocSchema, SaasFolderSchema, SaasProjectSchema, rowSchema, saasAudience, saasCustomRoles, saasDoc, saasFolder, saasFolderScenarios, saasIssuer, saasJwks, saasLimitStore, saasMemberships, saasOrg, saasPermissions, saasPlans, saasPolicy, saasPrincipal, saasPrivateJwk, saasProject, saasPublicJwk, saasRelations, saasRoles, saasScenarioOptions, saasScenarios, saasSchemaSql, saasSeed, saasSeedSql, saasTenantRoleNames, saasUser, saasUsers, signSaasToken, verifySaasSession, verifySaasToken };

package/dist/testing/saas/permissions.d.ts

@@ -0,0 +1,2 @@
+import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-B8vCg_bI.js";
+export { SaasDoc, SaasDocSchema, SaasFolder, SaasFolderSchema, SaasProject, SaasProjectSchema, saasPermissions, saasPlans, saasRoles, saasTenantRoleNames };

package/dist/testing/saas/permissions.js

@@ -0,0 +1,2 @@
+import { a as saasPlans, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-CofRqesP.js";
+export { SaasDocSchema, SaasFolderSchema, SaasProjectSchema, saasPermissions, saasPlans, saasRoles, saasTenantRoleNames };

package/dist/text-diff-BdkkYSbi.js

@@ -0,0 +1,15 @@
+import { createTwoFilesPatch } from "diff";
+//#region src/cli/text-diff.ts
+const MAX_LINES = 40;
+/**
+* A unified diff from the file on disk to what the command would write,
+* cut to the first {@link MAX_LINES} lines so a CI log stays readable.
+*/
+function shortDiff(file, onDisk, next) {
+	const lines = createTwoFilesPatch(`${file} (on disk)`, `${file} (generated)`, onDisk, next, void 0, void 0, { context: 2 }).split("\n").filter((line) => !line.startsWith("=====")).filter((line, index, all) => line !== "" || index < all.length - 1);
+	if (lines.length <= MAX_LINES) return lines.join("\n");
+	const rest = lines.length - MAX_LINES;
+	return [...lines.slice(0, MAX_LINES), `… ${rest} more diff line${rest === 1 ? "" : "s"}`].join("\n");
+}
+//#endregion
+export { shortDiff as t };

package/dist/thenable-okc2xDsj.js

@@ -0,0 +1,10 @@
+//#region src/core/thenable.ts
+function isThenable(value) {
+	return value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
+}
+/** Settles a promise nobody awaits, so its rejection is not reported as unhandled. */
+function ignoreRejection(value) {
+	Promise.resolve(value).then(void 0, () => void 0);
+}
+//#endregion
+export { isThenable as n, ignoreRejection as t };

package/dist/timeout-D51niuQP.js

@@ -0,0 +1,8 @@
+//#region src/core/timeout.ts
+/** Aborts after `ms`, or earlier when `signal` aborts. */
+function timeoutSignal(ms, signal) {
+	const deadline = AbortSignal.timeout(ms);
+	return signal === void 0 || signal === null ? deadline : AbortSignal.any([signal, deadline]);
+}
+//#endregion
+export { timeoutSignal as t };

package/dist/trpc/index.d.ts

@@ -0,0 +1,80 @@
+import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
+import { d as Permission } from "../permissions-B4apnahQ.js";
+import { f as ApprovalStore } from "../types-B8w5PFtS.js";
+import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
+import { r as PdpFactory } from "../types-BvBk1wgn.js";
+import { S as ConnectionOptions, b as Connection, h as WebBotAuthVerifier, n as OpenApiHooks, o as TenantOption } from "../create-BKF3dgFk.js";
+import { t as StreamProtectOptions } from "../stream-BhMfZOwr.js";
+import { AnyTRPCMiddlewareFunction } from "@trpc/server";
+//#region src/trpc/create.d.ts
+type TrpcMiddlewareOpts<TCtx = object, TInput = unknown> = {
+  readonly ctx: TCtx;
+  readonly input?: TInput;
+  readonly path: string;
+  readonly type: string;
+  readonly next: (opts?: {
+    readonly ctx: TCtx;
+  }) => Promise<unknown>;
+};
+type TrpcMiddleware = AnyTRPCMiddlewareFunction;
+type TrpcPermDockOptions<TCtx = object, TUser = unknown> = {
+  readonly subject: (opts: TrpcMiddlewareOpts<TCtx>) => TUser | Promise<TUser>;
+  readonly tenant?: TenantOption<TrpcMiddlewareOpts<TCtx>>;
+  /** The Web `Request` behind a context; defaults to `ctx.request` or `ctx.req`. */
+  readonly request?: (ctx: TCtx) => Request | null | undefined;
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The object graph for relation grants that walk a parent chain; without it they deny. */
+  readonly relations?: RelationSource;
+  readonly entitlements?: EntitlementSource;
+  readonly customRoles?: RoleSource;
+  /** Hosted grants, read once per instance; see `PolicySource`. */
+  readonly policies?: PolicySource;
+  readonly store?: ApprovalStore;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  /** `createPermDock` from `permdock/pdp`; `protect` then decides delegated permissions remotely. */
+  readonly pdp?: PdpFactory;
+  /** Accepted for adapter parity; not read by this adapter. */
+  readonly snapshots?: SnapshotSource;
+  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
+  readonly webBotAuth?: WebBotAuthVerifier;
+  /** Ends or revalidates open subscriptions. */
+  readonly revocations?: RevocationFeed;
+};
+type TrpcOpenApiHooks = {
+  readonly security: (permission: Permission) => {
+    readonly openapi: {
+      readonly protect: true;
+      readonly security: readonly Record<string, readonly string[]>[];
+      readonly "x-permdock-permissions": readonly string[];
+    };
+  };
+  readonly securitySchemes: OpenApiHooks["securitySchemes"];
+};
+type TrpcPermDock<TCtx = object> = {
+  readonly permdock: () => TrpcMiddleware;
+  readonly protect: (permission: Permission, loadData?: (opts: TrpcMiddlewareOpts<TCtx>) => unknown, protectOptions?: StreamProtectOptions) => TrpcMiddleware;
+  /** A long-lived connection for the request behind `ctx`. */
+  readonly connection: (opts: TrpcMiddlewareOpts<TCtx>, connectionOptions?: ConnectionOptions) => Promise<Connection>;
+  readonly permdockHandler: (request: Request) => Promise<Response>;
+  readonly openapi: TrpcOpenApiHooks;
+  readonly errorFormatter: <TShape extends {
+    readonly data: object;
+  }>(opts: {
+    readonly shape: TShape;
+    readonly error: {
+      readonly cause?: unknown;
+    };
+  }) => TShape;
+};
+export declare function errorFormatter<TShape extends {
+  readonly data: object;
+}>(opts: {
+  readonly shape: TShape;
+  readonly error: {
+    readonly cause?: unknown;
+  };
+}): TShape;
+export declare function createPermDock<TCtx = object, TUser = unknown, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: TrpcPermDockOptions<TCtx, TUser>): TrpcPermDock<TCtx>;
+//#endregion
+export type { TrpcMiddleware, TrpcMiddlewareOpts, TrpcOpenApiHooks, TrpcPermDock, TrpcPermDockOptions };

package/dist/trpc/index.js

@@ -0,0 +1,205 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { o as invalidSignatureResponse } from "../evaluations-DsAU9ppl.js";
+import { r as tenantScope, t as createKernel } from "../create-CSkhDU9T.js";
+import { t as problemFromError } from "../map-error-RJ3ZsUyA.js";
+import { n as guardIterable, r as isAsyncIterable } from "../stream-Q_xlB6Ko.js";
+import { TRPCError, isTrackedEnvelope } from "@trpc/server";
+//#region src/trpc/create.ts
+function requestFromCtx(ctx) {
+	if ("request" in ctx && ctx.request instanceof Request) return ctx.request;
+	if ("req" in ctx && ctx.req instanceof Request) return ctx.req;
+}
+function problemMessage(cause, fallback) {
+	if (cause !== null && typeof cause === "object" && "detail" in cause && typeof cause.detail === "string" && cause.detail.length > 0) return cause.detail;
+	return fallback;
+}
+const PROBLEM = Symbol.for("permdock.problem");
+function trpcCode(status) {
+	switch (status) {
+		case 400: return "BAD_REQUEST";
+		case 401: return "UNAUTHORIZED";
+		case 404: return "NOT_FOUND";
+		case 429: return "TOO_MANY_REQUESTS";
+		case 503: return "SERVICE_UNAVAILABLE";
+		default: return "FORBIDDEN";
+	}
+}
+/** A `TRPCError` for a revoked subscription; the Problem Details body rides on `cause`. */
+function trpcErrorFrom(error) {
+	const problem = error.toProblemDetails();
+	const cause = { ...problem };
+	Object.defineProperty(cause, PROBLEM, {
+		value: true,
+		enumerable: true
+	});
+	return new TRPCError({
+		code: trpcCode(problem.status),
+		message: error.code,
+		cause
+	});
+}
+async function throwTrpcError(response) {
+	let cause;
+	try {
+		cause = await response.json();
+	} catch {
+		cause = { status: response.status };
+	}
+	if (cause !== null && typeof cause === "object") Object.defineProperty(cause, PROBLEM, {
+		value: true,
+		enumerable: true
+	});
+	const code = trpcCode(response.status);
+	throw new TRPCError({
+		code,
+		message: problemMessage(cause, code),
+		cause
+	});
+}
+/**
+* A PermDock error thrown further down (an `assert` in a resolver) arrives as
+* a failed middleware result; it becomes the same TRPCError `protect` throws.
+*/
+function mapDownstream(result) {
+	if (result === null || typeof result !== "object" || result.ok !== false) return Promise.resolve(result);
+	const error = result.error;
+	const cause = error instanceof TRPCError && error.code === "INTERNAL_SERVER_ERROR" ? error.cause : void 0;
+	const mapped = problemFromError(cause);
+	return mapped === void 0 ? Promise.resolve(result) : throwTrpcError(mapped);
+}
+function errorFormatter(opts) {
+	const cause = opts.error.cause;
+	if (cause === null || typeof cause !== "object" || !(PROBLEM in cause)) return opts.shape;
+	const { [PROBLEM]: _brand, ...problem } = cause;
+	return {
+		...opts.shape,
+		data: {
+			...opts.shape.data,
+			...problem
+		}
+	};
+}
+function createPermDock(policy, options) {
+	const optsByRequest = /* @__PURE__ */ new WeakMap();
+	const requestByCtx = /* @__PURE__ */ new WeakMap();
+	const kernel = createKernel(policy, compact({
+		subject: (request) => {
+			const opts = optsByRequest.get(request);
+			return opts === void 0 ? null : options.subject(opts);
+		},
+		memberships: options.memberships,
+		relations: options.relations,
+		entitlements: options.entitlements,
+		customRoles: options.customRoles,
+		policies: options.policies,
+		store: options.store,
+		sink: options.sink,
+		limits: options.limits,
+		pdp: options.pdp,
+		webBotAuth: options.webBotAuth,
+		revocations: options.revocations,
+		adapter: "trpc"
+	}));
+	const requestOf = (ctx) => {
+		if (options.request !== void 0) try {
+			return options.request(ctx) ?? void 0;
+		} catch {
+			return;
+		}
+		return requestFromCtx(ctx);
+	};
+	/**
+	* One `Request` per HTTP request, shared by every procedure in a batch. The
+	* subject reads the first procedure's opts; the tenant is resolved from each
+	* procedure's own opts in `scopeOf`, never through the shared `Request`.
+	*/
+	const bind = (opts) => {
+		const ctx = opts.ctx;
+		const hit = requestByCtx.get(ctx);
+		if (hit !== void 0) return hit;
+		const request = requestOf(opts.ctx) ?? new Request(`http://localhost/trpc/${opts.path}`, { method: "POST" });
+		requestByCtx.set(ctx, request);
+		if (!optsByRequest.has(request)) optsByRequest.set(request, opts);
+		return request;
+	};
+	const scopeOf = (opts) => tenantScope(options.tenant, opts);
+	const attach = (ctx, request) => {
+		requestByCtx.set(ctx, request);
+	};
+	const permdock = () => (async (opts) => {
+		const request = bind(opts);
+		let instance;
+		try {
+			instance = await kernel.permdock(request, await scopeOf(opts));
+		} catch (error) {
+			const response = invalidSignatureResponse(error);
+			if (response !== void 0) return throwTrpcError(response);
+			throw error;
+		}
+		const nextCtx = {
+			...opts.ctx,
+			permdock: instance
+		};
+		attach(nextCtx, request);
+		return mapDownstream(await opts.next({ ctx: nextCtx }));
+	});
+	const connection = async (opts, connectionOptions) => kernel.connection(bind(opts), connectionOptions, await scopeOf(opts));
+	/** Wraps a subscription's iterable so revocation ends it and unreadable items drop. */
+	const guardSubscription = async (result, opts, permission, loadData, protectOptions) => {
+		if (result === null || typeof result !== "object" || result.ok !== true || !isAsyncIterable(result.data)) return result;
+		const conn = await connection(opts, compact({
+			permission,
+			data: loadData
+		}));
+		return {
+			...result,
+			data: guardIterable(result.data, conn, compact({
+				items: protectOptions?.items,
+				unwrap: (item) => isTrackedEnvelope(item) ? item[1] : item,
+				onRevoked: trpcErrorFrom
+			}))
+		};
+	};
+	const protect = (permission, loadData, protectOptions) => (async (opts) => {
+		const request = bind(opts);
+		const guard = await kernel.protect(permission, loadData === void 0 ? void 0 : () => loadData(opts), protectOptions)(request, await scopeOf(opts));
+		if (guard.ok) {
+			const nextCtx = {
+				...opts.ctx,
+				permdock: guard.permdock,
+				permdockData: guard.data
+			};
+			attach(nextCtx, request);
+			return guardSubscription(await mapDownstream(await opts.next({ ctx: nextCtx })), opts, permission, loadData === void 0 ? void 0 : () => loadData(opts), protectOptions);
+		}
+		return throwTrpcError(guard.response);
+	});
+	const permdockHandler = (request) => {
+		const opts = {
+			ctx: { req: request },
+			path: "permdock",
+			type: "unknown",
+			next: (nextOpts) => Promise.resolve(nextOpts ?? { ctx: { req: request } })
+		};
+		bind(opts);
+		const { POST, GET } = kernel.permdockHandler(() => scopeOf(opts));
+		return Promise.resolve(request.method === "GET" ? GET(request) : POST(request));
+	};
+	const kernelOpenApi = kernel.openapi;
+	return {
+		permdock,
+		protect,
+		connection,
+		permdockHandler,
+		openapi: {
+			security: (permission) => ({ openapi: {
+				protect: true,
+				...kernelOpenApi.security(permission)
+			} }),
+			securitySchemes: kernelOpenApi.securitySchemes
+		},
+		errorFormatter
+	};
+}
+//#endregion
+export { createPermDock, errorFormatter };

package/dist/types-B8w5PFtS.d.ts

@@ -0,0 +1,141 @@
+import { U as Approver, hr as Subject, o as ApprovalStage, pr as Membership, qn as RelationGrantee, r as ApprovalMode } from "./policy-CInmNGkM.js";
+//#region src/approvals/types.d.ts
+type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
+type ApprovalApprovers = {
+  /** Under `mode: 'any'` (the default). */
+  readonly by?: Approver | readonly Approver[];
+  readonly mode?: ApprovalMode;
+  /** Under `mode: 'all'` or `'sequential'`. */
+  readonly stages?: readonly ApprovalStage[];
+  /** `false` lets the request's principal approve it; absent means `true`. */
+  readonly distinct?: boolean;
+  /** Set when the approval no longer applies once the row's `version` changes. */
+  readonly staleOn?: "resource-change";
+  /** Distinct approvers of `by` needed before `status` becomes `approved`; absent means 1. */
+  readonly quorum?: number;
+  /** Who else may approve once the request has waited `after` (a duration such as `'4h'`) since `createdAt`. */
+  readonly escalation?: {
+    readonly after: string;
+    readonly to: Approver | readonly Approver[];
+  };
+};
+/** One recorded approval: who gave it, when, and under `stages` the index of the stage it counts for. */
+type ApprovalSignature = {
+  readonly by: string;
+  readonly at: string;
+  readonly stage?: number;
+};
+type ApprovalSubjectSummary = {
+  readonly principal: {
+    readonly id: string;
+    readonly roles: readonly string[];
+    readonly tenant?: string;
+  } | null;
+  readonly actor?: {
+    readonly id: string;
+    readonly kind: string;
+  };
+  readonly session?: string;
+  readonly delegation?: {
+    readonly scopes?: readonly string[];
+    readonly authorizationDetails?: readonly unknown[];
+  };
+};
+type ApprovalRequest = {
+  readonly v: 1;
+  readonly token: string;
+  readonly permission: string;
+  readonly scope: string;
+  readonly resource: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly subject: ApprovalSubjectSummary;
+  readonly membership?: Membership;
+  readonly approvers?: ApprovalApprovers;
+  readonly detail: string;
+  readonly adapter?: string;
+  readonly createdAt: string;
+  readonly expiresAt: string;
+  readonly status: ApprovalStatus;
+  /** Approvals given so far, oldest first; the request is `approved` once there are `approvers.quorum` of them. */
+  readonly approvals?: readonly ApprovalSignature[];
+  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 note?: string;
+  readonly consumedAt?: string;
+};
+type ApprovalVerdict = {
+  readonly status: "approved" | "rejected";
+  readonly by: Subject;
+  readonly note?: string;
+  /**
+   * The relation approvers (by `approverRelationKey`) that `by` holds on the
+   * request's resource, as `approverRelations` read them. Server-side input:
+   * set it from a `RelationSource`, never from the request body. Absent means
+   * none, so relation approvers match nobody.
+   */
+  readonly relations?: readonly string[];
+};
+type ApprovalListFilter = {
+  readonly status?: ApprovalStatus;
+  readonly principalId?: string;
+  readonly actorId?: string;
+  readonly tenant?: string;
+  readonly session?: string;
+};
+type ApprovalListQuery = ApprovalListFilter & {
+  /** Page size, 1 to 200; 50 when omitted. */
+  readonly limit?: number;
+  /** The `next` of the previous page; opaque to the caller. */
+  readonly cursor?: string;
+};
+/**
+ * One page, oldest `createdAt` first. `next` is absent on the last page; an
+ * unreadable cursor yields an empty last page.
+ */
+type ApprovalPage = {
+  readonly items: readonly ApprovalRequest[];
+  readonly next?: string;
+};
+type ApprovalCancelMeta = {
+  readonly by: string;
+  readonly note?: string;
+};
+type ApprovalStore = {
+  create(request: ApprovalRequest): Promise<void> | void;
+  get(token: string): Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  resolve(token: string, verdict: ApprovalVerdict): Promise<ApprovalRequest> | ApprovalRequest;
+  list(query: ApprovalListQuery): Promise<ApprovalPage> | ApprovalPage;
+  expire(now?: Date): Promise<number> | number;
+  /**
+   * Marks an approved, unexpired, unconsumed request consumed and returns it;
+   * returns `null` otherwise. Must be atomic: two concurrent calls for one
+   * token never both return the request.
+   */
+  consume(token: string, now?: Date): Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  cancel?(filter: ApprovalListFilter, meta: ApprovalCancelMeta): Promise<number> | number;
+};
+type ApprovalResumeFailure = "approval-not-found" | "approval-pending" | "approval-rejected" | "approval-expired" | "approval-consumed";
+type ApprovalInspectResult = {
+  readonly ok: true;
+  readonly request: ApprovalRequest;
+} | {
+  readonly ok: false;
+  readonly detail: ApprovalResumeFailure;
+};
+declare const APPROVAL_HEADER: "PermDock-Approval";
+declare const DEFAULT_APPROVAL_TTL_MS: number;
+/** The approvals a request needs in total: `approvers.quorum` (or 1), or the sum of its stages' quorums. */
+declare function approvalQuorum(request: ApprovalRequest): number;
+/**
+ * The instant from which `approvers.escalation.to` may approve, in epoch
+ * milliseconds, or `undefined` when the request has no escalation or its
+ * `after` does not parse (then nobody escalates: fail-closed).
+ */
+declare function escalationOpenAt(request: ApprovalRequest): number | undefined;
+/** The key a verdict's `relations` lists a relation approver under. */
+declare function approverRelationKey(item: RelationGrantee): string;
+//#endregion
+export { approverRelationKey as _, ApprovalListFilter as a, ApprovalRequest as c, ApprovalStatus as d, ApprovalStore as f, approvalQuorum as g, DEFAULT_APPROVAL_TTL_MS as h, ApprovalInspectResult as i, ApprovalResumeFailure as l, ApprovalVerdict as m, ApprovalApprovers as n, ApprovalListQuery as o, ApprovalSubjectSummary as p, ApprovalCancelMeta as r, ApprovalPage as s, APPROVAL_HEADER as t, ApprovalSignature as u, escalationOpenAt as v };