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

---

## Script Permissions & Security
- **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].