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. The only selector that still matches is anyone(); every other to: fails closed. Nothing throws, nothing falls back to "trust the claims anyway", and the audit event says why.

The pipelineCopy Anchor Link

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, 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 materialCopy Anchor Link

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 recipesCopy Anchor Link

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. Every mapper, PermDock's 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 groups of rows concern agents. 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 are server-written plan and feature inputs, never grants: RFC 9068 entitlements and Clerk Billing pla become principal.plans, Clerk fea becomes roles through the features map, and Frontegg entitlements and Kinde feature_flags are principal.plans or context (Clerk provider).

Claim trust rulesCopy Anchor Link

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.

MFA and passkeys as policy inputCopy Anchor Link

assurance() on a grant reads principal.assurance. Providers fill that object from verified claims; they never invent an amr value the token did not carry.

allow(permissions.filing.pay, {
  to: [roles.admin, assurance({ amr: ["hwk"], maxAge: 300 })],
});

A subject that lacks hwk or whose authTime is older than 300 seconds is denied with reason insufficient-user-authentication. HTTP adapters render Problem Details type ending in /step-up-required and WWW-Authenticate: Bearer error="insufficient_user_authentication".

Single sign-on and directoriesCopy Anchor Link

"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. Two ways to get there: an auth layer's Directory Sync (WorkOS, Better Auth's provisioning hook) writing rows your context or MembershipSource reads, or permdock/scim, an RFC 7644 receiver you mount that writes to a DirectoryStore you own and exposes it as directoryMembershipSource; group-to-role mapping is a groupRoles map or the roles attribute of the PermDock SCIM extension, set by the IdP or by the PermDock Cloud relay's mapping UI. The Cloud relays; it never resolves memberships (invariant 15). In Cloud-native directory mode the Cloud is the directory of record instead, and memberships reach your app only as the memberships, roles, entitlements and tenant claims of a Cloud-issued access token that subjectFromJwt verifies (PermDock Cloud). IPSIE AL1 is the checklist for the receiver's authentication.

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 (active: false or DELETE received by scimHandler, or a Directory Sync row) takes effect on the next directoryMembershipSource or context lookup, which is the next request when memberships are read per request and the next refetch when a snapshot is cached; scimHandler's onChange callback is where to invalidate the cache. "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.

Enterprise SSOCopy Anchor Link

OIDC enterprise SSO is subjectFromJwt({ discovery }) against the IdP or the auth layer's issuer. SAML is terminated upstream: Better Auth's SSO plugin, Clerk Enterprise SSO, WorkOS AuthKit, Auth.js, Supabase SAML, or the Cloud gateway of PermDock Cloud. A SAML assertion is never a PermDock input, and there is no permdock/saml entry (ecosystem index).

JWT validation checklistCopy Anchor Link

permdock/jwt implements the RFC 8725 checklist: keys and issuer from Discovery or explicit configuration, an explicit algorithm allow-list that never includes none, keys never chosen by the token, iss, aud, typ, exp and nbf checked, signature before claims, and every failure mapped to the anonymous subject with on('auth') reason invalid-token. If you verify tokens yourself before calling a subjectFrom* function, or plug a custom TokenVerifier in through the verifier option (extension interfaces), your verifier must follow the same list. The full checklist with its RFC mapping is on JOSE; the cause values are on the JWT adapter.

Token to delegation and sender constraintCopy Anchor Link

A token often carries authority that was delegated to the bearer, not the bearer's own authority. subjectFromJwt maps scope (RFC 6749 / RFC 8693) to delegation.scopes, authorization_details (RFC 9396) to delegation.authorizationDetails, GNAP access (RFC 9635) to delegation.access, and the RFC 8693 act claim to actor with the full nesting as delegation.chain; may_act is recorded for audit and never grants. A sender-constrained token's cnf member (jkt for DPoP, x5t#S256 for mTLS) becomes binding on the principal or, for an act chain, on the actor. The shapes and the intersection rule are on subject.

Two rules belong to verification. A token with an act claim and no scope or authorization_details yields an actor with no delegation, so every check is denied with reason no-delegation. And checking a binding needs the request, so it is an adapter concern: verifyDpopProof(request, claims) in permdock/jwt compares the DPoP proof's JWK thumbprint to cnf.jkt, the mTLS check compares the forwarded client certificate to cnf.x5t#S256, and under profile: 'fapi2' a token without cnf is rejected (FAPI 2.0).

Staleness and revocationCopy Anchor Link

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 and Back-Channel Logout. session-revoked, credential-change and assurance-level-change delivered through the Shared Signals Framework, and an OpenID Connect logout_token (typ: logout+jwt) delivered by the OP, invalidate the subject's cached snapshots immediately, matched by issuer + principal.id or by session (sid), so revocation is bounded by the identity provider rather than by a timer (SSF adapter, OpenID Connect).

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 endpointCopy Anchor Link

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 processesCopy Anchor Link

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 decisionCopy Anchor Link

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', issuer: 'https://login.example.com', kind: 'user', roles: ['editor'], tenant: 'acme' } | null,
//   actor?:    { id: 'https://agent.example/cimd.json', kind: 'oauth-client' },   // from `act`, RFC 8693
//   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.

RelatedCopy Anchor Link

• 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.
• SCIM adapter: the RFC 7644 receiver that provisions users and groups into a DirectoryStore you own and exposes them as memberships.
• 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.

SourcesCopy Anchor Link

• 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.