# 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].