Add authority bootstrap flows and Concelier ops runbooks
This commit is contained in:
@@ -43,6 +43,7 @@ Consumers MUST treat the combination of `schemaVersion` and `sequence` as a mono
|
||||
{
|
||||
"alg": "ES256",
|
||||
"kid": "{signingKeyId}",
|
||||
"provider": "{providerName}",
|
||||
"typ": "application/vnd.stellaops.revocation-bundle+jws",
|
||||
"b64": false,
|
||||
"crit": ["b64"]
|
||||
@@ -54,8 +55,28 @@ 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 JWKS (`/.well-known/jwks.json`) or the offline key bundle.
|
||||
4. Verify the detached JWS using the stored signing key (example tooling coming with `stella auth revoke verify`).
|
||||
3. Resolve the signing key from JWKS (`/.well-known/jwks.json`) 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:
|
||||
|
||||
```bash
|
||||
stellaops 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. Confirms the detached JWS header advertises `b64: false`, captures the provider hint, and that the algorithm matches the Authority configuration (ES256 unless overridden).
|
||||
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
|
||||
|
||||
@@ -64,7 +85,7 @@ The repository contains an [example bundle](revocation-bundle-example.json) demo
|
||||
## 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 using cached JWKS or an offline PEM key and reports digest mismatches before distribution.
|
||||
- `stella auth revoke verify` validates a bundle using cached JWKS or an offline PEM key, honours the `provider` metadata embedded in the signature, and reports digest mismatches before distribution.
|
||||
- `POST /internal/revocations/export` provides the same payload for orchestrators that already talk to the bootstrap API.
|
||||
- `POST /internal/signing/rotate` 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 Feedser exports so agents ingest revocations during the same sync pass.
|
||||
|
||||
Reference in New Issue
Block a user