permdock 0.4.0 → 0.5.0

package/README.md

@@ -70,6 +70,7 @@ Server-only. Roles are data; conditions are a portable JSON tree.
 ```ts
 // src/policy.ts
 import { allow, definePolicy, principal, relation, role } from "permdock";
+
 import { permissions, roles } from "./permissions";
 
 const member = role(roles.member, [
@@ -93,7 +94,7 @@ export const policy = definePolicy(
   {
     roles: [member, admin],
     scopes: { tenant: { key: "orgId" } },
-    principal: (user: User | null) =>
+    subject: (user: User | null) =>
       user && {
         id: user.id,
         roles: user.roles,
@@ -110,9 +111,9 @@ export const policy = definePolicy(
 ### 3. Decide
 
 ```ts
-import { createPermDock } from "permdock";
+import { getPermDock } from "permdock";
 
-const permdock = await createPermDock(policy, user); // frozen, request-scoped, never throws
+const permdock = await getPermDock(policy, user); // frozen, request-scoped; getPermDockSync when every input is synchronous
 permdock.can(permissions.post.update, post); // boolean
 permdock.decide(permissions.post.delete, post); // { outcome: 'granted' | 'denied' | 'approval-required', ... }
 permdock.explain(permissions.post.delete, post); // the decision plus a trace naming the deny that won
@@ -132,7 +133,7 @@ import { PermDockProvider, Protected, usePermission } from "permdock/react";
   <Protected
     permission={permissions.post.update}
     data={post}
-    fallback={<Locked />}
+    denied={<Locked />}
   >
     <EditButton />
   </Protected>
@@ -149,15 +150,13 @@ The same hook names exist in React Native, Vue, Svelte and Solid. Read [building
 // src/permdock/server.ts
 import { createPermDock } from "permdock/next";
 
-export const { getPermDock, requireAccess, permdockHandler } = createPermDock(
-  policy,
-  {
+export const { getPermDock, requirePermission, permdockHandler } =
+  createPermDock(policy, {
     subject: async () => getUser(await cookies()),
-  },
-);
+  });
 
 // in a page or Server Action
-await requireAccess({ permission: permissions.post.update, data: post }); // forbidden() / unauthorized() on a denial
+await requirePermission(permissions.post.update, post); // forbidden() / unauthorized() on a denial
 ```
 
 ### Hono
@@ -167,10 +166,10 @@ Express, Fastify, Elysia, Nest, Node, tRPC and oRPC have the same shape.
 ```ts
 import { createPermDock } from "permdock/hono";
 
-export const { permdock, protect } = createPermDock(policy, {
+export const { middleware, protect } = createPermDock(policy, {
   subject: (c) => c.get("user"),
 });
-app.use(permdock());
+app.use(middleware());
 app.delete(
   "/posts/:id",
   protect(permissions.post.delete, (c) => loadPost(c.req.param("id"))),
@@ -204,6 +203,7 @@ protectServer(server).registerTool(
 The Claude Agent SDK, Eve, the OpenAI Agents SDK, WebMCP and A2A have their own entries with the same tool map.
 
 ```ts
+import { defineOperations } from "permdock";
 import { createPermDock } from "permdock/ai-sdk";
 
 const { toolApproval } = createPermDock(policy, {
@@ -212,12 +212,12 @@ const { toolApproval } = createPermDock(policy, {
     id: runtimeContext.agentId,
     kind: "ai-sdk",
   }),
-  tools: {
+  operations: defineOperations(permissions, {
     delete_post: {
       permission: permissions.post.delete,
       data: (args) => loadPost(args.id),
     },
-  },
+  }),
 });
 generateText({ model, tools, toolApproval }); // granted → approved, denied → denied, approval-required → user-approval
 ```
@@ -226,7 +226,7 @@ generateText({ model, tools, toolApproval }); // granted → approved, denied
 
 ```bash
 permdock rls generate --target drizzle --dialect supabase   # roles × grants → policies
-permdock rls verify --db $DATABASE_URL                      # can() vs database parity
+printf %s "$DATABASE_URL" | permdock rls verify --db-url-stdin                      # can() vs database parity
 ```
 
 ## Agents and approvals
@@ -253,8 +253,8 @@ allow(permissions.payout.release, {
   approval: {
     by: roles.finance,
     quorum: 2, // two distinct finance approvers
-    ttl: "30m",
-    escalation: { after: "10m", to: roles.cfo },
+    ttl: 1800, // seconds: 30 minutes
+    escalation: { after: 600, to: roles.cfo },
   },
 });
 ```
@@ -284,28 +284,30 @@ PermDock adopts the permission keys, SQL helpers, tokens and stored custom roles
 
 Any Standard Schema validator: Zod, Valibot, ArkType, Effect Schema. One import path per target:
 
-| Group              | Entries                                                                                                                                                            |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| UI                 | `permdock/react` · `permdock/react-native` · `permdock/vue` · `permdock/svelte` · `permdock/solid`                                                                 |
-| Full-stack         | `permdock/next`                                                                                                                                                    |
-| HTTP               | `permdock/server` · `permdock/hono` · `permdock/express` · `permdock/fastify` · `permdock/elysia` · `permdock/nest` · `permdock/node`                              |
-| Terminal           | `permdock/terminal` for your own CLI (not the `permdock` binary)                                                                                                   |
-| RPC                | `permdock/trpc` · `permdock/orpc`                                                                                                                                  |
-| Agents             | `permdock/mcp` · `permdock/ai-sdk` · `permdock/claude-agent` · `permdock/eve` · `permdock/openai` · `permdock/webmcp` · `permdock/a2a`                             |
-| Decision plane     | `permdock/authzen` · `permdock/approvals` · `permdock/cloud` · `permdock/scim` · `permdock/ssf` · `permdock/openapi` · `permdock/otel` · `permdock/pdp`            |
-| Data               | `permdock/drizzle` · `permdock/prisma` · `permdock/kysely` · `permdock rls` · `permdock powersync`                                                                 |
-| Auth and providers | `permdock/jwt` · `permdock/supabase` · `permdock/supabase/middleware` · `permdock/better-supabase` · `permdock/better-auth` · `permdock/clerk` · `permdock/convex` |
-| Build              | `permdock/next/plugin` · `permdock/unplugin`                                                                                                                       |
-| Testing            | `permdock/testing`                                                                                                                                                 |
-
-React Router, TanStack Start, SvelteKit and Nuxt loaders call `getSnapshot(request)` from `permdock/server` and send `snapshotHeaders(snapshot)`. Astro and Effect use these entries plus `permdock/unplugin`. The full matrix with example apps and related standards is on the [adapters page](https://permdock.com/docs/adapters).
+| Group              | Entries                                                                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| UI                 | `permdock/react` · `permdock/react-native` · `permdock/vue` · `permdock/svelte` · `permdock/solid`                                                                                                      |
+| Full-stack         | `permdock/next` · `permdock/sveltekit` · `permdock/astro` · `permdock/solid-start` · `permdock/tanstack-start`                                                                                          |
+| HTTP               | `permdock/server` · `permdock/hono` · `permdock/h3` · `permdock/express` · `permdock/fastify` · `permdock/elysia` · `permdock/nest` · `permdock/node`                                                   |
+| Terminal           | `permdock/terminal` for your own CLI (not the `permdock` binary)                                                                                                                                        |
+| RPC                | `permdock/trpc` · `permdock/orpc`                                                                                                                                                                       |
+| Agents             | `permdock/agent` · `permdock/mcp` · `permdock/ai-sdk` · `permdock/claude-agent` · `permdock/eve` · `permdock/openai` · `permdock/webmcp` · `permdock/a2a`                                               |
+| Messaging          | `permdock/delivery` · `permdock/resend` · `permdock/chat` · `permdock/chat-sdk`                                                                                                                         |
+| Decision plane     | `permdock/authzen` · `permdock/approvals` · `permdock/workflow` · `permdock/workflow-sdk` · `permdock/cloud` · `permdock/scim` · `permdock/ssf` · `permdock/openapi` · `permdock/otel` · `permdock/pdp` |
+| Data               | `permdock/drizzle` · `permdock/prisma` · `permdock/kysely` · `permdock rls` · `permdock powersync`                                                                                                      |
+| Auth and providers | `permdock/jwt` · `permdock/supabase` · `permdock/supabase/middleware` · `permdock/better-supabase` · `permdock/better-auth` · `permdock/clerk` · `permdock/convex`                                      |
+| Build              | `permdock/next/plugin` · `permdock/unplugin`                                                                                                                                                            |
+| Testing            | `permdock/testing`                                                                                                                                                                                      |
+
+React Router loaders call `getSnapshot(request)` from `permdock/server` and send `snapshotHeaders(snapshot)`; Nitro and Nuxt server routes use `permdock/h3`. Effect uses these entries plus `permdock/unplugin`. The full matrix with example apps and related standards is on the [adapters page](https://permdock.com/docs/adapters).
 
 ## Secure by default
 
 - Fail-closed: an unknown, invalid or thrown check denies, and `can()` never throws.
 - Deny overrides allow, an unknown reference is a type error, and evaluation is prototype-safe with no eval.
 - `service_role` is never emitted, a model-supplied subject is never trusted, and an agent with no delegation is denied.
-- No one approves their own request by default, there is never a default tenant, and data is validated against the resource schema unless the caller marks a row it loaded `trusted: true`.
+- No one approves their own request by default, a delegate is held to the same rule as the person they cover, there is never a default tenant, and data is validated against the resource schema unless the caller marks a row it loaded `trusted: true`.
+- A user or service API key expires unless the tenant sets `allowNoExpiry`. A feed key (`pdfeed_`) does not expire; rotation replaces the secret and keeps the id, and the key is bound to one resource.
 - Authentication stays upstream: PermDock consumes verified sessions, JWKS-verified JWTs (`permdock/jwt`, with `jose` as an optional peer), provider claims and MCP `authInfo`. Core never verifies a token. User-editable fields never become claims: `subjectFromBetterAuth` copies `additionalFields` only through a `schema`. Read [authentication](https://permdock.com/docs/concepts/authentication).
 - Every decision runs in-process. [PermDock Cloud](https://permdock.com/docs/adapters/cloud) adds a decision log, an approval inbox, a hosted AuthZEN endpoint and a SCIM relay, behind interfaces this package ships with in-process defaults.
 
@@ -319,10 +321,10 @@ Other TypeScript permission libraries (CASL, permix, Kilpi, `@zap-studio/permit`
 
 ```bash
 npx skills add ScaleDockHQ/PermDock   # the permdock, permdock-wire, permdock-audit and topic skills
-permdock skills                       # the same skills, offline, from node_modules/permdock/skills
+permdock skills install                       # the same skills, offline, from node_modules/permdock/skills
 ```
 
-Claude Code users can add the plugin marketplace instead: `/plugin marketplace add ScaleDockHQ/permdock`. Every docs page is served as Markdown, with `llms.txt`, `llms-full.txt` and a docs MCP server at `https://permdock.com/mcp`. Read [for AI agents](https://permdock.com/docs/for-ai-agents).
+Claude Code users can add the plugin marketplace instead: `/plugin marketplace add ScaleDockHQ/permdock`. Every docs page is served as Markdown, with `llms.txt`, `llms-full.txt` and a docs MCP server at `https://permdock.com/docs/mcp`. Read [for AI agents](https://permdock.com/docs/for-ai-agents).
 
 ## License
 

package/dist/{schema-Bol6gqXA.js → 2020-C9VN-x8c.js}

@@ -1,10 +1,5 @@
-import { r as isRecord } from "./compact-CAf557ZB.js";
-import { t as packageRoot } from "./package-root-DtNnpmUd.js";
-import { t as DRAFT_PINS } from "./pins-8ILTftC9.js";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 //#region \0rolldown/runtime.js
-var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod, mod.exports), cb = null), mod.exports);
 //#endregion
 //#region ../../node_modules/.pnpm/ajv@8.20.0/node_modules/ajv/dist/compile/codegen/code.js
 var require_code$1 = /* @__PURE__ */ __commonJSMin(((exports) => {
@@ -6678,8 +6673,8 @@ var require_json_schema_2020_12 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.default = addMetaSchema2020;
 }));
 //#endregion
-//#region src/cli/openapi/schema.ts
-var import__2020 = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+//#region ../../node_modules/.pnpm/ajv@8.20.0/node_modules/ajv/dist/2020.js
+var require__2020 = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	Object.defineProperty(exports, "__esModule", { value: true });
 	exports.MissingRefError = exports.ValidationError = exports.CodeGen = exports.Name = exports.nil = exports.stringify = exports.str = exports._ = exports.KeywordCxt = exports.Ajv2020 = void 0;
 	const core_1 = require_core$2();
@@ -6775,126 +6770,6 @@ var import__2020 = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 			return ref_error_1.default;
 		}
 	});
-})))();
-function schemaDir() {
-	return join(packageRoot(), "schemas", "openapi");
-}
-const validators = /* @__PURE__ */ new Map();
-/** Parses a bundled schema file; throws on anything but a JSON object. */
-function parseSchema(text, file) {
-	const parsed = JSON.parse(text.replaceAll("\"$dynamicRef\": \"#meta\"", "\"$ref\": \"#/$defs/schema\""));
-	if (!isRecord(parsed)) throw new TypeError(`PermDock CLI: ${file} is not a JSON Schema`);
-	return parsed;
-}
-function schemaFile(file) {
-	return parseSchema(readFileSync(join(schemaDir(), file), "utf8"), file);
-}
-function child(parent, ...path) {
-	let node = parent;
-	for (const key of path) {
-		const next = node[key];
-		if (!isRecord(next)) throw new TypeError(`PermDock CLI: OpenAPI schema has no ${path.join(".")}`);
-		node = next;
-	}
-	return node;
-}
-const STRINGS = {
-	type: "array",
-	items: { type: "string" }
-};
-/**
-* No official 3.3 schema exists: the 3.2 schema plus the pinned draft's
-* Security Profiles (a `profile` scheme type and
-* `components.securityProfileRequirements`). Mutates and returns `schema`.
-*/
-function patchOas33(schema) {
-	schema["$id"] = `https://permdock.com/schemas/openapi/oas-3.3/${DRAFT_PINS.oas}`;
-	child(schema, "properties", "openapi")["pattern"] = String.raw`^3\.3\.\d+(-.+)?$`;
-	const defs = child(schema, "$defs");
-	const scheme = child(defs, "security-scheme");
-	const type = child(scheme, "properties", "type");
-	type["enum"] = [...Array.isArray(type["enum"]) ? type["enum"] : [], "profile"];
-	scheme["allOf"] = [...Array.isArray(scheme["allOf"]) ? scheme["allOf"] : [], {
-		if: { properties: { type: { const: "profile" } } },
-		then: {
-			properties: { profileMetadata: {
-				type: "object",
-				required: ["name"],
-				properties: {
-					name: { type: "string" },
-					supportedParametersSchema: { type: ["string", "object"] },
-					supportedOperations: {},
-					servers: {
-						type: "array",
-						items: {
-							type: "object",
-							required: ["url"],
-							properties: {
-								name: { type: "string" },
-								url: { type: "string" }
-							}
-						}
-					}
-				}
-			} },
-			required: ["profileMetadata"]
-		}
-	}];
-	child(defs, "components", "properties")["securityProfileRequirements"] = {
-		type: "object",
-		additionalProperties: {
-			type: "object",
-			required: ["securityScheme", "scopes"],
-			properties: {
-				securityScheme: { $ref: "#/$defs/reference" },
-				token_endpoint_auth_methods: STRINGS,
-				grant_types: STRINGS,
-				scopes: STRINGS
-			}
-		}
-	};
-	return schema;
-}
-function validatorFor(file) {
-	const cached = validators.get(file);
-	if (cached !== void 0) return cached;
-	const compiled = new import__2020.Ajv2020({
-		strict: false,
-		allErrors: false,
-		validateFormats: false
-	}).compile(file === "oas-3.3.json" ? patchOas33(schemaFile("oas-3.2.json")) : schemaFile(file));
-	validators.set(file, compiled);
-	return compiled;
-}
-function describeErrors(errors) {
-	return (errors ?? []).slice(0, 5).map((error) => `  ${error.instancePath || "/"} ${error.message ?? ""}`).join("\n");
-}
-/** Validates an OpenAPI 3.1 or 3.2 document against the official JSON Schema, and 3.3 against the pinned patch of 3.2. */
-function validateOpenapi(document) {
-	const version = isRecord(document) ? document["openapi"] : void 0;
-	const match = typeof version === "string" ? /^3\.([123])\.\d+$/u.exec(version) : null;
-	if (match === null) return {
-		ok: false,
-		error: "expected an OpenAPI 3.1, 3.2 or 3.3 document"
-	};
-	const minor = match[1] === "1" ? "3.1" : match[1] === "2" ? "3.2" : "3.3";
-	const validate = validatorFor(`oas-${minor}.json`);
-	if (!validate(document)) return {
-		ok: false,
-		error: `document is not valid OpenAPI ${minor}:\n${describeErrors(validate.errors)}`
-	};
-	return {
-		ok: true,
-		version: minor
-	};
-}
-/** Validates an Overlay 1.1 document against the official JSON Schema. */
-function validateOverlay(document) {
-	const validate = validatorFor("overlay-1.1.json");
-	return validate(document) ? { ok: true } : {
-		ok: false,
-		error: `document is not a valid Overlay 1.1:\n${describeErrors(validate.errors)}`
-	};
-}
+}));
 //#endregion
-export { validateOverlay as n, validateOpenapi as t };
+export { require__2020 as t };

package/dist/a2a/index.d.ts

@@ -1,8 +1,8 @@
-import { E as Policy, Or as Principal, br as AuthorizationDetail } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { f as ApprovalStore } from "../types-Br9IXUBG.js";
-import { a as ProblemDetails } from "../errors-OD_4c__H.js";
-import { t as InstanceOptions } from "../instance-options-plkrsAog.js";
+import { T as Policy, Yn as AuthorizationDetail, 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 { a as ProblemDetails } from "../errors-C2PXIv4c.js";
+import { t as InstanceOptions } from "../instance-options-Omfd793B.js";
 //#region src/a2a/types.d.ts
 type A2aAuth = {
   readonly clientId?: string;
@@ -166,6 +166,6 @@ type A2aPermDock = {
 };
 //#endregion
 //#region src/a2a/create.d.ts
-export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: A2aPermDockOptions<TUser>): A2aPermDock;
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, given: A2aPermDockOptions<TUser>): A2aPermDock;
 //#endregion
 export type { A2aAgentCard, A2aAgentCardSignature, A2aAuth, A2aCardInfo, A2aPermDock, A2aPermDockOptions, A2aSecurityRequirement, A2aSecurityScheme, A2aSkill, A2aSkillConfig, A2aTaskOutcome, A2aWireSecurityScheme };

package/dist/a2a/index.js

@@ -1,14 +1,14 @@
 import { t as compact } from "../compact-CAf557ZB.js";
 import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-drnfxYtm.js";
-import { t as canonicalJson } from "../canonical-json-CFKyFOke.js";
-import { t as bytesToBase64Url } from "../sha256-BO0swRXL.js";
-import { a as scopesReaching, i as hasScope, r as challengeScope } from "../permdock-L26udHSk.js";
+import { o as statusProblem } from "../problem-details-cn5X30gZ.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-BKy0EfhN.js";
+import { t as canonicalJson } from "../canonical-json-BC8_nMTw.js";
+import { t as bytesToBase64Url } from "../sha256-D9ihqmvd.js";
 import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
-import { t as mayUse } from "../may-use-BOn_dR_w.js";
-import { f as wwwAuthenticate, r as bearerChallenge } from "../problem-CnWraVhC.js";
-import { r as instanceOptions } from "../build-instance-DIIV9DbC.js";
-import { n as createAgentKernel } from "../kernel-CB3LrIJM.js";
+import { a as hasScope, c as withApp, i as challengeScope, o as scopesReaching } from "../permdock-B9JxkBwC.js";
+import { f as wwwAuthenticate, r as bearerChallenge } from "../problem-CTviyH5L.js";
+import { r as instanceOptions } from "../build-instance-BMnAudHn.js";
+import { n as createAgentKernel } from "../kernel-5JatXyND.js";
 import { t as delegationFrom } from "../delegation-input-FTxMK3ji.js";
 //#region src/a2a/create.ts
 function firstScheme(options) {
@@ -146,23 +146,20 @@ async function signCard(card, signPayload) {
 function missingScope(permission, scope) {
 	return {
 		ok: false,
-		status: 401,
+		status: 403,
 		state: "failed",
-		problem: {
-			type: "https://permdock.com/problems/unauthenticated",
-			title: "Insufficient scope",
-			status: 401,
-			detail: `insufficient_scope: ${scope}`,
+		problem: statusProblem(403, `insufficient_scope: ${scope}`, {
 			permission: permission.key,
 			scope
-		},
+		}),
 		wwwAuthenticate: bearerChallenge({
 			error: "insufficient_scope",
 			scopes: [scope]
 		})
 	};
 }
-function createPermDock(policy, options) {
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
 	for (const [id, config] of Object.entries(options.skills)) if (config.permission.kind === "instance" && config.data === void 0) throw new TypeError(`PermDock: A2A skill '${id}' checks ${config.permission.key} on a row and needs a data loader; the task body is never used as the row`);
 	const kernel = createAgentKernel(policy, compact({
 		subject: options.subject,
@@ -183,7 +180,7 @@ function createPermDock(policy, options) {
 		}
 		const scheme = firstScheme(options);
 		const skills = [];
-		for (const [id, config] of Object.entries(options.skills)) if (mayUse(permdock, config.permission)) skills.push(skillOf(id, config, scheme));
+		for (const [id, config] of Object.entries(options.skills)) if (permdock.mayUse(config.permission)) skills.push(skillOf(id, config, scheme));
 		return cardOf(options, skills);
 	};
 	const protectSkill = (selector) => async (task, auth) => {

package/dist/{adapter-context-mlWsVGGg.js → adapter-context-CRhqyzCk.js}

@@ -1,4 +1,4 @@
-import { n as isActor } from "./subject-C6dLxqHU.js";
+import { n as isActor } from "./subject-BGoM5o8B.js";
 //#region src/core/adapter-context.ts
 /** Resolves an adapter `tenant` option against its framework context; a throw is no tenant. */
 async function tenantScope(option, context) {

package/dist/adoption-scan-B4R5fnMU.js

@@ -0,0 +1,107 @@
+import { r as listSourceFiles } from "./files-D_JIzUrP.js";
+import { t as DOCS_BASE } from "./manifest-CtKR3GXL.js";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+//#region src/cli/adoption-scan.ts
+/** Authorization checks written before PermDock, by the shape they usually take. */
+const LEGACY_PATTERNS = [
+	{
+		name: "role comparison",
+		pattern: /\brole\s*[!=]==?\s*['"`]/u
+	},
+	{
+		name: "roles.includes",
+		pattern: /\broles?\.(?:includes|some|has)\(/u
+	},
+	{
+		name: "isAdmin flag",
+		pattern: /\bis(?:Admin|Owner|SuperUser|Staff)\b/u
+	},
+	{
+		name: "hasRole / hasPermission",
+		pattern: /\b(?:has|check|require)(?:Role|Permission|Access)s?\(/u
+	},
+	{
+		name: "CASL ability",
+		pattern: /\bability\.(?:can|cannot)\(/u
+	},
+	{
+		name: "Clerk has()",
+		pattern: /\bhas\(\s*\{\s*(?:role|permission)\s*:/u
+	},
+	{
+		name: "JWT role claim",
+		pattern: /\[['"](?:role|roles|user_role)['"]\]/u
+	}
+];
+/**
+* Lines that look like an authorization check written without PermDock:
+* the work left before a permission can be enforced. It reads source text
+* only and runs nothing; a finding is a place to look, not a verdict.
+*/
+function scanLegacy(options) {
+	const custom = (options.patterns ?? []).map((source) => ({
+		name: "custom",
+		pattern: new RegExp(source, "u")
+	}));
+	const patterns = [...LEGACY_PATTERNS, ...custom];
+	const findings = [];
+	for (const file of listSourceFiles(options.cwd, options.srcPath)) {
+		const lines = readFileSync(file, "utf8").split("\n");
+		for (const [index, line] of lines.entries()) {
+			if (/permdock/iu.test(line)) continue;
+			const hit = patterns.find((item) => item.pattern.test(line));
+			if (hit !== void 0) findings.push({
+				file: relative(options.cwd, file),
+				line: index + 1,
+				kind: hit.name,
+				text: line.trim().slice(0, 160)
+			});
+		}
+	}
+	return findings;
+}
+function runAdoptionScan(options) {
+	let findings;
+	try {
+		findings = scanLegacy(options);
+	} catch (error) {
+		return {
+			code: 2,
+			output: `permdock scan: ${error instanceof Error ? error.message : String(error)}\n`
+		};
+	}
+	const located = findings.map((finding) => ({
+		code: "legacy-check",
+		severity: "info",
+		message: `${finding.kind}: ${finding.text}`,
+		file: finding.file,
+		line: finding.line,
+		docs: `${DOCS_BASE}/scan`
+	}));
+	if (options.json === true) return {
+		code: 0,
+		output: `${JSON.stringify(findings, null, 2)}\n`,
+		findings: located
+	};
+	if (findings.length === 0) return {
+		code: 0,
+		output: "No legacy authorization checks found.\n",
+		findings: []
+	};
+	const byKind = /* @__PURE__ */ new Map();
+	for (const finding of findings) byKind.set(finding.kind, (byKind.get(finding.kind) ?? 0) + 1);
+	return {
+		code: 0,
+		output: `${[
+			...findings.map((finding) => `${finding.file}:${finding.line}  ${finding.kind}  ${finding.text}`),
+			"",
+			`${findings.length} checks to move to PermDock: ${[...byKind].map(([kind, count]) => `${count} ${kind}`).join(", ")}.`,
+			"Run them beside PermDock with shadowMode before enforcing (https://permdock.com/docs/getting-started/existing-apps).",
+			...byKind.has("CASL ability") ? ["CASL rules import as roles: permdock casl import --rules <file> --out <file> (https://permdock.com/docs/cli/casl)."] : []
+		].join("\n")}\n`,
+		findings: located
+	};
+}
+//#endregion
+export { runAdoptionScan };

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+import { n as DeniedTextEvent, t as DeniedText } from "../denied-text-D8jDHgsl.js";
+import { a as createPermDock, c as ModelMap, i as OperationVerdict, l as ToolBinding, n as AgentPermDockOptions, o as AgentAdapterOptions, r as GatewayOptions, s as DecideToolOptions, t as AgentPermDock, u as ToolMap } from "../create-BDS7wc3y.js";
+export { type AgentAdapterOptions, type AgentPermDock, type AgentPermDockOptions, type DecideToolOptions, type DeniedText, type DeniedTextEvent, type GatewayOptions, type ModelMap, type OperationVerdict, type ToolBinding, type ToolMap, createPermDock };

package/dist/agent/index.js

@@ -0,0 +1 @@
+export { n as createPermDock } from "../create-C3b4B5eF.js";

package/dist/ai-sdk/index.d.ts

@@ -1,40 +1,14 @@
-import { E as Policy, Or as Principal, wr as Delegation } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { f as ApprovalStore } from "../types-Br9IXUBG.js";
-import { t as InstanceOptions } from "../instance-options-plkrsAog.js";
-import { n as OnDeniedText, t as DeniedTextEvent } from "../denied-text-DfRk15uw.js";
-import { t as RequestContext } from "../request-context-C2_1lchh.js";
-import { t as ToolMap } from "../types-DvupZE0w.js";
-import { n as PermDockWrap } from "../wrap-Cr93qqdP.js";
+import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { n as DeniedTextEvent, t as DeniedText } from "../denied-text-D8jDHgsl.js";
+import { o as AgentAdapterOptions, t as AgentPermDock } from "../create-BDS7wc3y.js";
 //#region src/ai-sdk/create.d.ts
 type AiSdkContext = {
   readonly runtimeContext?: unknown;
   readonly permdockApproval?: string;
   readonly [key: string]: unknown;
 };
-type AiSdkPermDockOptions<TUser = unknown> = InstanceOptions & {
-  readonly subject: (context: AiSdkContext) => TUser | Promise<TUser>;
-  readonly actor?: (context: AiSdkContext) => unknown;
-  readonly delegation?: (context: AiSdkContext) => Delegation | undefined | Promise<Delegation | undefined>;
-  readonly tenant?: string | ((context: AiSdkContext) => string | undefined | Promise<string | undefined>);
-  readonly tools: ToolMap;
-  readonly store?: ApprovalStore;
-  /**
-   * Tools the `tools` map does not bind to a permission. `'deny'` (default):
-   * the middleware hides them and `toolApproval` denies them. `'allow'`: they
-   * pass through both, to the application's own `toolApproval`.
-   */
-  readonly unmapped?: "deny" | "allow";
-  /**
-   * Request values merged into `subject.context`, under `policy.context`.
-   * Only values the server derived belong here, never model output.
-   */
-  readonly context?: (context: AiSdkContext) => RequestContext | undefined | Promise<RequestContext | undefined>;
-  /** Wraps each instance; build it with `wrapPermDock` to cover derived instances. */
-  readonly wrap?: PermDockWrap;
-  /** Replaces the denial reason or approval summary text; nothing else. */
-  readonly onDenied?: OnDeniedText;
-};
+type AiSdkPermDockOptions<TUser = unknown> = AgentAdapterOptions<AiSdkContext, TUser>;
 /** What an AI SDK tool approval function may return; `undefined` is `not-applicable`. */
 type ToolApprovalResult = ToolApprovalStatus | undefined | "not-applicable" | "denied" | "user-approval" | {
   readonly type: "not-applicable";
@@ -80,14 +54,19 @@ type CallParams = {
   }[];
   readonly toolChoice?: unknown;
 };
+/** The part of `LanguageModelV4` the model gate reads. */
+type CallModel = {
+  readonly modelId?: unknown;
+};
 /** Structural `LanguageModelMiddleware` (specification `v4`) from `ai`. */
 type LanguageModelMiddleware = {
   readonly specificationVersion: "v4";
   readonly transformParams: <TParams extends CallParams>(options: {
     readonly params: TParams;
+    readonly model?: CallModel;
   }) => Promise<TParams>;
 };
-type AiSdkPermDock = {
+type AiSdkPermDock<V extends PolicyVocabulary = PolicyVocabulary> = AgentPermDock<AiSdkContext, V> & {
   readonly toolApproval: (call: ToolApprovalCall) => Promise<ToolApprovalStatus>;
   /**
    * PermDock's `toolApproval` followed by the application's own: `app` is
@@ -98,10 +77,14 @@ type AiSdkPermDock = {
    * come first.
    */
   readonly composeToolApproval: (app: AppToolApproval) => (call: ToolApprovalCall) => Promise<ToolApprovalResult>;
-  /** Hides tools the subject in `context` can never use, before the model sees them. */
+  /**
+   * Hides tools the subject in `context` can never use, before the model
+   * sees them. With `models`, a call to a model the subject is not granted
+   * throws `PermDockDeniedError` before the provider is called.
+   */
   readonly capabilityMiddleware: (context: AiSdkContext) => LanguageModelMiddleware;
   readonly needsApproval: (permission: Permission) => (input: unknown, options?: NeedsApprovalOptions) => Promise<boolean>;
 };
-export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: AiSdkPermDockOptions<TUser>): AiSdkPermDock;
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: AiSdkPermDockOptions<TUser>): AiSdkPermDock<V>;
 //#endregion
-export type { AiSdkContext, AiSdkPermDock, AiSdkPermDockOptions, AppToolApproval, DeniedTextEvent, LanguageModelMiddleware, NeedsApprovalOptions, OnDeniedText, ToolApprovalCall, ToolApprovalResult, ToolApprovalStatus };
+export type { AiSdkContext, AiSdkPermDock, AiSdkPermDockOptions, AppToolApproval, DeniedText, DeniedTextEvent, LanguageModelMiddleware, NeedsApprovalOptions, ToolApprovalCall, ToolApprovalResult, ToolApprovalStatus };