permdock 0.6.0 → 0.7.0

package/dist/{instance-options-BsVpyGIk.d.ts → instance-options-CU0YQCLH.d.ts}

@@ -1,4 +1,4 @@
-import { i as PermDockOptions } from "./permdock-SV8ZINYT.js";
+import { o as PermDockOptions } from "./permdock-Dco6dyCK.js";
 //#region src/core/instance-options.d.ts
 type InstanceKey = "memberships" | "relations" | "entitlements" | "customRoles" | "policies" | "approvalPolicies" | "sink" | "limits" | "principals";
 /**

package/dist/{instance-snapshot-BOEhcqIF.js → instance-snapshot-CjcwnEiV.js}

@@ -1,21 +1,21 @@
 import { t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { a as hasConditionOp } from "./refs-K6eWUJ0H.js";
+import { o as hasConditionOp } from "./refs-CNJBiTFo.js";
 import { o as sameId } from "./expiry-D4_YKRKD.js";
-import { a as getResource, c as listPermissions } from "./permission-registry-Br4jSNVi.js";
+import { a as getResource, c as listPermissions } from "./permission-registry-DpPtSKNZ.js";
 import { n as isThenable } from "./thenable-yD7SabqG.js";
 import { u as isPrincipalRelation } from "./resource-relations-D_jw0BFx.js";
 import { p as nowSeconds, s as instantAt } from "./time-DkWjdL98.js";
-import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
-import { c as rootScope, d as scopeList, i as keepsPermission, m as tenantOf, o as resolveScope } from "./scopes-CUPSjo9q.js";
-import { a as readOnlyActorRefuses, i as delegatedPermissions, r as coversRequirements } from "./delegation-j6-rc37o.js";
-import { b as synthesiseRole, m as findRole, o as flattenGrantee, v as listRoles, x as treeXSchema, y as sourceRoleMeta } from "./grantee-hxrUsbpM.js";
-import { c as nowSeconds$1, d as resolveActiveTenant, l as partitionsOf, p as scopeField, r as isMembershipExpired } from "./tenancy-DN2QAx9z.js";
-import { a as levelCondition, o as levelNames, r as grantList, t as declaredRoleNames } from "./policy-DbM5YYtV.js";
+import { t as canonicalJson } from "./canonical-json-DwilZ1iB.js";
+import { f as scopeList, h as tenantOf, i as keepsPermission, l as rootScope, s as resolveScope } from "./scopes-BHsc-wp-.js";
+import { a as readOnlyActorRefuses, i as delegatedPermissions, r as coversRequirements } from "./delegation-C5rOdTp5.js";
+import { b as synthesiseRole, m as findRole, o as flattenGrantee, v as listRoles, x as treeXSchema, y as sourceRoleMeta } from "./grantee-BrRANrpT.js";
+import { c as nowSeconds$1, d as resolveActiveTenant, l as partitionsOf, p as scopeField, r as isMembershipExpired } from "./tenancy-CmeBQ6Nv.js";
+import { o as levelCondition, r as grantList, s as levelNames, t as declaredRoleNames } from "./policy-DaJy4nK4.js";
 import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { A as contactMayUse, S as tenantCustomRoles, T as emptyListeners, _ as isSharedCustomRole, a as expandRoleNames, b as resolveCustomRole, g as holdsGlobalCustomRole, h as holdsCustomRole, l as ceilingGrants, m as customRoleScope, n as requirementCondition, p as customRoleOf, t as evaluate, u as customGrantsFor, x as roleAllowKeys } from "./evaluate-CNClBvcj.js";
-import { n as matchGrantee, t as combineWhere } from "./grantee-match-DbENBHLB.js";
-import { t as buildSnapshot } from "./snapshot-B7DkYg6g.js";
+import { C as tenantCustomRoles, D as emptyListeners, M as contactMayUse, S as roleAllowKeys, _ as isSharedCustomRole, a as expandRoleNames, g as holdsGlobalCustomRole, h as holdsCustomRole, l as ceilingGrants, m as customRoleScope, n as requirementCondition, p as customRoleOf, t as evaluate, u as customGrantsFor, x as resolveCustomRole } from "./evaluate-B_oqFbWC.js";
+import { n as matchGrantee, t as combineWhere } from "./grantee-match-0RtHWQDx.js";
+import { t as buildSnapshot } from "./snapshot-CbGmYiJx.js";
 //#region src/core/memberships.ts
 /** Two memberships are the same row when everything but `roles` matches. */
 function identity(membership) {
@@ -71,7 +71,11 @@ function then(value, next) {
 function composeMemberships(sources) {
 	const listing = sources.filter((source) => source.list !== void 0);
 	const versioned = sources.filter((source) => source.version !== void 0);
+	const rolesReaders = sources.filter((source) => source.globalRolesFor !== void 0);
 	return {
+		...rolesReaders.length === 0 ? {} : { globalRolesFor(principal) {
+			return then(all(rolesReaders.map((source) => source.globalRolesFor?.(principal) ?? [])), (lists) => [...new Set(lists.flat())]);
+		} },
 		membershipsFor(principal, options) {
 			return then(all(sources.map((source) => source.membershipsFor(principal, options))), (lists) => mergeMemberships(lists));
 		},
@@ -117,6 +121,7 @@ function claimsFirst(source, options = {}) {
 		membershipsFor: (principal, query) => inner.membershipsFor(principal, query),
 		...inner.list === void 0 ? {} : { list: (query) => inner.list?.(query) ?? [] },
 		...version === void 0 ? {} : { version },
+		...inner.globalRolesFor === void 0 ? {} : { globalRolesFor: (principal) => inner.globalRolesFor?.(principal) ?? [] },
 		...options.onStale === "reread" ? { onStale: "reread" } : {},
 		claimsFirst: true
 	};

package/dist/jwt/index.d.ts

@@ -1,7 +1,7 @@
-import { Y as JwtClaims, ar as Subject, dt as TokenVerifier, lt as TokenFailureCause, qt as AuthEvent, rr as Principal, ut as TokenSigner } from "../policy-types-n0uRTsW8.js";
-import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-Drg-1YhL.js";
-import { B as JwtAlgorithm, F as DpopProofResult, H as JwtPrincipal, I as IntrospectionPrincipal, L as JoseTokenSignerOptions, P as DiscoveryInput, R as JoseTokenVerifierOptions, U as JwtSubjectOptions, V as JwtJwks, W as MappedSubject, l as ReplayStore, z as JsonWebKeySet } from "../types-C791HFu9.js";
-import { t as memoryReplayStore } from "../replay-Bkm-Ne4l.js";
+import { Y as JwtClaims, Zt as AuthEvent, dt as TokenVerifier, lr as Subject, lt as TokenFailureCause, pt as VerifiedToken, sr as Principal, ut as TokenSigner } from "../policy-types-B-F-qAZk.js";
+import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-D4UC9TTW.js";
+import { B as JwtAlgorithm, F as DpopProofResult, H as JwtPrincipal, I as IntrospectionPrincipal, L as JoseTokenSignerOptions, P as DiscoveryInput, R as JoseTokenVerifierOptions, U as JwtSubjectOptions, V as JwtJwks, W as MappedSubject, l as ReplayStore, z as JsonWebKeySet } from "../types-cTos-H7p.js";
+import { t as memoryReplayStore } from "../replay-DCDD_ZfL.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/jwt/capability.d.ts
 /** `on('auth')` causes: a verification failure, or one of the three capability checks. */
@@ -82,6 +82,48 @@ type DpopProofOptions = {
 };
 export declare function verifyDpopProof(request: Request, claims: JwtClaims, accessToken?: string, options?: DpopProofOptions): Promise<DpopProofResult>;
 //#endregion
+//#region src/jwt/id-token.d.ts
+/** `TokenFailureCause` plus `nonce-mismatch`; a `TokenVerifier` never returns it. */
+type IdTokenFailureCause = TokenFailureCause | "nonce-mismatch";
+type VerifyIdTokenOptions = {
+  /** The OpenID Provider's issuer; `iss` must equal it. */
+  readonly issuer: string;
+  /** The relying party's `client_id`; `aud` must contain it and `azp`, when present, must equal it. */
+  readonly clientId: string;
+  /** The `nonce` sent in the authentication request; the token's must equal it. */
+  readonly nonce?: string;
+  readonly clockTolerance?: number;
+} & ({
+  /** A verifier the caller keeps, so its JWKS cache outlives one call. */
+  readonly verifier: TokenVerifier;
+  readonly jwks?: never;
+  readonly algorithms?: never;
+} | {
+  readonly jwks: JsonWebKeySet;
+  readonly algorithms?: readonly JwtAlgorithm[];
+  readonly verifier?: never;
+});
+type IdTokenClaims = JwtClaims & {
+  readonly iss: string;
+  readonly sub: string;
+  readonly iat: number;
+};
+type VerifyIdTokenResult = {
+  readonly ok: true;
+  readonly claims: IdTokenClaims;
+  readonly header: VerifiedToken["header"];
+} | {
+  readonly ok: false;
+  readonly cause: IdTokenFailureCause;
+};
+/**
+ * Verifies an OpenID Connect ID token for a relying party (Core section
+ * 3.1.3.7): signature, `iss`, `aud`, `exp`, `iat`, `typ` `JWT` or absent,
+ * `azp` and, when `nonce` is given, `nonce`. It does not check `at_hash`,
+ * `c_hash`, `auth_time` or `acr`. Never throws.
+ */
+export declare function verifyIdToken(token: string, options: VerifyIdTokenOptions): Promise<VerifyIdTokenResult>;
+//#endregion
 //#region src/jwt/introspection.d.ts
 export declare function subjectFromIntrospection(response: unknown, options?: JwtSubjectOptions): Subject<IntrospectionPrincipal>;
 //#endregion
@@ -92,7 +134,43 @@ export declare function joseTokenSigner(options: JoseTokenSignerOptions): TokenS
 export declare function subjectFromJwt(token: string | undefined | null, options: JwtSubjectOptions, request?: Request): Promise<Subject<JwtPrincipal>>;
 export declare function jwtSubjectResolver(options: JwtSubjectOptions): (token: string | undefined | null, request?: Request) => Promise<MappedSubject>;
 //#endregion
+//#region src/jwt/subject-token.d.ts
+/** `TokenFailureCause` plus the two checks `verifySubjectToken` adds; a `TokenVerifier` never returns them. */
+type SubjectTokenFailureCause = TokenFailureCause | "replayed" | "lifetime-exceeded";
+type VerifySubjectTokenOptions = {
+  /** Tried in order; the first that accepts the token wins. */
+  readonly verifiers: readonly TokenVerifier[];
+  readonly audience: string | readonly string[];
+  /** Records each `jti` once; `claim` when the store has it, else `seen` and `remember`. */
+  readonly replay: ReplayStore;
+  /** The largest `exp - iat`, in seconds; default 300. */
+  readonly maxLifetime?: number;
+  readonly clockTolerance?: number;
+};
+type SubjectTokenClaims = JwtClaims & {
+  readonly sub: string;
+  readonly jti: string;
+  readonly iat: number;
+  readonly exp: number;
+};
+type VerifySubjectTokenResult = {
+  readonly ok: true;
+  readonly claims: SubjectTokenClaims;
+  readonly header: VerifiedToken["header"];
+} | {
+  readonly ok: false;
+  readonly cause: SubjectTokenFailureCause;
+};
+/**
+ * Verifies a subject token: an RFC 9068 `at+jwt` naming one subject for one
+ * request, such as the `PermDock-Subject` header. The first of `verifiers`
+ * that accepts it wins. The token must carry `sub`, `jti`, `iat` and `exp`,
+ * live at most `maxLifetime` seconds, and present its `jti` once. A replay
+ * store that throws refuses the token as `replayed`. Never throws.
+ */
+export declare function verifySubjectToken(token: string, options: VerifySubjectTokenOptions): Promise<VerifySubjectTokenResult>;
+//#endregion
 //#region src/jwt/verifier.d.ts
 export declare function joseTokenVerifier(options: JoseTokenVerifierOptions): TokenVerifier;
 //#endregion
-export { type CapabilityFailureCause, type CapabilitySubjectOptions, type CiOidcPrincipal, type CiOidcProvider, type CiOidcSubjectOptions, type DiscoveryInput, type DpopProofOptions, type DpopProofResult, type IntrospectionPrincipal, type JoseTokenSignerOptions, type JoseTokenVerifierOptions, type JsonWebKeySet, type JwtAlgorithm, type JwtJwks, type JwtPrincipal, type JwtSubjectOptions, type ReplayStore, memoryReplayStore };
+export { type CapabilityFailureCause, type CapabilitySubjectOptions, type CiOidcPrincipal, type CiOidcProvider, type CiOidcSubjectOptions, type DiscoveryInput, type DpopProofOptions, type DpopProofResult, type IdTokenClaims, type IdTokenFailureCause, type IntrospectionPrincipal, type JoseTokenSignerOptions, type JoseTokenVerifierOptions, type JsonWebKeySet, type JwtAlgorithm, type JwtJwks, type JwtPrincipal, type JwtSubjectOptions, type ReplayStore, type SubjectTokenClaims, type SubjectTokenFailureCause, type VerifyIdTokenOptions, type VerifyIdTokenResult, type VerifySubjectTokenOptions, type VerifySubjectTokenResult, memoryReplayStore };

package/dist/jwt/index.js

@@ -3,10 +3,10 @@ import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
 import { o as epochSeconds, p as nowSeconds } from "../time-DkWjdL98.js";
 import { n as sha256, t as bytesToBase64Url } from "../sha256-D9ihqmvd.js";
 import { t as anonymousSubject } from "../subject-BGoM5o8B.js";
-import { i as linkPolicyViolation, r as capabilitySubject, s as redeemerAllows, t as capabilityFromClaims } from "../capability-N1K9IpqS.js";
+import { i as linkPolicyViolation, r as capabilitySubject, s as redeemerAllows, t as capabilityFromClaims } from "../capability-L7NnfhiE.js";
 import { a as verifierOptions, i as issuerFromDiscovery, n as assertSubjectConfig, o as decodeHeader, r as fail, s as normalizeTyp, t as joseTokenVerifier } from "../verifier-DHuh-okk.js";
 import { t as loadJose } from "../load-jose-DZ4dnjri.js";
-import { n as mapClaimsToSubject, r as validateCustomClaims, t as acceptMismatch } from "../map-claims-D3oRmTk0.js";
+import { i as validateCustomClaims, n as idTokenMismatch, r as mapClaimsToSubject, t as acceptMismatch } from "../map-claims-etGIS_Dv.js";
 import { t as memoryReplayStore } from "../replay-Du1tJjG7.js";
 //#region src/jwt/dpop.ts
 const DPOP_WINDOW_SECONDS = 60;
@@ -124,7 +124,7 @@ function emit(options, reason, cause, token) {
 		requestId: options.requestId
 	}));
 }
-async function claimOnce(replay, key, expiresAt) {
+async function claimOnce$1(replay, key, expiresAt) {
 	if (replay.claim !== void 0) return replay.claim(key, expiresAt);
 	if (await replay.seen(key)) return false;
 	await replay.remember(key, expiresAt);
@@ -136,7 +136,7 @@ async function stores(options, capability, issuedAt, once) {
 		if (policy !== void 0 && linkPolicyViolation(capability, policy, issuedAt) !== void 0) return "link-policy";
 		if (options.revoked !== void 0 && await options.revoked(capability.id)) return "capability-revoked";
 		const replay = options.replay;
-		if (once !== void 0 && (replay === void 0 || !await claimOnce(replay, once.key, once.expiresAt))) return "capability-replayed";
+		if (once !== void 0 && (replay === void 0 || !await claimOnce$1(replay, once.key, once.expiresAt))) return "capability-replayed";
 		return { ok: true };
 	} catch {
 		return {
@@ -318,6 +318,66 @@ async function subjectFromCiOidc(token, options) {
 	});
 }
 //#endregion
+//#region src/jwt/id-token.ts
+/**
+* Verifies an OpenID Connect ID token for a relying party (Core section
+* 3.1.3.7): signature, `iss`, `aud`, `exp`, `iat`, `typ` `JWT` or absent,
+* `azp` and, when `nonce` is given, `nonce`. It does not check `at_hash`,
+* `c_hash`, `auth_time` or `acr`. Never throws.
+*/
+async function verifyIdToken(token, options) {
+	const verifier = options.verifier ?? joseTokenVerifier(compact({
+		jwks: options.jwks,
+		issuer: options.issuer,
+		algorithms: options.algorithms
+	}));
+	let verified;
+	try {
+		verified = await verifier.verify(token, compact({
+			issuer: options.issuer,
+			audience: options.clientId,
+			clockTolerance: options.clockTolerance
+		}));
+	} catch {
+		return {
+			ok: false,
+			cause: "invalid-signature"
+		};
+	}
+	if (!verified.ok) return {
+		ok: false,
+		cause: verified.cause
+	};
+	const { claims, header } = verified;
+	if (idTokenMismatch(claims, header.typ, options.clientId)) return {
+		ok: false,
+		cause: "wrong-token-type"
+	};
+	const { iss, sub, iat } = claims;
+	if (iss !== options.issuer) return {
+		ok: false,
+		cause: "wrong-issuer"
+	};
+	if (typeof sub !== "string" || sub === "" || typeof iat !== "number") return {
+		ok: false,
+		cause: "malformed"
+	};
+	if (options.nonce !== void 0 && claims["nonce"] !== options.nonce) return {
+		ok: false,
+		cause: "nonce-mismatch"
+	};
+	return {
+		ok: true,
+		claims: {
+			...claims,
+			iss,
+			sub,
+			iat
+		},
+		header
+	};
+}
+//#endregion
 //#region src/jwt/introspection.ts
 function emitAuth$1(options, cause) {
 	if (options.onAuth === void 0) return;
@@ -608,4 +668,82 @@ async function resolveSubject(token, options, request) {
 	return extraMemberships(options, mapped.subject, mapped.subject.principal.tenant);
 }
 //#endregion
-export { joseTokenSigner, joseTokenVerifier, jwtSubjectResolver, memoryReplayStore, subjectFromCapability, subjectFromCiOidc, subjectFromIntrospection, subjectFromJwt, verifyDpopProof };
+//#region src/jwt/subject-token.ts
+const DEFAULT_MAX_LIFETIME = 300;
+/** Causes a verifier for another issuer answers; a different cause names the token's real fault. */
+const OTHER_ISSUER = /* @__PURE__ */ new Set(["wrong-issuer", "unknown-kid"]);
+async function firstAccepted(token, options) {
+	const causes = [];
+	for (const verifier of options.verifiers) {
+		let verified;
+		try {
+			verified = await verifier.verify(token, {
+				typ: "at+jwt",
+				audience: options.audience,
+				...options.clockTolerance === void 0 ? {} : { clockTolerance: options.clockTolerance }
+			});
+		} catch {
+			causes.push("invalid-signature");
+			continue;
+		}
+		if (verified.ok) return verified;
+		causes.push(verified.cause);
+	}
+	return { cause: causes.find((cause) => !OTHER_ISSUER.has(cause)) ?? causes[0] ?? "invalid-signature" };
+}
+async function claimOnce(replay, key, expiresAt) {
+	try {
+		if (replay.claim !== void 0) return await replay.claim(key, expiresAt);
+		if (await replay.seen(key)) return false;
+		await replay.remember(key, expiresAt);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Verifies a subject token: an RFC 9068 `at+jwt` naming one subject for one
+* request, such as the `PermDock-Subject` header. The first of `verifiers`
+* that accepts it wins. The token must carry `sub`, `jti`, `iat` and `exp`,
+* live at most `maxLifetime` seconds, and present its `jti` once. A replay
+* store that throws refuses the token as `replayed`. Never throws.
+*/
+async function verifySubjectToken(token, options) {
+	const verified = await firstAccepted(token, options);
+	if (!("ok" in verified)) return {
+		ok: false,
+		cause: verified.cause
+	};
+	if (normalizeTyp(verified.header.typ)?.toLowerCase() !== "at+jwt") return {
+		ok: false,
+		cause: "wrong-token-type"
+	};
+	const { claims } = verified;
+	const { sub, jti, iat, exp } = claims;
+	if (typeof sub !== "string" || sub === "" || typeof jti !== "string" || jti === "" || typeof iat !== "number" || typeof exp !== "number") return {
+		ok: false,
+		cause: "malformed"
+	};
+	if (exp - iat > (options.maxLifetime ?? DEFAULT_MAX_LIFETIME)) return {
+		ok: false,
+		cause: "lifetime-exceeded"
+	};
+	const key = `subject-token\n${claims.iss ?? ""}\n${jti}`;
+	if (!await claimOnce(options.replay, key, exp + (options.clockTolerance ?? 0))) return {
+		ok: false,
+		cause: "replayed"
+	};
+	return {
+		ok: true,
+		claims: {
+			...claims,
+			sub,
+			jti,
+			iat,
+			exp
+		},
+		header: verified.header
+	};
+}
+//#endregion
+export { joseTokenSigner, joseTokenVerifier, jwtSubjectResolver, memoryReplayStore, subjectFromCapability, subjectFromCiOidc, subjectFromIntrospection, subjectFromJwt, verifyDpopProof, verifyIdToken, verifySubjectToken };

package/dist/{kernel-D0NVb1cK.js → kernel-DVExUwkp.js}

@@ -1,13 +1,17 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { t as describe } from "./describe-BybMRY7A.js";
+import { i as stepUpOf } from "./problem-details-cn5X30gZ.js";
+import { t as describe } from "./describe-DZlnEtLy.js";
 import { a as deniedMessage } from "./errors-BKy0EfhN.js";
-import { t as actorMayCallTool } from "./delegation-j6-rc37o.js";
+import { t as actorMayCallTool } from "./delegation-C5rOdTp5.js";
+import { c as nowSeconds, r as isMembershipExpired } from "./tenancy-CmeBQ6Nv.js";
+import { k as activate } from "./evaluate-B_oqFbWC.js";
 import { n as resourceRef } from "./resource-ref-CaS9yVPi.js";
-import { c as withApp } from "./permdock-BrAscV28.js";
-import { l as storedApprovalToken, s as resumeDecision } from "./helpers-CBYVMjwh.js";
-import { n as resolveOrNull } from "./build-instance-Bu_eDqYw.js";
+import { n as delegationAllows } from "./where-scope-wq2coopv.js";
+import { l as withApp } from "./permdock-BfWEeMqk.js";
+import { l as storedApprovalToken, s as resumeDecision } from "./helpers-DY3vXuGs.js";
+import { n as resolveOrNull } from "./build-instance-DxE7czo9.js";
 import { n as tenantScope, t as actorFrom } from "./adapter-context-CRhqyzCk.js";
-import { n as requestContext, t as buildReportingInstance } from "./request-context-C81Pip9n.js";
+import { n as requestContext, t as buildReportingInstance } from "./request-context-BykKLmyE.js";
 //#region src/agent/denied-text.ts
 /** The hook's text, or `event.text` when there is no hook or it throws or returns no string. */
 function refusalText(hook, event, report) {
@@ -35,6 +39,126 @@ function thrownReason(toolName) {
 	return `Denied: ${toolName} failed closed.`;
 }
 //#endregion
+//#region src/agent/step-up.ts
+/** Denials neither a fresh sign-in nor an activation can lift. */
+const FINAL = /* @__PURE__ */ new Set([
+	"deny",
+	"validation",
+	"anonymous",
+	"not-delegated",
+	"no-delegation",
+	"agent-tool-not-delegated",
+	"approval",
+	"stale-approval"
+]);
+/** Activation denials the activation flow itself asks the user to fix. */
+const ACTIVATION_ASKS = /* @__PURE__ */ new Set(["reason-required", "insufficient-user-authentication"]);
+function elevated(membership, role) {
+	return compact({
+		scope: membership.scope,
+		id: membership.id,
+		within: membership.within,
+		roles: [role],
+		via: "elevated"
+	});
+}
+function activationFor(permdock, permission, data) {
+	const held = permdock.subject.principal?.memberships ?? [];
+	const now = nowSeconds();
+	for (const membership of held) {
+		const { scope, id } = membership;
+		if (scope === void 0 || id === void 0 || isMembershipExpired(membership, now)) continue;
+		for (const role of membership.eligible ?? []) {
+			const offered = activate(permdock, compact({
+				role,
+				scope,
+				id,
+				within: membership.within
+			}));
+			if (offered.outcome === "denied" && !offered.denials.every((denial) => ACTIVATION_ASKS.has(denial.reason))) continue;
+			const [decision] = permdock.simulate({ memberships: [...held, elevated({
+				...membership,
+				scope,
+				id
+			}, role)] }).simulate([[permission, data]]);
+			if (decision !== void 0 && decision.outcome !== "denied") return compact({
+				kind: "activation",
+				role,
+				scope,
+				id,
+				within: membership.within
+			});
+		}
+	}
+}
+/**
+* The step-up that could lift `decision`, or `undefined`. A denial with
+* `insufficient-user-authentication` asks for a fresh sign-in when the
+* delegation and the actor still cover the permission; any other
+* denial asks for the first eligible role whose activation the simulated
+* decision grants. A matched deny, a validation failure, an anonymous
+* subject, a delegation that does not cover the call, an undelegated tool
+* and a failed approval resume never step up.
+*/
+function stepUpFor(permdock, permission, data, decision) {
+	if (decision.outcome !== "denied" || decision.denials.length === 0 || decision.denials.some((denial) => FINAL.has(denial.reason))) return;
+	try {
+		if (decision.denials.some((denial) => denial.reason === "insufficient-user-authentication")) return delegationAllows(permdock, permission) ? {
+			kind: "authentication",
+			...stepUpOf(decision)
+		} : void 0;
+		return activationFor(permdock, permission, data);
+	} catch {
+		return;
+	}
+}
+/**
+* The subject's instance with every eligible role activated, for a tool
+* listing that keeps tools an activation would open. `undefined` when the
+* subject is eligible for nothing.
+*/
+function eligiblePreview(permdock) {
+	const held = permdock.subject.principal?.memberships ?? [];
+	const now = nowSeconds();
+	const activations = held.flatMap((membership) => {
+		const { scope, id } = membership;
+		return scope === void 0 || id === void 0 || isMembershipExpired(membership, now) ? [] : (membership.eligible ?? []).map((role) => elevated({
+			...membership,
+			scope,
+			id
+		}, role));
+	});
+	if (activations.length === 0) return;
+	try {
+		return permdock.simulate({ memberships: [...held, ...activations] });
+	} catch {
+		return;
+	}
+}
+/** The URL the user signs in again at, with the RFC 9470 `acr_values` and `max_age` added. */
+function signInUrl(at, stepUp) {
+	let url;
+	try {
+		url = new URL(at);
+	} catch {
+		return;
+	}
+	if (stepUp.acrValues !== void 0 && stepUp.acrValues.length > 0) url.searchParams.set("acr_values", stepUp.acrValues.join(" "));
+	if (stepUp.maxAge !== void 0) url.searchParams.set("max_age", String(stepUp.maxAge));
+	return url.href;
+}
+/** The sentence the user reads on the step-up prompt. */
+function stepUpText(stepUp, permission, at) {
+	switch (stepUp.kind) {
+		case "authentication": {
+			const url = at === void 0 ? void 0 : signInUrl(at, stepUp);
+			return url === void 0 ? `Sign in again to use ${permission.key}.` : `Sign in again to use ${permission.key}: ${url}`;
+		}
+		case "activation": return `Activate the ${stepUp.role} role on ${stepUp.scope} ${stepUp.id} to use ${permission.key}.`;
+		default: return stepUp;
+	}
+}
+//#endregion
 //#region src/agent/kernel.ts
 /** The resume token an agent run carries under the namespaced `permdockApproval` key. */
 function approvalTokenOf(context) {
@@ -210,12 +334,13 @@ function createAgentKernel(policy, given) {
 			token: decision.token,
 			summary: modelReason(decision, binding.permission, permdock.subject.principal?.id)
 		};
-		return {
+		return compact({
 			outcome: "denied",
 			decision,
 			permission: binding.permission,
-			reason: modelReason(decision, binding.permission, permdock.subject.principal?.id)
-		};
+			reason: modelReason(decision, binding.permission, permdock.subject.principal?.id),
+			stepUp: options.stepUp === true ? stepUpFor(permdock, binding.permission, data, decision) : void 0
+		});
 	};
 	const evaluate = async (binding, toolName, args, context, decideOptions = {}) => {
 		const checked = await check(binding, args, context, {
@@ -265,10 +390,11 @@ function createAgentKernel(policy, given) {
 		}, void 0));
 		return evaluate(binding, toolName, args, context, decideOptions);
 	};
-	const allowedToolNames = async (context) => {
+	const allowedToolNames = async (context, listOptions = {}) => {
 		const permdock = await instance(context);
+		const preview = listOptions.eligible === true ? eligiblePreview(permdock) : void 0;
 		const allowed = /* @__PURE__ */ new Set();
-		for (const [name, binding] of Object.entries(tools)) if (actorMayCallTool(permdock.subject.actor, name) && permdock.mayUse(binding.permission)) allowed.add(name);
+		for (const [name, binding] of Object.entries(tools)) if (actorMayCallTool(permdock.subject.actor, name) && (permdock.mayUse(binding.permission) || preview?.mayUse(binding.permission) === true)) allowed.add(name);
 		return allowed;
 	};
 	return {
@@ -282,4 +408,4 @@ function createAgentKernel(policy, given) {
 	};
 }
 //#endregion
-export { createAgentKernel as n, refusalText as r, approvalTokenOf as t };
+export { refusalText as i, createAgentKernel as n, stepUpText as r, approvalTokenOf as t };

package/dist/kysely/index.d.ts

@@ -1,7 +1,7 @@
-import { Rt as Instant, ar as Subject, ur as Condition } from "../policy-types-n0uRTsW8.js";
-import { c as WhereResult } from "../permdock-SV8ZINYT.js";
+import { Rt as Instant, lr as Subject, mr as Condition } from "../policy-types-B-F-qAZk.js";
+import { u as WhereResult } from "../permdock-Dco6dyCK.js";
 import { r as RelationsMapping } from "../graph-sql-B-dsAT6j.js";
-import { s as MembershipsMapping } from "../compile-1bsAezL0.js";
+import { s as MembershipsMapping } from "../compile-COM2VKuN.js";
 import { n as WithSubjectOptions, t as RowCheck } from "../row-check-Dt35czLy.js";
 //#region src/kysely/types.d.ts
 type KyselySelectQuery = {

package/dist/kysely/index.js

@@ -1,6 +1,6 @@
 import { t as compact } from "../compact-CAf557ZB.js";
 import { t as assertSafeKey } from "../paths-DXSHAMIa.js";
-import { n as escapeLike, t as compileWhere } from "../compile-CMqMx_IN.js";
+import { n as escapeLike, t as compileWhere } from "../compile-BAEO5bOk.js";
 import { a as rowCheckFrom, i as templateOf, r as subjectStatements, s as loadPeer, t as statementTemplate } from "../subject-settings-CkEwrw3W.js";
 //#region src/kysely/to-where.ts
 function ident(name) {

package/dist/load-DrMHXzgN.js

@@ -0,0 +1 @@
+export { a as loadModule, s as pickNamed } from "./load-DxroEzH1.js";

package/dist/{load-DFS_ry0W.js → load-DxroEzH1.js}

@@ -1,5 +1,5 @@
-import { c as listPermissions } from "./permission-registry-Br4jSNVi.js";
-import { a as describeError, n as CliError } from "./errors-CWTY6uih.js";
+import { c as listPermissions } from "./permission-registry-DpPtSKNZ.js";
+import { a as describeError, n as CliError } from "./errors-DpP_U6Bf.js";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createJiti } from "jiti";

package/dist/{login-Dfe5RlYk.js → login-ClSJh5t5.js}

@@ -1,5 +1,5 @@
 import { t as defineLeaf } from "./command-L8EstFNm.js";
-import { c as given } from "./flags-C3DktBDY.js";
+import { c as given } from "./flags-aaeRAdiD.js";
 //#region src/cli/commands/login.ts
 const urlFlag = { url: {
 	type: "string",
@@ -27,7 +27,7 @@ const login = defineLeaf({
 		}
 	},
 	async run(ctx, { flags }) {
-		const { runLogin } = await import("./login-imhuwvn3.js");
+		const { runLogin } = await import("./login-WC9HPJpU.js");
 		return runLogin({
 			cwd: ctx.cwd,
 			url: given(flags.url),
@@ -43,7 +43,7 @@ const login = defineLeaf({
 const logout = defineLeaf({
 	flags: { ...urlFlag },
 	async run(ctx, { flags }) {
-		const { runLogout } = await import("./login-imhuwvn3.js");
+		const { runLogout } = await import("./login-WC9HPJpU.js");
 		return runLogout({
 			url: given(flags.url),
 			json: ctx.json,
@@ -55,7 +55,7 @@ const logout = defineLeaf({
 const whoami = defineLeaf({
 	flags: { ...urlFlag },
 	async run(ctx, { flags }) {
-		const { runWhoami } = await import("./login-imhuwvn3.js");
+		const { runWhoami } = await import("./login-WC9HPJpU.js");
 		return runWhoami({
 			url: given(flags.url),
 			json: ctx.json,

package/dist/{login-imhuwvn3.js → login-WC9HPJpU.js}

@@ -1,18 +1,15 @@
 import { h as secondsAt, i as dateAt, s as instantAt } from "./time-DkWjdL98.js";
-import { n as CliError } from "./errors-CWTY6uih.js";
+import { n as CliError } from "./errors-DpP_U6Bf.js";
 import { i as postForm, r as parseToken, s as runDeviceFlow } from "./device-BARQ8eYG.js";
 import { i as writeCredentials, n as deleteCredentials, r as readCredentials, t as credentialsPath } from "./storage-C2bWdvJH.js";
-import { n as httpRequest } from "./http-DXJ37RDA.js";
-import { c as READ_SCOPES, d as issuerMetadata, i as credentialsInsideRepository, l as cloudUrl, n as cliRuntime, r as credentialStorage, s as CLI_CLIENT_ID, t as CREDENTIAL_SERVICE } from "./auth-DRLEizbL.js";
-import { createHash, randomBytes } from "node:crypto";
+import { n as randomToken, t as pkce } from "./pkce-5h8NgMQJ.js";
+import { n as httpRequest } from "./http-Ca3Sr5x1.js";
+import { c as READ_SCOPES, d as issuerMetadata, i as credentialsInsideRepository, l as cloudUrl, n as cliRuntime, r as credentialStorage, s as CLI_CLIENT_ID, t as CREDENTIAL_SERVICE } from "./auth-CscUX8Sy.js";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 //#region src/cli/cloud/loopback.ts
 /** How long the loopback listener waits for the browser to come back. */
 const LOOPBACK_TIMEOUT_MS = 3e5;
-function base64url(bytes) {
-	return bytes.toString("base64url");
-}
 function listen(server) {
 	return new Promise((resolve, reject) => {
 		server.once("error", reject);
@@ -28,9 +25,8 @@ function listen(server) {
 * `state` that the callback must echo.
 */
 async function runLoopbackFlow(options, runtime) {
-	const verifier = base64url(randomBytes(32));
-	const challenge = base64url(createHash("sha256").update(verifier).digest());
-	const state = base64url(randomBytes(16));
+	const { verifier, challenge } = await pkce();
+	const state = randomToken(16);
 	const { promise: callback, resolve: settle } = Promise.withResolvers();
 	const server = createServer((request, response) => {
 		const url = new URL(request.url ?? "/", "http://127.0.0.1");

package/dist/{manifest-C8IzW3Do.js → manifest-B79YuF2T.js}

@@ -1,8 +1,12 @@
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
 import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
 import { n as copyJson, t as checkSchema } from "./json-schema-B-vAwlde.js";
-import { t as supabaseManifestSchema } from "./manifest-schema-C0kK_8V0.js";
+import { t as supabaseManifestSchema } from "./manifest-schema-Cv492Qev.js";
 //#region src/supabase/manifest.ts
+/** Whether the manifest describes a token hook. */
+function hasTokenHook(manifest) {
+	return "hook" in manifest;
+}
 /**
 * Reads a `permdock.manifest.json` document (parsed, or the JSON text) and
 * validates it against `schemas/supabase-manifest-v1.json`. Returns a
@@ -39,4 +43,4 @@ function invalidManifest(issues) {
 	});
 }
 //#endregion
-export { parseSupabaseManifest as t };
+export { parseSupabaseManifest as n, hasTokenHook as t };