113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
# signing-service
|
|
|
|
HTTP service that implements `POST /api/v1/sign/dsse` per
|
|
[ADR-0005](../../docs/adr/0005-signing-service-and-transparency-log-api.md). It
|
|
canonicalises an in-toto v1 Statement, DSSE-signs it with the key named by
|
|
`key_ref`, and returns the envelope plus a stable `content_hash` that the
|
|
admin-api and other clients use as the single attestation reference.
|
|
|
|
## Status
|
|
|
|
- **Signing is real**: Ed25519 PAE + envelope + content_hash. Verified
|
|
end-to-end against the admin-api `attest.HTTPSigner` client via a Go
|
|
interop test that re-verifies the signature with the server's public key.
|
|
- **In-memory keyring**: `-backend=memory`. Ephemeral keys are generated at
|
|
startup unless `-keys-from-env` is set; stable dev keys can be supplied as
|
|
hex-encoded 64-byte Ed25519 private keys via `KEY_<slug>` env vars.
|
|
- **OpenBao Transit backend**: stub (`-backend=openbao` returns
|
|
`ErrNotWired`). Separate subtask.
|
|
- **Pocket ID JWKS verifier**: stub. Dev uses the static `-bearers` table.
|
|
Separate subtask.
|
|
- **OPA policy decider**: stub. Dev uses AllowAll. Separate subtask.
|
|
- **Deployment manifest**: separate subtask.
|
|
|
|
## Layout
|
|
|
|
```
|
|
services/signing-service/
|
|
├── README.md
|
|
├── go.mod
|
|
├── cmd/signing-service/main.go — HTTP entry (bind + router + graceful shutdown)
|
|
└── internal/
|
|
├── canonical/canonical.go — stable JSON serialisation (byte-for-byte
|
|
│ compatible with admin-api/internal/attest/hash.go)
|
|
├── signer/signer.go — Signer interface, InMemory (Ed25519), OpenBao stub,
|
|
│ DSSE PAE and SignStatement orchestration
|
|
├── signer/signer_test.go — signature verification, PAE format exactness, errors
|
|
├── policy/policy.go — Decider interface, AllowAll, OPA stub
|
|
├── token/validator.go — bearer validator, Static + PocketID stub
|
|
└── httpapi/
|
|
├── sign.go — POST /api/v1/sign/dsse handler + /healthz
|
|
└── sign_test.go — happy path, auth, policy, unknown key, bad statement
|
|
```
|
|
|
|
## Local dev
|
|
|
|
```bash
|
|
cd services/signing-service
|
|
go vet ./... && go test ./...
|
|
go run ./cmd/signing-service \
|
|
-listen=:8081 \
|
|
-backend=memory \
|
|
-keys=trust-api/rate-change-signer-2026-q4 \
|
|
-bearers=dev-token=agent-admin-api
|
|
```
|
|
|
|
Smoke-test it with curl:
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:8081/api/v1/sign/dsse \
|
|
-H "Authorization: Bearer dev-token" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"key_ref":"trust-api/rate-change-signer-2026-q4",
|
|
"statement":{
|
|
"_type":"https://in-toto.io/Statement/v1",
|
|
"subject":[{"name":"per_diem_rate/PDR-1","digest":{"sha256":"aaaa"}}],
|
|
"predicateType":"https://basicstack.de/attestations/rate_change/v1",
|
|
"predicate":{"change_kind":"create","rate_id":"PDR-1"}
|
|
}
|
|
}' | jq .
|
|
```
|
|
|
|
Pointing the admin-api at this instance:
|
|
|
|
```bash
|
|
# Terminal 1
|
|
cd services/signing-service && go run ./cmd/signing-service -listen=:8081
|
|
# Terminal 2 (admin-api still needs a tlog, so this will log "attestation failed"
|
|
# until services/transparency-log is up — rows will still be created and marked
|
|
# attestation-pending as designed):
|
|
cd services/admin-api && go run ./cmd/admin-api -store=memory \
|
|
-signer-url=http://localhost:8081 \
|
|
-tlog-url=http://localhost:9099 \
|
|
-bearer=dev-token \
|
|
-signer-key=trust-api/rate-change-signer-2026-q4
|
|
```
|
|
|
|
## Keys
|
|
|
|
### Generate one hex-encoded Ed25519 private key for dev
|
|
|
|
```bash
|
|
go run ./cmd/signing-service -gen-dev-key
|
|
# → prints 128 hex chars (64 bytes raw private key)
|
|
```
|
|
|
|
Supply it via env:
|
|
|
|
```bash
|
|
# For key_ref "trust-api/rate-change-signer-2026-q4" the env name is
|
|
# KEY_TRUST_API_RATE_CHANGE_SIGNER_2026_Q4 (upper-case, / - . → _)
|
|
export KEY_TRUST_API_RATE_CHANGE_SIGNER_2026_Q4=<hex>
|
|
go run ./cmd/signing-service -backend=memory -keys-from-env \
|
|
-keys=trust-api/rate-change-signer-2026-q4
|
|
```
|
|
|
|
### Prod
|
|
|
|
Prod wiring in the OpenBao-Transit subtask: Signer backend becomes
|
|
`signer.OpenBao` with HTTP client to the cluster-internal OpenBao, policy
|
|
backend becomes `policy.OPA` with the Rego bundle under `policies/signing/`
|
|
(not yet created), token validator becomes `token.PocketID` with JWKS from
|
|
`https://auth.basicstack.de/.well-known/jwks.json`.
|