Some additional checks and cleanup

Security-audit.md

@@ -173,15 +173,19 @@ These findings are prioritized below. Severity describes the potential security
 
 **Priority:** Medium.
 
-### SA-012: Token lifecycle has unused refresh-token semantics
+### SA-012: Token lifecycle has refresh-token rotation and revocation controls
 
-**Severity:** Medium  
-**Evidence:** `issue_token()` returns a `refresh_token` value, but only the access token is inserted into `tokens`; no refresh endpoint or refresh-token hash is implemented.  
-**Impact:** Clients may assume the refresh token provides renewal or may store a value that cannot be revoked or used. This complicates session reasoning and can lead to unsafe client fallbacks. Access tokens currently live for the configured default of 30 days.
+**Severity:** Medium, remediated in current worktree
+**Evidence before remediation:** `issue_token()` returned a `refresh_token` value, but only the access token was inserted into `tokens`; no refresh endpoint or refresh-token hash was implemented.
+**Impact:** Clients could assume the refresh token provided renewal or could store a value that could not be revoked or used. This complicated session reasoning and could lead to unsafe client fallbacks. Access tokens previously lived for the configured default of 30 days.
 
-**Recommendation:** Either remove `refresh_token` from the API contract or implement a real refresh-token lifecycle: hash and persist refresh tokens, rotate them on use, detect reuse, bind them to a session/device, expire them separately, and revoke the token family on logout or password change. Reduce access-token lifetime after a real refresh flow is available.
+**Current state:** Login and `POST /api/auth/refresh` issue 15-minute access tokens and separately expiring 30-day refresh tokens. Only SHA-256 refresh-token hashes are stored. Each token family is bound to a device ID; a valid refresh token is rotated and the previous family state is revoked. Reuse of a revoked refresh token revokes the complete family. Logout revokes the token family, and password reset deletes all tokens for the user.
 
-**Priority:** Medium.
+**Residual impact:** Existing sessions issued before deployment should be rotated, refresh-token reuse should be monitored, and clients must protect the device ID and session storage. Token-family cleanup and retention remain operational improvements.
+
+**Recommendation:** Keep access tokens short-lived, require device binding on refresh, alert on refresh-token reuse, and retain family revocation on logout and password reset. Never place tokens in URLs or logs.
+
+**Priority:** Completed in code; session rotation and monitoring remain.
 
 ### SA-013: No explicit security headers, CORS policy, or request-size policy
 
@@ -224,7 +228,7 @@ These findings are prioritized below. Severity describes the potential security
 - **Primary email selection:** Only an already verified alternative address can be promoted to primary. The same user row retains account permissions and active sessions, and the previous primary is retained as a verified alternative.
 - **Password policy:** New and reset passwords require at least eight characters. This is better than no policy but should be replaced with a longer passphrase-oriented policy and breached-password screening after a proper password hash migration.
 - **Email verification:** New administrator-created users cannot log in until verified. The setup-created first administrator is marked verified, which is appropriate for bootstrap but should be protected by the setup controls above.
-- **Password reset:** Tokens are random, hashed, expiring, single-use, and revoke existing access tokens after reset. Reset-email generation errors are intentionally swallowed to preserve generic login behavior, but this should be paired with server-side monitoring.
+- **Password reset:** Tokens are random, hashed, expiring, single-use, and revoke all access and refresh token families after reset. Reset-email generation errors are intentionally swallowed to preserve generic login behavior, but this should be paired with server-side monitoring.
 - **OTP:** Login enforcement is present and OTP setup requires confirmation. Recovery codes, secret rotation, reauthentication, and encrypted secret storage are missing.
 - **Authorization:** Admin checks and link ownership checks are present. The last-administrator invariant is enforced for privilege changes and deletion. Add authorization tests for every new destructive endpoint as the API grows.
 
@@ -243,7 +247,7 @@ These findings are prioritized below. Severity describes the potential security
 - The web API currently uses bearer headers, so browser CSRF risk is lower than with cookie sessions. Keep it that way unless a CSRF token design is added.
 - Browser local storage is exposed to any script running in the same origin. Keep third-party scripts out of authenticated pages and add a restrictive CSP.
 - The extension's `<all_urls>` host permission should be reduced if the active-tab workflow is sufficient. Review Mozilla Add-ons policies before publishing signed releases.
-- The extension stores access and refresh-token-like values in `browser.storage.local`; implement actual refresh semantics or stop storing/returning unused refresh values.
+- The extension stores access and refresh credentials in `browser.storage.session`; it uses the refresh endpoint after access-token expiry and clears session and legacy token material on logout or invalidation.
 - Extension error messages should not include tokens or full sensitive URLs.
 
 ## Deployment Checklist
@@ -260,7 +264,7 @@ Before production exposure:
 - [ ] Define a restrictive CORS policy or leave CORS disabled.
 - [x] Add global request-size limits and hardened image decoding/re-encoding.
 - [x] Add OTP recovery codes and a protected recovery workflow.
-- [ ] Remove or implement refresh-token behavior.
+- [x] Implement refresh-token behavior with hashing, device binding, rotation, reuse detection, and family revocation.
 - [x] Add security audit events and centralized redacted logging.
 - [ ] Rotate all credentials and set a unique high-entropy production secret.
 - [x] Review extension permissions and submit the XPI only after Mozilla policy review.