sal-modular/docs/extension_architecture.md

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.

   // 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

// 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)

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