diff options
Diffstat (limited to 'architecture.md')
| -rw-r--r-- | architecture.md | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/architecture.md b/architecture.md new file mode 100644 index 0000000..986be62 --- /dev/null +++ b/architecture.md @@ -0,0 +1,128 @@ +# Architecture + +## Runtime Topology + +Four execution contexts: + +### 1. Background Page (control plane) +- Entry: `background/background.html` → `background/background.js` (2.9MB minified) +- Also loads: `background/health-check.js` (responds to `health-check-request`) +- Central broker for all policy decisions, vault operations, native messaging, sync, telemetry +- Initializes: database, core interface (WASM), feature flags (Unleash), native app connection, XAM backend, context menus, Watchtower data +- Event subscriptions handle account changes, lock/unlock, session state transitions +- Exports `b5xHandlers` for b5 web app integration and `initializeFinishedPromise` for startup gating + +### 2. Content Script Bootstrap (every page, every frame) +- Entry: `inline/inject-content-scripts.js` at `document_start`, `all_frames: true`, `<all_urls>` +- Guards against double-injection (`injectJsHasStarted` property) +- Dynamically imports two modules: + - `/inline/injected.js` (368KB) — always loaded (page managers, autofill, inline menu, frame management) + - `/inline/injected/heuristics.js` — conditionally loaded when `login-detection-is-enabled` returns true from background +- Import retry logic: 3 attempts with 25ms/50ms delays between retries +- Error reporting via `report-error` message to background +- Initializes a `LogReporter` (logger) that forwards all content-script logs to background via `new-tab-log-event` + +### 3. Specialized Content Scripts (host-specific) +Declared in manifest, loaded on matching hosts: + +| Script | Hosts | Timing | Purpose | +|--------|-------|--------|---------| +| `webauthn.js` + `webauthn-listeners.js` | `https://*/*`, `http://localhost/*` | `document_start` | WebAuthn/passkey mediation (see [webauthn-analysis.md](webauthn-analysis.md)) | +| `b5.js` | `*.1password.com/ca/eu`, `*.b5dev.*`, `*.b5test.*`, `*.b5local.*`, `*.b5staging.*`, `*.b5rev.*` | `document_idle` | 1Password web app integration, SSO completion, session init | +| `kolide.js` | `app.kolide.com/ca/eu`, `auth.kolide.com/ca/eu` | `document_start` | Kolide device trust / EPM integration | +| `secure-remote-autofill-start-pairing.js` | `www.director.ai/?*`, `www.director.ai/` | `document_end` | Remote autofill pairing initiation | +| `secure-remote-autofill-complete-pairing.js` | `www.director.ai/complete-1password-pairing*` | `document_end` | Remote autofill pairing completion | +| `autofill.js` | `autofill.me/*` | `document_start` | Test/demo autofill site | + +### 4. Extension UI Surfaces +- `app/app.html` + `app/app.js` (682KB) — main extension window/panel +- `popup/index.html` + `popup/index.js` (399KB) + `popup/set-popup-width.js` — browser action popup +- `launcher/apps.html` + `launcher/apps.js` — app launcher +- `inline/menu/menu.html` — inline autofill suggestion menu (web-accessible) +- `inline/modal/modal.html` — modal dialogs for Privacy.com, email alias, Brex (web-accessible) +- `inline/notification/notification.html` — save/update notifications (web-accessible) +- `inline/universal-sign-on/universal-sign-on.html` — USO banner (web-accessible) +- `inline/tutorial/tutorial.html` — onboarding tutorial +- `devtools/devtools.html` + `devtools/panels.html` — DevTools logging panel + +## Chunk System + +356 chunk files under `chunks/`. Two categories: +- **Code chunks**: `chunk-{HASH}.js` — shared logic modules (largest: `chunk-OJR52IF5.js` at 1.9MB, `chunk-MSIWLBOQ.js` at 804KB, `chunk-22IBMJDR.js` at 138KB) +- **Icon/asset chunks**: named by icon (e.g., `icon_creditcard_color_32-HASH.js`, `sso_login_okta_32-HASH.js`) + +Semantic chunk name patterns observed: `account-family`, `account-team`, `developer_watchtower`, `browserbase_logo`, `browseruse-icon`, `anchor-browser-icon`, `browser-polyfill`, `import_guide_pen`. + +## WASM Modules + +Seven WebAssembly modules in `assets/wasm/` (total ~30MB): + +| Module | Size | Likely Purpose | +|--------|------|----------------| +| `op_wasm_b5x_bg` | 15.6MB | Core vault/crypto operations for b5x (extension) | +| `op_wasm_xam_bg` | 11.2MB | XAM (cross-app management / device trust) backend | +| `confidential_computing_bg` | 1.8MB | Confidential computing primitives | +| `b5_trustlog_bg` | 1.3MB | Trust log generation/verification | +| `b5_trust-verifier_bg` | 1.0MB | Trust verification | +| `b5_mycelium_bg` | 319KB | Mycelium relay protocol (P2P communication for remote autofill) | +| `b5_hpke_bg` | 82KB | Hybrid Public Key Encryption (RFC 9180) | + +The background.js initialization calls `rA.init(e)` ("initializeCoreInterface") which loads the main WASM module. CSP allows `wasm-unsafe-eval` for this purpose. + +## Permission Profile + +### Always granted +`<all_urls>`, `alarms`, `clipboardWrite`, `contextMenus`, `downloads`, `idle`, `management`, `nativeMessaging`, `notifications`, `privacy`, `scripting`, `storage`, `tabs`, `webNavigation`, `webRequest`, `webRequestBlocking`, `declarativeNetRequestWithHostAccess` + +### Optional +`bookmarks` + +### Web-Accessible Resources +Source maps (`*.js.map`), fonts, images, and critically: `inline/injected.js`, `inline/injected/heuristics.js`, `inline/injected/styles/inline-tooltip.css`, and all inline UI HTML files (menu, notification, modal, universal-sign-on). These can be loaded/detected by any web page. + +## Feature Flags + +Unleash-based feature flag system with two tiers: +- **Pre-registration flags**: evaluated before any account is signed in (e.g., `b5x-pre-auth-tracing`) +- **Account-gated feature trials**: per-account feature flags from server + +Background broadcasts `unleash-features-changed` events to all listeners when flags update. Content scripts query individual flags (e.g., `login-detection-is-enabled`). + +## Initialization Sequence + +From `background.js` main init function (reconstructed): + +1. Initialize storage +2. Initialize feature flags cache +3. Check for terminated DB, set icon +4. Get browser language +5. Initialize Sentry +6. Init build info +7. Initialize core interface (WASM load) +8. Set locale +9. Initialize database (IndexedDB) +10. Get device info, sync pre-registration feature flags +11. Start performance observer (if tracing flag set) +12. Load all accounts, set up account handlers +13. Initialize crypto +14. Subscribe to events: session changes, account updates, lock/unlock +15. Load Watchtower data +16. Initialize native app connection +17. Initialize unlock-with-context cache +18. Enable insiders (if appropriate) +19. Initialize XAM backend +20. Initialize App Launcher +21. Migrate storage (if needed) +22. Initialize context menus +23. Initialize notifications + +## External Extension Communication + +3 references to `chrome.runtime.onMessageExternal` — the extension accepts messages from other extensions (likely 1Password desktop app or enterprise connectors). No `externally_connectable` manifest key found, so Firefox's default policy applies. + +## Build/Signing + +- Build channel: `stable` +- Signed by Mozilla AMO Production Signing Service +- COSE + RSA signatures in `META-INF/` +- Sentry debug IDs embedded in every JS file for crash correlation |