Authority Revocation Bundle

Audience: Authority operators, Offline Kit / air-gap mirror maintainers, integrators consuming revocations. Scope: The on-disk revocation bundle format, its deterministic formatting and signing rules, and the CLI/API surface for exporting and verifying it.

The Authority service exports revocation information as an offline-friendly JSON document plus a detached JWS signature. Operators can mirror the bundle alongside Concelier exports so that air-gapped scanners receive the latest token, subject, and client revocations during the same sync pass.

File layout

All hashes and signatures are generated after applying the deterministic formatting rules below.

Deterministic formatting rules

• JSON is serialised with UTF-8 encoding and 2-space indentation. Object keys are emitted in a fixed, explicitly declared order (RevocationBundleModel/RevocationEntryModel annotate every property with [JsonPropertyOrder]), not lexicographically. Only free-form maps — the top-level metadata object and each entry’s metadata — are key-sorted, because they are serialised from a SortedDictionary.
• Arrays are sorted by deterministic keys:
  • Top-level revocations sorted by (category, id, revokedAt).
  • Nested arrays (scopes) sorted ascending, unique enforced.
• Numeric values (sequence) are emitted without leading zeros.
• Timestamps use UTC ISO-8601 format with Z suffix.

Consumers MUST treat the combination of schemaVersion and sequence as a monotonic feed. Bundles with older sequence values are ignored unless bundleId differs and issuedAt is newer (supporting replay detection).

Revocation entry categories

The schema (revocation_bundle.schema.json) enumerates four categories. Two are emitted by the current builder; the other two are reserved by the schema for forward-looking use but are not produced by any Authority code path today.

reason is a machine-friendly code constrained to the schema pattern ^[a-z0-9_.-]{1,64}$ (lower-cased on export); observed values include compromised, rotation, and lifecycle. When the source revocation has no reason recorded, the builder emits unspecified. reasonDescription may include a short operator note (max 256 chars).

Detached JWS workflow

1. Serialise revocation-bundle.json using the deterministic rules.
2. Compute the lower-case hex SHA-256 digest of the canonical bytes; write it to revocation-bundle.json.sha256 (the CLI prefixes it as sha256:<hex>).
3. Sign using ES256 (default, or Signing.Algorithm when overridden) with the configured Authority signing key (Signing.ActiveKeyId). The detached JWS header carries the following claims (serialised compactly by the signer; shown expanded here for readability):

   {
     "alg": "ES256",
     "kid": "{signingKeyId}",
     "provider": "{providerName}",
     "typ": "application/vnd.stellaops.revocation-bundle+jws",
     "b64": false,
     "crit": ["b64"]
   }
   

4. Persist the detached signature payload to revocation-bundle.json.jws (per RFC 7797).

Verification steps:

1. Validate revocation-bundle.json against the schema.
2. Re-compute SHA-256 and compare with .sha256 (if present).
3. Resolve the signing key from the Authority JWKS endpoint (/jwks, advertised in /.well-known/openid-configuration) or the offline key bundle, preferring the provider declared in the JWS header (provider falls back to default).
4. Verify the detached JWS using the resolved provider. The CLI mirrors Authority resolution, so builds compiled with StellaOpsCryptoSodium=true automatically use the libsodium provider when advertised; otherwise verification downgrades to the managed fallback.

CLI verification workflow

Use the bundled CLI command before distributing a bundle:

stella auth revoke verify \
  --bundle artifacts/revocation-bundle.json \
  --signature artifacts/revocation-bundle.json.jws \
  --key etc/authority/signing/authority-public.pem \
  --verbose

The verifier performs three checks:

1. Prints the computed digest in sha256:<hex> format. Compare it with the exported .sha256 artefact.
2. Parses the detached JWS header, confirms it advertises b64: false, captures the provider and kid hints, and reads the signing algorithm from the alg header (defaulting to ES256 when absent). The CLI verifies with the algorithm carried in the header; it does not have the Authority’s runtime configuration to compare against.
3. Registers the supplied PEM key with the crypto provider registry and validates the signature (falling back to the managed provider when the hinted provider is unavailable).

A zero exit code means the bundle is ready for mirroring/import. Non-zero codes signal missing arguments, malformed JWS payloads, or signature mismatches; regenerate or re-sign the bundle before distribution.

Example

The repository contains an example bundle demonstrating a mixed export of token, subject, and client revocations. Use it as a reference for integration tests and tooling. Note that the subject entry is illustrative: it is valid against the schema, but no current Authority code path emits subject revocations (see Revocation entry categories).

Operations Quick Reference

• stella auth revoke export emits a canonical JSON bundle, .sha256 digest, and detached JWS signature in one command. Use --output to write into your mirror staging directory.
• stella auth revoke verify validates a bundle against an offline PEM key (--bundle, --signature, and --key are all required), honours the provider metadata embedded in the signature, and reports the computed digest before distribution.
• GET /internal/revocations/export provides the same payload for orchestrators that already talk to the bootstrap API. The bundle is returned base64-encoded inside a JSON envelope (bundle.data) alongside the signature (with algorithm, keyId, provider, value) and digest (sha256). Like all /internal/* routes it is guarded by the bootstrap API key (BootstrapApiKeyFilter) and only mounted when Bootstrap.Enabled is set — it is not scope-gated.
• GET /api/v1/authority/revocation/status returns read-only bundle metadata for gateway/operator verification fan-out: entryCount, bundleDigest, lastIssuedAt, and lastSigningKid. It requires authority.revocation.read and never returns token identifiers.
• POST /internal/signing/rotate (also bootstrap API-key gated) rotates JWKS material without downtime; always export a fresh bundle afterward so downstream mirrors receive signatures from the new kid.
• Offline Kit automation should mirror revocation-bundle.json* alongside Concelier exports so agents ingest revocations during the same sync pass.