permdock 0.0.0 → 0.1.0

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

@@ -0,0 +1,211 @@
+# 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.dev/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.dev/docs/adapters/ai-sdk)).
+
+## 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.dev/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.dev/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.dev/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'`, 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. 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.dev/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.
+
+## 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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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.dev/docs/security/approvals), [approvals adapter](https://permdock.dev/docs/adapters/approvals), [wire formats](https://permdock.dev/docs/concepts/wire-formats).

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

@@ -0,0 +1,83 @@
+# Approval stores and the resume flow
+
+The API and the store contract are on the [approvals adapter](https://permdock.dev/docs/adapters/approvals); the token and the runtime table are on [approval security](https://permdock.dev/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));
+```
+
+- `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.
+- 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.
+- 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" }, // no escalation in data
+    },
+  ]),
+});
+```
+
+- 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.
+- 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`.
+
+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.dev/docs/adapters/approvals#delivery)).

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.dev/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.dev/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.dev/docs/security/owasp-agentic), [threat model](https://permdock.dev/docs/security/threat-model), [`permdock doctor`](https://permdock.dev/docs/cli/doctor), [`permdock usage`](https://permdock.dev/docs/cli/usage), [testing](https://permdock.dev/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.dev/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.dev/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.dev/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.dev/docs/concepts/authentication), [subject](https://permdock.dev/docs/concepts/subject), [JWT adapter](https://permdock.dev/docs/adapters/jwt), [API keys](https://permdock.dev/docs/concepts/credentials), [link capabilities](https://permdock.dev/docs/concepts/capabilities), [JOSE](https://permdock.dev/docs/standards/jose).

package/skills/permdock-credentials/references/tokens-keys-links.md

@@ -0,0 +1,127 @@
+# Tokens, API keys and share links
+
+Owning pages: [JWT adapter](https://permdock.dev/docs/adapters/jwt), [authentication](https://permdock.dev/docs/concepts/authentication), [API keys](https://permdock.dev/docs/concepts/credentials), [link capabilities](https://permdock.dev/docs/concepts/capabilities).
+
+## Access tokens — `permdock/jwt`
+
+```ts
+import { subjectFromJwt } from "permdock/jwt";
+
+const subject = await subjectFromJwt(token, {
+  discovery: "https://issuer.example.com",
+  audience: "https://api.example.com",
+});
+```
+
+- Prefer `discovery: '<issuer>'` over a hand-copied `jwks` URL. Set `audience` to the resource identifier. Write algorithms as `Ed25519`, `ES256` or `PS256`; never `EdDSA`, `none` or `RSA1_5`.
+- Keep the default `accept: 'access-token'`, so an ID token never authorises an API call.
+- `jose` is an optional peer. A failure is the anonymous subject, never a throw; the cause is reported through `on('auth')`. A claimed `act` chain that does not nest is anonymous with cause `invalid-chain`.
+- When the app already called RFC 7662 or RFC 9767 introspection, pass the response JSON to `subjectFromIntrospection`. `active` other than `true` is anonymous, and the HTTP call stays the app's.
+- In CI, `subjectFromCiOidc(jwt, { provider: 'github', audience })` returns a `workload` principal, never a user.
+
+## API keys and service accounts
+
+```ts
+import { decideCredential } from "permdock";
+import { generateApiKey, hashApiKey } from "permdock/server";
+
+const decision = await decideCredential(
+  permdock,
+  {
+    kind: "service", // or 'user'
+    id: "svc_01J8",
+    tenant: "o_1",
+    roles: ["developer"],
+    permissions: [permissions.repo.read],
+    expiresAt: Math.floor(Date.now() / 1000) + 30 * 86_400,
+  },
+  { settings },
+);
+if (decision.outcome === "granted") {
+  const key = generateApiKey(decision.credential.id);
+  await db.insert(apiKeys).values({
+    id: decision.credential.id,
+    hash: await hashApiKey(key),
+    credential: decision.credential,
+  });
+  return key; // shown once
+}
+```
+
+- Guard the endpoint that creates keys with its own permission (`apiKey.create`).
+- Every key lists 1 to 64 permissions. A `user` key is its owner's live rights narrowed to the key; a `service` key is a `kind: 'service'` principal whose tenant, roles and permissions must be within the creator's `assignableRoles` / `assignablePermissions` (otherwise `exceeds-creator`). A key cannot mint keys.
+- Tenant rules come from a `SettingsSource` (`memorySettings({ o_1: { credentials: { maxTtl, kinds, approval, allowNoExpiry } } })`). A key without `expiresAt` needs `allowNoExpiry`. `approval: true` makes creation `approval-required`; after approval, call `decideCredential` again with `approved: token`.
+- Store only `hashApiKey(key)`. The key is `pdk_<id>_<secret><checksum>`; `parseApiKey` rejects a bad checksum before any lookup.
+
+Resolve keys on each request:
+
+```ts
+import { apiKeyVerifier, subjectFromApiKey } from "permdock/server";
+
+const resolveKey = subjectFromApiKey({
+  verifier: apiKeyVerifier({ find: (id) => findKeyRow(id) }), // returns { credential, hash }
+  permissions,
+  owner: (id) => loadOwner(id), // the live owner of a user key
+  revoked: (id) => isRevoked(id),
+  settings,
+  sink,
+});
+
+const subject = await resolveKey(bearer, { tenant });
+```
+
+Never pass a `memberships` source to `createPermDock` for a service-key subject: its one membership comes from the credential. `memoryCredentials()` is an in-process store for tests.
+
+## Share links
+
+```ts
+import { signCapability } from "permdock";
+import { subjectFromCapability } from "permdock/jwt";
+
+// Declare the link's roles on the resource
+role("guest", [allow(permissions.quote.read, { where: { status: "sent" } })], {
+  on: permissions.quote,
+});
+
+// Mint, behind a guard of its own (quote.share)
+const token = await signCapability(
+  {
+    id: linkId,
+    on: { resource: permissions.quote, id: quote.id },
+    roles: ["guest"],
+    expiresAt,
+  },
+  signer,
+  { audience },
+);
+
+// Resolve
+const subject = await subjectFromCapability(token, {
+  jwks,
+  issuer,
+  audience,
+  revoked,
+  replay,
+  viewer,
+  linkPolicy,
+});
+```
+
+- The result is a `kind: 'link'` principal with one `{ on, roles, via: 'link' }` membership. It never holds a scope or global role.
+- `linkPolicy` returns the tenant's `LinkPolicy` (`maxLifetime`, `redeemers`, `once`). Passing the same policy to `signCapability` refuses to mint a link the resolver would refuse.
+- Never an unguessable id without expiry, and never a security-definer RPC for the guest page.
+
+With Supabase, let RLS serve the link through an exchange, never the link token itself:
+
+```ts
+import { exchangeCapability } from "permdock/supabase";
+
+const accessToken = await exchangeCapability(subject, {
+  key: signingJwk,
+  alg: "ES256",
+  kid: "permdock-links",
+  ttl: 300,
+});
+```
+
+`accessToken` is `role: 'anon'` with a `capability` claim and no `sub`, or `undefined` for anything but a live link. Generate the matching policies with `permdock rls generate --capabilities`.