book-library.git · PLANS.md

revision 661006ab93f2060ae0c37fe6dc6b18bdb2dc56b9 · complete file

Title: FountainMaintenanceKit server adapter — initial vertical slice

Goal: Consume the published FCIS Kit in the Book Library server and expose a narrow typed maintenance admission/read
surface with server-owned authorization and repeat-safe receipts.

Scope: remote Kit dependency, `MaintenanceAdmission`, health operation, operation receipt lookup, focused tests, and
fixture-server proof.

Non-goals: native Swift Git backend, deployment/promotion executors, real SecretStore provider, TLS termination,
remote production deployment, Reframe UI, or FountainStore integration.

Constraints: no secret values; no guessed SSH or filesystem authority; unsupported operations fail visibly.

Plan:
- Step 1 (status: completed) - Resolve published `FountainMaintenanceKit` and add the server admission adapter.
- Step 2 (status: completed) - Add authorization, idempotency, collision, and receipt tests.
- Step 3 (status: completed) - Run the fixture server and prove health success, retry, denial, receipt retrieval, and
restart persistence.
- Step 4 (status: completed) - Commit and push the Book Library server adapter; record the exact Kit revision.

Validation:
- `swift test`
- fixture server HTTP proof on `/v1/maintenance/operations`
- `git diff --check`

Evidence:
- `FountainMaintenanceKit@0.1.1` revision `3d58c56bf5b685ea8211a0ec503317b1a74552eb`
- `swift test`: 13 tests passed
- Live fixture server: health `200/succeeded`, idempotent retry `200/same receipt`, unauthorized actor `403`, receipt
lookup `200/succeeded`, and after process restart receipt lookup again returned `200/succeeded` with the same
operation timestamp and identity.

## Durable maintenance receipts — Chapter 62/63 follow-on

Goal: make maintenance admission survive service restart without putting secrets or host-bound state into receipts.

Implemented: `MaintenanceAdmission` now writes typed request/receipt entries atomically beneath the explicit
`BOOK_LIBRARY_MAINTENANCE_RECEIPTS_ROOT`; a new process reloads by idempotency key and operation ID. Unsafe keys,
unknown actors, and idempotency collisions fail closed.

Non-goals: deployment executor, native Git, real SecretStore authentication, or remote production rollout.

Validation: 13 Book Library tests plus live stop/restart/receipt lookup proof passed.

## Server-side maintenance authentication — Chapter 63 follow-on

Implemented: `MaintenanceBearerAuthenticator` verifies the SHA-256 digest configured by
`BOOK_LIBRARY_MAINTENANCE_TOKEN_SHA256`. When configured, both maintenance POST and receipt GET routes require an
exact bearer credential; the raw token is never persisted, logged, or placed in a receipt. An absent digest is
explicitly reported as fixture-only mode and is not a production deployment claim.

Validation: 14 Book Library tests passed. Live configured-server proof returned `401` for a wrong bearer, `200` and a
succeeded receipt for the correct bearer, and a receipt lookup containing no token or authorization value.