rouse-context/docs/security-decisions.md
Jason Monk ae4245882b
Update README and security docs to match shipped behavior (#406 chunk A) (#411)
Address the audit findings in #406 chunk A for README.md, the 2026-04-07
security audit summary, and the security decisions log:

- README.md: 6 copy fixes — per-integration URL form (`{adj}-{integration}.subdomain/mcp`,
  not legacy `{adj}-{noun}/integration/mcp`); CA is Google Trust Services
  (post-#391/#398), Let's Encrypt is supported but not the default; certs are
  per-device, not "wildcard"; build prereqs are JDK 21 and SDK 36/35/24; add
  `:core:testfixtures` to the module table.
- docs/security-audit-2026-04-07.md: annotate all 23 findings inline with
  current status (15 FIXED with code refs, 6 ACCEPTED-AS-RISK referencing
  security-decisions.md, 1 PARTIAL — #8 SHA-256 hashes not encryption,
  3 UNKNOWN — #17 #18 #21 flagged for follow-up review). Doc structure
  preserved.
- docs/security-decisions.md: refresh the stale "Not yet implemented" line
  for finding #23 — refresh-token rotation with OAuth 2.1 §4.14 reuse
  detection now ships in `RoomTokenStore.refreshToken`. Also resolve the
  "Needs verification" line for finding #15 (`open_link` validates
  http/https in `OutreachMcpProvider`).

Documentation only; no behavior changes. Per .claude/rules/ux-changes.md,
doc updates describing already-shipped behavior do not require user
approval.

Co-authored-by: Claude Opus 4 (1M context) <noreply@anthropic.com>
2026-04-25 18:38:12 -04:00

2.8 KiB
Raw Permalink Blame History

Security Decisions Log

Tracks security concerns we've evaluated and decided not to address, with reasoning. Only remove entries from this list if we later implement a fix.

Accepted Risks

Debug broadcast receiver exported (Audit #13)

Decision: Accept Reasoning: TestWakeReceiver is in app/src/debug/ and excluded from release builds entirely. Debug builds are only on developer devices. Not a production risk.

Intent extras in launch_app (Audit #14)

Decision: Accept Reasoning: The MCP client has already been through full OAuth approval. If the user has granted an AI client access to launch apps, passing string extras is within that trust boundary. The user explicitly approved this integration.

Certificate pinning on relay connection (Audit #19)

Decision: Skip Reasoning: Without an automatic app update channel, cert pinning would break all devices when the relay cert rotates (Let's Encrypt = 90 days). The attack surface is narrow (attacker needs a valid cert for relay.rousecontext.com from a public CA). mTLS client cert already authenticates device→relay. System CA store validates relay→device. Revisit if we add auto-update.

Sequential stream IDs (Audit #20)

Decision: Accept Reasoning: Security through obscurity is not security. The relay's dispatch_incoming routes frames by stream ID to the sender that owns that stream. A device can only send DATA/CLOSE for streams the relay opened for it. Frames for unowned streams are silently dropped. The security model doesn't depend on stream ID unpredictability.

CORS on OAuth endpoints (Audit #22)

Decision: Accept Reasoning: The authorize status polling endpoint is same-origin (served from the device's own hostname). Cross-origin access would require the attacker to know the request_id (128-bit random UUID). The timing information leaked (whether a user approved) is low-value.

Addressed (for reference)

Token expiration / refresh (Audit #23)

Decision: Implement refresh tokens (short-lived access + long-lived refresh) with rotation. Status: Implemented. app/src/main/java/com/rousecontext/app/token/TokenEntity.kt carries expiresAt, refreshExpiresAt, and rotatedAt; app/src/main/java/com/rousecontext/app/token/RoomTokenStore.kt (see refreshToken, lines ~115–140) performs OAuth 2.1 §4.14 refresh-token rotation with family-wide revocation on detected reuse.

Notification action URLs (Audit #15)

Decision: Verify http/https validation covers notification action buttons too. Status: Verified. open_link in integrations/.../OutreachMcpProvider.kt (around lines 161–172) rejects any scheme other than http or https.

Usage integration privacy (Audit #16)

Decision: Address via UX — clear setup copy explaining what's exposed Status: Backlog item.