permdock 0.3.1 → 0.5.0

package/dist/{manifest-uDS9y5de.d.ts → manifest-mx5ghSFM.d.ts}

@@ -13,6 +13,13 @@ type SupabaseHookManifest = {
     readonly schema: string;
     readonly function: "custom_access_token_hook";
     readonly out: string;
+    /**
+     * How the project turns SQL into migrations: `pg-delta` (`supabase db
+     * schema declarative sync`, which keeps the hook's grants in `out`),
+     * `migra` (`supabase db diff`, which drops them) or `migrations`
+     * (hand-written). Absent means `pg-delta`.
+     */
+    readonly schemas?: "pg-delta" | "migra" | "migrations";
     readonly before?: readonly string[];
   };
   readonly helpers: {
@@ -91,7 +98,7 @@ type SupabaseManifestThrough = {
 type SupabaseManifestRole = SupabaseManifestValue | (SupabaseManifestColumn & {
   readonly through: SupabaseManifestThrough;
 });
-/** One `fromTable` or `fromJunction` source. */
+/** One `tableMembershipSource` or `junctionMembershipSource` source. */
 type SupabaseManifestMembership = {
   /** `schema.table`, `public` when the source names no schema. */
   readonly table: string;
@@ -99,7 +106,7 @@ type SupabaseManifestMembership = {
   readonly user: SupabaseManifestColumn | (SupabaseManifestColumn & {
     readonly through: SupabaseManifestThrough;
   });
-  /** A column for `fromTable`, the fixed scope for `fromJunction`. */
+  /** A column for `tableMembershipSource`, the fixed scope for `junctionMembershipSource`. */
   readonly scope: SupabaseManifestValue;
   readonly id: SupabaseManifestColumn;
   /** A role column, the fixed roles every row holds, or several role columns whose keys the row holds together. */

package/dist/manifest-schema-C0kK_8V0.js

@@ -0,0 +1,399 @@
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+//#region src/supabase/manifest-schema.ts
+/** `schemas/supabase-manifest-v1.json`, which `parseSupabaseManifest` checks against; a test keeps the two equal. */
+const supabaseManifestSchema = freezeDeep({
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://permdock.com/schemas/supabase-manifest-v1.json",
+	title: "PermDock Supabase hook manifest v1",
+	description: "What `permdock supabase inspect --json` prints and `--out` writes: the generated hook, the SQL helpers, the claims, the membership sources and the columns that decide them. Fields are only added within v1.",
+	type: "object",
+	required: [
+		"$schema",
+		"version",
+		"hook",
+		"helpers",
+		"tenantClaim",
+		"budget",
+		"claims",
+		"authzVersion",
+		"memberships",
+		"rls",
+		"decidingColumns",
+		"markers"
+	],
+	properties: {
+		$schema: { const: "https://permdock.com/schemas/supabase-manifest-v1.json" },
+		version: { const: 1 },
+		hook: {
+			type: "object",
+			required: [
+				"schema",
+				"function",
+				"out"
+			],
+			properties: {
+				schema: { $ref: "#/$defs/identifier" },
+				function: { const: "custom_access_token_hook" },
+				out: { type: "string" },
+				schemas: {
+					enum: [
+						"pg-delta",
+						"migra",
+						"migrations"
+					],
+					description: "How the project turns SQL into migrations: pg-delta (supabase db schema declarative sync), migra (supabase db diff) or hand-written migrations. Absent means pg-delta."
+				},
+				before: {
+					type: "array",
+					items: {
+						type: "string",
+						pattern: "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+					}
+				}
+			}
+		},
+		helpers: {
+			type: "object",
+			required: ["schema", "functions"],
+			properties: {
+				schema: { $ref: "#/$defs/identifier" },
+				functions: {
+					type: "array",
+					items: { $ref: "#/$defs/helperName" }
+				}
+			}
+		},
+		tenantClaim: { $ref: "#/$defs/identifier" },
+		budget: {
+			type: "object",
+			required: ["bytes", "measure"],
+			properties: {
+				bytes: {
+					type: "integer",
+					minimum: 1
+				},
+				measure: { type: "string" }
+			}
+		},
+		claims: {
+			type: "array",
+			items: {
+				type: "object",
+				required: [
+					"name",
+					"source",
+					"budget"
+				],
+				properties: {
+					name: { $ref: "#/$defs/identifier" },
+					source: {
+						type: "string",
+						pattern: "^(permdock|[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*)$"
+					},
+					budget: { type: "boolean" }
+				}
+			}
+		},
+		authzVersion: { type: "boolean" },
+		authzVersionBump: {
+			type: "object",
+			required: [
+				"schema",
+				"function",
+				"args"
+			],
+			properties: {
+				schema: { $ref: "#/$defs/identifier" },
+				function: { const: "permdock_bump_authz_version_for" },
+				args: { const: "p_users uuid[]" }
+			}
+		},
+		memberships: {
+			type: "array",
+			items: { $ref: "#/$defs/membership" }
+		},
+		rls: {
+			type: "object",
+			required: [
+				"schema",
+				"mode",
+				"tenantClaim",
+				"scopes",
+				"helpers",
+				"memberships"
+			],
+			properties: {
+				schema: { $ref: "#/$defs/identifier" },
+				mode: { enum: ["jwt", "database"] },
+				tenantClaim: { $ref: "#/$defs/identifier" },
+				scopes: {
+					type: "array",
+					items: {
+						type: "object",
+						required: ["name", "type"],
+						properties: {
+							name: {
+								type: "string",
+								pattern: "^[a-z][a-z0-9_]*$"
+							},
+							type: { type: "string" },
+							within: {
+								type: "string",
+								pattern: "^[a-z][a-z0-9_]*$"
+							}
+						}
+					}
+				},
+				helpers: {
+					type: "array",
+					items: {
+						type: "object",
+						required: [
+							"name",
+							"args",
+							"returns",
+							"execute"
+						],
+						properties: {
+							name: { $ref: "#/$defs/helperName" },
+							args: { type: "string" },
+							returns: { type: "string" },
+							execute: {
+								type: "array",
+								items: { enum: [
+									"anon",
+									"authenticated",
+									"supabase_auth_admin"
+								] }
+							}
+						}
+					}
+				},
+				memberships: {
+					type: "array",
+					items: { $ref: "#/$defs/membership" }
+				},
+				customRoles: { type: "boolean" },
+				roles: {
+					type: "object",
+					required: [
+						"table",
+						"user",
+						"role"
+					],
+					additionalProperties: false,
+					properties: {
+						table: { type: "string" },
+						user: { $ref: "#/$defs/column" },
+						role: { oneOf: [{ $ref: "#/$defs/role" }, {
+							type: "array",
+							minItems: 2,
+							items: { $ref: "#/$defs/role" }
+						}] }
+					}
+				},
+				suspension: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						users: { $ref: "#/$defs/activeRow" },
+						scopes: {
+							type: "object",
+							additionalProperties: { $ref: "#/$defs/activeRow" }
+						},
+						memberships: {
+							type: "object",
+							required: ["keep"],
+							additionalProperties: false,
+							properties: { keep: {
+								description: "The permission keys a membership whose disabledAt column is set still holds.",
+								type: "array",
+								items: { type: "string" }
+							} }
+						}
+					}
+				},
+				assignments: {
+					type: "object",
+					required: ["tables"],
+					additionalProperties: false,
+					properties: { tables: {
+						type: "array",
+						items: { type: "string" }
+					} }
+				},
+				apiKeys: {
+					type: "object",
+					required: [
+						"claim",
+						"scopes",
+						"tenant",
+						"roles",
+						"serviceRoles"
+					],
+					additionalProperties: false,
+					properties: {
+						claim: { type: "string" },
+						scopes: { type: "string" },
+						tenant: { type: "string" },
+						roles: { type: "string" },
+						serviceRoles: {
+							type: "array",
+							items: { type: "string" }
+						}
+					}
+				}
+			}
+		},
+		decidingColumns: {
+			type: "array",
+			items: {
+				type: "string",
+				pattern: "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+			}
+		},
+		markers: {
+			type: "object",
+			required: ["hook", "grants"],
+			properties: {
+				hook: { const: "v1" },
+				grants: { const: "v1" }
+			}
+		},
+		requires: {
+			description: "The supabase/sdk capability-matrix feature ids the hook, the helpers and subjectFromSupabase depend on, as of the matrix release tag.",
+			type: "object",
+			required: ["matrix", "capabilities"],
+			additionalProperties: false,
+			properties: {
+				matrix: {
+					type: "string",
+					pattern: "^capability-matrix-v1\\.[0-9]+\\.[0-9]+$"
+				},
+				capabilities: {
+					type: "array",
+					uniqueItems: true,
+					items: {
+						type: "string",
+						pattern: "^[a-z][a-z0-9_]*\\.[a-z0-9_]+\\.[a-z0-9_]+$"
+					}
+				}
+			}
+		}
+	},
+	$defs: {
+		membership: {
+			type: "object",
+			required: [
+				"table",
+				"user",
+				"scope",
+				"id",
+				"role",
+				"columns"
+			],
+			properties: {
+				table: {
+					type: "string",
+					pattern: "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+				},
+				user: { $ref: "#/$defs/user" },
+				scope: { $ref: "#/$defs/value" },
+				id: { $ref: "#/$defs/column" },
+				role: { oneOf: [{ $ref: "#/$defs/role" }, {
+					type: "array",
+					minItems: 2,
+					items: { $ref: "#/$defs/role" }
+				}] },
+				within: { oneOf: [{ $ref: "#/$defs/column" }, {
+					type: "object",
+					required: ["columns"],
+					additionalProperties: false,
+					properties: { columns: {
+						type: "object",
+						additionalProperties: { $ref: "#/$defs/identifier" }
+					} }
+				}] },
+				via: { $ref: "#/$defs/value" },
+				expiresAt: { $ref: "#/$defs/column" },
+				disabledAt: { $ref: "#/$defs/column" },
+				columns: {
+					type: "array",
+					items: { $ref: "#/$defs/identifier" }
+				}
+			}
+		},
+		identifier: {
+			type: "string",
+			pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+		},
+		activeRow: {
+			type: "object",
+			required: ["table", "id"],
+			additionalProperties: false,
+			properties: {
+				table: { type: "string" },
+				id: { $ref: "#/$defs/identifier" },
+				disabledAt: { $ref: "#/$defs/identifier" },
+				status: { $ref: "#/$defs/identifier" },
+				active: {
+					type: "array",
+					items: { type: "string" }
+				},
+				keep: {
+					description: "A scope only: the permission keys members of a suspended instance still hold.",
+					type: "array",
+					items: { type: "string" }
+				}
+			}
+		},
+		helperName: {
+			type: "string",
+			pattern: "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
+		},
+		column: {
+			type: "object",
+			required: ["column"],
+			additionalProperties: false,
+			properties: { column: { $ref: "#/$defs/identifier" } }
+		},
+		role: { oneOf: [{ $ref: "#/$defs/value" }, { $ref: "#/$defs/through" }] },
+		user: { oneOf: [{ $ref: "#/$defs/column" }, { $ref: "#/$defs/through" }] },
+		through: {
+			type: "object",
+			required: ["column", "through"],
+			additionalProperties: false,
+			properties: {
+				column: { $ref: "#/$defs/identifier" },
+				through: {
+					type: "object",
+					required: [
+						"table",
+						"id",
+						"column"
+					],
+					additionalProperties: false,
+					properties: {
+						table: {
+							type: "string",
+							pattern: "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+						},
+						id: { $ref: "#/$defs/identifier" },
+						column: { $ref: "#/$defs/identifier" }
+					}
+				}
+			}
+		},
+		value: { oneOf: [{ $ref: "#/$defs/column" }, {
+			type: "object",
+			required: ["value"],
+			additionalProperties: false,
+			properties: { value: { oneOf: [{ type: "string" }, {
+				type: "array",
+				items: { type: "string" }
+			}] } }
+		}] }
+	}
+});
+//#endregion
+export { supabaseManifestSchema as t };

package/dist/{map-claims-Z4QZOiFF.js → map-claims-D3oRmTk0.js}

@@ -1,8 +1,10 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { O as readPath, T as isForbiddenKey } from "./permissions-DVoF6dMt.js";
-import { t as ignoreRejection } from "./thenable-okc2xDsj.js";
-import { t as anonymousSubject } from "./subject-C6dLxqHU.js";
+import { n as isForbiddenKey, o as readPath } from "./paths-DXSHAMIa.js";
+import { n as expirySeconds } from "./expiry-D4_YKRKD.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 { t as clientNameOf } from "./clients-DjU5ABMy.js";
 //#region src/jwt/map-claims.ts
 /** OpenID Connect Core section 5.1: profile data the provider owns. */
@@ -72,13 +74,10 @@ function assuranceOf(claims, paths) {
 	});
 	return Object.keys(assurance).length === 0 ? void 0 : assurance;
 }
-function isPlainRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function hasForbiddenKey(value, depth = 0) {
 	if (depth > 16) return true;
 	if (Array.isArray(value)) return value.some((item) => hasForbiddenKey(item, depth + 1));
-	if (!isPlainRecord(value)) return false;
+	if (!isRecord(value)) return false;
 	return Object.keys(value).some((key) => isForbiddenKey(key) || hasForbiddenKey(value[key], depth + 1));
 }
 /**
@@ -86,7 +85,7 @@ function hasForbiddenKey(value, depth = 0) {
 * without `verification.trust_framework` and a `claims` object is dropped.
 */
 function verifiedClaimsOf(value) {
-	const verified = (Array.isArray(value) ? value : [value]).filter((entry) => isPlainRecord(entry) && isPlainRecord(entry["verification"]) && typeof entry["verification"]["trust_framework"] === "string" && isPlainRecord(entry["claims"]) && !hasForbiddenKey(entry));
+	const verified = (Array.isArray(value) ? value : [value]).filter((entry) => isRecord(entry) && isRecord(entry["verification"]) && typeof entry["verification"]["trust_framework"] === "string" && isRecord(entry["claims"]) && !hasForbiddenKey(entry));
 	return verified.length === 0 ? void 0 : freezeDeep(verified.map((entry) => ({
 		verification: entry.verification,
 		claims: entry.claims
@@ -128,7 +127,7 @@ function keptKeys(value) {
 function claimExtras(record) {
 	return compact({
 		via: typeof record["via"] === "string" ? record["via"] : void 0,
-		expiresAt: typeof record["expiresAt"] === "number" ? record["expiresAt"] : void 0,
+		expiresAt: record["expiresAt"] === void 0 || record["expiresAt"] === null ? void 0 : expirySeconds(record["expiresAt"]) ?? 0,
 		keep: keptKeys(record["keep"])
 	});
 }
@@ -242,33 +241,28 @@ function customClaims(claims, reserved) {
 	return out;
 }
 function validateCustomClaims(claims, schema) {
-	const result = schema["~standard"].validate(claims);
-	if (result instanceof Promise) {
-		ignoreRejection(result);
-		return { ok: false };
-	}
-	if ("issues" in result && result.issues !== void 0) return { ok: false };
-	return {
+	const value = validateRecord(schema, claims);
+	return value === void 0 ? { ok: false } : {
 		ok: true,
-		value: result.value
+		value
 	};
 }
 function mapClaimsToSubject(claims, options) {
 	const paths = options.claims;
 	const idPath = paths?.id ?? DEFAULT_CLAIMS.id;
-	const id = readPath(claims, idPath);
+	const id = readClaim(claims, idPath);
 	if (typeof id !== "string" || id.length === 0) return {
 		subject: anonymousSubject(),
 		invalidClaims: false,
 		invalidChain: false
 	};
 	const tenantPath = paths?.tenant;
-	const tenant = tenantPath === void 0 ? void 0 : readPath(claims, tenantPath);
+	const tenant = tenantPath === void 0 ? void 0 : readClaim(claims, tenantPath);
 	const activeTenant = typeof tenant === "string" ? tenant : void 0;
-	const roles = asStringArray(readPath(claims, paths?.roles ?? DEFAULT_CLAIMS.roles));
-	const plans = asStringArray(readPath(claims, paths?.plans ?? paths?.entitlements ?? DEFAULT_CLAIMS.entitlements));
-	const groups = asStringArray(readPath(claims, paths?.groups ?? DEFAULT_CLAIMS.groups));
-	const memberships = [...membershipsFromClaim(paths?.memberships === void 0 ? void 0 : readPath(claims, paths.memberships)), ...membershipsFromGroups(groups, options.groupRoles, activeTenant)];
+	const roles = asStringArray(readClaim(claims, paths?.roles ?? DEFAULT_CLAIMS.roles));
+	const plans = asStringArray(readClaim(claims, paths?.plans ?? paths?.entitlements ?? DEFAULT_CLAIMS.entitlements));
+	const groups = asStringArray(readClaim(claims, paths?.groups ?? DEFAULT_CLAIMS.groups));
+	const memberships = [...membershipsFromClaim(paths?.memberships === void 0 ? void 0 : readClaim(claims, paths.memberships)), ...membershipsFromGroups(groups, options.groupRoles, activeTenant)];
 	let extra = customClaims(claims, [
 		"iss",
 		"sub",
@@ -327,7 +321,7 @@ function mapClaimsToSubject(claims, options) {
 		binding
 	}));
 	const sessionPath = paths?.session ?? DEFAULT_CLAIMS.session;
-	const sessionValue = readPath(claims, sessionPath);
+	const sessionValue = readClaim(claims, sessionPath);
 	const sessionExpiry = claims["session_expiry"];
 	const exp = typeof claims.exp === "number" ? claims.exp : void 0;
 	const expiresAt = typeof sessionExpiry === "number" && exp !== void 0 ? Math.min(exp, sessionExpiry) : exp;

package/dist/{map-error-pgUWNNtG.js → map-error-TCAdw-eW.js}

@@ -1,8 +1,8 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { n as PermDockValidationError } from "./validation-error-CnjZ4t92.js";
-import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "./errors-Cz5zn0mW.js";
-import { r as decisionResponse, s as problemResponse } from "./problem-B43ztKIm.js";
-import { r as InvalidSignatureError } from "./evaluations-tz6D9A2G.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
+import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "./errors-BKy0EfhN.js";
+import { c as problemResponse, i as decisionResponse } from "./problem-CTviyH5L.js";
+import { u as InvalidSignatureError } from "./evaluations-DZ2CbV5k.js";
 //#region src/server/map-error.ts
 /**
 * Turns a thrown PermDock error into its Problem Details response, with the

package/dist/{markers-B0hYLvMD.js → markers-C6joDI3o.js}

@@ -1,4 +1,5 @@
-//#region src/cli/markers.ts
+import { t as beforeFirst } from "./text-BMFRfBqc.js";
+//#region src/cli/sql/markers.ts
 const HOOK_MARKER = "-- permdock:hook v1";
 /** The first line of a `--grants-out` file. */
 const GRANTS_MARKER = "-- permdock:grants v1";
@@ -6,10 +7,14 @@ const GRANTS_MARKER = "-- permdock:grants v1";
 const SEEDS_MARKER = "-- permdock:seeds v1";
 /** The first line of the `indexes` part: the indexes the policies and helpers read through. */
 const INDEXES_MARKER = "-- permdock:indexes v1";
+/** The first line of a `--backfill-out` migration: existing custom roles copied into the custom-role tables. */
+const BACKFILL_MARKER = "-- permdock:backfill v1";
+/** The first line of a `rls migrate --retire-out` migration: a materialised permissions table and its refresh triggers dropped. */
+const RETIRE_MARKER = "-- permdock:retire v1";
 const HOOK_LINE = /^-- permdock:hook v(?<version>[1-9]\d*)(?: (?<rest>.*))?$/u;
 const GRANTS_LINE = /^-- permdock:grants v(?<version>[1-9]\d*)(?: (?<rest>.*))?$/u;
 function firstLine(sql) {
-	return (sql.split("\n", 1)[0] ?? "").replace(/\r$/u, "");
+	return beforeFirst(sql, "\n").replace(/\r$/u, "");
 }
 /** The `key=value` pairs after the marker, in a prototype-less object. */
 function pairs(rest) {
@@ -57,4 +62,4 @@ function parseGrantsMarker(sql) {
 	});
 }
 //#endregion
-export { hookMarkerFields as a, SEEDS_MARKER as i, HOOK_MARKER as n, parseGrantsMarker as o, INDEXES_MARKER as r, parseHookMarker as s, GRANTS_MARKER as t };
+export { RETIRE_MARKER as a, parseGrantsMarker as c, INDEXES_MARKER as i, parseHookMarker as l, GRANTS_MARKER as n, SEEDS_MARKER as o, HOOK_MARKER as r, hookMarkerFields as s, BACKFILL_MARKER as t };

package/dist/mcp/index.d.ts

@@ -1,11 +1,14 @@
-import { C as Policy, Nr as Principal, Pr as Subject } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { f as ApprovalStore } from "../types-aqOHTHcp.js";
-import { t as ApprovalHint } from "../errors-DPdqI50v.js";
-import { t as InstanceOptions } from "../instance-options-jARdwfPN.js";
+import { $n as Delegation, T as Policy, ir as Subject, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { m as ApprovalStore } from "../types-CCpc2Dcv.js";
+import { t as ApprovalHint } from "../errors-C2PXIv4c.js";
+import { t as InstanceOptions } from "../instance-options-Omfd793B.js";
+import { t as RequestContext } from "../request-context-C2_1lchh.js";
+import { n as PermDockWrap } from "../wrap-Bd1Tejur.js";
+import { o as OtelWrap } from "../types-BqAKcRNW.js";
+import { n as DeniedTextEvent, t as DeniedText } from "../denied-text-D8jDHgsl.js";
 import { t as ClientNames } from "../clients-C7zLFuWT.js";
-import { u as JwtSubjectOptions } from "../types-Cq_H8N_X.js";
-import { o as OtelWrap } from "../types-QCuYJh4q.js";
+import { U as JwtSubjectOptions } from "../types-DiQjupG2.js";
 import { CacheHint, Icon, McpServer, PromptCallback, ReadResourceCallback, ReadResourceTemplateCallback, RegisteredPrompt, RegisteredResource, RegisteredResourceTemplate, RegisteredTool, ResourceMetadata, ResourceTemplate, ScopeChallengeHandler, StandardSchemaWithJSON, ToolAnnotations, ToolCallback, Variables } from "@modelcontextprotocol/server";
 //#region src/mcp/types.d.ts
 /** The verified `AuthInfo` the MCP SDK's bearer auth puts on `ctx.http.authInfo`. */
@@ -96,6 +99,16 @@ type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
    * client, so one policy delegation covers the token on every surface.
    */
   readonly actorKind?: string;
+  /**
+   * Replaces the actor built from `authInfo.clientId`, `actorKind` and
+   * `clients`. Read it from the verified `authInfo`, never from tool arguments.
+   */
+  readonly actor?: (authInfo: McpAuthInfo) => unknown;
+  /**
+   * Replaces the delegation read from `authInfo.scopes` and
+   * `authInfo.extra.authorization_details`.
+   */
+  readonly delegation?: (authInfo: McpAuthInfo) => Delegation | undefined | Promise<Delegation | undefined>;
   /** Names for OAuth client ids (`ClientNames`): the actor gets `client` set to the name of `authInfo.clientId`, which a policy delegation matches with `to: { kind, client }`. */
   readonly clients?: ClientNames;
   readonly tenant?: string | ((authInfo: McpAuthInfo) => string | undefined | Promise<string | undefined>);
@@ -125,6 +138,18 @@ type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
   readonly store?: ApprovalStore;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
+  /** Wraps each instance after `otel`; build it with `wrapPermDock` to cover derived instances. */
+  readonly wrap?: PermDockWrap;
+  /**
+   * Request values merged into `subject.context`, under `policy.context`.
+   * Read them from the verified `authInfo`, never from tool arguments.
+   */
+  readonly context?: (authInfo: McpAuthInfo) => RequestContext | undefined | Promise<RequestContext | undefined>;
+  /**
+   * Replaces the text of a refusal. `isError`, `structuredContent` and the
+   * approval shape stay as PermDock built them.
+   */
+  readonly deniedText?: DeniedText;
 };
 type McpPermDock = {
   /** Call before registering anything: later `register*` calls must carry a `permission`. */
@@ -135,9 +160,11 @@ type McpPermDock = {
 };
 //#endregion
 //#region src/mcp/create.d.ts
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, given: McpPermDockOptions<TUser>): McpPermDock;
+//#endregion
+//#region src/mcp/mcp-auth.d.ts
 /** `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an approval token. */
 export declare const APPROVAL_META_KEY = "dev.permdock/approval";
-export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: McpPermDockOptions<TUser>): McpPermDock;
 //#endregion
 //#region src/mcp/subject.d.ts
 type McpSubjectOptions = Pick<JwtSubjectOptions, "claims" | "groupRoles" | "schema" | "delegation"> & {
@@ -156,4 +183,4 @@ type McpSubjectOptions = Pick<JwtSubjectOptions, "claims" | "groupRoles" | "sche
  */
 export declare function subjectFromMcp(authInfo: McpAuthInfo | undefined, options?: McpSubjectOptions): Subject<McpPrincipal>;
 //#endregion
-export type { GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig, ProcedureMcpServer };
+export type { DeniedText, DeniedTextEvent, GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig, ProcedureMcpServer };