permdock 0.1.0 → 0.2.0

package/README.md

@@ -3,42 +3,32 @@
 **Typed permissions for TypeScript apps, APIs, databases and AI agents.**
 
 [![npm](https://img.shields.io/npm/v/permdock?label=permdock)](https://www.npmjs.com/package/permdock)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ScaleDockHQ/permdock/blob/main/LICENSE)
-[![CI](https://img.shields.io/github/actions/workflow/status/ScaleDockHQ/permdock/ci.yml?label=CI)](https://github.com/ScaleDockHQ/permdock/actions)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ScaleDockHQ/PermDock/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/ScaleDockHQ/PermDock/ci.yml?label=CI)](https://github.com/ScaleDockHQ/PermDock/actions)
 ![Node.js 24+](https://img.shields.io/badge/Node.js-24%2B-5fa04e.svg)
 ![TypeScript 7](https://img.shields.io/badge/TypeScript-7-3178c6.svg)
 
-Define permissions once as typed references over the Zod, Valibot or ArkType schemas you already have. Grant them to roles with portable conditions. Check them in React, React Native, Next.js, Hono, tRPC and MCP servers. Compile the same conditions to SQL `where` clauses and Postgres Row Level Security policies. Drive tool approvals in the Vercel AI SDK, the Claude Agent SDK, Eve and the OpenAI Agents SDK from the same decision.
+Define permissions once as typed references over the Zod, Valibot or ArkType schemas you already have. Grant them to roles with portable conditions. Check them in React, Next.js, Hono, tRPC, MCP servers and agent runtimes, and compile the same conditions to SQL `where` clauses and Postgres Row Level Security.
 
-> **Pre-release.** The first published version is `0.1.0`. See the [roadmap](https://permdock.dev/docs/roadmap).
-
-[Docs](https://permdock.dev/docs) · [Quick start](https://permdock.dev/docs/getting-started/quick-start) · [Adapters](https://permdock.dev/docs/adapters) · [For AI agents](https://permdock.dev/docs/for-ai-agents) · [Source](https://github.com/ScaleDockHQ/permdock)
-
-## Install
+[Docs](https://permdock.com/docs) · [Quick start](https://permdock.com/docs/getting-started/quick-start) · [Adapters](https://permdock.com/docs/adapters) · [Existing apps](https://permdock.com/docs/getting-started/existing-apps) · [For AI agents](https://permdock.com/docs/for-ai-agents) · [Changelog](https://github.com/ScaleDockHQ/PermDock/blob/main/packages/permdock/CHANGELOG.md) · [Source](https://github.com/ScaleDockHQ/PermDock)
 
 ```bash
-pnpm add permdock   # core, every adapter as a subpath export, the permdock CLI and permdock/testing
+pnpm add permdock
 ```
 
-- One package. Core is `permdock`; every adapter is a subpath (`permdock/react`, `permdock/hono`, `permdock/next`, `permdock/ai-sdk`, …). The `permdock` binary (`collect`, `catalog`, `usage`, `openapi`, `rls`, `doctor`, `skills`) and the `permdock/testing` runners ship in the same package.
-- ESM only. Node.js 24 or later. Written in and tested with TypeScript 7; the public types are also checked under TypeScript 5.9 and 6.
-- Runtime entries depend on `@standard-schema/spec` only. The CLI's dependencies (`oxc-parser`, `citty`, `jiti`, `smol-toml`, `package-manager-detector`, `@clack/prompts`, `diff`) never reach them. Framework SDKs are optional peers, and structurally typed providers (`supabase`, `clerk`, `better-auth`, `convex`, `prisma`, `mcp`, `react-native`) declare no peer at all.
+One package: core, every adapter as a subpath export, the `permdock` CLI and `permdock/testing`. ESM only, Node.js 24 or later, built with TypeScript 7 and type-checked under 5.9 and 6. Runtime entries depend on `@standard-schema/spec` only; framework SDKs are optional peers.
 
-## Why PermDock
+## One definition, one decision
 
-Permission logic in a typical TypeScript app is spread across `if (user.role === 'admin')` checks in components, string keys like `'post:update'` in middleware, a hand-written client copy of the server rules, RLS policies nobody can diff against the app, and AI agents that call tools on a user's behalf with no way to say "ask first". PermDock replaces all of that with one definition and one decision object.
+| Surface   | What PermDock gives it                                                                         |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| UI        | A JSON snapshot with conditions, `<Protected>` and `usePermission`, answered offline           |
+| HTTP, RPC | `protect` guards that answer a denial with RFC 9457 Problem Details                            |
+| Database  | `where()` for Drizzle, Prisma and Kysely; generated Postgres RLS with a parity check           |
+| Agents    | Filtered tool lists, model-readable refusals, human approvals with a replay-safe token         |
+| CI        | A committed catalog, `permdock diff` that fails on a breaking change, `permdock doctor` checks |
 
-- **Reference-based.** `permissions.post.update` is a typed, frozen object carrying `key`, `scope`, schema and metadata. Go-to-definition works, renames are safe, and the runtime definition is the catalog.
-- **Standard Schema native.** Resources are built from any [Standard Schema](https://standardschema.dev) validator; instance types are inferred; untrusted input is validated at trust boundaries only.
-- **Policy as data.** Roles are arrays of `allow` / `deny` grants with a portable condition AST. One condition evaluates in the browser, filters arrays, compiles to Drizzle / Prisma / Kysely `where`, and generates Postgres RLS.
-- **Multi-tenant roles.** A role is held globally, in a tenant, in a team or on one resource: `role('admin', grants, { on: 'tenant' })` replaces the `orgId` condition you used to repeat on every grant. Memberships come from your auth provider; PermDock stores nothing. Read [tenants, teams and scoped roles](https://permdock.dev/docs/concepts/tenancy).
-- **Decisions, not booleans.** `decide()` returns `granted`, `denied` or `approval-required` with the matched grant, denial reasons and permitted alternatives. Adapters turn that into RFC 9457 Problem Details, model-readable MCP refusals and AI SDK approval states.
-- **Snapshots that carry conditions.** The client answers ownership checks offline with no duplicated rules, and `<Protected>` never blocks a Next.js 16.3 instant navigation.
-- **Agent-native.** A two-principal subject (principal, actor, delegation), adapters for MCP, the AI SDK, the Claude Agent SDK, Eve, the OpenAI Agents SDK, WebMCP and A2A, an AuthZEN 1.0 decision endpoint, and bundled agent skills.
-- **Human approvals that resume safely.** `approval: 'human'` grants yield a third outcome with a replay-safe `token`. Pending approvals live in a pluggable `ApprovalStore`; approvers are authenticated and never the agent; plain HTTP resumes with a `PermDock-Approval` header.
-- **Secure by default.** Fail-closed, deny overrides allow, an unknown reference is a type error, prototype-safe, no eval, `service_role` never emitted, model-supplied subjects never trusted, an agent with no delegation denied, no one approving their own request, never a default tenant, data validated against the resource schema unless the caller marks a row it loaded `trusted: true`.
-- **Authentication stays upstream.** PermDock consumes verified material only: sessions, JWKS-verified JWTs (`permdock/jwt`, with `jose` as an optional peer), Supabase, Clerk and Better Auth claims, MCP `authInfo`. Token failures become RFC 6750 challenges, never thrown errors. Read [authentication](https://permdock.dev/docs/concepts/authentication).
-- **The Cloud is optional.** Every decision runs in-process. PermDock Cloud adds a decision log, access reviews, an approval inbox, a hosted AuthZEN endpoint and a SCIM relay, all behind interfaces this package ships with in-process defaults. Read [PermDock Cloud](https://permdock.dev/docs/adapters/cloud).
+Every check returns one of three outcomes: `granted`, `denied` or `approval-required`. Anything unknown, invalid or thrown denies, and a deny overrides an allow.
 
 ## Quick start
 
@@ -71,9 +61,11 @@ export const roles = defineRoles({ member: {}, admin: { on: "tenant" } });
 permissions.post.update.key; // 'post.update'
 ```
 
+`permissions.post.update` is a frozen object, not a string: go-to-definition works, a rename is a type error everywhere it is used, and the definition is the catalog.
+
 ### 2. Write the policy
 
-Server-only. Roles are data; conditions are portable.
+Server-only. Roles are data; conditions are a portable JSON tree.
 
 ```ts
 // src/policy.ts
@@ -113,7 +105,7 @@ export const policy = definePolicy(
 );
 ```
 
-`subjectFromClerk`, `subjectFromBetterAuth`, `subjectFromSupabase` and `subjectFromJwt` produce `memberships` from the provider you already use.
+`subjectFromClerk`, `subjectFromBetterAuth`, `subjectFromSupabase` and `subjectFromJwt` produce `memberships` from the provider you already use. PermDock stores no tenants, teams or memberships.
 
 ### 3. Decide
 
@@ -123,11 +115,14 @@ import { createPermDock } from "permdock";
 const permdock = await createPermDock(policy, user); // frozen, request-scoped, never throws
 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
 permdock.filter(permissions.post.read, posts); // Post[]
 permdock.where(permissions.post.read); // portable condition for Drizzle / Prisma / Kysely / SQL
 permdock.snapshot({ include: [permissions.post] }); // JSON for the client
 ```
 
+## Use it where the check happens
+
 ### React
 
 ```tsx
@@ -146,7 +141,7 @@ import { PermDockProvider, Protected, usePermission } from "permdock/react";
 const { allowed, status } = usePermission(permissions.post.update, post);
 ```
 
-The same hook names exist in React Native, Vue, Svelte and Solid. Read [building UI](https://permdock.dev/docs/concepts/ui).
+The same hook names exist in React Native, Vue, Svelte and Solid. Read [building UI](https://permdock.com/docs/concepts/ui).
 
 ### Next.js 16.3
 
@@ -206,6 +201,8 @@ protectServer(server).registerTool(
 
 ### AI SDK
 
+The Claude Agent SDK, Eve, the OpenAI Agents SDK, WebMCP and A2A have their own entries with the same tool map.
+
 ```ts
 import { createPermDock } from "permdock/ai-sdk";
 
@@ -225,36 +222,98 @@ const { toolApproval } = createPermDock(policy, {
 generateText({ model, tools, toolApproval }); // granted → approved, denied → denied, approval-required → user-approval
 ```
 
-### RLS
+### Postgres RLS
 
 ```bash
 permdock rls generate --target drizzle --dialect supabase   # roles × grants → policies
 permdock rls verify --db $DATABASE_URL                      # can() vs database parity
 ```
 
+## Agents and approvals
+
+An agent acts for a user, so a subject has two principals: the user (`principal`) and the agent (`actor`). Policy `delegations` cap what an actor may do for a user, and an approval grant pauses the call until people other than the requester approve it.
+
+```ts
+import { actor, allow, definePolicy } from "permdock";
+
+const policy = definePolicy(permissions, {
+  roles: [member, finance],
+  delegations: [
+    {
+      from: roles.member,
+      to: actor("eve"),
+      permissions: [permissions.post.read, permissions.post.update],
+      validUntil: "2027-06-01T00:00:00Z",
+    },
+  ],
+  subject,
+});
+
+allow(permissions.payout.release, {
+  approval: {
+    by: roles.finance,
+    quorum: 2, // two distinct finance approvers
+    ttl: "30m",
+    escalation: { after: "10m", to: roles.cfo },
+  },
+});
+```
+
+Approvers are authenticated and are never the agent, no one approves their own request by default, and the resumed call carries a token bound to the permission and the data. Read [delegation](https://permdock.com/docs/security/delegation) and [approvals](https://permdock.com/docs/security/approvals).
+
+## Existing apps
+
+PermDock adopts the permission keys, SQL helpers, tokens and stored custom roles an app already has, in steps that each leave the app working: generated helpers beside the hand-written SQL, `permdock rls migrate` to rewrite policies, and `renamed` aliases for keys you change later. `permdock doctor` reports what still uses an old key. Read [existing apps](https://permdock.com/docs/getting-started/existing-apps).
+
+## CLI
+
+| Command                  | What it does                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------------ |
+| `permdock collect`       | Scan the sources and write `permissions.catalog.json`; `--check` in CI               |
+| `permdock diff a b`      | Compare two policies or catalogs; exit `1` on a breaking change; `--impact`          |
+| `permdock doctor`        | Check wiring, imports, catalog freshness and security defaults; print a fix for each |
+| `permdock usage`         | Report unused, ungranted and role-less permissions                                   |
+| `permdock rls`           | `generate`, `import`, `verify` and `migrate` Postgres RLS policies                   |
+| `permdock supabase hook` | Generate the Supabase Custom Access Token Hook from your membership sources          |
+| `permdock openapi`       | Emit `security` into an OpenAPI document or Overlay, or import one                   |
+| `permdock skills`        | Install the PermDock Agent Skills from `node_modules/permdock/skills`                |
+
+`catalog`, `arazzo check` and `cloud push` complete the list. Every command takes `--json`; under it, a failure prints RFC 9457 Problem Details. Read [CLI](https://permdock.com/docs/cli).
+
 ## Works with
 
 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`                                                                             |
-| Auth and providers | `permdock/jwt` · `permdock/supabase` · `permdock/supabase/middleware` · `permdock/better-auth` · `permdock/clerk` · `permdock/convex`                   |
-| Build              | `permdock/next/plugin` · `permdock/unplugin`                                                                                                            |
-| Testing            | `permdock/testing`                                                                                                                                      |
-
-Nuxt, Astro, React Router, TanStack Start and Effect use these entries plus `permdock/unplugin`. The full matrix with example apps and related standards is on the [adapters page](https://permdock.dev/docs/adapters).
+| 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).
+
+## 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`.
+- 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.
+
+Read the [threat model](https://permdock.com/docs/security/threat-model).
 
 ## Compared with
 
-Other TypeScript permission libraries (CASL, permix, Kilpi, `@zap-studio/permit`) return booleans from string keys and stop at the server or the UI. Hosted PDPs (Cerbos, Permit.io, OpenFGA, SpiceDB) put a network call on every check. PermDock is an embedded, typed library with one decision object across UI, API, SQL, RLS and agent approvals. Read the [comparison](https://permdock.dev/docs/comparison).
+Other TypeScript permission libraries (CASL, permix, Kilpi, `@zap-studio/permit`) return booleans from string keys and stop at the server or the UI. Hosted PDPs (Cerbos, Permit.io, OpenFGA, SpiceDB) put a network call on every check. PermDock is an embedded, typed library with one decision object across UI, API, SQL, RLS and agent approvals. Read the [comparison](https://permdock.com/docs/comparison).
 
 ## For AI agents
 
@@ -263,8 +322,8 @@ npx skills add ScaleDockHQ/PermDock   # the permdock, permdock-wire, permdock-au
 permdock skills                       # 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, plus `llms.txt` and `llms-full.txt`. Read [for AI agents](https://permdock.dev/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/mcp`. Read [for AI agents](https://permdock.com/docs/for-ai-agents).
 
 ## License
 
-[MIT](https://github.com/ScaleDockHQ/permdock/blob/main/LICENSE) © 2026 ScaleDockHQ. Report vulnerabilities privately through [GitHub security advisories](https://github.com/ScaleDockHQ/permdock/security/advisories/new).
+[MIT](https://github.com/ScaleDockHQ/PermDock/blob/main/LICENSE) © 2026 ScaleDockHQ. Report vulnerabilities privately through [GitHub security advisories](https://github.com/ScaleDockHQ/PermDock/security/advisories/new).

package/dist/a2a/index.d.ts

@@ -1,7 +1,8 @@
-import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, or as AuthorizationDetail, 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 { o as ProblemDetails } from "../errors-DbZ1YOnb.js";
+import { C as Policy, Nr as Principal, Tr as AuthorizationDetail } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { a as ProblemDetails } from "../errors-DAqevpNk.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
 //#region src/a2a/types.d.ts
 type A2aAuth = {
   readonly clientId?: string;
@@ -138,28 +139,18 @@ type A2aTaskOutcome = {
   readonly ok: true;
 } | {
   readonly ok: false;
-  readonly status: 401 | 403;
+  readonly status: 401 | 403 | 429 | 503;
   readonly state: "failed" | "input-required";
   readonly problem: ProblemDetails;
   readonly wwwAuthenticate?: string;
 };
-type A2aPermDockOptions<TUser = unknown> = {
+type A2aPermDockOptions<TUser = unknown> = InstanceOptions & {
   readonly subject: (auth: A2aAuth) => TUser | Promise<TUser>;
   readonly card: A2aCardInfo;
   readonly securitySchemes: Readonly<Record<string, A2aSecurityScheme>>;
   readonly skills: Readonly<Record<string, A2aSkillConfig>>;
   readonly tenant?: string | ((auth: A2aAuth) => string | undefined | Promise<string | undefined>);
-  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;
 };
 type A2aPermDock = {
   readonly agentCard: () => A2aAgentCard;

package/dist/a2a/index.js

@@ -1,15 +1,14 @@
 import { t as compact } from "../compact-y6vfu2_f.js";
-import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
-import { l as canonicalJson } from "../snapshot-DE8dE_hz.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Cz5zn0mW.js";
+import { t as canonicalJson } from "../canonical-json-DemiK4Vp.js";
 import { t as bytesToBase64Url } from "../sha256-BO0swRXL.js";
-import { t as createPermDock$1 } from "../permdock-yoZ7EjxX.js";
-import { t as mayUse } from "../may-use-CnFEjVEp.js";
-import { l as storedApprovalToken, s as resumeDecision } from "../helpers-DnSOrhB9.js";
-import { r as bearerChallenge } from "../problem-Cgp9-KZA.js";
+import { i as scopesReaching, r as challengeScope } from "../permdock-CzqXjCpU.js";
+import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
+import { t as mayUse } from "../may-use-DndQ5tQ-.js";
+import { d as wwwAuthenticate, n as bearerChallenge } from "../problem-B43ztKIm.js";
+import { t as instanceOptions } from "../instance-options-Dhhcnm3y.js";
+import { n as createAgentKernel } from "../kernel-GSQnMz3O.js";
 //#region src/a2a/create.ts
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function firstScheme(options) {
 	return Object.keys(options.securitySchemes)[0];
 }
@@ -88,24 +87,8 @@ function actorOf(auth) {
 		kind: "oauth-client"
 	} : void 0;
 }
-async function resolveTenant(tenant, auth) {
-	if (tenant === void 0 || typeof tenant === "string") return tenant;
-	try {
-		return await tenant(auth);
-	} catch {
-		return;
-	}
-}
-function hasScope(auth, scope) {
-	return auth.scopes?.includes(scope) === true;
-}
-function resourceRef(permission, data) {
-	if (!isRecord(data)) return { type: permission.resource };
-	const id = data["id"];
-	return typeof id === "string" || typeof id === "number" ? {
-		type: permission.resource,
-		id: String(id)
-	} : { type: permission.resource };
+function hasScope(auth, scopes) {
+	return scopes.some((scope) => auth.scopes?.includes(scope) === true);
 }
 const LOAD_FAILED = {
 	outcome: "denied",
@@ -115,20 +98,29 @@ const LOAD_FAILED = {
 	}],
 	alternatives: []
 };
-function deniedOutcome(decision, permission, data, permdock) {
-	return {
+const NO_SUBJECT = {
+	principal: null,
+	context: {}
+};
+function taskStatus(status) {
+	return status === 401 || status === 429 || status === 503 ? status : 403;
+}
+function deniedOutcome(decision, permission, data, subject) {
+	const problem = new PermDockDeniedError({
+		decision,
+		permission: permission.key,
+		scope: permission.scope,
+		resource: resourceRef(permission, data),
+		subject: subject ?? NO_SUBJECT,
+		message: `${permission.key} denied.`
+	}).toProblemDetails();
+	return compact({
 		ok: false,
-		status: 403,
+		status: taskStatus(problem.status),
 		state: "failed",
-		problem: new PermDockDeniedError({
-			decision,
-			permission: permission.key,
-			scope: permission.scope,
-			resource: resourceRef(permission, data),
-			subject: permdock.subject,
-			message: `${permission.key} denied.`
-		}).toProblemDetails()
-	};
+		problem,
+		wwwAuthenticate: wwwAuthenticate(decision, permission, false)
+	});
 }
 function approvalOutcome(decision, permission, data) {
 	return {
@@ -158,51 +150,44 @@ async function signCard(card, signPayload) {
 		}]
 	};
 }
-function missingScope(permission) {
+function missingScope(permission, scope) {
 	return {
 		ok: false,
 		status: 401,
 		state: "failed",
 		problem: {
-			type: "https://permdock.dev/problems/unauthenticated",
+			type: "https://permdock.com/problems/unauthenticated",
 			title: "Insufficient scope",
 			status: 401,
-			detail: `insufficient_scope: ${permission.scope}`,
+			detail: `insufficient_scope: ${scope}`,
 			permission: permission.key,
-			scope: permission.scope
+			scope
 		},
 		wwwAuthenticate: bearerChallenge({
 			error: "insufficient_scope",
-			scopes: [permission.scope]
+			scopes: [scope]
 		})
 	};
 }
 function createPermDock(policy, options) {
 	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 instanceFor = async (auth) => {
-		let user = null;
+	const kernel = createAgentKernel(policy, compact({
+		subject: options.subject,
+		actor: actorOf,
+		delegation: delegationOf,
+		tenant: options.tenant,
+		store: options.store,
+		adapter: "a2a",
+		...instanceOptions(options)
+	}));
+	const agentCard = () => cardOf(options, publicSkills(options));
+	const extendedAgentCard = async (auth) => {
+		let permdock;
 		try {
-			user = await options.subject(auth);
+			permdock = await kernel.instance(auth);
 		} catch {
-			user = null;
+			return cardOf(options, []);
 		}
-		const tenant = await resolveTenant(options.tenant, auth);
-		return createPermDock$1(policy, user, compact({
-			tenant,
-			actor: actorOf(auth),
-			delegation: delegationOf(auth),
-			memberships: options.memberships,
-			relations: options.relations,
-			entitlements: options.entitlements,
-			customRoles: options.customRoles,
-			policies: options.policies,
-			sink: options.sink,
-			limits: options.limits
-		}));
-	};
-	const agentCard = () => cardOf(options, publicSkills(options));
-	const extendedAgentCard = async (auth) => {
-		const permdock = await instanceFor(auth);
 		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));
@@ -216,46 +201,22 @@ function createPermDock(policy, options) {
 			status: 403,
 			state: "failed",
 			problem: {
-				type: "https://permdock.dev/problems/denied",
+				type: "https://permdock.com/problems/denied",
 				title: "Permission denied",
 				status: 403,
 				detail: "unknown skill"
 			}
 		};
-		if (!hasScope(auth, config.permission.scope)) return missingScope(config.permission);
-		const permdock = await instanceFor(auth);
-		let data;
-		if (config.data !== void 0) {
-			try {
-				data = await config.data(task);
-			} catch {
-				return deniedOutcome(LOAD_FAILED, config.permission, void 0, permdock);
-			}
-			if (config.permission.kind === "instance" && (data === null || data === void 0)) return deniedOutcome(LOAD_FAILED, config.permission, void 0, permdock);
-		}
-		let decision;
-		try {
-			const raw = permdock.decide(config.permission, data, compact({
-				source: "adapter",
-				adapter: "a2a",
-				trusted: false,
-				boundary: "tool-args"
-			}));
-			decision = await resumeDecision({
-				decision: raw,
-				permission: config.permission,
-				subject: permdock.subject,
-				store: options.store,
-				resource: resourceRef(config.permission, data),
-				adapter: "a2a",
-				token: auth.extra?.approval ?? await storedApprovalToken(options.store, raw, false)
-			});
-		} catch {
-			return deniedOutcome(LOAD_FAILED, config.permission, data, permdock);
-		}
+		if (!hasScope(auth, scopesReaching(policy, config.permission))) return missingScope(config.permission, challengeScope(policy, config.permission));
+		const checked = await kernel.check(compact({
+			permission: config.permission,
+			data: config.data
+		}), task, auth, compact({ resumeToken: auth.extra?.approval }));
+		if (!checked.ok) return deniedOutcome(LOAD_FAILED, config.permission, void 0, checked.permdock?.subject);
+		const { decision, data, permdock } = checked;
 		switch (decision.outcome) {
 			case "granted": return { ok: true };
-			case "denied": return deniedOutcome(decision, config.permission, data, permdock);
+			case "denied": return deniedOutcome(decision, config.permission, data, permdock.subject);
 			case "approval-required": return approvalOutcome(decision, config.permission, data);
 			default: return decision;
 		}

package/dist/adapter-context-mlWsVGGg.js

@@ -0,0 +1,23 @@
+import { n as isActor } from "./subject-C6dLxqHU.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) {
+	if (option === void 0 || typeof option === "string") return { tenant: option };
+	try {
+		return { tenant: await option(context) };
+	} catch {
+		return { tenant: void 0 };
+	}
+}
+/** Resolves an adapter `actor` option; anything but an `Actor`, or a throw, is no actor. */
+async function actorFrom(option, context) {
+	if (option === void 0) return;
+	try {
+		const resolved = await option(context);
+		return isActor(resolved) ? resolved : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { tenantScope as n, actorFrom as t };

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

@@ -1,31 +1,43 @@
-import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, ur as Delegation, 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 ToolMap } from "../types-CxquUByI.js";
+import { C as Policy, Nr as Principal, kr as Delegation } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
+import { t as ToolMap } from "../types-Bvc4oWT6.js";
 //#region src/ai-sdk/create.d.ts
 type AiSdkContext = {
   readonly runtimeContext?: unknown;
   readonly permdockApproval?: string;
   readonly [key: string]: unknown;
 };
-type AiSdkPermDockOptions<TUser = 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 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;
+  /**
+   * 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";
 };
+/** 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";
+} | {
+  readonly type: "approved";
+  readonly reason?: string;
+} | {
+  readonly type: "denied";
+  readonly reason?: string;
+} | {
+  readonly type: "user-approval";
+  readonly reason?: string;
+};
+/** An application's own tool approval function, in the AI SDK's generic form. */
+type AppToolApproval = (call: ToolApprovalCall) => ToolApprovalResult | PromiseLike<ToolApprovalResult>;
 type ToolApprovalStatus = "approved" | {
   readonly type: "denied";
   readonly reason: string;
@@ -65,10 +77,19 @@ type LanguageModelMiddleware = {
 };
 type AiSdkPermDock = {
   readonly toolApproval: (call: ToolApprovalCall) => Promise<ToolApprovalStatus>;
+  /**
+   * PermDock's `toolApproval` followed by the application's own: `app` is
+   * asked only for a call PermDock grants (or an unmapped tool under
+   * `unmapped: 'allow'`), and its answer is returned as is, `undefined`
+   * included (not applicable, as the AI SDK reads it). An answer that is not
+   * a tool approval result denies. PermDock's denials and approval requests
+   * come first.
+   */
+  readonly composeToolApproval: (app: AppToolApproval) => (call: ToolApprovalCall) => Promise<ToolApprovalResult>;
   /** Hides tools the subject in `context` can never use, before the model sees them. */
   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;
 //#endregion
-export type { AiSdkContext, AiSdkPermDock, AiSdkPermDockOptions, LanguageModelMiddleware, NeedsApprovalOptions, ToolApprovalCall, ToolApprovalStatus };
+export type { AiSdkContext, AiSdkPermDock, AiSdkPermDockOptions, AppToolApproval, LanguageModelMiddleware, NeedsApprovalOptions, ToolApprovalCall, ToolApprovalResult, ToolApprovalStatus };