Extension interfaces

Status: proposed (ADR 0024, ADR 0022) Phase: 1 (interfaces, defaults, runners), 2 to 4 (implementations)

PermDock has no plugin system (ADR 0006). What it has instead is a short list of interfaces, each with one job, one trust class and one in-process default, passed explicitly to createPermDock. A provider (Supabase, Clerk, Better Auth), a store (Postgres, Redis, PermDock Cloud), a sink (OpenTelemetry, a SIEM) or a compile target (Drizzle, MongoDB, a sync engine) implements one of them; nothing else can reach the evaluator. This page is the list. If an integration needs something not on it, that is an ADR, not a new option.

The interfaces

Two rules follow from the table. Subject inputs run once per createPermDock, before any check, and their output is frozen into the subject; they never run during can or decide, so a slow membership lookup costs one await per request, not one per button. Operational interfaces never sit in the decision path: decide returns before a sink is awaited, a store is consulted only on resume (and the resume re-runs decide), and a snapshot source distributes what the in-process instance already computed (invariant 15). permdock/cloud implements the three operational interfaces and none of the subject inputs.

Subject inputs

SubjectResolver

import type { StandardSchemaV1 } from '@standard-schema/spec'

interface SubjectResolver<TInput, TPrincipal extends Principal = Principal> {
  (input: TInput, options?: { tenant?: string }): Subject<TPrincipal> | Promise<Subject<TPrincipal>>
}

Every subjectFrom* function satisfies it, and so does the subject function you pass to definePolicy. A resolver never throws: an unverifiable token, a missing session or a failed schema check yields the anonymous subject and an on('auth') event with the reason (authentication). The optional tenant is the active tenant the server resolved from the request; the resolver compares it against the memberships it finds and sets principal.tenant only on a match (tenancy).

Typed provider principals

Each provider entry exports a base principal type and accepts a schema option, any Standard Schema, for the claims or fields it cannot know in advance:

import { subjectFromSupabase, type SupabasePrincipal } from 'permdock/supabase'
import { z } from 'zod'

const claims = z.object({ tenant_id: z.string().uuid(), user_role: z.enum(['viewer', 'admin']), plan: z.enum(['free', 'pro']) })

export const subject = subjectFromSupabase(supabase, {
  schema: claims,                                   // validated once per request; typed from InferOutput
  tenant: (c) => c.tenant_id,
  roles: (c) => [c.user_role, ...(c.plan === 'pro' ? ['pro'] : [])],
})
// typeof subject: SubjectResolver<SupabaseClient, SupabasePrincipal & z.output<typeof claims>>

Validation failure is not a throw: the principal becomes anonymous and on('auth') reports schema as the reason, the same fail-closed rule as an invalid token. The schema output type is intersected with the base type, so subject.plan in a condition is typed and a typo is a compile error. There is no declare module 'permdock' augmentation and no $Infer accessor: augmentation types values that may not exist at runtime and cannot be validated, and an inference accessor cannot see configuration TypeScript cannot link statically (ADR 0024 alternatives).

Two helper types cover the policy side: PrincipalOf<typeof policy> and SubjectOf<typeof policy> are the principal and subject types the policy's subject function produces, for use in server actions, tests and handlers without re-deriving them.

MembershipSource and RoleSource

interface MembershipSource {
  membershipsFor(principal: { id: string; kind?: string }, options: { tenant?: string }): Membership[] | Promise<Membership[]>
}

interface RoleSource {
  rolesFor(tenant: string): CustomRole[] | Promise<CustomRole[]>
  assignable?(tenant: string): string[] | Promise<string[]>
}

Both are documented with their evaluation rules on the tenancy page. They are read-only from PermDock's point of view: PermDock never creates, updates or deletes a membership or a custom role, so a source is a query, not a repository. A source that throws yields no memberships or no custom roles for that request (fewer grants, never more) and an on('auth') event; it never fails the request.

Operational interfaces

ApprovalStore, DecisionSink and SnapshotSource are defined on their own pages (approvals, audit and observability, snapshots) and summarised here for the trust rule only. LimitStore is Phase 4 and its shape is an open question on policies; it is the one operational interface whose answer (quota exhausted) produces a denied, which is why it is listed separately and why a store failure is treated as exhausted.

interface WhereCompiler<TTarget, TOptions = unknown> {
  (condition: PortableCondition, target: TTarget, options?: TOptions): unknown
}

toWhere from each query adapter is a WhereCompiler. A compiler receives the normalised JSON tree (conditions), including the memberOf node, and must return a fail-closed value (an always-false expression, { OR: [] }, eb.lit(false)) when the condition is the empty allow set. It never receives closures; permdock.where has already excluded them and set partial. A community compiler for a new target (MongoDB, a sync engine's permission language) implements this interface and runs testWhereCompiler below; it does not become a package entry without an ADR (ADR 0023).

Events

permdock.on(event, handler) registers observers on the request-scoped instance:

Handlers cannot change a Decision; they receive a frozen copy after the outcome is computed. Throwing inside a handler is caught and reported once.

Conformance runners

@permdock/testing ships one runner per interface so an implementation can prove it honours the contract before it is used:

import { testSubjectResolver, testMembershipSource, testRoleSource, testApprovalStore, testDecisionSink, testSnapshotSource, testWhereCompiler } from '@permdock/testing'

testSubjectResolver(subjectFromSupabase(client, { schema }), { valid: [session], invalid: [expiredSession, tamperedSession] })
testMembershipSource(documentMembers, { principals: [alice], expect: { alice: [{ on: { resource: 'document', id: 'd_1' }, roles: ['editor'] }] } })
testRoleSource(betterAuthRoles, { tenants: ['o_acme'], declared: policy.assignable })
testApprovalStore(postgresStore)
testWhereCompiler(toMongo, { fixtures: conditionFixtures })

The runners are what the provider adapters run in this repository's CI and what a community implementation runs in its own.

Open questions

• Whether SubjectResolver should receive the request itself (for DPoP or mTLS binding checks) or keep those in the adapter kernel that already has the request (the current design).
• LimitStore's shape and whether a store failure should deny (proposed) or fall back to unlimited (rejected on fail-closed grounds, recorded for completeness).
• Whether WhereCompiler should be a formal export of permdock or stay a type the query adapters share internally until a community compiler exists.