Unified Policy
Access control on Kilimanjaro is one declarative system, not a set of disconnected mechanisms. The same JSON-policy language governs collections (via Postgres RLS), storage (via per-object policy evaluation), gates for irreversible actions, and the Maker-Checker framework for data-write approval. In access-control terms this is attribute-based access control (ABAC) delivered as policy-based access control (PBAC): decisions come from policy rules evaluated over subject, resource and context attributes, not from role membership alone. Authoring once means the policy doesn't drift between layers; reasoning once means the audit trail tells one coherent story.
1. One primitive, every surface
A JSON-policy rule looks the same wherever it appears:
when:
or:
- eq: [subject.id, resource.ownerId]
- contains: [subject.roles, "PROJECT_ADMIN"]
The same shape governs:
- Collection RLS — compiled to Postgres
USING (...)andWITH CHECK (...)clauses at migration-apply time. Rows that fail the predicate are silently excluded fromSELECTresults; failingINSERT/UPDATE/DELETEreturnsK9O_ACCESS_DENIED(403). - Storage object access — evaluated per-object at request time by the storage service. The
resourcecontext exposes bucket, path, content-type, size, and caller-supplied metadata. IRREVERSIBLE_ACTION_GATEapprover constraints — the rules that determine which approvers may attest to a gated action (custody downgrades, project deletes, extension purges).- Maker-Checker auto-approval predicates — the policy that decides whether a proposed write commits directly or enters the approval queue.
There is no second access-control language for any of these surfaces. Engineers who learn the JSON-policy syntax once author across all four.
2. Two-layer access model
Every protected operation passes through two sequential gates:
Caller → [Layer 1: RBAC] → [Layer 2: JSON-policy ABAC] → Operation
| Layer | What it checks | Where it runs | Failure response |
|---|---|---|---|
| RBAC | Does the caller hold the minimum platform role for this endpoint? | Edge | K9O_ACCESS_DENIED (403) before any policy evaluation |
| ABAC (attribute-based, policy-driven) | Does the project's JSON-policy rule for this action permit this caller on this resource? | Origin | K9O_ACCESS_DENIED (403) for INSERT / UPDATE / DELETE; silent exclusion for SELECT |
RBAC is coarse — it operates at endpoint granularity, and platform roles (PROJECT_ADMIN, PROJECT_MEMBER, etc.) are a small closed enumeration. ABAC is fine — it operates at row granularity, references caller and resource attributes, and lets you author rules like "end-users see only their own records" or "managers may update entries in their own region" without inventing custom role names for every variation.
The two layers compose additively: RBAC passes first; ABAC is the second gate. A PROJECT_ADMIN whose JSON policy explicitly excludes them from a sensitive collection is still excluded. Coarse and fine layers reinforce rather than substitute.
3. Deny-by-default
If no policy rule grants access, access is denied. An absent rule is treated as { "rule": false }. This is the safe default — adding a new collection to a project does not silently expose it; you must explicitly author its rules.
Unknown context references (a subject.someField that doesn't exist in this caller's JWT, for example) resolve to null, and comparisons against null evaluate to false. This is fail-secure: a missing claim does not accidentally grant access.
4. Authoring paths
Policies are authored along two paths that land in the same system table:
Migration files — for engineering teams operating the schema lifecycle. Policy and schema version together inside migrations/<timestamp>_<slug>.k9o.yaml. A schema change that introduces a new collection without coupled policy emits a warning unless the migration declares noPolicy: true. The migration pipeline guarantees policy changes apply atomically with schema changes.
Console — visual policy builder for non-engineering authors (Pathmakers). The builder generates the same JSON-policy expressions that migration files declare; it commits through the same migration pipeline. There is no parallel "Console-only" policy that could drift from migration-declared state.
Both paths deduplicate on (collection, action) keys with last-write-wins resolution. A policy change in Console produces a new migration file that the next deploy applies.
5. Irreversible-action gates
Some actions are destructive in ways no policy rule can cleanly express — the action either happens or doesn't, and the consequences are hard to reverse. Kilimanjaro uses IRREVERSIBLE_ACTION_GATE for these:
| Action | Why it's gated |
|---|---|
| Project force-delete | Permanent data loss; affects every member of the project |
| Custody-mode downgrade (e.g. HYOK → BYOK) | Erodes a security guarantee; cannot be retroactively reversed for data already decrypted under the weaker mode |
| Project KEK zeroize | Crypto-shreds the project's key-encryption key, and with it every secret and encrypted record under it |
| Residency region removal | Removes a jurisdiction from the project's residency set — a zero-residue erasure of that region's data |
| K9O-CORE de-provisioning | The whole platform footprint comes down; multi-party attestation makes the act deliberate |
| Extension purge | Destroys the extension's per-project schema and all extension-owned data |
| MFA device unenrollment without replacement | A single-step rollback of an MFA factor would leave the account in a downgraded posture |
The gate flow is a configurable maker-checker chain:
- The requester creates a gate token with the action context.
- Approvers receive notifications and call the approve endpoint.
- Each approver is evaluated against the chain constraints —
not_originator,not_subject_of,distinct_from,role_required, andgroup_required. - When the required count of valid approvals lands, the token's status transitions to
approved. - The requester retries the gated action, this time carrying
X-K9O-Gate-Token: <gate-id>. - The platform verifies the token and executes the action; the token transitions to
redeemed.
Approval constraints are JSON-policy rules in the same vocabulary as RLS — the language stays one. A custody-mode downgrade is one gate per transition, whichever rungs it spans: dropping directly from HYOK to Platform-Managed is a single transition, so a single multi-party attestation, not one per rung skipped.
6. Maker-Checker
Maker-Checker is the multi-row data-write generalization of the gate primitive. Where a gate covers a single platform action, Maker-Checker covers ordinary data writes — inserts, updates, deletes on collections — behind a declarative approval policy.
The framework is built around four bindings:
- Auto-approval is the primary scale primitive. Per-row human approval at sustained 3 changes/sec is unworkable. Most writes pass an auto-approval predicate and commit directly; only the residual exception path queues for human review. Authoring a Maker-Checker policy means authoring the auto-approval predicate first.
- Read-Committed default. Pending changes are invisible to standard SDK reads, downstream extensions, workflow triggers, realtime subscriptions, and other readers. Only dedicated approval-queue surfaces and the maker's own session-aware UI see pending state.
- Bulk human approval across multiple dimensions. When human approval is needed, it can be granted in bulk — by maker session, by criteria predicate, by time window, by table scope, or via a delegation grant. The bulk surface goes through the same constraint evaluation as per-change approval; it's an efficiency primitive, not a relaxation of the rules. Delegation is non-transitive — a delegate cannot re-delegate — and can never exceed the grantor's own approval scope.
- Audit attribution by default. Every Maker-Checker-gated change emits a chain of audit events: the maker's proposal, each checker's decision, and the first-applied-write paired with the originating proposal ID. The audit log tells the complete story of who proposed, who approved, and when the change actually applied.
For data writes, approval is declared as an approval policy: a JSON predicate over the pending change, created with POST /@<projectSlug>/approval-policies. A write that matches the predicate queues for a checker; a write that does not match commits directly.
{
"collection": "refunds",
"operation": "update",
"action": "queue",
"predicate": { "gt": ["change.row.amount_cents", 100000] }
}
This says: refund updates of $1,000 or more queue for approval; smaller ones commit straight through. change.row is the request body, so on an update the predicate matches only when the update sends amount_cents. The predicate uses the same JSON operator vocabulary as RLS; a string or YAML body is refused. See API → Control §7.3.
Named rules (name, when, and either action or requires_approval_from, with optional expires_after) are authored once in a policy bundle and referenced from wherever they apply. That catalogue applies to tools, functions, secrets, streams and analytics; it is not a way to require approval for collection writes.
6.1 requires_proof — a step-up obligation, not a yes/no gate
A rule can additionally demand a fresher, stronger proof of identity before its outcome applies — independent of whether that outcome is allow or an approval requirement:
requires_proof: {
max_age: "30s", # the proof must be this fresh
min_tier: T4_HW_ATTESTED, # the assurance floor this proof must clear
single_use: true # true = the proof is consumed on use, never replayed
}
max_age takes a number followed by a unit: 30s, 5m, 1h or 1d.
min_tier draws from a total order of four assurance tiers — T1_OTP_CHANNEL (SMS/email OTP) < T2_OTP_SEED (TOTP/HOTP) < T3_KEY_POSSESSION (WebAuthn for a human, DPoP/mTLS for a workload) < T4_HW_ATTESTED (a hardware-measured TEE quote). The concrete method is resolved from the subject's own class, never named per rule — a rule states only the floor. T4_HW_ATTESTED is reachable only by a hardware-attested workload identity; declaring it against a human-subject operation is a policy authoring error, caught before the policy is ever accepted.
requires_proof composes with action or requires_approval_from; it never replaces them. A rule can allow an action outright and still demand a fresh, high-assurance proof before that allowance takes effect.
6.2 Meta-Maker-Checker — publishing a policy is itself gated
Publishing a policy change is a maker-checker action in its own right: the admin who authored the change cannot also be the one who activates it. A single PROJECT_ADMIN cannot self-publish — a distinct second PROJECT_ADMIN must approve the publish before it takes effect, server-enforced with no per-org opt-out. A solo-admin project cannot change its own policy without adding a second admin.
6.3 The incident path — rollback and the Lockdown template
A policy bundle is immutable once active; recovering from a bad publish means publishing a new one, not editing history. Two shapes cover the incident case, both through the ordinary publish pipeline — no separate reflexive "kill switch" action:
- Rollback — copy an archived bundle's content into a new draft and publish it. This is the "go back to what we know worked" path.
- The Lockdown template — a platform-shipped, deny-all starter policy document, for "get to deny-all fast" when the goal isn't to go back to a specific prior state but to stop evaluating anything permissive right now. Authored and published exactly like any other change — the same Meta-Maker-Checker gate applies.
Because both paths are ordinary publishes, the incident response inherits the same distinct-second-admin approval and the same audit trail as every other policy change — there's no separate, less-scrutinized "emergency" code path to reason about.
7. How everything composes
The three policy mechanisms layer rather than compete:
A write that fails RBAC never reaches the policy layer. A write that passes RBAC but fails the JSON-policy ABAC is rejected at the origin. A write that passes both but is governed by Maker-Checker either auto-commits (predicate evaluates true) or queues for human review. A platform action behind IRREVERSIBLE_ACTION_GATE requires both RBAC + ABAC for the underlying operation AND a redeemed gate token before the action executes.
The audit log records every layer's contribution: RBAC rejections, ABAC denials, Maker-Checker proposals + decisions + applied writes, and gate lifecycle events. A single requestId connects them so a security review can reconstruct the complete authorisation chain for any change.
See also
- Security reference — the platform role enumeration, JWT claim carriage, and audit log surface.
- Control reference — the complete JSON-policy expression syntax, gate lifecycle endpoints, and Maker-Checker approval-queue API.
- Threat model — the four-layer anti-injection posture that runs upstream of every policy evaluation.