refactor(security): move secret store under keyring

[senamakel]

Summary

• move SecretStore under the keyring module while keeping security::secrets as a compatibility shim
• switch normal app environments to use keyring-backed master-key storage, with migration from legacy .secret_key files
• add Rust E2E coverage for both legacy-key migration and fresh keyring-backed initialization paths
• wire the new keyring secret-store suites into scripts/test-rust-e2e.sh
• add public GitBook documentation for OS keyring and encrypted secret storage

Problem

• local encrypted config/state secrets still depended on a file-era storage model that was separate from the keyring module
• dev/staging did not follow the desired desktop security model of rooting local secret material in the OS keyring
• the migration path from legacy .secret_key installs to keyring-backed storage was not covered by end-to-end tests
• the public docs did not explain how OpenHuman stores local secrets on desktop

Solution

• move the encrypted secret-store implementation into src/openhuman/keyring/encrypted_store.rs and re-export it through keyring::SecretStore
• keep ciphertext-on-disk semantics, but store the secret-store master key in the keyring backend and migrate legacy .secret_key files into that backend on first use
• update keyring backend selection so tests can still use the file backend, while normal app runs default to the OS keyring unless explicitly overridden
• add focused unit coverage plus two integration-style Rust E2E suites: one for migration from a legacy key file and one for fresh key creation in keyring-backed storage
• document the model in GitBook as "key in keyring, ciphertext on disk"

Submission Checklist

If a section does not apply to this change, mark the item as N/A with a one-line reason. Do not delete items.

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage ≥ 80% — changed lines are covered by focused tests locally and the enforced CI diff-coverage gate remains authoritative for merge
• Coverage matrix updated — N/A: no existing feature-matrix row was added/removed/renamed by this storage/docs refactor
• All affected feature IDs from the matrix are listed in the PR description under ## Related — N/A: no matrix feature IDs changed
• No new external network dependencies introduced (mock backend used per Testing Strategy)
• Manual smoke checklist updated if this touches release-cut surfaces — N/A: no installer/distribution/manual-smoke surface changed
• Linked issue closed via Closes #NNN in the ## Related section — N/A: no tracked issue was provided for this branch

Impact

• desktop/local secret handling now uses the keyring module as the root secret store for the encrypted-file path
• legacy .secret_key installs migrate forward instead of requiring manual re-entry of secrets
• docs now state explicitly that OpenHuman uses OS-level keyring storage for local secret roots on desktop
• test-only/file-backend behavior remains available for deterministic automation

Related

• Closes: N/A
• Feature IDs: N/A
• Follow-up PR(s)/TODOs:
  • update coverage-matrix references if reviewers want this change linked to specific feature IDs

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Keep this section for AI-authored PRs. For human-only PRs, mark each field N/A.

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: keychain-secretstore-migration
• Commit SHA: 041878741

Validation Run

• pnpm --filter openhuman-app format:check
• pnpm typecheck
• Focused tests:
  • cargo test --manifest-path Cargo.toml keyring::encrypted_store::tests -- --nocapture
  • cargo test --manifest-path Cargo.toml --test keyring_secretstore_e2e --test keyring_secretstore_fresh_e2e -- --nocapture
  • bash scripts/test-rust-e2e.sh --suite keyring_secretstore_e2e --suite keyring_secretstore_fresh_e2e
• Rust fmt/check (if changed):
  • cargo fmt --manifest-path Cargo.toml
  • pre-push cargo check --manifest-path src-tauri/Cargo.toml
• Tauri fmt/check (if changed): pre-push cargo check --manifest-path src-tauri/Cargo.toml

Validation Blocked

• command: pnpm test:coverage, pnpm test:rust
• error: not run in full during this change; focused validation was used instead
• impact: diff-coverage merge gate still depends on CI/full-suite coverage jobs

Behavior Changes

• Intended behavior change: use keyring-backed secret roots for desktop secret-store encryption, with migration from legacy local key files
• User-visible effect: existing installs keep working, and local secret handling now follows the documented OS keyring model more closely

Parity Contract

• Legacy behavior preserved: encrypted ciphertext remains on disk; security::secrets remains as a compatibility re-export shim
• Guard/fallback/dispatch parity checks: legacy .secret_key migration path covered by E2E; fresh-install key creation path covered by E2E; test file-backend override preserved

Duplicate / Superseded PR Handling

• Duplicate PR(s): N/A
• Canonical PR: this PR
• Resolution (closed/superseded/updated): N/A

[coderabbitai]

Warning

Review limit reached

@senamakel, we couldn't start this review because you've used your available PR reviews for now.

Your plan includes 5 reviews of capacity. Refill in 16 minutes and 10 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dc0b3a16-28d5-4cd7-ac43-56010a1ab2f8

📥 Commits

Reviewing files that changed from the base of the PR and between ddfb611 and a26d242.

📒 Files selected for processing (21)

• docs/security/keychain-secretstore-migration.md
• gitbooks/SUMMARY.md
• gitbooks/features/os-keyring-and-secret-storage.md
• gitbooks/features/privacy-and-security.md
• scripts/test-rust-e2e.sh
• src/openhuman/config/schema/load.rs
• src/openhuman/credentials/ops.rs
• src/openhuman/credentials/profiles.rs
• src/openhuman/devices/rpc.rs
• src/openhuman/encryption/README.md
• src/openhuman/keyring/backend.rs
• src/openhuman/keyring/encrypted_store.rs
• src/openhuman/keyring/encrypted_store_tests.rs
• src/openhuman/keyring/mod.rs
• src/openhuman/keyring/store.rs
• src/openhuman/security/README.md
• src/openhuman/security/mod.rs
• src/openhuman/security/secrets.rs
• tests/json_rpc_e2e.rs
• tests/keyring_secretstore_e2e.rs
• tests/keyring_secretstore_fresh_e2e.rs

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}