08 — Published API docs
Summary
Swagger for the published folder is two artefacts with very different costs. The spec (api/openapi.json, a few KB) is generated from manifest.json by the tool that just wrote the folder, so it cannot drift, describes only what the folder actually serves, and uses a relative server URL so it works on any host. The UI is 1.53 MB — measured at 2.7× the entire published vault it documents — so it is opt-in, with CDN-plus-SRI as the default and bundling for offline or no-third-party policies. The non-obvious security interaction: the docs page is same-origin with the loader, which may store keys, so the CDN mode requires the exact-version pin, integrity hashes, crossorigin, no-referrer, and a CSP whose connect-src 'self' means even a script that somehow ran could not exfiltrate a key.
Key concepts
- Generated from the manifest, so it cannot drift — the publisher's spec describes this deployment; the API team's spec describes the live service — complementary, and the conformance loop closes from both ends
- SRI is the mitigation, not CDN avoidance — a pinned hash means substituted bytes do not execute; a floating version tag is not acceptable in any mode
- A demonstration, not documentation — a Swagger UI whose every operation returns opaque bytes, with no auth scheme at all, makes the zero-knowledge claim visible — the ciphertext panel's argument for a different reader
Key ideas
- The root fix belongs in the loader: keep keys in memory, never in localStorage, and the same-origin objection collapses for every script anyone ever adds.
- A published vault becomes self-describing to an agent — a machine-readable contract with no out-of-band explanation.
- The 230 KB standalone preset is simply not emitted: a fixed-spec page never uses it.