Plan: finish the operations, security and Portal issues (#139, #221 to #225, #227) #237

Summary

This issue is the plan and the progress record for seven open issues of operations and security work: #223, #224, #225, #221, #222, #139 and #227. They are worked one at a time, in the order below. Each step is its own pull request, and a step starts only after the pull request of the step before it is merged.

The plan was approved by the requester on 2026-11-14. The approval does not authorize any merge or any release tag. Each pull request is merged only with the requester's word for that pull request, and each tag only with the requester's word for that tag.

Out of scope: #187, #191 and #234 stay with their authors. #233 (the sheet type) has its own plan and its own design pull request, #236.

Order

The order puts unblocked work first, and it puts the key ID format and rotate-key before the issues that add new kinds of sealed values.

• 1. flats backup with a manifest and a verify mode, proven by a restore under write load. Closes feat(cli): add flats backup for a consistent online copy #223. Done in feat(cli): add flats backup for a consistent online copy #238, merged as b09f5fd.
• 2. A key path setting, so that secret.key can live outside the data directory. feat(secrets): key outside the data directory, rotation and injected fetch secrets #224, item 1.
• 3. A host event log that survives the delete of a flat, and an event for every secret and key operation. feat(secrets): key outside the data directory, rotation and injected fetch secrets #224, item 4.
• 4. A key ID and a class on every sealed value, and flats secret rotate-key. feat(secrets): key outside the data directory, rotation and injected fetch secrets #224, item 2.
• 5. Signed webhooks and flats audit export. Closes feat(events): approval webhook and audit export #225.
• 6. Secrets that the host injects into fetch for one origin and one header. feat(secrets): key outside the data directory, rotation and injected fetch secrets #224, item 3. Closes feat(secrets): key outside the data directory, rotation and injected fetch secrets #224.
• Release 1, after steps 1 to 6.
• 7. Portal SDK upgrade from v2.6.3 to the newest v2.7 release, with no change of behavior.
• 8. Per-flat Portal sign-in that fails closed. Closes feat(portal): per-flat sign-in for flats served through Portal #221.
• 9. portal.require_auth. Closes feat(portal): refuse to serve a flat through Portal without sign-in #222.
• Release 2, after steps 7 to 9.
• 10. Built-in authentication. The requester decides the five design questions of feat(auth): add built-in authentication for console and MCP/API access #139 in one batch with evidence. The spec with the access matrix follows, then identities and sessions, client credentials for MCP and the API, and the migration, in several pull requests. Closes feat(auth): add built-in authentication for console and MCP/API access #139.
• 11. The operator vault. Closes feat(secrets): operator vault for keys and files that people read back #227.
• Release 3, after steps 10 and 11.

Item 5 of #224, the recovery password for secret.key, is done by #231.

How each step runs

• The repository workflow applies to every step: design, then implementation, then testing, each with a review by a different model and a correction before acceptance.
• Each stage has at most two review rounds. A finding about wording only is fixed without a new round and is listed in the pull request. An open blocker or major finding at the cap stops the work with a report to the requester.
• A step that changes stored data says how an older binary behaves and what to back up before the upgrade.
• A step that changes what an agent can do or can not do updates the agent guide and the MCP tool texts.
• New commands keep one style: prompts without echo, and no secret in an argument. Each new refusal names the next command.
• Console changes follow the console UI playbook.
• At each release the plan is updated and the next group is estimated again. A step that grows past twice its estimate is reported before its code starts.
• Releases follow docs/release.md.

Known open points

• Step 1 (settled): the requester chose that a running host is never paused. The copy checks itself and fails, to be run again, when a change during the copy could make it inconsistent. flats.db and the outbox databases are snapshotted together and checked in both directions (see docs/spec/host-backup.md).
• Step 4: a key in a read-only Docker secret can not be rewritten by rotate-key. The design must choose the behavior.
• Step 8: tests use a fake OIDC issuer. A check against a real provider needs credentials from the requester.
• Step 10: the size is unknown until the five design questions are decided.
• Release step 5 of docs/release.md has four parts that the author can not do without other machines: the installer service on disposable machines, the standard-user Windows run, a macOS run, and running the darwin and arm64 binaries.