@anywalletkit/extension-kit

The security-relevant core of a non-custodial Chromium (MV3) wallet extension, built on the Any Wallet Kit chain and protocol packages: an encrypted vault, the unlocked-key session with auto-lock, the dApp request router with per-origin permissions and an approval queue, signing-request classification, and the review helpers for swaps and Earn plans. No UI, no @types/chrome, no network code of its own: the chrome adapters take structural objects (StorageAreaLike, AlarmsLike), so everything runs under Vitest with in-memory adapters.

Install

npm install @anywalletkit/extension-kit
# or: pnpm add @anywalletkit/extension-kit  ·  yarn add @anywalletkit/extension-kit

On npm: @anywalletkit/extension-kit, published from the release workflow with provenance.

This package is for wallet developers who build their own extension. It is a library, not an extension: the popup, approval windows, injected providers, service-worker wiring, build and release pipeline are the wallet's. The Vaulty browser extension is one product built on it.

pnpm add @anywalletkit/extension-kit @anywalletkit/core @anywalletkit/keyring

What it provides

Security model (summary)

• Keys at rest. Envelope v2: scrypt N=2^17 r=8 p=1 (@noble/hashes) → AES-256-GCM wraps a random 32-byte DEK; the DEK seals each secret under AAD forgewallet-vault/secret/<id> (boxes cannot be swapped). The DEK box's AAD binds the exact KDF parameters, so an envelope whose salt or cost was edited on disk fails to open; unlock refuses sub-floor costs (weak-kdf), and costs or sizes above VAULT_LIMITS (scrypt N ≤ 2^20, r ≤ 16, p ≤ 4; PBKDF2 ≤ 5 000 000 iterations; 1 000 secrets, 32 passkeys, 4 MiB) before any KDF runs (unsupported-envelope). Writes to the envelope are serialized (one Vault per storage area), so parallel imports keep every secret. v1 envelopes (PBKDF2-SHA256, ≥ 600 000 iterations) still open and are re-sealed as v2. Passwords shorter than 8 characters are refused by the vault itself. Wrong password and tampering are the same failure (wrong-password). create never overwrites; reset is an explicit destroy().
• Passkeys. A passkey wraps the same DEK under HKDF-SHA256(PRF output, salt = credential id); the password stays the recovery path.
• Re-keying. changePassword re-wraps the same DEK, and removePasskey does not take back a DEK the passkey already unwrapped. After a suspected compromise, rotateVaultKey(password) makes a fresh DEK, re-seals every secret, drops the passkeys (register them again) and writes one envelope; hand the returned DEK to session.unlock, which replaces the old one. setSecret refuses a DEK that does not open the vault's secrets.
• Unlocked state. Only the DEK is kept, in chrome.storage.session (memory-only, trusted contexts), with an expiry enforced on every read and an alarm that locks; key buffers this package owns are zeroized after use. unlock / lock / touch / getKey run one at a time, so activity racing a lock never brings the key back.
• Errors to pages. toRelayError(e, { log }) passes the wallet's own refusals (EIP-1193 codes) and a node's JSON-RPC error (code, revert data) with URLs removed; anything else is -32603 Internal error on the page and goes to log.
• Origins. The content script relays only what the page window itself posted (pageRequestFrom: event.source is the page, event.origin its origin), so an ad or embed in an iframe cannot speak as the site. The service worker answers a relay message only when the content script's stamped origin equals port.sender.origin. Permissions are keyed by that origin, never by a URL a page or a WalletConnect peer claims.
• Requests. Everything that reveals accounts or moves funds goes through the approval queue; blind signing (eth_sign) is not offered; typed data for another chain, deployments and site-originated EIP-7702 delegations are refused; read-only RPC goes to the wallet's own endpoints.
• Network. The kit makes no requests of its own beyond the RPC / provider calls the wallet wires in; the phishing list is data the wallet ships.

What stays the wallet's job: the extension-page CSP (script-src 'self', no remote images), a host allowlist for the worker's fetch, isolating third-party network SDKs (WalletConnect, Omniston) in a sandbox page, the reproducible release build and the store account.

Using the chrome adapters

import {
  Vault, Session, PermissionStore, NetworksTable, ApprovalQueue, RequestRouter,
  chromeLocalVaultStorage, chromeSessionStorage, chromeAlarms, chromeJsonStorage,
  chromeKeyringStorage, vaultSecretStorage, checkSenderOrigin, isRelayRequest, PORT_NAME,
} from '@anywalletkit/extension-kit'

// service worker
const vault = new Vault({ storage: chromeLocalVaultStorage(chrome.storage.local) })
const session = new Session({ storage: chromeSessionStorage(chrome.storage.session), alarms: chromeAlarms(chrome.alarms) })

// onboarding
const dek = await vault.create(password)          // refuses if a vault exists or the password is too short
await vault.setSecret(dek, 'main', utf8(seedPhrase))
await session.unlock(dek)                         // dek is zeroized here

// @anywalletkit/keyring on top of the vault
const keyringStorage = chromeKeyringStorage(chrome.storage.local)
const secrets = vaultSecretStorage(vault, session) // VaultError('locked') once the session expired

// the dApp side
const permissions = new PermissionStore(chromeJsonStorage(chrome.storage.local, 'my-wallet.permissions'))
const networks = new NetworksTable(chromeJsonStorage(chrome.storage.local, 'my-wallet.networks'))
const approvals = new ApprovalQueue(myApprovalWindow) // chrome.windows.create({ type: 'popup' }) behind ApprovalWindow
const router = new RequestRouter({ permissions, networks, approvals, accounts, rpc, emit, sign })

chrome.runtime.onConnect.addListener((port) => {
  if (port.name !== PORT_NAME) return
  port.onMessage.addListener(async (msg) => {
    if (!isRelayRequest(msg)) return
    const origin = checkSenderOrigin(port.sender, msg.origin)
    if (!origin) return // forged origin: dropped, not answered
    const result = await router.handle(origin, msg.chain, msg.method, msg.params)
    // post a RelayResponse { kind: 'response', id: msg.id, … } back on the port
  })
})

memoryVaultStorage, memorySessionStorage, memoryAlarms, memoryJsonStorage and memoryApprovalWindow are the in-memory twins for tests.