Standards

Status: planned Phase: 1

PermDock is an in-process library, not a hosted policy service. It still has to talk to the rest of an authorization stack: identity providers that issue tokens, policy decision points that already exist in an organisation, API gateways that read OpenAPI documents, database engines that enforce row-level security, and agent runtimes (MCP servers, the AI SDK, the Claude Agent SDK, A2A agents, browsers running WebMCP) that need a yes/no/ask answer for every tool call. Every one of those seams already has a specification. PermDock adopts the specification instead of inventing a wire format, a policy language or a token shape of its own.

Why standards-first

• Interop with PDPs and PEPs. The decision endpoint speaks OpenID AuthZEN 1.0, so a Cerbos, Topaz or Keycloak deployment can call PermDock, and the pdp provider can call any certified PDP. See AuthZEN and ADR 0011.
• Interop with identity providers. Subjects carry OAuth scopes and RFC 9396 authorization_details; revocation arrives as CAEP events; MCP Enterprise-Managed Authorization tokens are consumed as-is. See OAuth for agents and Shared Signals and CAEP.
• Interop with agent runtimes. Each runtime already has a permission hook (scopeChallenge, toolApproval, canUseTool, Agent Card securityRequirements, document.modelContext.registerTool). PermDock translates one Decision into each vocabulary rather than asking runtimes to learn a new one.
• Agents can wire PermDock without bespoke formats. A coding agent that knows Standard Schema, OpenAPI, Problem Details and MCP authorization already knows most of PermDock's surface. Skills, AGENTS.md and llms.txt follow the same rule: use the format agents already read. See Agent docs standards.
• Fewer things to get wrong. Fail-closed defaults, deny overriding allow, prototype-safe paths and boundary validation are easier to audit when the inputs are well-specified formats rather than free-form objects. See the threat model.

The trade-off is that PermDock inherits the pace and gaps of each specification. Every unfinished text PermDock follows carries one of three postures (ADR 0025): build against a pinned revision when the capability is needed now and a stable twin can carry the same information (OpenAPI 3.3 Security Profiles, Overlay 1.2, WebMCP, RAR remediation, the OpenTelemetry GenAI conventions, Web Bot Auth), name when only a public identifier must be reserved (GNAP as an OpenAPI scheme, the permdock/jwt checklist drafts), or track. The watch list shows the posture per row.

Standards PermDock implements or targets

The Phase column is the first phase in which PermDock uses the standard; adapters that build on it later are listed on each page under "Adapter phases".

Related security frameworks that are not wire standards but shape the design: the OWASP Top 10 for Agentic Applications and the threat model.

Status: tracking

Standards pages carry one of four Status values. planned, in progress and shipped describe the code that implements the standard. tracking is for a specification PermDock follows and has designed against but has no adapter or feature for yet: GNAP and the watch list carry it today. A tracking page still has a Phase line, naming the phase in which PermDock would first act on the specification if the trigger stated on the page occurs, and it is reviewed each release like every watch-list row. When code is scheduled the status moves to planned.

A page for an unfinished text adds a third line, Draft posture: build | name | track; a build posture names the pinned revision in the same line, as OpenAPI 3.3 does.

By phase

• Phase 1 (core + agents). Standard Schema for definitions and boundary validation; Problem Details for HTTP denials; the AuthZEN-shaped decision endpoint and batched client; the two-principal subject with scope and authorizationDetails on every permission; permdock/jwt with the FAPI 2.0 profile and the RFC 9068 roles / groups / entitlements mapping into roles and memberships; skills, AGENTS.md and llms.txt; the watch list.
• Phase 2 (surfaces). permdock/mcp with scopeChallenge, elicitation and EMA awareness; the full permdock/authzen endpoint set and a certification run; OpenAPI 3.2 emission and import, Overlay output (1.1.0, and the pinned 1.2 draft behind --overlay 1.2), the pinned OpenAPI 3.3 Security Profile draft behind --target 3.3, Arazzo input and the x-permdock- namespace registration; WebMCP and A2A adapters.
• Phase 3 (data). Postgres RLS generate, import and verify; the SSF/CAEP receiver against the CAEP Interoperability Profile.
• Phase 4 (ecosystem). The pdp AuthZEN client provider; Web Bot Auth verification in HTTP adapters; delegation-chain verification and GNAP access evaluation; the docs MCP server.

One decision, many vocabularies

The standards above meet in one place: a Decision from decide. Each adapter translates the same three outcomes into the vocabulary its runtime already has.

No adapter ever emits an outcome outside these three; in particular the AI SDK adapter never returns 'not-applicable', the value that lets @ai-sdk/policy-opa fail open.

How to read a standards page

Every page in this section follows the same layout so an agent can scan it:

1. What it is: the specification, its status and the parts PermDock cares about.
2. Why it matters for PermDock: the problem it solves for a permissions library.
3. How PermDock uses it: the adapter, API or CLI command that implements it, in the exact shapes from the API design.
4. Mapping table: specification concept on the left, PermDock concept on the right.
5. Sources: the URLs the page was written from. Nothing on a standards page is asserted without one.
6. Open questions: what the plan leaves undecided.

The Status and Phase lines under each page's frontmatter follow the roadmap. Everything with code behind it is planned until Phase 1 ships; pages for specifications PermDock only follows are tracking (see above). Phase is the first phase in which PermDock uses the standard, and pages whose standard is used by several adapters add an "Adapter phases" sentence directly after it.

What PermDock deliberately does not standardise

• Policy language. Roles are TypeScript data (role, allow, deny) and conditions are a small portable JSON AST, see conditions. PermDock does not export Cedar or Rego and does not import them.
• Token issuance. PermDock consumes scopes, authorization_details, ID-JAG-derived tokens and delegation chains; it never mints them.
• Authentication. Providers (Supabase, Better Auth, Clerk, Convex) map an authenticated session to a subject. PermDock starts where authentication ends.

Sources

• Product plan, "Standards and agent runtimes (Sept 2026)" section, and the research survey.
• Each individual standards page lists its own primary sources.

Open questions

• Which standards deserve a certification or conformance run beyond AuthZEN (see AuthZEN); OpenAPI 3.2 output could be validated against the official schema in CI.
• Whether to publish PermDock's own extension vocabularies (x-permdock-permissions, the Problem Details type URIs, the authorizationDetails type) as a small registry page so other tools can reference them.