# 0013: Core authorization, permission registry, and platform-owner bootstrap

- Status: Accepted
- Date: 2026-07-23

## Context

ADR 0010 and ADR 0011 established Core-owned identity and its HTTP transport but explicitly left
authorization out of scope: every account received identical baseline authenticated status, and
signup order never granted elevation. `docs/architecture/platform-architecture.md` names
permissions as a Core concern (ADR 0001), not a feature module or a surface concern, alongside
identity, database connectivity, and module lifecycle.

Phase 4C adds that missing piece in two slices on this branch. The first slice
(`feat: add core authorization foundation`) established the schema, evaluator, store, and
contracts. The second (`feat: add authorization bootstrap and HTTP enforcement`) added an explicit
platform-owner bootstrap operation, a permission registry, and HTTP enforcement wired into
`apps/api`. This ADR records the durable architectural decisions both slices established, since
together they fix a shape future changes must not casually violate: what a permission is, who can
grant one, how a platform owner is established, and how any of this reaches HTTP.

## Decision

### Core owns authorization independently of Hono, Surfaces, and modules

Authorization is a Core platform concern, exactly like identity. The schema
(`core/src/authorization/schema.ts`), evaluator (`core/src/authorization/evaluator.ts`), store
(`core/src/authorization/store.ts`), permission registry (`core/src/authorization/permissions.ts`),
and bootstrap operation (`core/src/authorization/bootstrap.ts`) import nothing from `hono`,
`apps/api`, or any module, and are independently testable without an HTTP transport. `apps/api`
consumes Core's authorization surface the same way it already consumes identity: through explicit,
injected composition (`apps/api/src/authorization-middleware.ts`,
`apps/api/src/grants-routes.ts`), never the reverse. Modules cannot import Core at all under
`scripts/check-boundaries.ts`, so this holds structurally, not just by convention.

### Permission IDs are exact, registered, and deny by default

A `PermissionId` (`@ekklesia/contracts`) is a validated, namespaced string
(`core.authorization.grants.manage`), but being well-formed is not the same as being *registered*.
`PermissionRegistry` (`core/src/authorization/permissions.ts`) is the trusted, immutable,
composition-time-built source of which permissions actually exist and what baseline each requires.
Matching is always exact string equality — there is no wildcard, prefix, or namespace-inheritance
matching anywhere in the evaluator or the store; a permission `core.authorization.grants.manage`
never implies or is implied by `core.authorization.grants.*` or `core.authorization.*`. An unknown
or malformed permission id is treated identically to a denied decision, never a distinct "this
would work if declared" response — deny-by-default holds even for permissions nobody has declared
yet.

Registration is enforced everywhere a permission id can originate from outside Core's own trusted
route wiring, not only for the caller's own required permission. `requirePermission`
(`apps/api/src/authorization-middleware.ts`) checks the registry for the permission a *route*
requires; `POST /api/v1/grants` (`apps/api/src/grants-routes.ts`) separately checks the registry
for the *target* permission a caller is requesting be granted to someone else, since that value
comes from the request body rather than route wiring. Without the second check, a caller with
`core.authorization.grants.manage` could create a stored grant for a permission id that is merely
well-formed, not registered — a dormant grant that would silently become effective the moment
that identifier was registered later, with no further action or review at registration time. Both
checks reject with the identical sanitized `403 {"code":"AUTHORIZATION_DENIED"}` an ordinary denial
would return, and neither ever calls into the store on rejection.

### Permissions declare one trusted baseline: public, authenticated, or restricted

Every registered permission declares exactly one `PermissionBaseline` at registration time. The
evaluator (`core/src/authorization/evaluator.ts`) still accepts a baseline as part of its own
request shape — that is pass 1's evaluator contract, unchanged — but the only caller allowed to
supply it in this repository is Core's own trusted registry lookup
(`requirePermission` in `apps/api/src/authorization-middleware.ts`); no HTTP route reads a baseline
from a request header, query parameter, or body. `public` always allows; `authenticated` requires a
non-anonymous principal and nothing else; `restricted` requires an authenticated principal *and*
either platform-owner authority or an active matching grant — the baseline alone never satisfies a
restricted check.

### Unknown permissions and client-supplied baselines fail closed

Two independent fail-closed layers exist on purpose, not one relied on twice, and they check
different things. The registry itself (`PermissionRegistry.get`/`.has`) returns `undefined`/`false`
for anything malformed or unregistered — this is the only layer that knows what is *registered*.
`requirePermission` treats a registry miss as an immediate sanitized `403`, before principal
resolution or evaluation ever runs; `POST /api/v1/grants` performs the equivalent registry check
for the target permission named in its body (see above). Separately, `createAuthorizationEvaluator`
independently re-validates permission *shape* — it holds no registry and cannot recognize
registration at all — denying (without throwing) any malformed or unrecognized
`permission`/`baseline`/`scope` it receives. This shape check runs, and can deny, **before any
baseline is allowed to return an allowed decision** — `public` and `authenticated` are not
exempt, even though neither reads the permission value for any other reason — so a future caller
that reaches the evaluator directly, bypassing the registry entirely (for example a different
transport Core does not yet have), inherits the same fail-closed guarantee for malformed input
rather than depending on a registry check having already run upstream. The evaluator's shape check
and the registry's registration check are deliberately not merged into one: only the registry can
answer "is this permission registered," and the evaluator must remain usable — and safe against
malformed input — by a caller that has no registry to consult at all.

### Explicit and relationship-derived grants share persistence but have distinct source kinds

`ekklesia_core_grant` is one table for both explicit grants (an administrator naming a subject
user, permission, and optional scope directly) and relationship-derived grants (a future module
operation establishing access automatically from a relationship it owns, for example a roster
assignment). A `source_kind` column, constrained to exactly `'explicit'` or `'relationship'`,
distinguishes them at the row level; nothing else about how a grant is stored or evaluated differs
by source kind. This lets both kinds share one evaluator code path and one audit trail while still
letting HTTP enforcement treat them very differently (see below).

### Unscoped grants satisfy scoped or unscoped checks; scoped grants satisfy only the exact matching scope

`AuthorizationStore.hasActiveGrant` (`core/src/authorization/store.ts`) matches a grant whose
`scope` column is `NULL` against *any* check, scoped or unscoped, but matches a grant with a
non-null `scope` only against a check requesting that exact scope string. An unscoped grant is
strictly broader than any scoped grant of the same permission; a scoped grant never leaks into an
unscoped check for the same permission. There is no partial, prefix, or hierarchical scope
matching.

### Revoked and expired grants never authorize

`hasActiveGrant`'s query requires `revoked_at IS NULL` and either no `expires_at` or
`expires_at` in the future, evaluated against an injectable clock (`now`) rather than each caller's
own wall-clock read. Revocation is soft: `AuthorizationStore.revokeGrant` sets `revoked_at` and the
revoking actor rather than deleting the row, so the audit trail and the grant's own history remain
queryable after revocation, but a revoked row can never again satisfy an authorization check.

### Platform-owner authority is represented separately from grants and is not a wildcard permission

`ekklesia_core_platform_owner` is its own table, not a synthetic all-permissions grant row.
`createAuthorizationEvaluator` checks `platformOwners.isPlatformOwner(userId)` as an independent
`OR` alongside `hasActiveGrant`, so owner status bypasses the grant/scope machinery entirely rather
than being implemented as a grant with a special scope or permission value that other code could
accidentally match against. This keeps "is a platform owner" and "has this specific permission"
structurally distinct, so a future owner-management feature can reason about the one table without
touching grant semantics.

### Platform-owner bootstrap is explicit, CLI-only, globally single-use, permanently consumed even after revocation, concurrency-safe, and audited atomically

There is no signup-order or first-user inference anywhere in this repository. The only way to
establish a platform owner is `pnpm authorization:bootstrap-owner -- --user-id <id>
--confirm-user-id <same-id>` (`core/src/cli/bootstrap-platform-owner.ts`,
`core/src/authorization/bootstrap.ts`), never an HTTP endpoint. "Bootstrap has already been
consumed" is defined as *any row ever created* in `ekklesia_core_platform_owner`, for any user,
including one whose `revoked_at` is set — there is no path in this slice that re-opens bootstrap
after a revocation; a later, separate owner-management feature (not part of this slice) is how a
platform owner would ever be re-established. The single-use check, the target user's existence
check, the owner-row insert, and its audit-row insert are one PostgreSQL transaction, serialized by
a transaction-scoped advisory lock (`pg_advisory_xact_lock`, a key pair distinct from the migration
runner's own lock) acquired as the transaction's first statement, so two concurrent bootstrap
attempts can never both observe "no owner yet" — exactly one succeeds, proven against real
PostgreSQL. Any failure path (nonexistent user, lost race, audit failure) rolls back the entire
transaction, leaving no partial owner or bootstrap state.

### Identity and Authorization use typed Drizzle views over one physical PostgreSQL pool in apps/api

`apps/api/src/database.ts`'s `createApiDatabase` constructs exactly one validated `pg.Pool`
(`core/src/database/pool.ts`) and wraps it with two independent typed Drizzle views
(`createIdentityDrizzleView`, `createAuthorizationDrizzleView`) rather than owning two pools. This
is additive: `createIdentityDrizzleDatabase` and `createAuthorizationDrizzleDatabase` (each owning
a private pool) remain available and unaffected for callers — the bootstrap CLI included — that
only need one domain and have no reason to share a connection. `apps/api` closes the one shared
pool exactly once, on graceful shutdown and on any startup failure after the pool was already
constructed.

### Cookie-authenticated authorization mutations require an exact trusted Origin

`requireTrustedOrigin` (`apps/api/src/authorization-middleware.ts`) requires an exact match against
the same trusted-origin set already used for CORS and Better Auth's own checks (ADR 0011, ADR
0012) on every grant-mutation route. This is deliberately a server-side check distinct from CORS:
CORS response headers only stop a browser from *reading* a cross-origin response, not from
*sending* the state-changing request in the first place. A missing or untrusted origin is rejected
before the permission check or any state change. Non-browser, non-cookie automation (service
accounts/API tokens) has no way to satisfy this check and is explicitly deferred, not silently
exempted.

### Generic HTTP grant management handles only explicit grants

`POST /api/v1/grants` always sets `source_kind` to `'explicit'` server-side — the request body has
no field that can influence it — and `POST /api/v1/grants/:grantId/revoke` always filters its
mutation to `source_kind = 'explicit'`. A relationship-derived grant's id, presented to the revoke
route, matches zero rows and returns the same `404` a nonexistent grant id would, indistinguishably
from the caller's perspective. The generic HTTP API also never accepts `actor`, `sourceKind`,
`sourceRef`, any audit field, a grant id, `createdAt`, or `revokedAt` in a mutation body: the
allowlist rejects the entire request if any other key is present, so a well-formed-looking request
cannot smuggle a server-derived field past validation.

### Relationship-derived grants may be created or revoked only by the trusted module operation owning that relationship

No code path in this repository creates a `source_kind = 'relationship'` grant yet — there is no
roster or similar module operation in this slice — but the architectural boundary is fixed here:
when that operation exists, it is the only trusted caller for that grant's lifecycle, exercised
through `AuthorizationStore` directly (as pass 2's own integration tests do to seed one), never
through the generic `/api/v1/grants` HTTP surface. Nothing about this ADR assumes what that future
module operation looks like — only that it does not go through the explicit-grant API.

### Deferred

Roles, groups, teams, and tenants; an owner-management HTTP endpoint (revoking or re-granting
platform-owner status over HTTP); service accounts and API tokens for non-browser automation; and
module permission discovery/registration (a mechanism for a module to contribute its own
declarations to a combined permission registry) are all deliberately out of scope for Phase 4C and
remain later work.

> **Update — see [ADR 0014](0014-module-permission-declarations-and-platform-registry.md).** Module
> permission discovery/registration, deferred above, was implemented by ADR 0014: a module manifest
> declares permissions in the same `PermissionDeclaration` shape this ADR's registry uses, and
> `apps/api` composes Core's declarations with every installed module's into the one registry every
> request is enforced against. Roles/groups/teams/tenants, owner-management HTTP, and service
> accounts/API tokens remain deferred.

## Alternatives

- Representing platform-owner status as a special grant row (a synthetic `*` permission, or a
  reserved scope value meaning "everything") was rejected: it would make "is this row an owner
  grant or a real permission grant" a runtime distinction every future grant-handling code path
  would need to remember to check, rather than a structural one enforced by table shape.
- Implementing bootstrap as "check for an existing owner, then call the same `grantPlatformOwner`
  function grants already use" was rejected: composing two separately-transacted operations leaves
  a window between the check and the grant where a concurrent caller could observe the same "no
  owner yet" state, which is exactly the race a single-use bootstrap must not allow. A dedicated,
  single-transaction operation closes that window structurally instead of relying on discipline at
  every call site.
- Allowing the generic explicit-grant HTTP API to also manage relationship-derived grants (with an
  optional `sourceKind` field in the request body) was rejected: it would let any caller holding
  `core.authorization.grants.manage` silently unwind access a module relationship established for
  reasons the generic API has no way to evaluate — for example, revoking a roster-derived grant
  without the roster module ever knowing its own invariant was violated.
- A second physical PostgreSQL pool dedicated to authorization in `apps/api` (mirroring identity's
  own private-pool factory) was rejected in favor of one shared pool: `apps/api` is one process
  with one connection budget, and two independently-sized pools would double configured connection
  limits for no isolation benefit within a single process.

## Consequences

Every HTTP route that needs authorization now goes through one reusable middleware
(`requirePermission`) backed by one trusted registry, rather than each route independently deciding
how to check a permission. Establishing a platform owner is a deliberate, auditable, one-time
operator action with no ambiguity about who holds it or how it was granted. Future work extending
authorization — module-declared permissions, relationship-derived grants, roles — has a fixed shape
to extend rather than a green field: new permissions register through the same
`createPermissionRegistry` constructor, new grant sources use the existing `source_kind` column
and audit table, and any new HTTP surface reuses `requirePermission`/`requireTrustedOrigin` rather
than reimplementing enforcement. No identity behavior, route, or response shape from ADR 0010,
0011, or 0012 changed.