Imported from diegogurpegui/nos2x-fox (AGENTS.md). Install upstream with npx skills add diegogurpegui/nos2x-fox. Copyright stays with the author.

nos2x-fox

Firefox browser extension (Manifest V2) that implements NIP-07: a Nostr signer exposing window.nostr to web apps so they can sign events and encrypt/decrypt without receiving private keys.

Fork of nos2x, adapted for Firefox. Optional PIN protection (AES-GCM-256) encrypts stored keys; unlocked PIN is cached in memory for 10 minutes.

For functional details (install, PIN setup, API methods), see README.md.

Stack

• TypeScript, React 19, WebExtension APIs (webextension-polyfill)
• nostr-tools for Nostr crypto and event handling
• esbuild bundles src/ → dist/

Architecture

Web page  →  content-script.js  →  background.js  ←  popup / options / prompt / pin (React UIs)
              injects nostr-provider.js (window.nostr)

• content-script.js — Injects nostr-provider.js and relays messages between the page and the background.
• nostr-provider.ts — Defines window.nostr API; forwards calls to the background via messaging.
• background.ts — Core logic: key management, signing, encryption, permissions, prompt orchestration.
• storage.ts — Persists keys, relays, and settings via browser.storage.
• pinEncryption.ts / pinCache.ts — PIN setup, key encryption/decryption, ephemeral PIN cache.
• common.ts — Shared helpers (key derivation, popup windows, authorization rules).
• types.ts — Shared TypeScript types and message shapes.

UI entry points

Commands

yarn install
yarn build          # production build → dist/
yarn watch          # rebuild on file changes
yarn start:firefox  # run extension in Firefox via web-ext

Load the extension from dist/ (about:debugging → Load Temporary Add-on).

Technical references

NIPs (Nostr Implementation Proposals) relevant to this project:

• NIP-07 — window.nostr browser capability
• NIP-04 — Encrypted Direct Message (deprecated in favor of NIP-17)
• NIP-17 — Private Direct Messages
• NIP repository

Code guidelines

• DRY — Reuse existing code when appropriate.
• KISS — Keep changes as simple as possible.
• Do not add new dependencies; use only what is already in package.json.
• Update README.md when a change affects user-facing behavior already documented there.
• Group related code together (helpers, types, enums for the same domain).