permdock 0.1.0 → 0.3.0

package/dist/manifest-uDS9y5de.d.ts

@@ -0,0 +1,206 @@
+//#region src/supabase/manifest.d.ts
+/**
+ * What `permdock supabase inspect --json` prints and `--out` writes to
+ * `permdock.manifest.json`: the contract between the generated hook and SQL
+ * helpers and a package that writes policies or claims next to them.
+ * `version` is the major of this shape; a field is only
+ * ever added within it. `schemas/supabase-manifest-v1.json` is its JSON Schema.
+ */
+type SupabaseHookManifest = {
+  readonly $schema: "https://permdock.com/schemas/supabase-manifest-v1.json";
+  readonly version: 1;
+  readonly hook: {
+    readonly schema: string;
+    readonly function: "custom_access_token_hook";
+    readonly out: string;
+    readonly before?: readonly string[];
+  };
+  readonly helpers: {
+    readonly schema: string;
+    /**
+     * `permdock_has` and, per declared scope, `permitted_<scope>_ids`, each
+     * `(p_grant text)`, the membership-only `member_<scope>_ids()` and, for a
+     * scope with a membership source, `member_<scope>_ids_for(p_user uuid)`.
+     */
+    readonly functions: readonly string[];
+  };
+  readonly tenantClaim: string;
+  readonly budget: {
+    readonly bytes: number;
+    readonly measure: string;
+  };
+  readonly claims: readonly SupabaseHookClaim[];
+  readonly authzVersion: boolean;
+  /**
+   * With `authzVersion`, the function that bumps the listed users' `authz_ver`,
+   * for a membership source outside the hook. It is `security definer` and no
+   * client role may execute it: call it from a trigger owned by the table's owner.
+   */
+  readonly authzVersionBump?: {
+    readonly schema: string;
+    readonly function: "permdock_bump_authz_version_for";
+    readonly args: "p_users uuid[]";
+  };
+  /** The `supabase.hook.memberships` sources, in the order the hook reads them. */
+  readonly memberships: readonly SupabaseManifestMembership[];
+  readonly rls: SupabaseManifestRls;
+  /**
+   * Every `schema.table.column` a membership or an `attrs` claim is computed
+   * from. A client role that can insert or update one can grant itself access.
+   */
+  readonly decidingColumns: readonly string[];
+  /** The majors of the `-- permdock:hook` and `-- permdock:grants` marker lines. */
+  readonly markers: {
+    readonly hook: "v1";
+    readonly grants: "v1";
+  };
+  /**
+   * The `supabase/sdk` capability-matrix feature ids the hook, the helpers and
+   * `subjectFromSupabase` depend on, as of the `matrix` release tag. A client
+   * SDK that lacks one cannot serve this policy.
+   */
+  readonly requires?: SupabaseManifestRequires;
+};
+type SupabaseManifestRequires = {
+  /** The capability-matrix release tag, `capability-matrix-v1.<minor>.<patch>`. */
+  readonly matrix: string;
+  /** Sorted three-segment feature ids, such as `auth.session.get_claims`. */
+  readonly capabilities: readonly string[];
+};
+type SupabaseHookClaim = {
+  readonly name: string;
+  /** `permdock`, or the `<schema>.<function>` of a `supabase.hook.claims` entry. */
+  readonly source: string;
+  /** Whether the claim counts toward `budget.bytes`. */
+  readonly budget: boolean;
+};
+type SupabaseManifestColumn = {
+  readonly column: string;
+};
+/** A column of the source table, or a value every row has. */
+type SupabaseManifestValue = SupabaseManifestColumn | {
+  readonly value: string | readonly string[];
+};
+/** A column that references another table: the value (role key or user id) is `column` of `table`, matched on `id`. */
+type SupabaseManifestThrough = {
+  readonly table: string;
+  readonly id: string;
+  readonly column: string;
+};
+/** A role column (with `through` when it references a roles table), or the fixed roles every row holds. */
+type SupabaseManifestRole = SupabaseManifestValue | (SupabaseManifestColumn & {
+  readonly through: SupabaseManifestThrough;
+});
+/** One `fromTable` or `fromJunction` source. */
+type SupabaseManifestMembership = {
+  /** `schema.table`, `public` when the source names no schema. */
+  readonly table: string;
+  /** The user id column, with `through` when it references the table that holds the user id. */
+  readonly user: SupabaseManifestColumn | (SupabaseManifestColumn & {
+    readonly through: SupabaseManifestThrough;
+  });
+  /** A column for `fromTable`, the fixed scope for `fromJunction`. */
+  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. */
+  readonly role: SupabaseManifestRole | readonly SupabaseManifestRole[];
+  /** A `jsonb` column of ancestor ids keyed by scope, or one column per ancestor scope. */
+  readonly within?: SupabaseManifestColumn | {
+    readonly columns: Readonly<Record<string, string>>;
+  };
+  readonly via?: SupabaseManifestValue;
+  readonly expiresAt?: SupabaseManifestColumn;
+  readonly disabledAt?: SupabaseManifestColumn;
+  /** The columns of `table` that decide the membership. */
+  readonly columns: readonly string[];
+};
+type SupabaseManifestHelper = {
+  readonly name: string;
+  /** The argument list, `p_grant text`, or `''` for none. */
+  readonly args: string;
+  readonly returns: string;
+  /** The roles granted `execute`; a field view `anon` reads adds `anon` to the `authenticated` ones. */
+  readonly execute: readonly string[];
+};
+/** A table whose row says whether a user or a scope instance is active (`rls.suspension`); a missing row counts as suspended. */
+type SupabaseManifestActiveRow = {
+  /** `schema.table`. */
+  readonly table: string;
+  /** The column holding the user id or the scope instance id. */
+  readonly id: string;
+  /** A nullable timestamp column; a row with a value is suspended. */
+  readonly disabledAt?: string;
+  /** A status column; only a row whose value is in `active` is active. */
+  readonly status?: string;
+  readonly active?: readonly string[];
+  /** A scope only: the permission keys members of a suspended instance still hold. */
+  readonly keep?: readonly string[];
+};
+type SupabaseManifestRls = {
+  readonly schema: string;
+  /** Where the helpers read roles and memberships: the claims (`jwt`) or the tables (`database`). */
+  readonly mode: "jwt" | "database";
+  readonly tenantClaim: string;
+  /** The declared scopes, root first, with the Postgres type of their ids. */
+  readonly scopes: readonly {
+    readonly name: string;
+    readonly type: string;
+    readonly within?: string;
+  }[];
+  /**
+   * Every function `rls generate` writes for policies and trusted SQL to
+   * call: `permdock_has`, `permitted_<scope>_ids`, `member_<scope>_ids` and
+   * `permdock_user_id`, the caller's user id; in `database` mode `permdock_has_for`, `permitted_<scope>_ids_for` and
+   * `member_<scope>_ids_for`; and when a role declares `assigns`,
+   * `permdock_can_assign`, `permdock_can_assign_any` and, with custom roles,
+   * `permdock_can_assign_custom_role`, each with its `_for` form where one
+   * is written. A helper whose `execute` is empty is for trusted SQL only.
+   */
+  readonly helpers: readonly SupabaseManifestHelper[];
+  /**
+   * The tables `member_<scope>_ids_for` reads: an `rls.memberships` table
+   * mapped for the scope, else `rls.membershipSources`, else the hook's
+   * `memberships`.
+   */
+  readonly memberships: readonly SupabaseManifestMembership[];
+  /** Whether custom roles live in the helpers' tables (`rls.customRoles` in `database` mode). */
+  readonly customRoles?: boolean;
+  /** The global-roles table the hook and the `database` mode helpers read. */
+  readonly roles?: {
+    readonly table: string;
+    readonly user: SupabaseManifestColumn;
+    readonly role: SupabaseManifestRole | readonly SupabaseManifestRole[];
+  };
+  /** `rls.suspension`: a suspended user, or a suspended scope instance, holds nothing but its scope's `keep`. */
+  readonly suspension?: {
+    readonly users?: SupabaseManifestActiveRow;
+    readonly scopes?: Readonly<Record<string, SupabaseManifestActiveRow>>;
+    readonly memberships?: {
+      readonly keep: readonly string[];
+    };
+  };
+  /**
+   * `rls.assignments`: the tables whose client writes the assignment
+   * triggers check against `permdock_can_assign_any`, so SQL writing rows
+   * there needs no role-ceiling check of its own.
+   */
+  readonly assignments?: {
+    readonly tables: readonly string[];
+  };
+  readonly apiKeys?: {
+    readonly claim: string;
+    readonly scopes: string;
+    readonly tenant: string;
+    readonly roles: string;
+    readonly serviceRoles: readonly string[];
+  };
+};
+/**
+ * Reads a `permdock.manifest.json` document (parsed, or the JSON text) and
+ * validates it against `schemas/supabase-manifest-v1.json`. Returns a
+ * deep-frozen copy built from own keys; throws `PermDockValidationError`
+ * with every issue, so a manifest of another major is refused.
+ */
+declare function parseSupabaseManifest(json: unknown): SupabaseHookManifest;
+//#endregion
+export { SupabaseManifestHelper as a, SupabaseManifestRls as c, SupabaseManifestValue as d, parseSupabaseManifest as f, SupabaseManifestColumn as i, SupabaseManifestRole as l, SupabaseHookManifest as n, SupabaseManifestMembership as o, SupabaseManifestActiveRow as r, SupabaseManifestRequires as s, SupabaseHookClaim as t, SupabaseManifestThrough as u };

package/dist/{map-DowSO96j.js → map-AcxK9o_D.js}

@@ -1,5 +1,5 @@
 import { t as compact } from "./compact-y6vfu2_f.js";
-import { g as listPermissions, i as findPermission } from "./permissions-DC7GROPA.js";
+import { t as itemResourceData } from "./evaluation-items-CfCCejQd.js";
 //#region src/authzen/map.ts
 const UNKNOWN = {
 	outcome: "denied",
@@ -28,22 +28,11 @@ function actionNameOf(item) {
 	const scope = item.action.properties["scope"];
 	return typeof scope === "string" ? scope : void 0;
 }
-function permissionOf(tree, item) {
-	const actionName = actionNameOf(item);
-	if (actionName === void 0) return;
-	const byKey = findPermission(tree, actionName);
-	if (byKey !== void 0) return byKey;
-	const resource = typeof item.resource?.type === "string" ? item.resource.type : void 0;
-	if (resource === void 0) return;
-	const dotted = findPermission(tree, `${resource}.${actionName}`);
-	if (dotted !== void 0) return dotted;
-	return listPermissions(tree).find((leaf) => leaf.resource === resource && leaf.action === actionName);
+function permissionOf(lookup, item) {
+	return lookup(actionNameOf(item), item.resource);
 }
 function resourceData(item) {
-	const properties = item.resource?.properties;
-	if (properties !== null && typeof properties === "object") return properties;
-	const id = item.resource?.id;
-	if (typeof id === "string" || typeof id === "number") return { id: String(id) };
+	return itemResourceData(item.resource);
 }
 function resourceIdOf(item) {
 	const id = item.resource?.id;

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

@@ -1,8 +1,9 @@
 import { t as compact } from "./compact-y6vfu2_f.js";
-import { n as freezeDeep } from "./freeze-y1_jQL4v.js";
-import { S as isForbiddenKey, T as readPath } from "./permissions-DC7GROPA.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 { t as clientNameOf } from "./clients-DjU5ABMy.js";
 //#region src/jwt/map-claims.ts
 /** OpenID Connect Core section 5.1: profile data the provider owns. */
 const PROFILE_CLAIMS = [
@@ -118,10 +119,17 @@ function stringRecord(value) {
 	for (const [key, item] of Object.entries(value)) if (typeof item === "string") out[key] = item;
 	return out;
 }
+function keptKeys(value) {
+	if (value === void 0) return;
+	if (!Array.isArray(value)) return [];
+	const keys = value.filter((key) => typeof key === "string" && key !== "");
+	return keys.length === value.length ? keys : [];
+}
 function claimExtras(record) {
 	return compact({
 		via: typeof record["via"] === "string" ? record["via"] : void 0,
-		expiresAt: typeof record["expiresAt"] === "number" ? record["expiresAt"] : void 0
+		expiresAt: typeof record["expiresAt"] === "number" ? record["expiresAt"] : void 0,
+		keep: keptKeys(record["keep"])
 	});
 }
 function membershipsFromClaim(value) {
@@ -204,7 +212,8 @@ function actorFromAct(claims, options) {
 		status: "ok",
 		actor: compact({
 			id: act.sub,
-			kind: configured?.kind ?? "oauth-client"
+			kind: configured?.kind ?? "oauth-client",
+			client: clientNameOf(configured?.clients, act.sub)
 		}),
 		chain: act
 	};

package/dist/map-error-pgUWNNtG.js

@@ -0,0 +1,23 @@
+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";
+//#region src/server/map-error.ts
+/**
+* Turns a thrown PermDock error into its Problem Details response, with the
+* status, `WWW-Authenticate` and rate-limit fields `protect` sends for the
+* same decision. Returns `undefined` for anything else so the framework's own
+* error path takes over.
+*/
+function problemFromError(error, options = {}) {
+	if (error instanceof InvalidSignatureError) return error.response;
+	if (error instanceof PermDockDeniedError || error instanceof PermDockApprovalRequiredError) return decisionResponse(error.toProblemDetails(compact({ instance: options.instance })), error.decision, compact({
+		scope: error.scope,
+		credentials: options.credentials
+	}));
+	if (error instanceof PermDockRevokedError) return problemResponse(error.toProblemDetails(), void 0, error.decision);
+	if (error instanceof PermDockValidationError) return problemResponse(error.toProblemDetails(compact({ instance: options.instance })));
+}
+//#endregion
+export { problemFromError as t };

package/dist/may-use-DndQ5tQ-.js

@@ -0,0 +1,77 @@
+import { d as scopeList, m as tenantOf, o as resolveScope } from "./scopes-CVdPrWN-.js";
+import { a as isMembershipExpired, t as isActive, u as nowSeconds } from "./validity-uOp8UpYn.js";
+import { t as coveredByDelegation } from "./delegation-D8pUEuce.js";
+//#region src/core/may-use.ts
+function delegationMayCover(permission, delegation, hasActor) {
+	return [void 0, ...[...delegation?.access ?? [], ...delegation?.authorizationDetails ?? []].flatMap((entry) => typeof entry === "object" && entry !== null && typeof entry["identifier"] === "string" ? [entry["identifier"]] : [])].some((id) => coveredByDelegation(permission, delegation, id, hasActor) === void 0);
+}
+function blocksEveryRow(grant) {
+	return grant.effect === "deny" && grant.where === void 0 && grant.check === void 0 && grant.portable !== false && grant.fields === void 0 && (grant.scope === void 0 || grant.scope === "tenant");
+}
+/**
+* Whether `permission` could be granted to this instance's subject for some
+* row: the grants its snapshot carries for the active tenant, minus an
+* unconditional deny, within its delegation. A listing hint for tools and
+* skills, never a decision; the call itself is decided in full.
+*/
+function mayUse(permdock, permission) {
+	try {
+		const snapshot = permdock.snapshot();
+		if (!("grants" in snapshot)) return false;
+		const ceiling = snapshot.delegated;
+		if (ceiling !== void 0 && !ceiling.includes(permission.key)) return false;
+		if (!delegationMayCover(permission, permdock.subject.delegation, permdock.subject.actor !== void 0 && ceiling === void 0)) return false;
+		const tenant = permdock.subject.principal?.tenant;
+		const scopes = scopeList(snapshot.scopes);
+		const grants = snapshot.grants.filter((grant) => {
+			if (grant.permission !== permission.key) return false;
+			const owner = grant.membership === void 0 ? void 0 : tenantOf(grant.membership, scopes);
+			return owner === void 0 || owner === tenant;
+		});
+		if (grants.some(blocksEveryRow)) return false;
+		return grants.some((grant) => grant.effect === "allow");
+	} catch {
+		return false;
+	}
+}
+function isConditioned(grant) {
+	return grant.where !== void 0 || grant.check !== void 0 || grant.validity !== void 0 || grant.portable === false;
+}
+/**
+* The instances of `scope` in which the subject holds `permission`, from its
+* live memberships of exactly that scope, within its delegation: by default
+* those with an allow that carries no row condition (`where`, `check`, a
+* validity window or a non-portable test; a `fields` limit is not a row
+* condition), minus the instances any deny of the permission reaches. The
+* in-process mirror of the SQL `permitted_<scope>_ids_by_permission`. With
+* `conditioned: true` it also lists the instances where a conditioned allow
+* applies, minus only unconditional denies, as
+* `permitted_<scope>_ids_by_permission(p_permission, true)` does. A listing,
+* never a decision: a row's own check still runs `can`.
+*/
+function permittedIds(permdock, permission, scope, options = {}) {
+	try {
+		const snapshot = permdock.snapshot({ tenants: "all" });
+		if (!("grants" in snapshot)) return [];
+		const scopes = scopeList(snapshot.scopes);
+		const name = resolveScope(scopes, scope);
+		const ceiling = snapshot.delegated;
+		if (name === void 0 || ceiling !== void 0 && !ceiling.includes(permission.key) || !delegationMayCover(permission, permdock.subject.delegation, permdock.subject.actor !== void 0 && ceiling === void 0)) return [];
+		const conditioned = options.conditioned === true;
+		const now = nowSeconds();
+		const allowed = /* @__PURE__ */ new Set();
+		const denied = /* @__PURE__ */ new Set();
+		for (const grant of snapshot.grants) {
+			const membership = grant.membership;
+			if (grant.permission !== permission.key || grant.scope !== name || membership?.scope !== name || membership.id === void 0 || isMembershipExpired(membership, now) || options.within !== void 0 && tenantOf(membership, scopes) !== options.within) continue;
+			if (grant.effect === "deny") {
+				if (!conditioned || !isConditioned(grant)) denied.add(membership.id);
+			} else if ((conditioned || !isConditioned(grant)) && isActive(grant.validity, now)) allowed.add(membership.id);
+		}
+		return [...allowed].filter((id) => !denied.has(id)).toSorted();
+	} catch {
+		return [];
+	}
+}
+//#endregion
+export { permittedIds as n, mayUse as t };

package/dist/mcp/index.d.ts

@@ -1,9 +1,11 @@
-import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, hr as Subject, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
-import { d as Permission } from "../permissions-B4apnahQ.js";
-import { f as ApprovalStore } from "../types-B8w5PFtS.js";
-import { t as ApprovalHint } from "../errors-DbZ1YOnb.js";
-import { u as JwtSubjectOptions } from "../types-bva3i4Gf.js";
-import { o as OtelWrap } from "../types-B9dmiiab.js";
+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 { 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 { 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`. */
@@ -36,6 +38,7 @@ type McpToolConfig<TInput extends StandardSchemaWithJSON | undefined = undefined
   readonly annotations?: ToolAnnotations;
   readonly icons?: Icon[];
   readonly scopeChallenge?: ScopeChallengeHandler;
+  readonly oauthScopes?: readonly string[];
   readonly _meta?: Record<string, unknown>;
   /**
    * Decide again when the handler resolves, without consuming quota, and
@@ -63,9 +66,38 @@ type GuardedMcpServer = Omit<McpServer, "registerTool" | "registerResource" | "r
   registerResource(name: string, template: ResourceTemplate, config: McpResourceConfig<[uri: URL, variables: Variables]>, read: ReadResourceTemplateCallback): RegisteredResourceTemplate;
   registerPrompt<TArgs extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpPromptConfig<TArgs>, handler: PromptCallback<TArgs>): RegisteredPrompt;
 };
-type McpPermDockOptions<TUser = unknown> = {
+/** A tool config when the tool's own procedure decides: no loader, no re-check. */
+type McpProcedureToolConfig<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined> = Omit<McpToolConfig<TInput, TOutput>, "permission" | "data" | "longRunning"> & {
+  /** Overrides `permissionFor(name)`. */
+  readonly permission?: Permission;
+};
+/** `GuardedMcpServer` whose tools are listed and annotated by permission but decided by the procedure they call. */
+type ProcedureMcpServer = Omit<GuardedMcpServer, "registerTool"> & {
+  registerTool<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpProcedureToolConfig<TInput, TOutput>, handler: ToolCallback<TInput>): RegisteredTool;
+};
+/**
+ * Tools whose handler calls a procedure that already runs `protect`, such as
+ * an oRPC procedure through `call()`. `tools/list` and annotations use the
+ * permission; the call itself is not guarded, so each call decides once.
+ */
+type McpProcedureEnforcement = {
+  readonly enforce: "procedure";
+  /** The permission of the tool `name`; `permissionOf(procedure)` from `permdock/orpc` reads it. `undefined` throws at registration. */
+  readonly permissionFor: (name: string) => Permission | undefined;
+  readonly oauthScopesFor?: (name: string) => readonly string[] | undefined;
+};
+type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
   /** Receives the verified auth info, or `{}` on a transport without one (stdio). */
   readonly subject: (authInfo: McpAuthInfo) => TUser | Promise<TUser>;
+  /**
+   * The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'`
+   * when absent. `'oauth-client'` decides the token under the kind
+   * `subjectFromSupabase`, `subjectFromJwt` and `permdock/a2a` give an OAuth
+   * client, so one policy delegation covers the token on every surface.
+   */
+  readonly actorKind?: string;
+  /** 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>);
   /** Deny every call and list nothing when the transport carries no auth info. */
   readonly requireAuthInfo?: boolean;
@@ -90,23 +122,16 @@ type McpPermDockOptions<TUser = unknown> = {
   readonly requestState?: {
     readonly mint: (token: string, context?: never) => Promise<string>;
   };
-  readonly memberships?: MembershipSource | readonly MembershipSource[];
-  /** The object graph for relation grants that walk a parent chain; without it they deny. */
-  readonly relations?: RelationSource;
-  readonly entitlements?: EntitlementSource;
-  readonly customRoles?: RoleSource;
-  /** Hosted grants, read once per instance; see `PolicySource`. */
-  readonly policies?: PolicySource;
   readonly store?: ApprovalStore;
-  readonly sink?: DecisionSink;
-  readonly limits?: LimitStore;
-  readonly snapshots?: SnapshotSource;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
 };
 type McpPermDock = {
   /** Call before registering anything: later `register*` calls must carry a `permission`. */
-  readonly protectServer: (server: McpServer) => GuardedMcpServer;
+  readonly protectServer: {
+    (server: McpServer): GuardedMcpServer;
+    (server: McpServer, options: McpProcedureEnforcement): ProcedureMcpServer;
+  };
 };
 //#endregion
 //#region src/mcp/create.d.ts
@@ -115,13 +140,20 @@ 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">;
+type McpSubjectOptions = Pick<JwtSubjectOptions, "claims" | "groupRoles" | "schema" | "delegation"> & {
+  /** The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'` when absent. Match `createPermDock`'s `actorKind`. */
+  readonly actorKind?: string;
+  /** Names for OAuth client ids; match `createPermDock`'s `clients`. */
+  readonly clients?: ClientNames;
+};
 /**
  * Maps the `AuthInfo` the MCP SDK's bearer verification produced to a
  * `Subject`: the principal from the verified claims in `extra`, the client
- * as an `mcp-client` actor, the granted scopes as the delegation. Never
- * verifies and never throws; anything unusable is the anonymous subject.
+ * as an actor of kind `actorKind` (`mcp-client` by default), the granted
+ * scopes as the delegation. Never verifies and never throws; anything
+ * unusable, including an `actorKind` that is not a non-empty string, is
+ * the anonymous subject.
  */
 export declare function subjectFromMcp(authInfo: McpAuthInfo | undefined, options?: McpSubjectOptions): Subject<McpPrincipal>;
 //#endregion
-export type { GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig };
+export type { GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig, ProcedureMcpServer };