summaryrefslogtreecommitdiff
path: root/message-catalog.md
diff options
context:
space:
mode:
authorYuval Adam <_@yuv.al>2026-02-26 09:13:23 +0100
committerYuval Adam <_@yuv.al>2026-02-26 09:13:23 +0100
commit7b609fffddf3ae138cdf301c97bad805fc508616 (patch)
treee952de5263e507e52b74db48cac8ac93f36fa8be /message-catalog.md
parent54adf11e1c8905c97512fcf29d8b3d75aa9eb0cb (diff)
Add key hierarchy analysis, update all docs with WASM/auth/native messaging findingsHEADmain
New document: - key-hierarchy.md: Full key derivation model, MUK lifecycle, SRP auth, biometric unlock, Duo MFA, dSecret bypass, delegated sessions, password timebox mechanism, crypto algorithm inventory Major updates: - architecture.md: Expanded WASM section with confirmed 80+ rA.* methods, clarified WASM is portability layer not security boundary - trust-boundaries.md: Corrected Zone A (keys in JS heap not just WASM), Zone D (confirmed native messaging protocol with biometry messages), Zone F (WASM is NOT a privilege boundary), detailed sensitive data table with confirmed storage locations, new Critical attack surface category - message-catalog.md: Added native messaging protocol (biometry save/unlock/ remove, availability check), desktop connection messages, server notification events - TODO.md: Marked completed items, added key material exposure assessment section, authentication & session security section
Diffstat (limited to 'message-catalog.md')
-rw-r--r--message-catalog.md31
1 files changed, 30 insertions, 1 deletions
diff --git a/message-catalog.md b/message-catalog.md
index db5be14..416dd23 100644
--- a/message-catalog.md
+++ b/message-catalog.md
@@ -92,6 +92,29 @@ The main handler registration (`m5({...})`) in `background.js` registers these c
| `report-error` | Structured error reporting from any context |
| `health-check-request` | (in health-check.js) Returns `health-check-response` with `"alive"` |
+## Native Messaging Protocol (Background → Native App)
+
+Messages sent via `browser.runtime.sendNativeMessage("")` with JSON envelope `{name: "core", data: JSON.stringify({type, data})}`.
+
+### Biometry Messages
+| Type | Subtype | Direction | Data |
+|------|---------|-----------|------|
+| `Biometry` | `save` | → Native | `{secrets: [{accountUuid, userUuid, muk: JWK, srpX}]}` |
+| `Biometry` | `unlock` | → Native, ← Response | Request: `{accounts: [...], useBiometry, useAppleWatch, fallbackPhrase, unlockPhrase}`. Response: `{secrets: [...], userFallback, userCancel}` |
+| `Biometry` | `remove` | → Native | `{accounts: [...], useBiometry, useAppleWatch, ...}` |
+| `Biometry` | `biometryAvailability` | → Native, ← Response | Response: `{current_availability, current_method, current_policy}` |
+
+All native messages have a 10-second timeout.
+
+### Desktop Connection Messages
+| Operation | Notes |
+|-----------|-------|
+| `requestUpgradeFromOfflineState` | Ask desktop app to re-establish online connection |
+| `requestDsecretProxy` | Get dSecret HMAC from desktop app for MFA bypass |
+| `saveBiometryUnlockSecrets` | Store MUK + SRP-X in OS secure enclave |
+| `getBiometryUnlockSecrets` | Retrieve after biometric verification |
+| `removeBiometryUnlockSecrets` | Remove from secure enclave |
+
## Content Script → Background Messages (from inline scripts)
### inject-content-scripts.js
@@ -143,9 +166,15 @@ Observed event names used in background's internal pub/sub system:
- `accounts-and-vaults-changed`
- `accounts-locked`
- `can-request-unlock-changed`
-- `unleash-features-changed`
+- `unleash-features-changed` — feature flag updates from Unleash
- `extension-first-survey`
- `unified-panel-update`
+- `set-lock-screen-status` — pushed to UI during biometric unlock (`"working"`, `"error"`)
+
+### Server Notification Events (via WebSocket)
+- `ServerChanged` — server data changed, triggers sync
+- `ServerConnected` — WebSocket reconnected
+- `SessionRequestIdChanged` — session request ID changed, triggers context cache update
## Message Volume