Authentication and PermDock

PermDock is an authorization library. It does not log anyone in, does not issue or refresh tokens, and does not store sessions. Every decision starts from verified material: a session your framework validated, a JWT whose signature and claims were checked against the issuer's keys, an authInfo object the MCP SDK attached after bearer verification, a signature the Web Bot Auth verifier accepted. PermDock's job begins where that verification ends: map the material to a subject, build a request-scoped PermDock, and answer can / decide.

The rule that follows from this is the one every adapter and provider on this site obeys: if the material cannot be verified, the subject is anonymous. Anonymous has no roles and therefore no grants. Nothing throws, nothing falls back to "trust the claims anyway", and the audit event says why (ADR 0018).

The pipeline

Verification happens to the left of the first box and is never PermDock core's job: core has no runtime dependency other than @standard-schema/spec (ADR 0015), so it cannot verify a signature. Verification lives in three places instead:

• Your framework or provider verifies sessions and tokens and hands PermDock the result (Next.js, Better Auth, Supabase getClaims(), Clerk auth(), the MCP SDK's bearer middleware).
• permdock/jwt verifies bearer JWTs against a JWKS or secret with jose as an optional peer dependency and returns a subject (JWT adapter).
• Provider adapters (permdock/supabase, permdock/clerk, permdock/better-auth) reuse the provider SDK's verification and map its output.

Each of them exposes a subjectFrom<Source> function. The name says where the material came from; the return type is always a Subject; the function never throws.

Sources of verified material

Two entries deserve a note. An API key identifies a caller that acts on its own behalf, so it is a principal with roles, not an actor: actors never hold grants, and a key modelled as an actor would be denied everything (subject, "Service principals"). A Web Bot Auth signature identifies who is asking, not whose authority applies, so it fills actor and leaves the principal to the token or session on the same request (Web Bot Auth).

Provider recipes

Four providers get an adapter (permdock/supabase, permdock/better-auth, permdock/clerk, permdock/convex) because each exposes a verification hook only in-process code can use. Every other provider is a recipe over subjectFromJwt or the framework session, following the rule that ecosystems are reached through wire formats rather than per-tool packages (ADR 0023). Every mapper, shipped or yours, satisfies the SubjectResolver interface, exports a base principal type and takes a schema option for custom claims (extension interfaces); how each fills tenant, team and resource memberships is summarised on tenancy and detailed in each provider page's "Memberships" section. The table records, per provider, where verification happens, which claim carries roles and organisation, and which fields are user-editable and therefore never feed grants. Claim names are the providers' defaults as documented in September 2026; confirm against the provider's current docs and pin them in the claims option.

Three patterns recur. Every provider has a server-only bucket (app_metadata, custom claims, serverMetadata, metadata_admin, trusted_metadata) and a user-writable one; only the first feeds grants. Organisation-scoped roles ride in the token for the org the session is currently in, so multi-org checks need either a token per org or a context lookup. And a provider's own permission or feature-flag arrays are delegation.scopes or context inputs, not PermDock grants: the policy stays the single place that says who may do what.

Two newer rows follow from the 2026-07-28 MCP release. Providers that sell the OAuth 2.1 authorization server for MCP servers (WorkOS Connect, Stytch Connected Apps, Descope, Scalekit, Auth0 Token Vault, Supabase's OAuth server) issue the access tokens permdock/mcp receives as authInfo; client_id becomes actor.id and scope becomes delegation.scopes with no provider-specific code (MCP authorization). Enterprise agent identity (Okta Cross App Access, Microsoft Entra Agent ID) produces tokens with the human as sub and the agent as the client, which is the two-principal subject as-is (delegation). Billing and entitlement claims (Clerk Billing pla and fea, Frontegg entitlements, Kinde feature_flags) are server-written and eligible as roles under the "entitlements are roles" rule, never as grants (Clerk provider).

Claim trust rules

Verification tells you a token is genuine. It does not tell you which claims inside it may drive grants. PermDock's providers apply these rules, and your own subject resolver should too:

• sub is the principal id. Nothing else (an email, a display name) identifies the principal, because those can change or be reused.
• Server-set claims are trusted; user-editable claims are never used for grants. Supabase separates app_metadata (written by service code and Auth Hooks) from user_metadata (writable by the user through the client SDK). subjectFromSupabase reads roles and tenant from app_metadata or from a hook-injected top-level claim and never looks at user_metadata. The same split exists elsewhere under other names: Clerk public metadata set through the backend API versus anything the client can write; Better Auth user.role managed by the admin plugin versus profile fields.
• Roles from claims or roles from the database. A role claim is cheap and offline-checkable but stale until the token is refreshed. A database lookup in the policy's context function is fresh but costs a query per createPermDock. Prefer claims when the token lifetime is short or a Shared Signals receiver invalidates on change; prefer context when role changes must take effect on the next request and tokens live for hours.
• Tenant from claims. A tenant_id or orgId that RLS also filters on belongs in the principal, sourced from a server-set claim, so the in-process condition and the generated (select auth.jwt()) ->> 'tenant_id' read the same value. With scoped roles the claim fills principal.tenant (the active tenant) and a membership; it is never defaulted when absent (tenancy).
• Memberships are verified material too. A team id, a resource share or a per-tenant role list comes from the provider's session, a server-set claim, a MembershipSource over your tables or the policy's own functions; never from a request body, a model argument, an unsigned header or a CLI flag. Team and group identifiers are ids (SCIM value, Entra object id), never display names.
• Unknown role names are dropped. A claim naming a role the policy does not declare contributes nothing (fewer grants, never more) and is reported in development. On a membership the name is first offered to the tenant's RoleSource as a custom role; if it resolves, the declared roles it includes apply.

Single sign-on and directories

"Log in with Google Workspace", "log in with Microsoft" and SAML SSO through Okta are authentication, and PermDock stays out of them. The auth layer (Better Auth's SSO plugin, Clerk Enterprise SSO, WorkOS AuthKit, Auth.js providers, Supabase SAML) terminates the SAML assertion or the IdP's ID token and issues its own session or JWT; that is what subjectFrom* reads. A SAML assertion never reaches PermDock, and a Google or Entra ID token only does when your API accepts it directly as a bearer (the Google and Entra rows above).

SSO nevertheless touches PermDock in three places, and each has a trap worth naming.

Tenant. The organisation a user logged in through is the natural principal.tenant, and every IdP carries it differently: Google Workspace in hd (hosted domain), Entra ID in tid, Okta in the authorization server's issuer or a custom claim, WorkOS and Clerk in org_id / orgId after they have mapped the connection to an organisation. Two rules apply. hd is absent for consumer Google accounts and tid is the personal-accounts tenant when the common endpoint is used, so a missing or unexpected tenant claim must produce a subject with no tenant (which tenant-scoped conditions then deny), never a default tenant; compare the claim against the connections you have onboarded, or restrict the issuer to your own Entra tenant and pass hd as an OAuth parameter to Google so the IdP filters first. And the domain of email is never a tenant: email_verified may be false, and a consumer IdP lets a user change the address. permdock doctor flags a claims.tenant that points at email (PD010) or at an optional tenant claim under a multi-tenant issuer (PD011).

Groups to roles. This is the permission-adjacent part and the IdPs differ most here:

The pattern that fits PermDock is to map groups to roles in the IdP or the auth layer, not in the policy: the policy declares roles, the token or session names them, and a directory group is one more server-set source of a role name. When the token only carries group ids, the mapping is a lookup in definePolicy's subject function and needs no PermDock API:

const rolesByGroupId: Record<string, string> = {
  'f2a1c0c8-1d5b-4b7e-9c0a-0d5b8a7c6e21': 'editor',   // Entra group object id, not the display name
  '0e6f5c1a-3b2d-4a9e-8f7c-1a2b3c4d5e6f': 'admin',
}

export const policy = definePolicy(permissions, {
  roles: [editor, admin],
  subject: (claims: EntraClaims | null) =>
    claims && {
      id: claims.oid,
      orgId: claims.tid,
      roles: (claims.groups ?? []).flatMap((id) => rolesByGroupId[id] ?? []),
    },
})

Group ids rather than display names, because names are editable by any group owner and are not unique across tenants. Directory Sync and SCIM are the third path: the IdP provisions users and groups into your database, and roles come from a row you control; IPSIE AL1 tracks the SCIM profile, and PermDock does not read SCIM itself.

With scoped roles the same lookup produces memberships instead of flat roles, which keeps the team visible to audit and to team-scoped roles: groups become { tenant: claims.tid, team: id, roles: rolesByGroupId[id] ?? [], via: 'group:' + id } entries, and subjectFromJwt does this by default for the RFC 9068 groups claim with a groupRoles option holding the id-to-roles map (JWT authorization claims).

Lifecycle. Deprovisioning a user in Google Workspace or Entra ID must reach cached snapshots. Entra, Okta and Auth0 transmit CAEP session-revoked and credential-change events today, which the SSF receiver turns into snapshot invalidation; for IdPs without a transmitter, the bound is exp and session_expiry as described under staleness, and SCIM deprovisioning into your database takes effect on the next context lookup. "We disabled the account and they can still see the page" is answered by whichever of these three you wired, so the SSO section of your runbook should name it.

JWT validation checklist

permdock/jwt implements this list; if you verify tokens yourself before calling a subjectFrom* function, your verifier must too. It follows RFC 8725 (JSON Web Token Best Current Practices) and its successor draft, rfc8725bis, which is in the RFC Editor queue.

1. Allowed algorithms are an explicit list. Configure algorithms: ['ES256', 'PS256', 'EdDSA'] (or the subset your issuer uses). A token whose alg is not in the list is rejected before any key lookup.
2. none is never allowed, whatever the list says.
3. The token never picks the key. jku, x5u and embedded jwk headers are ignored; keys come only from the configured JWKS URL, key set or secret. This closes key-confusion attacks where an RSA public key is fed to an HMAC verifier.
4. kid must resolve in the JWKS. An unknown kid triggers at most one refetch per configured interval; if it still does not resolve, the token is rejected.
5. iss equals the configured issuer. Exact string comparison.
6. aud contains this resource. A token issued for another API is rejected even when the signature is valid.
7. exp and nbf are checked with a small, explicit clock tolerance (seconds, not minutes). iat in the future is rejected under the same tolerance.
8. Signature before claims. Claims are parsed only after the signature verified; an attacker cannot make the verifier branch on unverified data.
9. Bearer tokens come from the Authorization header (RFC 6750 section 2.1) or the DPoP scheme (RFC 9449 section 7.1). Tokens in query strings are rejected under profile: 'fapi2' and discouraged everywhere.

Token to delegation

A token often carries authority that was delegated to the bearer, not the bearer's own authority. PermDock maps the standard carriers to delegation so that the intersection rule applies:

A token with an act claim and no scope or authorization_details yields an actor with no delegation, and every check is denied with reason no-delegation. This is deliberate: a delegated token that says nothing about what was delegated grants nothing.

Sender constraint

FAPI 2.0 and the IPSIE profiles ask resource servers to accept sender-constrained tokens: a token bound to a key the client must prove it holds. The binding lives in the cnf claim and PermDock surfaces it on the subject so adapters can check it:

The binding is attached to principal when the token identifies a user or workload acting for itself, and to actor when the token carries an act chain (the key belongs to the agent that presented it). Core stores it and puts it on audit events; checking it is an adapter concern, because proof-of-possession needs the request: verifyDpopProof(request, claims) in permdock/jwt compares the DPoP header's JWK thumbprint to cnf.jkt, and the mTLS check compares the client certificate the TLS terminator forwarded to cnf.x5t#S256. Under profile: 'fapi2' a token without cnf is rejected outright (FAPI 2.0).

Staleness and revocation

A verified token is a statement about the past. Three signals bound how long PermDock treats it as current:

• exp. The subject built from a token inherits its expiry, and snapshot() sets expiresAt to it so a client stops trusting cached grants when the token would have expired.
• session_expiry. The IPSIE SL1 profile and OpenID Connect Enterprise Extensions add a session_expiry claim to ID tokens and require re-authentication after it (IPSIE SL1 profile). When present it is the earlier bound: expiresAt = min(exp, session_expiry).
• CAEP events. session-revoked, credential-change and assurance-level-change delivered through the Shared Signals Framework invalidate the subject's cached snapshots immediately, so revocation is bounded by the identity provider rather than by a timer (SSF adapter).

None of these make a stale token verify differently: an expired token is rejected by the checklist above, and a revoked but unexpired token is only caught by CAEP or by an introspection call your resolver chooses to make.

Authenticating the decision endpoint

The AuthZEN endpoint served by permdock/authzen answers "may this subject do this" for remote policy enforcement points. Two callers exist, and both must authenticate as themselves:

• A PEP asking for the subject it authenticated (the browser's PermDockProvider endpoint, a gateway). The endpoint resolves the subject from the caller's own session or token and ignores any subject field in the request body. A browser can only ask about itself.
• A trusted PEP asking on behalf of many subjects (an API gateway, a sidecar). It authenticates with client credentials or mTLS; the identity in that token must be in the endpoint's allow-list before the request body's subject is honoured.

A model, a tool argument or a page's JavaScript is never a trusted PEP: the threat model invariant "never trust model-supplied subjects" applies to the decision endpoint exactly as it does to MCP tools. A shared static secret in client code is obfuscation, not authentication (AuthZEN adapter).

Agent-run processes

CLIs, workers and agent runtimes are the place where verification is most tempting to skip. A command like mytool deploy --actor=ci-bot is a claim, not an identity. The terminal adapter therefore refuses to build a subject from flags or environment variables that name a principal or actor; it requires a verified token (device authorization grant, client credentials, or a workload identity) and derives the actor from it. Tokens stored on disk are treated like session cookies: short-lived, scoped, and invalidated by CAEP where the issuer supports it. An agent-run CLI that cannot present a token runs as anonymous and gets exactly the anonymous grants.

Example: a JWT into a decision

import { createPermDock } from 'permdock'
import { subjectFromJwt } from 'permdock/jwt'
import { policy } from './policy'
import { permissions } from './permissions'

const token = request.headers.get('authorization')?.replace(/^Bearer /, '')

const subject = await subjectFromJwt(token, {
  jwks: new URL('https://login.example.com/.well-known/jwks.json'),
  issuer: 'https://login.example.com',
  audience: 'https://api.example.com',
  algorithms: ['ES256'],
  claims: { id: 'sub', roles: 'app_metadata.roles', tenant: 'app_metadata.tenant' },
  delegation: { scopes: 'scope', authorizationDetails: 'authorization_details' },
  actor: { from: 'act' },
})
// subject = {
//   principal: { id: 'user_42', kind: 'user', roles: ['editor'], tenant: 'acme' } | null,
//   actor?:    { id: 'https://agent.example/cimd.json', kind: 'oauth-actor' },
//   delegation?: { scopes: ['post:read', 'post:update'], authorizationDetails: [...] },
//   expiresAt: 1757164800,
// }

const permdock = await createPermDock(policy, subject)
const decision = permdock.decide(permissions.post.update, post)
// granted: editor role allows it AND 'post:update' is in delegation.scopes
// denied { reason: 'not-delegated' }: the role allows it but the token did not delegate it
// denied { reason: 'anonymous' }: the token failed verification; the audit event carries the reason code

subjectFromJwt returned a full Subject, so createPermDock takes it as the second argument with no third; the actor and delegation are already inside it. When verification fails, subject.principal is null and the same two lines produce a denial rather than an exception.

Related

• Subject: the shape the verified material becomes.
• JWT adapter: subjectFromJwt, createJwtSubjectResolver, verifyDpopProof.
• Supabase provider: asymmetric signing keys, getClaims(), the Custom Access Token Hook.
• Delegation: the attenuation invariants that the delegation mapping feeds.
• SSF adapter: CAEP events from Entra, Okta and Auth0 that invalidate snapshots after SSO deprovisioning.
• doctor: PD010 and PD011, the checks for role and tenant claims sourced from unverified or optional claims.
• Threat model: token-handling threats and their mitigations.
• ADR 0018: Authentication is upstream.

Sources

• FAPI 2.0 Security Profile, sections 5.3.4 (resource servers) and 5.4.1 (cryptography).
• RFC 9635, Grant Negotiation and Authorization Protocol, section 8 (resource access rights).
• OAuth Transaction Tokens and the WIMSE architecture for workload principals and context propagation.
• IPSIE SL1 OpenID Connect Profile for session_expiry and sender-constrained tokens.
• Supabase JWT signing keys for the app_metadata / user_metadata split and getClaims().
• Google Identity: OpenID Connect for the hd claim, the hd authorization parameter and the certificate endpoint.
• Microsoft Entra: configure group claims and app roles for the groups overflow behaviour and the app-roles alternative.
• Okta: add a groups claim for the groups claim filter on custom authorization servers.