BBramaDocs

Brama core contract: configuration, secrets, telemetry

Authorization and observability

The public workflows are only as trustworthy as the configuration that admits them, the secret handling behind them, and the record they leave. This page states all three.

Configuration contract

Startup configuration is generated, not hand-authored. It must:

  • reject missing, malformed, empty, duplicate, unknown, or contradictory client identities and alias policy;
  • use exact model allowlists without wildcards;
  • validate capability IDs and expected resource tuples before redemption;
  • keep direct and subscription capability names separate;
  • reject non-HTTPS provider origins except explicit loopback overrides;
  • reject untrusted forwarded transport headers;
  • expose build identity and non-secret configuration categories without exposing bearer, HMAC, OAuth, or provider material;
  • require a restart after startup policy changes.

A security, credential, provider, identity, or storage decision either uses the configured source or refuses. No other source is put in its place, and the refusal reaches both the caller's answer and the log.

The route registry document

The registry has exactly three known top-level fields: schema_version, deployments and routes. The current schema_version is the number one. routes maps an alias to its single destination — one alias, one route, with nothing standing behind it. An unknown top-level field is refused by the deserializer, so a document carrying anything else is rejected whole and every alias then reports routes_file_invalid.

Apart from the version line, which the loader supplies and validates, the document reads like this:

{
  "deployments": {
    "primary": "anthropic"
  },
  "routes": {
    "best": "anthropic/claude-sonnet-4-5",
    "fast": "openai/gpt-4o-mini"
  }
}

Two admin endpoints edit it, and both answer {"ok":true,"routes":<document>}:

  • PUT /v1/admin/routes takes exactly {"alias","primary"}; an unknown field is refused with the deserializer's own sentence;
  • DELETE /v1/admin/routes takes {"alias"}.

An operator whose file predates this shape does not edit it by hand. brama routes migrate reads the configured document, keeps only the three known top-level fields, validates the result and commits it with the same atomic owner-only replacement the admin endpoints use. It is idempotent and prints the document it committed. GET /v1/aliases then reports each row as {"alias","state","route","reason","required","authorized","last_answer","concurrency"}, and brama aliases prints the alias, its state and its route.

Authorization and secrets

Authorization is enforced at ingress and mutation boundaries. One valid bearer never implies agent authority. One agent identity never grants access to another agent's path or subscription. Brama receives only capability handles until the final-use seam, accepts bounded secret bytes from the owner-bound socket, and zeroizes scoped OAuth material.

Donation accepts secret input only in the authorized request body, passes it to the entitlements router through child stdin, and stores only non-secret metadata in Brama's overlay. Logs and errors must never include the donated value.

Alias authority is part of this boundary, not a routing convenience. A bearer whose allowlist does not name an alias is answered 403 forbidden; naming an allowed alias reaches exactly the one route the registry records for it, and never a route the caller was not authorized for. GET /v1/aliases reports the required and authorized fields for precisely this reason.

Observability contract

Secret-free build identity is available through brama version and /health. A routing event records bounded fields:

  • request correlation ID;
  • client identity and routing mode;
  • requested logical model and the canonical route it resolved to;
  • provider and attempt count;
  • success or failure class, retryability, latency, and token totals;
  • whether operator action is required.

A refused alias is recorded the same way: the event names the alias, the one route it resolved to, and the state that made it unserviceable, which is the same pair the caller reads in details.

The provider usage report reader is logged under its own plan_usage_* events, and the operator-triggered completion probe under usage_probe_*, each naming the subscription, the provider, and the provider's refusal when there was one, so a request nobody made is never read as a caller's traffic.

Do not log bearer values, HMAC signatures, capability IDs, raw credentials, request bodies, prompt text, raw provider payloads, or donated secrets. /stats is bearer-protected. Process telemetry is not durable billing evidence.

Where to go next