.cursorrules

# Cursor Rules — canary-kit

Deepfake-proof identity verification library. Derives spoken words from shared secrets using HMAC-SHA256 counters.

## Commands

- `npm run build` — compile TypeScript to dist/
- `npm test` — run all tests (vitest)
- `npm run typecheck` — type-check without emitting

## Conventions

- British English — colour, initialise, behaviour, licence
- ESM-only — "type": "module" in package.json
- TDD — write a failing test first, then implement
- Pure functions — group management returns new state, never mutates input
- Minimal dependencies — core crypto is pure JS; only @scure/bip32 and @scure/bip39 for mnemonic recovery
- Commit messages — type: description format (feat:, fix:, docs:, chore:, refactor:). No Co-Authored-By lines.

## Key Patterns

- All group functions return new GroupState, never mutate input
- Crypto in src/crypto.ts is synchronous pure JS (SHA-256, HMAC-SHA256)
- Only src/beacon.ts and src/sync-crypto.ts use async crypto (crypto.subtle for AES-256-GCM)
- Nostr event builders return UnsignedEvent — signing is the caller's responsibility
- Sync protocol validates against 6 invariants (admin checks, epoch ordering, replay protection)
- All public APIs validate inputs and throw on invalid parameters

## Structure

- src/ — library source (15 modules + tests alongside as *.test.ts)
- app/ — interactive demo app (Vite, builds to docs/)
- Eight subpath exports: canary-kit, canary-kit/token, canary-kit/encoding, canary-kit/session, canary-kit/wordlist, canary-kit/nostr, canary-kit/beacon, canary-kit/sync