112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# Browser Extension Architecture & Workflow
|
||
|
||
## Overview
|
||
The browser extension is the main user interface for interacting with the modular Rust cryptographic stack (vault, EVM client, key-value store) and for executing Rhai scripts securely. It is designed for both local (user-driven) scripting and remote (server-driven) workflows.
|
||
|
||
---
|
||
|
||
## Features & Phases
|
||
|
||
### Phase 1: Local Session & Script Execution
|
||
- **Session Management**: User creates/unlocks a keyspace and selects/creates a keypair. Session state is required for all cryptographic operations.
|
||
- **Keypair Actions**:
|
||
- Sign, verify
|
||
- Asymmetric encrypt/decrypt
|
||
- Symmetric encrypt/decrypt (arbitrary messages/files, using password-derived key)
|
||
- Send transaction, check balance (with selected provider)
|
||
- Execute user-provided Rhai scripts (from extension input box)
|
||
- Scripts have access to the session manager's signer; explicit per-script approval is required.
|
||
|
||
### Phase 2: WebSocket Server Integration
|
||
- **Connection**: User connects to a websocket server using the selected keypair's public key. Connection persists as long as the extension is loaded (i.e., its background logic/service worker is active), regardless of whether the popup/UI is open.
|
||
- **Script Delivery & Approval**:
|
||
- Server can send Rhai scripts (with title, description, tags: `local`/`remote`).
|
||
- Extension notifies user of incoming scripts, displays metadata, allows viewing and approval.
|
||
- User must unlock keyspace and select the correct keypair to approve/execute.
|
||
- For `remote` scripts: user signs the script hash and sends signature to server (for consent/authorization; server may execute script).
|
||
- For `local` scripts: script executes locally, and the extension logs and reports the result back to the server.
|
||
- For user-pasted scripts: logs only; server connection not required.
|
||
|
||
---
|
||
|
||
## Security Considerations
|
||
|
||
### Restricting WASM and Session API Access to the Extension
|
||
|
||
To ensure that sensitive APIs (such as session state, cryptographic operations, and key management) are accessible **only** from the browser extension and not from arbitrary web pages, follow these best practices:
|
||
|
||
1. **Export Only Safe, High-Level APIs**
|
||
- Use `#[wasm_bindgen]` only on functions you explicitly want to expose to the extension.
|
||
- Do **not** export internal helpers, state singletons, or low-level APIs.
|
||
|
||
```rust
|
||
// Safe to export
|
||
#[wasm_bindgen]
|
||
pub fn run_rhai(script: &str) -> Result<JsValue, JsValue> {
|
||
// ...
|
||
}
|
||
|
||
// NOT exported: internal state
|
||
// pub static SESSION_MANAGER: ...
|
||
```
|
||
|
||
2. **Do Not Attach WASM Exports to `window` or `globalThis`**
|
||
- When loading the WASM module in your extension, do not attach its exports to any global object accessible by web pages.
|
||
- Keep all WASM interaction within the extension’s background/content scripts.
|
||
|
||
3. **Validate All Inputs**
|
||
- Even though only your extension should call WASM APIs, always validate inputs to exported functions to prevent injection or misuse.
|
||
|
||
4. **Use Message Passing Carefully**
|
||
- If you use `postMessage` or similar mechanisms, always check the message origin and type before processing.
|
||
- Only process messages from trusted origins (e.g., your extension’s own scripts).
|
||
|
||
5. **Load WASM in Extension-Only Context**
|
||
- Load and instantiate the WASM module in a context (such as a background script or content script) that is not accessible to arbitrary websites.
|
||
- Never inject your WASM module directly into web page scopes.
|
||
|
||
#### Example: Secure WASM Export
|
||
|
||
```rust
|
||
// Only export high-level, safe APIs
|
||
#[wasm_bindgen]
|
||
pub fn run_rhai(script: &str) -> Result<JsValue, JsValue> {
|
||
// ...
|
||
}
|
||
// Do NOT export SESSION_MANAGER or internal helpers
|
||
```
|
||
|
||
#### Example: Secure JS Loading (Extension Only)
|
||
|
||
```js
|
||
// In your extension's background or content script:
|
||
import init, { run_rhai } from "./your_wasm_module.js";
|
||
|
||
// Only your extension's JS can call run_rhai
|
||
// Do NOT attach run_rhai to window/globalThis
|
||
```
|
||
|
||
By following these guidelines, your WASM session state and sensitive APIs will only be accessible to your browser extension, not to untrusted web pages.
|
||
|
||
### Session Password Handling
|
||
- The extension stores the keyspace password (or a derived key) securely in memory only for the duration of an unlocked session. The password is never persisted or written to disk/storage, and is zeroized from memory immediately upon session lock/logout, following cryptographic best practices (see also Developer Notes below).
|
||
- **Signer Access**: Scripts can access the session's signer only after explicit user approval per execution.
|
||
- **Approval Model**: Every script execution (local or remote) requires user approval.
|
||
- **No global permissions**: Permissions are not granted globally or permanently.
|
||
|
||
---
|
||
|
||
## UI/UX Guidelines
|
||
- Use any robust, modern, and fast UI framework (React, Svelte, etc.).
|
||
- Dark mode is recommended.
|
||
- UI should be responsive, intuitive, and secure.
|
||
- All cryptographic operations and script executions must be clearly auditable and user-approved.
|
||
|
||
---
|
||
|
||
## Developer Notes
|
||
- Extension is the canonical interface for scripting and secure automation.
|
||
- CLI and additional server features are planned for future phases.
|
||
- For vault and scripting details, see [rhai_architecture_plan.md].
|
||
- For EVM client integration, see [evm_client_architecture_plan.md].
|