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"] }

SearchRequest — resolving a name to an id

Search is the call to make when a question arrives in a person's own words and every step after it needs ids.

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

{ "matches": [
    { "object": "account:acme/brand:42", "score": 0.875,
      "field": "label", "value": "Nike, Inc.",
      "metadata": { "label": "Nike, Inc.", "sector": "Footwear" } }
] }

The result is already scoped — do not filter it client-side. Candidates are decided before they are scored, by the same walk Enumerate uses, so the matches are always a subset of what Enumerate would return for the same account, principal, action and pattern. The alternative shape — enumerate a type over the wire, then match in your client — puts the unscoped set across the boundary first and narrows it second, and any bug in that client-side filter turns your surface into an enumeration oracle for every object in the system.

A score ranks; it never authorizes. Nothing in Aperture reads one. A client that acts on a returned id still calls Check.

Matching is case- and punctuation-insensitive (Nike, Inc. matches nike inc) and tolerates a typo or transposition. Only text is matched — a string field and the string elements of a list field; match a number, bool or date through fields instead.

Each match's metadata is the object's full bag, encoded exactly like EnumerateRequest.fields and carrying the same caveat: a google.protobuf.Value holds a number as a double, so an integer beyond 2^53 loses precision in transit. It rides along so labelling a result set costs no further round-trip.

Search requires the deployment to have an object-metadata source wired. Without one the answer is APERTURE_PROVIDER_UNREGISTERED, never an empty matches list — an empty list reads as "you may see nothing" and would hide the misconfiguration.

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)

Deployment posture and health

WiringPosture is the deliberate counterpart to Capabilities: the same kind of question, the opposite answer about who may ask. It is gated, and not a field on CapabilitiesResponse, because it carries mutable runtime state about a FAULT whose useful half is a duration — and because "this instance has been enforcing configuration its operator already replaced, for four hours" tells an anonymous caller that the enforced policy is not the intended policy, and how long the window has been open.

It takes an Actor rather than Empty for the reason every other system-tier call does: system-admin authority resolves in the caller's active account, and only the caller knows which of its accounts that is. The principal on the wire is ignored as always.

Sweep both. Equal digest across a fleet means the same push landed; equal digest and equal local_digest means the two instances were built from the same configuration. Neither field carries a path, an account, a principal or an object — both are hashes.

Every field is empty or false on a healthy instance, so "nothing is wrong" needs no interpretation. An instance that does not poll — and a server whose facade was built without a recorder — answers with polling: false, stale: false rather than refusing, so the read is usable as a fleet-wide probe. Nothing here carries model data: digests, durations, counts and coded errors only.

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.