Encrypted-file secret store via swift-crypto (Closes #35)

[0xLeif]

Closes #35.

Summary

Replaces the Keychain-backed secret with an encrypted-file secret store under the state root (design decision 3ii). The macOS Keychain prompted for the password on every access — ad-hoc signed CLI binaries can never earn durable Keychain trust — and SecureState says nothing for Windows/Linux.

Construction: ephemeral X25519 ECDH + HKDF + ChaCha20-Poly1305, directly on swift-crypto (new dependency). Same envelope design as AlgoChat's Crypto/ — without the AlgoKit dependency that would sink the tri-OS goal.

Unlock model (interview decisions):

• Key file (default): <state-root>/secret.key generated on first use, mode 0600 — the SSH model. Zero prompts, headless-safe, every OS.
• Passphrase (opt-in): APS_SECRET_PASSPHRASE derives the key via HKDF-SHA256; wrong passphrases fail loudly with the new APSError.secretUnlockFailed.
• TTY fallback: APS_SECRET_USE_PASSPHRASE=1 prompts once with our own getpass (not macOS's).

Housekeeping: AppState SecureState extension and APSKeychain removed; the now-dead keychainUnavailable case removed (the #42 lesson applied). AppState itself untouched; SecureState dogfooding continues in AppStateExamples. Write-then-read-back verification kept from #27; freshValue reads the store directly so cross-process writes surface in watch; requireDecodableDiskState covers secret with loud corrupt/unlock failures.

Verification (all empirical, worktree)

• Key-file mode: set/get round-trip, secret.key mode 0600, reset deletes secret.enc
• Passphrase mode: HKDF round-trip; wrong passphrase -> loud secretUnlockFailed
• Corrupt envelope -> decodingFailed; cross-process watch sees v1 -> v2
• 43 tests (the 3 Keychain skips replaced by real coverage), 0 failures; smoke.sh green incl. perms and passphrase right/wrong
• specsync check --force 7/7 files 100%, specsync change check 20 active valid, fledge lanes run verify green
• specs/README/GOAL/windows-readiness updated in lockstep

SpecSync

• CHG-0021 accepted (feature, architecture-risk with research artifact; REQ-aps-cli-020 + REQ-aps-cli-005 with requirement evidence)
• Evidence rebound for shared accepted changes via audited reopen (actor 0xLeif)

Merge note

Touches the same DemoKey/StateStore/spec files as #50; whichever merges second gets the usual rebase + rebind pass, which I will run.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[cursor]

Review (agent:cursor) — tested locally

Verdict: Approve after small docs fix + SpecSync renumber. Crypto design looks solid.

Tested

• CI: all green (linux-smoke/windows-smoke/trust included)
• Local: built with explicit libstdc++ link flags on this agent image; 42 tests pass
• Manual: APS_SECRET_PASSPHRASE=... set/get secret round-trips; wrong passphrase → secretUnlockFailed

Required changes

1. Stale help text in Sources/aps/Aps.swift discussion still says:
   secret String SecureState (Keychain; macOS)
   README/DemoKey correctly say EncryptedFile. Please update the command discussion (and any other Keychain leftovers in help strings).
2. SpecSync CHG-0021-encrypted-file-... collides with Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50/TTY-aware output under the git porcelain rule (Closes #33) #53/watch signal handling and termination semantics (Closes #34) #54. Renumber after Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50 lands.
3. Error taxonomy coupling: this replaces keychainUnavailable with secretUnlockFailed. Coordinate with Error contract: exit-code taxonomy and JSON error envelope (Closes #31) #50 (exit-code mapping) and Add aps schema self-describing contract endpoint (Closes #32) #51 (schema error table) so agents do not see a dead keychain_unavailable code after merge.

Merge order

After #50 (so unlock failures get a proper taxonomy exit, not ValidationError→64). Before #51 so schema can document secretUnlockFailed / EncryptedFile.

[cursor]

Follow-up (agent:cursor)

Pushed two small commits onto this branch:

1. Help text: Aps discussion now says EncryptedFile (~/.aps/secret.enc) instead of Keychain SecureState.
2. Spec hygiene: superseded stale REQ-aps-cli-015 / REQ-state-store-013 Keychain ACs and updated testing notes to the encrypted-file contract (REQ-aps-cli-020).

Still needed on your side: renumber CHG-0021 after #50 lands (collision with #50/#53/#54).