Skip to main content

Unified Policy

Most data platforms ship two separate authorisation systems: row-level security (RLS) on the database, expressed in a SQL-adjacent predicate language, and a different access-control language for object storage (S3-style bucket policies, IAM-style permission grants on file objects). Two languages, two evaluation engines, two places to drift out of sync — and any meaningful application that touches both surfaces has to keep them aligned manually.

Kilimanjaro's policy layer is one authoring surface. A single JSON policy compiles simultaneously to RLS on collections and access-control on storage buckets and objects. The same subject/resource binding semantics, the same operator vocabulary, the same evaluation engine. There is no second policy language. In access-control terms, a JSON policy is attribute-based access control (ABAC): rules read attributes of the caller (subject), the target (resource) and the request context. Because rules live in versioned, published policy documents rather than in application code, it is also policy-based access control (PBAC).

This guide covers the conceptual model. For the canonical rule syntax, operator vocabulary, subject and resource context fields, and worked examples, see API → Control.

1. The single authoring surface​

A unified policy is a JSON document binding rules to resources. The author writes one expression; the compiler emits enforcement code for each of the targets the rule covers.

The rule applies across resource surfaces — collections (which compile to a PostgreSQL WHERE clause that filters every query) and storage paths (which compile to an access-check at file-handle open) — using identical match semantics. The compiler resolves abstract resource attribute names to the right concrete bindings per surface, per the schema declarations the project's migrations established.

1.1 The policy bundle​

A policy is organised as one unit: the bundle, identified by pol_<base62>. A bundle is the whole project's policy document — every RLS rule, storage access rule, and IRREVERSIBLE_ACTION_GATE constraint the project declares, published and activated together. One bundle per project is active at any time; publishing a new draft is the atomic unit of change. See §7 for the full lifecycle.

1.2 Why one surface and not two​

The "two systems" approach has three failure modes:

Failure modeWhy it happens
Drift between surfacesThe team updates the RLS policy to add MFA enforcement but forgets the bucket policy, so users can still read their avatars without MFA — the policies say different things
Evaluation semantics divergenceThe SQL predicate language allows operations the storage policy language does not, or vice versa; the same intent expressed in two languages diverges subtly
Audit trail fragmentationRLS decisions log to one place, storage decisions to another; correlating "who accessed user X's data" requires joining two log surfaces

A single authoring surface eliminates all three. The drift cannot happen because there is one source of truth. The semantics cannot diverge because there is one evaluator. The audit log carries the unified policy decision, not two surface-specific decisions.

2. Subject and resource binding​

Every policy expression operates on two context objects: the subject (who is asking) and the resource (what they are asking about). The bindings are populated by the Identity-Aware Kernel (subject) and the schema layer (resource).

The subject context carries the caller's cryptographically-verified identity claims — the authenticated identity, the platform roles, group memberships, project scope, MFA claim state. These claims are not strings the caller can set freely; they are the identity Gate established at session issuance (token + step-up), propagated through the request context, and re-verified at the policy evaluation point. Forging a claim would require breaking Gate's software-verified signing chain.

The resource context carries the target of the operation — the resource identifier, type, and any schema-declared attributes (column values for collection resources, metadata for storage objects). The resource binding is established by the schema declaration: a collection's schema declares which fields are bindable as resource attributes; a storage bucket declares which path patterns and metadata keys are bindable. The compiler enforces that policy expressions only reference declared bindings.

The canonical subject and resource field schemas are documented in API → Control.

3. The operator vocabulary​

The match expression language is a focused, declarative dialect — small enough to reason about exhaustively, expressive enough to cover the common authorisation patterns. The operator vocabulary deliberately excludes general-purpose computation — no arithmetic, no string manipulation, no function calls. Policies are predicates over identity and resource state, not programs. The narrow vocabulary is what makes static analysis, audit-trail interpretation, and IRREVERSIBLE_ACTION_GATE composition tractable.

The canonical operator list and form syntax is in API → Control.

4. Policy compilation targets​

The same policy compiles to multiple enforcement points depending on the resource bindings:

TargetCompilation output
Collections (RLS)A PostgreSQL WHERE clause appended to every query against the bound collection; enforced by Postgres itself, not by application code
Storage (bucket/object ACL)An access-check evaluated at file-handle open and on every read/write/delete; enforced by the storage layer's gateway
Functions (invocation gate)A precondition checked before function dispatch; failed checks return K9O_ACCESS_DENIED without invoking the function
Real-time channels (subscription filter)A row-level filter applied to every event before delivery; subscribers see only events they would have read via direct query

The author does not need to know which target a given rule will compile to. The compiler resolves the targets from the rule's resource declarations and emits enforcement code for each.

Policy bundleone JSON policycompiler resolves targetsCollections (RLS)PostgreSQL WHERE clause on every queryStorage (bucket/object ACL)access-check at file-handle open, every read/write/deleteFunctions (invocation gate)precondition before dispatch; failed: K9O_ACCESS_DENIEDReal-time channels (subscription filter)row-level filter on every event before delivery
The author writes one policy; the compiler emits the enforcement for each target the rule's resources reach.

5. Composing with the Control pillar​

Unified policy is the foundation; the Control pillar builds higher-level authorisation patterns on top:

  • IRREVERSIBLE_ACTION_GATE — a policy family for destructive actions (custody downgrade, project deletion, key zeroize) that requires multi-party approval before the action executes.
  • Maker-Checker — multi-row write workflows where a "maker" proposes a change and a "checker" approves it before the change commits. See Guides → Maker-Checker.

Both patterns are expressed as compositions of unified-policy rules, not as separate authorisation systems. The same evaluator runs against the same context.

6. Authoring surfaces​

Policy is authored through three surfaces:

SurfaceAudience
Console policy editorPathmaker — visual rule composition with autocompletion over the schema's declared bindings
CLI / SDKArchitect — programmatic policy definition for version-controlled, code-reviewed policy management
Migration filesEngineering teams — policy declared alongside schema changes in migrations/*.k9o.yaml, version-controlled with the database schema

Policy and schema can version together — the migration file format and the schema-coupled discipline are documented in Unified Policy.

7. Policy lifecycle​

The bundle resource, identified by pol_<base62>, has a four-state machine:

StateMeaning
draftAuthored but not active; no runtime effect; freely editable.
publish-pendingPublish requested; awaiting the distinct second PROJECT_ADMIN approval Meta-Maker-Checker requires.
activeCurrently live; evaluated at runtime; immutable.
archivedWas previously active; replaced by a newer bundle, or rolled back from. Retained for audit; immutable.
draftfreely editableno runtime effectpublishpublish-pendingawaits secondPROJECT_ADMINapproveactivelive, immutableone per projectreplacedarchivedkept for audit,immutablerollback republishes archived content as a new draftPublish-time validation failure returns K9O_POLICY_BUNDLE_INVALID; the previously active bundle stays active.
A bundle only moves forward through four states; recovery is always a new draft, never an edit to history.

A project has at most one active bundle at any time. Publishing a draft moves it to publish-pending; once the second admin approves, the platform atomically marks the previously-active bundle archived and the draft active, then triggers Postgres RLS recompilation. If validation fails at publish time (a referenced column was dropped between draft creation and publish, for example), the platform returns K9O_POLICY_BUNDLE_INVALID and the previously-active bundle remains active.

Editing, deleting, or republishing an active or archived bundle returns K9O_POLICY_PUBLISH_CONFLICT — past bundles are immutable history. Bundle records are addressable by their stable pol_<base62> identifier across the lifecycle; the identifier returned at draft creation is the same identifier carried through to archived. Recovering from a bad publish is a new bundle, never an edit to history — see Architecture → Unified Policy §6.3 for rollback and the Lockdown template.

Publishing a bundle is itself a gated action: a distinct second PROJECT_ADMIN must approve the publish before it takes effect — the admin who authored the draft cannot also be the one who activates it. Recovering from a bad publish is always a new publish, never an edit to history: rollback republishes an archived bundle's content forward as a new draft, and a platform-shipped Lockdown template is the deny-all starting point when the goal is to stop evaluating a permissive policy fast. See Architecture → Unified Policy §6 for both.

8. See also​

  • API → Control — the full policy expression syntax, operator vocabulary, subject and resource schemas, gate lifecycle endpoints, and Maker-Checker approval-queue API.
  • Guides → Maker-Checker — multi-signature validation loops built on policy.
  • Unified Policy — schema-coupled policy authoring, migration discipline, and the role of policy in the request flow.
  • Security → Isolation & Privilege — how policy composes with the structural project-isolation layers.