permdock 0.4.0 → 0.6.0

package/dist/clerk/index.d.ts

@@ -1,6 +1,7 @@
-import { Or as Principal, kr as Subject, nt as RoleSource } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { s as RemotePdpCache } from "../types-CIlTojhq.js";
+import { W as CustomRoleSource, ar as Subject, rr as Principal } from "../policy-types-n0uRTsW8.js";
+import { w as Permission } from "../vocabulary-CN8H_9UF.js";
+import { s as RemotePdpCache } from "../types-_WhUP7ud.js";
+import { t as ClaimsMap } from "../claims-map-Ca-QX8C6.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/clerk/types.d.ts
 type ClerkPrincipal = Principal & {
@@ -30,14 +31,14 @@ type ClerkBackend = {
     } | readonly ClerkMembershipListItem[]>;
   };
 };
-type ClerkGlobalRoles = string | ((claims: Readonly<Record<string, unknown>>) => readonly string[]);
 type ClerkSubjectOptions = {
   readonly memberships?: "active" | "all";
   readonly backend?: ClerkBackend;
-  readonly customRoles?: RoleSource;
+  readonly customRoles?: CustomRoleSource;
   readonly permissions?: Readonly<Record<string, Permission>>;
   readonly schema?: StandardSchemaV1;
-  readonly globalRoles?: ClerkGlobalRoles;
+  /** Where the session token carries platform roles (`claims.roles`): a path such as `publicMetadata.staff`, or a function. Organization roles come from the `o` claim. */
+  readonly claims?: Pick<ClaimsMap, "roles">;
   readonly features?: Readonly<Record<string, string>>;
   readonly declared?: readonly string[];
 };
@@ -60,6 +61,6 @@ export declare function subjectFromClerk(authObject: unknown, options?: ClerkSub
  * A resolver that keeps each user's `memberships: 'all'` list for
  * `cache.ttl` (at most 30 seconds), so a removed membership grants until then.
  */
-export declare function createClerkSubjectResolver(options?: ClerkSubjectResolverOptions): (authObject: unknown) => Promise<Subject<ClerkPrincipal>>;
+export declare function clerkSubjectResolver(options?: ClerkSubjectResolverOptions): (authObject: unknown) => Promise<Subject<ClerkPrincipal>>;
 //#endregion
-export type { ClerkAuthObject, ClerkBackend, ClerkGlobalRoles, ClerkMembershipListItem, ClerkPrincipal, ClerkSubjectOptions, ClerkSubjectResolverOptions };
+export type { ClerkAuthObject, ClerkBackend, ClerkMembershipListItem, ClerkPrincipal, ClerkSubjectOptions, ClerkSubjectResolverOptions };

package/dist/clerk/index.js

@@ -1,8 +1,9 @@
 import { i as omitKeys, r as isRecord, t as compact } from "../compact-CAf557ZB.js";
 import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { l as readPath, r as validateRecord } from "../thenable-QSmvt-vZ.js";
-import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
-import { c as ttlMs, s as ttlCache } from "../shared-JhMeOsDF.js";
+import { r as validateRecord } from "../thenable-yD7SabqG.js";
+import { t as anonymousSubject } from "../subject-BGoM5o8B.js";
+import { t as readClaim } from "../claims-map-7oQ3ue4X.js";
+import { c as ttlMs, s as ttlCache } from "../shared-DvvFzYXe.js";
 //#region src/clerk/subject.ts
 function asRoles(value) {
 	if (typeof value === "string") return value === "" ? [] : [value];
@@ -80,14 +81,8 @@ function featureRoles(fea, map) {
 		sources
 	};
 }
-function globalRolesFrom(claims, option) {
-	if (option === void 0) return [];
-	if (typeof option === "function") try {
-		return asRoles(option(claims));
-	} catch {
-		return [];
-	}
-	return asRoles(readPath(claims, option));
+function globalRolesFrom(claims, path) {
+	return path === void 0 ? [] : asRoles(readClaim(claims, path));
 }
 function splitList(value) {
 	return typeof value === "string" ? value.split(",").map((item) => item.trim()).filter((item) => item !== "") : [];
@@ -206,7 +201,7 @@ function subjectFromClerk(authObject, options = {}) {
 * A resolver that keeps each user's `memberships: 'all'` list for
 * `cache.ttl` (at most 30 seconds), so a removed membership grants until then.
 */
-function createClerkSubjectResolver(options = {}) {
+function clerkSubjectResolver(options = {}) {
 	const { cache, ...rest } = options;
 	const lists = ttlCache(ttlMs(cache));
 	const load = async (backend, userId) => {
@@ -249,7 +244,7 @@ async function fromClerk(authObject, options, loadMemberships) {
 		})];
 		let claims = extraClaims(mapped.claims);
 		if (options.schema !== void 0) claims = validateRecord(options.schema, claims) ?? {};
-		const global = [...globalRolesFrom(mapped.claims, options.globalRoles), ...features.user];
+		const global = [...globalRolesFrom(mapped.claims, options.claims?.roles), ...features.user];
 		const exp = mapped.claims["exp"];
 		const principal = compact({
 			id: mapped.id,
@@ -273,4 +268,4 @@ async function fromClerk(authObject, options, loadMemberships) {
 	}
 }
 //#endregion
-export { createClerkSubjectResolver, subjectFromClerk };
+export { clerkSubjectResolver, subjectFromClerk };

package/dist/cli/bin.js

@@ -1,20 +1,39 @@
 #!/usr/bin/env node
-import { t as run } from "../run-DMcNW_8T.js";
-import { n as streamHasColors } from "../style-CTm1AXDT.js";
+import module from "node:module";
+import { text } from "node:stream/consumers";
 //#region src/cli/bin.ts
-const result = await run(process.argv.slice(2), {
-	cwd: process.cwd(),
-	io: {
-		env: process.env,
-		stdout: (text) => {
-			process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
-		},
-		stderr: (text) => {
-			process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
-		},
-		color: streamHasColors(process.stdout),
-		interactive: process.stdin.isTTY === true && process.stdout.isTTY === true && process.env["CI"] === void 0
-	}
-});
-process.exitCode ??= result.code;
+module.enableCompileCache?.();
+const argv = process.argv.slice(2);
+if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
+	const { cliVersion } = await import("../version-DXkYUISx.js");
+	process.stdout.write(`${cliVersion()}\n`);
+} else {
+	const [{ isCi }, { trapSignals }, { run }, { streamHasColors }] = await Promise.all([
+		import("../env-DJZrPjRi.js"),
+		import("../signals-D3NcTKUS.js"),
+		import("../run-DDwUaJDU.js"),
+		import("../style-DiKWnAvn.js")
+	]);
+	const signals = trapSignals();
+	const result = await run(argv, {
+		cwd: process.cwd(),
+		io: {
+			env: process.env,
+			signal: signals.signal,
+			stdout: (chunk) => {
+				process.stdout.write(chunk);
+			},
+			stderr: (chunk) => {
+				process.stderr.write(chunk);
+			},
+			color: streamHasColors(process.stdout),
+			errColor: streamHasColors(process.stderr),
+			stdoutIsTty: process.stdout.isTTY === true,
+			stderrIsTty: process.stderr.isTTY === true,
+			readStdin: () => text(process.stdin),
+			interactive: process.stdin.isTTY === true && process.stdout.isTTY === true && !isCi(process.env)
+		}
+	});
+	process.exitCode ??= result.code;
+}
 //#endregion

package/dist/cli/index.d.ts

@@ -1,5 +1,6 @@
-import { a as CatalogDocument, c as CatalogResource, d as CatalogSupportAccess, f as CatalogUsage, l as CatalogRole, n as CatalogApproval, r as CatalogBreakGlass, s as CatalogPermission, t as CatalogActivation, u as CatalogScope } from "../types-DpWfQdSh.js";
-import { _ as RunResult, c as RlsConfig, d as RlsMembershipTable, f as RlsMemberships, g as RlsTarget, h as RlsSuspension, i as PermDockConfig, l as RlsDialect, m as RlsSuspendedScope, n as CliIo, o as RlsActiveRow, p as RlsSuspendedMembership, r as CollectConfig, s as RlsApiKeys, t as CatalogConfig, u as RlsFunctionMapping } from "../types-7rJVLWe5.js";
+import { a as CatalogDocument, d as CatalogRole, f as CatalogScope, l as CatalogPermission, m as CatalogUsage, n as CatalogApproval, p as CatalogSupportAccess, r as CatalogBreakGlass, t as CatalogActivation, u as CatalogResource } from "../types-Druu9wLM.js";
+import { a as pushedPolicy, i as parsePushedPolicy, n as PushedGrant, r as PushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-DCW91KQU.js";
+import { _ as RunResult, c as RlsConfig, d as RlsMembershipTable, f as RlsMemberships, g as RlsTarget, h as RlsSuspension, i as PermDockConfig, l as RlsDialect, m as RlsSuspendedScope, n as CliIo, o as RlsActiveRow, p as RlsSuspendedMembership, r as CollectConfig, s as RlsApiKeys, t as CatalogConfig, u as RlsFunctionMapping } from "../types-Dfv0aTER.js";
 //#region src/cli/catalog-path.d.ts
 /**
  * The absolute path `permdock collect` writes the catalog to: `collect.out`,
@@ -8,7 +9,7 @@ import { _ as RunResult, c as RlsConfig, d as RlsMembershipTable, f as RlsMember
  */
 export declare function catalogPath(config: PermDockConfig, cwd: string, out?: string): string;
 //#endregion
-//#region src/cli/config.d.ts
+//#region src/cli/project/config.d.ts
 export declare function defineConfig<T extends PermDockConfig>(config: T): T;
 //#endregion
 //#region src/cli/sql/markers.d.ts
@@ -37,10 +38,23 @@ export declare function parseHookMarker(sql: string): SupabaseHookMarker | undef
  */
 export declare function parseGrantsMarker(sql: string): SupabaseGrantsMarker | undefined;
 //#endregion
-//#region src/cli/run.d.ts
+//#region src/cli/token-schemas.d.ts
+/**
+ * `schemas/run-v1.json`: the claims of a `vnd.permdock.run+jwt`, as
+ * `signRunTicket` writes them and `parseRunTicket` accepts them. Unknown
+ * claims are allowed; `parseRunTicket` drops them.
+ */
+export declare const RUN_TICKET_SCHEMA: Readonly<Record<string, unknown>>;
+/**
+ * `schemas/support-session-v1.json`: the claims of a
+ * `vnd.permdock.support-session+jwt`, as `signSupportSession` writes them.
+ */
+export declare const SUPPORT_SESSION_SCHEMA: Readonly<Record<string, unknown>>;
+//#endregion
+//#region src/cli/core/run.d.ts
 export declare function run(argv: readonly string[], options?: {
   readonly cwd?: string;
   readonly io?: CliIo;
 }): Promise<RunResult>;
 //#endregion
-export type { CatalogActivation, CatalogApproval, CatalogBreakGlass, CatalogConfig, CatalogDocument, CatalogPermission, CatalogResource, CatalogRole, CatalogScope, CatalogSupportAccess, CatalogUsage, CollectConfig, PermDockConfig, RlsActiveRow, RlsApiKeys, RlsConfig, RlsDialect, RlsFunctionMapping, RlsMembershipTable, RlsMemberships, RlsSuspendedMembership, RlsSuspendedScope, RlsSuspension, RlsTarget, RunResult, SupabaseGrantsMarker, SupabaseHookMarker };
+export { type CatalogActivation, type CatalogApproval, type CatalogBreakGlass, type CatalogConfig, type CatalogDocument, type CatalogPermission, type CatalogResource, type CatalogRole, type CatalogScope, type CatalogSupportAccess, type CatalogUsage, type CollectConfig, PUSHED_POLICY_SCHEMA, type PermDockConfig, type PushedGrant, type PushedPolicy, type RlsActiveRow, type RlsApiKeys, type RlsConfig, type RlsDialect, type RlsFunctionMapping, type RlsMembershipTable, type RlsMemberships, type RlsSuspendedMembership, type RlsSuspendedScope, type RlsSuspension, type RlsTarget, type RunResult, type SupabaseGrantsMarker, type SupabaseHookMarker, parsePushedPolicy, pushedPolicy };

package/dist/cli/index.js

@@ -1,5 +1,165 @@
 import { t as catalogPath } from "../catalog-path-CnI0XTFK.js";
-import { t as defineConfig } from "../config-BIjREpyE.js";
-import { c as parseGrantsMarker, l as parseHookMarker } from "../markers-CiwAOZtO.js";
-import { t as run } from "../run-DMcNW_8T.js";
-export { catalogPath, defineConfig, parseGrantsMarker, parseHookMarker, run };
+import { t as defineConfig } from "../config-bs_kZeYq.js";
+import { n as parsePushedPolicy, r as pushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-CqtxkV4G.js";
+import { c as parseGrantsMarker, l as parseHookMarker } from "../markers-C6joDI3o.js";
+import { t as run } from "../run-CUKuz0A8.js";
+//#region src/cli/token-schemas.ts
+const ID = {
+	type: "string",
+	minLength: 1,
+	maxLength: 256
+};
+const NUMERIC_DATE = {
+	type: "integer",
+	minimum: 0
+};
+const AUDIENCE = { anyOf: [ID, {
+	type: "array",
+	items: ID,
+	minItems: 1
+}] };
+/**
+* `schemas/run-v1.json`: the claims of a `vnd.permdock.run+jwt`, as
+* `signRunTicket` writes them and `parseRunTicket` accepts them. Unknown
+* claims are allowed; `parseRunTicket` drops them.
+*/
+const RUN_TICKET_SCHEMA = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://permdock.com/schemas/run-v1.json",
+	title: "PermDock run ticket",
+	description: "The claims of a vnd.permdock.run+jwt, wire format v1. At least one of scope and authorization_details is present; automation is present exactly when kind is automation.",
+	type: "object",
+	required: [
+		"v",
+		"iss",
+		"sub",
+		"aud",
+		"jti",
+		"iat",
+		"exp",
+		"kind"
+	],
+	properties: {
+		v: { const: 1 },
+		iss: ID,
+		sub: ID,
+		aud: AUDIENCE,
+		jti: ID,
+		iat: NUMERIC_DATE,
+		exp: NUMERIC_DATE,
+		kind: { enum: [
+			"automation",
+			"job",
+			"caller"
+		] },
+		act: { $ref: "#/$defs/act" },
+		scope: { type: "string" },
+		authorization_details: {
+			type: "array",
+			items: {
+				type: "object",
+				required: ["type"],
+				properties: { type: { type: "string" } }
+			}
+		},
+		automation: {
+			type: "object",
+			required: ["id", "version"],
+			properties: {
+				id: ID,
+				version: { anyOf: [ID, {
+					type: "integer",
+					minimum: 0
+				}] }
+			}
+		},
+		tenant: ID,
+		trigger: { type: "object" },
+		binding: {
+			type: "object",
+			properties: {
+				connector: ID,
+				tools: {
+					type: "array",
+					items: ID,
+					maxItems: 64
+				}
+			}
+		}
+	},
+	anyOf: [{
+		required: ["scope"],
+		properties: { scope: true }
+	}, {
+		required: ["authorization_details"],
+		properties: { authorization_details: true }
+	}],
+	$defs: { act: {
+		description: "RFC 8693 act: the party running the work; at most 8 nested levels.",
+		type: "object",
+		required: ["sub"],
+		properties: {
+			sub: ID,
+			kind: ID,
+			act: { $ref: "#/$defs/act" }
+		}
+	} }
+};
+/**
+* `schemas/support-session-v1.json`: the claims of a
+* `vnd.permdock.support-session+jwt`, as `signSupportSession` writes them.
+*/
+const SUPPORT_SESSION_SCHEMA = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://permdock.com/schemas/support-session-v1.json",
+	title: "PermDock support session",
+	description: "The claims of a vnd.permdock.support-session+jwt, wire format v1: sub is the viewed principal, act the support actor, jti the session id. exp is after iat, by at most one day.",
+	type: "object",
+	required: [
+		"v",
+		"iss",
+		"sub",
+		"aud",
+		"jti",
+		"iat",
+		"exp",
+		"act",
+		"tenant",
+		"reason",
+		"permissions"
+	],
+	properties: {
+		v: { const: 1 },
+		iss: ID,
+		sub: ID,
+		aud: AUDIENCE,
+		jti: ID,
+		iat: NUMERIC_DATE,
+		exp: NUMERIC_DATE,
+		act: {
+			type: "object",
+			required: ["sub", "kind"],
+			additionalProperties: false,
+			properties: {
+				sub: ID,
+				kind: { const: "support" }
+			}
+		},
+		tenant: ID,
+		reason: {
+			type: "string",
+			minLength: 1,
+			maxLength: 1e3
+		},
+		permissions: {
+			type: "array",
+			items: ID,
+			minItems: 1,
+			maxItems: 64
+		},
+		approved_by: ID,
+		reference: ID
+	}
+};
+//#endregion
+export { PUSHED_POLICY_SCHEMA, RUN_TICKET_SCHEMA, SUPPORT_SESSION_SCHEMA, catalogPath, defineConfig, parseGrantsMarker, parseHookMarker, parsePushedPolicy, pushedPolicy, run };

package/dist/cloud/index.d.ts

@@ -1,90 +1,129 @@
-import { Cn as MembershipEvent, Ht as PolicySource, Sn as DirectoryEvent, W as DecisionSink, at as SnapshotSource, bn as CredentialEvent, ct as TokenFailureCause, ut as TokenVerifier, vn as AccessEvent, xn as DecisionEvent } from "../policy-types-sp9P1iIV.js";
-import { f as ApprovalStore } from "../types-Br9IXUBG.js";
-import { a as JsonWebKeySet, g as ReplayStore } from "../types-C0dee0Qf.js";
-import { n as CatalogEventData, o as CloudEventType } from "../sink-CPN4zLfs.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;
-};
-type CloudOptions = CloudEndpointOptions & {
-  readonly key?: string;
-  readonly fetch?: typeof fetch;
-  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;
-  /**
-   * 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;
-};
-type CloudClient = CloudEndpoints & {
-  readonly approvals: ApprovalStore;
-  readonly sink: DecisionSink;
-  readonly snapshots: SnapshotSource;
-  readonly policies: PolicySource;
-};
-//#endregion
-//#region src/cloud/create.d.ts
+import { Jt as AutomationEvent, Kt as AccessEvent, Qt as DeliveryEvent, Rt as Instant, Xt as DecisionEvent, Yt as CredentialEvent, Zt as DeliveryChannel, en as DirectoryEvent, nn as MembershipEvent, ut as TokenSigner } from "../policy-types-n0uRTsW8.js";
+import { m as ApprovalStore } from "../types-BdtSDbBO.js";
+import { i as CatalogEventData, l as CloudEventType, r as CLOUD_EVENT_TYPES, s as CloudEvent } from "../sink-4-eQIRWf.js";
+import { c as DeliveryTransport } from "../types-BtHtcKMr.js";
+import { a as CloudConnectionOptions, c as CloudOptions, i as CloudClient, l as CloudSignerOptions, n as CloudCatalog, o as CloudEndpointOptions, r as CloudCatalogPush, s as CloudEndpoints, t as CloudApproverOptions } from "../types-8RnwUAvE.js";
+import { n as ApprovalWaiter } from "../waiter-B986w1oK.js";
+import { l as ReplayStore } from "../types-C791HFu9.js";
+import { f as WebhookVerifier, r as WebhookFailureCause$1, s as WebhookJwks } from "../standard-webhooks-rbD7LS6h.js";
+//#region src/cloud/request.d.ts
 /**
  * The environment URL and JWK Set URL `cloud()` uses, resolved with the same
  * fallbacks (`PERMDOCK_CLOUD_URL`; `PERMDOCK_CLOUD_ENV`, `VERCEL_ENV`, `production`).
  */
 export declare function cloudEndpoints(options?: CloudEndpointOptions): CloudEndpoints;
+//#endregion
+//#region src/cloud/create.d.ts
 export declare function cloud(options?: CloudOptions): CloudClient;
 //#endregion
+//#region src/cloud/delivery.d.ts
+/**
+ * A `DeliveryTransport` for `channel` that hands each checked recipient to
+ * PermDock Cloud, which sends it from its hosted email, chat or webhook
+ * sender and reports back through `com.permdock.delivery.*` events. The
+ * router has already decided the recipient: the Cloud receives the target
+ * and the permission that let it through, never a decision to make.
+ * `Idempotency-Key` is the delivery's idempotency key, so a retry repeats it.
+ */
+export declare function cloudDeliveryTransport<C extends DeliveryChannel>(channel: C, options?: CloudConnectionOptions): DeliveryTransport<C>;
+//#endregion
+//#region src/cloud/signer.d.ts
+/**
+ * A `TokenSigner` backed by the environment's PermDock Cloud keys, typically
+ * KMS-held, for run tickets (`vnd.permdock.run+jwt`) and every other signed
+ * output an app issues. The Cloud signs only what the app sends: it sets
+ * `iss` to the environment URL and adds no claim. Policy documents,
+ * snapshots, evidence exports, Security Event Tokens and `at+jwt` access tokens are the Cloud's own
+ * outputs, so their `typ` values are refused here. Verify what it signs with
+ * `joseTokenVerifier({ jwks: cloudEndpoints().jwks })`.
+ */
+export declare function cloudSigner(options?: CloudSignerOptions): TokenSigner;
+//#endregion
 //#region src/cloud/webhook.d.ts
-type Envelope<TType extends CloudEventType, TData> = {
-  readonly specversion: "1.0";
+type Envelope<TType extends CloudEventType, TData> = Omit<CloudEvent, "type" | "data"> & {
   readonly type: TType;
-  readonly source: string;
-  readonly subject?: string;
-  readonly id: string;
-  readonly time: string;
-  readonly datacontenttype: "application/json";
   readonly data: TData;
 };
+type Types = typeof CLOUD_EVENT_TYPES;
 /** A CloudEvent PermDock Cloud delivers, discriminated by `type`. */
-type PermDockCloudEvent = Envelope<"dev.permdock.decision", DecisionEvent> | Envelope<"dev.permdock.approval", DecisionEvent> | Envelope<"dev.permdock.directory", DirectoryEvent> | Envelope<"dev.permdock.membership", MembershipEvent> | Envelope<"dev.permdock.credential", CredentialEvent> | Envelope<"dev.permdock.catalog", CatalogEventData> | Envelope<"dev.permdock.access.started", AccessEvent> | Envelope<"dev.permdock.access.ended", AccessEvent> | Envelope<"dev.permdock.access.revoked", AccessEvent>;
-type VerifyWebhookOptions = {
-  /** Your receiver's URL; the batch `aud` must name it. */
-  readonly audience: string | readonly string[];
-  /** A verifier over the Cloud JWKS; built from `jwks` when absent. */
-  readonly verifier?: TokenVerifier;
-  /** `cloud().jwks`, a JWKS URL, or an inline key set. */
-  readonly jwks?: string | URL | JsonWebKeySet;
-  /** Drops a batch whose `jti` was already delivered. */
+type PermDockCloudEvent = Envelope<Types["decision"], DecisionEvent> | Envelope<Types["approvalRequested"] | Types["approvalResolved"] | Types["approvalExpired"] | Types["approvalCancelled"], DecisionEvent> | Envelope<Types["directoryCreated"] | Types["directoryReplaced"] | Types["directoryPatched"] | Types["directoryDeleted"], DirectoryEvent> | Envelope<Types["membershipAdded"] | Types["membershipRemoved"] | Types["membershipChanged"], MembershipEvent> | Envelope<Types["credentialCreated"] | Types["credentialUsed"] | Types["credentialRotated"] | Types["credentialRevoked"], CredentialEvent> | Envelope<Types["catalogPublished"] | Types["catalogDrifted"], CatalogEventData> | Envelope<Types["supportSessionStarted"] | Types["supportSessionEnded"], AccessEvent> | Envelope<Types["automationPublished"] | Types["automationChanged"] | Types["automationRevoked"] | Types["automationRun"], AutomationEvent> | Envelope<Types["deliverySent"] | Types["deliveryDelivered"] | Types["deliveryBounced"] | Types["deliveryComplained"] | Types["deliveryFailed"], DeliveryEvent>;
+type WebhookOptions = {
+  /**
+   * A verifier to reuse across deliveries, so the JWKS is fetched once;
+   * built from `jwks`, `secret`, `replay`, `tolerance` and `now` when absent.
+   */
+  readonly verifier?: WebhookVerifier;
+  /** `cloud().jwks`, a JWKS URL or an inline key set, for `v1a` signatures. */
+  readonly jwks?: WebhookJwks;
+  /** The endpoint's `whsec_` secret, for `v1` signatures. */
+  readonly secret?: string | readonly string[];
+  /** Records each `webhook-id`; required unless `verifier` is set. */
   readonly replay?: ReplayStore;
+  /** Seconds a timestamp may differ from the clock. Defaults to 300. */
+  readonly tolerance?: number;
+  readonly now?: () => Instant;
+  readonly fetch?: typeof fetch;
 };
-type WebhookFailureReason = "unsigned" | "invalid-token" | "invalid-events" | "replayed";
+/** The Standard Webhooks verifier's cause, or `invalid-events` for a signed body that is not a CloudEvents batch. */
+type WebhookFailureCause = WebhookFailureCause$1 | "invalid-events";
 type VerifiedWebhook = {
   readonly ok: true;
+  /** The `webhook-id`, unique per message across retries. */
   readonly id: string;
+  /** The `webhook-timestamp` as an RFC 3339 instant. */
+  readonly timestamp: string;
   readonly events: readonly PermDockCloudEvent[];
 } | {
   readonly ok: false;
-  readonly reason: WebhookFailureReason;
-  readonly cause?: TokenFailureCause;
+  readonly cause: WebhookFailureCause;
 };
 /**
- * Validates one CloudEvent against the closed type list and its data shape;
- * returns `null` for anything else, never throws.
+ * Validates one CloudEvent against the closed type list, its `dataschema` and
+ * its data shape; returns `null` for anything else, never throws.
  */
 export declare function parseCloudEvent(value: unknown): PermDockCloudEvent | null;
 /**
- * Verifies a PermDock Cloud webhook delivery: a compact JWS with
- * `typ: permdock-decisions+jwt` whose `events` claim holds CloudEvents.
- * There is no unsigned mode, and it never throws.
+ * Verifies a PermDock Cloud webhook delivery: Standard Webhooks headers over
+ * an `application/cloudevents-batch+json` body (or one
+ * `application/cloudevents+json` event). There is no unsigned mode, and it
+ * never throws.
+ */
+export declare function verifyWebhook(request: Request, options: WebhookOptions): Promise<VerifiedWebhook>;
+//#endregion
+//#region src/cloud/waiter.d.ts
+type CloudApprovalWaiterOptions = WebhookOptions & ({
+  /** Read when a wait starts and every `interval` after; typically `cloud().approvals`. */
+  readonly store: ApprovalStore;
+  /** Milliseconds between fallback reads of `store`. Defaults to 60000. */
+  readonly interval?: number;
+  readonly waiter?: undefined;
+} | {
+  /** A durable runner's waiter (`workflowSdkWaiter()`); `wait` and `wake` go to it. */
+  readonly waiter: ApprovalWaiter;
+  readonly store?: undefined;
+  readonly interval?: undefined;
+});
+type CloudApprovalWaiter = ApprovalWaiter & {
+  /**
+   * The endpoint for the environment's webhook connector. It verifies the
+   * Standard Webhooks signature and wakes the wait of every
+   * `com.permdock.approval.resolved`, `.expired` and `.cancelled` event in
+   * the batch. It answers `204` once handled or replayed, and Problem
+   * Details otherwise.
+   */
+  readonly webhook: (request: Request) => Promise<Response>;
+};
+/** The approval token of each event that ends a wait, in delivery order. */
+export declare function approvalTokensOf(events: readonly PermDockCloudEvent[]): readonly string[];
+/**
+ * An `ApprovalWaiter` that PermDock Cloud wakes. Mount `webhook` on the
+ * route the environment's webhook connector posts to: when an approval is
+ * resolved, expires or is cancelled, the parked run for its token wakes.
+ * Waking never approves anything. The run decides again with the token, and
+ * only the app's `decide` and its approval store can grant. Without
+ * `waiter`, waits poll `store` as a fallback for a webhook another process
+ * received.
  */
-export declare function verifyWebhook(request: Request, options: VerifyWebhookOptions): Promise<VerifiedWebhook>;
+export declare function cloudApprovalWaiter(options: CloudApprovalWaiterOptions): CloudApprovalWaiter;
 //#endregion
-export type { CloudClient, CloudEndpointOptions, CloudEndpoints, CloudOptions, PermDockCloudEvent, VerifiedWebhook, VerifyWebhookOptions, WebhookFailureReason };
+export type { CloudApprovalWaiter, CloudApprovalWaiterOptions, CloudApproverOptions, CloudCatalog, CloudCatalogPush, CloudClient, CloudConnectionOptions, CloudEndpointOptions, CloudEndpoints, CloudOptions, CloudSignerOptions, PermDockCloudEvent, VerifiedWebhook, WebhookFailureCause, WebhookOptions };