SeedPass/docs/auth_lock_unlock_access_review.md

SeedPass Auth, Lock/Unlock & Access-Control Review (Item 6)

Status: Done
Date: 2026-02-25

Scope Reviewed

1. src/seedpass/core/manager.py
2. src/seedpass/api.py
3. src/seedpass/core/api.py
4. src/seedpass/core/config_manager.py

Exit Criteria Check (Item 6)

1. Lock/unlock/timeout/quick unlock behavior reviewed with tests: Done

Findings

Completed in this pass

1. Added explicit locked-state gate for protected HTTP API routes.
   • Sensitive endpoints now reject access with 423 Vault is locked when lock flags are set.
2. Added explicit HTTP unlock endpoint.
   • New route: POST /api/v1/vault/unlock using X-SeedPass-Password.
3. Added API regression tests for lock enforcement and unlock flow.
   • Entry/password endpoints blocked while locked.
   • Unlock endpoint clears locked state path.
4. Tightened admin/config access controls while locked.
   • Config, relay, checksum, and selected profile-management routes now require unlocked state.
5. Restricted sensitive config key exposure/update.
   • password_hash and pin_hash access/update blocked via generic config API.
6. Added unlock-attempt throttling on API unlock route.
   • Repeated failed unlock attempts now return 429 after threshold.

Validation

1. pytest -q src/tests/test_api_new_endpoints.py src/tests/test_api.py src/tests/test_vault_lock_flag.py src/tests/test_inactivity_lock.py src/tests/test_unlock_sync.py
2. Result: 65 passed

Existing posture

1. Core manager has lock_vault() / unlock_vault() and publishes lock events.
2. Inactivity timeout enforcement exists via AuthGuard.
3. Quick unlock behavior is configurable and covered by existing tests.

Policy decisions

1. Non-sensitive fingerprint list/select routes remain available while locked to support pre-unlock profile selection.
2. Admin/config/data routes are lock-gated.
3. Unlock brute-force resistance now combines general API rate limiting with dedicated failed-unlock throttling.

Evidence

1. src/tests/test_api_new_endpoints.py
2. src/tests/test_vault_lock_flag.py
3. src/tests/test_inactivity_lock.py
4. src/seedpass/api.py
5. src/seedpass/core/manager.py