permdock 0.1.0 → 0.2.0

package/dist/nest/index.d.ts

@@ -1,12 +1,10 @@
-import { $ as DecisionSink, C as Policy, Zt as PermDock, 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 { C as Policy, Nr as Principal, ln as PermDock } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
 import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
-import { o as OtelWrap } from "../types-B9dmiiab.js";
-import { r as PdpFactory } from "../types-BvBk1wgn.js";
-import { S as ConnectionOptions, b as Connection, g as discoverViaSignatureAgent, h as WebBotAuthVerifier, n as OpenApiHooks, o as TenantOption, r as ProtectOptions, u as InvalidSignatureError, y as verifyWebBotAuth } from "../create-BKF3dgFk.js";
+import { A as ConnectionOptions, O as Connection, h as InvalidSignatureError, i as ProtectOptions, n as OpenApiHooks, w as verifyWebBotAuth, x as discoverViaSignatureAgent } from "../create-BWyx3jua.js";
+import { t as ServerAdapterOptions } from "../bind-CVy3Espv.js";
 import { i as sendResponse, t as NodeRequest } from "../http-DPuDaChb.js";
-import { CanActivate, ExceptionFilter, ExecutionContext, Type } from "@nestjs/common";
+import { CanActivate, DynamicModule, ExceptionFilter, ExecutionContext, Type } from "@nestjs/common";
 //#region src/nest/http.d.ts
 /**
  * `@nestjs/platform-express` hands the guard an `IncomingMessage`;
@@ -20,27 +18,7 @@ type NestRequest = NodeRequest & {
   permdock?: PermDock;
   permdockData?: unknown;
 };
-type NestPermDockOptions<TUser = unknown> = {
-  readonly subject: (req: NestRequest) => TUser | Promise<TUser>;
-  readonly tenant?: TenantOption<NestRequest>;
-  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;
-  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
-  readonly otel?: OtelWrap;
-  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
-  readonly webBotAuth?: WebBotAuthVerifier;
+type NestPermDockOptions<TUser = unknown> = ServerAdapterOptions<NestRequest, TUser> & {
   /**
    * Maps a `ws`, `rpc` or `graphql` context to the request its subject comes
    * from. Without it, a protected handler outside HTTP is denied.
@@ -55,13 +33,20 @@ type NestSocket = {
   disconnect?(close?: boolean): unknown;
   close?(code?: number, reason?: string): unknown;
 };
-type NestProtect = (permission: Permission, loadData?: (req: NestRequest) => unknown, protectOptions?: ProtectOptions) => ClassDecorator & MethodDecorator;
+/** `Protect(null, loadData?, { oauthScopes })` needs a principal and one of the OAuth scopes, but no permission. */
+type NestProtect = (permission: Permission | null, loadData?: (req: NestRequest) => unknown, protectOptions?: ProtectOptions) => ClassDecorator & MethodDecorator;
 type NestHandlerOptions = {
   /** Controller path; may hold route params such as `:org`. Default `api/permdock`. */
   readonly path?: string;
 };
+type PermDockModuleOptions = {
+  /** `"global"` registers `PermDockGuard` as `APP_GUARD`, so every `Protect` rule runs without `UseGuards`. */
+  readonly guard?: "global";
+};
 type NestPermDock = {
-  readonly PermDockModule: Type<unknown>;
+  readonly PermDockModule: Type<unknown> & {
+    readonly forRoot: (options?: PermDockModuleOptions) => DynamicModule;
+  };
   readonly PermDockGuard: Type<CanActivate>;
   readonly Protect: NestProtect;
   readonly InjectPermDock: () => ParameterDecorator;
@@ -77,4 +62,14 @@ type NestPermDock = {
 };
 export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: NestPermDockOptions<TUser>): NestPermDock;
 //#endregion
-export { InvalidSignatureError, type NestHandlerOptions, type NestPermDock, type NestPermDockOptions, type NestProtect, type NestRequest, type NestSocket, discoverViaSignatureAgent, sendResponse, verifyWebBotAuth };
+//#region src/nest/decorate.d.ts
+/**
+ * Applies method decorators to `cls.prototype[key]` without decorator syntax,
+ * for projects limited to erasable TypeScript. Decorators apply in the order
+ * given; each sees the descriptor the previous one left.
+ */
+export declare function decorateMethod(cls: {
+  readonly prototype: object;
+}, key: string, ...decorators: readonly MethodDecorator[]): void;
+//#endregion
+export { InvalidSignatureError, type NestHandlerOptions, type NestPermDock, type NestPermDockOptions, type NestProtect, type NestRequest, type NestSocket, type PermDockModuleOptions, discoverViaSignatureAgent, sendResponse, verifyWebBotAuth };

package/dist/nest/index.js

@@ -1,12 +1,28 @@
 import { t as compact } from "../compact-y6vfu2_f.js";
-import { i as PermDockValidationError, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } 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 { i as onRevoked, t as POLICY_VIOLATION } from "../stream-Q_xlB6Ko.js";
-import { i as toRequest$1, n as isServerResponse, r as sendResponse } from "../http-GgVApX1k.js";
+import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
+import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "../errors-Cz5zn0mW.js";
+import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-tz6D9A2G.js";
+import { t as problemFromError } from "../map-error-pgUWNNtG.js";
+import { a as socketConnection, r as bindKernel } from "../bind-VnYn2HKq.js";
+import { i as onRevoked, t as POLICY_VIOLATION } from "../stream-DDpvynSB.js";
+import { i as toRequest$1, n as isServerResponse, r as sendResponse } from "../http-BIhmLfCc.js";
 import { Catch, Controller, Get, Inject, Injectable, Module, Post, Req, Res, createParamDecorator } from "@nestjs/common";
-import { APP_FILTER, Reflector } from "@nestjs/core";
+import { APP_FILTER, APP_GUARD, Reflector } from "@nestjs/core";
+//#region src/nest/decorate.ts
+/**
+* Applies method decorators to `cls.prototype[key]` without decorator syntax,
+* for projects limited to erasable TypeScript. Decorators apply in the order
+* given; each sees the descriptor the previous one left.
+*/
+function decorateMethod(cls, key, ...decorators) {
+	for (const decorator of decorators) {
+		const descriptor = Object.getOwnPropertyDescriptor(cls.prototype, key);
+		if (descriptor === void 0) throw new TypeError(`decorateMethod: ${key} is not a method of the class`);
+		const next = decorator(cls.prototype, key, descriptor);
+		if (next !== void 0) Object.defineProperty(cls.prototype, key, next);
+	}
+}
+//#endregion
 //#region src/nest/http.ts
 function isReadable(value) {
 	return typeof value === "object" && value !== null && typeof value.read === "function";
@@ -54,17 +70,28 @@ function reflectMeta() {
 	if (typeof ref.getMetadata !== "function" || typeof ref.defineMetadata !== "function") throw new TypeError("reflect-metadata is required for permdock/nest");
 	return ref;
 }
-function applyMethod(cls, key, decorator) {
-	const descriptor = Object.getOwnPropertyDescriptor(cls.prototype, key);
-	if (descriptor === void 0) throw new TypeError(`missing ${key} handler`);
-	decorator(cls.prototype, key, descriptor);
-}
 function applyParameter(cls, key, index, decorator) {
 	decorator(cls.prototype, key, index);
 }
 function hasEmit(value) {
 	return typeof value === "object" && value !== null && typeof value.emit === "function";
 }
+/** One call per loader for a request, so class and method rules naming the same loader share its row. */
+function loadsFor(req) {
+	const loaded = /* @__PURE__ */ new Map();
+	return (loader) => {
+		if (loader === void 0) return;
+		return () => {
+			if (req === void 0) return Promise.resolve(void 0);
+			let hit = loaded.get(loader);
+			if (hit === void 0) {
+				hit = Promise.resolve(loader(req));
+				loaded.set(loader, hit);
+			}
+			return hit;
+		};
+	};
+}
 function rulesOf(target) {
 	const found = reflectMeta().getMetadata(PROTECT_KEY, target);
 	if (!Array.isArray(found)) return [];
@@ -84,73 +111,34 @@ const Protect = (permission, loadData, protectOptions) => {
 	});
 };
 function createPermDock(policy, options) {
-	const contexts = /* @__PURE__ */ new WeakMap();
-	const bound = /* @__PURE__ */ new WeakMap();
-	const kernel = createKernel(policy, compact({
-		subject: (request) => {
-			const req = contexts.get(request);
-			return req === void 0 ? null : options.subject(req);
-		},
-		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: "nest",
-		wrap: options.otel
-	}));
-	const scopeOf = (req) => tenantScope(options.tenant, req);
-	const applyProtect = async (remaining, req, request, scope) => {
+	const { kernel, bind, rebind, scopeOf, handlerScope } = bindKernel(policy, options, "nest", toRequest);
+	const applyProtect = async (remaining, req, request, scope, load) => {
 		const [rule, ...rest] = remaining;
 		if (rule === void 0) return;
-		const loader = rule.loadData;
-		const guard = await kernel.protect(rule.permission, loader === void 0 ? void 0 : () => loader(req), rule.options)(request, scope);
+		const guard = await kernel.protect(rule.permission, load(rule.loadData), rule.options)(request, scope);
 		if (!guard.ok) throw new PermDockHttpError(guard.response);
 		req.permdock = guard.permdock;
 		req.permdockData = guard.data;
-		await applyProtect(rest, req, request, scope);
-	};
-	const bind = (req) => {
-		const hit = bound.get(req);
-		if (hit !== void 0) return hit;
-		const request = toRequest(req);
-		bound.set(req, request);
-		contexts.set(request, req);
-		return request;
+		await applyProtect(rest, req, request, scope, load);
 	};
 	const sockets = /* @__PURE__ */ new WeakMap();
-	const connection = (client, req, connectionOptions) => {
-		const hit = sockets.get(client);
-		if (hit !== void 0) return hit;
-		const opened = (async () => {
-			const conn = await kernel.connection(bind(req), connectionOptions, await scopeOf(req));
-			onRevoked(conn, (problem) => {
-				client.emit?.("permdock:error", problem);
-				if (typeof client.disconnect === "function") client.disconnect(true);
-				else client.close?.(POLICY_VIOLATION, problem.type);
-			});
-			return conn;
-		})();
-		sockets.set(client, opened);
-		return opened;
-	};
-	/** Decides each rule for a gateway message against the client's connection. */
+	const connection = (client, req, connectionOptions) => socketConnection(sockets, client, async () => {
+		const conn = await kernel.connection(bind(req), connectionOptions, await scopeOf(req));
+		onRevoked(conn, (problem) => {
+			client.emit?.("permdock:error", problem);
+			if (typeof client.disconnect === "function") client.disconnect(true);
+			else client.close?.(POLICY_VIOLATION, problem.type);
+		});
+		return conn;
+	});
+	/** Decides each rule for a gateway message against the client's connection, as `protect` does for HTTP. */
 	const checkMessage = async (rules, conn, req) => {
+		const request = req === void 0 ? void 0 : bind(req);
+		const load = loadsFor(req);
 		for (const rule of rules) {
-			const loader = rule.loadData;
-			let data;
-			if (loader !== void 0) {
-				data = req === void 0 ? void 0 : await loader(req);
-				if (data === null || data === void 0) throw new PermDockHttpError(new Response(null, { status: 404 }));
-			}
-			const decision = conn.check(rule.permission, data, rule.options?.trusted === true ? { trusted: true } : void 0);
-			if (decision.outcome !== "granted") throw new PermDockHttpError(kernel.problem(decision, { permission: rule.permission }));
+			if (conn.signal.aborted) throw conn.signal.reason instanceof PermDockRevokedError ? conn.signal.reason : new PermDockRevokedError({ code: "denied" });
+			const guard = await kernel.protectOn(conn.permdock, rule.permission, load(rule.loadData), rule.options, request);
+			if (!guard.ok) throw new PermDockHttpError(guard.response);
 		}
 	};
 	class PermDockGuard {
@@ -172,7 +160,7 @@ function createPermDock(policy, options) {
 			const request = bind(req);
 			const scope = await scopeOf(req);
 			req.permdock = await kernel.permdock(request, scope);
-			await applyProtect(rules, req, request, scope);
+			await applyProtect(rules, req, request, scope, loadsFor(req));
 			return true;
 		}
 		rulesFor(context) {
@@ -186,7 +174,7 @@ function createPermDock(policy, options) {
 	class PermDockExceptionFilter {
 		send = sendNestResponse;
 		async catch(exception, host) {
-			const problem = exception instanceof PermDockHttpError ? exception.response : problemFromError(exception);
+			const problem = exception instanceof PermDockHttpError ? exception.response : problemFromError(exception, { credentials: host.getType() === "http" && host.switchToHttp().getRequest().headers.authorization !== void 0 });
 			if (problem === void 0) throw new TypeError("unhandled permdock exception");
 			if (host.getType() === "http") {
 				await this.send(host.switchToHttp().getResponse(), problem);
@@ -202,10 +190,18 @@ function createPermDock(policy, options) {
 			});
 		}
 	}
-	Catch(PermDockHttpError, InvalidSignatureError, PermDockDeniedError, PermDockApprovalRequiredError, PermDockValidationError)(PermDockExceptionFilter);
+	Catch(PermDockHttpError, InvalidSignatureError, PermDockDeniedError, PermDockApprovalRequiredError, PermDockRevokedError, PermDockValidationError)(PermDockExceptionFilter);
 	Injectable()(PermDockExceptionFilter);
 	class PermDockRoot {
-		static adapter = "nest";
+		static forRoot(moduleOptions = {}) {
+			return {
+				module: PermDockRoot,
+				providers: moduleOptions.guard === "global" ? [{
+					provide: APP_GUARD,
+					useExisting: PermDockGuard
+				}] : []
+			};
+		}
 	}
 	Module({
 		providers: [
@@ -231,24 +227,19 @@ function createPermDock(policy, options) {
 	});
 	const InjectPermDock = () => injectPermDock();
 	const permdockHandler = (handlerOptions = {}) => {
-		const { POST, GET } = kernel.permdockHandler((request) => {
-			const req = contexts.get(request);
-			return req === void 0 ? { tenant: void 0 } : scopeOf(req);
-		});
+		const { POST, GET } = kernel.permdockHandler(handlerScope);
 		class EvaluationsController {
 			send = sendNestResponse;
 			async post(req, res) {
-				const request = toRequest(req);
-				contexts.set(request, req);
-				await this.send(res, await POST(request));
+				await this.send(res, await POST(rebind(req)));
 			}
 			async get(req, res) {
 				await this.send(res, await GET(bind(req)));
 			}
 		}
 		Controller(handlerOptions.path ?? "api/permdock")(EvaluationsController);
-		applyMethod(EvaluationsController, "post", Post());
-		applyMethod(EvaluationsController, "get", Get());
+		decorateMethod(EvaluationsController, "post", Post());
+		decorateMethod(EvaluationsController, "get", Get());
 		applyParameter(EvaluationsController, "post", 0, Req());
 		applyParameter(EvaluationsController, "post", 1, Res({ passthrough: false }));
 		applyParameter(EvaluationsController, "get", 0, Req());
@@ -267,4 +258,4 @@ function createPermDock(policy, options) {
 	};
 }
 //#endregion
-export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendResponse, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, createPermDock, decorateMethod, discoverViaSignatureAgent, sendResponse, toRequest, verifyWebBotAuth };

package/dist/next/client.d.ts

@@ -1,15 +1,13 @@
-import { t as PermDockDigest } from "../digest-B3kc_PgQ.js";
+import { t as PermissionBoundaryState } from "../boundary-BmHxVH1J.js";
 import { ComponentType, ReactNode } from "react";
 //#region src/next/client.d.ts
-export type PermissionBoundaryState = PermDockDigest & {
-  /** Re-fetches and re-renders the boundary's children, e.g. after an approval or a role change. */
-  readonly retry: () => void;
-};
+/** A fallback node, or a function of what was refused. */
+export type PermissionBoundaryFallback = ReactNode | ((state: PermissionBoundaryState) => ReactNode);
 export type PermissionBoundaryProps = {
   /** Rendered in place of the children when one throws `PermDockDeniedError`. */
-  readonly denied?: ReactNode;
+  readonly denied?: PermissionBoundaryFallback;
   /** Rendered when a child throws `PermDockApprovalRequiredError`; defaults to `denied`. */
-  readonly approval?: ReactNode;
+  readonly approval?: PermissionBoundaryFallback;
 };
 /**
  * A component-level boundary for PermDock errors thrown below it, in a Server
@@ -21,4 +19,5 @@ export declare const PermissionBoundary: ComponentType<PermissionBoundaryProps &
 }>;
 /** Inside a `PermissionBoundary` fallback: what was refused, and `retry()`. */
 export declare function usePermissionBoundary(): PermissionBoundaryState | null;
-//#endregion
+//#endregion
+export type { PermissionBoundaryState };

package/dist/next/client.js

@@ -1,20 +1,22 @@
 "use client";
-import { r as parsePermDockDigest } from "../digest-BI-6aa6d.js";
+import { n as boundaryFallback, t as boundaryDigest } from "../boundary-BM8a_P6E.js";
 import { createContext, useContext } from "react";
 import { jsx } from "react/jsx-runtime";
-import { catchError } from "next/error";
+import * as nextError from "next/error.js";
 //#region src/next/client.tsx
+const catchError = nextError.catchError ?? nextError.default.catchError;
 const BoundaryContext = createContext(null);
 function PermissionFallback(props, info) {
-	const parsed = parsePermDockDigest(info.error.digest);
+	const parsed = boundaryDigest(info.error);
 	if (parsed === null) throw info.error;
-	const node = parsed.outcome === "approval-required" ? props.approval ?? props.denied : props.denied;
+	const fallback = boundaryFallback(parsed, props);
+	const state = {
+		...parsed,
+		retry: info.retry
+	};
 	return /* @__PURE__ */ jsx(BoundaryContext.Provider, {
-		value: {
-			...parsed,
-			retry: info.retry
-		},
-		children: node ?? null
+		value: state,
+		children: typeof fallback === "function" ? fallback(state) : fallback ?? null
 	});
 }
 /**

package/dist/next/index.d.ts

@@ -1,47 +1,17 @@
-import { $ as DecisionSink, C as Policy, E as PolicyVocabulary, Mn as Decision, Zt as PermDock, 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 { o as OtelWrap } from "../types-B9dmiiab.js";
+import { C as Policy, D as PolicyVocabulary, Nr as Principal, Tt as Snapshot, Yn as Decision, ln as PermDock } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
+import { o as OtelWrap } from "../types-vNSDF7Dq.js";
+import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-DwQH8ufx.js";
 import { ReactElement, ReactNode } from "react";
-//#region src/next/cache-life.d.ts
-type CacheLifeForOptions = {
-  /** Lower bound in seconds. Next.js includes a private entry in per-link prefetches from 30. */
-  readonly min?: number;
-  /** Upper bound in seconds. Next.js keeps a per-session App Shell entry from 300. */
-  readonly max?: number;
-  /** Seconds since the epoch; defaults to the snapshot's `issuedAt`, then the clock. */
-  readonly now?: number;
-};
-/**
- * `{ stale }` for `cacheLife()` inside an app-owned `'use cache: private'` function: `max` when the
- * value never expires, otherwise the seconds left, clamped to `[min, max]`. A value with less than
- * `min` seconds left gets its real remainder, so Next.js leaves it out of prefetches instead of
- * serving it past `expiresAt`.
- */
-export declare function cacheLifeFor(value: {
-  readonly expiresAt?: number | null;
-  readonly issuedAt?: number;
-} | null, options?: CacheLifeForOptions): {
-  readonly stale: number;
-};
-//#endregion
 //#region src/next/types.d.ts
 type NextSubjectInput = unknown;
-type NextPermDockOptions<TUser = NextSubjectInput> = {
+type NextPermDockOptions<TUser = NextSubjectInput> = InstanceOptions & {
   readonly subject: () => TUser | Promise<TUser>;
   readonly tenant?: string | (() => string | undefined | Promise<string | undefined>);
   readonly onDenied?: (decision: Decision) => never | void;
-  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;
-  readonly snapshots?: SnapshotSource;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
   /**
@@ -54,6 +24,14 @@ type NextPermDockOptions<TUser = NextSubjectInput> = {
 type GetPermDockQuery = {
   readonly tenant?: string;
 };
+type GetSnapshotQuery = GetPermDockQuery & {
+  readonly include?: readonly (Permission | {
+    readonly [key: string]: unknown;
+  })[];
+  readonly tenants?: "all";
+  /** Tags added next to `snapshotTag(sub)`, such as the app's own organisation tag. */
+  readonly tags?: readonly string[];
+};
 type RequireAccessInput = {
   readonly permission: Permission;
   /** The row for an instance permission; omit it for a collection permission. */
@@ -75,6 +53,8 @@ type ServerPermDockProviderProps = {
   readonly tenants?: "all";
   /** Overrides the factory's `endpoint`; `false` is snapshot-only. */
   readonly endpoint?: string | false;
+  /** Suspends permission readers until the snapshot streams in, instead of answering `pending`. */
+  readonly suspend?: boolean;
 };
 type PermDockHandler = {
   readonly POST: (request: Request) => Promise<Response>;
@@ -82,7 +62,18 @@ type PermDockHandler = {
 };
 type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   readonly getPermDock: (query?: GetPermDockQuery) => Promise<PermDock<V>>;
-  readonly getPermission: (permission: Permission, data?: unknown) => Promise<ServerPermissionState>;
+  /**
+   * `{ allowed, status: 'ready', decision }`. Any failure to build the
+   * instance denies; Next.js interrupts (`redirect()`, `notFound()`,
+   * request-time bailouts) from `subject` or `tenant` pass through.
+   */
+  readonly getPermission: (permission: Permission, data?: unknown, query?: GetPermDockQuery) => Promise<ServerPermissionState>;
+  /**
+   * The session's snapshot for a `'use cache: private'` function the app owns:
+   * calls `cacheLife(cacheLifeFor(snapshot))` and `cacheTag(snapshotTag(sub), ...tags)`
+   * in that scope, and throws outside one.
+   */
+  readonly getSnapshot: (query?: GetSnapshotQuery) => Promise<Snapshot>;
   /**
    * Resolves to the granted `Decision`. A denial calls `unauthorized()` for an
    * anonymous subject and `forbidden()` otherwise (`experimental.authInterrupts`);
@@ -99,12 +90,4 @@ type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
 //#region src/next/create.d.ts
 export declare function createPermDock<TUser = NextSubjectInput, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: NextPermDockOptions<TUser>): NextPermDock<V>;
 //#endregion
-//#region src/next/snapshot-tag.d.ts
-/**
- * The `cacheTag` for one subject's cached snapshots: `permdock:<sub>`, or `permdock:anon`
- * without a subject. Tag the private cache with it and pass it to `updateTag` or
- * `revalidateTag` on every write that changes the subject's snapshot.
- */
-export declare function snapshotTag(sub?: string | null): string;
-//#endregion
-export type { CacheLifeForOptions, GetPermDockQuery, NextPermDock, NextPermDockOptions, PermDockHandler, RequireAccessInput, ServerPermDockProviderProps, ServerPermissionState };
+export { type CacheLifeForOptions, type GetPermDockQuery, type GetSnapshotQuery, type NextPermDock, type NextPermDockOptions, type PermDockHandler, type RequireAccessInput, type ServerPermDockProviderProps, type ServerPermissionState, type SnapshotHeaders, type SnapshotHeadersOptions, cacheLifeFor, snapshotHeaders, snapshotTag };