canary-kit 0.9.0

package/README.md

@@ -0,0 +1,187 @@
+# canary-kit
+
+> Deepfake-proof identity verification. Open protocol, minimal dependencies.
+
+[![npm](https://img.shields.io/npm/v/canary-kit)](https://www.npmjs.com/package/canary-kit)
+[![CI](https://github.com/TheCryptoDonkey/canary-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/TheCryptoDonkey/canary-kit/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)](https://www.typescriptlang.org/)
+[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](vitest.config.ts)
+
+**[Interactive Demo](https://thecryptodonkey.github.io/canary-kit/)** · [Protocol Spec](CANARY.md) · [Nostr Binding](NIP-CANARY.md) · [Integration Guide](INTEGRATION.md)
+
+## The Problem
+
+Voice phishing surged 442% in 2025. AI can clone a voice from three seconds of
+audio. The tools that were supposed to protect us are failing:
+
+- **Security questions** are one-directional and socially engineerable
+- **Voice biometrics** — 91% of US banks are reconsidering after deepfake attacks
+- **TOTP codes** prove you to a server, but never prove the server to you
+- **"Family safe words"** are static, never rotate, and have no duress signalling
+
+CANARY is the first protocol that combines **bidirectional verification** (both
+sides prove identity), **coercion resistance** (duress tokens), and **spoken-word
+output** — three properties that have never existed together in a standard.
+
+It works because cloning a voice doesn't help you derive the right word. Only
+knowledge of the shared secret does.
+
+## Quick Start
+
+```bash
+npm install canary-kit
+```
+
+### Phone Verification (Insurance, Banking)
+
+```typescript
+import { createSession } from 'canary-kit/session'
+
+const session = createSession({
+  secret: sharedSeed,
+  namespace: 'aviva',
+  roles: ['caller', 'agent'],
+  myRole: 'agent',
+  preset: 'call',
+})
+
+session.myToken()        // "choose" — what I speak
+session.theirToken()     // "bid" — what I expect to hear
+session.verify('bid')    // { status: 'valid' }
+```
+
+### Family / Team Verification
+
+```typescript
+import { createGroup, getCurrentWord, verifyWord, getCounter } from 'canary-kit'
+
+const group = createGroup({
+  name: 'Family',
+  members: [alicePubkey, bobPubkey],
+  preset: 'family',
+})
+
+getCurrentWord(group)  // "falcon"
+```
+
+## Use Cases
+
+| Use case | Preset | Rotation | What it replaces |
+|----------|--------|----------|------------------|
+| Insurance phone calls | `call` | 30 seconds | Security questions |
+| Banking phone calls | `call` | 30 seconds | Voice biometrics, callbacks |
+| Rideshare/delivery handoff | `handoff` | Single-use | Random PINs |
+| Family safety | `family` | 7 days | Static safe words |
+| Journalism / activism | `field-ops` | 24 hours | Nothing (no existing standard) |
+| Enterprise incident response | `enterprise` | 48 hours | Challenge-response over email |
+
+## Why Not Just...
+
+| Solution | Limitation CANARY solves |
+|----------|------------------------|
+| Security questions | One-directional. Socially engineerable. No rotation. |
+| Voice biometrics | Defeated by AI voice cloning. One-directional. |
+| TOTP (Google Auth) | Machine-readable digits, not spoken words. No duress. One-directional. |
+| Callback numbers | Slow. Doesn't prove the agent's identity. |
+| BIP-39 wordlist | No verification protocol. No rotation. No duress. |
+| "Family safe word" | Static. No rotation. No duress. No protocol. |
+| **CANARY** | **Bidirectional. Deepfake-proof. Duress-aware. Rotating. Offline. Open.** |
+
+## Why Canary
+
+**Bidirectional.** Both sides prove identity. The caller proves they know the secret, and the agent proves it back. Neither can impersonate the other.
+
+**Built on proven primitives.** CANARY extends the HMAC-counter pattern from HOTP (RFC 4226) and TOTP (RFC 6238) to human-to-human spoken verification, adding duress signalling and coercion resistance.
+
+**Offline-first.** Words are derived locally from a shared seed and a time-based counter. No network is required after initial setup.
+
+**Duress-aware.** Every party has a personal duress word distinct from the verification word. Speaking it silently alerts the system while giving the attacker plausible deniability.
+
+**Automatic rotation.** Configurable intervals — 30 seconds for phone calls, 7 days for family groups.
+
+**Minimal dependencies.** Core crypto is pure JavaScript. Only `@scure/bip32` and `@scure/bip39` for mnemonic key recovery. Requires `globalThis.crypto` (Web Crypto API): all browsers, Node.js 22+, Deno, and edge runtimes.
+
+**Protocol-grade.** Formal specification with published test vectors and a curated 2048-word spoken-clarity wordlist.
+
+## Compatibility
+
+| Runtime | Version | Notes |
+|---------|---------|-------|
+| Node.js | 22+ | Full support (`globalThis.crypto` required) |
+| Deno | 1.x+ | Full support |
+| Bun | 1.x+ | Full support |
+| Browsers | All modern | Chrome, Firefox, Safari, Edge |
+| Cloudflare Workers | Yes | Web Crypto API available |
+| React Native | Via polyfill | Needs `crypto.subtle` polyfill |
+
+ESM-only. Eight subpath exports for tree-shaking:
+
+```typescript
+import { createSession } from 'canary-kit/session'    // just sessions
+import { deriveToken } from 'canary-kit/token'         // just derivation
+import { encodeAsWords } from 'canary-kit/encoding'    // just encoding
+import { WORDLIST } from 'canary-kit/wordlist'          // just the wordlist
+import { buildGroupEvent } from 'canary-kit/nostr'     // just Nostr
+import { encryptBeacon } from 'canary-kit/beacon'      // just beacons
+import { applySyncMessage } from 'canary-kit/sync'     // just sync protocol
+```
+
+## Security
+
+- **Minimal runtime dependencies** — only `@scure/bip32` and `@scure/bip39` for mnemonic key recovery; core crypto is pure JS
+- **Automated publishing** — GitHub Actions with OIDC trusted publishing, no stored tokens
+- **Provenance signed** — npm provenance attestation enabled
+- **Protocol-grade test vectors** — frozen canonical vectors in both CANARY.md and NIP-CANARY.md; any conformant implementation must produce identical results
+- **Timing-safe byte compare** — `timingSafeEqual()` utility provided for constant-time byte operations
+- **Bounded tolerance** — `MAX_TOLERANCE` cap prevents pathological iteration
+
+See [SECURITY.md](SECURITY.md) for vulnerability disclosure and known limitations. See [CANARY.md](CANARY.md) for the full security analysis.
+
+## API
+
+| Subpath export | Key functions |
+|---|---|
+| `canary-kit/session` | `createSession`, `generateSeed`, `deriveSeed` |
+| `canary-kit/token` | `deriveToken`, `verifyToken`, `deriveDuressToken`, `deriveLivenessToken` |
+| `canary-kit/encoding` | `encodeAsWords`, `encodeAsPin`, `encodeAsHex` |
+| `canary-kit` | `createGroup`, `getCurrentWord`, `verifyWord`, `addMember`, `reseed` |
+| `canary-kit/nostr` | `buildGroupEvent`, `buildBeaconEvent`, + 4 more builders |
+| `canary-kit/beacon` | `encryptBeacon`, `decryptBeacon`, `buildDuressAlert` |
+| `canary-kit/sync` | `applySyncMessage`, `encodeSyncMessage`, `deriveGroupKey` |
+| `canary-kit/wordlist` | `WORDLIST`, `getWord`, `indexOf` |
+
+Full API documentation with signatures, types, and presets: **[API.md](API.md)**
+
+## Protocol
+
+The full protocol specification is in [CANARY.md](CANARY.md). The Nostr binding is in [NIP-CANARY.md](NIP-CANARY.md). The integration guide for finance/enterprise is in [INTEGRATION.md](INTEGRATION.md).
+
+| Event | Kind | Type |
+|---|---|---|
+| Group announcement | `38800` | Replaceable |
+| Seed distribution | `28800` | Ephemeral |
+| Member update | `38801` | Replaceable |
+| Reseed | `28801` | Ephemeral |
+| Word used | `28802` | Ephemeral |
+| Encrypted location beacon | `20800` | Ephemeral |
+
+Content is encrypted with **NIP-44**. Events may carry a **NIP-40** `expiration` tag.
+
+## For AI Assistants
+
+- [llms.txt](llms.txt) — concise API summary
+- [llms-full.txt](llms-full.txt) — complete reference with all type signatures
+
+## Support
+
+For issues and feature requests, see [GitHub Issues](https://github.com/TheCryptoDonkey/canary-kit/issues).
+
+If you find canary-kit useful, consider sending a tip:
+
+- **Lightning:** `thedonkey@strike.me`
+- **Nostr zaps:** `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`
+
+## Licence
+
+MIT

package/SECURITY.md

@@ -0,0 +1,92 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x.x   | Yes       |
+| < 1.0.0 | No        |
+
+## Reporting a Vulnerability
+
+**Please report security vulnerabilities through GitHub Security Advisories only.**
+
+1. Go to [Security Advisories](https://github.com/TheCryptoDonkey/canary-kit/security/advisories)
+2. Click **"New draft security advisory"**
+3. Fill in the details of the vulnerability
+
+**Do not** report security vulnerabilities through public GitHub issues, pull requests, or any other public channel.
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Potential impact
+- Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgement:** Within 72 hours
+- **Initial assessment:** Within 1 week
+- **Fix timeline:** Depends on severity; Critical issues targeted within 2 weeks
+
+### Severity Definitions
+
+| Level | Definition |
+|-------|-----------|
+| Critical | Breaks a core security property (token unpredictability, duress indistinguishability, coercion resistance) |
+| High | Significant weakness exploitable by a defined adversary profile |
+| Medium | Defence-in-depth gap; exploitable under specific conditions |
+| Low | Minor issue; hardening opportunity |
+
+### Scope
+
+The following components are in scope for security reports:
+
+- Protocol specification (`CANARY.md`, `NIP-CANARY.md`)
+- Reference implementation (`src/*.ts`)
+- Cryptographic primitives (`src/crypto.ts`)
+- Sync protocol (`src/sync.ts`, `src/sync-crypto.ts`)
+
+Out of scope: demo application (`app/`), build tooling, CI/CD.
+
+## Security Model
+
+CANARY's security rests on the secrecy of the shared seed and the properties of HMAC-SHA256. The protocol does **not** protect against:
+
+- Compromise of the shared seed (all tokens derivable until reseed)
+- Side-channel attacks inherent to JavaScript runtimes (timing, memory access patterns)
+- An attacker who can observe both parties' tokens in real time
+
+### Known Limitations of JavaScript Cryptography
+
+- **No constant-time guarantees.** JavaScript engines may optimise away constant-time patterns. A `timingSafeEqual()` utility is provided and used for all token comparisons. The CANARY threat model (spoken-word verification over voice calls) makes sub-millisecond timing attacks impractical.
+- **HMAC-SHA256 is synchronous.** The core derivation uses a pure JavaScript SHA-256 implementation rather than Web Crypto API, because derivation must be synchronous (called frequently, deterministic, offline). The implementation follows FIPS 180-4.
+- **AES-256-GCM is async.** Beacon encryption uses `crypto.subtle` (Web Crypto API) and is the only async operation in the library.
+
+### Browser Storage
+
+The demo/alpha browser application stores group seeds and private keys in `localStorage`:
+
+- **Without PIN:** Secrets are stored in plaintext. Any script running on the page origin can read them.
+- **With PIN:** Secrets are encrypted with AES-256-GCM via a PBKDF2-derived key (600,000 iterations, non-extractable `CryptoKey`). Secrets are only readable in memory while the app is unlocked.
+
+**This is NOT suitable for enterprise or high-security deployments.** Production implementations on native platforms MUST use platform secure storage (iOS Keychain, Android Keystore, OS credential manager).
+
+The browser app mitigates this with:
+- A strict `Content-Security-Policy` (`script-src 'self'`) blocking injected scripts
+- Zero third-party runtime dependencies in the production bundle
+- Auto-lock after configurable inactivity period (default: 5 minutes)
+
+### Supply Chain
+
+- **Minimal runtime dependencies.** Only `@scure/bip32` and `@scure/bip39` for mnemonic key recovery; core crypto is pure JS.
+- **Automated publishing.** Releases are built and published via GitHub Actions with OIDC trusted publishing — no npm tokens stored.
+- **Provenance signed.** npm provenance attestation is enabled.
+
+## Security Documents
+
+- [Threat Model](THREAT-MODEL.md) — Adversary profiles, security properties, attack trees
+- [Audit Report](AUDIT.md) — Adversarial security audit with findings register
+- [Protocol Specification](CANARY.md) — Full protocol spec with security analysis

package/dist/beacon.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Encrypted location beacons and duress alerts for canary groups.
+ *
+ * Key derivation: sync (HMAC-SHA256 from crypto.ts)
+ * Encryption:     async (AES-256-GCM via crypto.subtle)
+ *
+ * The sync/async split is intentional:
+ * - Word derivation stays sync (called frequently, deterministic)
+ * - Beacon/duress encryption is async (event-driven, one call per publish)
+ */
+/**
+ * Derive a 256-bit AES key from the group seed for beacon encryption.
+ * Deterministic: same seed always produces the same key.
+ *
+ * @param seedHex - Group seed as a 64-character lowercase hex string (32 bytes).
+ * @returns 32-byte AES-256 key derived via HMAC-SHA256.
+ * @throws {Error} If seedHex is not a valid 64-character hex string.
+ */
+export declare function deriveBeaconKey(seedHex: string): Uint8Array;
+/**
+ * Derive a 256-bit AES key from the group seed for duress alert encryption.
+ * Uses a distinct HMAC info string from beacon keys for domain separation —
+ * prevents cross-type key reuse between normal beacons and duress alerts.
+ *
+ * @param seedHex - Group seed as a 64-character lowercase hex string (32 bytes).
+ * @returns 32-byte AES-256 key derived via HMAC-SHA256 with duress-specific info.
+ * @throws {Error} If seedHex is not a valid 64-character hex string.
+ */
+export declare function deriveDuressKey(seedHex: string): Uint8Array;
+/** Decrypted content of a kind 20800 location beacon event. */
+export interface BeaconPayload {
+    geohash: string;
+    precision: number;
+    timestamp: number;
+}
+/**
+ * Encrypt a location beacon payload with the group's beacon key.
+ * Returns a base64 string suitable for a Nostr event's `content` field.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveBeaconKey}.
+ * @param geohash - Geohash string representing the location.
+ * @param precision - Geohash precision level (1-11).
+ * @returns Base64-encoded ciphertext (12-byte IV prepended to AES-GCM output).
+ * @throws {Error} If key is not 32 bytes.
+ */
+export declare function encryptBeacon(key: Uint8Array, geohash: string, precision: number): Promise<string>;
+/**
+ * Decrypt a location beacon event's content.
+ * Throws if the key is wrong or the ciphertext is tampered with (AES-GCM authentication).
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveBeaconKey}.
+ * @param content - Base64-encoded ciphertext from the beacon event's content field.
+ * @returns Decrypted {@link BeaconPayload} with geohash, precision, and timestamp.
+ * @throws {Error} If decryption fails, ciphertext is tampered, or payload is malformed.
+ */
+export declare function decryptBeacon(key: Uint8Array, content: string): Promise<BeaconPayload>;
+/** Decrypted content of a duress alert beacon (kind 20800, AES-GCM encrypted). */
+export interface DuressAlert {
+    type: 'duress';
+    member: string;
+    geohash: string;
+    precision: number;
+    locationSource: 'beacon' | 'verifier' | 'none';
+    timestamp: number;
+}
+/** Location info for a duress alert. Null means no location available. */
+export interface DuressLocation {
+    geohash: string;
+    precision: number;
+    locationSource: 'beacon' | 'verifier';
+}
+/**
+ * Construct a duress alert payload.
+ *
+ * The caller is responsible for geohash encoding and precision upgrade
+ * (e.g. using geohash-kit to re-encode at precision 11 for duress).
+ * This function just assembles the payload.
+ *
+ * @param memberPubkey - 64-character lowercase hex pubkey of the member under duress.
+ * @param location - Location info with geohash, precision, and source; or null if unavailable.
+ * @returns A {@link DuressAlert} payload ready for encryption.
+ * @throws {Error} If memberPubkey is not a valid 64-character hex string.
+ */
+export declare function buildDuressAlert(memberPubkey: string, location: DuressLocation | null): DuressAlert;
+/**
+ * Encrypt a duress alert with the group's duress key (from deriveDuressKey).
+ * Returns a base64 string for the Nostr event's `content` field.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveDuressKey}.
+ * @param alert - The {@link DuressAlert} payload to encrypt.
+ * @returns Base64-encoded ciphertext (12-byte IV prepended to AES-GCM output).
+ * @throws {Error} If key is not 32 bytes.
+ */
+export declare function encryptDuressAlert(key: Uint8Array, alert: DuressAlert): Promise<string>;
+/**
+ * Decrypt a duress alert event's content.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveDuressKey}.
+ * @param content - Base64-encoded ciphertext from the duress alert event's content field.
+ * @returns Decrypted {@link DuressAlert} payload.
+ * @throws {Error} If decryption fails, ciphertext is tampered, or payload is malformed.
+ */
+export declare function decryptDuressAlert(key: Uint8Array, content: string): Promise<DuressAlert>;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyBH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAG3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAG3D;AA2CD,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,CAaxB;AAMD,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;IAC9C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,QAAQ,GAAG,UAAU,CAAA;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,cAAc,GAAG,IAAI,GAC9B,WAAW,CAsBb;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAqBtB"}

package/dist/beacon.js

@@ -0,0 +1,197 @@
+/**
+ * Encrypted location beacons and duress alerts for canary groups.
+ *
+ * Key derivation: sync (HMAC-SHA256 from crypto.ts)
+ * Encryption:     async (AES-256-GCM via crypto.subtle)
+ *
+ * The sync/async split is intentional:
+ * - Word derivation stays sync (called frequently, deterministic)
+ * - Beacon/duress encryption is async (event-driven, one call per publish)
+ */
+import { hmacSha256, hexToBytes, bytesToBase64, base64ToBytes } from './crypto.js';
+const HEX_64_RE = /^[0-9a-f]{64}$/;
+// ---------------------------------------------------------------------------
+// Key Derivation (sync)
+// ---------------------------------------------------------------------------
+const BEACON_KEY_INFO = new TextEncoder().encode('canary:beacon:key');
+const DURESS_KEY_INFO = new TextEncoder().encode('canary:duress:key');
+function validateSeedHex(seedHex) {
+    if (!HEX_64_RE.test(seedHex)) {
+        throw new Error('seedHex must be a 64-character lowercase hex string (32 bytes)');
+    }
+}
+function validateAesKey(key) {
+    if (key.length !== 32) {
+        throw new Error('AES-256-GCM requires a 32-byte key');
+    }
+}
+/**
+ * Derive a 256-bit AES key from the group seed for beacon encryption.
+ * Deterministic: same seed always produces the same key.
+ *
+ * @param seedHex - Group seed as a 64-character lowercase hex string (32 bytes).
+ * @returns 32-byte AES-256 key derived via HMAC-SHA256.
+ * @throws {Error} If seedHex is not a valid 64-character hex string.
+ */
+export function deriveBeaconKey(seedHex) {
+    validateSeedHex(seedHex);
+    return hmacSha256(hexToBytes(seedHex), BEACON_KEY_INFO);
+}
+/**
+ * Derive a 256-bit AES key from the group seed for duress alert encryption.
+ * Uses a distinct HMAC info string from beacon keys for domain separation —
+ * prevents cross-type key reuse between normal beacons and duress alerts.
+ *
+ * @param seedHex - Group seed as a 64-character lowercase hex string (32 bytes).
+ * @returns 32-byte AES-256 key derived via HMAC-SHA256 with duress-specific info.
+ * @throws {Error} If seedHex is not a valid 64-character hex string.
+ */
+export function deriveDuressKey(seedHex) {
+    validateSeedHex(seedHex);
+    return hmacSha256(hexToBytes(seedHex), DURESS_KEY_INFO);
+}
+// ---------------------------------------------------------------------------
+// AES-256-GCM helpers (async, shared by beacon and duress)
+// ---------------------------------------------------------------------------
+async function aesGcmEncrypt(key, plaintext) {
+    validateAesKey(key);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt']);
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, cryptoKey, plaintext));
+    // Prepend 12-byte IV to ciphertext, then base64
+    const combined = new Uint8Array(12 + ciphertext.length);
+    combined.set(iv);
+    combined.set(ciphertext, 12);
+    return bytesToBase64(combined);
+}
+async function aesGcmDecrypt(key, content) {
+    validateAesKey(key);
+    const combined = base64ToBytes(content);
+    const MIN_CIPHERTEXT_LEN = 28; // 12-byte IV + 16-byte GCM auth tag
+    if (combined.length < MIN_CIPHERTEXT_LEN) {
+        throw new Error('Invalid ciphertext: too short (minimum 28 bytes: 12-byte IV + 16-byte GCM tag)');
+    }
+    const iv = combined.slice(0, 12);
+    const ciphertext = combined.slice(12);
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['decrypt']);
+    return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, cryptoKey, ciphertext));
+}
+/**
+ * Encrypt a location beacon payload with the group's beacon key.
+ * Returns a base64 string suitable for a Nostr event's `content` field.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveBeaconKey}.
+ * @param geohash - Geohash string representing the location.
+ * @param precision - Geohash precision level (1-11).
+ * @returns Base64-encoded ciphertext (12-byte IV prepended to AES-GCM output).
+ * @throws {Error} If key is not 32 bytes.
+ */
+export async function encryptBeacon(key, geohash, precision) {
+    const payload = {
+        geohash,
+        precision,
+        timestamp: Math.floor(Date.now() / 1000),
+    };
+    return aesGcmEncrypt(key, new TextEncoder().encode(JSON.stringify(payload)));
+}
+/**
+ * Decrypt a location beacon event's content.
+ * Throws if the key is wrong or the ciphertext is tampered with (AES-GCM authentication).
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveBeaconKey}.
+ * @param content - Base64-encoded ciphertext from the beacon event's content field.
+ * @returns Decrypted {@link BeaconPayload} with geohash, precision, and timestamp.
+ * @throws {Error} If decryption fails, ciphertext is tampered, or payload is malformed.
+ */
+export async function decryptBeacon(key, content) {
+    const plaintext = await aesGcmDecrypt(key, content);
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        throw new Error('Invalid beacon payload: decrypted content is not valid JSON');
+    }
+    const obj = parsed;
+    if (typeof obj.geohash !== 'string' || typeof obj.precision !== 'number' || typeof obj.timestamp !== 'number') {
+        throw new Error('Invalid beacon payload: missing or malformed required fields');
+    }
+    return parsed;
+}
+/**
+ * Construct a duress alert payload.
+ *
+ * The caller is responsible for geohash encoding and precision upgrade
+ * (e.g. using geohash-kit to re-encode at precision 11 for duress).
+ * This function just assembles the payload.
+ *
+ * @param memberPubkey - 64-character lowercase hex pubkey of the member under duress.
+ * @param location - Location info with geohash, precision, and source; or null if unavailable.
+ * @returns A {@link DuressAlert} payload ready for encryption.
+ * @throws {Error} If memberPubkey is not a valid 64-character hex string.
+ */
+export function buildDuressAlert(memberPubkey, location) {
+    if (!HEX_64_RE.test(memberPubkey)) {
+        throw new Error(`Invalid member pubkey: expected 64 lowercase hex characters, got ${memberPubkey.length} chars`);
+    }
+    if (location) {
+        return {
+            type: 'duress',
+            member: memberPubkey,
+            geohash: location.geohash,
+            precision: location.precision,
+            locationSource: location.locationSource,
+            timestamp: Math.floor(Date.now() / 1000),
+        };
+    }
+    return {
+        type: 'duress',
+        member: memberPubkey,
+        geohash: '',
+        precision: 0,
+        locationSource: 'none',
+        timestamp: Math.floor(Date.now() / 1000),
+    };
+}
+/**
+ * Encrypt a duress alert with the group's duress key (from deriveDuressKey).
+ * Returns a base64 string for the Nostr event's `content` field.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveDuressKey}.
+ * @param alert - The {@link DuressAlert} payload to encrypt.
+ * @returns Base64-encoded ciphertext (12-byte IV prepended to AES-GCM output).
+ * @throws {Error} If key is not 32 bytes.
+ */
+export async function encryptDuressAlert(key, alert) {
+    return aesGcmEncrypt(key, new TextEncoder().encode(JSON.stringify(alert)));
+}
+/**
+ * Decrypt a duress alert event's content.
+ *
+ * @param key - 32-byte AES-256 key from {@link deriveDuressKey}.
+ * @param content - Base64-encoded ciphertext from the duress alert event's content field.
+ * @returns Decrypted {@link DuressAlert} payload.
+ * @throws {Error} If decryption fails, ciphertext is tampered, or payload is malformed.
+ */
+export async function decryptDuressAlert(key, content) {
+    const plaintext = await aesGcmDecrypt(key, content);
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        throw new Error('Invalid duress alert payload: decrypted content is not valid JSON');
+    }
+    const obj = parsed;
+    const VALID_SOURCES = new Set(['beacon', 'verifier', 'none']);
+    if (obj.type !== 'duress' ||
+        typeof obj.member !== 'string' ||
+        typeof obj.timestamp !== 'number' ||
+        typeof obj.geohash !== 'string' ||
+        typeof obj.precision !== 'number' ||
+        !VALID_SOURCES.has(obj.locationSource)) {
+        throw new Error('Invalid duress alert payload: missing or malformed required fields');
+    }
+    return parsed;
+}
+//# sourceMappingURL=beacon.js.map

package/dist/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"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"}

package/dist/counter.d.ts

@@ -0,0 +1,37 @@
+/** Default rotation interval: 7 days in seconds. */
+export declare const DEFAULT_ROTATION_INTERVAL = 604800;
+/**
+ * Maximum allowed usage offset above the current time-based counter.
+ * Implementations MUST reject counter updates where effective counter > time-based counter + MAX_COUNTER_OFFSET.
+ * See CANARY spec §Counter Acceptance.
+ */
+export declare const MAX_COUNTER_OFFSET = 100;
+/**
+ * Derive the current counter from a unix timestamp and rotation interval.
+ * Counter = floor(timestamp / interval).
+ *
+ * @param timestampSec - Unix timestamp in seconds (non-negative finite number).
+ * @param rotationIntervalSec - Rotation interval in seconds (positive finite number, default: 604800 = 7 days).
+ * @returns Integer counter value within uint32 range.
+ * @throws {RangeError} If timestampSec is negative/non-finite, rotationIntervalSec is non-positive/non-finite, or counter exceeds uint32.
+ */
+export declare function getCounter(timestampSec: number, rotationIntervalSec?: number): number;
+/**
+ * Derive a counter from an event identifier (e.g. a task ID or Nostr event ID).
+ * Uses SHA-256 truncated to 32 bits for a deterministic, uniformly distributed counter.
+ * Per CANARY spec §Counter Schemes: event-based counters are deterministic from event ID.
+ *
+ * @param eventId - String identifier to derive the counter from (e.g. a Nostr event ID).
+ * @returns Unsigned 32-bit integer derived from SHA-256 of the event ID.
+ */
+export declare function counterFromEventId(eventId: string): number;
+/**
+ * Serialise a counter to an 8-byte big-endian Uint8Array.
+ * Same encoding as TOTP (RFC 6238).
+ *
+ * @param counter - Non-negative safe integer to serialise.
+ * @returns 8-byte big-endian Uint8Array representation of the counter.
+ * @throws {RangeError} If counter is negative, not an integer, or exceeds Number.MAX_SAFE_INTEGER.
+ */
+export declare function counterToBytes(counter: number): Uint8Array;
+//# sourceMappingURL=counter.d.ts.map

package/dist/counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../src/counter.ts"],"names":[],"mappings":"AAEA,oDAAoD;AACpD,eAAO,MAAM,yBAAyB,SAAU,CAAA;AAEhD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,EACpB,mBAAmB,GAAE,MAAkC,GACtD,MAAM,CAYR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAQ1D"}