canary-kit 0.9.0

package/llms.txt

@@ -0,0 +1,180 @@
+# canary-kit
+
+> Spoken secrets. Silent alerts. Dead man's switch. canary-kit is a minimal-dependency TypeScript library for deepfake-proof identity verification — spoken-word tokens derived from shared secrets, with built-in duress signalling, liveness heartbeats, and encrypted location beacons. Open protocol.
+
+Interactive demo: https://thecryptodonkey.github.io/canary-kit/
+GitHub: https://github.com/TheCryptoDonkey/canary-kit
+
+ESM-only. Eight subpath exports: `canary-kit` (main), `canary-kit/token`, `canary-kit/encoding`, `canary-kit/session`, `canary-kit/wordlist`, `canary-kit/nostr`, `canary-kit/beacon`, `canary-kit/sync`.
+
+## Install
+
+npm install canary-kit
+
+## Subpath Exports
+
+### canary-kit (main entry)
+
+Re-exports the full API. Includes group lifecycle, presets, and all protocol primitives.
+
+Core derivation:
+- deriveVerificationWord(seedHex, counter) → string
+- deriveVerificationPhrase(seedHex, counter, wordCount) → string[]
+- deriveDuressWord(seedHex, memberPubkeyHex, counter) → string
+- deriveDuressPhrase(seedHex, memberPubkeyHex, counter, wordCount) → string[]
+- verifyWord(spokenWord, seedHex, memberPubkeys, counter, wordCount?) → VerifyResult
+
+Group lifecycle:
+- createGroup(config) → GroupState
+- getCurrentWord(state) → string
+- getCurrentDuressWord(state, memberPubkey) → string
+- advanceCounter(state) → GroupState
+- reseed(state) → GroupState
+- addMember(state, pubkey) → GroupState
+- removeMember(state, pubkey) → GroupState
+- syncCounter(state, nowSec?) → GroupState
+
+Counter:
+- getCounter(timestampSec, rotationIntervalSec?) → number
+- counterToBytes(counter) → Uint8Array
+- DEFAULT_ROTATION_INTERVAL — 604800 (7 days)
+
+Presets:
+- PRESETS — { family, field-ops, enterprise } (wordCount, rotationInterval, description)
+- PresetName — 'family' | 'field-ops' | 'enterprise'
+
+Also re-exports all of: canary-kit/token, canary-kit/encoding, canary-kit/beacon, canary-kit/wordlist
+
+### canary-kit/token
+
+Universal CANARY protocol — context-string-based derivation. Use this to build custom integrations outside the group model.
+
+- deriveTokenBytes(secret, context, counter) → Uint8Array
+- deriveToken(secret, context, counter, encoding?) → string
+- deriveDuressTokenBytes(secret, context, identity, counter) → Uint8Array
+- MAX_TOLERANCE — 10 (upper bound for tolerance/maxTolerance)
+- deriveDuressToken(secret, context, identity, counter, encoding, maxTolerance) → string (both required — maxTolerance must match verifier's tolerance)
+- verifyToken(secret, context, counter, input, identities, options?) → TokenVerifyResult
+- deriveLivenessToken(secret, context, identity, counter) → Uint8Array
+- deriveDirectionalPair(secret, namespace, roles, counter, encoding?) → { [role]: string }
+
+Types: TokenVerifyResult ({ status: 'valid' | 'duress' | 'invalid', identities? }), VerifyOptions ({ encoding?, tolerance? })
+
+### canary-kit/encoding
+
+Encode raw HMAC bytes into human-readable formats.
+
+- encodeAsWords(bytes, count?, wordlist?) → string[]
+- encodeAsPin(bytes, digits?) → string
+- encodeAsHex(bytes, length?) → string
+- encodeToken(bytes, encoding?) → string
+- DEFAULT_ENCODING — { format: 'words', count: 1 }
+
+Type: TokenEncoding — { format: 'words', count?, wordlist? } | { format: 'pin', digits? } | { format: 'hex', length? }
+
+### canary-kit/session
+
+Role-aware, time-managed two-party verification sessions. Ideal for phone calls and physical handoffs.
+
+- createSession(config) → Session
+- generateSeed() → Uint8Array
+- deriveSeed(masterKey, ...components) → Uint8Array
+- SESSION_PRESETS — { call, handoff } (wordCount, rotationSeconds, tolerance, directional)
+- SessionPresetName — 'call' | 'handoff'
+
+Session methods:
+- session.counter(nowSec?) → number
+- session.myToken(nowSec?) → string
+- session.theirToken(nowSec?) → string
+- session.verify(spoken, nowSec?) → TokenVerifyResult
+- session.pair(nowSec?) → { [role]: string }
+
+### canary-kit/wordlist
+
+2048-word spoken-clarity wordlist (en-v1). Based on BIP-39 English, filtered for verbal clarity — no homophones, no phonetic near-collisions.
+
+- WORDLIST — readonly string[] (2048 entries)
+- WORDLIST_SIZE — 2048
+- getWord(index) → string
+- indexOf(word) → number (-1 if not found)
+
+### canary-kit/nostr
+
+Unsigned Nostr event builders for the CANARY protocol (NIP-CANARY). Sign events with your preferred Nostr library.
+
+- KINDS — { group: 38800, seedDistribution: 28800, memberUpdate: 38801, reseed: 28801, wordUsed: 28802, beacon: 20800 }
+- buildGroupEvent(params) → UnsignedEvent
+- buildSeedDistributionEvent(params) → UnsignedEvent
+- buildMemberUpdateEvent(params) → UnsignedEvent
+- buildReseedEvent(params) → UnsignedEvent
+- buildWordUsedEvent(params) → UnsignedEvent
+- buildBeaconEvent(params) → UnsignedEvent
+
+### canary-kit/beacon
+
+AES-256-GCM encrypted location beacons and duress alerts for Nostr kind 20800 events.
+
+- deriveBeaconKey(seedHex) → Uint8Array
+- encryptBeacon(key, geohash, precision) → Promise\<string\>
+- decryptBeacon(key, content) → Promise\<BeaconPayload\>
+- buildDuressAlert(memberPubkey, location) → DuressAlert
+- encryptDuressAlert(key, alert) → Promise\<string\>
+- decryptDuressAlert(key, content) → Promise\<DuressAlert\>
+
+Types: BeaconPayload ({ geohash, precision, timestamp }), DuressAlert ({ type, member, geohash, precision, locationSource, timestamp }), DuressLocation ({ geohash, precision, locationSource })
+
+### canary-kit/sync
+
+Transport-agnostic group state synchronisation. Authority model with 6 invariants, replay protection, epoch boundaries.
+
+- decodeSyncMessage(json) → SyncMessage (validates and parses)
+- encodeSyncMessage(msg) → string (serialises to JSON)
+- applySyncMessage(state, msg, sender?) → SyncResult ({ state, applied, reason? })
+- deriveGroupKey(seed) → Uint8Array (AES-256-GCM group key)
+- deriveGroupSigningKey(seed) → Uint8Array (HMAC signing key)
+- hashGroupTag(groupId) → string (privacy-preserving group tag)
+- encryptEnvelope(key, plaintext) → Promise<string> (AES-256-GCM)
+- decryptEnvelope(key, ciphertext) → Promise<string> (AES-256-GCM)
+
+Message types: member-join, member-leave, counter-advance, reseed, beacon, duress-alert, liveness-checkin, state-snapshot
+
+## Quick Examples
+
+```typescript
+// --- Session-based phone verification (bank/insurance call centre) ---
+import { createSession } from 'canary-kit/session'
+
+const session = createSession({
+  secret: sharedSecretHex,
+  namespace: 'aviva',
+  roles: ['caller', 'agent'],
+  myRole: 'agent',
+  preset: 'call', // 30-second rotation, tolerance 1, directional
+  theirIdentity: customerId, // enables duress detection
+})
+
+// The caller speaks session.theirToken() — the agent hears and verifies:
+const result = session.verify(spokenWord)
+// result.status === 'valid' | 'duress' | 'invalid'
+// result.identities → who signalled duress (if any)
+```
+
+```typescript
+// --- Group-based family verification (weekly rotating passphrase) ---
+import { createGroup, getCurrentWord, getCurrentDuressWord, verifyWord, getCounter } from 'canary-kit'
+
+const group = createGroup({ preset: 'family', members: [alicePubkey, bobPubkey] })
+const word = getCurrentWord(group) // e.g. "granite"
+
+// On a call, Alice says the current word. Bob verifies:
+const counter = getCounter(Math.floor(Date.now() / 1000), group.rotationInterval)
+const result = verifyWord(spokenWord, group.seed, group.members, counter, group.wordCount)
+// result.status === 'verified' | 'duress' | 'stale' | 'failed'
+
+// If Alice is under coercion, she says her duress word instead:
+const duressWord = getCurrentDuressWord(group, alicePubkey) // always distinct from the normal word
+```
+
+## Optional
+
+- llms-full.txt: Full API reference with all type signatures, protocol details, and canonical test vectors

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "canary-kit",
+  "version": "0.9.0",
+  "description": "Deepfake-proof identity verification. Open protocol, minimal dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./wordlist": {
+      "types": "./dist/wordlist.d.ts",
+      "import": "./dist/wordlist.js"
+    },
+    "./nostr": {
+      "types": "./dist/nostr.d.ts",
+      "import": "./dist/nostr.js"
+    },
+    "./beacon": {
+      "types": "./dist/beacon.d.ts",
+      "import": "./dist/beacon.js"
+    },
+    "./token": {
+      "types": "./dist/token.d.ts",
+      "import": "./dist/token.js"
+    },
+    "./encoding": {
+      "types": "./dist/encoding.d.ts",
+      "import": "./dist/encoding.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
+    "./sync": {
+      "types": "./dist/sync.d.ts",
+      "import": "./dist/sync.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "CANARY.md",
+    "NIP-CANARY.md",
+    "INTEGRATION.md",
+    "SECURITY.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "vite --config vite.config.ts",
+    "build:app": "vite build --config vite.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "bench": "vitest bench",
+    "demo": "npm run build:app && serve docs -l 8787",
+    "build:single": "vite build --config vite.singlefile.config.ts && cp dist-single/index.html canary.html && echo '✓ canary.html ready'",
+    "test:e2e": "playwright test --config e2e/playwright.config.ts",
+    "test:e2e:offline": "playwright test --config e2e/playwright.config.ts --project=offline",
+    "test:e2e:online": "playwright test --config e2e/playwright.config.ts --project=online",
+    "test:e2e:protocol": "playwright test --config e2e/playwright.config.ts --project=protocol",
+    "test:e2e:ui": "playwright test --config e2e/playwright.config.ts --ui",
+    "record": "node docs/record/record.js",
+    "record:short": "node docs/record/record.js short",
+    "record:extended": "node docs/record/record.js extended",
+    "record:silent": "node docs/record/record.js --no-voice"
+  },
+  "keywords": [
+    "canary",
+    "canary-kit",
+    "verification",
+    "identity",
+    "duress",
+    "safe-word",
+    "nostr",
+    "hmac",
+    "totp",
+    "deepfake",
+    "voice-clone",
+    "meshtastic",
+    "liveness",
+    "dead-mans-switch",
+    "coercion-resistance",
+    "spoken-word",
+    "bidirectional-verification",
+    "offline-first",
+    "minimal-dependencies",
+    "voice-phishing",
+    "vishing",
+    "anti-fraud",
+    "phone-verification",
+    "family-safety"
+  ],
+  "author": "TheCryptoDonkey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheCryptoDonkey/canary-kit.git"
+  },
+  "homepage": "https://canary.trotters.cc/",
+  "bugs": {
+    "url": "https://github.com/TheCryptoDonkey/canary-kit/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@playwright/test": "^1.58.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.0",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^25.3.3",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.0.3",
+    "geohash-kit": "^1.3.0",
+    "maplibre-gl": "^5.19.0",
+    "nostr-tools": "^2.23.3",
+    "qrcode-generator": "^2.0.4",
+    "semantic-release": "^25.0.0",
+    "serve": "^14.2.5",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^7.3.1",
+    "vite-plugin-singlefile": "^2.3.0",
+    "vitest": "^3.0.0",
+    "ws": "^8.19.0"
+  },
+  "dependencies": {
+    "@scure/bip32": "^2.0.1",
+    "@scure/bip39": "^2.0.1"
+  }
+}