permdock 0.6.0 → 0.8.0

package/dist/jwt/index.d.ts

@@ -1,10 +1,13 @@
-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-CCiDRZBH.js";
+import { c as LinkPolicy, o as CapabilityPrincipal, t as Capability } from "../capability-ChuiONQU.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-DjuMBNF9.js";
+import { t as memoryReplayStore } from "../replay-DNftIb_R.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. */
+/**
+ * `on('auth')` causes: a verification failure, or one of the three capability
+ * checks.
+ */
 type CapabilityFailureCause = TokenFailureCause | "capability-revoked" | "capability-replayed" | "redeemer-mismatch" | "link-policy";
 type CapabilitySubjectOptions = Omit<JoseTokenVerifierOptions, "typ" | "issuer" | "audience" | "profile"> & {
   /** The issuer the capability was signed by (`iss`); required. */
@@ -13,20 +16,26 @@ type CapabilitySubjectOptions = Omit<JoseTokenVerifierOptions, "typ" | "issuer"
   readonly audience: string | readonly string[];
   readonly verifier?: TokenVerifier;
   /**
-   * The link policies of the scope instances the linked resource sits in
-   * (its tenant, its customer); every one must hold. A throw denies.
+   * The link policies of the scope instances the linked resource sits in (its
+   * tenant, its customer); every one must hold. A throw denies.
    */
   readonly linkPolicy?: (capability: Capability) => LinkPolicy | readonly LinkPolicy[] | undefined | Promise<LinkPolicy | readonly LinkPolicy[] | undefined>;
   /** `true` when the application revoked the link id (`sub`); a throw denies. */
   readonly revoked?: (id: string) => boolean | Promise<boolean>;
-  /** Claims the `jti` of a one-time capability; a one-time capability without it is refused. */
+  /**
+   * Claims the `jti` of a one-time capability; a one-time capability without it
+   * is refused.
+   */
   readonly replay?: ReplayStore;
-  /** The request's own verified subject, checked against the capability's `redeemer`. */
+  /**
+   * The request's own verified subject, checked against the capability's
+   * `redeemer`.
+   */
   readonly viewer?: Subject;
   /**
    * The incoming request. A capability with `cnf` resolves only when the
-   * request carries a DPoP proof (RFC 9449) signed by the bound key;
-   * without one it is refused.
+   * request carries a DPoP proof (RFC 9449) signed by the bound key; without
+   * one it is refused.
    */
   readonly request?: Request;
   readonly onAuth?: (event: AuthEvent) => void;
@@ -34,8 +43,8 @@ type CapabilitySubjectOptions = Omit<JoseTokenVerifierOptions, "typ" | "issuer"
 };
 /**
  * Resolves a `vnd.permdock.capability+jwt` into the `link` subject it acts as.
- * Every failure (signature, `typ`, `iss`, `aud`, expiry, a malformed claim,
- * a revoked link, a replayed one-time token, a redeemer the viewer does not
+ * Every failure (signature, `typ`, `iss`, `aud`, expiry, a malformed claim, a
+ * revoked link, a replayed one-time token, a redeemer the viewer does not
  * satisfy, a `cnf` without a matching DPoP proof, a throwing store) is the
  * anonymous subject, never a throw.
  */
@@ -52,13 +61,19 @@ type CiOidcSubjectOptions = Omit<JoseTokenVerifierOptions, "typ" | "issuer" | "a
    * from OpenID discovery unless `jwks` is set.
    */
   readonly issuer?: string;
-  /** Validates the verified claims; a failure or a Promise is the anonymous subject. */
+  /**
+   * Validates the verified claims; a failure or a Promise is the anonymous
+   * subject.
+   */
   readonly schema?: StandardSchemaV1;
   readonly verifier?: TokenVerifier;
   readonly onAuth?: (event: AuthEvent) => void;
   readonly requestId?: string;
 };
-/** A CI job: never a user. `ref` is a full ref (`refs/heads/main`, `refs/tags/v1`). */
+/**
+ * A CI job: never a user. `ref` is a full ref (`refs/heads/main`,
+ * `refs/tags/v1`).
+ */
 type CiOidcPrincipal = Principal & {
   readonly kind: "workload";
   readonly issuer: string;
@@ -77,11 +92,62 @@ export declare function subjectFromCiOidc(token: string | undefined | null, opti
 //#endregion
 //#region src/jwt/dpop.d.ts
 type DpopProofOptions = {
-  /** Rejects a proof whose `jti` this key already used within the 60-second window. */
+  /**
+   * Rejects a proof whose `jti` this key already used within the 60-second
+   * window.
+   */
   readonly replay?: ReplayStore;
 };
 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 +158,49 @@ 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

@@ -1,13 +1,13 @@
 import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
-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 { n as freezeDeep } from "../freeze-jjan0lCv.js";
+import { o as epochSeconds, p as nowSeconds } from "../time-nR1JesoH.js";
+import { n as sha256, t as bytesToBase64Url } from "../sha256-C-4WXKIu.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 { 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 { i as linkPolicyViolation, r as capabilitySubject, s as redeemerAllows, t as capabilityFromClaims } from "../capability-BqX94r07.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-DUV6pLqZ.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 { t as memoryReplayStore } from "../replay-Du1tJjG7.js";
+import { i as validateCustomClaims, n as idTokenMismatch, r as mapClaimsToSubject, t as acceptMismatch } from "../map-claims-BNWCJtmP.js";
+import { t as memoryReplayStore } from "../replay-BU09ad4L.js";
 //#region src/jwt/dpop.ts
 const DPOP_WINDOW_SECONDS = 60;
 const PROOF_ALGS = /* @__PURE__ */ new Set([
@@ -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 {
@@ -147,8 +147,8 @@ async function stores(options, capability, issuedAt, once) {
 }
 /**
 * Resolves a `vnd.permdock.capability+jwt` into the `link` subject it acts as.
-* Every failure (signature, `typ`, `iss`, `aud`, expiry, a malformed claim,
-* a revoked link, a replayed one-time token, a redeemer the viewer does not
+* Every failure (signature, `typ`, `iss`, `aud`, expiry, a malformed claim, a
+* revoked link, a replayed one-time token, a redeemer the viewer does not
 * satisfy, a `cnf` without a matching DPoP proof, a throwing store) is the
 * anonymous subject, never a throw.
 */
@@ -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;
@@ -492,10 +552,10 @@ function mtlsThumbprint(claims) {
 }
 /**
 * The sender constraint to enforce. Without a configured `sender`, a token
-* whose `cnf` binds it to a key or a certificate is held to that binding,
-* never accepted as a bearer token (RFC 9449 section 7.1, RFC 8705
-* section 3). An explicit `sender: "none"` is the opt-out for a gateway
-* that verified the binding upstream.
+* whose `cnf` binds it to a key or a certificate is held to that binding, never
+* accepted as a bearer token (RFC 9449 section 7.1, RFC 8705 section 3). An
+* explicit `sender: "none"` is the opt-out for a gateway that verified the
+* binding upstream.
 */
 function senderFor(options, cnf) {
 	if (options.sender !== void 0) return options.sender;
@@ -608,4 +668,85 @@ 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-C-fYydV2.js}

@@ -1,15 +1,22 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { t as describe } from "./describe-BybMRY7A.js";
-import { a as deniedMessage } from "./errors-BKy0EfhN.js";
-import { t as actorMayCallTool } from "./delegation-j6-rc37o.js";
+import { i as stepUpOf } from "./problem-details-CLDgX1KV.js";
+import { n as describe } from "./describe-Bb4hGK5d.js";
+import { a as deniedMessage } from "./errors-B6R_lg2a.js";
+import { t as actorMayCallTool } from "./delegation-CDB6_keF.js";
+import { c as nowSeconds, r as isMembershipExpired } from "./tenancy-5d1zVBvK.js";
+import { k as activate } from "./evaluate-Dd8Ta0Ie.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 tenantScope, t as actorFrom } from "./adapter-context-CRhqyzCk.js";
-import { n as requestContext, t as buildReportingInstance } from "./request-context-C81Pip9n.js";
+import { n as delegationAllows } from "./where-scope-DlCdCM_8.js";
+import { l as withApp } from "./permdock-L-_I_3zP.js";
+import { l as storedApprovalToken, s as resumeDecision } from "./helpers-DJicaG6f.js";
+import { n as resolveOrNull } from "./build-instance-CNWaYJyr.js";
+import { n as tenantScope, t as actorFrom } from "./adapter-context-CIQpQxbE.js";
+import { n as requestContext, t as buildReportingInstance } from "./request-context-C25ilqiJ.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. */
+/**
+* The hook's text, or `event.text` when there is no hook or it throws or
+* returns no string.
+*/
 function refusalText(hook, event, report) {
 	if (hook === void 0) return event.text;
 	try {
@@ -35,8 +42,134 @@ 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. */
+/**
+* The resume token an agent run carries under the namespaced `permdockApproval`
+* key.
+*/
 function approvalTokenOf(context) {
 	if (context === null || typeof context !== "object") return;
 	const token = context.permdockApproval;
@@ -210,12 +343,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 +399,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 +417,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 };