Introduction

Aperture is a fine-grained access-control engine for the frankbardon/* family of services. It answers one question — "is this principal allowed to do this thing to this resource, and why?" — consistently across every surface that asks it.

Library-first

Aperture is library-first: the public Go packages at the module root (github.com/frankbardon/aperture) are the product. Every other surface — the aperture CLI, the Twirp/HTTP RPC API, the MCP server, and the admin UI — is a thin translator over a single decision engine. There is exactly one place a decision is made, so the answer a script gets from the CLI is the same answer a service gets over RPC and an agent gets over MCP.

The decision API

The engine exposes three operations, each available in a single and a bulk-batched form:

Explain is a first-class citizen, not a debugging afterthought: access decisions are auditable by construction.

What's inside

Aperture models principals (identity), the resource/object model (model, scope), and object providers (provider) that resolve live attributes. Decisions flow through the engine, driven by a rules layer (rules) that compiles a rule AST to an expr-lang/expr expression and evaluates it in-process — pure-Go, no external policy service. Grants come in several flavors (direct, delegation, impersonation), reads are narrowed by scoped visibility (filter), and every decision can be recorded to an audit log (audit). Persistence sits behind one Storage interface with a hand-written SQL / modernc.org/sqlite implementation and an in-memory twin.

Design tenets

• Pure-Go, CGO_ENABLED=0 end to end. No CGO, no external policy engine.
• Coded errors. Every failure is an APERTURE_* error carrying a stable code and an actionable fixup — never a bare string.
• No cross-account leakage. Decisions and error messages never expose data from an account the caller cannot see.
• One engine, many surfaces. CLI, RPC, MCP, and UI are adapters; the decision logic lives once, in the library.

Where to go next

• Getting Started — install Aperture and run your first check.
• CLI & Library — the aperture command tree and the Go embedding API.
• Service Surfaces — the Twirp/HTTP RPC API, MCP server, and admin UI.
• Concepts — identities, the object model, scopes, rules, grants, and audit.
• Reference — error codes, configuration, and the CLI/RPC surface tables.
• Operations — deployment, storage, and running the engine in production.
• Internals — architecture, package layout, and extension points.
• Contributing — conventions and the Update-Demand rule.

Getting Started

This section is the on-ramp. In four short pages you install Aperture, learn the vocabulary the rest of the book assumes, and make your first access-control decision two ways — from the command line and from Go.

Everything here runs against Aperture's embedded example model, a self-contained fixture for the tenant acme. You need nothing but the built binary; there is no store to provision and no data to load.

Read in order

1. Installation — build bin/aperture from source (Go 1.26.1, pure-Go, CGO_ENABLED=0).
2. Concepts primer — principals, actions, objects, patterns and specificity, rules, scopes, and accounts: enough to read any later chapter.
3. First decision (CLI) — a runnable aperture check walkthrough showing an allow, a default deny, and a deny-override.
4. Library quickstart — the same decision from a minimal Go program embedding the engine.

Already know what Aperture is? Skip to Installation. Want the big picture first? See the Introduction.

Installation

Aperture ships as a single, statically linked binary with no runtime dependencies. It is pure Go with CGO_ENABLED=0 end to end — there is no C toolchain, no external policy engine, and nothing to install alongside it. Build it from source and you get one file, bin/aperture, that runs anywhere the Go build targets.

Prerequisites

Build from source

Clone the repository and build the binary with the provided target:

git clone https://github.com/frankbardon/aperture.git
cd aperture
make build

make build compiles the aperture command with CGO_ENABLED=0, -trimpath, and -ldflags="-s -w", writing the result to bin/aperture. Confirm the binary works:

bin/aperture --version

aperture version <version>

Build directly with go

If you prefer not to use make, the equivalent invocation is:

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/aperture ./cmd/aperture

The cmd/aperture/main.go entrypoint is a thin adapter: it only stamps the version and hands off to the CLI command tree. All behavior lives in the library packages at the module root.

Put it on your PATH (optional)

The examples in this book invoke the binary as bin/aperture from the repository root. To run aperture from anywhere, copy the binary onto your PATH:

cp bin/aperture /usr/local/bin/aperture
aperture --version

Verify the toolchain

Aperture keeps CGO_ENABLED=0 and stays free of any CGO dependency (no geo/h3, no SQLite C bindings — the SQLite backend uses the pure-Go modernc.org/sqlite). If a build fails complaining about a C compiler, an environment variable is forcing CGO on; clear it and rebuild:

CGO_ENABLED=0 make build

Where to go next

• Concepts — the vocabulary the rest of the book assumes.
• First decision (CLI) — run aperture check against the built-in example model.
• Library quickstart — embed the decision engine in a Go program.

Concepts primer

Aperture answers one question — "is this principal allowed to do this action to this object, and why?" This page defines the vocabulary that question is built from. It is deliberately brief: enough to read any later chapter. Each term links forward to its full treatment in the Concepts section of the book.

Every example on this page is drawn from the committed example model (account acme), the same fixture the First decision (CLI) walkthrough uses.

Principal

A principal is the actor a decision is made for — a user, a service, or any other identity that can attempt an action. In the example model, alice and bob are principals. Each principal has a stable id, a kind, an identity string (such as user:alice), and a set of roles and group memberships that carry its grants. The identity package owns this model.

Action

An action is the verb being attempted — read, write, delete, share. Actions are declared per object type: a document in the example model permits read, write, delete, and share. A decision always names exactly one action.

Object

An object is the resource an action targets, named by a canonical object-identity string. Identities are hierarchical, path-like, and always rooted at an account. In the example model a document is written as:

account:acme/project:atlas/document:42

Each type:id segment narrows the path. This structure is what lets a single grant cover a whole subtree while a more specific grant overrides it for one object. The model package defines object types and identities; live object attributes are resolved by object providers (the provider package).

Identity patterns and specificity

A pattern is an object-identity with wildcards, used by a grant to cover many objects at once. ** matches any remaining path; a plain segment matches exactly. In the example model:

account:acme/project:atlas/**              # every object under project atlas
account:acme/project:atlas/document:secret # exactly one document

Specificity decides which grant wins when several match. A more specific pattern (one that matches fewer objects) outranks a broader one. That is how the example model seals a single document: a broad allow on account:acme/project:atlas/** lets engineering read everything, while a narrower deny on account:acme/project:atlas/document:secret overrides it for that one object. Deny-overrides plus specificity is the core resolution rule.

Grant

A grant binds a subject (a principal, role, or group), a permission (an object-type + action pair), and an object pattern, with an effect of allow or deny. Grants are the raw material of every decision. They come in several flavors: direct grants, time-bounded delegations (delegation), and impersonation grants that let one principal act as another (impersonation).

Rule

A rule is a conditional predicate that gates a grant on the attributes of the request — the principal, the object, or the environment. Rules are authored as an AST that Aperture compiles to an expr-lang/expr expression and evaluates in-process; there is no external policy service and no Pulse dependency. The rules package owns compilation and caching.

Scope

A scope narrows what a principal can see or act on within an account — Aperture's mechanism for row-level and subtree-level visibility. Scoped reads are narrowed by the filter package so a listing never returns objects the caller is not entitled to see. The scope package defines the scoping model.

Account

An account is the top-level tenant boundary. Every object identity is rooted at an account (account:acme/...), every grant is stamped to an account, and every decision is scoped to one active account. Accounts are hard isolation boundaries: a decision or an error message never leaks data from an account the caller cannot see. Principals join an account through a membership, which the engine can optionally enforce (a non-member is denied). Accounts are modeled as entities in the model package.

How they fit together

A Check takes an account, a principal, an action, and an object. Aperture gathers every grant whose subject includes the principal and whose pattern matches the object, evaluates any attached rules, applies deny-overrides by specificity, and returns a verdict plus a reason naming the deciding grants. The same resolution drives Enumerate (which objects a principal may act on) and Explain (the full decision trace).

Where to go next

• First decision (CLI) — see these terms resolve into a real verdict.
• Library quickstart — ask the same question from Go.
• The Concepts section of this book expands each term above into its own chapter (identities, the object model, patterns and specificity, rules, scopes, grants, and accounts).

First decision (CLI)

This walkthrough makes real access-control decisions with the aperture binary. It needs nothing beyond the build from Installation: every command below runs against Aperture's embedded example model — a self-contained fixture for the account acme — so there is no store to set up and no data to load.

The example model

When you do not pass --seed, aperture check loads the committed example fixture. It models one tenant, acme, with a project atlas full of documents, and three grants:

alice is an editor in engineering; bob is a viewer in engineering. That is enough to see an allow, a default deny, and a deny-override.

The command

aperture check <principal> <action> <object>

check takes three positional arguments and prints a one-word verdict plus a reason. The process exit code carries the verdict — 0 for allow, non-zero for deny — so a check composes in a shell pipeline (aperture check … && deploy).

Relevant flags:

The full flag reference lives in the CLI chapter later in this book; the three above are all this walkthrough needs.

Allow: engineering reads a document

alice is in engineering, and g-eng-read-atlas lets engineering read everything under atlas:

bin/aperture check alice read account:acme/project:atlas/document:42

allow
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

The command exits 0. The reason names the deciding grant and its specificity — a broad ** pattern scores low.

Allow: an editor writes

alice also holds the editor role, so g-editor-write-atlas permits a write:

bin/aperture check alice write account:acme/project:atlas/document:42

allow
reason: allowed by grant g-editor-write-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

Default deny: no grant matches

bob is only a viewer — nothing grants him write — so the decision falls through to a fail-closed default deny:

bin/aperture check bob write account:acme/project:atlas/document:42

deny
reason: default deny: no grant matched action "write" on "account:acme/project:atlas/document:42" for principal "bob" in account "acme"

The command exits non-zero. A decision with no matching grant is always a deny — Aperture fails closed.

Deny by override: specificity wins

g-deny-secret-read seals one document. Even though g-eng-read-atlas would allow the read, the deny is more specific and overrides it:

bin/aperture check alice read account:acme/project:atlas/document:secret

deny
reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

Two grants matched; the deny at specificity 60300 outranks the allow at 39300. This is deny-overrides by specificity — see the Concepts primer.

Why? — explain

check gives the verdict; explain gives the whole trace. It takes the same three arguments:

bin/aperture explain alice read account:acme/project:atlas/document:secret

Explain alice/read on account:acme/project:atlas/document:secret in account acme
  subjects: principal:alice, role:editor, group:engineering
  grants considered (3):
     g-eng-read-atlas [allow account:acme/project:atlas/**] allow covers the object via literal scope at specificity 39300
     g-editor-write-atlas [allow account:acme/project:atlas/**] action "write" does not match the requested "read"
   * g-deny-secret-read [deny account:acme/project:atlas/document:secret] deny covers the object via literal scope at specificity 60300
  verdict: DENY (top specificity 60300)
  reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

The * marks the deciding grant. explain is a first-class operation, not a debug afterthought — every decision is auditable by construction.

A note on the acting principal

For check, enumerate, and explain, the principal is a positional argument — the subject of the question. The write commands (put, bestow, revoke, impersonate, …) are different: they need to know who is acting, and take that principal from the --principal flag or the APERTURE_PRINCIPAL environment variable. For example, bestow reads the delegating principal from APERTURE_PRINCIPAL:

export APERTURE_PRINCIPAL=alice
bin/aperture bestow --help

Setting APERTURE_PRINCIPAL once in your shell saves passing the flag to every mutation. The read decisions above never consult it — they ask about a principal you name explicitly.

Where to go next

• Library quickstart — make the same decision from Go.
• Concepts primer — the vocabulary behind the verdicts.
• The CLI section of this book documents every command and flag in full.

Library quickstart

Aperture is library-first: the CLI, the RPC API, the MCP server, and the admin UI are all thin adapters over the same Go packages. This page embeds the decision engine directly and asks it the same question the First decision (CLI) walkthrough asked — this time from Go.

The pieces

A decision needs three collaborators, wired by hand (Aperture uses manual dependency injection — no wire/fx/dig):

A minimal program

Save this as main.go inside a module that requires github.com/frankbardon/aperture:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/frankbardon/aperture/engine"
	"github.com/frankbardon/aperture/seed"
	"github.com/frankbardon/aperture/service"
	"github.com/frankbardon/aperture/storage/memory"
)

func main() {
	ctx := context.Background()

	// Build an in-memory store and load the embedded example model (account "acme").
	store := memory.New()
	if err := store.Setup(ctx); err != nil {
		log.Fatal(err)
	}
	if err := seed.Load(ctx, store, seed.Example, seed.FormatYAML); err != nil {
		log.Fatal(err)
	}

	// The service facade is the single entry point every surface uses.
	svc := service.New(engine.New(store))

	res, err := svc.Check(ctx, service.Query{
		Account:   seed.ExampleAccount, // "acme"
		Principal: "alice",
		Action:    "read",
		Object:    "account:acme/project:atlas/document:42",
	})
	if err != nil {
		log.Fatalf("check failed: %v", err)
	}

	fmt.Printf("allow=%v\n", res.Allow)
	fmt.Printf("reason: %s\n", res.Reason)
	fmt.Printf("deciding grants: %v\n", res.DecidingGrantIDs)
}

Run it:

go run .

allow=true
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered
deciding grants: [g-eng-read-atlas]

That is the identical decision, reason, and deciding grant the CLI printed — because it is the same code path. There is one engine; every surface is a translator over it.

The request and result types

service.Check takes a service.Query and returns a service.Result:

type Query struct {
	Account   string // active account the decision is scoped to
	Principal string // id of the principal asking
	Action    string // the verb being attempted
	Object    string // canonical object-identity string
}

type Result struct {
	Allow            bool     // the verdict
	Reason           string   // human-readable explanation
	DecidingGrantIDs []string // grant ids that produced the verdict
}

Result never surfaces raw errors as denies inconsistently: an operational failure fails closed (Allow: false) with the cause in Reason, while a malformed request returns a non-nil error carrying an APERTURE_* code. Recover that code with errors.CodeOf from the errors package.

Errors are coded

Every failure Aperture returns across a package boundary is an APERTURE_* coded error, not a bare string. When Check returns a non-nil error — for example, a malformed object identity — inspect the code rather than the message:

import aerr "github.com/frankbardon/aperture/errors"

if err != nil {
	switch aerr.CodeOf(err) {
	case aerr.APERTURE_INVALID_INPUT:
		// the query was malformed — fix the caller
	default:
		// something operational went wrong
	}
}

Beyond Check

The facade exposes the whole read API — Enumerate (which objects a principal may act on), Explain (the full decision trace), and batch forms of each — plus, when constructed with the right options, the mutation path (entity CRUD, grants, delegation, impersonation). A read-only service.New(eng) returns APERTURE_UNIMPLEMENTED from any mutation, so a decision-only surface stays minimal.

Where to go next

• Concepts primer — the vocabulary behind Query and Result.
• The CLI & Library section of this book covers the full Go embedding API.
• The Reference section lists every APERTURE_* error code and its fixups.

CLI overview

Audience: operators and integrators driving Aperture from a shell.

aperture is the command-line face of the same decision engine the library, the RPC/HTTP server, and the MCP surface all call. Every subcommand is a thin adapter: it parses flags, hand-wires the storage → engine → service graph, makes exactly one call into the library, and maps the result to output plus an exit code. There is no CLI-only behaviour — a check from the shell resolves through the identical code path a Check RPC does.

This part of the book is the narrative CLI guide, grouped by what each command family is for. It links into the generated Command-Line Reference, which is produced from the live urfave/cli command tree and holds the authoritative, per-command flag tables. When you want the exact flags for a command, follow the link on that command's name — this guide never re-tabulates them, so the two never drift.

Command families

The embedded example model

Every command runs against a model. When you pass neither --seed nor --store, Aperture loads a committed example fixture — a self-contained model for the account acme — so the read commands below work with no setup. The fixture, its grants, and its principals are walked through in First decision (CLI). The examples in this guide use that fixture unless they say otherwise, and never reference data from any other account.

Two ways to select a model

The commonly shared options — --seed, --store, --account, and --principal — are defined per command, not as root persistent flags, and they mean the same thing everywhere they appear. They are documented once in Global options; each family page below links back to that page rather than re-explaining them.

Related

• Global options — --seed / --store / --account / --principal.
• Command-Line Reference — the generated per-command flag tables.
• First decision (CLI) — the example model, end to end.
• Library overview — the same engine, embedded in Go.

Global options

Audience: operators and integrators driving Aperture from a shell.

aperture declares no persistent global flags. The four options that recur across the command tree — --seed, --store, --account, and --principal — are defined per command, so they appear in each command's flag table in the Command-Line Reference. They carry the same meaning wherever they appear; this page is the single explanation the family pages link back to.

Selecting a model: --seed and --store

Every command resolves its model from these two options, in this order:

Use --seed to point at your own model file for a one-shot decision, and --store when you want changes to persist to disk across invocations. A store built from --store is seeded from --seed (or the embedded example) the first time it is populated.

# Decide against a model file, no persistence:
bin/aperture check alice read account:acme/project:atlas/document:42 \
  --seed ./my-model.yaml

# Persist mutations to a SQLite file so a later command sees them:
bin/aperture put grant --principal root --account acme \
  --store ./aperture.db --file ./grant.json

Scoping a decision: --account

--account names the active account a decision or mutation is scoped to. Its behaviour differs by command family:

• On the decision commands (check, enumerate, explain), --account defaults to acme (the example account) and bounds which grants the decision considers.
• On mutation, provisioning, and portability commands, --account has no default and is the active account used to resolve the acting principal's admin tier (account-admin vs system-admin). Several of those commands require it.

Aperture never lets one account's data surface in another account's decision, and error messages never leak cross-account detail.

The acting principal: --principal

This is the option most worth getting right.

On the read decision commands, the principal is a positional argument — the subject of the question you are asking:

bin/aperture check alice read account:acme/project:atlas/document:42
#                  ^^^^^ the subject principal, positional — NOT --principal

On the write / mutation commands (put, delete, bestow, revoke, impersonate, template, bulk, export, import), --principal is a flag that names the authenticated caller performing the mutation — who is acting, not who is being asked about. It is sourced from the APERTURE_PRINCIPAL environment variable, so you can set it once per shell:

export APERTURE_PRINCIPAL=root
bin/aperture put role --account acme --file ./role.json
bin/aperture delete grant g-old --account acme

A mutation with no --principal (and no APERTURE_PRINCIPAL) fails with APERTURE_UNAUTHENTICATED. A few commands name the acting principal with a purpose-specific flag instead — bestow/revoke use --delegator, and impersonate uses --operator — but each of those still reads from APERTURE_PRINCIPAL as its default source.

Related

• Command-Line Reference — every command's full flag table.
• Decisions — where the principal is positional.
• Mutations — where --principal is the acting caller.
• First decision (CLI) — the note on subject vs actor, worked through.

Decisions

Audience: operators and integrators asking and auditing access-control questions from a shell.

The decision commands are the read-only core of the CLI. They never change the model — they ask a question of it. All three of check, enumerate, and explain take the subject principal as a positional argument (the principal the question is about), not a --principal flag; see Global options for why the write commands differ. identifiers inspects an object type's source.

All four build the same decision stack aperture serve does, so a question asked in a shell resolves exactly as it does over HTTP — see Rule-backed permissions.

check — decide one question

aperture check [options] <principal> <action> <object>

check prints a one-word verdict (allow / deny) and a reason, and carries the verdict in its exit code — 0 for allow, non-zero for deny — so it composes in a pipeline (aperture check … && deploy).

bin/aperture check alice read account:acme/project:atlas/document:42

allow
reason: allowed by grant g-eng-read-atlas (allow account:acme/project:atlas/**) at specificity 39300; 1 matching grant(s) considered

A question with no matching grant is always a deny — Aperture fails closed:

bin/aperture check bob write account:acme/project:atlas/document:42

deny
reason: default deny: no grant matched action "write" on "account:acme/project:atlas/document:42" for principal "bob" in account "acme"

Full flags: check.

Rule-backed permissions decide the same here as on the server

check, enumerate, identifiers and explain build the same decision stack aperture serve does: the object metadata declared in the seed's providers: and objects: sections, the rules engine over the stored rules, and scope resolution. A permission whose scope strategy is rule-backed (inclusive;rule=… / exclusive;rule=…) is therefore evaluated identically from the shell and over HTTP.

This was not always true. Before the shared stack landed, the one-shot commands wired no rules engine, so a rule-backed permission had no evaluator, the scope resolver reported APERTURE_SCOPE_RULE_UNCONFIGURED and the fail-closed policy turned that into a deny. If you scripted against the old behaviour, those checks now return the verdict the rule implies — which may be allow.

explain — why a decision resolved

aperture explain [options] <principal> <action> <object>

explain takes the same three arguments as check and prints the whole decision trace: the subject set, every grant considered, why each did or did not apply, and the deciding grant (marked *). It is a first-class operation, not a debug afterthought.

bin/aperture explain alice read account:acme/project:atlas/document:secret

Explain alice/read on account:acme/project:atlas/document:secret in account acme
  subjects: principal:alice, role:editor, group:engineering
  grants considered (3):
     g-eng-read-atlas [allow account:acme/project:atlas/**] allow covers the object via literal scope at specificity 39300
     g-editor-write-atlas [allow account:acme/project:atlas/**] action "write" does not match the requested "read"
   * g-deny-secret-read [deny account:acme/project:atlas/document:secret] deny covers the object via literal scope at specificity 60300
  verdict: DENY (top specificity 60300)
  reason: denied by grant g-deny-secret-read (deny account:acme/project:atlas/document:secret) at specificity 60300; 2 matching grant(s) considered

When a grant's scope is decided by a rule, the trace also carries the evaluation notes that rule recorded — a metadata field read with the wrong shape, or a match that happened only because the field was absent:

  evaluation notes (1):
     g-viewer-read [rule public-documents]: object.tags: expected collection, got string

Notes are diagnostic only; they never change a verdict, and they name paths and shapes, never metadata values.

Full flags: explain.

enumerate — list objects a principal may act on

aperture enumerate [options] <principal> <action> <pattern>

enumerate turns the question around: instead of one object, it lists the object ids under a <pattern> that the principal may take <action> on, one id per line. --limit caps the result count. Enumeration expands objects from the object sources the model declares — providers: (a file- or database-backed provider per type) and objects: (metadata declared inline) — so a model with neither (like the embedded example) yields an empty list. Run enumerate against a seed that declares an object source for the type.

bin/aperture enumerate alice read 'account:acme/project:atlas/document:*' \
  --seed ./model-with-providers.yaml --limit 100

Narrowing by object metadata

--field and --fields-json filter the listing by the objects' metadata — "which of the datasets I may list carry brand Y?". They apply on top of the access decision, so they can only ever remove objects from the list; an object a check would deny is never returned however the predicate is written.

The predicate is typed: a field matches only when its value equals the wanted value and is of the same kind, so the string "5" never matches the number 5. A shell flag only carries a string, and guessing which strings are "really" numbers would make enumerate return objects check then denies — so there are two flags rather than one, and each says what it sends:

Both may be given. --fields-json is merged first and --field entries then override it by key, so a stored JSON body can be reused with one value swapped from the shell.

# a string field
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --field tier=premium

# a list field, matched by MEMBERSHIP — "datasets carrying brand Y"
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --field brands=brand:Y

# seats is a NUMBER, so it needs the JSON spelling; --field seats=5 matches nothing
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --fields-json '{"seats":5,"active":true}'

# merged: seats from JSON, tier overridden from the shell
bin/aperture enumerate alice list 'account:acme/**' --seed ./model.yaml \
  --fields-json '{"seats":5,"tier":"basic"}' --field tier=premium

The rules the listing obeys:

• Predicates are ANDed — every one must hold.
• A list-valued field matches by membership; a whole list in --fields-json is a container compared by equality.
• A field the object does not carry never matches — not even against null.
• Filtering happens before --limit. --field tier=premium --limit 10 gives the first ten premium objects, not the premium ones among the first ten candidates.

A malformed predicate is a usage error (APERTURE_INVALID_INPUT) naming the offending text — a --field with no =, an empty key, a --fields-json that is not JSON or is JSON but not an object. It is never silently skipped: a dropped predicate would widen the result, and a filter that silently widens is a filter that authorizes. Parsing happens before the store is opened, so a usage error never boots a decision stack.

Filtering needs an object source for the type, exactly as enumeration itself does. A model that declares none reports APERTURE_PROVIDER_UNREGISTERED rather than printing nothing — an empty list would read as "no access". (Because the predicate is applied per candidate, you only see that error once the principal is allowed at least one object under the pattern.)

Restricting to what a reference names

--via asks the other direction. --field asks "which datasets contain brand Y?"; --via asks "which brands does dataset X list?".

bin/aperture enumerate alice read 'account:acme/brand:*' --seed ./model.yaml \
  --via account:acme/dataset:x.current_brands

It restricts the listing to the identities held in a declared reference field on one holder object — a references: block in the seed document (Declaring a reference) is what makes the field dereferenceable.

The two are not interchangeable, and the asymmetry is the reason --via exists. The dataset holds current_brands, so a predicate on dataset expresses "which datasets contain brand Y?" — that is --field. A brand holds no field naming its datasets, so no predicate on brand can express "which brands belong to dataset X?" at all. --field is a filter; --via is a dereference.

The spelling is <holder-identity>.<field>, split on the last . — a . is legal inside an identity component (dataset:2026.q1) while a reference field is a single metadata key, so the final dot is the only unambiguous boundary. The holder's type is deliberately not spelled: it is the identity's last segment type, which the engine derives itself, so the two cannot disagree.

The rules the restriction obeys:

• Repeatable, and edges are ANDed. Two --via flags give "the brands in dataset x and in campaign spring".
• It composes with --field, and both apply before --limit.
• It only subtracts. Restriction runs on candidates that still go through the access decision, so --via can never surface an object check would deny.
• Exactly one hop. The brands a dataset names are not themselves dereferenced, however many references brand declares.

A holder you may not read prints nothing and exits 0. That is deliberate, not a bug: "you may not see dataset X" and "dataset X lists nothing you may see" must not be tellable apart, or --via becomes a way to probe for objects you were never allowed to know about. The same goes for a holder in another account — empty whether or not it exists — and for a principal who is not a member of --account.

An absent holder is APERTURE_NOT_FOUND only when it is inside --account and the principal is a member of it. That is the ergonomics a typo deserves, confined to someone already inside the account.

A wiring fault stays loud rather than printing nothing: a field with no references: declaration is APERTURE_PROVIDER_REFERENCE_INVALID, and a holder type with no provider is APERTURE_PROVIDER_UNREGISTERED. A malformed --via — no ., an empty holder, an empty field — is APERTURE_INVALID_INPUT naming the offending text, rejected before the store is opened.

If a --via returns nothing you expected, check the server log first: a referenced identity the provider no longer serves is skipped with a warning naming it, and the commonest cause is an identity composed in the wrong shape (brand:1 where the deployment yields account:acme/brand:1).

Full flags: enumerate.

identifiers — a type's valid instance ids

aperture identifiers [options] <object_type>

identifiers lists every valid instance id of an object type, read from the object source the model binds to that type — a providers: entry (a CSV file today, a data source later) or inline objects: metadata. --exclude drops ids from the result — this is how an exclusive "all except these" allowance expands into a positive allow-list. Because it needs a source, identifiers errors with APERTURE_PROVIDER_UNREGISTERED against a model that declares none, so run it against a seed that binds the type:

bin/aperture identifiers document --seed ./model-with-providers.yaml
bin/aperture identifiers document --seed ./model-with-providers.yaml --exclude secret

Full flags: identifiers.

Related

• Global options — --seed / --store / --account, and why the principal is positional here.
• First decision (CLI) — the same commands walked through against the example model.
• Mutations — change the grants these decisions read.
• Command-Line Reference — the generated flag tables.

Mutations

Audience: administrators changing the Aperture model from a shell.

The mutation commands read and change the model: generic entity CRUD (put, get, list, delete), delegation (bestow, revoke), and impersonation (impersonate). Each builds the fully-wired facade — the same storage → engine → gate → delegation → impersonation → service graph the serve command mounts — so a CLI mutation is gated exactly as the HTTP/Twirp surface gates it. There is no CLI-only write path.

Every write command needs an acting principal: the authenticated caller performing the change, taken from --principal (or APERTURE_PRINCIPAL) — not a positional argument. The reads (get, list) need no actor. See Global options for the subject-vs-actor distinction, and set it once per shell:

export APERTURE_PRINCIPAL=root

Entity bodies are the canonical JSON encoding of the corresponding model.* struct — the same shape the Twirp entity_json field carries. Supply one with --json, --file, or on stdin (in that order).

Entity CRUD: put, get, list, delete

put <kind> creates or updates one entity; the admin tier it requires depends on the kind. It prints put <kind> ok.

bin/aperture put grant --account acme --json '{
  "id": "g-analyst-read",
  "accountId": "acme",
  "subject": {"kind": "role", "id": "analyst"},
  "permissionId": "perm-doc-read",
  "object": "account:acme/project:atlas/**",
  "effect": "allow"
}'

get <kind> <id> reads one entity as pretty JSON (no actor, no tier):

bin/aperture get grant g-eng-read-atlas

{
  "ID": "g-eng-read-atlas",
  "AccountID": "acme",
  "Subject": { "Kind": "group", "ID": "engineering" },
  "PermissionID": "perm-doc-read",
  "Object": "account:acme/project:atlas/**",
  "Effect": "allow"
}

list <kind> lists entities of a kind as JSON. Listing grants requires --account (grants are per-account); the other kinds do not:

bin/aperture list principals
bin/aperture list grants --account acme

delete <kind> <id> removes one entity, gated by the kind's tier; it prints delete <kind> <id> ok. Memberships are keyed by (principal, account) rather than a single id, so delete membership takes --principal-id and --account-id instead:

bin/aperture delete grant g-analyst-read --account acme
bin/aperture delete membership --account acme \
  --principal-id bob --account-id acme

Full flags: put, get, list, delete.

Delegation: bestow and revoke

bestow lets a principal delegate a grant it already holds to another principal. Unlike put grant, it is not gated by an admin tier — it enforces the delegation subset rule: you can only bestow authority you hold, over a delegatable permission. The delegating principal is named by --delegator (env APERTURE_PRINCIPAL); the grant body is a normal grant JSON. It prints bestow <grant-id> ok.

bin/aperture bestow --delegator alice --json '{
  "id": "g-bob-read-42",
  "accountId": "acme",
  "subject": {"kind": "principal", "id": "bob"},
  "permissionId": "perm-doc-read",
  "object": "account:acme/project:atlas/document:42",
  "effect": "allow"
}'

revoke is the inverse: it removes a grant the delegator previously bestowed, by id. It prints revoke <grant-id> ok.

bin/aperture revoke --delegator alice --grant g-bob-read-42

Full flags: bestow, revoke.

Impersonation: impersonate

impersonate starts a time-boxed session in which an --operator acts as a --target within --account, and prints the session as JSON. --mode is augment (add the target's authority to the operator's — the default) or become (resolve purely as the target). It is guarded: an operator with no right covering the target is denied with APERTURE_IMPERSONATION_DENIED.

bin/aperture impersonate --operator root --target alice --account acme --mode augment

Full flags: impersonate.

Related

• Global options — --principal / --account / --seed / --store.
• Decisions — check the effect of a grant you just changed.
• Provisioning — apply many grants at once via templates or bulk.
• Portability — move a whole model between stores.
• Command-Line Reference — the generated flag tables.

Provisioning

Audience: administrators granting access at scale from a shell.

The provisioning commands turn repeated grant-making into one transactional call: template manages and applies parameterized grant bundles, and bulk applies or removes many grants atomically. Both build the same fully-wired, tier-gated facade the mutation commands use, and both need an acting principal via --principal (or APERTURE_PRINCIPAL) plus, in most cases, --account. Set the principal once:

export APERTURE_PRINCIPAL=root

template — parameterized grant bundles

aperture template <put|get|list|delete|apply>

A template is a named, versioned bundle of grants with named parameters. The subcommands split into CRUD and apply:

template apply binds --param name=value (repeatable) into the template and writes the resulting grants in one transaction; --id-prefix prefixes the generated grant ids, and --version 0 (the default) applies the latest. It prints the applied grants as JSON.

# Define a template (system-admin tier):
bin/aperture template put --account acme --file ./project-onboarding.json

# Apply it into an account, binding parameters (account-admin tier):
bin/aperture template apply --account acme \
  --name project-onboarding \
  --param project=atlas \
  --param team=engineering \
  --id-prefix onboard-

Full flags: template.

bulk — many grants in one transaction

aperture bulk <grant|revoke>

bulk grant applies a JSON array of grant bodies atomically — either all land or none do — from --json, --file, or stdin. It prints bulk grant <n> ok.

bin/aperture bulk grant --account acme --json '[
  {"id":"g-a","accountId":"acme","subject":{"kind":"role","id":"analyst"},"permissionId":"perm-doc-read","object":"account:acme/project:atlas/**","effect":"allow"},
  {"id":"g-b","accountId":"acme","subject":{"kind":"role","id":"analyst"},"permissionId":"perm-doc-write","object":"account:acme/project:atlas/document:42","effect":"allow"}
]'

bulk revoke deletes many grants atomically by id. Ids come from repeated --grant flags, positional arguments, or both; it prints bulk revoke <n> ok.

bin/aperture bulk revoke --account acme --grant g-a --grant g-b
# or positionally:
bin/aperture bulk revoke --account acme g-a g-b

Both bulk subcommands are account-admin tier.

Full flags: bulk.

Related

• Global options — --principal / --account / --seed / --store.
• Mutations — single-entity put / delete and delegation.
• Portability — export/import a whole model at once.
• Command-Line Reference — the generated flag tables.

Portability

Audience: administrators moving or backing up a whole Aperture model.

export and import are the declarative-state commands: export serializes the entire model to a single JSON/YAML state file, and import applies such a file back as an idempotent, transactional upsert. Both are system-admin tier and drive exactly the path the Twirp Export / Import RPCs drive, so they need an acting principal via --principal (or APERTURE_PRINCIPAL) and --account for authority resolution:

export APERTURE_PRINCIPAL=root

export — serialize the whole model

aperture export [options]

export writes the full model to stdout by default, or to --out <path>. The format is JSON unless you pass --format yaml (or --out a .yaml/.yml path). Writing to a file prints a one-line summary; writing to stdout emits the raw document.

# To stdout as JSON:
bin/aperture export --account acme --principal root > model.json

# To a YAML file (format inferred from the extension):
bin/aperture export --account acme --principal root --out model.yaml

exported <model summary> -> model.yaml

Full flags: export.

import — apply a state file

aperture import [options]

import reads a state file from --file <path> or, when no file is given, from stdin (treated as JSON). It applies the document as an idempotent upsert in one transaction — re-importing the same file is a no-op — and prints a one-line summary. The file format is inferred from the --file extension.

# From a file:
bin/aperture import --account acme --principal root --file model.yaml

# From stdin (JSON):
bin/aperture export --account acme --principal root \
  | bin/aperture import --account acme --principal root

imported <model summary>

Round-tripping through export | import — or between two --store DSNs — is the supported way to snapshot, back up, or migrate a model. Because both ends run as a system-admin actor scoped to --account, no cross-account data crosses the boundary implicitly.

Full flags: import.

Related

• Global options — --principal / --account / --store for the source/target store.
• Provisioning — apply incremental grants rather than a whole model.
• Mutations — single-entity edits.
• Command-Line Reference — the generated flag tables.

Attributes

Audience: operators who need to know which host directories a deployment reads principal.* and account.* out of — and how fast a revocation lands.

An attribute slot is a host directory: the user table, the service-account registry, the tenant catalogue. There are exactly three — user, machine, and account — and each caches the bags it has fetched, with its own ttl: and max_size:. See Providers for the seam itself and Seed & portability for the YAML that wires it.

aperture attributes <slots|query|invalidate>

All three read through the same wiring builder every other command uses, so the slots a listing reports are the slots a decision resolves through: the CLI cannot describe a wiring it does not itself run. All three therefore take --seed (and --store) exactly as check does.

The cache window is a security property

Object metadata going stale for a TTL is usually tolerable — a document's category is a fact about a thing. An attribute bag is the asker's standing: the clearance, the department, the plan. Until a cached bag expires, every decision about that subject keeps evaluating against access the host may have already taken away, so a revocation that takes effect ttl: later is a revocation that has not happened yet.

That is the frame for both of the interesting columns below and for the whole of invalidate: pick a slot's ttl: for how fast its revocations must land, read back what the deployment is actually running, and close the window explicitly when you cannot wait.

slots — what is wired, and how stale it may be

bin/aperture attributes slots --seed ./seed.yaml

slot     source  ttl    max-size  cached
user     sql     1m0s   10000     12
machine  csv     30s    10000     0
account  inline  never  10000     3

(An unwired slot renders as (unwired) with - in the three columns that describe a cache it does not have.)

• source is where that slot's bags come from: csv or sql (an attribute_providers: entry), inline (the attributes: block), (host) for a registry a host wired in Go rather than from the seed, and (unwired) for a slot this deployment declares no source for. An unwired slot is not an error: every decision for it resolves the floor bag and proceeds.
• ttl is the revocation window. never means a fetched bag is dropped only by eviction or by an explicit invalidate — correct for a fixed inline block, dangerous for a live directory.
• cached counts this process. A one-shot invocation starts cold and reads 0; it is the number that matters in a long-running serve.

slots needs no actor. It discloses nothing the caller did not already supply: it reads the seed file named on the command line plus the cache configuration this process built from it, contacts no provider, names no key, and prints no bag. Requiring system-admin authority to read back a file you just passed in would only mean nobody could diagnose "is the user slot even wired?" without already holding the authority the diagnosis exists to explain.

When a seed declares one slot in both attribute_providers: and attributes:, every command that builds the stack prints a warning naming the affected slots — the external entry wins and the inline bags for that slot are discarded entirely. Only slot names are named, never keys.

query — read a directory (system-admin)

bin/aperture attributes query user \
  --principal alice --account acme \
  --field department=eng --fields-json '{"clearance":3}' --limit 100

Prints a JSON array of {id, attributes}.

Unfiltered, this returns the head of the host's user table — keys and bags together — so it is a system-tier read: --principal must hold system-admin authority in --account. A refusal returns nothing: no partial page, no count, and no way to tell an empty slot from a full one or from an unwired one. That is deliberate — the authority check runs before the slot name is even parsed, so a refused caller cannot use the error to probe which directories a deployment wires. If a refusal is unexpected, ask aperture explain about your own authority.

--field and --fields-json narrow by attribute, on exactly the predicate aperture enumerate applies to object metadata: predicates are ANDed, a field the bag does not carry never matches, a list-valued field matches by membership, and everything else matches by typed equality, so the string "5" never matches the number 5. --field always sends a string; reach for --fields-json when a number, bool, or list is genuinely meant. Given both, --fields-json is merged first and --field entries override it by key.

A slot whose attribute_providers: entry declares no get_all: is fetch-only by design — it answers the decision path without exposing the whole table to an enumeration — and query reports that provider's coded refusal rather than an empty page.

invalidate — close the window now (system-admin)

bin/aperture attributes invalidate user --id alice --principal root --account acme
bin/aperture attributes invalidate user --principal root --account acme
bin/aperture attributes invalidate --all --principal root --account acme

The three forms — one subject, one slot, everything — are mutually exclusive, and a conflict is refused rather than resolved by precedence: "--all plus a slot" has two plausible readings, and guessing the broader one would clear caches the operator did not ask to clear.

"Nothing was cached" is reported, not silently succeeded (no cached user bag for "alice"): an operator invalidating a subject they believe is cached wants to know their key did not match. Note that --id takes the bare subject id — alice, never user:alice.

It is gated for the same reason query is, even though it writes nothing and discloses no bag: the result says whether this process had that key cached, which is a fact about who has recently been decided about, and clearing a large slot costs the next wave of decisions a provider round-trip each. invalidate --all names no slot, so it cannot be used to probe which exist.

Invalidation is process-local. It clears the caches of the process that runs it. That makes it exact for a host embedding Aperture, and self-contained for a one-shot CLI invocation (which starts cold and exits cold) — but it cannot reach a running aperture serve. The controls that reach that process's cache are the slot's ttl: and a restart.

Full flags: attributes.

Related

• Global options — --principal / --account / --seed / --store.
• Providers — the attribute seam, its leniency contract, and why enumerating a slot can never be scope resolution.
• Seed & portability — the attributes: and attribute_providers: blocks these commands report on.
• Rules engine — what a rule reads when a slot answers nothing.
• Command-Line Reference — the generated flag tables.

serve

Audience: operators running Aperture as a long-lived service.

aperture serve [options]

serve hand-wires the full dependency graph (storage → engine → service → HTTP handler) and boots a net/http server exposing the HTTP + Twirp API and the admin UI. It shuts down gracefully on SIGINT / SIGTERM, draining in-flight requests within a 10-second window. This is the same fully-wired facade the mutation CLI commands build — the server just puts it behind a listener and an authenticator.

bin/aperture serve --addr :8080

aperture serving on :8080

Press Ctrl-C to trigger a graceful shutdown (shutting down...).

What the flags control

• --addr — the TCP address to listen on (default :8080).
• --seed / --store — the model to serve, exactly as elsewhere (see Global options). With no --store, the server runs against an in-memory model seeded from --seed or the embedded example.
• --auth — the authenticator adapter that maps each request to a principal: dev (the default — the bearer token is the principal id, no external IdP), oidc, or parsec. It overrides the APERTURE_AUTH_MODE env var. Because the default is dev, serve runs with no external identity provider out of the box; oidc and parsec are opt-in.
• --enforce-membership — defence-in-depth: deny any decision whose principal is not a member of the active account before grants are consulted. This lets a single shared role (manager, analyst, …) be reused across accounts without one account's grants leaking to another's members. Also settable via APERTURE_ENFORCE_MEMBERSHIP.

Under serve, the facade is wired with everything the other surfaces expect: the admin gate, delegation and impersonation mutators, the append-only audit trail, the rules engine over a storage-backed rule source, and the object providers declared in the seed's providers: section. A rule saved through the admin UI takes effect on the next decision with no separate rule store.

Full flags: serve.

Related

• Global options — --seed / --store.
• mcp — the read-only stdio surface, for MCP clients rather than HTTP.
• Command-Line Reference — the generated flag table.

mcp

Audience: integrators wiring Aperture into an MCP client (an AI assistant or agent runtime).

aperture mcp [options]

mcp serves Aperture's read-only decision surface over stdio — the transport an MCP client uses when it spawns Aperture as a subprocess. It exposes the decision API (check / enumerate / explain, single and bulk), a read-only what-if simulator, and model inspection as MCP tools. No tool mutates. The command wires the facade with storage for inspection and what-if reads, but deliberately not the gate, delegation, or impersonation mutators — the surface can never write.

Because it speaks the MCP protocol over stdio, you normally don't run mcp interactively; an MCP client launches it. A minimal client configuration points at the binary and the model to serve:

{
  "mcpServers": {
    "aperture": {
      "command": "bin/aperture",
      "args": ["mcp", "--store", "./aperture.db"]
    }
  }
}

On start it prints one line to stderr (stdout is reserved for the protocol):

aperture mcp: serving read-only MCP surface over stdio

What the flags control

• --seed / --store — the model the surface reads, exactly as elsewhere (see Global options). With neither, it serves the embedded example model over an in-memory store.

There are no other flags: the surface is read-only by construction, so it needs no acting principal, account, or auth adapter.

Full flags: mcp.

Related

• Global options — --seed / --store.
• serve — the read/write HTTP + Twirp surface.
• Decisions — the same check/enumerate/explain questions from a shell.
• Command-Line Reference — the generated flag table.

Library overview

Aperture is library-first: the public Go packages at the module root are the product, and every other surface — the CLI, the RPC/HTTP API, the MCP server, and the admin UI — is a thin translator over them. This part of the book is the reference for embedding Aperture directly in a Go host program.

If you have not run the Library quickstart yet, start there: it wires a store, an engine, and the facade end to end and asks one Check. This section then documents the full decision API those pieces expose.

Two layers, one decision

A host program drives Aperture through two collaborating packages:

The engine answers the pure question; the facade is where the surface-facing policy lives (how an operational error becomes a rendered deny, when a decision is audited, how a what-if overlay is layered). A host that wants the raw PDP can call the engine; a host that is building its own surface should call the facade, so it inherits the same fail-closed contract every built-in surface has.

import (
	"github.com/frankbardon/aperture/engine"
	"github.com/frankbardon/aperture/service"
	"github.com/frankbardon/aperture/storage/memory"
)

store := memory.New()
_ = store.Setup(ctx)

eng := engine.New(store)     // the PDP
svc := service.New(eng)      // the facade every surface calls

engine.New(store, opts...) and service.New(eng, opts...) both take functional options; see Constructing the engine and The service facade for the options each exposes.

The decision API

Both layers expose the same three operations, in single and bulk-batched forms, with an impersonation-aware variant of each on the engine:

The pages that follow cover each cluster:

• Decision API — the single Check / Enumerate / Explain operations: real signatures, input and result shapes, and when to reach for each.
• Batch operations — CheckBatch / EnumerateBatch / ExplainBatch and the generic BatchResult[T] type that keeps one bad query from failing a whole batch.
• Impersonation — CheckAs / EnumerateAs / ExplainAs and the ImpersonationContext decorator that steers which subject set a decision resolves over.
• The service facade — how surfaces call the facade, its fail-closed rendering, and the read-only Simulate / SimulateExplain what-if path with a worked example.

Errors are always coded

Every failure Aperture returns across a package boundary is an APERTURE_* coded error, never a bare string. Recover the code with errors.CodeOf rather than matching on the message:

import aerr "github.com/frankbardon/aperture/errors"

if err != nil {
	switch aerr.CodeOf(err) {
	case aerr.APERTURE_INVALID_INPUT:
		// the query was malformed — a caller bug
	case aerr.APERTURE_NOT_FOUND:
		// an unknown principal, permission, or entity
	default:
		// an operational failure (storage, an unresolvable strategy, ...)
	}
}

The engine and the facade differ in how they treat these errors — the engine returns them, while the facade folds operational failures into a fail-closed deny. The distinction is spelled out per operation on the pages below and in The service facade. The full catalog lives in the Error Codes reference.

The vocabulary these operations are built from — principal, action, object, pattern, specificity, grant, account — is defined in the Concepts primer and expanded in the Concepts section of this book.

Decision API

The engine package is Aperture's Policy Decision Point. It exposes three single operations — Check, Enumerate, and Explain — on *engine.Engine. This page gives their real signatures, input and result shapes, and the rule for choosing between them. Their bulk and impersonation-aware forms live in Batch operations and Impersonation.

All three are methods on an engine you construct once and reuse. The engine is stateless beyond its storage handle and safe for concurrent use to whatever degree the underlying Storage is.

Constructing the engine

func New(store model.Storage, opts ...Option) *Engine

With no options the engine uses the literal identity-pattern coverer — a grant's object pattern is matched directly against the requested object. The options extend that behaviour:

Two further seams return a shallow copy of the engine rather than mutating it, for the read-only what-if paths: (*Engine).WithStore(store) re-points the copy at a different (e.g. overlay) store, and (*Engine).WithRuleEvaluator(re) redirects rule-backed scope strategies at a different rule evaluator. Both leave the original engine untouched, so a live engine and a transient what-if engine never interfere. The facade's Simulate path is built on exactly these.

Check

func (e *Engine) Check(ctx context.Context, req Request) (Decision, error)

Check resolves a single authorization decision: may this principal take this action on this one object, in this account?

Request

Request is a value type; every field is mandatory.

type Request struct {
	Account   string // active account the decision is scoped to
	Principal string // id of the principal requesting access
	Action    string // the verb being attempted, e.g. "read"
	Object    string // canonical object-identity string
}

Principal is a principal id (the key storage and the subject set are keyed on), not the principal's identity string. Object is a canonical object-identity string such as account:acme/project:atlas/document:42. Grants stamped to any account other than Account are never consulted (the sole exception is a grant stamped to the account wildcard *, which spans all tenancies).

Decision

type Decision struct {
	Allow            bool                  // the verdict: true permits, false denies
	Reason           string                // human-readable explanation naming the deciding grant(s)
	DecidingGrantIDs []string              // ids of the grant(s) that produced the verdict, sorted; empty on a default-deny
	Impersonation    *ImpersonationContext // non-nil only under an active impersonation session (see Impersonation)
}

Reason names the deciding grant(s), their specificity, and how many grants were considered. DecidingGrantIDs is sorted for determinism and is empty on a default-deny. Impersonation is nil on the ordinary path.

Error contract

Check never returns an allow-on-error. Any operational failure — a malformed request, an unknown principal, a storage fault — is returned as an APERTURE_* coded error and the caller treats it as a non-decision. A well-formed request that simply matches no grant is a clean default-deny (Allow: false, no error). Default-deny is the floor: with no candidate grant the answer is DENY.

dec, err := eng.Check(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	// operational failure — not a decision
	return err
}
fmt.Println(dec.Allow, dec.Reason)

Building your own surface? Prefer the facade's Service.Check, which folds operational errors into a fail-closed deny so a decision point can never fail open. The raw engine.Check here returns those errors for the facade to render.

Enumerate

func (e *Engine) Enumerate(ctx context.Context, req EnumerateRequest) ([]string, error)

Enumerate is the inverse of Check: it returns the object ids under a pattern that the principal may take the action on, in the active account. Every id it returns is one Check would allow — a denied object is never returned — so the two operations agree by construction.

EnumerateRequest

type EnumerateRequest struct {
	Account    string          // active account the enumeration is scoped to
	Principal  string          // id of the principal whose access is enumerated
	Action     string          // the verb being enumerated, e.g. "read"
	Pattern    string          // identity pattern bounding the search
	Fields     map[string]any  // optional object-metadata predicates; nil/empty filters nothing
	References []ReferenceEdge // optional reference edges; nil/empty restricts nothing
	Limit      int             // caps the number of returned ids; <= 0 means the default bound
}

Pattern both bounds the candidate set and is intersected with each grant's own scope — for example account:acme/** (everything in the account) or account:acme/document:* (every document at the account root). Limit caps the result; a non-positive Limit (or one above the default) is clamped to engine.DefaultEnumerateLimit (1000), so an enumeration can never materialise an unbounded set. Object order is deterministic (sorted by canonical id).

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/project:atlas/**",
	Limit:     100,
})

An operational failure — a storage fault, an unresolvable scope strategy, or an unconfigured object lister an implicit/exclusive grant needs — is returned as a coded error, never a silent partial set.

Filtering by object metadata

Fields is an optional set of object-metadata predicates. An allowed candidate is returned only when its metadata satisfies all of them; a nil or empty map (the default) filters nothing and never touches a metadata source, so an unfiltered enumeration costs exactly what it always did.

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/**",
	Fields:    map[string]any{"tier": "premium", "brands": "brand:Y"},
	Limit:     10,
})

The meaning is provider.Filter's Fields contract verbatim, evaluated by the same provider.MatchFields a provider's own Query calls — so an enumeration filtered here and one filtered inside a provider select the same objects. AND across keys; a collection field matches by membership; an absent field never matches, not even a nil want; and comparison is typed (int64(5) matches a float64(5) want, "5" does not match 5).

Two orderings are load-bearing:

1. Deny first. The predicate runs on candidates that already survived deny-overrides and specificity, so it can only subtract from the allowed set. A denied object is never returned, whatever the predicate says.
2. Filter before Limit. The candidate set is predicated before it is truncated, so asking for the first 10 objects tagged brand:Y searches every candidate rather than tagging the first 10 candidates and returning the few that stuck.

Metadata is read through engine.WithMetadata(fetcher), whose seam (MetadataFetcher) has the signature of *provider.Registry.Fetch — the same registry that backs the scope lister and the rule evaluator, so a candidate is served from the per-type cache the enumeration already warmed:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg))

Failure is deliberately asymmetric — an enumeration returning fewer objects reads as "no access", one returning more is an authorization bug:

• no metadata source wired, or no provider for the candidate's object-type → APERTURE_PROVIDER_UNREGISTERED, never a silently empty result. The predicate runs per candidate, so this only surfaces once the enumeration has at least one allowed candidate; an empty allowed set returns empty regardless of wiring.
• the object has no metadata row (APERTURE_NOT_FOUND from Fetch) → every field is absent, absent never matches, so the object is excluded.
• any other provider failure → returned verbatim.

EnumerateBatch and EnumerateAs carry Fields through the same path.

Restricting through a declared reference

References restricts the enumeration to the identities a holder object's declared reference field contains — "the brands in dataset X". Nil or empty (the default) restricts nothing.

ids, err := eng.Enumerate(ctx, engine.EnumerateRequest{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/brand:*",
	References: []engine.ReferenceEdge{{
		HolderID: "account:acme/dataset:x", // HolderType is optional
		Field:    "current_brands",         // must be a DECLARED reference
	}},
})

It is a dereference, not a filter, and the distinction is the whole reason it exists. Fields answers "which datasets contain brand Y?" because the dataset holds current_brands. A brand holds no field naming its datasets — references are declared on the holding side only — so no predicate on brand can express "which brands belong to dataset X?" at all.

Composition mirrors the filter's: several edges AND, an edge composes with Fields, both apply before Limit, and the restriction can only subtract from the allowed set. Exactly one hop is taken — the identities an edge yields are never themselves dereferenced. The whole restriction is resolved once per enumeration, before candidates are gathered, against the same grants and subject set the candidates are decided with; that is what makes EnumerateAs check the holder with the impersonated authority.

The failure modes are asymmetric, and the asymmetry is the security model:

Wire the source alongside the metadata source; it is the same registry:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg),
	engine.WithReferences(reg),
	engine.WithLogger(logger))

A rules-engine dereference is deliberately not supported: Check owes a p99 under a millisecond, and following a reference inside rule evaluation is a join on the decision hot path with a recursive cache-miss path behind it. Enumeration computes the restriction once, off that path.

EnumerateBatch and EnumerateAs carry References through the same path.

Explain

func (e *Engine) Explain(ctx context.Context, req Request) (Trace, error)

Explain resolves the request exactly as Check does but records the full derivation instead of only the verdict. Use it as a diagnostic — the "why" behind a verdict — not as an enforcement gate. It takes the same Request as Check.

Trace

Trace is a stable public contract: the RPC surface, the MCP inspect tool, and the what-if simulator all serialize it, so its fields are part of the API.

type Trace struct {
	Request        Request               // the question that was asked
	Subjects       []model.Subject       // the principal's expanded subject set (itself, roles, groups)
	Considered     []GrantEvaluation     // every grant loaded, each tagged with how it fared
	MaxSpecificity int                   // top specificity among covering candidates; 0 when nothing covered
	Notes          []EvaluationNote      // diagnostics rule evaluation recorded; empty when no rule ran
	Attributes     TraceAttributes       // the `principal` and `account` bags the rules read; zero when no rule ran
	Now            time.Time             // the reference instant rule evaluation resolved against; zero when no rule ran
	Decision       Decision              // the final verdict — identical to what Check returns
	Impersonation  *ImpersonationContext // non-nil only under an active impersonation session
}

Each entry in Considered is a GrantEvaluation recording one grant's contribution — its subject, permission, effect, object pattern, whether its action matched, whether it covered the object and at what specificity, which scope strategy it used, whether it was a deciding grant, and a short human-readable Outcome. A grant that failed the action match is still listed (with ActionMatched: false) so the trace shows what was ruled out.

Evaluation notes

Notes is where a rule-backed scope explains itself. A rule can decide false for a reason the verdict never shows — the metadata field it reads is the wrong shape (a string where an array was meant), or it matched only because the field is absent. Both are deny-safe by policy: a collection operator over a non-collection evaluates to false rather than raising APERTURE_RULE_EVAL, so one mistyped field cannot break every decision that touches it. See Rules.

type EvaluationNote struct {
	GrantID  string // the grant whose scope resolution recorded it
	Rule     string // the rule reference that was evaluated
	Kind     string // "shape_mismatch" | "absent_field" | "date_invalid" |
	                //   "date_bounds_inverted" | "dangling_reference" | "attributes_floor_only"
	Op       string // the comparison operator ("hasAll", …)
	Path     string // the dotted variable path ("object.tags")
	Expected string // the shape the operator requires ("collection")
	Actual   string // the shape found ("string")
	Message  string // "object.tags: expected collection, got string"
}

Six kinds are recorded today: shape_mismatch, absent_field, date_invalid, date_bounds_inverted, dangling_reference (an enumeration skipped a declared reference whose target no longer exists), and attributes_floor_only (a rule read a host-defined field off principal or account while that root carried nothing but the engine's floor, so every such comparison was false).

Three rules govern them:

1. Diagnostic only — a note never influences a verdict.
2. Explain only — Check and Enumerate install no collector, so they record nothing, allocate nothing, and behave exactly as before.
3. Shape and path only — never a metadata value, never anything that could cross an account boundary, the same discipline error messages follow.

The attribute bags

Attributes carries the principal and account roots this decision's rules were evaluated against — the host's bag with the engine's floor stamped over it, exactly as a rule read it:

type TraceAttributes struct {
	Principal map[string]any `json:"principal,omitempty"`
	Account   map[string]any `json:"account,omitempty"`
}

Both are nil on a decision that evaluated no rule, and Account is also nil for a decision made at the account wildcard "*" — that is not an account, so no bag is resolved for it and none is invented here.

This field deliberately discloses VALUES, and it is the one place a Trace does. It is not an oversight to fix, and it does not contradict rule 3 above: a note is produced by a comparison against an object's metadata, on whatever objects a wide decision happened to sweep, while these two bags are the subjects of the very question being asked — the principal in Request.Principal and the account in Request.Account. A trace that discloses them tells the asker about their own decision and nothing else.

The disclosure is also the point: "why was this denied?" is unanswerable from a grant list when the deciding comparison was principal.tier == "gold" and the operator cannot see that the tier is "silver", or absent entirely. So do not redact these into a note, and do not widen them past those two subjects. The wider-audience rule what-if preview takes the opposite side on purpose and supplies no principal or account input at all, so a rule author's editor cannot become a directory read oracle.

Trace implements String(), which renders an operator-readable, deterministic report:

tr, err := eng.Explain(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	return err
}
fmt.Print(tr.String())

tr.Decision is byte-for-byte the decision Check returns for the same request, so a surface can render a verdict and its explanation from a single Explain call. The rendered report prints each non-empty attribute root as one key-sorted line before the grants — they are the input the grants' rules were judged against — and stays byte-identical for the same decision.

When to use each

Check is the allocation-conscious hot path; reach for it in enforcement. Enumerate is the most cache-sensitive op and is deliberately bounded — use it to answer "what can they see", not as a substitute for repeated Checks on a known object. Explain does the same work as Check plus recording the derivation, so use it when a human (or a machine) needs to understand the verdict, not on every hot-path call.

Related

• Batch operations — resolve many of these in one call.
• Impersonation — the *As variants that resolve over an elevated subject set.
• The service facade — the fail-closed wrapper surfaces call.
• Concepts primer — deny-overrides, specificity, and the subject set these operations resolve over.

Batch operations

Each of the three single decision operations has a bulk form that resolves many requests in one call: CheckBatch, EnumerateBatch, and ExplainBatch. They exist so a surface — the RPC bulk RPCs, the MCP tools, the what-if simulator — can answer a list of questions in one round trip while keeping each answer isolated: one bad query never fails the whole batch.

The batch forms live on both layers with the same shape. This page shows the engine methods; the facade exposes the same three over its surface-neutral Query / EnumerateQuery types.

BatchResult[T]

Every batch op returns a slice of BatchResult[T], aligned by index with the input: result[i] is the outcome of reqs[i].

type BatchResult[T any] struct {
	Result T     // the item's answer when Err is nil; the zero value otherwise
	Err    error // the item's coded error when it failed, or nil on success
}

Exactly one of the two fields is meaningful per item. When Err is non-nil the Result is the zero value and the caller reads Err; otherwise Result holds the answer. The generic parameter is the per-op result type: Decision for CheckBatch, []string for EnumerateBatch, and Trace for ExplainBatch.

Iterate a batch by checking each item's Err before reading its Result:

for i, item := range results {
	if item.Err != nil {
		log.Printf("query %d failed: %v", i, item.Err)
		continue
	}
	use(item.Result)
}

CheckBatch

func (e *Engine) CheckBatch(ctx context.Context, reqs []Request) []BatchResult[Decision]

Resolves many Check requests, returning []BatchResult[Decision] aligned with reqs. A request that errors yields an item with Err set and a zero Decision; its siblings are unaffected. A nil reqs yields a nil result.

results := eng.CheckBatch(ctx, []engine.Request{
	{Account: "acme", Principal: "alice", Action: "read", Object: "account:acme/project:atlas/document:42"},
	{Account: "acme", Principal: "alice", Action: "write", Object: "account:acme/project:atlas/document:42"},
})
for i, item := range results {
	if item.Err != nil {
		continue // a malformed request — item.Result is the zero Decision
	}
	fmt.Printf("query %d: allow=%v\n", i, item.Result.Allow)
}

EnumerateBatch

func (e *Engine) EnumerateBatch(ctx context.Context, reqs []EnumerateRequest) []BatchResult[[]string]

Resolves many Enumerate requests, aligned with reqs — result[i] is the id list for reqs[i]. A request that errors yields an item with Err set and a nil list; the rest are unaffected.

results := eng.EnumerateBatch(ctx, []engine.EnumerateRequest{
	{Account: "acme", Principal: "alice", Action: "read", Pattern: "account:acme/project:atlas/**"},
	{Account: "acme", Principal: "alice", Action: "read", Pattern: "account:acme/project:nimbus/**"},
})

ExplainBatch

func (e *Engine) ExplainBatch(ctx context.Context, reqs []Request) []BatchResult[Trace]

Resolves many Explain requests, aligned with reqs. A request that errors yields an item with Err set and a zero Trace; the rest are unaffected.

Facade batch forms

The service facade exposes the same three over its surface-neutral query types, so a surface never touches the engine's Request type:

func (s *Service) CheckBatch(ctx context.Context, qs []Query) []engine.BatchResult[Result]
func (s *Service) EnumerateBatch(ctx context.Context, qs []EnumerateQuery) []engine.BatchResult[[]string]
func (s *Service) ExplainBatch(ctx context.Context, qs []Query) []engine.BatchResult[engine.Trace]

Note where the fail-closed contract lands. Service.CheckBatch renders each item exactly as Service.Check: an operational failure folds into a deny Result (with Err nil), while an input-validation failure sets the item's Err. So a CheckBatch item's Err is only ever a caller-bug error, never a storage fault — the storage fault already became a fail-closed deny. EnumerateBatch and ExplainBatch carry engine errors verbatim in each item's Err. See The service facade for the full rendering rules.

Like the engine forms, every facade batch method returns nil for a nil input slice.

Related

• Decision API — the single operations these batch.
• The service facade — the fail-closed rendering the facade batch forms inherit.

Impersonation

The engine exposes an impersonation-aware sibling of each decision operation: CheckAs, EnumerateAs, and ExplainAs. They resolve a decision over an effective subject set — the target's authority, borrowed by an operator — while recording the real operator for audit. They never mutate stored grants; an ImpersonationContext only steers which subject set the engine resolves over.

ImpersonationContext

The decorator that carries a session into the engine:

type ImpersonationContext struct {
	RealActor        string    // the operator's principal id (the audit identity)
	EffectiveSubject string    // the target's principal id (whose authority is used)
	Mode             Mode      // augment or become (or none, which is inert)
	ExpiresAt        time.Time // the session's hard expiry instant
}

• RealActor is the operator — the principal that truly issued the request and under whose identity audit attributes the action.
• EffectiveSubject is the target — the principal whose authority the decision borrows.
• Mode selects augment vs become (below).
• ExpiresAt is a hard time-box the engine enforces with its injected clock. A presented-but-expired context fails closed to no elevation (the operator's own authority), never to the target's.

Mode

const (
	ModeNone    Mode = ""        // no impersonation — the inert zero value
	ModeAugment Mode = "augment" // ADD the target's permissions to the operator's own
	ModeBecome  Mode = "become"  // FULLY assume the target's identity for the decision
)

• ModeAugment resolves over the union of the operator's and the target's subject sets, but the operator keeps acting under its own identity. Use it to "see what they can see" while retaining your own authority.
• ModeBecome resolves over the target's subject set alone, as if the target had asked — the operator's own grants do not apply. Become is the strictly stronger mode and is gated by a stronger right (see the impersonation package). The audit trail still records the real operator.
• ModeNone is the inert default: a zero ImpersonationContext confers no elevation, and the *As operation delegates straight to its plain sibling.

Mode.Valid() reports whether a mode is recognised (none counts as valid).

The operations

func (e *Engine) CheckAs(ctx context.Context, req Request, ic ImpersonationContext) (Decision, error)
func (e *Engine) EnumerateAs(ctx context.Context, req EnumerateRequest, ic ImpersonationContext) ([]string, error)
func (e *Engine) ExplainAs(ctx context.Context, req Request, ic ImpersonationContext) (Trace, error)

Each takes the same request its plain sibling takes, plus the ImpersonationContext. Behaviour is identical to the plain operation except for the subject set the decision resolves over.

Rules for an active session

An ImpersonationContext is active when its mode is augment or become and its ExpiresAt is still in the future (per the engine's clock). For an active session:

• The request's principal must be the operator: req.Principal == ic.RealActor. A mismatch is a caller bug and surfaces as APERTURE_INVALID_INPUT, not a deny.
• Augment resolves over operator ∪ target subjects; become resolves over the target alone.
• A rule-backed scope strategy is told about the effective subject: under become the rule's principal.id is the target's id and the target's kind picks the attribute slot principal.* is read from; under augment both are the operator's, because the operator keeps acting under its own identity. The rule and the grant set therefore always describe the same principal — see Under become, principal.* is the target.
• The operator and the target must both be members of the active account, else the decision is a fail-closed deny — cross-account impersonation is refused. (CheckAs/ExplainAs return a deny with no deciding grant; EnumerateAs returns the empty set.)
• The returned Decision / Trace carries ic on its Impersonation field for audit. In a Trace, Subjects is the effective subject set while Request.Principal remains the real operator — so a trace shows both who asked and whose authority answered.

Under become, principal.* is the target

The subject set and the rule must describe the same principal. A decision whose grants are the target's and whose rule is about the operator answers a question nobody asked, and nothing in a trace reveals it.

principal.id therefore changes meaning under become: a rule comparing principal.id == object.owner asks whether the target owns the object, which is what "as if the target had asked" means. The target's kind also picks the attribute slot, so principal.tier is read from the target's directory.

Audit is unaffected in both modes. Request.Principal is still the operator — it is what the deny reason names and what a Trace records — and Decision.Impersonation / Trace.Impersonation still carry the real actor. The rule sees whose authority answered; the audit trail sees who acted.

The change is free: the target's kind arrives with the subject-set expansion a become decision already performs, so it buys no extra storage read.

Inert sessions fail closed

When ic is inert — mode none, or an expired session — the *As operation delegates straight to its plain sibling. An expired become session therefore resolves as the operator's own authority with no elevation, never as the target's. Elevation never outlives its time-box.

ic := engine.ImpersonationContext{
	RealActor:        "alice",  // the operator issuing the request
	EffectiveSubject: "bob",    // the target whose access is borrowed
	Mode:             engine.ModeBecome,
	ExpiresAt:        time.Now().Add(15 * time.Minute),
}

dec, err := eng.CheckAs(ctx, engine.Request{
	Account:   "acme",
	Principal: "alice", // MUST equal ic.RealActor
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
}, ic)
if err != nil {
	return err
}
// dec resolves over bob's authority; dec.Impersonation records alice as the real actor.
fmt.Println(dec.Allow, dec.Impersonation.RealActor)

Carrying impersonation on the context

The engine also exposes context helpers so a middleware layer — most importantly the audit layer — can read the real actor and effective subject of any decision made while a session is set:

func WithImpersonation(ctx context.Context, ic ImpersonationContext) context.Context
func ImpersonationFromContext(ctx context.Context) (ImpersonationContext, bool)

The *As entry points set this on the context they evaluate under; a surface may also set it before calling so audit middleware wrapping the engine sees it.

Related

• Decision API — the plain operations these mirror.
• The service facade — surfaces reach impersonation through the facade's impersonation service (wired with WithImpersonation).
• The impersonation package — session issuance and the rights that gate augment vs become.

The service facade

The service package is the thin decision facade every surface calls instead of touching the engine directly — the CLI check command, the HTTP /check endpoint, the Twirp service, and the MCP read subset. It exists so those surfaces share one code path with one fail-closed policy: the rule for turning an engine error into a rendered decision lives here, not duplicated per surface.

If you are embedding Aperture to build your own surface, call the facade rather than the raw engine — you inherit its fail-closed contract, decision auditing, and the what-if Simulate path for free.

Constructing the facade

func New(eng *engine.Engine, opts ...Option) *Service

With no options a Service is read-only: it carries the decision API (Check / Enumerate / Explain and their batch forms) always, and returns APERTURE_UNIMPLEMENTED from any mutation. Options wire the additional dependencies:

The serve command builds the fully-wired facade so HTTP, Twirp, and the CLI all drive one mutation path. A decision-only surface can stay minimal with service.New(eng).

Surface-neutral query types

The facade takes Query / EnumerateQuery — surface-neutral mirrors of the engine's request types — so the CLI and HTTP layers marshal to and from these and the engine's Request stays an engine-internal concern.

type Query struct {
	Account   string
	Principal string
	Action    string
	Object    string
}

type Result struct {
	Allow            bool     // the verdict
	Reason           string   // names the deciding grants, or the fail-closed cause
	DecidingGrantIDs []string // empty on a default-deny or a fail-closed deny
}

type EnumerateQuery struct {
	Account    string
	Principal  string
	Action     string
	Pattern    string
	Fields     map[string]any // optional object-metadata predicates; nil filters nothing
	References []ReferenceEdge // optional reference edges; nil restricts nothing
	Limit      int
}

type ReferenceEdge struct {
	HolderType string // optional; empty means HolderID's terminal segment type
	HolderID   string // "account:acme/dataset:7"
	Field      string // a DECLARED reference field on the holder
}

EnumerateQuery.Fields — the object-metadata filter

Fields narrows an enumeration by object metadata: an object the principal is allowed to act on is returned only when its metadata satisfies every predicate. Nil or empty — the default — filters nothing and does not consult a metadata source at all, so existing callers are unaffected.

The facade passes the map to the engine unchanged. It parses nothing, coerces nothing, and normalises nothing, and it never rewrites the caller's map. That is deliberate: the predicate's meaning is provider.Filter's Fields contract, evaluated in exactly one place (provider.MatchFields). A surface that re-interpreted a value on the way in — parsing "5" into a number, say — would make an enumeration select objects a Check then denies.

ids, err := svc.Enumerate(ctx, service.EnumerateQuery{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/**",
	Fields:    map[string]any{"tier": "premium", "brands": "brand:Y"},
	Limit:     10,
})

The semantics a caller must know:

• AND across keys. Every predicate must hold.
• Collections match by membership. A list-valued metadata field matches when it contains the wanted value; a list-valued want is a container compared by equality.
• An absent field never matches — not even against a nil want.
• Comparison is typed. int(5) and float64(5) are one value; "5" is not 5.
• The filter runs before Limit. Candidates are decided, then filtered, then truncated — so "the first 10 objects tagged brand:Y" searches every candidate. Truncating first would return a silently wrong answer.
• The filter only subtracts. It applies to candidates that already survived deny-overrides, so no predicate can surface an object Check would deny.

Failure is asymmetric on purpose, because a short answer reads as "no access":

Wire the source alongside the scope lister — it is the same registry:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg))

Two notes for anyone refactoring this field:

• Over Twirp, Fields rides as map<string, google.protobuf.Value>, which carries every number as a double. An integer beyond 2^53 loses precision in transit and must be sent (and stored) as a string; a non-finite number (NaN, ±Inf) is rejected as APERTURE_INVALID_INPUT. See the RPC reference.
• Fields carries json and jsonschema struct tags — the only tagged field on any service type. The MCP surface aliases this struct (mcp.EnumerateIn) and reflects its tool schema off it, so the omitempty is load-bearing: without it the reflected schema marks the predicate required and an agent cannot ask an unfiltered question at all.

EnumerateQuery.References — the reference edges

References restricts an enumeration to the identities a holder object's declared reference field contains — "the brands in dataset X". Nil or empty — the default — restricts nothing.

ids, err := svc.Enumerate(ctx, service.EnumerateQuery{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Pattern:   "account:acme/brand:*",
	References: []service.ReferenceEdge{{
		HolderID: "account:acme/dataset:x",
		Field:    "current_brands",
	}},
})

It is a dereference, not a predicate, which is why it is not spelled through Fields: a brand carries no field naming its datasets, so no predicate on brand can express the question. Fields answers the mirror image ("which datasets contain brand Y?") because that side holds the field. The declaration side is Declared references.

The facade carries the edges to the engine unchanged — it does not parse a holder identity, infer a holder type, or check that a field is declared. Every one of those is a decision with a disclosure consequence, and a surface that made it separately would be a second place for the answer to differ.

• HolderType is optional. Empty means "whatever HolderID's terminal segment type is"; when given it must agree with HolderID, and the engine — not this type — enforces that.
• Several edges AND, an edge composes with Fields, and both precede Limit.
• Exactly one hop. The identities an edge yields are never themselves dereferenced.
• The restriction is computed once per enumeration, against the same grants and subject set the candidates are decided with — so EnumerateAs checks the holder with the impersonated authority, not the operator's.

The failure modes are asymmetric on purpose, and the asymmetry is the security model:

Wire the source alongside the metadata source — it is the same registry again:

eng := engine.New(store,
	engine.WithScopeResolution(nil, engine.ScopeDeps{Lister: reg, Rules: rulesEngine}),
	engine.WithMetadata(reg),
	engine.WithReferences(reg),
	engine.WithLogger(logger)) // where a dangling reference is reported

References carries the same json / jsonschema tags Fields does, for the same MCP-reflection reason: omitempty on the slice keeps the edges optional, while HolderID and Field are required properties of an edge and HolderType is not.

Fail-closed rendering

The facade's reason for existing is one shared policy for turning an engine outcome into a rendered decision:

This rule is applied per operation as follows.

Check (fail-closed)

func (s *Service) Check(ctx context.Context, q Query) (Result, error)

Check returns an error only for a genuine input-validation failure; every other engine failure folds into a fail-closed deny Result with a nil error. On a clean render the decision is audited (sampled, asynchronous, off the hot path).

res, err := svc.Check(ctx, service.Query{
	Account:   "acme",
	Principal: "alice",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	// only a malformed query reaches here (APERTURE_INVALID_INPUT / _IDENTITY_INVALID)
	return err
}
fmt.Println(res.Allow, res.Reason) // an operational failure is res.Allow == false, err == nil

Enumerate and Explain (verbatim errors)

func (s *Service) Enumerate(ctx context.Context, q EnumerateQuery) ([]string, error)
func (s *Service) Explain(ctx context.Context, q Query) (engine.Trace, error)

Enumerate and Explain return engine errors verbatim for the surface to map to a status. Enumerate cannot fail open by construction — every id it returns is one Check allows — so an operational failure is a returned error, not a silent partial set. Explain is a diagnostic, not an enforcement gate; its engine.Trace is the public contract surfaces serialize.

That trace carries Notes — six kinds today: shape_mismatch, absent_field, date_invalid, date_bounds_inverted, dangling_reference, and attributes_floor_only — and it carries Attributes, the principal and account bags the rules were evaluated against, values included. That is a deliberate disclosure and the one place a trace carries values: the two bags are the subjects of the very request being explained. Callers gate Explain accordingly.

Batch forms

CheckBatch, EnumerateBatch, and ExplainBatch return per-item engine.BatchResult[T] aligned with their queries. CheckBatch renders each item exactly as Check (operational error → deny Result; input-validation error → item Err); the other two carry engine errors verbatim per item. See Batch operations.

Simulate — what-if

The facade adds a read-only what-if surface: Simulate and SimulateExplain answer "what would the decision be if these hypothetical entities existed?" without ever persisting them. It is the seam the MCP Simulate tool and the what-if simulator UI drive.

func (s *Service) Simulate(ctx context.Context, ov Overlay, q Query) (Result, error)
func (s *Service) SimulateExplain(ctx context.Context, ov Overlay, q Query) (engine.Trace, error)

Both require the entity surface (WithStorage) so there is a base store to overlay. Simulate carries the same fail-closed contract as Check; SimulateExplain returns the trace verbatim like Explain. Nothing is written and nothing is audited — a simulation is not a real decision.

The overlay

Overlay is the set of hypothetical entities a run layers over the live model. Every field is additive and optional; an overlay entity with the same id as a stored one shadows it (so a what-if can model an edited grant or a re-roled principal), and ids absent from the overlay fall through to storage.

type Overlay struct {
	Principals  []model.Principal  // hypothetical or shadowing principals
	Groups      []model.Group      // hypothetical groups (union with stored memberships)
	Permissions []model.Permission // hypothetical or shadowing permissions
	Grants      []model.Grant      // the hypothetical grants — the common what-if input
	Memberships []model.Membership // hypothetical account memberships (consulted under enforcement)
	Rules       []model.Rule       // an unsaved rule being previewed (needs WithRuleSource)
}

The mechanism is structural, not conventional: Simulate builds a transient engine (e.WithStore(overlay) — same coverer, membership policy, and clock as the live engine, just a different read source) whose overlay store's writes are all inert. A simulation physically cannot persist through it.

Worked example: "what if I bestowed this grant?"

Suppose bob currently cannot read document:42, and you want to preview the effect of a new allow grant before bestowing it. Layer the hypothetical grant (and the permission it references, if not already stored) into an Overlay and ask SimulateExplain — the trace shows which hypothetical grant decided the verdict.

import (
	"github.com/frankbardon/aperture/model"
	"github.com/frankbardon/aperture/service"
)

ov := service.Overlay{
	Grants: []model.Grant{{
		ID:           "sim-grant-1",
		AccountID:    "acme",
		Subject:      model.Subject{Kind: model.SubjectPrincipal, ID: "bob"},
		PermissionID: "perm-doc-read",
		Effect:       model.EffectAllow,
		Object:       "account:acme/project:atlas/**",
	}},
}

tr, err := svc.SimulateExplain(ctx, ov, service.Query{
	Account:   "acme",
	Principal: "bob",
	Action:    "read",
	Object:    "account:acme/project:atlas/document:42",
})
if err != nil {
	return err
}
fmt.Print(tr.String()) // shows sim-grant-1 as the deciding grant — nothing was written

Because Simulate reuses the engine's exact resolution, a hypothetical deny overlay grant correctly carves out a stored allow, and a shadowing principal models "what if alice had role X" — all without a write.

SimulateExplain returns the same engine.Trace Explain does, attribute bags included, because it runs the live engine over an overlay store. One nuance: when the overlay carries unsaved rules, those rules are evaluated through a transient rule engine built for the overlay alone, which carries no attribute resolvers — so a previewed rule reads the floor bags (principal.{id, kind}, account.{id}) and nothing else, and earns an attributes_floor_only note if it names a host-defined field. A simulation cannot inject an attribute bag either: Overlay has no field for one.

Related what-if reads

Two adjacent reads support the rule-builder's what-if and require WithProviders:

• ObjectMetadata(ctx, objectID) (map[string]any, error) — the provider metadata a rule preview evaluates against.

• EvaluateRule(ctx, ast *rules.Node, objectID) (bool, map[string]any, error) — compiles an unsaved rule AST and evaluates it against one object's metadata, returning the boolean result and the metadata snapshot it saw.

• EvaluateRulePreview(ctx, ast *rules.Node, objectID) (RulePreview, error) — the same evaluation with the diagnostics a rule builder renders: Result, Object, Now (the reference instant, from the facade clock), Bounds (each relative-date operand and the concrete date it resolved to at Now), and Notes (the evaluation's deny-safe observations). EvaluateRule is its narrow projection.

  Unlike Check / Enumerate / Explain, this path compiles the AST directly instead of going through the decision engine, so it must supply the reference instant itself — a rules.Input with a zero Now has none, and every relative date correctly resolves to nothing.

  It also supplies no principal and no account input at all — not even the engine's floor. A rule reading principal.tier in the preview sees nothing, and no attributes_floor_only note is recorded, because there is no resolver behind it whose silence could be reported. This is the disclosure boundary of the whole preview surface: it is the wider-audience one (a rule author's editor), and handing it a principal bag would turn "evaluate this draft rule" into a read oracle for the principal directory — name a subject, compare a field, read the answer off the verdict. Explain takes the opposite side on purpose.

ObjectIdentifiers(ctx, objectType, exclude...) (also WithProviders) enumerates a type's complete instance set minus any excluded ids — the positive allow-list an exclusive allowance materialises to.

The attribute directory — a system-tier read

WithAttributes adds the one administrative door onto an attribute slot. Listing the user slot returns the host's whole user table, keys and bags together, so every method here is gated directly through authz.Gate.RequireSystemAdmin — the shape Export uses — rather than through a mutation tier. Nothing here writes, and nothing here is audited.

recs, err := svc.ListAttributes(ctx, actor, "user", provider.AttributeFilter{
	Fields: map[string]any{"department": "eng"},
	Limit:  100,
})

Three properties are contract, not implementation:

• The gate runs before the slot is parsed. A refused caller gets the identical APERTURE_AUTHZ_DENIED — nil slice, no count, no partial page — for a populated slot, an unregistered slot, and a slot name that does not exist, so a refusal cannot be used to probe which directories a deployment wires. A system-admin does get the real diagnostics.
• No gate wired means APERTURE_UNIMPLEMENTED, never "unrestricted": a bulk directory read has no narrower fallback to degrade to.
• The decision path's fetch is not gated, and must never be. A decision resolves one bag for a subject it already named, through the rules engine's resolvers — never through this option. The two paths reach the same registry through different seams.

Invalidation is a security control, not a performance knob: a slot's TTL is the window a revoked clearance keeps authorizing for, and these methods are how an operator closes it now instead of waiting it out. They clear the caches of this process only.

Related

• Decision API — the raw engine operations the facade wraps.
• Batch operations — the facade's per-item batch rendering.
• Impersonation — the engine's *As operations.
• Library quickstart — the facade wired end to end.

RPC / HTTP overview

Audience: engineers integrating a non-CLI consumer (a service, a script, or the admin UI) against a running aperture serve.

Aperture exposes its full access-control API over HTTP as a Twirp service. Twirp is a plain request/response RPC framework: every method is an HTTP POST to a fixed URL, with a JSON (or protobuf) body and a JSON (or protobuf) reply. There is no streaming, no custom verbs, and no URL-encoded parameters — just one POST per call. This makes the surface trivially reachable from curl, any HTTP client, or a generated Twirp stub.

The service facade is the one code path

Everything on the wire is a thin translation onto the service.Service facade — the same facade the CLI drives and the same one the admin UI calls. HTTP / Twirp / CLI therefore share one decision engine, one mutation path, and one auth + admin-tier policy. A handler decodes the request, calls exactly one facade method, and encodes the result; there is no business logic in the transport layer (internal/server/).

Concretely, internal/server/twirp.go implements the generated rpc.ApertureService interface, and each method body is a few lines: decode, call h.svc.<Method>(...), encode. If a behaviour is not described here, it is governed by the facade and documented under The service facade.

Transport and endpoints

The Twirp service is mounted on a net/http ServeMux in internal/server/server.go, under a fixed base path:

/twirp/aperture.ApertureService/<Method>

• Method is the RPC name exactly as it appears in the proto (Check, PutGrant, Enumerate, …).
• Content-Type selects the codec: application/json for JSON bodies (the form shown throughout these docs) or application/protobuf for the binary form. Both are the standard Twirp codecs; the JSON encoding is identical to the library's own JSON.
• HTTP status is always 200 for a successful call — including a decision of deny, which is a successful answer, not an error. Failures map an Aperture coded error onto a Twirp error code and its HTTP status (see Errors below).

Two smaller routes share the same mux for convenience:

The server is started by aperture serve, which listens on --addr (default :8080) and wraps the whole mux in the authentication middleware.

service.proto is the source of truth

The canonical, machine-readable contract is internal/wire/rpc/service.proto. It declares roughly 60 RPCs and every request/response message. The committed service.pb.go / service.twirp.go are generated from it (make proto).

The reference in the next page is hand-authored: generating a page from the proto is out of scope, so the catalog summarises each RPC's purpose and points back to the proto for exact field lists. When in doubt about a field name or a message shape, read the proto — it is authoritative. If an RPC is added to the proto and this chapter is not updated, the proto wins; treat any discrepancy as a docs bug, not a contract change.

Auth model

Authentication is applied as net/http middleware (server.Authenticate, internal/server/middleware.go), wired in front of the whole mux by the serve command. It reads a bearer credential from the Authorization header and, on success, attaches the resolved Aperture principal to the request context:

• No credential → the request proceeds anonymously (no principal in context).
• A valid credential → the resolved principal is attached and the request proceeds as that identity.
• A bad credential → the request is refused 401 with a coded error (APERTURE_INVALID_TOKEN / APERTURE_UNAUTHENTICATED). A bad token is a hard failure, never silently downgraded to anonymous.

The authenticator adapter is chosen by --auth / APERTURE_AUTH_MODE; the default dev adapter treats the bearer token as the principal id, so Aperture runs with no external IdP out of the box (oidc and parsec are opt-in). See serve.

On top of that, each RPC enforces its own requirement, owned by the Twirp handler and the facade gate:

The actor is always the authenticated principal. For any mutation, the principal a change is attributed to and authorized against is the identity the middleware resolved from the request — never a value taken from the request body. The wire Actor.account field is honoured (it selects the active account), but a caller cannot act as someone else by editing the body.

The two administrative tiers themselves are ordinary in-scheme authority (documented in authz/): SYSTEM authority is a holder of system:* (or broader); ACCOUNT authority is a holder of account:<acct>/admin:* within one account, and is confined to that account. System supersedes account for account-tier mutations.

Errors and status codes

Every failure is an APERTURE_* coded error. The handler maps the code onto a Twirp error code (and thus an HTTP status) and attaches the canonical code as meta["code"] so a client can dispatch without parsing the message:

See Error Codes for the full registry.

Why those two are 412 and not 500

Both are mapped out of the internal default on purpose, and the argument is the same in each case: nothing is broken, so nothing should page.

APERTURE_ENTITY_UNMANAGED means the deployment does not manage the entity kind the write targeted — a switch an operator set, working exactly as configured.

APERTURE_STORAGE_CONSTRAINT means the storage layer refused a write that would have broken referential integrity, overwhelmingly a delete whose children are still there: a role a principal still holds, a permission a role still bundles, an account with live memberships or grants. The caller is usually a fully privileged admin who took the teardown steps out of order. A 500 would page an on-call for a mistake the caller made and can fix, and would invite the one thing that can never work — retrying the identical request. A 400 would be closer but still wrong: the request is valid in isolation and becomes legal the moment the children are gone, so the fault is in the deployment's state, not in the message.

412 says exactly that, and the canonical code still rides in meta["code"], so a client dispatching on the code can look up the fixups — which enumerate the children to remove first. See Error Codes and the troubleshooting table.

A first call

An anonymous decision needs no credential:

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Check \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","object":"doc:42"}'

{ "allow": true, "reason": "grant g-123 allows read", "deciding_grant_ids": ["g-123"] }

A mutation needs a bearer token that resolves to a principal with the required tier — here, a system-admin creating an object type:

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/PutObjectType \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer root' \
  -d '{"actor":{"account":"acme"},"entity_json":"{\"ID\":\"doc\",\"Actions\":[\"read\",\"write\"]}"}'

{}

Related

• RPC reference — the endpoint catalog by area.
• The service facade — the single code path every surface shares.
• serve — running the server; --addr, --auth, --store.
• Error Codes — the APERTURE_* registry.

RPC reference

Audience: engineers wiring specific calls against aperture serve.

This is a hand-authored catalog of the ApertureService RPCs, grouped by area. It summarises each method's purpose, its request/response messages, and its auth requirement. The canonical, exact field lists live in internal/wire/rpc/service.proto — read it for message shapes; this page is maintained by hand and may lag the proto (the proto wins on any discrepancy).

Every method is a POST to /twirp/aperture.ApertureService/<Method> with a JSON body. See the overview for transport, auth, and error mapping. Auth shorthand used below:

• open — no authenticated principal required.
• auth — requires an authenticated principal.
• system — requires system-admin authority (system:*).
• account — requires account-admin authority in the target account (system supersedes).
• own rule — not gated by the admin tiers; carries its own delegation / impersonation authorization.

Wire-shape convention

Simple hot-path messages (Check, Enumerate) carry their fields directly. Rich or recursive shapes — the model entities with their timestamps, the Explain trace, the rule AST — ride as a canonical JSON string in a *_json field rather than being modelled in proto. That JSON is identical to the library's own encoding of the corresponding model.* struct. So an EntityRequest.entity_json is just the JSON of a model.ObjectType, model.Grant, etc., and an EntityResponse.entity_json is the same on the way back.

Mutations carry an Actor { principal, account }. On the wire the principal is ignored — the authenticated identity from the middleware is always used — while account selects the active account. Reads that are account-scoped resolve their authority from the authenticated principal directly.

Decision RPCs (open)

The core decision API, single and bulk. These are open (no principal required) and always answer fail-closed.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"doc:*","limit":50}'

{ "object_ids": ["doc:42", "doc:77"] }

EnumerateRequest.fields — the object-metadata filter

EnumerateRequest carries an optional fields map (field 6, map<string, google.protobuf.Value>) that narrows the result by object metadata. Omitting it filters nothing, so an existing client is unaffected.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"account:acme/**",
       "fields":{"tier":"premium","seats":5,"brands":"brand:Y"},"limit":50}'

Semantics — the same contract a provider's own Filter.Fields obeys, evaluated by the same code, so a filtered enumeration and a provider-side query select the same objects:

Why Value and not a JSON string. The predicate compares by type, so the string/number/bool/list distinction has to be visible in the schema — a JSON blob in a string field would be opaque to every generated client and unvalidatable at the boundary. Each Value kind maps to exactly one shape, recursively, with no coercion between kinds: null→absent-ish nil, number→float64, string→string, bool→bool, list→array, struct→object.

Caveat: integers beyond 2^53. google.protobuf.Value carries every number as a double, so an integer larger than 2^53 loses precision in transit. Send such a key as a string and store it as a string in metadata. Nothing in the conversion can repair the loss — it is a property of Value itself. (internal/wire/rpc's TestFieldsRoundTrip_LargeIntegerLosesPrecision pins this, and fails loudly if it ever stops holding.)

Rejections are APERTURE_INVALID_INPUT / 400, never a dropped predicate — a dropped predicate widens the result, and a filter that silently widens is a filter that authorizes:

• a non-finite number (NaN, ±Inf). It would otherwise become the string "NaN", an unsatisfiable predicate that reads as "no access". Note protojson cannot marshal a non-finite Value at all, so only the binary codec can reach this guard;
• a Value with no kind set (unreachable from a generated client, reachable from a hand-rolled one).

In EnumerateBatch a malformed predicate fails only its own item — that item carries the error code/message and never an empty object_ids, and the rest of the batch runs.

Wiring: the server must have an object-metadata source (the same provider registry that backs object listing). Filtering a type with no registered provider, or with no source configured at all, is APERTURE_PROVIDER_UNREGISTERED / 404 rather than an empty list — an empty list would read as "no access" and hide the misconfiguration. Because the predicate runs per candidate, that error only appears when the enumeration has at least one allowed candidate. An object the provider has no row for is simply excluded (every field absent, and absent never matches).

EnumerateRequest.references — the reference edges

EnumerateRequest also carries an optional references list (field 7, repeated ReferenceEdge) that restricts the result to the identities a holder object's declared reference field contains — "the brands in dataset X". Omitting it restricts nothing, so an existing client is unaffected. EnumerateBatchRequest embeds EnumerateRequest, so edges ride per query.

message ReferenceEdge {
  string holder_type = 1;  // OPTIONAL; empty means holder_id's terminal segment type
  string holder_id   = 2;  // required — "account:acme/dataset:7"
  string field       = 3;  // required — a DECLARED reference field
}

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/Enumerate \
  -H 'Content-Type: application/json' \
  -d '{"account":"acme","principal":"alice","action":"read","pattern":"account:acme/brand:*",
       "references":[{"holder_id":"account:acme/dataset:x","field":"current_brands"}]}'

It is a dereference, not a filter, and the two are not interchangeable. fields answers "which datasets contain brand Y?" — the dataset holds the field, so a predicate on dataset expresses it. references answers the mirror image, "which brands belong to dataset X?" — a brand holds no field naming its datasets (references are declared on the holding side only), so no predicate on brand can express it at all.

The security semantics are the point, and they are asserted over a real JSON round trip — a boundary that turned an empty result into a 404, or a 404 into an empty list, would silently change what the server discloses about objects it never let the caller see:

APERTURE_PROVIDER_REFERENCE_INVALID is a 400, not the 500 the default mapping would give it: the only way a client reaches it is an edge naming an undeclared field — its own input, which no retry can fix — and 5xx is the one class a client is entitled to retry and an alert rule is entitled to page on. The Aperture code is in meta["code"] either way.

In EnumerateBatch each item keeps its own answer: one query's 404 never becomes another's, and a fail-closed empty result is reported as an empty list rather than an error.

See Object references for the declaration side, and the CLI's --via for the same query from a terminal.

Entity CRUD

Full create/read/list/delete for each model entity. The write body is entity_json (a model.* struct as JSON); reads return entity_json (single) or entities_json (list). List RPCs accept an optional server-side Filter (field predicates ANDed or ORed) applied before the response is returned.

Writes are system-tier (managing the global schema); reads require auth.

¹ ListPrincipals and ListAccounts resolve read visibility against the caller's admin authority, so an account-admin sees only what their tier permits.

Requests: PutX uses EntityRequest { actor, entity_json }; GetX/DeleteX use GetRequest/DeleteRequest { actor, id }; ListX uses ListRequest { filter }. Responses: EntityResponse / EntityListResponse / Empty.

ObjectIdentifiers (ObjectIdentifiersRequest → ObjectIdentifiersResponse, auth) enumerates every instance id of an object type from its provider, optionally minus an exclude list — an admin/config read over all objects of a type.

curl -s -X POST http://localhost:8080/twirp/aperture.ApertureService/PutGrant \
  -H 'Content-Type: application/json' -H 'Authorization: Bearer acme-admin' \
  -d '{"actor":{"account":"acme"},"entity_json":"{\"ID\":\"g-1\",\"Account\":\"acme\",\"Principal\":\"alice\",\"Action\":\"read\",\"Object\":\"doc:*\",\"Effect\":\"allow\"}"}'

Grants and memberships (account-tier)

Grants and memberships are account-scoped: writes require account-admin in the target account; reads resolve against the caller's authority.

Rules (definition writes system; reads auth)

Rules are global schema: named, persisted rule-AST definitions the node editor authors and the rule-backed scope strategies resolve. The AST rides as a model.Rule JSON in rule_json.

What-if / simulation (auth)

Read-only previews. Nothing is written and nothing is audited.

Templates

Reusable grant bundles. Definition writes are system-tier; apply is account-tier (it materialises grants into a target account).

Bulk grant / revoke (account-tier)

Transactional multi-grant mutations, both account-tier.

Declarative state (system-tier)

Whole-model portability.

Audit query (gated read)

Delegation (own rule)

Not admin-gated; authorized by the delegation subset rule, with the actor = the authenticated delegator.

Impersonation (own rule)

Not admin-gated; authorized by the impersonation guardrails, with the actor = the authenticated operator. Sessions are stateless, time-boxed values.

Related

• RPC / HTTP overview — transport, auth model, error mapping.
• service.proto — the canonical contract.
• The service facade — the shared code path.
• Error Codes — the APERTURE_* registry.

MCP surface

Audience: authors integrating Aperture into an MCP client (an AI assistant or agent runtime) as a tool provider.

Aperture exposes its decision API and model inspection as Model Context Protocol tools. An MCP client spawns aperture mcp as a subprocess, speaks MCP over stdio, and calls the Aperture tools the same way it calls any other tool server.

Read-only by construction

The MCP surface is read-only. Every tool calls a read or decision method on the single service.Service facade — Check / Enumerate / Explain, the what-if Simulate, and the Get* / List* inspectors. No tool mutates. No tool name carries a mutating verb (put / create / add / set / delete / remove / update / write / bestow / revoke / grant / …), and a test (mcp.TestNoMutatingTool, mirrored at the wire level in the adapter) fails if one ever does. The aperture mcp command deliberately wires the facade with storage for inspection and what-if reads but not the gate, delegation, or impersonation mutators, so the surface cannot write even by accident.

Everything on the surface is a thin translation onto the same facade the CLI and the HTTP/Twirp surface drive — one decision engine, one code path. If a behaviour is not described here it is governed by the facade and documented under The service facade.

The tool catalog

The catalog is stable and ordered. Tool names are aperture_-prefixed, snake_cased, and defined once in mcp/toolmeta (the single source of truth for tool identity), so the SDK-free core and the SDK adapter never drift.

Decision API (single + bulk)

What a trace discloses about attributes

ExplainOut — and SimulateOut — are type aliases for engine.Trace, so every one of these tools serializes the trace verbatim. That includes its Attributes field: the principal and account bags the decision's rules were evaluated against, values included.

That is a deliberate disclosure, and it reached this surface with no mcp/ code change at all — which is exactly why it is written down here. The two bags are the subjects of the very request being explained (the principal and account named in the query), so a trace tells the asker about their own decision and nothing else; see the attribute bags. Gate the MCP surface accordingly: an agent that may call aperture_explain on an arbitrary (account, principal) pair can read that principal's attribute bag for that account.

There is deliberately no attribute tool. Listing a slot returns the host's whole user table, and MCP is where an agent doing that is least defensible, so the directory read stays a system-tier CLI operation (aperture attributes) and never becomes a tool.

aperture_enumerate's Fields filter

Fields is an optional object of metadata predicates that narrows the listing — "which of the datasets alice may list carry brand Y?". Omit it to filter nothing; it is not a required property, so an unfiltered enumerate is a valid call for a schema-validating client.

{
  "Account": "acme", "Principal": "alice", "Action": "list",
  "Pattern": "account:acme/**",
  "Fields": { "tier": "premium", "seats": 5, "brands": "brand:Y" }
}

The predicates are ANDed; a field the object does not carry never matches; a list-valued field matches by membership; everything else is typed equality, so "5" never matches 5. The filter runs on objects the principal is already allowed — it can only remove ids, never add one — and it is applied before Limit, so Limit: 10 returns the first ten matches.

The schema is reflected straight off service.EnumerateQuery, so the tool input and the Go facade query are the same type; the semantics above are carried in the property description an agent reads.

aperture_enumerate's References edges

References is an optional list of reference edges that restricts the listing to the identities a holder object's declared reference field contains — "which brands belong to dataset X?". Omit it to restrict nothing; like Fields, it is not a required property.

{
  "Account": "acme", "Principal": "alice", "Action": "read",
  "Pattern": "account:acme/brand:*",
  "References": [{ "HolderID": "account:acme/dataset:x", "Field": "current_brands" }]
}

HolderID and Field are required properties of an edge; HolderType is optional and, when given, must agree with HolderID's last segment type.

This is not the same thing as Fields, and an agent that treats them as interchangeable will get the wrong answer. Fields is a filter — "which datasets contain brand Y?" — and works because the dataset holds the field. References is a dereference — "which brands belong to dataset X?" — and exists because a brand holds no field naming its datasets, so no filter can express that question at all.

Several edges are ANDed, an edge composes with Fields, both apply before Limit, and exactly one hop is taken.

The answers an agent must not over-read:

• A holder the principal may not see returns an empty list, not an error. Emptiness here means "nothing you may see", and it is deliberately indistinguishable from "you may not see the holder" — do not report it as a permission failure.
• An absent holder is APERTURE_NOT_FOUND only when it is inside the request's account and the principal is a member of it. Out of account, or for a non-member, the answer is empty.
• An edge naming a field that is not a declared reference is a loud APERTURE_PROVIDER_REFERENCE_INVALID, never an empty list — it means the deployment is not wired for that question, not that access was denied.

What-if simulation (read-only, never persisted)

Model inspection

Surface documentation

Grants are account-scoped by design: aperture_list_grants requires an account argument and never returns another account's grants, so the surface cannot leak cross-account data.

Inputs, outputs, and errors

Each tool carries an input and output JSON Schema (draft 2020-12), reflected at package-init time from the typed Go contract in mcp/schema.go and mcp/contract.go. The In/Out types alias the facade's own surface-neutral types (for example aperture_check's input is service.Query and its output is service.Result), so the schema advertised to the client is exactly the shape the facade decides on. A client discovers these schemas through the standard MCP tools/list call — no Aperture-specific schema fetch is needed.

Argument handling and error surfacing:

• Parameterless tools (the list_* inspectors, aperture_skills_list) accept an empty argument blob.
• A missing required argument (for example id on a get_* tool) returns a plain validation tool-error, surfaced to the model so it can self-correct — it is intentionally not a coded error.
• A coded facade error (an APERTURE_* error) is returned verbatim; the adapter renders it as a structured {code, message, details} envelope rather than a flattened string.
• In the batch tools, a per-item failure is folded into that item's error field (a string); the rest of the batch is unaffected.

The mcp/ core and the SDK firewall

The core lives in the root mcp/ package and is SDK-free: it imports no MCP protocol SDK. Its files divide the surface cleanly:

The core depends only on the decision facade (service), the domain types it returns (engine, model), the coded-errors package (errors), the embedded skill docs (mcp/skills, stdlib-only), and the schema reflector (google/jsonschema-go). It carries the schema as json.RawMessage specifically so a consumer can import the contract without pulling in any MCP SDK.

The adapter is the only SDK importer

The one package permitted to import the protocol SDK (github.com/modelcontextprotocol/go-sdk) is the thin mcp/gosdk adapter. gosdk.Register(server, svc, cfg) mounts the core's ToolDescriptor catalog onto a caller-supplied go-sdk server via the low-level Server.AddTool path — which accepts any value that marshals to a valid 2020-12 schema, exactly the json.RawMessage the core emits. Register mounts onto the server it is given; it never constructs, serves, or owns the server lifecycle. An embedder that already runs its own go-sdk server can mount the full Aperture surface the same way.

firewall_test.go makes the guarantee load-bearing

mcp/firewall_test.go enforces the boundary so it is a fact, not an aspiration:

• TestMCPCore_NoSDKImport runs go list -deps over the core packages (mcp, mcp/toolmeta, mcp/skills) and fails if the MCP SDK module appears anywhere in their transitive dependency graph. Moving an SDK import into any core package makes this test fail with the exact offending dependency line.
• TestMCPCore_AllowedDepsReachable asserts the documented allow-list (service, engine, model, errors, mcp/skills, mcp/toolmeta, google/jsonschema-go) is reachable from the core, proving the firewall is inspecting a real, populated graph rather than passing vacuously.

The adapter (mcp/gosdk) is deliberately excluded from the firewall's package list — the SDK is allowed there and nowhere else. This keeps the promise a client author relies on: importing the Aperture MCP contract never drags in a protocol SDK.

Running it

aperture mcp hand-wires the read-only dependency graph (storage → engine → service), constructs the go-sdk server, mounts the SDK-free catalog through the gosdk adapter, and serves over stdio — the transport an MCP client uses when it spawns Aperture as a subprocess:

aperture mcp [--seed <path>] [--store <dsn>]

• --seed — path to a JSON/YAML seed model (defaults to the embedded example).
• --store — sqlite DSN for the backing store (defaults to in-memory).

With neither flag it serves the embedded example model over an in-memory store. There are no other flags: the surface is read-only by construction, so it needs no acting principal, account, or auth adapter.

On start it prints one line to stderr — stdout is reserved for the MCP protocol:

aperture mcp: serving read-only MCP surface over stdio

Connecting a client

You normally don't launch aperture mcp interactively; an MCP client spawns it over stdio. A minimal client configuration points at the binary and the model to serve:

{
  "mcpServers": {
    "aperture": {
      "command": "bin/aperture",
      "args": ["mcp", "--store", "./aperture.db"]
    }
  }
}

The server advertises its identity as aperture with the binary's build version during the MCP initialize handshake, then answers tools/list with the full catalog above and tools/call for each tool.

Related

• aperture mcp — the command-level reference and flags.
• The service facade — the one code path behind every tool.
• Decision API — the same check/enumerate/explain questions from Go.
• RPC / HTTP overview — the read/write Twirp surface served by aperture serve.

Admin UI shell

Audience: operators who want to browse and edit the access-control model from a browser instead of the CLI or raw RPC.

Aperture ships a small embedded admin UI — a static, single-page frontend served from the root of a running aperture serve. It is not a separate service: the HTML, CSS, and JavaScript are compiled into the binary and mounted at /, so starting the server is all it takes to reach the UI. Every screen is a thin client over the same Twirp / HTTP surface; the shell holds no access-control logic of its own — it decodes what the server returns and posts mutations back through the facade.

What it is built from

The shell is deliberately dependency-light and builds with no Node pipeline. Its assets are pre-built, committed blobs embedded via //go:embed all:static (see internal/server/static.go), so the binary stays self-contained in dev and CI.

The full frontend lives under internal/server/static/ (index.html, css/, js/, and vendor/). Vendored blobs (Alpine, Tailwind, DaisyUI) are pinned and documented in internal/server/static/vendor/README.md. The Rete.js bundle is the one asset regenerated by a manual make vendor-rete target — it is never rebuilt in CI. Treat all of these as committed artifacts, not build outputs.

How to reach it

Start the server and open the listen address in a browser:

aperture serve            # listens on :8080 by default

• Default address: :8080 (override with --addr). See the serve command for all flags.
• The UI is mounted last on the mux at /. More specific routes — the Twirp path prefix, POST /check, GET /healthz — take precedence, so the frontend never shadows the API.

Auth expectation

Aperture's authentication is external — the shell never issues credentials. Every request the UI makes is routed through a single apiFetch wrapper that attaches an Authorization: Bearer <token> header, and a 401 clears the token and re-opens the sign-in affordance.

With the default dev authenticator (aperture serve with no --auth override), the bearer token is the principal id: "signing in" through the UI just names which principal your session presents. Switching to the oidc or parsec adapters changes how that bearer is obtained, but the shell's behaviour is unchanged — it still only carries whatever token it holds. A global account switcher in the top bar picks the active account shared by every screen; the server scopes the account list to what the signed-in principal may see (ListAccounts).

Screen tour

The left-hand nav routes by URL hash (#/crud, #/grants, …). Each screen is one Alpine component in static/js/, and each drives a small set of Twirp RPCs on aperture.ApertureService.

Model (CRUD) — #/crud

The model editor. Browse and mutate the core entities — principals, roles, groups, permissions, object types, and accounts — plus account memberships. It lists each entity type (ListPrincipals, ListRoles, ListGroups, ListPermissions, ListObjectTypes, ListAccounts), creates/updates via the matching Put*, and removes via Delete*; memberships use PutMembership / DeleteMembership. It probes the viewer's admin tier with the open Check RPC and can Export the model.

Grants — #/grants

Bestowed grants, delegation, and grant templates. Lists and edits grants (ListGrants, PutGrant, DeleteGrant), issues and rescinds authority (Bestow, Revoke), and manages templates (ListTemplates, PutTemplate, DeleteTemplate, ApplyTemplate) with a bulk path (BulkPutGrants). It uses Check to resolve the viewer's tier.

Graph — #/graph

A force-directed map of the whole model rendered on a <canvas>. It pulls the entire declarative model with a single Export RPC (seeding an account via ListAccounts first) and derives every node and edge — subjects, grants, objects, memberships, roles, and reachability — from that one document, so the picture always reflects the live store. The layout is a small self-contained simulation; no external graph library is used here.

Rules — #/rules

The rule-blueprint editor. This is where Rete.js is used: rules are edited as a node graph on a Rete canvas, then serialized to Aperture's rule AST. It loads and saves rules (ListRules, GetRule, PutRule), lists object types (ListObjectTypes) and object identifiers (ObjectIdentifiers), and validates or dry-runs an expression against the live model (ValidateRule, EvaluateRule, Check).

The what-if preview shows more than the verdict: the reference instant the evaluation resolved against, what each relative-date operand became at that instant, and the deny-safe notes explaining a false. Dates are rendered verbatim, Z included — the editor never constructs a JavaScript Date, which would restate a stored UTC instant in the viewer's own zone.

What-if — #/whatif

A read-only decision simulator. Ask "would principal P be allowed action A on object O?" and see both the verdict and the full explain trace — the expanded subject set, every grant considered with its per-grant outcome, and the deciding grant(s). It drives the open Check and Explain RPCs (no mutation), listing accounts via ListAccounts. It runs a hypothetical against the live model without writing anything.

Audit — #/audit

A queryable table over the append-only audit trail via the QueryAudit RPC. Every mutation, impersonation, and delegation is always recorded; decisions are sampled. Read access is tier-gated — a system-admin reads everything, an account-admin reads only events scoped to their own account — and the screen probes both tiers with Check (using ListAccounts for scope). A viewer with neither tier is told why the table is empty.

Import / export (portability) — #/portability

Download the declarative model file or import one with a preview diff. It exports the whole model (Export), and imports a supplied document (Import) after resolving the viewer's tier with Check and scoping with ListAccounts.

Related

• RPC / HTTP overview and the RPC reference — the surface every screen calls.
• serve command — flags, listen address, and auth adapter.
• The service facade — the one code path behind every RPC the UI drives.

Identity patterns & specificity

Everything Aperture decides is expressed in one primitive: a uniform, hierarchical identity. The same type describes principals (the actor a decision is made for) and objects (the resource an action targets), so there is no second addressing scheme to learn. This chapter defines that primitive, the pattern grammar a grant uses to cover many identities at once, the Contains containment test delegation relies on, and the specificity score that resolves overlapping matches.

If you have not read the Concepts primer, skim it first — it fixes the vocabulary (principal, object, grant, effect) this page builds on. The code lives in the identity package.

The identity primitive

An identity is an ordered path of typed segments. Each segment is a type:id pair; segments are joined by /:

account:acme/project:atlas/document:42

Read left to right, each segment narrows the path: account acme, then project atlas within it, then document 42 within that. A principal is written the same way — user:alice or account:acme/team:eng — because principals and objects share the type.

The grammar is intentionally strict, and matching runs on the Check hot path (the NFR target is p99 < 1 ms), so parsing validates without regular expressions and stores segments pre-split so a match never re-parses:

• A segment's type and id are each non-empty.
• Allowed characters in a component are ASCII letters, digits, and -._~@+ — enough for slugs, UUIDs, and qualified ids, while excluding the structural delimiters / and :, whitespace, and the * wildcard sentinel.
• An empty string, an empty segment (a leading, trailing, or doubled /), a segment missing its :, or an illegal character is rejected as an APERTURE_IDENTITY_INVALID coded error.

identity.Parse builds an Identity from its canonical string and round-trips losslessly (Parse(s).String() == s); identity.New builds one from segments a caller already holds. The identity package depends on nothing but the root errors/ package, so it stays a leaf every other layer resolves against.

id, err := identity.Parse("account:acme/project:atlas/document:42")
if err != nil {
    // APERTURE_IDENTITY_INVALID
}
id.Len()        // 3
id.Segments()   // []Segment{{account,acme}, {project,atlas}, {document,42}}

Patterns

A single grant rarely names one object. A pattern is an identity with wildcards that describes a set of concrete identities; a grant's object scope is a pattern. Build one with identity.ParsePattern. Beyond the concrete-identity grammar, a pattern segment may be:

A component set lets one grant scope to several ids without a wildcard, so brand:{1,5,23} covers exactly three brands and nothing else. The set must be non-empty ({} is rejected); duplicate members are dropped, preserving order.

How a pattern matches

Pattern.Matches(identity) is anchored at both ends: every identity segment must be consumed and every pattern segment satisfied. A literal or single * each consume exactly one identity segment; ** consumes one-or-more via backtracking. The matcher slices into the pre-compiled segments and does not allocate.

Pattern                                     Matches?
account:acme/project:atlas/**               account:acme/project:atlas/document:42   ✓ (** = "document:42")
account:acme/project:atlas/**               account:acme/project:atlas               ✗ (** needs ≥1 segment)
account:acme/project:*/document:42          account:acme/project:atlas/document:42   ✓ (project id wildcard)
account:acme/brand:{1,5,23}                 account:acme/brand:5                     ✓ (5 ∈ set)
account:acme/brand:{1,5,23}                 account:acme/brand:9                     ✗ (9 ∉ set)

Because ** must consume at least one segment, a pattern is never shorter than the identities it matches minus its wildcard expansion — a trailing ** matches any non-empty remainder but not the empty one.

Enumerating a finite pattern

When a pattern contains no * or ** anywhere — every segment is a literal whose components are plain literals or explicit sets — its language is finite. Pattern.Expand() returns that concrete set as the deterministic cross-product of each segment's members (segment order, then written member order), reporting ok=false for any pattern with a wildcard (whose language is unbounded or provider-dependent). This lets a set-scoped grant like brand:{1,5,23} list its three concrete objects without consulting a provider.

Specificity: resolving overlaps

Two grants can both match the same object with different effects — a broad allow on account:acme/project:atlas/** and a narrow deny on account:acme/project:atlas/document:secret. Aperture resolves this with deny-overrides ranked by specificity: the more specific pattern wins, and on a genuine tie deny beats allow. identity.Specificity(pattern) produces the deterministic score that drives the tiebreak.

The score is a single weighted integer (paths are short, so there is no overflow risk) built from three signals:

A type:id literal contributes up to two literal components; a component wildcard (*) or a bare * segment contributes none (only its pinned position). The result is that the pattern a human would call "more specific" — more fixed components, fewer and shallower wildcards — always scores strictly higher.

Pattern                                        Specificity
account:acme/project:atlas/document:secret     6 literals·10000 + 3 segs·100      = 60300
account:acme/project:atlas/**                  4 literals·10000 + 3 segs·100 − 1000 = 39300
account:acme/**                                2 literals·10000 + 2 segs·100 − 1000 = 19200

identity.Compare(a, b) returns +1 / -1 / 0 as a total, deterministic order (safe as a sort key), and identity.MoreSpecific(a, b) reports whether a ranks strictly above b. The decision engine consumes these directly; this package never applies deny-overrides itself — it only supplies the ranking.

flowchart TD
    O["object: account:acme/project:atlas/document:secret"]
    O --> G1["grant A · allow<br/>account:acme/project:atlas/** · spec 39300"]
    O --> G2["grant B · deny<br/>account:acme/…/document:secret · spec 60300"]
    G1 --> R{"both match —<br/>rank by specificity"}
    G2 --> R
    R -->|"B is more specific"| D["deny wins"]

Containment: Contains

Delegation asks a different question: is one grant's authority a subset of another's? identity.Contains(outer, inner) answers it structurally — it reports whether outer's language is a superset of inner's, i.e. every concrete identity inner matches, outer matches too. Equivalently, inner is "equal-or-more-specific / contained within" outer. outer.Contains(inner) is the method form.

The test is sound and conservative: it never reports containment that does not hold, but — because it is a structural check rather than a full language inclusion decision over the one-or-more ** — it may return false for some genuinely-contained pairs. Delegation fails closed, so a false negative merely rejects a bestow that could in principle have been allowed; it never permits an escalation. It is reflexive (a pattern contains itself).

Contains(account:acme/**,           account:acme/project:atlas/document:42)  = true
Contains(account:acme/brand:{1,5},  account:acme/brand:5)                    = true
Contains(account:acme/brand:{1,5},  account:acme/brand:{5,9})                = false (9 ∉ {1,5})
Contains(account:acme/*,            account:acme/**)                         = false (single can't cover ≥1)

For a component, an outer wildcard covers anything, an inner wildcard is never subsumed by a fixed outer, and otherwise both reduce to finite value sets where outer must contain every inner value — so {1,5,23} subsumes 5 and {1,5} but not 3 or {5,9}.

Where this leads

Patterns bound what a grant covers, but membership within that bound can be more than literal matching — a grant can cover "every object of this type" or "these ids only" or "whatever a rule selects." That is the job of scopes and scope strategies. The attributes a rule reads about an object are supplied by the host through providers. For the end-to-end decision flow that consumes specificity, see the library Decision API.

Rules engine

A grant can be gated on the attributes of a request — deny a read unless the object's classification is public, allow a share only for principals above a clearance tier. Aperture expresses those conditions as rules. A rule is a small, typed AST that Aperture compiles once to an expression program and evaluates in-process against the object's metadata plus the principal/action context.

Aperture evaluates rules with expr-lang/expr directly. It renders each rule AST to an expr-lang expression and compiles it with expr-lang's pure-Go evaluator, in-process. There is no external policy service and no dependency on Pulse — any documentation that says "Pulse expression" is stale. The rules package imports github.com/expr-lang/expr; that is the whole engine.

The code lives in the rules package, in three layers: the AST (ast.go), the compiler and cache (compiler.go, cache.go), and the engine (engine.go).

The rule AST

A rule is a tree of rules.Node values. The node set is deliberately small and closed so a node editor can map its palette one-to-one onto it, and so the JSON form is a stable contract that round-trips byte-identically (marshal → unmarshal → marshal). There is no second rule format.

The operators carried in compare.Op are covered in the operator vocabulary below.

Constructor helpers build the tree in Go — And, Or, Not, Compare, Unary, Var, Lit, List, Call. This rule says the object is public, or the principal's tier is one of gold/platinum:

ast := rules.Or(
    rules.Compare(rules.OpEq, rules.Var("object.classification"), rules.Lit("public")),
    rules.Compare(rules.OpIn, rules.Var("principal.tier"),
        rules.List(rules.Lit("gold"), rules.Lit("platinum"))),
)

Its canonical JSON — the shape the editor and the state file persist — omits every zero field, keeping the serialized form minimal:

{
  "type": "or",
  "children": [
    {"type": "compare", "op": "eq",
     "left": {"type": "var", "name": "object.classification"},
     "right": {"type": "literal", "value": "public"}},
    {"type": "compare", "op": "in",
     "left": {"type": "var", "name": "principal.tier"},
     "right": {"type": "list", "items": [
       {"type": "literal", "value": "gold"},
       {"type": "literal", "value": "platinum"}]}}
  ]
}

The evaluation context

A rule reads from a closed set of four roots, and only those — a reference to anything else is an unknown variable:

The three metadata roots are map[string]any so a rule reads host-defined fields dynamically; action is a typed string so misusing it (action.foo) is a type error. This closed environment is enforced twice — structurally by Validate (below) and again by the expr-lang type-checker at compile time.

The operator vocabulary

There are eleven comparison operators beyond the six scalar ones. All of them are values of compare.Op — none is editor-only sugar, because the AST is the editor's serialization target and the state file's persisted form: a rule authored as has all must read back as has all.

Scalar comparisons

Both operands are required and either may be any operand node.

Collection operators

Left is the collection being tested (for exists, any path at all). Right is the operand — and the last three operators are unary: they reuse the same compare node with Right omitted, rather than introducing a new node type.

// "tagged both a and b, in no blocked region, and it actually has an owner"
rules.And(
    rules.Compare(rules.OpHasAll, rules.Var("object.tags"),
        rules.List(rules.Lit("a"), rules.Lit("b"))),
    rules.Compare(rules.OpHasNone, rules.Var("object.regions"),
        rules.Var("account.blockedRegions")),
    rules.Unary(rules.OpExists, rules.Var("object.owner.dept")),
)

rules.Unary(op, left) builds a unary node; it is still a compare node, and its JSON simply carries no right key:

{"type":"compare","op":"isEmpty","left":{"type":"var","name":"object.tags"}}

That omission is part of the contract. Validate requires Right == nil for exactly isEmpty, isNotEmpty and exists and rejects a supplied one, so there is only ever one spelling of a unary rule and the JSON round-trips byte-identically. Every other operator still requires both operands.

How each operator compiles

expr.DisableAllBuiltins() is in force, so nothing may be assumed reachable. Each operator makes a deliberate choice:

has and hasKey need no new machinery because expr's in is element membership over an array and key membership over a map — "dept" in object.owner is already the hasKey semantics, so the operator is pure spelling. exists leans on the optional chaining var already renders, which is what makes object.owner.dept exists false rather than a runtime error when owner is missing.

The six with no native spelling are backed by functions in the curated pure set. Each is deterministic and side-effect-free, so the purity guarantee holds: they read their arguments and nothing else.

The guarded row overrides the other four. A collection operator whose collection operand is not statically known to be a collection — anything but a list literal, so in practice any operand that reads metadata — renders to the internal dispatcher $op instead, which applies the shape policy and records a note. The common object.region in ["us","eu"] keeps its native in: a list literal is an array by construction and cannot mismatch, so the decision path pays nothing for a guard it does not need.

Neither $op nor the __notes sink it reads is reachable from a rule. $ is outside the identifier grammar Validate enforces for a call name, and __notes is not one of the four exposed context roots — so the guard is compiler-only by construction, with no denylist to keep in sync.

Predicate builtins are denied

expr.DisableAllBuiltins() does not do everything its name suggests. expr's fifteen predicate builtins — all, any, none, one, filter, map, count, sum, find, findIndex, findLast, findLastIndex, groupBy, sortBy, reduce — are resolved by the parser before it consults the disabled table, so all(...) still compiles under Aperture's option set while len(...) genuinely does not. Nothing in the AST emits expr's # pointer, so none is reachable through a well-formed rule today — but a call node renders name(args…) verbatim, so Call("all", …) would compile. Validate therefore rejects those names outright with APERTURE_RULE_INVALID, and a test pins the callable set against expr's own builtin registry.

Missing fields and nested access

Metadata is host-defined and ragged: one object carries an owner, the next does not. Two behaviors follow from that, and both matter for whether a rule grants.

Nested access is nil-safe

A var may read a nested path — object.owner.dept. Aperture renders every segment after the root with optional chaining, so that path compiles to object?.owner?.dept. If owner is absent the read yields nil, the enclosing comparison goes false, and the rule simply does not select.

This matters because the un-chained form is not nil-safe: in expr-lang, object.owner.dept against an object with no owner is a runtime error (cannot fetch dept from <nil>), which would surface as APERTURE_RULE_EVAL at Check time. A rule that works against every object carrying an owner would otherwise blow up on the one object that lacks it — in production, not in dev. Optional chaining makes that uniform and deny-safe, so no rule author has to write a guard. A path through a present intermediate behaves exactly as before; ?. differs from . only when the receiver is nil.

// Selects only for objects that actually carry owner.dept == "eng".
// An object with no owner at all evaluates to false, never an error.
rules.Compare(rules.OpEq, rules.Var("object.owner.dept"), rules.Lit("eng"))

⚠️ nin over a field the object lacks grants

in and nin over a missing field do not error — but they are not symmetric in their consequences:

x not in <nil> evaluating to true is the correct logical dual, and it is expr-lang's pre-existing behavior, not something Aperture introduces. But the practical effect is a trap: a deny-list rule written with nin passes every object that is simply missing the column. A typo'd field name, a CSV without that header, or a nested path through an absent intermediate all read as nil — and the rule grants.

List-valued and nested metadata make this far easier to hit than it used to be. If a rule must not select for objects lacking the field, require the field explicitly:

rules.And(
    rules.Compare(rules.OpNe, rules.Var("object.blocklist"), rules.Lit(nil)),
    rules.Compare(rules.OpNin, rules.Var("principal.id"), rules.Var("object.blocklist")),
)

Collection operators: an absent field reads as an empty collection

Every collection operator applies the same rule — an absent array or object is not an error, it is an empty one. Which way that falls out depends on the operator's polarity, and the negative operators grant exactly the way nin does:

hasNone and subsetOf are the ones to watch: no forbidden tag and only allowed tags are both trivially satisfied by an object that carries no tags at all. Pair them with exists (or isNotEmpty) when the field must be present:

rules.And(
    rules.Unary(rules.OpIsNotEmpty, rules.Var("object.tags")),
    rules.Compare(rules.OpHasNone, rules.Var("object.tags"),
        rules.List(rules.Lit("restricted"))),
)

Wrong-shaped fields deny, and are recorded

A field of the wrong shape — has over a string, hasAll over a number, isEmpty over a bool — makes the comparison false. Every collection operator, no exceptions, including the negative ones: nin over a string is false, not true. A mismatch never matches, whatever the operator's polarity, so mistyped data can only ever deny.

expr-lang on its own is not like this. "a" in object.missing is false, but "a" in object.title is the runtime error operator "in" not defined on string — so inheriting expr's behavior would mean one mistyped field breaks every Check that touches it. Load-time validation of the value model stops mistyped data from the CSV and inline loaders, but it cannot cover a host-implemented ObjectProvider or the principal attribute bag, which bypass loaders entirely. Hence a runtime policy as well.

Note the asymmetry with the absent-field table above, and that it is deliberate:

Treating a mismatch as an empty collection would have been more uniform, but it would make nin / hasNone / subsetOf grant on mistyped data. Deny-safety wins the tiebreak.

Which shapes each operator accepts:

Evaluation notes

A silent false is how an access-control bug hides. So the mismatch is recorded and surfaced in Explain, on every decision surface:

Explain alice/read on account:acme/document:9 in account acme
  subjects: principal:alice
  grants considered (1):
     g-doc [allow account:acme/**] inclusive scope does not cover the object
  evaluation notes (1):
     g-doc [rule tagged]: object.tags: expected collection, got string
  verdict: DENY (top specificity 0)

A second kind of note covers the other invisible case: an operator that matched because the field is missing — the nin / hasNone / subsetOf / isEmpty grant described above.

     g-doc [rule tagged]: object.tags: absent; hasNone matched because the field is missing

Notes carry shape and path only — never a metadata value, because a trace crosses account boundaries the same way an error message does. They are diagnostic only and never influence a verdict, and only Explain collects them: Check and Enumerate install no collector, so the decision hot path records nothing and allocates nothing.

Library callers reach the same channel directly:

ctx, notes := rules.WithNoteCollector(ctx)
allowed, err := compiled.Eval(ctx, in)
for _, n := range notes.Notes() {
    log.Println(n) // object.tags: expected collection, got string
}

Other missing-field behavior

• Equality against a missing field is false (nil never equals a scalar).
• Ordered comparison (lt le gt ge) against a missing field is a runtime error — APERTURE_RULE_EVAL. The rule assumes a field the object does not carry; the scope resolver treats that as a non-decision, not a silent select.

Validation

Node.Validate() checks that a node and its subtree are structurally well-formed — the closed node set, the correct arities (and/or need ≥ 2 children, not exactly 1, compare the operands its operator calls for), a known comparison operator, a scalar literal, and a variable whose first path segment is one of the four roots. It returns APERTURE_RULE_INVALID for a malformed node and APERTURE_RULE_UNKNOWN_VARIABLE for a variable outside the exposed roots.

Validation is pure structure — it does not type-check and never touches the expression engine. Beyond arity it enforces, per operator:

• A literal carries a scalar (arrays and objects are rejected; use a list node for collections).
• isEmpty / isNotEmpty / exists carry no right operand; every other operator carries one.
• in nin hasAll hasAny hasNone subsetOf take a list or a var on the right.
• has / hasKey take a single element on the right — a list there is an error that points at hasAll/hasAny/hasNone.
• A call may not name one of expr's predicate builtins.

For the deep check — structure plus a full compile pass that surfaces type errors and unknown functions — call rules.ValidateAST(raw). It decodes a JSON AST and compiles it against a shared package-level validator (nil source, nil fetcher — it resolves no references and fetches no metadata), returning nil for a compilable rule and an APERTURE_RULE_* code otherwise. This is what a save/validate surface runs before persisting a rule.

Compilation and caching

Node.Expr() renders the validated AST to an expr-lang expression string. The rendering is direct and injection-free (variable paths are Go-style identifiers, string literals are quoted, integers keep their exact form via json.Number):

((object?.classification == "public") || (principal?.tier in ["gold", "platinum"]))

Every path segment after the root renders with expr-lang's optional chaining (?.); the root itself is a typed environment field and needs none. That is what makes nested reads nil-safe — see Missing fields and nested access below. The AST is unchanged: a var node still stores the plain dotted path (object.owner.dept), so the JSON form the editor and the state file share carries no ?.

Compiler.Compile(node) validates, renders, and compiles that expression to a reusable *vm.Program via expr.Compile. Every compiler fixes the same options:

• expr.Env(evalEnv{}) — the typed four-root environment, so any other top-level identifier is an unknown name at compile time.
• expr.AsBool() — a rule must evaluate to a boolean.
• expr.DisableAllBuiltins() — expr-lang's builtin library is off, so no wall-clock or random function is reachable and evaluation stays deterministic. It does not cover the predicate builtins; Validate denies those by name.
• The curated pure function set — lower, upper, contains, startsWith, endsWith, len, plus the collection-operator backings hasAll, hasAny, hasNone, subsetOf, isEmpty, isNotEmpty. A host adds its own deterministic, side-effect-free functions with rules.Function(name, fn) / Engine WithFunction; these join (and can shadow) the curated set. An unknown function is caught at compile time. Note that contains, startsWith and endsWith are reserved as infix operators by expr's grammar, so they are registered but cannot be reached through a call node; the other nine can.

A compile failure that survives validation is a type mismatch, a non-boolean result, or a call to an unregistered function — all surfaced as APERTURE_RULE_TYPE_ERROR, with the evaluator's own message preserved in context. A Compiled is immutable and safe for concurrent evaluation; it carries the canonical Source() and its Hash() (sha256 of the source).

The compiled-rule cache

Compiling an expression is the expensive step, and Check runs on a tight latency budget, so a compile happens once per canonical form. The engine keys a compiledCache by the rule's canonical hash. Two different rule references whose ASTs render to the same expression share a single compiled program.

flowchart TD
    A["rule AST (Node)"] --> V["Validate<br/>structure + roots"]
    V --> R["render → expr-lang source"]
    R --> H["hash = sha256(source)"]
    H --> C{"cache hit<br/>for hash?"}
    C -->|"hit"| P["reuse *vm.Program"]
    C -->|"miss"| K["expr.Compile → program"]
    K --> S["cache.put"]
    S --> P
    P --> E["Eval(Input) → bool"]

The cache is concurrency-safe and exposes Hits / Misses / Evictions / Entries via Engine.CacheStats(). An optional TTL (WithCacheTTL, with an injectable Clock for deterministic tests) bounds entry lifetime; TTL ≤ 0 keeps entries until explicit invalidation. When a rule's definition changes underneath a cached compilation, a host calls Engine.Invalidate(node) (drop one) or Engine.InvalidateAll() (clear).

Evaluation and the engine

Compiled.Eval(ctx, Input) runs the program against an Input — Object, Principal, and Account maps plus the Action string (a nil map reads as empty). Evaluation is pure: it reads only the input, mutates nothing (the object metadata snapshot is treated read-only), and exposes no nondeterministic function. A runtime failure or a non-boolean result is APERTURE_RULE_EVAL.

rules.Engine ties the pieces together. It is built over a RuleSource (which resolves an opaque rule reference to its Rule definition — MapSource is the in-memory default; a missing reference yields APERTURE_RULE_NOT_FOUND) and a MetadataFetcher (whose signature matches *provider.Registry.Fetch, so a provider registry wires in directly as the object-metadata source without the rules package importing provider). An optional PrincipalResolver supplies principal attributes, keyed by Attributes(ctx, kind, principal). A resolver returns the host's bag alone; returning nil is a complete answer, because the engine stamps the floor over whatever comes back. The kind is model.PrincipalKind's spelling ("user" / "machine") carried as a string, so one resolver can dispatch to a different attribute source per kind — a human directory and a service-account registry are rarely the same store. An empty kind means the caller did not have the principal's record in hand: treat it as unknown, never as a default, or a machine gets answered for out of the human directory.

An optional AccountResolver supplies the active account's attributes, keyed by AccountAttributes(ctx, account). It is the same contract one root over: the host's bag alone, nil is a complete answer, the engine stamps the floor. The method is spelled AccountAttributes rather than Attributes so that one *provider.AttributeRegistry can satisfy both seams — Go has no overloading, and the registry already holds both directories and both caches.

The floor bag, and principal.kind

principal always carries {id, kind}, whatever is wired. The floor is stamped last, so a host bag with its own id or kind key cannot shadow it — the realistic collision is innocent (a directory with an internal id column), and a floor that can be shadowed silently changes what principal.id == object.owner compares. An unknown kind is published as the empty string rather than omitted, so "unknown" is a value a rule can compare against.

kind is published because attribute providers are registered per kind, which makes a rule silently kind-dependent: a rule reading the user directory finds nothing for a machine principal. In an inclusive grant that denies safely; in an exclusive one — where being selected means being excluded — a rule that quietly stops selecting widens access. principal.kind is how an author states the dependence instead of hiding it:

principal.kind == "user" && principal.tier == "gold"

The account floor, and the wildcard

account always carries {id} — the active account, the tenancy the decision is being made in, never the account a grant happens to be stamped to. A wildcard-stamped grant is evaluated inside whatever account is active, so reading its attributes off the stamp would give one tenant's decision another tenant's plan.

The floor is {id} and deliberately not {id, kind}: there is one account slot, so a kind key would be the same constant in every bag in every deployment, and a value that can never discriminate is noise a rule author would eventually compare against. As with principal, the floor is stamped last, so a host account table with its own internal id column cannot silently change what account.id == object.account compares.

"*" — the all-accounts grant sentinel — is never an attribute fetch key. There is no account row for it (ValidateAccount refuses to store one), and the only bag that could answer "the attributes of every account" is one tenant's data served as every other's. It is nonetheless a live active account: platform-tier authority is anchored there, so authz.Gate.RequireSystemAdmin really does run a Check with it. A decision made at platform scope therefore sees the floor and nothing else — account.id is "*", which truthfully says "not scoped to a tenant", and every host-defined field is absent exactly as it is for an unwired slot. The engine short-circuits before any resolver is consulted, so a rule-backed grant guarding the system anchor stays decidable; presenting "*" to provider.AttributeRegistry directly is APERTURE_ATTRIBUTE_PROVIDER_INVALID, which makes that refusal a backstop rather than the mechanism.

Wiring a *provider.AttributeRegistry

A provider.AttributeRegistry — the host seam that maps each of the three attribute slots (user, machine, account) to a provider plus a per-slot cache — is both a PrincipalResolver and an AccountResolver as it stands, structurally, with provider importing nothing from rules:

attrs := provider.NewAttributeRegistry()
attrs.MustRegister(provider.AttributeSlotUser, userDirectory)
attrs.MustRegister(provider.AttributeSlotAccount, tenantDirectory)
eng := rules.NewEngine(source, objects,
    rules.WithPrincipalResolver(attrs),
    rules.WithAccountResolver(attrs))

The kind picks the slot: "user" resolves the user slot, "machine" the machine slot. "account" is a real slot but is not a principal kind, so it never resolves through WithPrincipalResolver — a tenant's bag must never be served as a principal's. WithAccountResolver is the only door to it, and it is keyed on the active account, not on any principal.

A deployment that has no directory to point at declares the bags in the seed file instead, under attributes:, and Document.BuildAttributeRegistry returns exactly the registry above — so aperture check decides on principal attributes with no Go written by the host.

A missing source is not a failed decision. A slot with no registered provider, and a registered provider with no record for the key, both yield the floor and no error, so a deployment with a human directory and no machine directory keeps deciding normally. Everything else — an unreachable directory, a bag the value model rejects — surfaces verbatim with its code and fixups intact and is treated as a non-decision, because an outage must not read as "this principal has no attributes".

Engine.Selected(ctx, rule, object, account, principalKind, principal, action) is the full path:

1. resolve the rule reference through the RuleSource;
2. compile-and-cache its AST;
3. fetch the object's metadata (empty when no fetcher is configured);
4. resolve the principal's attributes for its kind, and stamp the floor over them into a fresh map (the resolver's bag may be cached and shared, and is read-only, transitively);
5. resolve the active account's attributes the same way, through the same read-only contract, and stamp {id} over them into a fresh map;
6. build the Input and evaluate.

Any step's failure is an APERTURE_* coded error, and the caller treats it as a non-decision — there is no select-on-error. That signature is exactly scope.RuleEvaluator, which is how the rule-backed inclusive/exclusive scope strategies get their variant: the engine is wired as scope.Deps{Rules: engine}.

One bag per decision

principal and account are constant for the whole decision, so they are resolved once and memoized for it, exactly as the reference instant NOW is snapshotted once. The decision engine opens that scope at the same three boundaries it opens the instant's — Check, Enumerate, Explain.

It is a correctness property, not only a cost one: a bag is served through a cache with a TTL, and a TTL expiring halfway through an enumeration would judge the first candidates against one version of the principal and the last against another — a result set no single view of the principal justifies, with no error anywhere. An absence memoizes (an unwired slot, or a directory with no record, is a complete answer describing a steady state, so a 1,000-object enumeration performs one resolution); a failure does not, and that costs almost nothing, because a failure ends the decision.

The memo is keyed by the subject each bag was resolved for and re-resolves on a mismatch, so a scope travelling somewhere its author did not picture cannot serve one principal's attributes as another's. There is no API to hand a bag in: a caller-supplied principal bag would be a caller-supplied answer to "who is asking".

Under impersonation, principal.* is the effective subject

When a decision resolves under an active impersonation session, the rule is told about the effective subject — the target under become, the operator under augment — which is the same principal the resolved grant set describes. become resolves the target's id and the target's kind, so principal.* is read from the target's directory.

The invariant is that the rule and the grant set always describe the same principal. A decision resolving the target's grants while reading the operator's attributes is an authorization bug that leaves no mark in a trace.

Audit is unaffected: the request and the decision still name the real operator, and the trace still records the session. An inert or expired session elevates nothing and reads the operator's own bag. Note that principal.id therefore changes meaning under become — a rule comparing principal.id == object.owner asks "does the target own it", which is what that mode means.

Where this leads

Rules are one of two ways a scope strategy can decide object membership; the other is an explicit id-list. See scopes & scope strategies for how the inclusive and exclusive strategies consult a rule. The object.* fields a rule reads come from providers.

Scopes & scope strategies

A grant's pattern bounds which objects the grant can reach. But "reach" is not always "every match" — a grant might cover every object of a type in that scope, or only a named id-list, or everything except a few, or whatever a rule selects. That choice is the grant's scope strategy, and this chapter covers the pluggable resolvers that implement it. The code lives in the scope package.

The key separation: the pattern bounds the scope and supplies the specificity the engine's deny-overrides tiebreak consumes; the strategy decides membership within that bound. A resolver never computes specificity — that stays the pattern's job in the engine, so the resolution semantics from literal-only grants are untouched.

The four strategies

literal is owned natively by the decision engine and is not in the registry. The scope package ships the other three plus a registry for host-defined strategies. Membership always composes with the pattern: a listed object that falls outside the grant pattern is not covered.

The scope reference and Spec

A permission carries its strategy as an opaque string reference; the engine parses it into a typed scope.Spec with ParseSpec. The grammar is a strategy key optionally followed by ;-separated name=value params. Identity strings never contain ;, =, or ,, so those separators never collide with id-list values:

implicit
inclusive;ids=account:acme/document:42,account:acme/document:99
exclusive;ids=account:acme/document:7
inclusive;rule=quarantine-rule

ParseSpec yields Spec{Strategy, IDs, Rule}. An empty reference (or the explicit literal) parses to the literal strategy, so grants that carry no strategy keep their literal behaviour. Parsing validates structure only — known params (ids, rule), non-empty values, no duplicates — and does not consult the registry, so a custom strategy key parses cleanly and is resolved by whatever the host registered. Anything malformed is APERTURE_SCOPE_INVALID.

The resolver contract

Each strategy is a ScopeResolver, constructed per evaluation from a GrantContext (the already-parsed pattern, the permission's object type, the parsed Spec, and the account/principal/action context) plus runtime Deps:

type ScopeResolver interface {
    // hot path — "is this concrete object a member?" — never enumerates.
    Contains(ctx context.Context, object identity.Identity) (bool, error)
    // bounded enumeration for Enumerate-style callers.
    Members(ctx context.Context, pattern identity.Pattern) ([]identity.Identity, error)
}

Contains answers the Check hot-path question and never needs to list objects. Members performs a bounded enumeration (capped by DefaultMaxMembers = 1000) for Enumerate-style callers. Resolver construction is cheap — small value structs, id-list membership by linear scan, no per-evaluation map allocation — and holds no cache.

Two seam dependencies

Strategies that need to enumerate "all objects of a type", or evaluate a rule, reach two seams through scope.Deps. Both default to an inert implementation so a zero Deps is usable:

RuleEvaluator.Selected(ctx, rule, object, account, principalKind, principal, action) is exactly rules.Engine.Selected — that shared signature is how the rule-backed path is wired without scope importing rules.

account and principalKind come straight off the GrantContext. They are there because a rule-backed strategy asks about attributes, and an attribute only means something once you know whose it is and which account it is read in. They are parameters rather than context values on purpose: a missing ctx value degrades silently to an empty account — a quiet allow-or-deny nobody wrote — where a parameter is a compile-time obligation on every caller. principalKind is model.PrincipalKind's spelling ("user" / "machine") carried as a string, since scope imports no model; empty means unknown, never a default.

How each strategy decides Contains

flowchart TD
    O["object"] --> M{"pattern matches?"}
    M -->|no| N["not a member"]
    M -->|yes| S{"strategy"}
    S -->|implicit| T1{"terminal type ==<br/>object type?"}
    S -->|inclusive| L1{"in id-list?"}
    S -->|exclusive| T2{"terminal type match?"}
    T1 -->|yes| Y["member"]
    T1 -->|no| N
    L1 -->|yes| Y
    L1 -->|"no, rule set"| RS{"rule Selected?"}
    L1 -->|"no, no rule"| N
    RS -->|yes| Y
    RS -->|no| N
    T2 -->|no| N
    T2 -->|"yes, in minus-list"| N
    T2 -->|"yes, rule excludes"| N
    T2 -->|"yes, otherwise"| Y

implicit — membership is the conjunction of the pattern match and a terminal-type check (the object's last segment is of the permission's object type). It takes no configuration; supplying an ids list or a rule is a misconfiguration and is rejected so it cannot silently mask intent. Members must list the type, so it depends on the ObjectLister.

inclusive — an opt-in. It must declare an id-list or a rule; neither is a misconfiguration. Contains first requires the pattern match, then: the object's canonical id is in the list (exact string equality), or — only when a rule is declared — the RuleEvaluator selects it. A pure list-backed grant never touches the rule dependency. Members returns the union of the two halves, with both patterns applied to each and no identity repeated — it has to, or Check and Enumerate would disagree about the same grant. The list half needs no lister (the members are the listed ids within both patterns). The rule half is list-then-filter, exactly as exclusive does it: list the type through the ObjectLister and keep what Contains selects. There is no reverse index and no attempt to invert the rule — a rule is an arbitrary expression over object metadata and is not invertible in general. A rule-backed grant enumerated with no ObjectLister therefore reports APERTURE_SCOPE_LISTER_UNCONFIGURED rather than returning nothing, because an empty member list is a legitimate answer; with no RuleEvaluator it reports APERTURE_SCOPE_RULE_UNCONFIGURED.

exclusive — an opt-out. It requires a minus id-list or a rule (declaring neither would make it identical to implicit). Contains requires the pattern match and the terminal-type check, then is a member unless the object is in the minus-list or the rule excludes it. Members enumerates all-of-type in scope via the ObjectLister and drops the excluded ones through Contains.

The registry

scope.Registry maps strategy keys to Factory functions. DefaultRegistry() preloads the three built-ins (implicit, inclusive, exclusive); literal stays native to the engine and is intentionally absent. A host adds its own with Register / MustRegister (rejecting an empty key, a nil factory, or a duplicate with APERTURE_SCOPE_INVALID).

Registry.Resolve(grantContext, deps) builds the resolver for the spec's strategy, validating the spec via the strategy's factory. An unregistered strategy yields APERTURE_SCOPE_UNKNOWN_STRATEGY; a spec the strategy rejects yields APERTURE_SCOPE_INVALID.

reg := scope.DefaultRegistry()

spec, _ := scope.ParseSpec("exclusive;ids=account:acme/document:7")
gc := scope.GrantContext{
    Pattern:       identity.MustParsePattern("account:acme/document:*"),
    ObjectType:    "document",
    Spec:          spec,
    Account:       "acme",
    PrincipalKind: "user",
    Principal:     "user:alice",
    Action:        "read",
}
resolver, _ := reg.Resolve(gc, scope.Deps{Lister: providerReg /* , Rules: rulesEngine */})
ok, _ := resolver.Contains(ctx, identity.MustParse("account:acme/document:42"))
// true: matches the pattern, is a document, and is not in the minus-list.

Where this leads

The ObjectLister that every non-list-backed enumeration depends on is the provider Registry; the RuleEvaluator the rule-backed paths consult is the rules Engine. For how the decision engine assembles grants, resolvers, and specificity into a verdict, see the library Decision API.

Providers

A rule reads object.classification; an exclusive scope enumerates "every document in this account." Both need domain data Aperture does not own. That data belongs to the host application — its database, its API, its source of truth — and Aperture reaches it through providers. A host implements one ObjectProvider per object-type; a Registry binds each type to its provider plus a per-type cache and is the seam every consumer resolves through. The code lives in the provider package; csvprovider (a file) and sqlprovider (a database) are the two concrete worked examples.

There are two provider seams, and this page covers both. An ObjectProvider describes the thing being acted on; an AttributeProvider describes the party asking — the principal and the account a rule reads principal.* and account.* out of. They share one value model and one cache design, and differ in everything that follows from an attribute key being a bare opaque id rather than a segmented identity.

A load-bearing rule: Aperture never persists provider data as a source of truth. The host owns it; Aperture only ever caches a copy. Cached metadata is handed back by reference and treated read-only — the cache never copies a map on read (allocation matters on the Check hot path), so a provider must return a fresh map per object and callers must never write to a returned map. Because a value may nest, that contract is transitive; see the read-only contract below.

ObjectProvider: the host seam

A host implements this once per object-type. It is a pull source — Aperture asks, the host answers — and must be safe for concurrent use:

type ObjectProvider interface {
    Fetch(ctx context.Context, id identity.Identity) (Metadata, error)
    List(ctx context.Context) ([]Object, error)
    Query(ctx context.Context, filter Filter) ([]Object, error)
}

• Fetch returns one object's metadata; a missing object yields an APERTURE_NOT_FOUND coded error, so the Registry can tell "absent" from an operational failure.
• List is the unfiltered enumeration of the type.
• Query returns the objects matching a Filter — an optional Pattern (bounds results to matching identities), a set of Fields predicates, and a Limit. The zero Filter selects everything (equivalent to List).

Metadata is map[string]any — an alias, not a named type — so the rules engine reads each field straight into its expression environment with no conversion layer. An Object pairs an identity with its metadata; the identity's terminal segment type is the object-type the provider is registered under.

The Filter.Fields contract

A provider evaluates Fields, but it does not get to define it. Query is how scope enumeration bounds itself, so two providers disagreeing about what Fields{"tags": "premium"} selects is two different answers to the same authorization question. The rule is stated once on provider.Filter and implemented once in provider.MatchFields; an implementation either calls that helper or reproduces it exactly (by pushing the predicate into SQL, say).

Three properties are worth stating outright, because each one closes a failure mode:

• A collection field matches by membership. Equality against a whole array is never what a caller filtering on a tag list means, and the predicate this replaced compared against the array's literal rendering ([premium launch]), so a tag filter could not match anything useful.
• Comparison is typed, not stringly. Numbers compare across Go numeric types by value (int(5), int64(5), float64(5) are one value), but a number never equals "5" and a string equals only a string. These are the rules engine's own comparison semantics, so Enumerate cannot select an object that a Check over the same value then denies. provider.ValuesEqual is the exported leaf comparison, and csvprovider's membership_equivalence_test.go runs it against a real compiled rule to keep the two from drifting.
• Every predicate must hold (the map is an AND), and an object field is compared by equality, never by key membership — so a scalar want against one is a plain false, not a panic and not an accidental rendering match.

The contract reaches past Query. Enumerate's own metadata filter (engine.EnumerateRequest.Fields, and its EnumerateQuery.Fields / --field / --fields-json / Twirp fields / MCP Fields spellings) is evaluated by this same provider.MatchFields, so an enumeration filtered by the engine and one filtered inside a provider select the same objects. There the filter runs on candidates that already survived deny-overrides, and it runs before the enumeration's Limit — see the decision API.

Because provider is a strict leaf (identity + errors + stdlib), ValuesEqual reimplements the evaluator's equality rather than importing expr-lang. It agrees with it on every value the metadata value model admits; the two documented divergences — time.Time/time.Duration, and a uint64 above math.MaxInt64 — are both outside that model.

The metadata value model

Metadata is an alias, so the type constrains nothing. The shape of a field value is constrained anyway, and deliberately so: metadata goes into the expression evaluator untranslated, which means a wrong shape is not a false decision — it is a runtime evaluation error on the Check hot path (operator "in" not defined on string). Catching that at load is the whole point of the model.

A field value is one of:

Two rules bound it:

• Arrays of objects are rejected at any position. Rule authors compare against arrays with in / not in, which has no useful meaning over a list of maps. Nested arrays ([["a"]]) are rejected for the same reason.
• Typed containers are rejected — []string, map[string]string, structs. The model is spelled in the two types the expression environment and JSON share, so a loader normalises once instead of every consumer type-switching.

time.Time is deliberately not a scalar: a rule literal is a JSON scalar and could never be compared against one, so a loader formats timestamps as RFC 3339 strings.

Dates are string scalars, in two canonical forms

A date is not a fourth shape — it is a string scalar a loader has been told is a date. Such a string must be one of exactly two forms, both UTC:

Granularity is carried by the string itself, so no type tag travels beside the value. An offset-free timestamp is read as UTC and fractional seconds are truncated, never rounded. An explicit offset is rejected rather than converted: a host writing 2026-01-01T00:00:00+05:00 means January 1st, but the UTC instant is 2025-12-31T19:00:00Z, so accepting it would silently move the calendar day and year.

The value model itself stays date-blind — ValidateField cannot know which strings a host means as dates, so it keeps accepting any string. Declaring a field to be a date, and running its values through provider.ParseDateValue, is a loader's job — in csvprovider that is the :date / :datetime column suffix, and in a seed document the field_types: section. A rejection is APERTURE_CONFIG_INVALID carrying a machine- readable reason (provider.DateReasonOf) and never the value, because a date can be personal data. Comparison goes through DateValue.Compare, which compares instants: "2026-03-04" and "2026-03-04T00:00:00Z" are the same moment but sort differently as text, so comparing the stored strings would be wrong at exactly that boundary.

Depth, counted below the field root

provider.ValueDepth(v) reports a value's container depth: every array or object entered adds one level, so a scalar is 0 and an empty container is 1. The cap is 2 by default.

Size, measured structurally

provider.ValueBytes(v) measures a value without serialising it (nothing is allocated on a load path): a string costs its length in bytes, a number 8, a bool 1, nil 0, an array the sum of its elements, and an object the sum of len(key) + value per entry. Container framing costs nothing. The cap is 64 KiB per field value by default.

Validating at load

Validation is load-time, in one place, called by every loader — CSV today, the inline seed next, a database-backed provider later. That is what lets a new loader inherit the semantics instead of renegotiating them.

// defaults: depth 2, 64KiB per value
if err := provider.ValidateMetadata(md); err != nil { return err }

// or tune the caps — the zero ValueLimits means "the defaults", and any
// field left zero keeps its default
limits := provider.ValueLimits{MaxDepth: 3}
if err := limits.ValidateMetadata(md); err != nil { return err }

// one field at a time, for a loader that reports per-column
err := provider.ValidateField("tags", []any{"eng", "oncall"})

A violation is APERTURE_METADATA_INVALID. Its context carries the field name, the path within the value (owner.members[0]), and the offending Go type — never the value itself, so a validation failure can be logged and surfaced without leaking one account's data into another's diagnostics. Fields and object keys are walked in sorted order, so a document with several offenders always reports the same one.

The read-only contract is transitive

Once a value can nest, "cached metadata is read-only" has to reach all the way down. The cache stores the provider's map by reference and never copies it on read, so the nested maps and slices inside it are shared too — appending to a []any you got back races every other reader exactly as writing the top-level map would.

• A provider returns a fresh map per object, with fresh nested containers. It must not hand out a value it also retains and mutates, and reloading a source builds a new value rather than editing the old one in place.
• No holder — engine, rules, scope, CLI, server, host code — writes to a Metadata it was given, at any depth.
• A consumer that needs to modify metadata copies it (deeply) first.

The Registry: binding, cache, invalidation

provider.NewRegistry() returns an empty registry; Register(objectType, provider, opts...) binds a provider to a type with a per-type cache (rejecting an empty type, a nil provider, or a duplicate with APERTURE_PROVIDER_INVALID). The registry is concurrency-safe: providers register at startup and are read on the hot path under an RWMutex, and each per-type cache is independently safe.

Registry.Fetch(ctx, id) is the read path consumers use. It routes by the id's terminal segment type (an unregistered type is APERTURE_PROVIDER_UNREGISTERED), serves from the type's cache when fresh, and otherwise pulls through the provider and caches the result — a cache hit never calls the provider. A host provider's error is normalised by providerError: one already carrying an APERTURE_* code passes through verbatim (so its APERTURE_NOT_FOUND reaches the caller intact), while a plain error is wrapped as APERTURE_PROVIDER_FETCH.

flowchart TD
    C["consumer: engine / rules / scope"] --> F["Registry.Fetch(id)"]
    F --> T["route by terminal type"]
    T --> H{"cache hit<br/>& fresh?"}
    H -->|yes| R["return cached metadata (read-only)"]
    H -->|no| P["ObjectProvider.Fetch"]
    P --> S["cache.Set"]
    S --> R

The registry serves two other roles by matching contracts from other packages without importing them:

• Fetch is a rules.MetadataFetcher — its signature is exactly what the rules Engine wants for object metadata, so a *Registry is wired in as the fetcher directly.
• List(ctx, objectType, pattern, limit) is a scope.ObjectLister — byte-for-byte the seam the implicit/exclusive scope resolvers left open, so a *Registry is passed as engine.ScopeDeps{Lister: reg}. It queries the provider, bounds the result by the pattern and the limit (DefaultListLimit = 1000), and opportunistically warms the cache with each returned object's metadata.

Two enumeration variants sit beside the bounded List: Identifiers returns the complete, unbounded id set (sorted, for a stable diff — use it to expand an exclusive allowance into a positive allow-list), and IdentifiersExcept is Identifiers minus an excluded set.

Cache tuning and invalidation

Each type's cache is an in-memory LRU (MemoryCache) behind the pluggable CacheBackend interface, tuned per type at registration:

Invalidation is explicit: Invalidate(id) drops one object, InvalidateType clears a type, InvalidateAll clears every cache. Stats(objectType) exposes Hits / Misses / Evictions / Expirations / Invalidations / Entries for observability and the latency benchmark. The provider package depends only on identity and errors — never scope, engine, or model — so it stays a leaf.

Attribute providers

An ObjectProvider answers "what do you know about this object?". An AttributeProvider answers "what do you know about the party asking?" — the principal's department and clearance, the account's plan and region — so a rule can be written about the asker instead of only about the thing being acted on:

principal.kind == "user" && principal.department == object.department
account.plan == "enterprise"

The two seams are not variants of each other, and the difference is the fan-out. Object metadata is resolved per object: a decision touching a thousand objects reads a thousand bags, each describing something different. An attribute bag is resolved once per decision and then read by every rule against every object in it. Almost everything below follows from that.

The three slots, and there is no fourth

provider.AttributeSlot is a closed set:

The object Registry is an open, type-keyed map because the host's object types are the host's business. The slots are not: they are the parties a decision has, and a decision has exactly these. An open map would let a host register a fourth "kind" of subject nothing in the engine knows how to fetch — discovered at evaluation time as an empty bag, which is to say as a silent denial. A further distinction is a field in the bag, never a fourth slot. user and machine are separate slots because in every host that has both, the two are served by different systems.

The interface is three methods, and the key is the whole difference from an object provider:

type AttributeProvider interface {
	Fetch(ctx context.Context, id string) (Metadata, error)
	List(ctx context.Context) ([]AttributeRecord, error)
	Query(ctx context.Context, filter AttributeFilter) ([]AttributeRecord, error)
}

An AttributeRecord pairs one bare string key with a Metadata bag. An object identity is a segmented path (account:acme/project:atlas/document:42) precisely so a scope can contain and pattern-match it; an attribute key is an opaque handle into the host's directory with no hierarchy to spell and no containment relation to anything. A provider returns APERTURE_NOT_FOUND for a key it does not know, must be safe for concurrent use, and owes the same transitively read-only contract an object provider owes — more strictly, in fact, because one attribute bag is shared across every object in a decision and every concurrent decision for that subject.

The bag is a provider.Metadata: the same value model, the same depth and size caps, the same ValidateMetadata, the same two canonical date forms, the same number normalisation in every loader. There is no second model, so principal.clearance == 3 answers identically whether the bag was authored in YAML, read from a CSV :int column, or read from a SQL integer.

The registry, the per-slot cache, and the revocation window

provider.AttributeRegistry binds each slot to a provider plus its own cache — its own TTL, size cap, and counters — because the three slots have genuinely different change rates and cardinalities:

attrs := provider.NewAttributeRegistry()
attrs.MustRegister(provider.AttributeSlotUser, dir, provider.WithTTL(60*time.Second))
attrs.MustRegister(provider.AttributeSlotAccount, tenants)

Registering a slot twice is refused, not replaced: "last writer wins" is how one deployment's directory quietly shadows another's during wiring, and the failure then surfaces as attributes that are merely wrong rather than absent. A slot left unregistered is not an error — a deployment with no machine principals wires no machine provider.

Staleness is not only a tuning knob here. An object's metadata going stale for a TTL is usually tolerable: a document's category is a fact about a thing. An attribute bag is the asker's standing — the clearance, the department, the plan — so until a cached bag expires, every decision about that subject is made against access the host may have already taken away. Pick a slot's TTL for how fast its revocations must land, and close the window explicitly when you cannot wait: Invalidate(slot, id) drops one subject (and reports whether an entry was present), InvalidateSlot(slot) a whole directory, InvalidateAll() everything. Invalidation is process-local: it clears the caches of the process that runs it and cannot reach a different one.

Leniency: a missing bag decides, a broken directory does not

The registry satisfies the rules engine's two resolver seams structurally, without importing rules:

eng := rules.NewEngine(ruleSource, objectRegistry,
	rules.WithPrincipalResolver(attrs),  // Attributes(ctx, kind, principal)
	rules.WithAccountResolver(attrs))    // AccountAttributes(ctx, account)

Two outcomes are lenient — they yield a nil bag and no error, so the decision proceeds against the engine's floor bag:

• the slot has no registered provider, or the principal's kind names no principal slot at all;
• a registered provider has no record for this key (APERTURE_NOT_FOUND).

Everything else — an unreachable directory, a bag the value model rejects — surfaces verbatim, keeping its code and its registry fixups, and every consumer treats it as a non-decision. That distinction is the point of the seam: an outage must not read as "this principal has no attributes", because that is an authorization change wearing an infrastructure failure's clothes.

Leniency leaves one hazard, and it is accepted rather than solved. An absent attribute makes every comparison against it false. In an inclusive grant that is deny-safe. In an exclusive grant, selection means excluded — so a rule that quietly stops selecting stops excluding, and the object the exclusion was written to withhold becomes covered, with nothing in the verdict saying so. The mitigations are visibility, not refusal: principal.kind, so an author can state a rule's kind-dependence out loud, and the attributes_floor_only evaluation note, so a trace says the bag was empty.

A principal bag is global, and keeping it account-neutral is a host obligation. A fetch is keyed by the bare principal id alone — it carries no account — so one principal's bag is visible to rules evaluating in every account that principal is a member of. Facts about the person or the machine are account-neutral; facts about the person in one tenancy are not, and putting one in a principal bag publishes one account's data into every other account that principal touches. Aperture cannot detect it: the values are opaque host data. Per-tenant facts belong on the account slot, which is bounded — the account bag is always resolved from the active account.

The containment boundary: enumeration is never scope resolution

*provider.Registry deliberately does satisfy scope.ObjectLister, which is how an exclusive scope enumerates a type. *provider.AttributeRegistry deliberately does not.

If the principal directory were reachable through that seam, the principal table would become an enumerable object set inside a decision — every principal in the deployment listable by anything holding a lister, bounded only by the grant's own scope, with no admin tier consulted.

Go's typing is structural, so intending otherwise is worth nothing: a method with a matching signature satisfies the interface whether or not anybody meant it to, and the wiring mistake it enables is silent. So the containment is structural too, four times over — enumeration is called Enumerate, not List; it is keyed by an AttributeSlot, not a bare object-type string; it takes an AttributeFilter, which carries no identity.Pattern to bound with; and it returns []AttributeRecord (bare keys), not []identity.Identity. Any one of the four makes the signature unassignable; all four make it unassignable by accident. TestAttributeRegistryIsNotAScopeLister asserts the negative against the real interface, with *provider.Registry as the positive control.

AttributeFilter carries no pattern for the same reason. There is nothing to match — an attribute key has no segments, so a pattern over it could only be a substring test dressed as containment — and Filter.Pattern exists solely to bound an enumeration to a grant's scope. Its Fields predicate is exactly the object seam's Filter.Fields contract, and both Fields and Limit are re-enforced by the registry on whatever a provider returns, so a provider that ignores them is still correct and no caller can materialise an unbounded directory.

Enumeration is therefore reachable from exactly one place: service.ListAttributes, a system-tier administrative read gated through authz.Gate.RequireSystemAdmin, surfaced as aperture attributes query. The decision path's Fetch is not gated and must never be — a decision resolves one bag for a subject it already named.

Where the bags come from

Declaratively, a seed document's attributes: block lists bags inline and attribute_providers: points a slot at a file or a connection. Both are runtime wiring, never model state.

One asymmetry is worth repeating here because nothing can catch it: an attribute provider's keys are bare ids. A CSV id column holds alice, not user:alice; a SQL get_all selects u.id AS id, not 'user:' || u.id AS id. An identity-shaped key is a legal opaque string that enumerates and caches happily and then matches no id any fetch ever presents, so the slot silently never answers. See the bare-id contract.

Declared references

A registry also holds references: declarations that one object-type's metadata field holds identities of another object-type. dataset.current_brands → brand is an application-level foreign key — nothing in a database enforces it, so the declaration lives beside the provider that serves the field.

providers:
  - object_type: dataset
    kind: sql
    connection: main
    get_one: SELECT d.tier, to_jsonb(d.brand_ids) AS current_brands FROM datasets d WHERE d.id = $1
    get_all: SELECT 'account:acme/dataset:' || d.id AS id,
                    to_jsonb(d.brand_ids) AS current_brands
             FROM datasets d
    references:
      current_brands: brand      # field name → target object-type

reg.MustRegister("brand", brands)
reg.MustRegister("dataset", datasets)
reg.MustDeclareReference("dataset", "current_brands", "brand")

Both paths reach the same Registry.DeclareReference, so anything expressible in YAML is expressible in Go. ReferenceTarget(type, field), References(type) and AllReferences() read the declarations back as a registry lookup rather than a re-parse of the document, and ResolveReference(ctx, id, field) turns one object's field into the identities it names.

Three properties are closed on purpose:

• The holding side only. A reference is declared on the type whose provider actually returns the field. There is no inbound form on brand, because brand has no column listing its datasets — an inbound declaration would describe a derived view with nothing to attach to, and a second referencing field (archived_brands) would make the unnamed reverse edge ambiguous anyway.
• One descriptor kind. A reference names its target object-type and nothing else. There is deliberately no type: key: the loader is the single typing mechanism (a CSV column suffix, a cast in the developer's SQL), and a second place to declare a type is a second place for the two to disagree.
• Values are full canonical identities — "account:acme/brand:1", composed by the developer where the data is loaded, never a bare primary key Aperture would template. That is what lets the ordinary Filter.Fields contract match one with no new code: {"current_brands": "account:acme/brand:Y"} is just a membership test over a list of strings.

Declaring a reference on a field no object happens to carry is not an error — metadata fields are discovered at fetch, not declared, so it resolves to nothing. A value that does not point where the declaration says — a "team:7" in a field declared to hold brands — is an error (APERTURE_PROVIDER_REFERENCE_MISMATCH), because an enumeration that silently dropped it would read as "no access" and hide the fault. A target type with no registered provider is APERTURE_PROVIDER_REFERENCE_INVALID at build.

A seed document applies its references: blocks in a second pass, after every type is registered, so a reference may name a target declared further down the file or served by the objects: section. Like the rest of providers:, a declaration is runtime wiring: Apply writes none of it and an export reproduces none of it.

What a declaration buys: enumerating through it

Enumerate can be restricted to the identities a holder object's declared field contains:

aperture enumerate alice read 'account:acme/brand:*' \
  --seed ./model.yaml --via account:acme/dataset:x.current_brands

The mirror-image question — "which datasets contain brand Y?" — is a filter, not a dereference, and the metadata filter already answered it. The two look symmetric and are not: the dataset holds the field, so a predicate on dataset expresses that question; a brand holds no field naming its datasets, so no predicate on brand can express the first one at all.

Its security semantics are the reason the dereference lives in the engine rather than being a caller-side two-call workaround, and they are deliberately asymmetric:

• a holder the principal may not read yields an empty result and no error — "you may not see dataset X" and "dataset X contains nothing you may see" must be indistinguishable, or the edge is an oracle for objects the caller was never allowed to know about;
• an absent holder is APERTURE_NOT_FOUND only inside the request's account and only for a member — outside the account, or for a non-member, the answer is empty and never NOT_FOUND;
• a dangling identity (referenced, no longer served) is skipped, logged at warning, and noted as dangling_reference, never a failed decision;
• exactly one hop is taken, several edges AND, and the restriction is applied before limit.

A rules-engine dereference is deliberately not supported: Check owes a p99 under a millisecond, and a join on the decision hot path — with a recursive cache-miss path behind it — is a cost that belongs to the host's data rather than to the rule. Enumeration computes the restriction once, off that path.

The full model, including the exact ordering and the per-surface tests that pin it, is in skills/object-references.md.

Worked example: csvprovider

csvprovider implements ObjectProvider over a CSV file, so a host can wire real object data during development before pointing Aperture at its database. It is a drop-in adapter: register a *Provider under an object-type exactly as the SQL-backed provider is registered, and the Registry's cache, invalidation, and rules wiring are unchanged.

reg := provider.NewRegistry()
reg.MustRegister("brand", csvprovider.New("brands.csv"), provider.WithTTL(0))
reg.MustRegister("app",   csvprovider.New("apps.csv"),   provider.WithTTL(0))
// swapping to a database later changes only these two lines.

File shape

The first row is a header. One column must be named id and holds each object's canonical identity string; its terminal segment type is the object-type the provider is registered under. Every other column becomes a metadata field keyed by the column name. A column name may carry a type suffix so its cells are coerced to a real type the rules engine reads natively. The full grammar is:

name:type[<elem>][(delim)]

Scalar columns

id,category_id,seats:int,active:bool,budget:float
brand:1,electronics,40,true,15000.50
brand:5,books,12,false,3000
brand:23,garden,,true,

Scalar types are string (the default, no suffix), int (stored as int64), float (float64), and bool. An empty cell omits that field for the row, so a rule can supply its own default (row brand:23 above has no seats or budget).

Date columns

The types date and datetime declare a column to hold dates, so every cell is validated and canonicalised at load through provider.ParseDateValue:

id,tier,hired_at:date,last_seen:datetime
brand:1,gold,2026-03-04,2026-03-04T12:30:00Z
brand:2,silver,,

The point is where the failure lands. A typo'd or impossible date in an untyped column is a perfectly good string that no rule can compare, so it becomes a silent deny at decision time — months later, in production. Declared as a date it is a hard error on the line and column that hold it.

The canonical string is what is stored, not the cell as written: 2026-03-04T12:30:00.750Z and 2026-03-04T12:30:00 both become 2026-03-04T12:30:00Z. Two rows naming one instant are therefore one string, which is what makes a Filter.Fields equality predicate over the column mean anything. That predicate must itself be canonical; range querying is not a provider concern — rules are where date ranges live.

Four rules, each because the alternative is a silently wrong answer:

• The declared type fixes the granularity. A :date column rejects a timestamp and a :datetime column rejects a bare day, rather than quietly widening it to midnight. Write the midnight out.
• An explicit offset is a load error, not a conversion. 2026-01-01T00:00:00+05:00 means January 1st to whoever wrote it, and its UTC instant is 2025-12-31T19:00:00Z — converting silently moves the year. A Z suffix is accepted, and so is an offset-free timestamp (read as UTC).
• An empty cell omits the field, following the scalar rule (row brand:2 above has neither). An absent date differs meaningfully from any date, and a zero time would silently satisfy every before rule written against the column.
• A date-shaped string in a :json cell is not date-validated. :json is opaque structured data; only a declared column gets date treatment.

There is no :list<date> — arrays of dates are out of scope, and the suffix is rejected by name rather than by accident — and no time-of-day type. A rejection is APERTURE_CONFIG_INVALID naming the column, the line, and the field, carrying the provider.DateReason and the layout expected, and never the cell: a date is frequently personal data.

Array columns

The type list produces a real []any — the array of the value model — which is what makes "premium" in object.tags decide correctly instead of string-matching a delimited blob (a blob match also matches "premium-trial" and grants access it shouldn't):

id,tags:list,seats:list<int>,aliases:list(;)
brand:1,premium|launch,3|5,acme;acme-co
brand:2,,1,bcorp

Element typing is not decoration. The expression evaluator does no numeric/string coercion, so 5 in object.seats is false against the strings ["3","5"] — a silently wrong false, the worst failure mode an access-control engine has. :list<int> is what prevents it.

There is no escape syntax. A value that must contain the delimiter needs a per-column delimiter its data does not contain. A stray, doubled, leading, or trailing delimiter — how a delimiter inside a value looks to the parser — yields an empty element and is a hard error at parse, never a silently mis-split row.

An empty cell in a list column is the one departure from the scalar rule: it yields an empty list ([]), not an absent field, so a membership rule evaluates to a definite false rather than running against nil (row brand:2 above has tags: []).

Object columns

The type json parses its cell as JSON, so a rule can read a structured value with a dotted path — object.owner.dept. The cell must decode to a JSON object at the top level; an array, a scalar, or null is rejected, because list stays the only array path. That keeps "arrays hold scalars, objects hold structure" true everywhere and the operator set flat.

A JSON object contains commas and quotes, so the cell has to be quoted per RFC 4180 — the whole cell in double quotes, with every inner double quote doubled. encoding/csv handles this correctly; the part that trips authors up is writing it:

id,owner:json
brand:1,"{""dept"":""eng"",""lead"":""alice""}"
brand:2,"{""dept"":""ops"",""tags"":[""oncall"",""eu""]}"
brand:3,

Below the top level it is ordinary JSON, bounded by the value model's depth and size caps: {"dept":"eng","tags":["a","b"]} is fine (depth 2) and {"members":[{"id":1}]} is not — arrays of objects are rejected at any position.

Numbers follow the scalar columns exactly. The cell decodes through json.Decoder with UseNumber, so nothing is floated before the type is chosen, and each number then becomes an int64 when it is an exact integer that fits one (as :int and :list<int> produce) and a float64 otherwise (as :float and :list<float> produce). 3 is int64(3), 1.5 and 1e3 are float64, and 9007199254740993 survives as an exact int64 rather than losing its last digit. That consistency is what makes a cross-column comparison such as object.owner.seats == object.seats behave. A number no int64 or float64 can represent is a hard error, not a silent Inf.

An empty cell in a json column omits the field, following the scalar rule rather than the list rule (row brand:3 above has no owner): an object that is absent is meaningfully different from one that is empty, and reading an absent object is safe.

Errors

A missing id column, a duplicate id, a wrong column count, an unknown type or malformed type suffix, a value that will not coerce to its declared type, a list cell with an empty element, a json cell that is not valid JSON or does not decode to an object, or a date cell that is not a canonical date of its column's granularity is an APERTURE_CONFIG_INVALID error naming the column — and, for a cell, the line and the offending element. A malformed id passes through as the identity package's APERTURE_IDENTITY_INVALID. Every parsed value is then checked against the value model with provider.ValidateField, so a shape, depth, or size violation fails the load as APERTURE_METADATA_INVALID instead of surfacing as a runtime error on the Check hot path. A json cell's rejection carries the column, the line, and the JSON kind or the decoder's message; a date cell's carries the column, the line, the reason, and the layout expected. Neither ever carries the cell, which is host data — and, for a date, frequently personal data.

Loading and the read-only contract

The file is read once, lazily, on the first Fetch/List/Query and held in memory. New(path) never fails at construction — a bad file surfaces on first use (the file may not exist yet at wiring time). FromReader(r) builds an already-loaded provider from any reader (embedded data, tests). Reload re-reads the file, building a fresh set and swapping it in atomically, so maps already handed to and cached by the Registry stay immutable — honouring the "metadata is read-only" contract. That holds at depth: every list cell is parsed into a slice, and every json cell decoded into a map, allocated for that row alone, so no two rows — and no two loads — ever share one. After a Reload, call Registry.InvalidateType to drop the now-stale cache entries.

Query honours Filter.Pattern and Filter.Limit directly and hands Filter.Fields to provider.MatchFields, so it inherits the contract instead of restating it — a :list column matches by membership, everything else by typed equality, and a field absent from a row never matches:

p.Query(ctx, provider.Filter{Fields: map[string]any{"tags": "premium"}})  // rows whose tags contain premium
p.Query(ctx, provider.Filter{Fields: map[string]any{"ranks": 5}})         // a :list<int> column, matched by value
p.Query(ctx, provider.Filter{Fields: map[string]any{"tier": "gold"}})     // scalar equality

The column's declared type is what makes the second one work: :list<int> holds int64 elements, so 5 matches and "5" does not — the same answer a rule's in gives over the same data. The Registry re-enforces the pattern and limit, so honouring them in the provider is an optimisation that also keeps Query correct when called standalone.

Like the core packages, csvprovider imports only errors, identity, and provider plus the standard library — pure-Go and CGO-free.

Worked example: sqlprovider

sqlprovider implements ObjectProvider over a relational database, so a host serves its real objects from the tables it already has instead of exporting them to a CSV. It is a drop-in sibling of csvprovider — the Registry's cache, invalidation, and rules wiring are identical — and it is a host data source, unrelated to Aperture's own storage and sharing no connection handling with it.

db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))   // the host's driver, the host's pool
if err != nil {
    return err
}
defer db.Close()

brands, err := sqlprovider.New(db, sqlprovider.Config{
    ObjectType: "brand",
    FetchQuery: `SELECT tier, seats, to_jsonb(tags) AS tags FROM brands WHERE id = $1`,
    ListQuery:  `SELECT 'brand:' || b.id AS id, b.tier, b.seats FROM brands b`,
})
if err != nil {
    return err
}
reg.MustRegister("brand", brands, provider.WithTTL(30*time.Second))

A seed document declares the same thing in YAML with no Go code at all.

Cast it in the statement

This is the part a developer cannot skip. The statement is the only typing mechanism there is — there is no :int / :list<T> suffix here and no per-column type declaration in YAML, because the developer is already writing a SELECT list and two spellings for one intent drift apart. A column becomes a metadata field of whatever Go type database/sql scanned it into.

The trap this package cannot catch for you

Selecting an array column without casting it compiles, runs, and is wrong:

SELECT tags FROM brands WHERE id = $1        -- WRONG
SELECT to_jsonb(tags) AS tags FROM brands WHERE id = $1   -- RIGHT

A Postgres text[] does not arrive as a list. It arrives as the raw array literal — the string {a,b} — which is a perfectly valid metadata string, indistinguishable from a string a host meant to store. Nothing in the provider can tell them apart, so nothing will complain. What happens instead is that every membership predicate over that field silently matches nothing, forever, and the rule reads as though it never applies. If a list-valued field is matching nothing, check its cast first.

Driver values become metadata

The mapping from a scanned Go type to a metadata value is a closed table, not an inference — an inference would be a value the expression evaluator silently mis-compares:

A []byte is JSON unconditionally — it never falls back to a string, because a fallback would let one column change type depending on its contents. So a bytea column does not work: encode it in the statement (encode(bytes,'base64')) or leave it out. A time.Time is converted to UTC first, because a timestamptz comes back in the process's local zone, then routed through provider.ParseDateValue like every other loader's date. Numbers inside a JSON column normalise exactly as scalar columns do, so object.limits.seats == object.seats is not a silent false. Every mapped row is then checked against the value model.

Fetch, List, and the id column

Fetch binds the identity's terminal segment value, not the identity string — brand:42 and account:acme/brand:42 both bind "42" — so the statement can say WHERE b.id = $1 against the primary key it already has and hit its index. Placeholders are engine-native and passed through untouched ($1 for Postgres, ? for MySQL or SQLite); there is no dialect rewriting. Parameters are always bound, never interpolated — that is the SQL-injection boundary of the feature and it is not configurable.

Zero rows is APERTURE_NOT_FOUND; more than one row is APERTURE_SQL_PROVIDER_AMBIGUOUS and the first row is never silently taken, because without an ORDER BY which row that is would be unspecified, and an object's metadata must not vary between two identical Checks.

List and Query run a second statement that takes no parameters, and its id column carries each row's full identity. The id column takes a string, or a []byte read as raw text — deliberately unlike a metadata column, where a []byte is JSON, because the id is not metadata and has no competing JSON reading. A row Aperture cannot place — no id column, a NULL/empty/non-textual id, an unparseable identity, or an identity whose terminal segment type is not this provider's object-type — is APERTURE_SQL_PROVIDER_ROW_IDENTITY naming the row's position, never a row silently skipped. A short enumeration reads as "no access" one layer up, and a wrong-type row would be cached under an identity this provider's own Fetch could never return.

Query applies Filter.Fields with provider.MatchFields, in Go — the predicates are never templated into the developer's SQL. Comparison in the contract is typed ("5" != 5) and matches collections by membership, which is the rules engine's own semantics; Postgres would happily coerce '5' to 5, so a predicate rendered into SQL would answer a different question than the rule evaluated over the same field. The cost is honest: the whole object-type is materialised per enumeration, and the Registry's per-type TTL cache is what absorbs it.

Rows stream, and the limit stops the read. One consequence worth knowing: a Limit that truncates before a malformed row is reached will not surface that row's error — the same enumeration with a larger limit can fail where the bounded one succeeded. rows.Err() is checked unconditionally after the loop, so a connection that dies mid-result is never reported as a short but successful enumeration.

Timeouts and errors

Every statement runs under context.WithTimeout — DefaultTimeout is 5s — applied on top of the caller's own context, so the earlier deadline wins. A Fetch sits under Check, which owes a p99 under a millisecond; an unbounded query against a host database is not a slow decision but one that never returns. There is no "no timeout" setting.

Failures are APERTURE_SQL_PROVIDER_QUERY (driver or connection, wrapping the cause), _AMBIGUOUS, _SCAN, _ROW_IDENTITY, and — for the declarative wiring — _DSN_LITERAL and _CONNECTION. Every diagnostic names the developer's own inputs (the column, the object-type, the row's position, the identity) and never a row value, which is host data belonging to some account. An error already carrying an APERTURE_* code — one a host's wrapping Querier raised — passes through verbatim.

The Querier seam

The dependency is not a *sql.DB but a two-method interface:

type Querier interface {
    QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
    QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

A *sql.DB satisfies it, and so does an *sql.Conn, an *sqlx.DB, a pgx stdlib handle, a *sql.Tx, or a host's own tracing, retrying, or read-replica wrapper. On this path Aperture owns no connection lifecycle: it does not open, close, ping, pool, or configure anything. That is also why sqlprovider imports no driver — its dependencies are database/sql, errors, identity, and provider — so a host that never uses it pays nothing for it, and a host that does picks its own driver.

The seed package is the one place Aperture links a driver itself: github.com/jackc/pgx/v5/stdlib, through database/sql, Postgres only. It was chosen over lib/pq on a correctness argument despite costing far more binary — lib/pq returns []byte for numeric and uuid, which the value model cannot distinguish from jsonb, so a numeric of 1.50 would silently arrive as the float 1.5. Measured with the project's own build flags, lib/pq costs +96,432 bytes (+0.34%) and pgx +3,589,088 bytes (+12.5%); the whole SQL-provider epic took the stripped binary from 28,621,090 to 32,867,698 bytes (+14.8%). Both are pure Go, so CGO_ENABLED=0 holds.

For the full reference — the connection defaults, the pool-sharing rule, and the gated real-Postgres test — see the sql-provider skill document.

In-memory objects: provider.Static

Not every object set comes from a file. A seed document declares metadata inline, a test needs three objects and no fixture on disk, and an embedded demo has its data compiled in. provider.Static is the ObjectProvider for all three — the same semantics as csvprovider over a slice already in memory, so nothing has to be re-derived per caller:

p, err := provider.NewStatic([]provider.Object{
    {ID: identity.MustParse("account:acme/brand:1"),
        Metadata: provider.Metadata{"tier": "gold", "tags": []any{"premium"}}},
    {ID: identity.MustParse("account:acme/brand:2"),
        Metadata: provider.Metadata{"tier": "silver"}},
})
reg.MustRegister("brand", p, provider.WithTTL(0))

It is immutable after construction, which is what makes it safe for concurrent use with no lock and makes the read-only contract trivially true: there is no reload that could edit a map the Registry already cached.

Everything is checked at construction, so a Fetch/List/Query can never fail for a reason the caller could have been told about at wiring time. An empty or duplicate identity is APERTURE_PROVIDER_INVALID (a last-writer-wins duplicate is how one object's metadata becomes another's); metadata violating the value model is APERTURE_METADATA_INVALID naming the id, the field, and the offending path. Static does not re-implement the model — and it does not trust a caller that says it already validated.

Fetch returns APERTURE_NOT_FOUND for an undeclared id, List returns declaration order, and Query hands Filter.Fields to provider.MatchFields while honouring Pattern and Limit directly — the same contract every other provider implements.

Values are deep-copied in at construction and handed out by reference on every read. The copy is what makes the read-only contract hold against a caller that keeps its input: mutating those maps afterwards, at any depth, cannot reach metadata the Registry has already cached. Nothing is copied on the read path, which is the allocation-aware half of the same contract.

Where this leads

Providers feed three consumers documented elsewhere: the object metadata a rule reads, the object enumeration an implicit/exclusive scope performs, and — through the attribute seam — the principal.* and account.* roots the same rule reads about the asker. For the CLI that inspects registered providers, see the provisioning commands; for the one that inspects attribute slots and drops cached bags, see aperture attributes.

The RBAC domain model

Every authorization decision Aperture makes is resolved against a small, explicit graph of entities. They all live in the model package — the single place the domain is defined, and the package every storage backend implements through one Storage interface. The model couples only to the leaf packages errors/ and identity/; it holds no storage, engine, or transport concepts, so this graph is the same whether you drive it from the library, the CLI, Twirp, or MCP.

An account is a model entity, not a package of its own — tenancy is part of the domain, documented alongside the rest here.

The entities

How they relate

erDiagram
    ObjectType  ||--o{ Permission : "declares verbs for"
    Permission  }o--|| ScopeStrategy : "references"
    Role        }o--o{ Permission : "bundles"
    Principal   }o--o{ Role : "assigned"
    Group       }o--o{ Principal : "contains"
    Account     ||--o{ Membership : "has"
    Principal   ||--o{ Membership : "in"
    Account     ||--o{ Grant : "stamps"
    Grant       }o--|| Permission : "on"
    Grant       }o--|| Subject : "for"
    Subject     }o--|| Principal : "or"
    Subject     }o--|| Role : "or"
    Subject     }o--|| Group : "binds"

A Subject is not a stored row of its own — it is a {Kind, ID} value carried on the grant, where Kind is one of principal, role, or group. At decision time the engine expands the request's principal into a subject set — the principal itself, the roles on Principal.RoleIDs, and the groups that list the principal — and resolves grants against that whole set.

Object types and typed actions

An ObjectType names an identity-segment type and declares a closed verb set in Actions. The verb set is authoritative: a Permission may only name an action the object type declares. Declaring a permission against an undeclared verb is rejected with APERTURE_ACTION_UNDECLARED. This typed-action validation means a typo in an action never silently becomes an unmatchable permission — it fails at write time.

{ "name": "document", "actions": ["read", "write", "delete", "aperture.delegate"] }

An object type opts a resource into delegation or impersonation by declaring their reserved verbs (aperture.delegate, aperture.impersonate.augment, aperture.impersonate.become) and a permission on each.

Permissions

A Permission is an (action, scope-strategy) pair bound to one object type. The ScopeStrategy field is an opaque reference resolved by the scope layer — it decides which objects within a grant's pattern the permission reaches. The Delegatable flag is an opt-in, fail-closed gate: a permission cannot be handed to another principal via bestow until it is explicitly flagged, so the right to delegate never leaks to permissions whose authors did not intend it.

Grants: subject × permission × object × effect × account

The Grant is the binding that actually confers (or withholds) access. It is the load-bearing entity, so its shape is worth reading closely:

• Subject — what the grant applies to: a principal, role, or group.
• PermissionID — the granted permission (which fixes the action and scope strategy).
• Object — an identity pattern in string form, e.g. account:acme/project:atlas/**. Wildcards and explicit id-sets (brand:{1,5,23}) are first-class, so one grant can scope broadly or to a handful of ids without many grants. The engine parses it with identity.ParsePattern.
• Effect — allow or deny. At decision time a matching deny overrides allows at equal-or-broader specificity, with a specificity tiebreak resolved by the pattern.
• AccountID — mandatory. It stamps the grant to one account.

Accounts and the isolation invariant

Accounts are global entities, and a single principal can belong to more than one (via Membership). The core tenancy rule is the (principal, active-account) isolation invariant: a principal's grants in one account never apply in another, because every grant query is account-scoped. A Membership edge says only that a principal is in scope in an account — not what it may do there (that is grants); the engine can optionally deny a request whose principal is not a member of the active account, as defence in depth.

The lone, deliberate exception is the account wildcard * (model.AccountWildcard): a grant stamped to * is loaded for decisions in every account. It is not a real account — ValidateAccount rejects * as an account id so no row can shadow the wildcard — and only a system-tier admin can mint one.

Because grants are account-stamped and queries account-scoped, error messages and decision output must never surface another account's data. Keep examples single-account.

Templates: provisioning many grants at once

A Template is a named, versioned bundle of parameterized grants. It declares typed Params (each a segment — an identity component — or a free string) and a set of TemplateGrants whose subject ids and object patterns reference those params with ${name} tokens. At apply time the params are filled with concrete values, tokens are substituted, and the bundle expands to a set of concrete Grants stamped to a target account and applied transactionally.

• A template is identified by the (Name, Version) pair; storing a new version keeps older ones intact, so an apply can pin a version while new provisioning uses the latest.
• Expansion is all-or-nothing: a missing, unknown, or ill-typed param — or any expanded grant that fails validation — aborts with no grants written, so a partial expansion can never be applied.
• The default grant-id prefix is <name>-v<version>, so re-applying with the same prefix upserts (idempotent provisioning) rather than duplicating.

Apply a template from the CLI; the same expansion runs behind the Twirp and library surfaces.

Rules

A Rule is a named, persisted decision AST stored verbatim as canonical JSON — the exact serialization the rules engine marshals. The model layer keeps it opaque (a json.RawMessage) so it stays free of an engine dependency; it validates only that the name is non-empty and the AST is a JSON object. Type-checking and compilation are the rules engine's job. A scope strategy names a rule to make membership rule-driven.

Validation and persistence

Every entity has a Validate* function that runs before persistence — non-empty ids, valid enum values, parseable identities and patterns, typed-action checks. Structural failures are APERTURE_INVALID_INPUT; the specialized codes (APERTURE_ACTION_UNDECLARED, APERTURE_TEMPLATE_INVALID, APERTURE_RULE_INVALID, …) name the specific rule that was broken. The Storage interface is the single seam behind which the in-memory and SQLite backends live; validation guarantees a malformed entity never reaches the decision hot path.

Where this leads

• Mutate these entities from the shell: CLI mutations.
• Grant a subset of your authority to someone else: Delegation.
• Borrow another principal's authority: Impersonation.
• Turn a grant's pattern into a concrete object set: Scopes.
• Resolve a request into a verdict: the Decision API.

Delegation ("bestow")

Delegation lets a principal hand a slice of the authority it already holds to another principal — without privilege escalation and without crossing an account boundary. Aperture calls the grant-forward operation bestow and its inverse revoke. The code lives in the delegation package; drive it from the CLI with bestow / revoke.

The defining property: a bestowed grant is an ordinary account-scoped grant. There is no special storage and no special decision path — once bestowed, the engine treats it exactly like any other grant, and it vanishes outside its account like any other grant, because every grant query is account-scoped.

Delegation is itself a permission

There is no magic "admin can delegate" flag. The right to delegate is a normal grant on a normal permission whose action is the reserved verb aperture.delegate (delegation.DelegateAction). A principal "may delegate" within an account when its effective grant set holds an allow grant on that action whose object pattern covers the object being bestowed. So the right to delegate is scoped exactly like every other permission — a delegate grant over account:acme/project:atlas/** authorizes bestowing only within that subtree.

An object type opts a resource into delegation by declaring the aperture.delegate verb and defining a permission on it.

The bestow rule

Bestow is conjunctive and fail-closed. A delegator may bestow a grant G only when all four conditions hold, checked against the delegator's (delegator, account) effective grant set:

flowchart TD
    B["Bestow(delegator, G)"] --> M{"delegator is a member<br/>of G's account?"}
    M -->|no| D1["DENIED: cross_account"]
    M -->|yes| Del{"may-delegate right<br/>covers G's object?"}
    Del -->|no| D2["DENIED: no_delegate_right"]
    Del -->|yes| Flag{"G's permission<br/>is Delegatable?"}
    Flag -->|no| D3["NOT_DELEGATABLE"]
    Flag -->|yes| Sub{"delegator holds an allow<br/>with G's action + scope strategy<br/>whose object ⊇ G's object?"}
    Sub -->|no| D4["DENIED: not_subset"]
    Sub -->|yes| OK["grant written<br/>as an ordinary grant"]

1. Account membership — the delegator is a member of G's account. A bestow stamped to any other account is rejected up front (a cross-account leakage guard, and defence in depth over the already account-scoped grant query).
2. May-delegate — the delegator holds an effective allow grant on aperture.delegate whose object pattern covers G's object.
3. Delegatable — G's underlying permission is flagged Delegatable. This is the model's opt-in gate; a permission is non-delegatable until explicitly flagged.
4. Subset — the delegator holds an effective allow grant with the same action and scope strategy as G's permission, whose object pattern covers G's object. In other words, G must be a subset of the delegator's own authority — never broader.

Only allow grants may be bestowed; a delegated deny is out of scope. Any failure returns an APERTURE_DELEGATION_* coded error naming the first broken condition (APERTURE_DELEGATION_DENIED with a reason, or APERTURE_DELEGATION_NOT_DELEGATABLE) and writes nothing.

"Covers" is pattern containment

"⊇" throughout is identity.Contains: the target's object pattern must be equal-or-more-specific than — that is, contained within — the delegator's. A more-specific pattern under the delegator's authority is a subset; a broader-or-disjoint one is not. The containment test is conservative (sound, possibly incomplete): when authority cannot be proven, the bestow is denied. A delegator holding a deny grant confers nothing to hand on — only allow grants are considered when computing what the delegator may bestow.

Revoke

Revoke is the inverse mutation and is gated by the same authority check Bestow applies. A delegator may revoke only a grant it could itself bestow now — so revocation can never be used to reach across accounts or beyond the delegator's own scope. Revoking an unknown grant is APERTURE_NOT_FOUND.

Worked example

Alice holds two allow grants in account acme: a delegate right and a read right, both over account:acme/project:atlas/**, on a Delegatable read permission. She bestows a narrower read grant on Bob:

export APERTURE_PRINCIPAL=alice
bin/aperture bestow --delegator alice --json '{
  "id": "g-bob-read-42",
  "accountId": "acme",
  "subject": {"kind": "principal", "id": "bob"},
  "permissionId": "perm-doc-read",
  "object": "account:acme/project:atlas/document:42",
  "effect": "allow"
}'

This passes all four checks: Alice is a member of acme; her delegate right covers document:42; perm-doc-read is delegatable; and her own read grant over .../atlas/** contains the narrower .../atlas/document:42. Had Bob's object been account:acme/project:atlas/** (equal to or broader than Alice's), the subset check would deny it.

Related

• The RBAC model — grants, permissions, the Delegatable flag.
• Identity patterns — how containment and specificity are decided.
• CLI mutations — the bestow / revoke commands.
• The service facade — how surfaces reach the gated delegation service.

Impersonation

Impersonation lets a privileged operator borrow another principal's authority for a decision — to reproduce what a user sees, or to act on their behalf — under hard guardrails and a strict time-box. This chapter is the conceptual half: what the two modes mean, how a session is gated, and how it expires. For the engine API that consumes a session (CheckAs / EnumerateAs / ExplainAs and the ImpersonationContext shape), see the library reference.

The feature has two halves. The impersonation package starts and gates a session; the engine's *As entry points consume it. A session never mutates stored grants — it only steers which subject set a decision resolves over.

Two modes: augment vs become

flowchart LR
    subgraph augment["AUGMENT"]
        A1["operator subjects"] --> AU["∪"]
        A2["target subjects"] --> AU
        AU --> AR["decision resolves<br/>over the union"]
    end
    subgraph become["BECOME"]
        B1["target subjects<br/>alone"] --> BR["decision resolves<br/>as if the target asked"]
    end

• Augment adds the target's effective permissions to the operator's own. The operator keeps acting under its own identity, and the decision resolves over the union of both subject sets. Use it to "see what they can see" while retaining your own authority.
• Become fully assumes the target's identity: the decision resolves over the target's subject set alone, as if the target had asked. The operator's own grants do not apply.

Become is strictly stronger than augment, and that ordering drives the gating rule below.

The mode also decides whose attributes a rule reads. A rule-backed scope strategy evaluates against the effective subject: under become that is the target — principal.id is the target's id and the target's kind picks the attribute slot principal.tier and friends come from — and under augment it is the operator, which is what "keeps acting under its own identity" means. The grant set and the rule always describe the same principal; a decision that resolved the target's grants while reading the operator's attributes would be an authorization bug invisible in a trace. This does not touch the audit trail: the real operator is recorded either way (see below). Under become, principal.id therefore means the target — a deliberate change in v0.8.0.

Impersonation is a permission — and become needs the stronger right

Like delegation, impersonation is gated by ordinary grants on reserved action verbs. Two verbs gate the two modes:

An operator "may impersonate" a target when its effective allow grant set holds the mode's right whose object pattern covers the target principal's identity (identity.Contains). The strictly-stronger rule:

• Become requires an allow on aperture.impersonate.become covering the target.
• Augment requires an allow on aperture.impersonate.augment or aperture.impersonate.become covering the target — so holding the become right implies the augment right (a become-holder can do either), but the augment right alone can never become a target.

An object type opts a principal type into being impersonable by declaring these verbs and defining a permission on each.

Starting a session: the guardrails

Start(operator, target, account, mode) gates and issues a session. The guardrails are conjunctive and fail closed — every one must hold, checked against the operator's (operator, account) effective grants:

1. Account boundary — both the operator and the target are members of the active account. A session spanning accounts is refused; there is no cross-account impersonation. (The engine independently re-checks this on every decision, so a forged context cannot bypass it.)
2. Right held — an effective allow grant on the mode's action (or, for augment, the stronger become action) whose object pattern covers the target's identity.

A failure returns APERTURE_IMPERSONATION_DENIED naming the failed guard in the error context (operator_not_member, cross_account, no_become_right, no_augment_right). Empty inputs or an unknown mode are APERTURE_INVALID_INPUT.

Expiry: a hard, short time-box

Impersonation is a privileged, transient act, so every session carries an expiry. Start stamps ExpiresAt = now + ttl, where ttl defaults to DefaultTTL — 15 minutes — and can be overridden per service with WithTTL (a non-positive ttl is ignored, so a session is always bounded). The clock is injected, so tests never touch the wall clock.

The ExpiresAt instant travels with the session into the engine, so the engine enforces the time-box itself:

• A session presented after its expiry confers no elevation. Instead of the target's authority, the decision fails closed to the operator's own authority — an expired become never resolves as the target. Elevation never outlives its time-box.
• A surface that would rather reject an expired session up front — instead of silently resolving with no elevation — calls Session.Live(now), which returns APERTURE_IMPERSONATION_EXPIRED once the session is past its expiry.

Every resulting decision records both the real operator and the effective subject for the audit layer — impersonation is never silent.

Starting one from the CLI

bin/aperture impersonate --operator root --target alice \
  --account acme --mode augment

This prints the session (operator, target, account, mode, and expiry) as JSON. The command is guarded exactly as above: an operator with no right covering alice is denied with APERTURE_IMPERSONATION_DENIED. See CLI mutations.

Related

• Library: Impersonation — the *As engine API and the ImpersonationContext decorator this conceptual page complements.
• The RBAC model — subjects, grants, and reserved action verbs.
• Delegation — the sibling "grant a subset of your authority" feature, gated the same way.
• The service facade — how surfaces reach the gated impersonation service.

Filtering entity lists

The filter package applies server-side field predicates to a list of entity JSON bodies before they are returned to a client. It is the business logic behind the admin UI's data-grid filters: the client sends a Spec (a set of predicates), the server evaluates it against each entity, and only the matches cross the wire. Rows filtered out are never sent — the filter runs where the data lives, not in the browser.

Why it is dynamic, not per-type

Aperture's entities are heterogeneous — accounts, principals, roles, grants, and so on. Rather than a typed filter per entity, filter addresses fields by their JSON key and evaluates over the decoded map[string]any. One predicate engine works across every entity list. Two consequences fall out of this:

• Text comparisons are case-insensitive. Both the field value and the predicate value are lower-cased before comparing.
• Array fields match if any element satisfies the predicate. A principal's roles array matches roles contains admin when any single role does. JSON numbers and booleans are rendered to strings for the comparison (an integer prints without a trailing .0).

Predicates and the spec

A Predicate is one field test — a Field (JSON key), an Op, and a Value:

type Predicate struct {
    Field string
    Op    string
    Value string
}

type Spec struct {
    Predicates []Predicate
    MatchAny   bool // OR when true; AND (the default) when false
}

A Spec combines its predicates with AND by default, or OR when MatchAny is set. Spec.Empty() reports whether the spec would constrain nothing, so a caller can skip the work entirely.

The operators

The operator set is deliberately small — "core":

For empty, a field counts as empty when it is absent, null, an empty string, or an empty array. For the three value operators, a predicate with an empty Value is treated as unusable and ignored. An unknown operator also makes its predicate a no-op — it is simply skipped, never an error.

Evaluation and the fail-open rule

Apply(entities, spec) returns the subset of entities (each a JSON object body) that satisfy the spec:

• An empty spec — no usable predicates — returns the input unchanged.
• Usable predicates are collected; then each entity is decoded and tested, combining predicate results with AND or OR per MatchAny.
• An entity whose JSON does not decode to an object is kept. This is the deliberate fail-open rule: a filter must never silently hide a row it could not evaluate. (Contrast the decision engine, which fails closed; a display filter is not an authorization boundary, so it errs toward showing data rather than hiding it.)

matches := filter.Apply(bodies, filter.Spec{
    Predicates: []filter.Predicate{
        {Field: "kind", Op: filter.OpEq, Value: "user"},
        {Field: "roles", Op: filter.OpContains, Value: "analyst"},
    },
    // MatchAny false → both must hold (AND).
})
// matches holds only the user principals that carry an "analyst" role.

Scope note

filter narrows a list the caller is already authorized to see — it is a display convenience, not an access-control gate. The authorization decision that determines which entities a caller may list at all is made upstream by the decision engine; a grant's own object membership is decided by scope strategies. Because the lists a filter runs over are account-scoped upstream, filtering never widens visibility across the account isolation boundary.

Related

• The RBAC model — the entities whose JSON bodies are filtered.
• Scopes & scope strategies — the authorization-side "which objects" question, distinct from display filtering.
• Admin UI shell — the data-grid this filtering backs.

Authentication

The auth package turns an incoming external credential into a known Aperture principal. Authentication is always external: Aperture consumes credentials, it never issues them. There is no login, signup, or credential-issuance surface — a caller arrives already holding a bearer token, and auth decides who that token names.

The Authenticator seam

Every adapter implements one small interface:

type Authenticator interface {
    Authenticate(ctx context.Context, bearer string) (principalID string, claims Claims, err error)
}

The input is the raw bearer token — the value after Bearer in the Authorization header. The HTTP middleware in internal/server extracts it from the request and calls Authenticate; on success it attaches a Principal to the request context. Handlers (and the decision surface) recover the caller with PrincipalFromContext.

type Principal struct {
    ID     string // the resolved Aperture principal id
    Claims Claims // the verified assertions behind it (empty for dev)
}

Claims is always a generic map[string]any, keyed by claim name, so downstream code reads any claim uniformly regardless of which adapter produced it.

Every adapter fails closed. A missing, malformed, or unverifiable credential is an error, never a silently-empty principal:

• an empty or unresolvable credential → APERTURE_UNAUTHENTICATED
• a presented credential that fails verification → APERTURE_INVALID_TOKEN

An anonymous request (no credential at all) surfaces as ok == false from PrincipalFromContext; callers that require a principal treat that as APERTURE_UNAUTHENTICATED.

The claim → principal mapping

The two verifying adapters (OIDC and Parsec) resolve the principal id through the same configurable mapping: PrincipalClaim names which verified claim — sub, email, or a custom claim — becomes the Aperture principal id. Which claim is the principal is configuration, not code. It defaults to sub when unset.

A verified token that does not carry the configured claim (or carries it empty, or non-string) is APERTURE_UNAUTHENTICATED — the token verified, but it does not name a principal Aperture can use.

The dev adapter is the one exception by construction: its bearer is the principal, so there is no claim to map.

The three adapters

dev / static (NewDev)

Trusts any non-empty bearer as the principal id — Authorization: Bearer alice resolves to principal alice. It performs no verification and returns nil claims. This is the adapter that makes Aperture runnable with no external IdP: fixtures, demos, and CI. It is the default when no auth mode is configured.

It is a development / single-tenant trust shortcut, not a security boundary. Never select it for a deployment facing untrusted callers. Even so, it still fails closed on an empty bearer.

oidc / JWT (NewOIDC)

Verifies a bearer JWT against an OIDC provider's published keys using the pure-Go github.com/coreos/go-oidc verifier: signature, issuer (iss must equal Issuer), audience (aud must contain Audience), and expiry. Signing keys are established up front — by JWKS discovery against Issuer, or from an explicit JWKSURL when the provider has no discovery document — so per-request verification is offline against the cached key set.

Issuer and Audience are both required: an empty audience would accept tokens minted for any client. Discovery performs network I/O, so Build/NewOIDC take a ctx. A missing issuer or audience is APERTURE_CONFIG_INVALID; a discovery failure at startup is APERTURE_BOOT.

parsec (NewParsec)

Verifies a token minted by the in-house github.com/frankbardon/parsec token broker against the broker's signing keyring. This is Orbit's realtime token-broker pattern: the broker issues a client a short-lived access token, and Aperture loads the same keyring to verify that token and learn who the caller is.

The keyring is the integration seam — the broker and Aperture must share it, because a parsec key carries a per-key id (kid) the verifier matches the token against. Point Aperture at the broker's persisted keyring exactly one of two ways (KeyringPath wins):

• KeyringPath — the broker's keyring.json directly.
• StateDir — the broker's state directory, inside which keyring.json is resolved (the Orbit serve.go shape, StateDir = <DataDir>/parsec).