AutistMask/README.md

# AutistMask

AutistMask is a GPL-licensed JavaScript browser extension by
[@sneak](https://sneak.berlin) that provides a minimal Ethereum wallet for
Chrome and Firefox. It manages HD wallets derived from BIP-39 seed phrases and
supports sending and receiving ETH and ERC-20 tokens, as well as web3 site
connection and authentication via the EIP-1193 provider API.

## Getting Started

```bash
git clone https://git.eeqj.de/sneak/autistmask.git
cd autistmask
yarn install
make build
```

Load the extension:

- **Chrome**: Navigate to `chrome://extensions/`, enable "Developer mode", click
  "Load unpacked", and select the `dist/chrome/` directory.
- **Firefox**: Navigate to `about:debugging#/runtime/this-firefox`, click "Load
  Temporary Add-on", and select `dist/firefox/manifest.json`.

## Rationale

MetaMask has become bloated with swap UIs, portfolio dashboards, analytics,
tracking, and advertisements. It is no longer a simple wallet. Most alternatives
(Rabby, Rainbow, etc.) only support Chromium browsers, leaving Firefox users
without a usable option.

AutistMask exists to provide the absolute minimum viable Ethereum wallet
experience: manage seed phrases, derive HD addresses, send and receive ETH and
ERC-20 tokens, and connect to web3 sites. Nothing else. No swaps (that's what
the web is for), no analytics, no tracking, no ads, no portfolio views, no NFT
galleries. Just a wallet.

## Design

AutistMask is a browser extension targeting both Chrome (Manifest V3) and
Firefox (Manifest V2/V3 as supported). The codebase is shared between both
targets with platform-specific manifest files and a build step that produces
separate output directories.

### Architecture

```
src/
  background/       — service worker / background script
    index.js        — extension lifecycle, message routing
    wallet.js       — wallet management (create, import, derive)
    provider.js     — EIP-1193 JSON-RPC provider implementation
    transaction.js  — transaction construction and signing
  popup/            — popup UI (the main wallet interface)
    index.html
    index.js
    components/     — UI components (account list, send form, etc.)
    styles/         — CSS
  content/          — content script injected into web pages
    index.js        — injects the provider into page context
    inpage.js       — the window.ethereum provider object
  shared/           — shared utilities
    crypto.js       — BIP-39 mnemonic, HD key derivation, signing
    storage.js      — encrypted storage abstraction
    constants.js    — chain IDs, default RPC endpoints, ERC-20 ABI
    rpc.js          — JSON-RPC client for Ethereum nodes
manifest/
  chrome.json       — Manifest V3 for Chrome
  firefox.json      — Manifest V2/V3 for Firefox
```

### Key Decisions

- **No framework**: The popup UI is vanilla JS and HTML. The extension is small
  enough that a framework adds unnecessary complexity and attack surface.
- **Encrypted storage**: Seed phrases are encrypted with a user-provided
  password using AES-256-GCM before being stored in the extension's local
  storage. The encryption key is derived from the password using PBKDF2 with a
  high iteration count.
- **BIP-39 / BIP-44**: Standard mnemonic generation and HD key derivation
  (`m/44'/60'/0'/0/n`) for Ethereum address compatibility.
- **EIP-1193 provider**: The content script injects a `window.ethereum` object
  that implements the EIP-1193 provider interface, enabling web3 site
  connectivity.
- **Minimal RPC**: The extension communicates with Ethereum nodes via JSON-RPC.
  The default endpoint is configurable. No Infura dependency — users can point
  it at any Ethereum JSON-RPC endpoint.
- **No external services**: No analytics, no tracking, no telemetry, no ads, no
  phishing lists, no token price feeds. The extension only talks to the
  configured Ethereum RPC endpoint.

### Supported Functionality

- Create new wallet from generated BIP-39 mnemonic
- Import wallet from existing BIP-39 mnemonic
- Derive multiple HD addresses per wallet (`m/44'/60'/0'/0/n`)
- View ETH balance
- View ERC-20 token balances (user adds token by contract address)
- Send ETH to an address
- Send ERC-20 tokens to an address
- Receive ETH/tokens (display address + copy to clipboard)
- Connect to web3 sites (EIP-1193 `eth_requestAccounts`)
- Sign transactions requested by connected sites
- Sign messages (`personal_sign`, `eth_sign`)
- Switch between wallets/accounts
- Lock/unlock with password
- Configurable RPC endpoint

### Non-Goals

- Token swaps (use a DEX in the browser)
- Portfolio/price tracking
- NFT display or management
- Multi-chain support (Ethereum mainnet only, for now)
- Analytics, telemetry, or tracking of any kind
- Advertisements or promotions
- Phishing detection (use your brain)
- Hardware wallet support (maybe later)

## TODO

- [ ] Set up build system (webpack/esbuild) for Chrome and Firefox targets
- [ ] Implement BIP-39 mnemonic generation and validation
- [ ] Implement BIP-32/BIP-44 HD key derivation for Ethereum
- [ ] Implement encrypted storage for seed phrases
- [ ] Build popup UI: lock screen, account list, send/receive views
- [ ] Implement background wallet manager
- [ ] Implement EIP-1193 provider and content script injection
- [ ] Implement ETH send/receive
- [ ] Implement ERC-20 token management (add by contract, view balance, send)
- [ ] Implement site connection approval flow
- [ ] Implement transaction signing approval flow
- [ ] Implement message signing (`personal_sign`, `eth_sign`)
- [ ] Add configurable RPC endpoint
- [ ] Test on Chrome and Firefox
- [ ] Write tests for crypto operations
- [ ] Write tests for transaction construction
- [ ] Security audit of key management

## License

GPL-3.0. See [LICENSE](LICENSE).

## Author

[@sneak](https://sneak.berlin)