permdock 0.4.0 → 0.6.0

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

@@ -1,7 +1,8 @@
-import { Dr as Membership, Mt as PermDockOptions, Or as Principal, Sr as CustomRole, Y as LimitStore, kr as Subject, tt as RelationSource, vr as Actor, wr as Delegation } from "../../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../../permission-types-Dg39z9Kv.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-COH-KRgT.js";
-import { n as saasPolicy, t as SAAS_API_KEY_LIMIT } from "../../policy-ur0BBK_e.js";
+import { $n as Delegation, Q as LimitStore, Rt as Instant, Zn as CustomRole, ar as Subject, it as RelationSource, nr as Membership, qn as Actor, rr as Principal } from "../../policy-types-n0uRTsW8.js";
+import { w as Permission } from "../../vocabulary-CN8H_9UF.js";
+import { i as PermDockOptions } from "../../permdock-SV8ZINYT.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-u_KHg-sN.js";
+import { n as saasPolicy, t as SAAS_API_KEY_LIMIT } from "../../policy-77FSAq_V.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/testing/saas/schema.d.ts
 type FieldKind = "string" | "boolean" | "nullable-string";
@@ -121,8 +122,8 @@ 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;
+  /** The instant used for `iat`; defaults to the current time. */
+  readonly now?: Instant;
   readonly issuer?: string;
   readonly audience?: string;
   readonly claims?: Readonly<Record<string, unknown>>;
@@ -134,9 +135,9 @@ export declare function signSaasToken(sub: string, options?: SaasTokenOptions):
  * 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>;
+export declare function verifySaasToken(token: string | null | undefined, now?: Instant): Promise<string | null>;
 /** `verifySaasToken` plus the token's `exp` as `expiresAt` (epoch seconds). */
-export declare function verifySaasSession(token: string | null | undefined, now?: number): Promise<{
+export declare function verifySaasSession(token: string | null | undefined, at?: Instant): Promise<{
   readonly sub: string;
   readonly expiresAt: number;
 } | null>;

package/dist/testing/saas/index.js

@@ -1,3 +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-CCJ6lmxB.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-DtaA4JuW.js";
+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-BPxlwVhN.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-BCXRuXca.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

@@ -1,2 +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-COH-KRgT.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-u_KHg-sN.js";
 export { SaasDoc, SaasDocSchema, SaasFolder, SaasFolderSchema, SaasProject, SaasProjectSchema, saasPermissions, saasPlans, saasRoles, saasTenantRoleNames };

package/dist/testing/saas/permissions.js

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

package/dist/text-BMFRfBqc.js

@@ -0,0 +1,8 @@
+//#region src/cli/shared/text.ts
+/** The text before the first `separator`, or all of it when there is none. */
+function beforeFirst(text, separator) {
+	const at = text.indexOf(separator);
+	return at === -1 ? text : text.slice(0, at);
+}
+//#endregion
+export { beforeFirst as t };

package/dist/{text-diff-BdkkYSbi.js → text-diff-BQcUapOb.js}

@@ -1,5 +1,5 @@
 import { createTwoFilesPatch } from "diff";
-//#region src/cli/text-diff.ts
+//#region src/cli/core/text-diff.ts
 const MAX_LINES = 40;
 /**
 * A unified diff from the file on disk to what the command would write,

package/dist/thenable-yD7SabqG.js

@@ -0,0 +1,31 @@
+import { r as isRecord } from "./compact-CAf557ZB.js";
+//#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);
+}
+/** Runs a Standard Schema that must answer synchronously; an asynchronous answer fails. */
+function validateSync(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (isThenable(result)) {
+		ignoreRejection(result);
+		return { ok: false };
+	}
+	return result.issues === void 0 ? {
+		ok: true,
+		value: result.value
+	} : {
+		ok: false,
+		issues: result.issues
+	};
+}
+/** `validateSync` for a schema whose output must be an object; anything else is `undefined`. */
+function validateRecord(schema, value) {
+	const validated = validateSync(schema, value);
+	return validated.ok && isRecord(validated.value) ? validated.value : void 0;
+}
+//#endregion
+export { validateSync as i, isThenable as n, validateRecord as r, ignoreRejection as t };

package/dist/time-DkWjdL98.js

@@ -0,0 +1,71 @@
+//#region src/core/time.ts
+/** RFC 3339 `date-time` in UTC or with an offset; fractional seconds optional. */
+const RFC3339_PATTERN = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$";
+const RFC3339 = /* @__PURE__ */ new RegExp(RFC3339_PATTERN, "u");
+function isRfc3339(value) {
+	return typeof value === "string" && RFC3339.test(value) && Number.isFinite(Date.parse(value));
+}
+/** Seconds since the epoch as RFC 3339 in UTC. */
+function rfc3339(seconds) {
+	return (/* @__PURE__ */ new Date(seconds * 1e3)).toISOString();
+}
+/** Milliseconds since the epoch as RFC 3339 in UTC, milliseconds kept; throws a `RangeError` for a value outside the `Date` range. */
+function isoAt(millis) {
+	return new Date(millis).toISOString();
+}
+/** RFC 3339 in UTC of `now`, or of the clock when absent; throws a `RangeError` for a `now` that is not an `Instant`. */
+function isoNow(now) {
+	return dateAt(now).toISOString();
+}
+/** Whole seconds since the epoch of an RFC 3339 instant; `undefined` for anything else. */
+function secondsOf(value) {
+	return isRfc3339(value) ? Math.floor(Date.parse(value) / 1e3) : void 0;
+}
+/** Whole seconds since the epoch of an RFC 3339 string or an `Instant`; `undefined` for anything else, Unix seconds included. */
+function instantOf(value) {
+	if (typeof value === "string") return secondsOf(value);
+	if (typeof value === "object" && value !== null && "epochMilliseconds" in value && typeof value.epochMilliseconds === "number" && Number.isFinite(value.epochMilliseconds)) return Math.floor(value.epochMilliseconds / 1e3);
+}
+/** A duration: a whole number of seconds above zero, else `undefined`. */
+function durationOf(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : void 0;
+}
+/** Throws at definition time unless `value` is a whole number of seconds above zero. */
+function assertDuration(value, label) {
+	if (durationOf(value) === void 0) throw new Error(`PermDock: ${label} must be a whole number of seconds above 0, got ${JSON.stringify(value) ?? String(value)}`);
+}
+/** Whole seconds since the epoch of `now`, or of the clock when absent. */
+function nowSeconds(now) {
+	return Math.floor(nowMillis(now) / 1e3);
+}
+/** The `validation` denial detail for a `now` option that is not an `Instant`. */
+const INVALID_NOW = Object.freeze({
+	field: "now",
+	message: "now must be an Instant ({ epochMilliseconds }), such as a Temporal.Instant"
+});
+/** The `Date` of `now`, or of the clock when absent; throws a `RangeError` for a `now` that is not an `Instant`. */
+function dateAt(now) {
+	const millis = nowMillis(now);
+	if (!Number.isFinite(millis)) throw new RangeError(`PermDock: ${INVALID_NOW.message}`);
+	return new Date(millis);
+}
+/** Whole seconds since the epoch of `now`, or of the clock when absent; throws a `RangeError` for a `now` that is not an `Instant`. */
+function secondsAt(now) {
+	return Math.floor(dateAt(now).getTime() / 1e3);
+}
+/** The instant `seconds` after the epoch. */
+function instantAt(seconds) {
+	return { epochMilliseconds: seconds * 1e3 };
+}
+/** Seconds since the epoch of `now`, fraction kept, or of the clock when absent. */
+function epochSeconds(now) {
+	return nowMillis(now) / 1e3;
+}
+/** Milliseconds since the epoch of `now`, or of the clock when absent; `NaN` for a `now` that is not an `Instant`. */
+function nowMillis(now) {
+	if (now === void 0) return Date.now();
+	const millis = typeof now === "object" && now !== null ? now.epochMilliseconds : void 0;
+	return typeof millis === "number" ? millis : NaN;
+}
+//#endregion
+export { durationOf as a, instantOf as c, isoNow as d, nowMillis as f, secondsOf as g, secondsAt as h, dateAt as i, isRfc3339 as l, rfc3339 as m, RFC3339_PATTERN as n, epochSeconds as o, nowSeconds as p, assertDuration as r, instantAt as s, INVALID_NOW as t, isoAt as u };

package/dist/{token-Bx9qy30p.js → token-BLZcjQgt.js}

@@ -1,5 +1,5 @@
-import { t as canonicalJson } from "./canonical-json-CFKyFOke.js";
-import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
+import { r as sha256Digest } from "./sha256-D9ihqmvd.js";
 //#region src/core/token.ts
 /**
 * Only stable identity goes into the token, so refreshing a session (new
@@ -22,7 +22,16 @@ function versionOf(row, field) {
 }
 /** The digest that binds a token to the call's data when no row id does. */
 function payloadDigest(data) {
-	return bytesToBase64Url(sha256(canonicalJson(data)));
+	return sha256Digest(canonicalJson(data));
+}
+/**
+* The payload a decision token binds: the call's `args` when the caller
+* passes them (an agent or MCP tool call, row or not), otherwise the data of
+* a call without a row id. `undefined` binds nothing beyond the row id.
+*/
+function tokenPayload(resourceId, data, args) {
+	if (args !== void 0) return payloadDigest(args);
+	return resourceId === "*" && data !== void 0 ? payloadDigest(data) : void 0;
 }
 /**
 * `version` is set only for an approval that goes stale on a resource
@@ -32,7 +41,7 @@ function payloadDigest(data) {
 * others.
 */
 function decisionToken(input) {
-	const payload = JSON.stringify({
+	const payload = canonicalJson({
 		key: input.key,
 		resourceId: input.resourceId,
 		principal: principalIdentity(input.principal),
@@ -44,7 +53,7 @@ function decisionToken(input) {
 		...input.version === void 0 ? {} : { version: input.version },
 		...input.payload === void 0 ? {} : { payload: input.payload }
 	});
-	return `pd1.${bytesToBase64Url(sha256(payload))}`;
+	return sha256Digest(payload);
 }
 //#endregion
-export { payloadDigest as n, versionOf as r, decisionToken as t };
+export { versionOf as i, payloadDigest as n, tokenPayload as r, decisionToken as t };

package/dist/{tool-refusal-CQ7OEia9.js → tool-refusal-CMLN5xhn.js}

@@ -1,5 +1,5 @@
-import { a as wireDenials } from "./problem-details-DECUnXAn.js";
-import { t as describe } from "./describe-Cgkp7eP0.js";
+import { t as wireDenials } from "./wire-denial-C7PaVYEM.js";
+import { t as describe } from "./describe-BybMRY7A.js";
 //#region src/core/tool-refusal.ts
 function deniedToolRefusal(decision, permission, resource) {
 	const alternatives = decision.alternatives.map((leaf) => leaf.key);

package/dist/trpc/index.d.ts

@@ -1,9 +1,10 @@
-import { E as Policy, Or as Principal } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
-import { A as ConnectionOptions, O as Connection, i as OpenApiHooks } from "../server-types-DdqBwZN_.js";
-import { t as ServerAdapterOptions } from "../bind-BzqG8SMb.js";
-import { t as StreamProtectOptions } from "../stream-Dwsg6WwE.js";
+import { T as Policy, rr as Principal } from "../policy-types-n0uRTsW8.js";
+import { w as Permission } from "../vocabulary-CN8H_9UF.js";
+import { r as PermDock } from "../permdock-SV8ZINYT.js";
+import { n as RevocationFeed } from "../revocations-R07lFBnX.js";
+import { D as ConnectionOptions, T as Connection, i as OpenApiHooks } from "../server-types-CKQiCnON.js";
+import { t as ServerAdapterOptions } from "../bind-DOyrv6zi.js";
+import { t as StreamProtectOptions } from "../stream-CeCMJmBB.js";
 import { AnyTRPCMiddlewareFunction } from "@trpc/server";
 //#region src/trpc/create.d.ts
 type TrpcMiddlewareOpts<TCtx = object, TInput = unknown> = {
@@ -33,11 +34,13 @@ type TrpcOpenApiHooks = {
   readonly securitySchemes: OpenApiHooks["securitySchemes"];
 };
 type TrpcPermDock<TCtx = object> = {
-  readonly permdock: () => TrpcMiddleware;
-  readonly protect: (permission: Permission | null, loadData?: (opts: TrpcMiddlewareOpts<TCtx>) => unknown, protectOptions?: StreamProtectOptions) => TrpcMiddleware;
+  /** The `PermDock` for one procedure call, for code the middleware does not run before. */
+  readonly getPermDock: (opts: TrpcMiddlewareOpts<TCtx>) => Promise<PermDock>;
+  readonly middleware: () => TrpcMiddleware;
+  readonly protect: (permission: Permission | null, data?: (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 permdockHandler: () => (request: Request) => Promise<Response>;
   readonly openapi: TrpcOpenApiHooks;
   readonly errorFormatter: <TShape extends {
     readonly data: object;

package/dist/trpc/index.js

@@ -1,8 +1,8 @@
 import { o as problemMessage } from "../http-BBoKefeS.js";
-import { t as problemFromError } from "../map-error-BE27PYkE.js";
-import { n as attached } from "../bind-kk-uyCwH.js";
-import { a as reloadAfter, r as isAsyncIterable } from "../stream-BMui98KK.js";
-import { i as rpcCode, n as guardStream, r as problemBody, t as bindRpcKernel } from "../rpc-nYC3cR_u.js";
+import { t as problemFromError } from "../map-error-Dr70oA_3.js";
+import { n as attached } from "../bind-CAvgUuKs.js";
+import { i as isAsyncIterable, o as reloadAfter } from "../stream-CvdUS9V1.js";
+import { i as rpcCode, n as guardStream, r as problemBody, t as bindRpcKernel } from "../rpc-VSl5ylaQ.js";
 import { TRPCError, isTrackedEnvelope } from "@trpc/server";
 //#region src/trpc/create.ts
 const PROBLEM = Symbol.for("permdock.problem");
@@ -58,9 +58,10 @@ function errorFormatter(opts) {
 }
 function createPermDock(policy, options) {
 	const { kernel, bind, attach, scopeOf, connection, evaluate, guard: runGuard } = bindRpcKernel(policy, options, "trpc", (opts) => opts.ctx, (opts) => opts.path);
-	const permdock = () => (async (opts) => {
+	const getPermDock = async (opts) => kernel.getPermDock(bind(opts), await scopeOf(opts));
+	const middleware = () => (async (opts) => {
 		const request = bind(opts);
-		const instance = await attached(async () => kernel.permdock(request, await scopeOf(opts)));
+		const instance = await attached(async () => kernel.getPermDock(request, await scopeOf(opts)));
 		if (!instance.ok) return throwTrpcError(instance.response);
 		const nextCtx = {
 			...opts.ctx,
@@ -70,18 +71,18 @@ function createPermDock(policy, options) {
 		return mapDownstream(await opts.next({ ctx: nextCtx }));
 	});
 	/** Wraps a subscription's iterable so revocation ends it and unreadable items drop. */
-	const guardSubscription = async (result, opts, permission, loadData, protectOptions) => {
+	const guardSubscription = async (result, opts, permission, data, protectOptions) => {
 		if (result === null || typeof result !== "object" || result.ok !== true || !isAsyncIterable(result.data)) return result;
 		return {
 			...result,
-			data: await guardStream(result.data, (connectionOptions) => connection(opts, connectionOptions), permission, loadData, protectOptions, {
+			data: await guardStream(result.data, (connectionOptions) => connection(opts, connectionOptions), permission, data, protectOptions, {
 				unwrap: (item) => isTrackedEnvelope(item) ? item[1] : item,
 				onRevoked: trpcErrorFrom
 			})
 		};
 	};
-	const protect = (permission, loadData, protectOptions) => (async (opts) => {
-		const { request, guard } = await runGuard(permission, loadData, opts, protectOptions);
+	const protect = (permission, data, protectOptions) => (async (opts) => {
+		const { request, guard } = await runGuard(permission, data, opts, protectOptions);
 		if (guard.ok) {
 			const nextCtx = {
 				...opts.ctx,
@@ -89,11 +90,11 @@ function createPermDock(policy, options) {
 				permdockData: guard.data
 			};
 			attach(nextCtx, request);
-			return guardSubscription(await mapDownstream(await opts.next({ ctx: nextCtx })), opts, permission, loadData === void 0 ? void 0 : reloadAfter(guard.data, () => loadData(opts)), protectOptions);
+			return guardSubscription(await mapDownstream(await opts.next({ ctx: nextCtx })), opts, permission, data === void 0 ? void 0 : reloadAfter(guard.data, () => data(opts)), protectOptions);
 		}
 		return throwTrpcError(guard.response);
 	});
-	const permdockHandler = (request) => {
+	const handler = (request) => {
 		return evaluate(request, {
 			ctx: { req: request },
 			path: "permdock",
@@ -103,10 +104,11 @@ function createPermDock(policy, options) {
 	};
 	const kernelOpenApi = kernel.openapi;
 	return {
-		permdock,
+		getPermDock,
+		middleware,
 		protect,
 		connection,
-		permdockHandler,
+		permdockHandler: () => handler,
 		openapi: {
 			security: (permission) => ({ openapi: {
 				protect: true,

package/dist/types-8RnwUAvE.d.ts

@@ -0,0 +1,107 @@
+import { ar as Subject, dt as TokenVerifier, ot as SnapshotSource, q as DecisionSink, ut as TokenSigner } from "./policy-types-n0uRTsW8.js";
+import { o as PolicySource } from "./hosted-BPk51-kX.js";
+import { m as ApprovalStore, u as ApprovalRequest } from "./types-BdtSDbBO.js";
+import { a as CatalogDocument } from "./types-Druu9wLM.js";
+import { a as CatalogFinding } from "./sink-4-eQIRWf.js";
+//#region src/cloud/types.d.ts
+type CloudEndpointOptions = {
+  readonly url?: string;
+  readonly environment?: string;
+};
+type CloudEndpoints = {
+  /** The environment URL, `<url>/v1/environments/<env>`: `iss` and `aud` of the policy document. */
+  readonly issuer: string;
+  /** The environment's JWK Set URL, for `joseTokenVerifier({ jwks })`. */
+  readonly jwks: string;
+};
+/** What every `permdock/cloud` client needs to reach one environment. */
+type CloudConnectionOptions = CloudEndpointOptions & {
+  /** The environment key; defaults to `PERMDOCK_CLOUD_KEY`. */
+  readonly key?: string;
+  readonly fetch?: typeof fetch;
+};
+/** Who signs the `PermDock-Approver` token `approvals.resolve` sends. */
+type CloudApproverOptions = {
+  /**
+   * Signs the token with a key the environment trusts as an issuer, such as
+   * `joseTokenSigner` over your own key. Never `cloudSigner`: a client key
+   * that could mint approver tokens could forge any approver.
+   */
+  readonly signer: TokenSigner;
+  /** `aud` of the token; defaults to `<issuer>/approvals`, the environment URL plus `/approvals`. */
+  readonly audience?: string | readonly string[];
+  /**
+   * The `holder(permission)` approvers of `request` that `approver` holds,
+   * typically `approverPermissions(request, permdockFor(approver))`. Signed
+   * into the token as `permissions`; without it the verdict's own
+   * `permissions` are signed. A throw signs none.
+   */
+  readonly permissions?: (request: ApprovalRequest, approver: Subject) => readonly string[] | Promise<readonly string[]>;
+  /**
+   * The relation approvers of `request` that `approver` holds, typically
+   * `approverRelations(request, approver, { relations, permissions })`.
+   * Signed into the token as `relations`; without it the verdict's own
+   * `relations` are signed. A throw signs none.
+   */
+  readonly relations?: (request: ApprovalRequest, approver: Subject) => readonly string[] | Promise<readonly string[]>;
+};
+type CloudOptions = CloudConnectionOptions & {
+  /**
+   * Proves the approver on `approvals.resolve`. Without it, every resolve but
+   * a `system` rejection throws `approver-unauthenticated` and sends nothing.
+   */
+  readonly approver?: CloudApproverOptions;
+  readonly flushAt?: number;
+  /** Most events the sink holds while the Cloud is unreachable (default 10 000); the oldest are dropped first. */
+  readonly capacity?: number;
+  readonly waitUntil?: (task: Promise<void>) => void;
+  /** The CloudEvents `source` of every event the sink sends, an absolute URI; defaults to the environment URL. */
+  readonly source?: string;
+  /**
+   * Verifies the environment's signed policy document, typically
+   * `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`. Without one,
+   * `policies.current()` stays `null`: an unverifiable document is never applied.
+   */
+  readonly verifier?: TokenVerifier;
+};
+/**
+ * What `POST /catalog` answers: `201` with the new version and the drift
+ * findings against the previous one, or `200` with `unchanged: true` when
+ * the fingerprint is already published.
+ */
+type CloudCatalogPush = {
+  readonly version: number;
+  readonly fingerprint: string;
+  readonly findings: readonly CatalogFinding[];
+} | {
+  readonly version: number;
+  readonly fingerprint: string;
+  readonly unchanged: true;
+};
+type CloudCatalog = {
+  /**
+   * Posts the catalog, its `operations` included, to the environment.
+   * Throws when the Cloud refuses it or answers another shape. The Cloud
+   * shows and diffs it; it never decides with it.
+   */
+  push(catalog: CatalogDocument): Promise<CloudCatalogPush>;
+};
+type CloudClient = CloudEndpoints & {
+  readonly approvals: ApprovalStore;
+  readonly sink: DecisionSink;
+  /**
+   * A `SnapshotSource` for the subject `token` proves: an `at+jwt` the
+   * environment issued, or one a trusted issuer registered for `subject`
+   * signed. Sent as `PermDock-Subject`; the Cloud never takes a subject from
+   * anything else.
+   */
+  snapshotsFor(token: string): SnapshotSource;
+  readonly policies: PolicySource;
+  readonly catalog: CloudCatalog;
+};
+type CloudSignerOptions = CloudConnectionOptions & {
+  /** `aud` when a `sign` call names none; signing without either throws. */
+  readonly audience?: string | readonly string[];
+};
+//#endregion
+export { CloudConnectionOptions as a, CloudOptions as c, CloudClient as i, CloudSignerOptions as l, CloudCatalog as n, CloudEndpointOptions as o, CloudCatalogPush as r, CloudEndpoints as s, CloudApproverOptions as t };

package/dist/{store-9KO4BlkB.d.ts → types-B3_ooZgZ.d.ts}

@@ -1,77 +1,7 @@
-import { Or as Principal, an as Snapshot, ir as Decision, j as PolicyVocabulary, jt as PermDock, ut as TokenVerifier, vr as Actor, wr as Delegation } from "./policy-types-sp9P1iIV.js";
-import { d as Permission } from "./permission-types-Dg39z9Kv.js";
-import { n as DescribeMessages } from "./describe-C3ldA9os.js";
-//#region src/client/types.d.ts
-type ClientStatus = "ready" | "pending" | "stale" | "server-only";
-type PermissionState = {
-  readonly allowed: boolean;
-  readonly status: ClientStatus;
-  readonly decision: Decision;
-};
-type PermissionSet = {
-  readonly granted: readonly Permission[];
-  get(permission: Permission): PermissionState | undefined;
-};
-type ClientPermDock<V extends PolicyVocabulary = PolicyVocabulary> = PermDock<V> & {
-  status(permission?: Permission, data?: unknown): ClientStatus;
-  invalidate(ref: Permission | {
-    readonly [key: string]: unknown;
-  }): void;
-  refresh(options?: {
-    readonly tenant?: string;
-  }): Promise<void>;
-  clear(): void;
-  subscribe(listener: () => void): () => void;
-};
-type ApprovalState = "not-needed" | "required" | "pending" | "approved" | "rejected" | "expired";
-type ApprovalHandle = {
-  readonly state: ApprovalState;
-  readonly token: string | undefined;
-  readonly request: (note?: string) => Promise<void>;
-};
-type SubjectView = {
-  readonly principal: Principal | null;
-  readonly actor: Actor | undefined;
-  readonly delegation: Delegation | undefined;
-  readonly expiresAt: number | undefined;
-  readonly simulated: boolean;
-};
-type TenantView = {
-  readonly tenant: string | null;
-  readonly tenants: readonly string[];
-  readonly switchTo: (id: string) => Promise<void>;
-  readonly status: ClientStatus;
-};
-type FilterResult<T> = readonly T[] & {
-  readonly partial: boolean;
-};
-type UseRolesOptions = {
-  readonly tenant?: string;
-  readonly team?: string;
-};
-/** The provider options Vue, Svelte and Solid share; each adds its own reactive `snapshot`, `tenant`, `headers`, `verifier` and `defaults`. */
-type ProviderOptionsBase = {
-  /**
-   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer.
-   * `false` never calls one: such a check is denied with reason `server-only`.
-   */
-  readonly endpoint?: string | false;
-  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
-  readonly snapshotUrl?: string;
-  readonly approvals?: string;
-  /** Read on every request, so a new `fetch` applies without a new store. */
-  readonly fetch?: typeof fetch;
-  readonly maxAge?: number;
-  /** Localised text for the describe helper. */
-  readonly messages?: DescribeMessages;
-  /** Called with each snapshot the store accepts. */
-  readonly onSnapshot?: NonNullable<ClientStoreOptions["onSnapshot"]>;
-  /** Called when the store drops its snapshot. */
-  readonly onClear?: () => void;
-  /** Milliseconds between approval status polls. Defaults to 2000. */
-  readonly approvalInterval?: number;
-};
-//#endregion
+import { $n as Delegation, Nn as Decision, Vt as Snapshot, dt as TokenVerifier, j as PolicyVocabulary, qn as Actor, rr as Principal } from "./policy-types-n0uRTsW8.js";
+import { w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { r as PermDock } from "./permdock-SV8ZINYT.js";
+import { n as DescribeMessages, t as DecisionDescription } from "./describe-B5qgDvEW.js";
 //#region src/client/request.d.ts
 type StoreHeaders = Readonly<Record<string, string>>;
 //#endregion
@@ -144,4 +74,99 @@ type ClientStore = {
   dispose(): void;
 };
 //#endregion
-export { ClientPermDock as a, PermissionSet as c, SubjectView as d, TenantView as f, ApprovalState as i, PermissionState as l, ClientStoreOptions as n, ClientStatus as o, UseRolesOptions as p, ApprovalHandle as r, FilterResult as s, ClientStore as t, ProviderOptionsBase as u };
+//#region src/client/types.d.ts
+type ClientStatus = "ready" | "pending" | "stale" | "server-only";
+type PermissionState = {
+  readonly allowed: boolean;
+  readonly status: ClientStatus;
+  readonly decision: Decision;
+};
+type PermissionSet = {
+  readonly granted: readonly Permission[];
+  get(permission: Permission): PermissionState | undefined;
+};
+type ClientPermDock<V extends PolicyVocabulary = PolicyVocabulary> = PermDock<V> & {
+  status(permission?: Permission, data?: unknown): ClientStatus;
+  invalidate(ref: Permission | {
+    readonly [key: string]: unknown;
+  }): void;
+  refresh(options?: {
+    readonly tenant?: string;
+  }): Promise<void>;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+};
+type ApprovalState = "not-needed" | "required" | "pending" | "approved" | "rejected" | "expired";
+type ApprovalHandle = {
+  readonly state: ApprovalState;
+  readonly token: string | undefined;
+  readonly request: (note?: string) => Promise<void>;
+};
+type SubjectView = {
+  readonly principal: Principal | null;
+  readonly actor: Actor | undefined;
+  readonly delegation: Delegation | undefined;
+  readonly expiresAt: number | undefined;
+  readonly simulated: boolean;
+};
+type TenantView = {
+  readonly tenant: string | null;
+  readonly tenants: readonly string[];
+  readonly switchTo: (id: string) => Promise<void>;
+  readonly status: ClientStatus;
+};
+type FilterResult<T> = readonly T[] & {
+  readonly partial: boolean;
+};
+type RolesOptions = {
+  readonly tenant?: string;
+  readonly team?: string;
+};
+/** The provider options Vue, Svelte and Solid share; each adds its own reactive `snapshot`, `tenant`, `headers`, `verifier` and `defaults`. */
+type ProviderOptionsBase = {
+  /**
+   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer.
+   * `false` never calls one: such a check is denied with reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  /** Read on every request, so a new `fetch` applies without a new store. */
+  readonly fetch?: typeof fetch;
+  readonly maxAge?: number;
+  /** Localised text for the describe helper. */
+  readonly messages?: DescribeMessages;
+  /** Called with each snapshot the store accepts. */
+  readonly onSnapshot?: NonNullable<ClientStoreOptions["onSnapshot"]>;
+  /** Called when the store drops its snapshot. */
+  readonly onClear?: () => void;
+  /** Milliseconds between approval status polls. Defaults to 2000. */
+  readonly approvalInterval?: number;
+};
+/** How a control shows a permission it cannot use: hidden, or disabled with a reason. */
+type GateMode = "hide" | "disable";
+/**
+ * Everything a permission-gated control renders from, in one value: a
+ * button, a menu item or a link reads these fields and decides nothing
+ * itself. The client is a hint; the server checks again.
+ */
+type GateView = {
+  /** The decision granted the action. */
+  readonly allowed: boolean;
+  /** The snapshot is loading; render the control disabled, not hidden. */
+  readonly pending: boolean;
+  /** `mode: "hide"` and the action is not available: render nothing. */
+  readonly hidden: boolean;
+  /** The control cannot run the action now (denied, pending or awaiting approval). */
+  readonly disabled: boolean;
+  /** The decision needs a person's approval first; offer to request it. */
+  readonly needsApproval: boolean;
+  /** The plans that would grant the action, for an upgrade prompt; empty otherwise. */
+  readonly upgrade: readonly string[];
+  /** Title and detail for a tooltip or an accessible description. */
+  readonly reason: DecisionDescription;
+  readonly decision: Decision;
+};
+//#endregion
+export { FilterResult as a, PermissionSet as c, RolesOptions as d, SubjectView as f, ClientStoreOptions as h, ClientStatus as i, PermissionState as l, ClientStore as m, ApprovalState as n, GateMode as o, TenantView as p, ClientPermDock as r, GateView as s, ApprovalHandle as t, ProviderOptionsBase as u };