3a01cc651f
New services/approval-service with the Session → Preview → Confirm
pipeline required by DEV-606/DEV-608:
* POST /api/v1/sessions starts a Pocket-ID-bound approval session.
* POST /api/v1/approvals/preview renders content server-side, computes
H_content = sha256(canonical JSON), stores the (nonce, salt, canonical,
challenge) tuple and returns the human verification digits plus the
WebAuthn challenge = nonce || H_content.
* POST /api/v1/approvals/confirm verifies the WebAuthn assertion against
the stored challenge, DSSE-signs the Approval statement via the
signing-service (key_ref=trust-api/approval-signer-2026-q4), submits
to the transparency-log, and returns {approval_id, attestation_ref,
log_index}. TLog failures leave the row at attestation-pending for
the reconciler.
* db/trust/migrations/0004_approval_sessions.{up,down}.sql: new tables
approval_sessions, approval_previews, approvals (schema matches the
Phase 1 store contract).
* internal/content: canonical JSON + H_content + 6-digit verification
code (byte-compatible with signing-service/internal/canonical).
* internal/webauthn: stdlib-only Phase-1 verifier; wire shape stays
WebAuthn-compatible for the Phase-2 swap to go-webauthn/webauthn.
* internal/signer, internal/tlog: HTTP clients mapping 5xx / connection
errors to typed ErrSignerUnavailable / ErrTLogUnavailable so the
HTTP layer can return 502 for signing failures and persist
attestation-pending on TLog failure.
* internal/service.Orchestrator ties the pipeline together and persists
the Approval BEFORE the TLog submit (never return a log_index for
an un-persisted approval).
Tests cover: happy path, tampered H_content → 400, expired challenge
→ 403, signer 5xx + conn-refused → 502, TLog failure → row stays
attestation-pending, duplicate confirm → 409, session expired → 403.
go vet clean, go test ./... passes.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
144 lines
6.2 KiB
Markdown
144 lines
6.2 KiB
Markdown
# approval-service
|
|
|
|
Phase 1 der ProofedMesh content-gebundenen Approvals ([DEV-608](/DEV/issues/DEV-608),
|
|
siehe `docs/architecture/v1.1.md §4.3`). Der Dienst nimmt menschliche
|
|
Freigaben an, bindet sie kryptographisch an einen deterministisch gerenderten
|
|
JSON-Inhalt (`H_content = sha256(canonical_json)`), verifiziert eine WebAuthn-
|
|
Assertion gegen die Challenge `nonce || H_content` und erzeugt daraus eine
|
|
DSSE-signierte Approval-Attestation, die ins Transparency-Log eingetragen
|
|
wird.
|
|
|
|
## Endpoints
|
|
|
|
Alle Routen sind JSON-API, Pocket-ID-Session-Cookie-geschützt.
|
|
|
|
| Methode | Pfad | Zweck |
|
|
| ------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
| `POST` | `/api/v1/sessions` | Startet eine Approval-Session. Antwort: `{session_id, active_until}`. |
|
|
| `POST` | `/api/v1/approvals/preview` | Rendert Freigabe-Inhalt serverseitig, berechnet `H_content`, legt Challenge und Prüfziffer ab. |
|
|
| `POST` | `/api/v1/approvals/confirm` | Nimmt die WebAuthn-Assertion entgegen, signiert und loggt die Approval. |
|
|
| `GET` | `/healthz` | Liveness. |
|
|
|
|
### `POST /api/v1/sessions`
|
|
|
|
Erzeugt eine Approval-Session an die aktuelle Pocket-ID-`sub`. `active_until`
|
|
ist in Phase 1 fest auf `SessionTTL` (Default 15 min).
|
|
|
|
### `POST /api/v1/approvals/preview`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"session_id": "sess_…",
|
|
"content": { "...application-defined..." }
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"preview_id": "pv_…",
|
|
"content_hash": "sha256:<hex>",
|
|
"verification_digits": "734219",
|
|
"webauthn_challenge": "<b64url>",
|
|
"expires_at": "2026-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
`verification_digits` ist eine 6-stellige Prüfziffer aus `H_content`, die der
|
|
Mensch im UI vor der Freigabe mit der Signaturaufforderung abgleichen MUSS.
|
|
`webauthn_challenge` ist bereits `nonce || H_content` (b64url), damit der
|
|
Browser direkt eine WebAuthn-Assertion anfordern kann.
|
|
|
|
### `POST /api/v1/approvals/confirm`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"preview_id": "pv_…",
|
|
"assertion": {
|
|
"credential_id": "<b64url>",
|
|
"client_data_json": "<b64url>",
|
|
"authenticator_data": "<b64url>",
|
|
"signature": "<b64url>"
|
|
}
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"approval_id": "ap_…",
|
|
"attestation_ref": "sha256:<hex>",
|
|
"log_index": 42,
|
|
"tlog_status": "logged"
|
|
}
|
|
```
|
|
|
|
Wenn der TLog-Submit scheitert, bleibt die Row `tlog_status =
|
|
"attestation-pending"`; die Antwort meldet dann `log_index: null,
|
|
tlog_status: "attestation-pending"`. Ein späterer Reconciler zieht den
|
|
Submit nach (ADR-0005, idempotent per `content_hash`).
|
|
|
|
## Fehler
|
|
|
|
| Zustand | Code | Body `error.code` |
|
|
| -------------------------------------------- | ---- | ------------------------- |
|
|
| Session abgelaufen / unbekannt | 403 | `session_expired` |
|
|
| `H_content`-Mismatch (Assertion vs. Preview) | 400 | `content_hash_mismatch` |
|
|
| Challenge abgelaufen | 403 | `challenge_expired` |
|
|
| WebAuthn-Assertion ungültig | 401 | `assertion_invalid` |
|
|
| Signing-Service nicht erreichbar | 502 | `signer_unavailable` |
|
|
|
|
## Phase 1 Scope
|
|
|
|
- Store ist in-memory (`internal/store/memory.go`); Postgres-Impl ist in
|
|
`internal/store/postgres.go` als Skelett angelegt (Pattern aus
|
|
`admin-api/internal/store/postgres.go`). Die SQL-Migration liegt bereits
|
|
in `db/trust/migrations/0004_approval_sessions.*.sql`.
|
|
- WebAuthn-Verifikation ist eine stdlib-only Shim im Stil von
|
|
`admin-api/internal/auth/pocket_id.go`: In-Memory-`Credential`-Store,
|
|
Ed25519-Assertion über `authenticator_data || sha256(client_data_json)`,
|
|
Challenge-Vergleich konstantzeitig. Die Datenformate sind
|
|
WebAuthn-kompatibel (b64url-encoded `client_data_json` mit `challenge`,
|
|
`type`, `origin`), damit das Phase-2-Umstieg auf
|
|
`github.com/go-webauthn/webauthn` ohne API-Bruch möglich bleibt.
|
|
- Keine HTML/UI; nur JSON. Browser-Integration landet in einem Folge-Task.
|
|
|
|
## Konfiguration
|
|
|
|
Alle über Flags oder Env (`APPROVAL_*`):
|
|
|
|
| Env / Flag | Default | Zweck |
|
|
| ------------------------------- | --------------------------- | --------------------------------------------------------- |
|
|
| `APPROVAL_LISTEN` | `:8080` | HTTP-Listen-Adresse. |
|
|
| `APPROVAL_SIGNING_URL` | *(required)* | Base URL des signing-service (`/api/v1/sign/dsse`). |
|
|
| `APPROVAL_SIGNING_KEY_REF` | `trust-api/approval-signer-2026-q4` | DSSE-Signaturschlüssel. |
|
|
| `APPROVAL_SIGNING_TOKEN` | *(optional)* | Bearer-Token für signing-service (Phase 1 Static). |
|
|
| `APPROVAL_TLOG_URL` | *(required)* | Base URL des transparency-log. |
|
|
| `APPROVAL_SESSION_TTL` | `15m` | Lebensdauer einer Approval-Session. |
|
|
| `APPROVAL_CHALLENGE_TTL` | `2m` | Max. Zeit zwischen Preview und Confirm. |
|
|
| `APPROVAL_WEBAUTHN_RP_ID` | `trust.basicstack.de` | WebAuthn relying party ID. |
|
|
| `APPROVAL_WEBAUTHN_RP_ORIGIN` | `https://trust.basicstack.de` | Erlaubter Origin in `client_data_json`. |
|
|
| `APPROVAL_POCKET_ID_ISSUER` | *(required in prod)* | Pocket-ID OIDC-Issuer. |
|
|
| `APPROVAL_POCKET_ID_CLIENT` | *(required in prod)* | Client-ID des approval-service. |
|
|
|
|
## Tests
|
|
|
|
```
|
|
cd services/approval-service
|
|
go test ./...
|
|
```
|
|
|
|
Deckt ab:
|
|
|
|
- Happy Path (Session → Preview → Confirm → DSSE verifiziert und ins TLog
|
|
eingetragen).
|
|
- Tampered `H_content` in der Assertion → 400.
|
|
- Abgelaufene Challenge → 403.
|
|
- Signing-Service antwortet nicht (connection refused) → 502.
|
|
- TLog-Submit scheitert → Approval bleibt `attestation-pending`.
|