Threat model

PermDock is an authorization library embedded in application code. It does not authenticate users, issue tokens or store data. Its threat model is therefore about one question: can a decision be wrong in the attacker's favour, or can the machinery around decisions leak or be bypassed. Everything below is a design constraint for Phase 1 and a test-suite checklist thereafter.

Assets

• Decision correctness. A granted outcome for a subject that should be denied is the primary failure.
• The policy. Roles, grants and conditions are server-only. They describe the shape of the business and often include tenant and ownership rules.
• Snapshots. Serialised grants sent to clients. They reveal what a subject may do.
• Approval tokens. A Decision.token that authorises a specific action once a human approves it.
• Audit trail. on('decision') events and OTel spans. Tampering or gaps hide abuse.
• Generated artefacts. RLS policies, OpenAPI documents and catalogs are consumed by other systems; a wrong artefact enforces the wrong thing elsewhere.

Trust boundaries

• Model to adapter. Everything a model produces (tool arguments, claimed user ids, "the user approved") is untrusted input.
• Client to server. Resource data and refresh requests from the browser are untrusted; the session or token that identifies the caller is trusted only after the application's real authentication has validated it.
• Server to core. Trusted rows from the application's own database are not re-validated (validate: 'boundary').
• Core to database. Generated where clauses and RLS are trusted by the database; they must be correct and never widen access.
• IdP to adapter. Tokens and CAEP events are trusted only after signature and issuer verification.
• Core to store and sink. The approval store and decision sink are trusted server components (the same standing as the database). They never influence a decision; a resume re-runs decide and recomputes the token before trusting a stored approved.

Invariants

1. Fail closed. No matching grant, an unknown role, a validation failure, a thrown condition, a rejected sub-policy, a network error to a PDP: all are denied. can never throws and never returns true by accident. @ai-sdk/policy-opa fails open on unrecognised decisions (vercel/ai#19978); PermDock's adapters never emit not-applicable.
2. Deny overrides allow. A deny grant in any applicable role wins over every allow. Allows OR together; denies AND against them.
3. Unknown reference is a type error. Permissions are typed references; a grant for a permission outside permissions, or a check with the wrong arity, does not compile. At runtime, a key that findPermission cannot resolve is denied.
4. Prototype-safe paths. Condition field paths and subject.* references are resolved with own-property lookups; __proto__, constructor and prototype segments are rejected at definition time and never traversed.
5. No eval. Portable conditions are data interpreted by a fixed evaluator. Closures are user code, branded non-portable, and never reconstructed from a string. Nothing in a snapshot, catalog or RLS import is executed.
6. Boundary validation. Data that crossed a trust boundary is validated against the resource's Standard Schema before a rule runs. A schema that cannot validate synchronously raises PermDockValidationError rather than skipping validation.
7. Never trust model-supplied subjects. principal, actor, delegation, memberships and the active tenant come from the adapter's verified authInfo, session, signature, or a MembershipSource / RoleSource the server owns, never from tool arguments, prompt content, request bodies or unsigned headers. A tool argument named userId or orgId is data about the resource, not the subject. There is never a default tenant: an absent or unmatched tenant means tenant-scoped grants do not apply (tenancy).
8. service_role is never emitted. RLS generation never writes policies for bypass roles and never suggests them.
9. The decision endpoint sits behind real authentication. The AuthZEN endpoint answers for the authenticated caller only. A shared "public secret" in client code (the Kilpi endpoint pattern) is obfuscation, not authentication, and is not supported as a configuration.
10. Server-only imports never reach client entries. definePolicy, createPermDock and adapters live in server entry points; permdock/react exports only snapshot consumers. Bundle tests enforce it.
11. Snapshots reveal grants, scoped snapshots limit it. A snapshot tells the client what its subject may do, including conditions. It never contains other subjects' grants, role definitions beyond names, closures (they serialise as { portable: false }) or opaque SQL. snapshot({ include: [...] }) limits a route to the features it renders.
12. Approval tokens are replay-safe. Decision.token is a hash of permission key, resource id, subject and actor. An approval for one call cannot be replayed on another. See approvals.
13. Quotas are server-side. limit grants (Phase 4) are enforced by a LimitStore the server owns, never by the client snapshot.
14. Immutable, request-scoped instances. createPermDock returns a frozen object per request; nothing mutates shared state between requests.
15. No network call to decide. can, decide, assert, filter, where, simulate and snapshot run in-process; the pdp provider is the only opt-in exception. Approval stores, decision sinks and snapshot sources are interfaces with in-process defaults; PermDock Cloud is one implementation and is never required (ADR 0021).

Threat table

Out of scope

• Authentication, login, session management and token issuance (providers and frameworks own these; PermDock consumes their result). Token verification is in scope only for the optional permdock/jwt entry and the provider adapters, never for core; see Authentication and PermDock and ADR 0018.
• Protecting the server process itself (secrets, dependency supply chain) beyond PermDock's own zero-runtime-dependency core.
• Preventing an application from calling can with the wrong permission; types reduce this, tests and the audit-permissions skill catch the rest.

Open questions

• Whether denials and alternatives in 403 bodies should be off by default in production (see Problem Details).
• The LimitStore interface and whether quotas belong in core at all.
• Whether to verify delegation chains in core or trust the token layer (see delegation).
• Whether approvals answered through a signed link (email, Slack action) without an approver session are acceptable, and how the link binds to an identity (see approvals).