permdock 0.0.0 → 0.2.0

package/skills/permdock-agents/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: permdock-agents
+description: Guards AI agent tool calls with PermDock subjects, actors and delegation. Use when wiring tool maps in permdock/ai-sdk, permdock/claude-agent, permdock/openai, permdock/eve or permdock/mcp, separating the user (principal) from the agent (actor), declaring a delegation option or policy delegations, publishing an A2A Agent Card with permdock/a2a, registering WebMCP tools with permdock/webmcp, verifying Web Bot Auth signers as actors, or when agent calls are denied with no-delegation or not-delegated.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/security/delegation
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock agents
+
+An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.com/docs/security/delegation)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- Runtimes in use: AI SDK, Claude Agent SDK, OpenAI Agents SDK, Eve, an MCP server, an A2A agent, WebMCP tools in a web page, signed bot traffic over HTTP.
+- Where the principal comes from: the host session, a verified token, the runtime's session (Eve).
+- Where the actor id comes from: runtime context, `authInfo.clientId`, an Agent Card, a request signature.
+- What the user delegates, per call (scopes, `authorizationDetails`, GNAP `access`) or as standing policy ("members let the Eve agent read and update posts").
+- Which tools are destructive or move money.
+
+## Invariants
+
+1. Subject and actor come from the host session or verified transport auth, never from tool arguments, a task body, a header the client sets, or model output.
+2. An actor with no delegation is denied every check with `no-delegation`. Delegate explicit scopes, never the principal's whole role.
+3. Delegation only narrows. A policy delegation is a ceiling, a token delegation on the same call must also cover the permission, and a `deny` or an `approval` still applies.
+4. One permission per tool. An instance action loads its row through `data` from parsed arguments; a collection permission (`list`, `create`) on a handler that reads `args.id` is a bug.
+5. Tool lists are hints. `capabilityMiddleware`, `guardTools`, MCP list filtering, the A2A extended card, `mayUse` and WebMCP registration hide tools; the server adapter still decides each call.
+6. A failed Web Bot Auth signature throws `InvalidSignatureError`; it never becomes an anonymous actor.
+7. Protocol rules come from the spec skills (`npx skills add ScaleDockHQ/scaledock-skills --skill <name>`): `mcp-authorization` for MCP auth, `a2a` for Agent Cards, `webmcp` for page tools, `web-bot-auth` for signatures, `owasp-agentic` for the threat checklist.
+
+## Workflow
+
+1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each runtime from the Inputs. The adapter table on [delegation](https://permdock.com/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option).
+   ✓ Every surface has all three, and none reads from model-controlled input.
+2. **Map the tools.** Use the runtime's `createPermDock` with `subject`, `actor` and a `tools` map, and pass the returned hook to the runtime. -> [references/runtimes.md](references/runtimes.md)
+   ✓ Every tool the agent can call has a `permission`, and every instance permission has a `data` loader that parses its arguments.
+3. **Delegate.** Per call, return `{ scopes: [permissions.post.update.scope] }` (or `authorizationDetails`) from the `delegation` option. As standing policy, declare it once on the policy:
+
+   ```ts
+   definePolicy(permissions, {
+     roles: [member],
+     delegations: [
+       {
+         from: roles.member,
+         to: actor("eve"),
+         permissions: [permissions.post.read, permissions.post.update],
+       },
+     ],
+     subject,
+   });
+   ```
+
+   `from` takes a role, `authenticated()`, a plan or `assurance()`. `to` is an actor kind, or `{ kind, id }` for one agent. A permission outside the ceiling is denied with `not-delegated`.
+   ✓ The agent is granted a delegated tool, and denied with `not-delegated` or `no-delegation` for anything else.
+
+4. **Gate destructive tools.** Put `approval: { by }` on each destructive or money-moving grant and pass a `store` to the adapter. Follow the `permdock-approvals` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-approvals`).
+   ✓ A destructive tool returns the runtime's approval outcome instead of running.
+5. **Wire the agent-facing surfaces.** A2A: serve `agentCard()` publicly, `extendedAgentCard(auth)` behind auth, and `protectSkill` on the task endpoint. WebMCP: `registerTools` from a snapshot, with the server re-checking. Web Bot Auth: `webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys })` on the HTTP adapter. -> [references/runtimes.md](references/runtimes.md)
+   ✓ Each surface passes the Verify list of its spec skill.
+6. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive tool ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
+   ✓ The tests pass and the audit has no blocker.
+
+## Verify before done
+
+- [ ] No `subject`, `actor`, tenant or approval token is read from tool arguments, a task body or model output.
+- [ ] Every in-process agent adapter sets `delegation`, or a policy `delegations` entry covers its actor kind.
+- [ ] Every instance tool has a `data` loader; no collection permission guards a handler that reads one row.
+- [ ] MCP servers set `resource` to their own URL; Claude Agent `mcp__` tools come only from `mcpSources`.
+- [ ] WebMCP and capability filtering are backed by a server-side check on the same permission.
+- [ ] Every destructive tool returns `approval-required`, and the `permdock-approvals` Verify list passes.
+
+## Reference index
+
+- [references/runtimes.md](references/runtimes.md): factory shapes and outcome mapping for AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, Web Bot Auth and `permdock/terminal`.
+- Docs: [delegation](https://permdock.com/docs/security/delegation), [subject](https://permdock.com/docs/concepts/subject), [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), adapter pages under `https://permdock.com/docs/adapters/<name>`.

package/skills/permdock-agents/references/runtimes.md

@@ -0,0 +1,213 @@
+# Agent runtimes
+
+Every agent adapter exports `createPermDock` from `permdock/<runtime>` and takes `subject`, `actor`, `delegation`, `tools` and `store`. One permission per tool. Instance actions load the row through `data`; tool input arrives as `unknown`, so parse it before loading. The current adapter page is `https://permdock.com/docs/adapters/<name>`.
+
+## AI SDK — `permdock/ai-sdk`
+
+```ts
+import { createPermDock } from "permdock/ai-sdk";
+import { z } from "zod";
+
+const PostArgs = z.object({ id: z.string() });
+
+export const { toolApproval, capabilityMiddleware, needsApproval } =
+  createPermDock(policy, {
+    subject: ({ runtimeContext }) => runtimeContext.user,
+    actor: ({ runtimeContext }) => ({
+      id: runtimeContext.agentId,
+      kind: "ai-sdk",
+    }),
+    delegation: () => ({ scopes: [permissions.post.delete.scope] }),
+    tools: {
+      delete_post: {
+        permission: permissions.post.delete,
+        data: (args) => loadPost(PostArgs.parse(args).id),
+      },
+    },
+  });
+```
+
+Pass `toolApproval` into `generateText` / `ToolLoopAgent`. Wrap the model with `wrapLanguageModel({ model, middleware: capabilityMiddleware({ user }) })` per caller. Use `needsApproval(permissions.post.delete)` only on `WorkflowAgent`. `denied` maps to `'denied'`, `approval-required` to `'user-approval'`, and `'not-applicable'` is never returned ([AI SDK adapter](https://permdock.com/docs/adapters/ai-sdk)). Tools without a permission are hidden and denied unless `unmapped: 'allow'`; to combine PermDock with the app's own confirmation, pass `composeToolApproval(appApproval)` as `toolApproval` instead of wrapping the adapter: the app's function is asked only for calls PermDock grants, and its answer passes through (`undefined` stays not applicable; an unreadable answer denies).
+
+## Claude Agent SDK — `permdock/claude-agent`
+
+```ts
+import { createPermDock } from "permdock/claude-agent";
+
+export const { canUseTool, permissionRequestHook } = createPermDock(policy, {
+  subject: () => user,
+  actor: () => ({ id: "claude", kind: "claude-agent" }),
+  delegation: () => ({ scopes: [permissions.post.delete.scope] }),
+  tools: {
+    delete_post: {
+      permission: permissions.post.delete,
+      data: (args) => loadPost(args),
+    },
+  },
+});
+```
+
+`canUseTool` returns `{ behavior: 'allow', updatedInput }` or `{ behavior: 'deny', message }`; approval-required is a deny whose message carries the pending token. Pass a `store`: once a reviewer approves, the retried call is allowed exactly once. `mcp__` tools are trusted only from `mcpSources` (default `['sdk']`). Pass `permissionRequestHook` under `hooks.PermissionRequest` ([Claude Agent adapter](https://permdock.com/docs/adapters/claude-agent)).
+
+## Eve — `permdock/eve`
+
+```ts
+import { createPermDock } from "permdock/eve";
+
+export const { approval, approvalFor, permdock } = createPermDock(policy, {
+  delegation: () => ({ scopes: [permissions.post.delete.scope] }),
+  tools: {
+    delete_post: {
+      permission: permissions.post.delete,
+      data: (args) => loadPost(args),
+    },
+  },
+});
+```
+
+Pass `approval` as the tool's `approval`. Default subject and actor read `session.auth.initiator` / `current`. `approval.request(ctx)` maps granted to Eve's `not-applicable` (continue), approval-required to `user-approval`, denied to `{ type: 'denied', reason }`; Eve's re-check of a call nobody approved is denied. `approval.response(ctx)` maps the responder through the same `subject`. Use a durable `store` when replicas share sessions ([Eve adapter](https://permdock.com/docs/adapters/eve)).
+
+## OpenAI Agents SDK — `permdock/openai`
+
+```ts
+import { createPermDock } from "permdock/openai";
+
+export const { needsApproval, guardTools, resolveInterruptions, permdock } =
+  createPermDock(policy, {
+    subject: (ctx) => ctx.user,
+    actor: (ctx) => ({ id: ctx.agentId, kind: "openai" }),
+    delegation: (ctx) => ({ scopes: ctx.scopes }),
+    tools: {
+      delete_post: {
+        permission: permissions.post.delete,
+        data: (args) => loadPost(args),
+      },
+    },
+  });
+```
+
+`needsApproval(permission)` is the tool's `needsApproval`; it reads `runContext.context` and is true unless granted. `guardTools` drops tools with no grant. `resolveInterruptions(state, interruptions, { context })` approves or rejects each pause and returns the still-pending `ApprovalRequest`s. On resume, rebuild the context from the session and use `RunState.fromStringWithContext` ([OpenAI adapter](https://permdock.com/docs/adapters/openai)).
+
+## MCP — `permdock/mcp`
+
+```ts
+import { createPermDock } from "permdock/mcp";
+
+export const { protectServer } = createPermDock(policy, {
+  subject: (authInfo) => userFrom(authInfo), // or subjectFromMcp
+  requireAuthInfo: true, // HTTP behind bearer auth
+  store,
+});
+
+const server = protectServer(
+  new McpServer({ name: "posts", version: "1.0.0" }),
+);
+server.registerTool(
+  "delete_post",
+  {
+    permission: permissions.post.delete,
+    inputSchema: z.object({ id: z.string() }),
+    data: ({ id }) => loadPost(id),
+  },
+  handler,
+);
+```
+
+`actor.kind` is `'mcp-client'` unless `actorKind` sets another (`'oauth-client'` makes the token the same actor kind `permdock/supabase` and `permdock/jwt` give it, so one delegation covers both), and `delegation` comes from the token's scopes and `authorization_details`. Every `registerTool` / `registerResource` / `registerPrompt` needs a `permission`. Lists are filtered per caller. A missing scope is an `insufficient_scope` step-up (HTTP `403`) naming only the scope the call needs. When the authorization server issues coarse scopes (`mcp:read`), declare them in `definePolicy({ oauthScopes })` instead of expanding scopes yourself: they are expanded into the delegation and named in challenges. Set `resource` to the server's URL so tokens for another audience are refused. Denied calls return `isError: true` with Decision `structuredContent`. `approval-required` parks the call in `store` and returns `isError: true` with the token, or an `input_required` URL request when `approval.at` is set and the client declares URL elicitation; the retried call runs once after approval (token optional under `_meta["dev.permdock/approval"]`, never from tool arguments) ([MCP adapter](https://permdock.com/docs/adapters/mcp)).
+
+An MCP server that is not an SDK `McpServer` cannot be wrapped: narrow the tool's `meta` with `isPermission`, filter its tool list with `mayUse(permdock, permission)` from `permdock`, and decide each call with `permdock.decide(permission, args)` in its `authorize` hook. `mayUse` is a listing hint, never a decision.
+
+When a tool's handler calls an oRPC procedure that runs `protect`, use `protectServer(server, { enforce: 'procedure', permissionFor: (name) => permissionOf(procedures.get(name)) })` with `permissionOf` from `permdock/orpc`. `tools/list` and annotations follow the permission; the call is not guarded, so each call decides once, in the procedure. `data` and `longRunning` throw in this mode, and the mode covers the whole server. When the same operations are REST routes, declare each permission once with `operationPermissions({ 'GET /customers/{id}': { permission, operationId } })` from `permdock/openapi` and pass `permissionFor: operations.forOperation`; the HTTP gate reads `operations.forRequest(method, path)` from the same object. When two operations share a permission but need different coarse scopes (reading an export with `mcp:read`, creating one with `mcp:write`), list the permission under both in `oauthScopes`, then narrow each operation with `oauthScopes: ['mcp:read']` on its entry (or on the tool config): pass `oauthScopesFor: operations.oauthScopesForOperation` to `protectServer`, and `operations` to `permdock/server` (or `protect`'s `oauthScopes`) for the REST routes, which then answer `insufficient_scope` naming that scope. A route that checks no permission but should still require a scope (a chat endpoint, setting the active organization) uses `protect(null, undefined, { oauthScopes: ['api:chat'] })` or an operation entry with only `oauthScopes`; never write an app-side rule that maps HTTP methods to scopes.
+
+## A2A — `permdock/a2a`
+
+```ts
+import { createPermDock } from "permdock/a2a";
+
+export const { agentCard, extendedAgentCard, protectSkill } = createPermDock(
+  policy,
+  {
+    subject: (auth) => userFrom(auth),
+    card: {
+      name: "Posts agent",
+      url: "https://agent.example.com/a2a",
+      version: "1.0.0",
+    },
+    securitySchemes: { oauth: { type: "oauth2" } },
+    skills: {
+      summarise: { permission: permissions.post.read },
+      publish: {
+        permission: permissions.post.publish,
+        data: (task) => loadPost(task.postId),
+      },
+    },
+  },
+);
+
+app.get("/.well-known/agent-card.json", (c) => c.json(agentCard()));
+app.get("/a2a/extended-card", (c) => c.json(extendedAgentCard(c.get("auth"))));
+app.post(
+  "/a2a/tasks",
+  protectSkill((task) => task.skillId),
+  handleTask,
+);
+```
+
+Identity comes from transport auth, never the task body. `actor.kind` is `'a2a'`, with `delegation` from the caller's token. Each skill's `securityRequirements` name the permission's `scope`. The public card is never filtered; `extendedAgentCard(auth)` keeps only skills the caller has a grant for. An instance-level skill without `data` throws at startup ([A2A adapter](https://permdock.com/docs/adapters/a2a)).
+
+## WebMCP — `permdock/webmcp`
+
+Client entry. No factory. Register snapshot-allowed tools on `document.modelContext`:
+
+```ts
+import { registerTools } from "permdock/webmcp";
+import { approvalHeaders, usePermDock } from "permdock/react";
+
+const permdock = usePermDock();
+const controller = new AbortController();
+registerTools(document.modelContext, permissions.post, {
+  permdock,
+  signal: controller.signal,
+  handlers: {
+    update: async ({ input, token }) =>
+      api.posts.update(input, { headers: approvalHeaders(token) }),
+  },
+});
+```
+
+Never import a policy into this entry. A missing `document.modelContext` is a no-op. Tools re-register when the snapshot changes. The client check is a filter: the server adapter behind `api.posts` makes the decision. `onApprovalRequired` opens the page's own confirmation dialog ([WebMCP adapter](https://permdock.com/docs/adapters/webmcp)).
+
+## Web Bot Auth on HTTP adapters
+
+```ts
+import {
+  createPermDock,
+  discoverViaSignatureAgent,
+  verifyWebBotAuth,
+} from "permdock/hono";
+
+const keys = discoverViaSignatureAgent({ allow: ["agents.example.com"] });
+
+export const { permdock, protect } = createPermDock(policy, {
+  subject: (c) => c.get("user"),
+  webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys }),
+});
+```
+
+A verified RFC 9421 signer becomes the actor with `kind: 'web-bot-auth'`; `delegation` comes from a bearer token on the same request, otherwise it is empty. A failed signature throws `InvalidSignatureError`, never an anonymous actor ([Web Bot Auth](https://permdock.com/docs/standards/web-bot-auth)).
+
+## Terminal — `permdock/terminal`
+
+```ts
+import { createPermDock } from "permdock/terminal";
+
+export const { permdock, protect, filterCommands, format, exitCode } =
+  createPermDock(policy, {
+    subject: async ({ token }) => {
+      const jwt = await token(["env", "keychain", "ci-oidc", "device"]);
+      return jwt ? subjectFromJwt(jwt, { issuer, audience: "acme-cli" }) : null;
+    },
+  });
+```
+
+For the app's own CLI; not the `permdock` binary. Never accept `--user` or `--actor` as identity. In CI, verify the job token with `subjectFromCiOidc(jwt, { provider: 'github', audience })` from `permdock/jwt`, which returns a `workload` principal, never a user. A `destructive` permission asks for the resource id to be typed, and exits `64` without a terminal unless `--yes` is passed; `--yes` never approves an `approval-required` call. `--dry-run` decides and exits with the outcome's code without running the action ([terminal adapter](https://permdock.com/docs/adapters/terminal)).

package/skills/permdock-approvals/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: permdock-approvals
+description: Requires human approval on PermDock grants and resumes the approved call. Use when adding approval to a destructive or money-moving action (delete, publish, pay, refund, approve, transfer), choosing approvers with approval by, user(), relation(), distinct, quorum, ttl, escalation or staleOn, ordering approvers with mode and stages, loading approval rules as data with an ApprovalPolicySource, separating preparer and approver with exclusiveWith, mounting approvalsHandler with an ApprovalStore, resuming with the PermDock-Approval header, mapping approval-required to an agent runtime, MCP elicitation or AG-UI interrupt, or fixing doctor PD017, PD018 or PD024.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/security/approvals
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock approvals
+
+`approval-required` is the third outcome: the subject may do it, but a person other than the requester confirms each call. An approval never grants something the subject could not do, and a `deny` still wins ([approval security](https://permdock.com/docs/security/approvals)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- Which actions need a person: deletions, publishing, payments, refunds, access changes, anything an agent can repeat.
+- Who may approve each one (a role, a plan, `assurance()`, one named user, or a relation on the row such as the expense's manager), how many approvers (quorum), whether several groups sign in order, how long an ask may wait, and who steps in when nobody answers.
+- Whether organisations configure their own approval rules at runtime ("payments over 1000 need finance").
+- Whether the approver judges the row's content (an amount, a text), so a changed row needs a new approval.
+- Whether a user confirming their own agent's call is the intent anywhere.
+- Where pending requests live: one process (`memoryApprovalStore`), the app's database, or PermDock Cloud.
+- Which runtimes ask: HTTP, AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, a chat UI.
+
+## Invariants
+
+1. The requester never approves by default. The actor is always refused. The principal is refused unless the grant sets `distinct: false`, and `requireDistinctApprover` on the handler refuses it even then.
+2. The approver comes from authentication on the approval surface, never from the request body, a tool argument or a link.
+3. One approval resumes one call. The token binds permission, resource, subject and actor, the resume re-runs `decide`, and `consume` spends the approval once.
+4. `can` returns `false` for `approval-required`. Only `decide`, `assert` and the adapters see the third outcome.
+5. Quorum, ttl and escalation live on the grant, not in the store. A grant's `ttl` can shorten the store's window, never extend it.
+6. A `relation()` approver is matched only through facts the approvals handler reads from the app's `RelationSource` at verdict time, never from a request body.
+7. Approval rules kept as data only add stages. A source that fails to load denies every call an allow would grant.
+
+## Workflow
+
+1. **Mark the grants.** Add `approval: 'human'` (anyone authenticated but the requester) or `approval: { by }` with the same selectors as `to`:
+
+   ```ts
+   allow(permissions.payout.release, {
+     approval: {
+       by: roles.finance,
+       quorum: 2,
+       ttl: "30m",
+       escalation: { after: "4h", to: roles.owner },
+     },
+   });
+   ```
+
+   For sign-off in order, use `mode: 'sequential'` with `stages: [{ by, quorum? }]` (or `mode: 'all'` for any order); one person signs one stage. `user('u_cfo')` names one person, and `relation(permissions.expense, 'manager')` names whoever holds the relation on the row.
+   Add `distinct: false` only where the user confirms their own agent's call and no money, deletion or access change sits behind it.
+   ✓ `permdock doctor` reports no PD017 (sensitive verb without approval), and every PD024 (`distinct: false`) is deliberate.
+
+2. **Bind content when it matters.** Declare `version: 'updatedAt'` (or a revision counter) on the `resource()` and add `staleOn: 'resource-change'` to the approval, so a changed row resumes as `stale-approval` and asks again.
+   ✓ `definePolicy` accepts the grant (it throws when the resource has no `version` or the action is a collection action).
+3. **Split workflow verbs.** Model `prepare`, `approve`, `pay`, `settle` and `submit` as separate leaves. Put the approval on `approve` / `pay`, and use `exclusiveWith` on `role()` so a preparer cannot also hold the approver role.
+   ✓ `permdock doctor` reports no PD018 (exclusive roles held together).
+4. **Store and handler.** Create one `ApprovalStore`, pass it as `store` to every adapter, and mount `approvalsHandler(store, { subject })` for approvers; add `relations` and `permissions` when a grant uses `relation()` approvers. -> [references/stores-and-resume.md](references/stores-and-resume.md)
+   ✓ A second authenticated user can approve; the actor and the requester get `403`.
+5. **Rules as data (optional).** Pass `approvalPolicies` (an `ApprovalPolicySource`, `memoryApprovalPolicies` in process) to `createPermDock` for approval rules organisations configure. -> [references/stores-and-resume.md](references/stores-and-resume.md#approval-policies-as-data)
+   ✓ `testApprovalPolicySource` from `permdock/testing` passes on the source.
+6. **Surface and resume.** Map the outcome to each runtime's approval hook and resume with the token: the `PermDock-Approval` header over HTTP, the runtime's own resume for agents. -> [references/stores-and-resume.md](references/stores-and-resume.md#surfaces)
+   ✓ The approved call runs once; a second resume is denied with `approval-consumed`.
+7. **Test.** Add a scenario test per approval grant: the ask, an approval by an eligible user, a refused self-approval, and the single resume ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testApprovalStore` on a custom store.
+   ✓ The tests pass.
+
+## Verify before done
+
+- [ ] Every destructive or money-moving action an agent or a user can trigger has `approval`, or a `deny` on the same leaf.
+- [ ] Each `distinct: false` (PD024) is a deliberate self-confirmation with nothing irreversible behind it.
+- [ ] Roles that must not be held together set `exclusiveWith`, and PD018 is clean.
+- [ ] The store survives the deployment: no `memoryApprovalStore` on serverless or across replicas.
+- [ ] No resume token is read from model output or tool arguments, and each resume re-runs `decide`.
+- [ ] A custom `ApprovalStore` passes `testApprovalStore` from `permdock/testing`.
+- [ ] Grants with `relation()` approvers have a handler with `relations`, and nothing fills `verdict.relations` from client input.
+
+## Reference index
+
+- [references/stores-and-resume.md](references/stores-and-resume.md): `approvalsHandler` routes, custom stores, relation approvers, approval policies as data, the token, resume details and denial causes, the runtime surfaces table, delivery to chat and email.
+- Docs: [approval security](https://permdock.com/docs/security/approvals), [approvals adapter](https://permdock.com/docs/adapters/approvals), [wire formats](https://permdock.com/docs/concepts/wire-formats).

package/skills/permdock-approvals/references/stores-and-resume.md

@@ -0,0 +1,94 @@
+# Approval stores and the resume flow
+
+The API and the store contract are on the [approvals adapter](https://permdock.com/docs/adapters/approvals); the token and the runtime table are on [approval security](https://permdock.com/docs/security/approvals).
+
+## Store and handler
+
+```ts
+import { approvalsHandler, memoryApprovalStore } from "permdock/approvals";
+
+export const store = memoryApprovalStore({ ttl: 60 * 60 * 1000 }); // default: one hour
+
+// Every agent and HTTP adapter takes the same option
+export const { protect } = createPermDock(policy, { subject, store });
+
+// Routes for approvers: GET /pending, GET /mine, GET /:token, POST /:token/approve, POST /:token/reject
+const handler = approvalsHandler(store, {
+  subject: (request) => approverFromSession(request), // the approver, from real authentication
+  requireDistinctApprover: false, // true refuses the principal even where a grant sets distinct: false
+  relations, // RelationSource: needed when a grant uses relation() approvers
+  permissions, // the permission tree, for relation approvers reached through links
+});
+app.all("/permdock/approvals/*", (c) => handler(c.req.raw));
+```
+
+The store's `ttl` is the window a request stays open when the call sets none; `resumeDecision({ ..., ttl })` sets it per call (milliseconds). A grant's `approval.ttl` only shortens either.
+
+- `memoryApprovalStore` is per process. On serverless or with several replicas, implement `ApprovalStore` over the app's database; the Drizzle recipe on the adapter page is the template, and `cloud().approvals` from `permdock/cloud` is the hosted implementation of the same interface. On Postgres or Supabase, set `rls.approvals: true` and use `supabaseApprovalStore(admin, { onOpen })` from `permdock/supabase` over the generated table and functions; grant the functions to the server's role, and put notifications and superseding older requests in `onOpen`.
+- A custom store calls `assertApprover(request, by, requireDistinct, now, verdict.relations)` in `resolve` and computes the next record with `applyApprovalVerdict`, which records each signature's `stage`. `verdict.relations` holds `approverRelationKey` values that the handler, or `resolveApproval(store, token, verdict, { relations, permissions })`, computed with `approverRelations`; a store never derives them. `consume` must be atomic: two concurrent calls never both succeed.
+- When the app's own rules decide who approves (a manager chain, delegates, a quorum it counts), record their verdict with `vouchApproval(store, token, { status, by, rule })` from `permdock/approvals` instead of mirroring those rules in `approvers` or copying the verdict into the request by hand. It resolves the request at once and records `vouched: rule`; the actor, requester and repeat checks still apply. Never take `vouched` from a request body.
+- Run `testApprovalStore(store, { reopen })` from `permdock/testing` on every custom store.
+- `cancelApprovals` rejects matching pending requests (for example when a session ends).
+
+## Approval policies as data
+
+```ts
+import { memoryApprovalPolicies } from "permdock";
+
+const permdock = await createPermDock(policy, user, {
+  approvalPolicies: memoryApprovalPolicies([
+    {
+      permission: "expense.pay",
+      tenant: "o_acme", // absent: every tenant
+      actors: ["agent"], // absent: every call
+      where: { op: "gt", field: "amount", value: 1000 },
+      approval: { by: "finance" }, // an escalation here widens only this entry's stages
+    },
+  ]),
+});
+```
+
+- Every adapter's `createPermDock` takes `approvalPolicies` (HTTP, MCP, A2A, AuthZEN, terminal and the agent adapters), so an entry also turns an agent call into `user-approval` or an MCP call into `approval-required`.
+- Entries are read once per instance and combine with the grant's own approval as stages (`sequential` if any part is, else `all`); the shortest `ttl` wins.
+- A throw or an invalid entry denies with detail `approval-policy-unavailable`. An unknown permission applies to nothing.
+- `where` reads the row, so it works only on instance permissions; on a collection permission the entry does not load. Use `check` (the proposed row) there. Validate entries where they are saved with `validateApprovalPolicy(policy, entry)` (`{ ok: false, problem }` names `unknown-permission`, `invalid`, `where-on-collection` or `stale-on-without-version`).
+- Client snapshots do not see the entries; the server's `decide` adds the approval.
+
+## Resume
+
+1. `decide` returns `approval-required` with a deterministic `token`. The adapter calls `store.create`; `create` is idempotent per token.
+2. The runtime surfaces the ask (table below). A person answers through `approvalsHandler`, the runtime's own UI or the Cloud inbox.
+3. The original call is retried with the token. The adapter re-runs `decide`, recomputes the token, compares it, and calls `store.consume`. Only then does the tool or route run.
+
+The token binds the permission key, the resource id (or a digest of the data when there is no id), the principal, the tenant, the actor and the matched grant's conditions. Under `staleOn: 'resource-change'` it also binds the row's `version`.
+
+A gate in your own code resumes the same way with `resumeDecision` from `permdock/approvals`, passing `token: carried ?? (await storedApprovalToken(store, decision))`: `storedApprovalToken` finds an approved or rejected request for the recomputed token, so the caller need not carry it. Do not reimplement it.
+
+Over HTTP, the client retries the same request with the `PermDock-Approval: <token>` header. In React, `approvalHeaders(token)` builds that header and `useApproval(decision)` requests and polls an approval from the UI.
+
+A bad resume is denied with detail `approval-not-found`, `approval-pending`, `approval-rejected`, `approval-expired`, `approval-consumed` or `approval-mismatch`; a changed row is `stale-approval`. `approvalsHandler` answers `403` for an ineligible approver (`approver-not-eligible`, the actor, or the principal without `distinct: false`) and `409` for a repeated one (`approver-repeated`).
+
+## Surfaces
+
+| Runtime                                 | Ask                                                                                             | Resume                                                                                  |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| AI SDK `generateText` / `ToolLoopAgent` | `toolApproval` returns `'user-approval'`                                                        | The SDK's re-check of the same call is denied unless the store holds an approved record |
+| AI SDK `WorkflowAgent`                  | `needsApproval(permission)` suspends the workflow                                               | The workflow resumes; the token is recomputed                                           |
+| Claude Agent SDK                        | `canUseTool` denies with the token and records the request                                      | The retry consumes the approved record once                                             |
+| Eve                                     | `approval.request` returns `user-approval`                                                      | `approval.response` checks the responder                                                |
+| OpenAI Agents SDK                       | `needsApproval` pauses the run with `interruptions`                                             | `resolveInterruptions` applies the store's verdict                                      |
+| MCP                                     | `input_required` URL elicitation to `approval.at`, otherwise an `isError` result with the token | The retried call re-runs `decide` and consumes                                          |
+| HTTP adapters                           | `403` Problem Details, type `.../approval-required`, with `token`                               | Retry with `PermDock-Approval`                                                          |
+| A2A                                     | The task enters input-required with the token                                                   | The caller continues the task                                                           |
+| WebMCP                                  | The handler is not run; `onApprovalRequired` opens the page's dialog                            | The page calls the guarded route with the token                                         |
+| Chat UI over AG-UI                      | The backend emits the request as an AG-UI human-in-the-loop or custom event                     | The answer returns on the stream; the backend recomputes the token                      |
+
+For AG-UI event shapes, defer to the `ag-ui` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill ag-ui`).
+
+## Delivery
+
+Notifying an approver is a listener on the `approval` event (`permdock.on('approval', …)`), never a package. A message or email carries only the token and links to a page where the approver signs in; the verdict goes through `approvalsHandler` with that session's subject. A link never approves on its own ([approvals adapter, Delivery](https://permdock.com/docs/adapters/approvals#delivery)).
+
+## Approvers
+
+`by` takes roles, `user(id)`, `relation()`, `holder(permission)` and `anyOf(...)`. A list is all-of; use `anyOf(user(id), holder(permissions.x.approve))` for "this person or anyone who holds the permission". `holder()` needs `approvalsHandler(store, { permdockFor: (approver, request) => createPermDock(policy, approver, { customRoles }) })`, so custom roles count. Stages may carry their own `escalation`.

package/skills/permdock-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: permdock-audit
+description: Reviews an existing PermDock setup or a pull request that changes it. Use when auditing permissions, reviewing a PR that touches permissions.ts, policy.ts or an adapter guard, finding ungranted or unused leaves, missing human approvals on agent tools, closures that should be portable, validate never, untested grants, or mapping an app to OWASP ASI02 and ASI03. Use whenever the user asks to audit, review or harden PermDock.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/for-ai-agents
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# Audit PermDock
+
+Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter guard, then write the findings as a Markdown checklist the user can turn into pull requests. Every finding names the file and the permission or role.
+
+## Inputs (find out, or ask before starting)
+
+- The scope: the whole app, or one pull request against its base branch.
+- Whether the `permdock` binary runs here (`permdock usage --json`, `permdock doctor --json`); otherwise walk the files and the catalog by hand.
+- Which topic areas the app uses: agent runtimes, approvals, named scopes and custom roles, ORM queries or RLS, tokens, API keys or share links.
+
+## Invariants
+
+1. Report, never fix silently. Each finding is one line with a file and a permission or role.
+2. Anything that widens access or fails open leads the report.
+3. Expected outcomes in tests are written by hand, never computed by calling `decide` or `can`.
+4. A topic skill's Verify list is the checklist for its area; this skill does not repeat it.
+
+## Workflow
+
+1. **Inventory.** List every leaf from `definePermissions`, every role from `defineRoles` / `role()`, every plan from `definePlans`, and every grant from `definePolicy` (`grants`, role bindings, `delegations`). Note which entries import the policy (server, agent) and which import only the snapshot (client).
+   ✓ Every leaf, role, plan and grant is in the report, including leaves with zero grants.
+2. **Ungranted and unused.** A leaf no `allow` mentions is ungranted: grant it or delete it. A granted leaf never passed to `can`, `decide`, `assert`, `protect`, `tools` or `<Protected>` is unused; confirm with `usage --json` or a repo-wide search for the reference.
+   ✓ Every leaf is tagged granted and used, granted and unused, or ungranted.
+3. **Validation and identity.**
+   - `validate: 'never'` on a policy that sees HTTP bodies, MCP arguments or model output is a finding.
+   - Client entries (`permdock/react` and the client half of a framework adapter) import permissions and snapshots only.
+   - `subject` and `actor` come from the host session or `subjectFrom*`, never from tool arguments or a model-supplied id.
+   - A `limit` grant without `limits` on `createPermDock` always denies with `limit-unavailable`, and a mutation that only calls `can` never spends a unit.
+   - On Supabase, every `ctx.supabaseAdmin`, `withPostgresAdminClient` or `service_role` client sits behind `permdock.assert(...)` (or `withPermDock({ protect })`), and `subjectFromSupabase` receives `getClaims()` output or `ctx.jwtClaims`, never `getSession().access_token` or `user_metadata`.
+     ✓ Each check has a pass or a file-level finding.
+4. **Topic checks.** For each area the app uses, run the Verify list of its skill (`npx skills add ScaleDockHQ/PermDock --skill <name>`): `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data`, `permdock-credentials`.
+   ✓ Every item of every applicable Verify list has a pass or a finding.
+5. **Tests.** No `describePolicy` suite, or one with `exhaustive: false`, is a finding: a new permission can ship untested. A custom `ApprovalStore`, `DecisionSink`, `MembershipSource`, `RoleSource`, `SnapshotSource`, `LimitStore`, `RelationSource` or `DirectoryStore` without its `test<Interface>` runner from `permdock/testing` is a finding.
+   ✓ Every policy and custom store has its runner, or a finding.
+6. **ASI02 and ASI03.** Map the inventory onto [OWASP Agentic](https://permdock.com/docs/security/owasp-agentic); for the threat list itself, defer to the `owasp-agentic` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill owasp-agentic`).
+   - **ASI02** (tool misuse): unmapped tools, a collection permission on a row handler, a destructive tool without `approval`, capability lists that include denied tools.
+   - **ASI03** (identity and privilege abuse): a model-supplied subject or actor, an actor used as approver, `distinct: false` on a sensitive action, a resume token not bound to permission, resource, subject and actor, API keys stored in plain text or created outside `decideCredential`, keys without expiry (PD029), and a `memberships` source applied to service-key subjects.
+     ✓ Each agent adapter in the app has an ASI02 line and an ASI03 line.
+7. **Pull request review**, when the scope is one PR. Review only what the diff changes:
+   - Run `permdock collect --check` and `permdock usage --json` on both sides and compare. New leaves with no grant, grants for leaves nobody checks, and new `undeclared` or `outsideInclude` findings are comments.
+   - A new or widened `allow` (a role gains a leaf, a `where` is dropped or loosened, a `to` becomes `anyone()` or `authenticated()`), a new policy `delegations` entry, or a removed `deny` needs a matching `describePolicy` row in the same PR.
+   - A new model-reachable tool, or a new destructive action on an existing one, goes through the `permdock-agents` and `permdock-approvals` Verify lists.
+   - A change to the `rls` config or generated RLS comes with `permdock rls generate --check` passing and an `rlsParity` or `rls verify` run.
+   - `permdock doctor --json` on the head branch reports no new error.
+     ✓ Every changed grant, leaf and tool has a comment on the changed line or an explicit pass.
+
+## Verify before done
+
+- [ ] The report leads with blockers: fail-open paths, a trusted model subject, a destructive tool without approval.
+- [ ] Then ungranted and unused leaves, then closures that could be portable, then test gaps.
+- [ ] Every finding names a file and a permission or role.
+- [ ] The report ends with suggested PRs, one finding per PR when the fixes are independent.
+
+## Reference index
+
+- Topic Verify lists: the `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data` and `permdock-credentials` skills.
+- Docs: [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), [threat model](https://permdock.com/docs/security/threat-model), [`permdock doctor`](https://permdock.com/docs/cli/doctor), [`permdock usage`](https://permdock.com/docs/cli/usage), [testing](https://permdock.com/docs/adapters/testing).

package/skills/permdock-credentials/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: permdock-credentials
+description: Resolves PermDock subjects from access tokens, API keys and share links. Use when verifying OAuth or OIDC access tokens with subjectFromJwt or an introspection response with subjectFromIntrospection, issuing personal access tokens, API keys or service accounts with decideCredential and resolving them with subjectFromApiKey, setting tenant key rules (maxTtl, kinds, allowNoExpiry) in a SettingsSource, minting guest or share links with signCapability and resolving them with subjectFromCapability, serving a link through RLS with exchangeCapability, or fixing doctor PD029 and on('auth') causes such as invalid-chain.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/concepts/authentication
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock credentials
+
+Authentication is upstream: core never verifies a token. A `subjectFrom*` resolver verifies the material and hands core a `Subject`, and anything it cannot verify becomes the anonymous subject, never a throw ([authentication](https://permdock.com/docs/concepts/authentication)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- Which credentials reach the app: browser sessions, OAuth or OIDC access tokens, introspected tokens, API keys, CI job tokens, share links.
+- For tokens: the issuer, the resource identifier (audience) and the signing algorithms.
+- For keys: personal (`user`) keys, service accounts (`service`), or both; where the hashes are stored; the tenant rules on lifetime and kinds.
+- For links: what a link opens, who may redeem it, how long it lives, and whether Postgres RLS must serve the guest page.
+
+## Invariants
+
+1. Core never verifies a token or a session. Only `permdock/jwt`, `permdock/server` key helpers and the provider `subjectFrom*` helpers do.
+2. A resolver never throws. An unverifiable token, key or link is the anonymous subject, and the cause goes to `on('auth')`.
+3. Never build grants from user-editable claims (`user_metadata`), and never take a subject from a request body, an unsigned header, a CLI flag or a model argument.
+4. Store only `hashApiKey(key)` and show the key once. Every key lists its permissions and expires unless the tenant opts in with `allowNoExpiry`.
+5. A share link is a signed, expiring capability on one resource. It never holds a scope or global role, and RLS sees it only through `exchangeCapability`, never `service_role`.
+6. Token rules come from the spec skills (`npx skills add ScaleDockHQ/scaledock-skills --skill <name>`): `jwt` for JOSE, `oauth` for access tokens and introspection, `openid-connect` for ID tokens and Discovery.
+
+## Workflow
+
+1. **Verify access tokens.** Resolve the subject with `subjectFromJwt(token, { discovery, audience })` from `permdock/jwt`, or `subjectFromIntrospection` when the app already called introspection. -> [references/tokens-keys-links.md](references/tokens-keys-links.md)
+   ✓ An ID token, a token for another audience and an expired token each resolve to the anonymous subject.
+2. **Issue API keys, when the product has them.** Guard the creation endpoint with its own permission, call `decideCredential(permdock, request, { settings })`, store the hash with the returned `Credential`, and show the key once. -> [references/tokens-keys-links.md](references/tokens-keys-links.md#api-keys-and-service-accounts)
+   ✓ A service key wider than its creator is denied with `exceeds-creator`.
+3. **Resolve API keys.** Build `subjectFromApiKey({ verifier: apiKeyVerifier({ find }), permissions, owner, revoked, settings, sink })` and call it as `resolveKey(key, { tenant })`.
+   ✓ A revoked or expired key is anonymous, and a user key never exceeds its owner's current rights.
+4. **Share links, when the product has them.** Declare the link's roles on the resource, mint with `signCapability` behind a guard of its own, and resolve with `subjectFromCapability` and the tenant's `linkPolicy`. With Supabase RLS, exchange the link with `exchangeCapability` and generate with `--capabilities`. -> [references/tokens-keys-links.md](references/tokens-keys-links.md#share-links)
+   ✓ An expired, revoked or replayed (`once`) link resolves to the anonymous subject.
+5. **Test.** Add scenario tests for each credential kind: a valid one, a forged or expired one, and a key or link used past its permissions ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `permdock doctor`.
+   ✓ The tests pass and PD029 is clean.
+
+## Verify before done
+
+- [ ] `subjectFromJwt` uses Discovery or an explicit `jwks` plus `issuer`, sets `audience`, and allows only `Ed25519`, `ES256` or `PS256`.
+- [ ] No subject, tenant or membership comes from `user_metadata`, a request body or an unsigned header.
+- [ ] API keys are stored as hashes, created only through `decideCredential` behind their own guard, and expire (PD029).
+- [ ] No `memberships` source is passed to `createPermDock` for service-key subjects.
+- [ ] Share links expire, are minted behind their own guard, and reach RLS only through `exchangeCapability`.
+
+## Reference index
+
+- [references/tokens-keys-links.md](references/tokens-keys-links.md): `subjectFromJwt` options, introspection, CI OIDC, `decideCredential`, key storage and resolution, tenant settings, `signCapability`, `subjectFromCapability`, `exchangeCapability`.
+- Docs: [authentication](https://permdock.com/docs/concepts/authentication), [subject](https://permdock.com/docs/concepts/subject), [JWT adapter](https://permdock.com/docs/adapters/jwt), [API keys](https://permdock.com/docs/concepts/credentials), [link capabilities](https://permdock.com/docs/concepts/capabilities), [JOSE](https://permdock.com/docs/standards/jose).