permdock 0.3.1 → 0.5.0

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

@@ -1,10 +1,11 @@
 # 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>`.
+Every agent adapter exports `createPermDock` from `permdock/<runtime>` and takes `subject`, `actor`, `delegation`, `tenant`, `operations`, `models`, `store`, `unmapped`, `context`, `otel`, `wrap` and `deniedText`. `ai-sdk`, `openai`, `claude-agent` and `eve` build on the `permdock/agent` contract, so each also returns `decideOperation`, `allowedOperations`, `decideModel`, `permittedModels`, `filterResults` and `gatewayOptions` ([operations-automations-chat.md](operations-automations-chat.md)). `operations` is the map `defineOperations(permissions, …)` returns, one permission per tool name. `unmapped: 'allow'` leaves a tool `operations` does not name to the runtime; the default denies it. 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 { defineOperations } from "permdock";
 import { createPermDock } from "permdock/ai-sdk";
 import { z } from "zod";
 
@@ -18,12 +19,12 @@ export const { toolApproval, capabilityMiddleware, needsApproval } =
       kind: "ai-sdk",
     }),
     delegation: () => ({ scopes: [permissions.post.delete.scope] }),
-    tools: {
+    operations: defineOperations(permissions, {
       delete_post: {
         permission: permissions.post.delete,
         data: (args) => loadPost(PostArgs.parse(args).id),
       },
-    },
+    }),
   });
 ```
 
@@ -32,18 +33,19 @@ Pass `toolApproval` into `generateText` / `ToolLoopAgent`. Wrap the model with `
 ## Claude Agent SDK — `permdock/claude-agent`
 
 ```ts
+import { defineOperations } from "permdock";
 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: {
+  operations: defineOperations(permissions, {
     delete_post: {
       permission: permissions.post.delete,
       data: (args) => loadPost(args),
     },
-  },
+  }),
 });
 ```
 
@@ -52,37 +54,39 @@ export const { canUseTool, permissionRequestHook } = createPermDock(policy, {
 ## Eve — `permdock/eve`
 
 ```ts
+import { defineOperations } from "permdock";
 import { createPermDock } from "permdock/eve";
 
-export const { approval, approvalFor, permdock } = createPermDock(policy, {
+export const { approval, approvalFor, getPermDock } = createPermDock(policy, {
   delegation: () => ({ scopes: [permissions.post.delete.scope] }),
-  tools: {
+  operations: defineOperations(permissions, {
     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)).
+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)). With PermDock Cloud, pass `policies: hostedPolicies(cloud().policies)` and give `cloud()` a `verifier` for the environment JWK Set; hosted grants apply only to `hostable` permissions, so mark the ones the dashboard may extend.
 
 ## OpenAI Agents SDK — `permdock/openai`
 
 ```ts
+import { defineOperations } from "permdock";
 import { createPermDock } from "permdock/openai";
 
-export const { needsApproval, guardTools, resolveInterruptions, permdock } =
+export const { needsApproval, guardTools, resolveInterruptions, getPermDock } =
   createPermDock(policy, {
     subject: (ctx) => ctx.user,
     actor: (ctx) => ({ id: ctx.agentId, kind: "openai" }),
     delegation: (ctx) => ({ scopes: ctx.scopes }),
-    tools: {
+    operations: defineOperations(permissions, {
       delete_post: {
         permission: permissions.post.delete,
         data: (args) => loadPost(args),
       },
-    },
+    }),
   });
 ```
 
@@ -115,7 +119,7 @@ server.registerTool(
 
 `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.
+An MCP server that is not an SDK `McpServer` cannot be wrapped: narrow the tool's `meta` with `isPermission`, filter its tool list with `permdock.mayUse(permission)`, 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.
 
@@ -160,8 +164,8 @@ Identity comes from transport auth, never the task body. `actor.kind` is `'a2a'`
 Client entry. No factory. Register snapshot-allowed tools on `document.modelContext`:
 
 ```ts
-import { registerTools } from "permdock/webmcp";
 import { approvalHeaders, usePermDock } from "permdock/react";
+import { registerTools } from "permdock/webmcp";
 
 const permdock = usePermDock();
 const controller = new AbortController();
@@ -183,14 +187,14 @@ Never import a policy into this entry. A missing `document.modelContext` is a no
 import {
   createPermDock,
   discoverViaSignatureAgent,
-  verifyWebBotAuth,
+  webBotAuthVerifier,
 } from "permdock/hono";
 
 const keys = discoverViaSignatureAgent({ allow: ["agents.example.com"] });
 
-export const { permdock, protect } = createPermDock(policy, {
+export const { middleware, protect } = createPermDock(policy, {
   subject: (c) => c.get("user"),
-  webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys }),
+  webBotAuth: webBotAuthVerifier({ verify: true, keys }),
 });
 ```
 
@@ -201,7 +205,7 @@ A verified RFC 9421 signer becomes the actor with `kind: 'web-bot-auth'`; `deleg
 ```ts
 import { createPermDock } from "permdock/terminal";
 
-export const { permdock, protect, filterCommands, format, exitCode } =
+export const { getPermDock, protect, filterCommands, format, exitCode } =
   createPermDock(policy, {
     subject: async ({ token }) => {
       const jwt = await token(["env", "keychain", "ci-oidc", "device"]);

package/skills/permdock-approvals/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Requires human approval on PermDock grants, notifies approvers and resumes the approved call. Use when adding approval to a destructive or money-moving action (delete, publish, pay, refund, transfer), choosing approvers with approval by, user(), relation(), distinct, quorum, ttl, escalation or staleOn, ordering approvers with mode and stages, covering an approver with an ApprovalDelegation, loading approval rules as data with an ApprovalPolicySource, separating preparer and approver with exclusiveWith, labelling operations with risk and effects meta, mounting approvalsHandler with an ApprovalStore, sending approval emails (approvalEmail) or chat cards (approvalCard, approvalActions) from approvalPrompt, parking a background run on an ApprovalWaiter (pollingApprovalWaiter, workflowSdkWaiter), 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
@@ -20,17 +20,21 @@ metadata:
 - 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.
+- Which runtimes ask: HTTP, AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, a chat UI, or a background run (workflow, queue) that must wait.
+- How approvers hear about a request (email, chat, the app's inbox only) and where the app's approval page lives.
 
 ## 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.
+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. A delegate is held to the same rule, and so is the delegator. One hop, and `until` is required.
 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.
+8. A link never approves. An email or chat prompt carries the request id, never the token, and links to the app's approval page where the approver signs in. Chat buttons carry the request id and are applied as the platform-verified clicking user.
+9. A wake carries no verdict. `waiter.wake(token)` only ends a wait; the run decides again through `resumeApproval`, which reads the store.
+10. PermDock never decides on operation `meta`. `risk` and `effects` label or gate a call in the host; only the grant's `approval` asks a person.
 
 ## Workflow
 
@@ -41,8 +45,8 @@ metadata:
      approval: {
        by: roles.finance,
        quorum: 2,
-       ttl: "30m",
-       escalation: { after: "4h", to: roles.owner },
+       ttl: 1800, // seconds: 30 minutes
+       escalation: { after: 14_400, to: roles.owner }, // 4 hours
      },
    });
    ```
@@ -55,14 +59,20 @@ metadata:
    ✓ `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)
+4. **Label risk.** Give each approval-gated operation in `defineOperations` a `meta` with `title`, `risk` (`low`, `medium`, `high`, `critical`) and `effects` (`read`, `write`, `delete`, `send`, `spend`, `external`), so prompts and the host's UI show what the call does ([operations](https://permdock.com/docs/concepts/operations)). -> [references/delivery-and-waiters.md](references/delivery-and-waiters.md#risk-meta)
+   ✓ `defineOperations` builds the map without throwing, and every `risk: 'high'` or `'critical'` operation's permission has an `approval` grant.
+5. **Store and handler.** Create one `ApprovalStore`, pass it as `store` to every adapter, and mount `approvalsHandler(store, { subject })` for approvers (`GET /:id`, `POST /:id/approve` and `/reject` with `If-Match`); 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`, and a stale `If-Match` gets `412`.
+6. **Rules as data (optional).** Pass `approvalPolicies` (an `ApprovalPolicySource`, `memoryApprovalPolicySource` 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)
+7. **Notify approvers.** Build the prompt with `approvalPrompt(request, { operation })` and send it with `createPermDock` from `permdock/delivery`: `approvalEmail` from `permdock/resend` for email, a chat message with `approval` (rendered as `approvalCard`) plus `approvalActions` from `permdock/chat-sdk` for chat ([delivery](https://permdock.com/docs/concepts/delivery)). -> [references/delivery-and-waiters.md](references/delivery-and-waiters.md#approval-prompts)
+   ✓ The `DeliveryReport` shows `sent` for each eligible approver and none for the requester; the message holds no token and no approve link.
+8. **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.
+9. **Wait in background runs.** Pass a `waiter` to `createPermDock` from `permdock/workflow` (`pollingApprovalWaiter({ store, interval })`, or `workflowSdkWaiter` from `permdock/workflow-sdk`) and call `awaitApproval`, or `openApproval` and `resumeApproval` as steps. The approver's endpoint calls `waiter.wake(token)` after `resolveApproval` ([automations](https://permdock.com/docs/concepts/automations)). -> [references/delivery-and-waiters.md](references/delivery-and-waiters.md#waiters)
+   ✓ A wake before any verdict leaves the run denied with reason `approval`; a wake after approval lets it proceed once.
+10. **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
 
@@ -73,8 +83,14 @@ metadata:
 - [ ] 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.
+- [ ] No email, chat message or URL carries the approval token or an approve link; `approvalUrl` is https and opens a page behind sign-in.
+- [ ] Approval recipients are decided by `deliver` from server-loaded principals, never from the request body, and the requester is not among them.
+- [ ] Chat approve and reject clicks go through `approvalActions` (or `resolveAction`), never a handler that trusts the button value alone.
+- [ ] Every approver endpoint that resolves a request for a parked run calls `waiter.wake(token)` after `resolveApproval`, and no run reads a verdict from a wake, hook payload or queue message.
+- [ ] No code grants, skips or auto-approves a call because of `meta.risk` or `meta.effects`.
 
 ## 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).
+- [references/stores-and-resume.md](references/stores-and-resume.md): `approvalsHandler` routes and preconditions, custom stores, relation approvers, approval policies as data, the token and its CloudEvents, resume details and denial causes, the runtime surfaces table.
+- [references/delivery-and-waiters.md](references/delivery-and-waiters.md): operation risk meta, `approvalPrompt` with `permdock/delivery`, `approvalEmail`, `approvalCard` and `approvalActions`, `ApprovalWaiter`, `pollingApprovalWaiter`, `workflowSdkWaiter`, `cloudApprovalWaiter`.
+- Docs: [approval security](https://permdock.com/docs/security/approvals), [approvals adapter](https://permdock.com/docs/adapters/approvals), [delivery](https://permdock.com/docs/concepts/delivery), [Resend](https://permdock.com/docs/adapters/resend), [Chat SDK](https://permdock.com/docs/adapters/chat-sdk), [automations](https://permdock.com/docs/concepts/automations), [Workflow SDK](https://permdock.com/docs/adapters/workflow-sdk), [operations](https://permdock.com/docs/concepts/operations), [wire formats](https://permdock.com/docs/concepts/wire-formats).

package/skills/permdock-approvals/references/delivery-and-waiters.md

@@ -0,0 +1,172 @@
+# Risk meta, approval prompts and waiters
+
+A pending request needs three things around it: a label saying how risky the call is, a prompt that reaches the approvers, and, for a background run, a way to park until someone answers. None of them decides anything: the verdict comes from `approvalsHandler` (or `resolveApproval`) and the resume re-runs `decide`.
+
+## Risk meta
+
+`defineOperations` from `permdock` binds each action to one permission leaf and carries `meta` `{ risk?, effects?, title? }` ([operations](https://permdock.com/docs/concepts/operations)):
+
+```ts
+import { defineOperations } from "permdock";
+
+export const operations = defineOperations(permissions, {
+  "invoice.pay": {
+    permission: permissions.invoice.pay,
+    data: (input: { id: string }) => invoices.get(input.id),
+    meta: {
+      title: "Pay an invoice",
+      risk: "high",
+      effects: ["spend", "external"],
+    },
+  },
+});
+```
+
+- `risk` is one of `low`, `medium`, `high`, `critical`. `effects` lists distinct values of `read`, `write`, `delete`, `send`, `spend`, `external`. Any other value throws when the map is built.
+- PermDock never decides on `meta`. The approval comes from the grant's `approval`; `meta` is what a host reads to label, confirm or gate a call (a red badge, a confirmation dialog, a rule in your own UI).
+- Do not use `risk: 'high'` instead of `approval` on the grant. A label without a grant asks nobody.
+- `approvalPrompt(request, { operation })` copies the operation's `name`, `title`, `risk` and `effects` into the prompt, so emails and cards show them.
+
+## Approval prompts
+
+`permdock/delivery` sends a message only to recipients the policy grants, and `approvalPrompt` turns a pending request into what an approver sees ([delivery](https://permdock.com/docs/concepts/delivery)).
+
+```ts
+import { whoCan } from "permdock";
+import { requestApproval } from "permdock/approvals";
+import { approvalPrompt, audience, createPermDock } from "permdock/delivery";
+import { approvalEmail, resendTransport } from "permdock/resend";
+
+const delivery = createPermDock(policy, {
+  transports: {
+    email: resendTransport(resend, { from: "Acme <billing@acme.test>" }),
+  },
+  principals, // PrincipalSource: links addresses to principals
+  sink,
+});
+
+const request = await requestApproval(store, decision, {
+  permission: permissions.invoice.pay,
+  resource: { type: "invoice", id: invoice.id },
+  subject: permdock.subject,
+  detail: `Pay invoice ${invoice.id}`,
+});
+const holders = await whoCan(permdock, permissions.invoice.pay, invoice);
+const approvers = await audience(permdock, permissions.invoice.read, invoice, {
+  candidates: holders.holders
+    .map((holder) => holder.principal.id)
+    .filter((id) => id !== permdock.subject.principal?.id),
+});
+const prompt = approvalPrompt(request, {
+  operation: operations["invoice.pay"],
+});
+await delivery.deliver(
+  permdock,
+  permissions.invoice.read, // a permission every approver holds on the row
+  invoice,
+  approvers.principals.map((id) => ({
+    principal: id,
+    channel: "email",
+    address: emailOf(id),
+  })),
+  {
+    email: approvalEmail(prompt, {
+      approvalUrl: "https://app.acme.test/approvals",
+    }),
+  },
+  { approval: prompt.id },
+);
+```
+
+- `approvalPrompt` throws a `TypeError` for a request that is not pending. The prompt (`ApprovalPrompt` v1) carries the request `id`, permission, scope, resource, requester, tenant, detail, `createdAt`, `expiresAt` and the operation; it never carries the approval token, roles or memberships.
+- `approvalUrl` is an https base the encoded request id is appended to, or a function of the prompt. Anything but https throws. The page it opens is the app's own approval screen, behind sign-in, that calls `approvalsHandler` (`GET /:id`, then `POST /:id/approve` or `/reject`).
+- `deliver` decides every recipient with `decideFor` and never rejects: a refused, unlinked or malformed recipient is a `failed` delivery event. Pass `{ approval: prompt.id }` so every event names the request.
+- Recipients come from the server: a `principal` id with the address the server loaded for it, or an address that `principals.principalByIdentity` links. Never take recipients from the request body.
+
+### Email
+
+`approvalEmail(prompt, { approvalUrl, product? })` from `permdock/resend` returns an `EmailMessage` with category `approval`. The subject is `Approval needed: <title>`; the body names the requester, the permission and resource, the risk and the expiry, and has one link to the approval page. It has no approve or reject link. Send it with `resendTransport`, or with your own `EmailTransport` for another provider. `resendWebhook` turns Resend bounces and complaints into delivery events ([Resend adapter](https://permdock.com/docs/adapters/resend)).
+
+### Chat
+
+`permdock/chat-sdk` renders and applies approval cards on the Chat SDK ([Chat SDK adapter](https://permdock.com/docs/adapters/chat-sdk)):
+
+```ts
+import { createPermDock } from "permdock/chat";
+import { approvalActions, chatSdkTransport } from "permdock/chat-sdk";
+
+const chatPermDock = createPermDock(policy, {
+  principals,
+  memberships,
+  store: store,
+});
+const actions = approvalActions(chatPermDock, { workspace: "T0ACME" });
+chat.onAction([...actions.actionIds], actions.onAction);
+
+// a chat message with `approval` is posted as `approvalCard`
+await delivery.deliver(
+  permdock,
+  permissions.invoice.read,
+  invoice,
+  recipients,
+  {
+    chat: {
+      text: prompt.detail,
+      approval: { prompt, url: "https://app.acme.test/approvals" },
+    },
+  },
+  { approval: prompt.id },
+);
+```
+
+- `approvalCard(prompt, { approvalUrl, buttons? })` shows the detail, requester, permission, resource, risk and expiry, a Review link, and Approve and Reject buttons whose `value` is the request id, never the token. `buttons: false` leaves only the link.
+- `approvalActions` resolves the clicking user from the platform's signed event through `ChatPermDock.resolveAction`. A click from an unlinked user, the requester or a bot records nothing.
+
+### Rules
+
+- A link never approves. A forwarded email, a link scanner or a preview bot can open it; the approval page asks the approver to sign in and decides as that session's subject.
+- Buttons are allowed in chat only because the platform signs the click and names the user. Never put approve or reject links, or the token, in an email.
+
+## Waiters
+
+A background run (a workflow, a queue consumer) cannot hold an HTTP request open while it waits. `createPermDock` from `permdock/workflow` takes a `waiter` (`ApprovalWaiter`) next to `approvals` ([automations](https://permdock.com/docs/concepts/automations)):
+
+```ts
+import { createPermDock, pollingApprovalWaiter } from "permdock/workflow";
+
+const workflow = createPermDock(policy, {
+  signer,
+  verifier,
+  principals,
+  automations,
+  store: store,
+  waiter: pollingApprovalWaiter({ store, interval: 5_000 }),
+  sink,
+});
+
+const decision = await workflow.awaitApproval(
+  ticket,
+  permissions.invoice.send,
+  invoice,
+);
+```
+
+- `ApprovalWaiter` is `{ wait(token, { expiresAt?, signal? }), wake(token) }`. `wait` resolves when the request leaves `pending`, is woken or expires; it never says how it was decided.
+- `awaitApproval(ticket, permission, row)` opens the request, waits, rebuilds the run and decides again. Runners that wait outside the call use the halves: `openApproval` before the wait and `resumeApproval(ticket, permission, token, row)` after it. A request still pending denies with reason `approval`.
+- `pollingApprovalWaiter({ store, interval })` reads the store every `interval` milliseconds (default 5,000); `wake` ends a wait in the same process at once.
+- `workflowSdkWaiter({ createHook, resumeHook, sleep? })` from `permdock/workflow-sdk` parks a Workflow SDK run on the hook `approvalHookToken(token)`. Call `wait` inside the `"use workflow"` function and `openApproval` / `resumeApproval` as steps ([Workflow SDK adapter](https://permdock.com/docs/adapters/workflow-sdk)).
+- `cloudApprovalWaiter` from `permdock/cloud` wakes waits from PermDock Cloud's `com.permdock.approval.resolved`, `.expired` and `.cancelled` webhooks ([Cloud adapter](https://permdock.com/docs/adapters/cloud)).
+
+The approver's endpoint wakes the run after it records the verdict:
+
+```ts
+import { resolveApproval } from "permdock/approvals";
+
+await resolveApproval(store, token, {
+  status: "approved",
+  by: approverFromSession(request),
+});
+await waiter.wake(token);
+```
+
+A wake carries no verdict. Anyone holding a Workflow SDK hook token can resume it, so the step after the wait reads the store through `resumeApproval`; a forged wake finds the request still pending and denies. Never pass the verdict through the hook payload or the queue message.

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

@@ -7,12 +7,12 @@ The API and the store contract are on the [approvals adapter](https://permdock.c
 ```ts
 import { approvalsHandler, memoryApprovalStore } from "permdock/approvals";
 
-export const store = memoryApprovalStore({ ttl: 60 * 60 * 1000 }); // default: one hour
+export const store = memoryApprovalStore({ ttl: 60 * 60 }); // seconds; 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
+// Routes for approvers: GET /pending, GET /mine, GET /:id, GET /:id/signature, POST /:id/approve, POST /:id/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
@@ -22,6 +22,10 @@ const handler = approvalsHandler(store, {
 app.all("/permdock/approvals/*", (c) => handler(c.req.raw));
 ```
 
+- `GET /:id` returns one request without its token, with a strong `ETag`; `If-None-Match` answers `304`. Unknown and foreign ids are `404`.
+- `POST /:id/approve` and `POST /:id/reject` honour `If-Match` with that `ETag`. A stale tag is `412`, so two approvers on one screen cannot overwrite each other. Send `If-Match` from the confirmation screen.
+- `GET /:id/signature` serves the signed approval (`vnd.permdock.approval+jwt`) when the handler has a `signer` and the request is approved, to the requester and the approvers only.
+
 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`.
@@ -33,10 +37,10 @@ The store's `ttl` is the window a request stays open when the call sets none; `r
 ## Approval policies as data
 
 ```ts
-import { memoryApprovalPolicies } from "permdock";
+import { getPermDock, memoryApprovalPolicySource } from "permdock";
 
-const permdock = await createPermDock(policy, user, {
-  approvalPolicies: memoryApprovalPolicies([
+const permdock = await getPermDock(policy, user, {
+  approvalPolicies: memoryApprovalPolicySource([
     {
       permission: "expense.pay",
       tenant: "o_acme", // absent: every tenant
@@ -60,7 +64,9 @@ const permdock = await createPermDock(policy, user, {
 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`.
+The token is `sha-256:<base64url>`, a digest of the RFC 8785 JSON of 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`. Treat it as opaque: compare it, never parse it.
+
+A `DecisionSink` receives the request's lifecycle as CloudEvents `com.permdock.approval.requested`, `com.permdock.approval.resolved`, `com.permdock.approval.expired` and `com.permdock.approval.cancelled` ([wire formats](https://permdock.com/docs/concepts/wire-formats)). An event never approves; a consumer that acts on `resolved` still resumes through the store.
 
 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.
 
@@ -68,6 +74,14 @@ Over HTTP, the client retries the same request with the `PermDock-Approval: <tok
 
 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`).
 
+## Delegation
+
+Pass `approvalDelegations` (`memoryApprovalDelegationSource` or your table) and `subjectFor` to `approvalsHandler`. A delegate may approve what the delegator could, inside `from` (inclusive) and `until` (exclusive). The signature records `by` as the delegate and `onBehalfOf` plus `delegation` for the person covered. The store checks the delegator again. A link or a feed cannot approve. See [delegation](https://permdock.com/docs/adapters/approvals#delegation).
+
+## Access reviews
+
+`startAccessReview` lists holders of a set of permissions. `decideAccessReviewItem` records keep or revoke. The application changes the role or membership, then marks the item applied. `accessReviewsHandler` serves the routes. See [access reviews](https://permdock.com/docs/concepts/access-reviews).
+
 ## Surfaces
 
 | Runtime                                 | Ask                                                                                             | Resume                                                                                  |
@@ -87,7 +101,7 @@ For AG-UI event shapes, defer to the `ag-ui` spec skill (`npx skills add ScaleDo
 
 ## 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)).
+Send the prompt with `approvalPrompt` and `permdock/delivery`: `approvalEmail` from `permdock/resend`, `approvalCard` and `approvalActions` from `permdock/chat-sdk`. A prompt carries the request id, never the token, and links to the app's approval page, where the approver signs in; the verdict goes through `approvalsHandler` with that session's subject. A link never approves. Details in [delivery-and-waiters.md](delivery-and-waiters.md#approval-prompts).
 
 ## Approvers
 

package/skills/permdock-audit/SKILL.md

@@ -15,7 +15,7 @@ Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter gua
 ## 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.
+- Whether the `permdock` binary runs here (`permdock usage --json`, `permdock doctor --json`; the report is in the result's `data`); 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
@@ -40,7 +40,7 @@ Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter gua
      ✓ 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.
+5. **Tests.** No `describePolicy` suite, or one with `exhaustive: false`, is a finding: a new permission can ship untested. A custom `ApprovalStore`, `DecisionSink`, `MembershipSource`, `CustomRoleSource`, `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.
@@ -50,7 +50,7 @@ Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter gua
    - 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.
+   - A change to the `rls` config or generated RLS comes with `permdock rls generate --check` passing and an `testRlsParity` 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.
 

package/skills/permdock-credentials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, service accounts or feed keys 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
@@ -24,17 +24,17 @@ Authentication is upstream: core never verifies a token. A `subjectFrom*` resolv
 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`.
+4. Store only `hashApiKey(key)` and show the key once. A user or service key lists its permissions and expires unless the tenant opts in with `allowNoExpiry`. A feed key (`pdfeed_`) does not expire; rotation replaces the secret, and the key is bound to one resource.
 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)
+1. **Verify access tokens.** Create one `jwtSubjectResolver({ discovery, audience })` per issuer from `permdock/jwt` for the life of the process, because it caches Discovery and the JWKS; `subjectFromJwt(token, options)` caches nothing and suits a one-off check. Or use `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 })`.
+3. **Resolve API keys.** Call `subjectFromApiKey(key, { verifier: apiKeyVerifier({ find }), permissions, principals, revoked, settings, sink, tenant })` on each request.
    ✓ 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.
@@ -45,7 +45,7 @@ Authentication is upstream: core never verifies a token. A `subjectFrom*` resolv
 
 - [ ] `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).
+- [ ] API keys are stored as hashes, created only through `permdock.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`.