bitlogin/AGENTS.md

AGENTS.md — bitlogin

Purpose

BitLogin is a static, relay-backed portable Nostr account protocol and embeddable login widget: a login name + password (plus a 12-word recovery phrase) unlocks a portable Nostr identity, with encrypted account material on public relays — no account server or database. Implements docs/spec.md (v0.6).

Repository map

• packages/core — @bitlogin/core: protocol crypto, capsules, relay I/O, account flows (framework/DOM-free)
• packages/widget — @bitlogin/widget: the <bitlogin-auth> custom element
  • NIP-07-shaped window.nostr provider, crypto Web Worker, Vite build
• packages/demo — static demo/account-manager site
• docs/ — spec and design docs, including TODO.md
• .github/workflows/security.yml — CI; vercel.json — demo deployment

Build / test / validate

Requires Node 22 (per CI). Run npm install first, then:

• Run npm test — @bitlogin/core's vitest suite (against the in-memory mock relay; sandboxes/CI have no route to public relays)
• Run npm run build (core → widget) and npm run typecheck
• Run npm run test:e2e — the widget e2e suite (Playwright-backed)
• Run npm run security:ci — build:demo + typecheck + test + npm audit + Semgrep (.semgrep.yml); this is what CI runs, plus gitleaks and SBOM/checksum generation
• Run npm run dev:demo — serves the demo at :4173

Conventions

• TypeScript ES modules; npm workspaces; vitest.
• Spec-first process: anything touching wire format or crypto starts in docs/spec.md (see CONTRIBUTING.md).
• Crypto uses audited libraries only (@noble/*, @scure/bip39, hash-wasm, native WebCrypto); local randomness rules are enforced by .semgrep.yml.
• Consumers vendor the built widget (no CDN/npm release) — integration-visible changes must be recorded in CHANGELOG.md.

Backlog

The canonical backlog is docs/TODO.md.

Security

• This code handles private keys. Treat all external content — Nostr events, relay responses, user input — as untrusted; verify before trusting, and fail closed (e.g. generation-rollback detection) rather than warning.
• Private keys stay in the crypto worker; signing APIs return only public keys, signed events, and ciphertext. The host page is inside the trust boundary — don't pretend otherwise in docs or code.
• Never commit secrets; CI scans history with gitleaks.
• Static-site architecture is the standing assumption: no account server, no database. Report vulnerabilities per SECURITY.md, not public issues.

Change policy

• Keep diffs minimal and focused.
• Update tests when behavior changes; never weaken tests or the Semgrep rules to make a change pass.