canary-kit 2.7.0 → 2.7.1

package/COOKBOOK.md

@@ -0,0 +1,763 @@
+# Cookbook -- canary-kit
+
+> Complete workflow examples for common integration patterns. For API reference, see [API.md](API.md). For protocol specs, see [CANARY.md](CANARY.md).
+
+## Duress Detection: Detecting and Handling Coercion
+
+Canary-kit's coercion resistance works by giving each member a personal duress word that is always distinct from the normal verification word. When a coerced member speaks their duress word instead of the normal word, the verifier silently detects the coercion without the coercer knowing.
+
+### Session-Based Duress Detection (Phone Calls)
+
+```typescript
+import { createSession } from 'canary-kit/session'
+
+// Both parties share a secret (established during onboarding)
+const session = createSession({
+  secret: sharedSecretHex,
+  namespace: 'acme-insurance',
+  roles: ['agent', 'customer'],
+  myRole: 'agent',
+  preset: 'call',
+  // CRITICAL: theirIdentity enables duress detection.
+  // Without it, duress tokens return 'invalid' instead of 'duress'.
+  theirIdentity: customerId,
+})
+
+// Agent speaks their token to prove identity to the customer
+const agentSaysToCustomer = session.myToken()
+
+// Customer speaks back -- agent verifies
+const spokenByCustomer = 'granite' // what the agent heard
+const result = session.verify(spokenByCustomer)
+
+switch (result.status) {
+  case 'valid':
+    // Normal verification -- proceed with the call
+    console.log('Customer verified successfully')
+    break
+
+  case 'duress':
+    // SILENT ALERT: customer is under coercion.
+    // result.identities contains the identity strings of coerced parties.
+    // DO NOT reveal this to the caller -- the coercer may be listening.
+    console.log('Duress detected for:', result.identities)
+    // Trigger silent alert workflow:
+    // 1. Continue the call as if verification succeeded
+    // 2. Flag the interaction in your backend
+    // 3. Notify security/compliance team via back-channel
+    // 4. Follow your organisation's duress response protocol
+    await triggerSilentDuressAlert(result.identities, session)
+    break
+
+  case 'invalid':
+    // Word does not match -- could be wrong word, expired token, or attacker
+    console.log('Verification failed')
+    // Ask the customer to repeat, or escalate
+    break
+}
+```
+
+### Group-Based Duress Detection
+
+```typescript
+import {
+  createGroup, getCurrentWord, getCurrentDuressWord,
+  verifyWord, getCounter,
+} from 'canary-kit'
+
+const group = createGroup({
+  name: 'Family Safety',
+  members: [alicePubkey, bobPubkey, carolPubkey],
+  preset: 'family',
+  creator: alicePubkey,
+})
+
+// The normal verification word is shared by all members
+const normalWord = getCurrentWord(group) // e.g. "falcon"
+
+// Each member has a unique duress word
+const aliceDuress = getCurrentDuressWord(group, alicePubkey) // e.g. "marble"
+const bobDuress = getCurrentDuressWord(group, bobPubkey)     // e.g. "timber"
+
+// Verify a word spoken by any group member
+const counter = getCounter(Math.floor(Date.now() / 1000), group.rotationInterval)
+const result = verifyWord(spokenWord, group.seed, group.members, counter, group.wordCount)
+
+switch (result.status) {
+  case 'verified':
+    console.log('Identity confirmed')
+    break
+
+  case 'duress':
+    // result.members contains the pubkeys of the coerced member(s)
+    console.log('DURESS: coerced members:', result.members)
+    // The specific member's duress word matched -- you know WHO is under duress
+    break
+
+  case 'stale':
+    // Word matches a previous time window -- likely clock skew or late call
+    console.log('Stale token -- ask them to repeat')
+    break
+
+  case 'failed':
+    console.log('Verification failed -- word does not match')
+    break
+}
+```
+
+### Key Design Points
+
+- **Duress words are always distinct from verification words.** The library enforces collision avoidance with suffix retry. A duress word can never accidentally equal the normal word.
+- **Duress detection requires identity context.** For sessions, pass `theirIdentity`. For groups, pass all `members` to `verifyWord`. Without identities, duress cannot be detected.
+- **Duress wins over valid.** If a word matches both (impossible by design, but as a safety property), duress takes priority.
+- **Silent by design.** The coercer hears a normal-sounding word. The verifier sees `duress` status. Nothing in the protocol reveals that duress was detected.
+
+---
+
+## Replacing SMS OTP with Spoken-Word Verification
+
+SMS OTP is vulnerable to SIM-swap, SS7 interception, and social engineering. Canary-kit replaces it with time-rotating spoken words derived from a shared secret, meeting FCA Strong Customer Authentication (SCA) requirements: possession (the shared secret on the device) + inherence (the human speaking the word).
+
+### Step-by-Step Migration
+
+```typescript
+import { createSession, deriveSeed } from 'canary-kit/session'
+
+// ── Step 1: Onboarding (replaces "register phone number") ─────────────────
+
+// During account creation or migration, derive a per-customer seed
+// from your platform's master key + customer ID.
+const customerSeed = deriveSeed(platformMasterKey, 'customer', customerId)
+// Store customerSeed securely server-side. Provision to customer's app via
+// secure channel (QR code in branch, NFC tap, or authenticated app download).
+
+// ── Step 2: Authentication (replaces "send SMS OTP") ──────────────────────
+
+// Server creates a session for this authentication attempt
+const serverSession = createSession({
+  secret: customerSeed,
+  namespace: 'mybank',
+  roles: ['server', 'customer'],
+  myRole: 'server',
+  preset: 'call',          // 30-second rotation, +-1 tolerance
+  theirIdentity: customerId, // enables duress detection
+})
+
+// Server displays or reads: "Please say the word: {serverSession.myToken()}"
+// Customer's app shows: serverSession.theirToken() from their local session
+// Customer speaks the word shown in their app
+
+// ── Step 3: Verification (replaces "check OTP code") ──────────────────────
+
+const result = serverSession.verify(spokenWord)
+
+if (result.status === 'valid') {
+  // Authentication successful
+  grantAccess(customerId)
+} else if (result.status === 'duress') {
+  // Customer is under coercion -- grant apparent access but trigger silent alert
+  grantApparentAccess(customerId)
+  await alertSecurityTeam(customerId, result.identities)
+} else {
+  // Authentication failed
+  denyAccess(customerId)
+}
+```
+
+### Why This Works as an OTP Replacement
+
+- **No phone number dependency.** SIM-swap and SS7 interception do not apply.
+- **Works offline.** Tokens derived locally from shared secret + time. No network needed at verification time.
+- **Bidirectional.** Both parties prove identity, not just the user to the server.
+- **Duress detection.** Coerced users can signal silently -- impossible with SMS OTP.
+
+For regulatory compliance mapping (FCA SCA, EU AI Act, UAE, RBI), see [INTEGRATION.md](INTEGRATION.md).
+
+---
+
+## Group Verification: Multi-Member Verification Workflows
+
+### Basic Group Verification
+
+```typescript
+import {
+  createGroup, getCurrentWord, getCurrentDuressWord,
+  verifyWord, getCounter, advanceCounter,
+} from 'canary-kit'
+
+// Create a group with an admin who can manage membership
+const group = createGroup({
+  name: 'Field Team Alpha',
+  members: [leaderPubkey, agent1Pubkey, agent2Pubkey, agent3Pubkey],
+  preset: 'field-ops',  // 2-word phrases, 24-hour rotation
+  creator: leaderPubkey, // leader is admin
+})
+
+// All members derive the same verification phrase
+const phrase = getCurrentWord(group) // e.g. "falcon granite"
+
+// Any member can verify any other member's spoken phrase
+const counter = getCounter(Math.floor(Date.now() / 1000), group.rotationInterval)
+const result = verifyWord(
+  spokenPhrase,
+  group.seed,
+  group.members,
+  counter,
+  group.wordCount,
+)
+
+// After using the word (e.g. for a check-in), burn it to prevent replay
+const updated = advanceCounter(group)
+// The next getCurrentWord(updated) returns a different phrase
+```
+
+### M-of-N Threshold Verification
+
+Canary-kit groups use a shared secret, so all members derive the same verification word. M-of-N threshold checks are implemented at the application layer by collecting individual verifications:
+
+```typescript
+import {
+  createGroup, getCurrentWord, verifyWord, getCounter,
+} from 'canary-kit'
+
+interface MemberVerification {
+  pubkey: string
+  spokenWord: string
+  timestamp: number
+}
+
+/**
+ * Verify M-of-N group members have provided correct tokens.
+ * Each member must independently speak the current word.
+ * Returns verified/duress member lists for threshold decisions.
+ */
+function verifyThreshold(
+  group: GroupState,
+  verifications: MemberVerification[],
+  requiredCount: number,
+): { verified: string[]; duress: string[]; failed: string[]; met: boolean } {
+  const counter = getCounter(Math.floor(Date.now() / 1000), group.rotationInterval)
+  const verified: string[] = []
+  const duress: string[] = []
+  const failed: string[] = []
+
+  for (const v of verifications) {
+    // Each verification is checked independently
+    const result = verifyWord(v.spokenWord, group.seed, group.members, counter, group.wordCount)
+
+    switch (result.status) {
+      case 'verified':
+        verified.push(v.pubkey)
+        break
+      case 'duress':
+        // Even in M-of-N, duress is flagged silently
+        duress.push(v.pubkey)
+        break
+      case 'stale':
+      case 'failed':
+        failed.push(v.pubkey)
+        break
+    }
+  }
+
+  return {
+    verified,
+    duress,
+    failed,
+    // Threshold met only when enough members verify AND no duress detected
+    met: verified.length >= requiredCount && duress.length === 0,
+  }
+}
+
+// Usage: require 2-of-3 members to verify before authorising an action
+const result = verifyThreshold(group, collectedVerifications, 2)
+
+if (result.duress.length > 0) {
+  // At least one member signalled duress -- abort and alert
+  await triggerGroupDuressProtocol(result.duress)
+} else if (result.met) {
+  // Threshold met -- proceed
+  authoriseAction()
+} else {
+  // Not enough verified members
+  requestMoreVerifications(result.failed)
+}
+```
+
+### Group Membership Management with Sync
+
+```typescript
+import {
+  createGroup, addMember, removeMember, advanceCounter,
+} from 'canary-kit'
+import {
+  applySyncMessage, encodeSyncMessage, decodeSyncMessage,
+  deriveGroupKey, encryptEnvelope, decryptEnvelope,
+  type SyncMessage,
+} from 'canary-kit/sync'
+
+// ── Adding a member (admin-only) ──────────────────────────────────────────
+
+const joinMsg: SyncMessage = {
+  type: 'member-join',
+  pubkey: newMemberPubkey,
+  displayName: 'Carol',
+  timestamp: Math.floor(Date.now() / 1000),
+  epoch: group.epoch,
+  opId: crypto.randomUUID(),
+  protocolVersion: 2,
+}
+
+// Encrypt for transport (AES-256-GCM with group key)
+const groupKey = deriveGroupKey(group.seed)
+const encrypted = await encryptEnvelope(groupKey, encodeSyncMessage(joinMsg))
+
+// On the receiving side: decrypt and apply
+const decrypted = await decryptEnvelope(groupKey, encrypted)
+const decoded = decodeSyncMessage(decrypted)
+const nowSec = Math.floor(Date.now() / 1000)
+
+// applySyncMessage returns a new GroupState (unchanged if rejected)
+const newState = applySyncMessage(group, decoded, nowSec, adminPubkey)
+
+// Check if it was applied by comparing references
+if (newState !== group) {
+  console.log('Member added:', newMemberPubkey)
+  console.log('Members:', newState.members)
+} else {
+  console.log('Message rejected (not admin, wrong epoch, or replay)')
+}
+```
+
+---
+
+## Family Safety Application
+
+### Setting Up a Family Verification Group
+
+```typescript
+import {
+  createGroup, getCurrentWord, getCurrentDuressWord,
+  verifyWord, getCounter,
+} from 'canary-kit'
+import { deriveSeed } from 'canary-kit/session'
+
+// ── Master Key Management ─────────────────────────────────────────────────
+// The master key should be stored in the device's secure enclave/keychain.
+// On iOS: Keychain Services. On Android: Android Keystore.
+// On web: IndexedDB with non-extractable CryptoKey (WebCrypto API).
+//
+// NEVER store the master key in localStorage, plain files, or app preferences.
+// If the master key is compromised, all derived group seeds are compromised.
+
+// Option A: Generate a fresh master key during family setup
+import { generateSeed } from 'canary-kit/session'
+const masterKey = generateSeed()  // 32 random bytes
+
+// Option B: Derive from a mnemonic (BIP-39) for recovery
+// import { mnemonicToSeedSync } from '@scure/bip39'
+// const masterKey = mnemonicToSeedSync(mnemonic).slice(0, 32)
+
+// ── Create Family Group ───────────────────────────────────────────────────
+const family = createGroup({
+  name: 'Smith Family',
+  members: [mumPubkey, dadPubkey, teenPubkey, granPubkey],
+  preset: 'family',     // 1 word, 7-day rotation
+  creator: mumPubkey,   // mum is admin (can add/remove members)
+})
+
+// ── Weekly Family Verification ────────────────────────────────────────────
+// Each week, the word rotates automatically. Family members can verify
+// each other during phone calls or video calls.
+const currentWord = getCurrentWord(family) // e.g. "falcon"
+
+// ── Elderly Parent Protection ─────────────────────────────────────────────
+// Scenario: gran receives a call from someone claiming to be her grandchild.
+// Instead of relying on voice recognition (defeated by AI cloning), she asks
+// for the family word.
+//
+// Legitimate grandchild knows the word (their app shows it).
+// Voice-cloning scammer does NOT know the word (they don't have the seed).
+
+// Gran verifies the word spoken to her:
+const counter = getCounter(Math.floor(Date.now() / 1000), family.rotationInterval)
+const result = verifyWord(spokenWord, family.seed, family.members, counter, family.wordCount)
+
+if (result.status === 'verified') {
+  // Caller knows the family word -- identity confirmed
+  console.log('This is really a family member')
+} else if (result.status === 'duress') {
+  // Family member is being coerced -- the correct response depends on context:
+  // - Notify other family members via the app
+  // - Contact authorities
+  // - Do NOT confront the coercer
+  console.log('Family member under duress:', result.members)
+} else {
+  // Caller does not know the word -- likely a scam
+  console.log('Scam call detected -- hang up')
+}
+```
+
+### Error Handling for Family Apps
+
+```typescript
+import { createGroup, syncCounter, type GroupState } from 'canary-kit'
+
+// ── Loading persisted state ───────────────────────────────────────────────
+// After app restart or device reboot, refresh the time-based counter.
+// syncCounter enforces monotonicity -- the counter never goes backwards,
+// even if the device clock was rolled back.
+
+function loadGroupState(persisted: GroupState): GroupState {
+  // Refresh counter to current time window
+  const refreshed = syncCounter(persisted)
+
+  // Validate the loaded state
+  if (refreshed.members.length === 0) {
+    throw new Error('Group has no members -- may have been dissolved')
+  }
+  if (refreshed.seed === '0'.repeat(64)) {
+    throw new Error('Group seed is zeroed -- group was dissolved')
+  }
+
+  return refreshed
+}
+
+// ── Handling network delays ───────────────────────────────────────────────
+// Family members may be in different time zones or have clock drift.
+// The tolerance window (default: 1 for family preset) accepts tokens
+// from adjacent time windows: current, previous, and next.
+//
+// For families spread across time zones, consider increasing tolerance:
+const family = createGroup({
+  name: 'Global Family',
+  members: [londonPubkey, sydneyPubkey, nyPubkey],
+  preset: 'family',
+  tolerance: 2,       // Accept tokens from +-2 windows (wider margin)
+  creator: londonPubkey,
+})
+```
+
+---
+
+## Multi-Channel Verification Architecture
+
+Canary-kit is transport-agnostic. The same shared secret can derive verification tokens across phone calls, video calls, messaging apps, and in-person encounters. This section covers how to maintain verification integrity across multiple channels.
+
+### Architecture Overview
+
+```
+                    +------------------+
+                    |  Shared Secret   |
+                    |  (per pair or    |
+                    |   per group)     |
+                    +--------+---------+
+                             |
+              +--------------+--------------+
+              |              |              |
+        +-----+-----+ +-----+-----+ +-----+-----+
+        |   Phone   | |   Video   | |   In-App   |
+        |   Call    | |   Call    | |  Message   |
+        +-----+-----+ +-----+-----+ +-----+-----+
+              |              |              |
+        session:call   session:call   group:verify
+        30s rotation   30s rotation   7d rotation
+```
+
+### Same Secret, Different Channels
+
+```typescript
+import { createSession, deriveSeed } from 'canary-kit/session'
+
+// Derive channel-specific sessions from the same master secret.
+// Each channel gets its own namespace, producing different tokens.
+// This prevents a token captured on one channel from being replayed
+// on another channel (cross-channel replay prevention).
+
+const masterSecret = deriveSeed(platformKey, 'customer', customerId)
+
+// Phone call session
+const phoneSession = createSession({
+  secret: masterSecret,
+  namespace: 'acme/phone',  // unique namespace per channel
+  roles: ['agent', 'customer'],
+  myRole: 'agent',
+  preset: 'call',
+  theirIdentity: customerId,
+})
+
+// Video call session (different tokens due to different namespace)
+const videoSession = createSession({
+  secret: masterSecret,
+  namespace: 'acme/video',
+  roles: ['agent', 'customer'],
+  myRole: 'agent',
+  preset: 'call',
+  theirIdentity: customerId,
+})
+
+// The phone token and video token are DIFFERENT at the same instant,
+// even though they derive from the same master secret.
+// This prevents cross-channel replay attacks.
+console.log(phoneSession.myToken()) // e.g. "falcon"
+console.log(videoSession.myToken()) // e.g. "marble" (different)
+```
+
+### Replay Prevention Mechanisms
+
+Canary-kit prevents replay attacks through multiple layers:
+
+1. **Time-based rotation.** Tokens rotate every 30 seconds (for `call` preset). A captured token expires within the tolerance window.
+
+2. **Namespace isolation.** Each channel uses a different namespace, producing different tokens. A token from the phone channel is invalid on the video channel.
+
+3. **Burn-after-use (groups).** `advanceCounter()` immediately rotates the token after use, preventing replay within the same time window.
+
+4. **Epoch-based replay protection (sync).** Every state-mutating sync message carries an `opId` tracked in `consumedOps`. Replayed messages are silently dropped. The `epoch` field ensures messages from old group states (before a reseed) are rejected.
+
+5. **Freshness gates (fire-and-forget).** Beacon and liveness messages are dropped if older than 5 minutes (`FIRE_AND_FORGET_FRESHNESS_SEC`) or more than 60 seconds in the future (`MAX_FUTURE_SKEW_SEC`).
+
+```typescript
+import { advanceCounter } from 'canary-kit'
+
+// After verifying a group member's word, burn it immediately
+let group = loadGroupState()
+const result = verifyWord(spoken, group.seed, group.members, counter, group.wordCount)
+if (result.status === 'verified') {
+  // Advance the counter so this word cannot be replayed
+  group = advanceCounter(group)
+  persistGroupState(group)
+}
+```
+
+---
+
+## Distributed Sync Architecture
+
+Canary-kit's sync protocol is designed for distributed environments where multiple devices hold copies of group state and must converge without a central server. This section covers the architectural considerations for deploying sync across multiple nodes.
+
+### Consistency Model: Convergent State via Operation Ordering
+
+Canary-kit uses an **operation-based consistency model** where the sync protocol guarantees convergence through invariant enforcement rather than consensus:
+
+- **No central coordinator.** Any node can generate and broadcast sync messages. There is no leader election or distributed lock.
+- **Idempotent operations.** Every sync message carries an `opId`. The `consumedOps` set ensures that applying the same message twice is a no-op (Invariant I2).
+- **Monotonic counters.** Counter-advance messages enforce `incomingEffective > currentEffective`, so out-of-order delivery of counter advances converges to the highest value.
+- **Epoch boundaries.** Reseeds atomically replace `{seed, members, admins, epoch}` and clear `consumedOps`. Messages from old epochs are rejected (Invariant I6). This provides a clean cut-over point.
+
+```typescript
+import {
+  applySyncMessage, decodeSyncMessage,
+  deriveGroupKey, decryptEnvelope,
+  type SyncMessage,
+} from 'canary-kit/sync'
+import type { GroupState } from 'canary-kit'
+
+/**
+ * Process an incoming sync message on any node.
+ * The invariants ensure convergence regardless of message ordering.
+ */
+async function processIncomingSyncMessage(
+  currentState: GroupState,
+  encryptedPayload: string,
+  senderPubkey: string,
+): Promise<GroupState> {
+  const groupKey = deriveGroupKey(currentState.seed)
+
+  // Decrypt the envelope (AES-256-GCM, keyed to current seed)
+  // Fails if the message was encrypted with an old seed (post-reseed)
+  let plaintext: string
+  try {
+    plaintext = await decryptEnvelope(groupKey, encryptedPayload)
+  } catch {
+    // Decryption failure: message from a different epoch or corrupted
+    // This is expected during reseed transitions -- not an error
+    return currentState
+  }
+
+  // Parse and validate the message structure
+  let msg: SyncMessage
+  try {
+    msg = decodeSyncMessage(plaintext)
+  } catch (err) {
+    // Invalid message: wrong protocol version, missing fields, etc.
+    // Log for debugging but do not apply
+    console.warn('Invalid sync message:', (err as Error).message)
+    return currentState
+  }
+
+  // Apply with full invariant checking
+  const nowSec = Math.floor(Date.now() / 1000)
+  const newState = applySyncMessage(currentState, msg, nowSec, senderPubkey)
+
+  // applySyncMessage returns the same reference if rejected
+  if (newState === currentState) {
+    // Message was rejected by an invariant (stale epoch, replay, etc.)
+    // This is normal in distributed systems -- not an error
+    return currentState
+  }
+
+  // Persist the updated state
+  await persistState(newState)
+  return newState
+}
+```
+
+### Message Ordering and Conflict Resolution
+
+**Out-of-order delivery is handled by the invariants, not by the application.** You do not need to implement message ordering, vector clocks, or CRDTs. The sync protocol handles it:
+
+| Scenario | How it converges |
+|---|---|
+| Two `counter-advance` messages arrive out of order | Monotonic check: only the higher effective counter wins. Both orderings produce the same final state. |
+| `member-join` arrives after `reseed` | Epoch check (I3/I6): the join is rejected because its epoch doesn't match. The admin must re-issue the join in the new epoch. |
+| Two nodes send `counter-advance` simultaneously | Both are applied if they advance the counter. The higher value wins on both nodes (monotonic). |
+| `member-leave` replayed after re-join | `opId` replay guard (I2): the duplicate `opId` is in `consumedOps` and is silently dropped. |
+| Network partition heals with diverged state | Nodes exchange their pending messages. Invariants ensure only valid, non-replayed messages are applied. Counter advances converge to the max. |
+
+### Preserving Deepfake-Proof Guarantees in Distributed Deployments
+
+The deepfake-proof property depends on the shared secret remaining secret. In a distributed environment:
+
+1. **Envelope encryption.** All sync messages travel inside AES-256-GCM envelopes derived from the group seed (`deriveGroupKey(seed)`). Only nodes that possess the current seed can decrypt messages.
+
+2. **Reseed isolates epochs.** When a member is removed or a compromise is suspected, `reseed` generates a new seed and bumps the epoch. Old nodes (or attackers with the old seed) cannot decrypt messages in the new epoch. The key derivation changes completely.
+
+3. **No seed in transit (except during provisioning).** Normal sync messages (counter-advance, beacon, member-join) do not contain the seed. The seed is only transmitted during initial group creation (via NIP-17 gift wrap or QR code) and during reseed (encrypted within the new epoch's envelope).
+
+4. **Offline-first derivation.** Each node derives tokens locally from its copy of the seed and the current counter. No network request is needed to verify a spoken word. This means a compromised relay or transport layer cannot inject false tokens.
+
+```typescript
+import {
+  applySyncMessage, encodeSyncMessage,
+  deriveGroupKey, encryptEnvelope,
+  type SyncMessage,
+} from 'canary-kit/sync'
+import { removeMember, type GroupState } from 'canary-kit'
+
+/**
+ * Handle suspected compromise: remove the compromised member and reseed.
+ * This atomically invalidates the old seed across all nodes.
+ */
+function handleCompromise(
+  group: GroupState,
+  compromisedPubkey: string,
+  adminPubkey: string,
+): { newState: GroupState; reseedMessage: SyncMessage } {
+  // Build the reseed message with the compromised member removed
+  const remainingMembers = group.members.filter(m => m !== compromisedPubkey)
+  const remainingAdmins = group.admins.filter(a => a !== compromisedPubkey)
+
+  // Generate a new seed (32 random bytes, hex-encoded)
+  const newSeed = crypto.getRandomValues(new Uint8Array(32))
+
+  const reseedMsg: SyncMessage = {
+    type: 'reseed',
+    seed: newSeed,
+    counter: group.counter,
+    timestamp: Math.floor(Date.now() / 1000),
+    epoch: group.epoch + 1,  // I4: reseed epoch = local epoch + 1
+    opId: crypto.randomUUID(),
+    admins: remainingAdmins,
+    members: remainingMembers,
+    protocolVersion: 2,
+  }
+
+  // Apply locally first
+  const nowSec = Math.floor(Date.now() / 1000)
+  const newState = applySyncMessage(group, reseedMsg, nowSec, adminPubkey)
+
+  return { newState, reseedMessage: reseedMsg }
+}
+```
+
+### Transport Layer Integration
+
+The sync protocol is transport-agnostic. Implement the `SyncTransport` interface to plug in any delivery mechanism:
+
+```typescript
+import type { SyncTransport, SyncMessage } from 'canary-kit/sync'
+
+// Example: Nostr relay transport
+class NostrSyncTransport implements SyncTransport {
+  async send(groupId: string, message: SyncMessage, recipients?: string[]): Promise<void> {
+    // 1. Encode the message
+    // 2. Encrypt with group key (AES-256-GCM)
+    // 3. Publish as a Nostr event (kind 30078 for stored, kind 20078 for ephemeral)
+  }
+
+  subscribe(groupId: string, onMessage: (msg: SyncMessage, sender: string) => void): () => void {
+    // 1. Subscribe to Nostr events for this group's hash tag
+    // 2. Decrypt incoming events
+    // 3. Decode and call onMessage
+    // Return unsubscribe function
+    return () => { /* cleanup */ }
+  }
+
+  disconnect(): void {
+    // Close relay connections
+  }
+}
+
+// Example: WebSocket transport (for custom infrastructure)
+class WebSocketSyncTransport implements SyncTransport {
+  // Same interface, different transport
+  // Messages still use the same envelope encryption
+}
+
+// Example: Signal/SMS transport (for bootstrapping)
+class ManualSyncTransport implements SyncTransport {
+  // For manual seed distribution via QR code or secure messaging
+  // Only used for initial group setup, not ongoing sync
+}
+```
+
+### Node Recovery After Extended Offline Period
+
+When a node comes back online after missing multiple sync messages:
+
+```typescript
+import { syncCounter, type GroupState } from 'canary-kit'
+import { applySyncMessage, decodeSyncMessage } from 'canary-kit/sync'
+
+/**
+ * Recover state after being offline. Fetch and apply all missed messages.
+ * The invariants handle out-of-order application automatically.
+ */
+async function recoverAfterOffline(
+  persistedState: GroupState,
+  missedMessages: Array<{ payload: string; sender: string }>,
+): Promise<GroupState> {
+  // 1. Refresh the time-based counter (monotonic -- never regresses)
+  let state = syncCounter(persistedState)
+
+  // 2. Apply each missed message in order
+  // Even if order is wrong, invariants ensure correctness
+  const nowSec = Math.floor(Date.now() / 1000)
+  for (const { payload, sender } of missedMessages) {
+    try {
+      const msg = decodeSyncMessage(payload)
+      state = applySyncMessage(state, msg, nowSec, sender)
+    } catch {
+      // Skip invalid messages (wrong protocol version, etc.)
+      continue
+    }
+  }
+
+  // 3. If the node missed a reseed, it cannot decrypt new-epoch messages.
+  // The node must be re-invited by an admin (state-snapshot or new group invite).
+  // This is by design: ensures forward secrecy after member removal.
+
+  return state
+}
+```
+
+### Deployment Checklist
+
+- [ ] **Persist state after every successful `applySyncMessage`.** The in-memory state must match what's on disk to survive crashes.
+- [ ] **Use `applySyncMessageWithResult()` for observability.** Unlike `applySyncMessage` which silently returns unchanged state on rejection, `applySyncMessageWithResult` returns `{ state, applied }` so you can log rejected messages.
+- [ ] **Handle decryption failures gracefully.** After a reseed, old-epoch messages will fail to decrypt. This is expected, not an error.
+- [ ] **Set `creator` in `createGroup()`.** Without a creator, `admins` is empty and all privileged sync operations (member-join, reseed, member-leave of others) are silently rejected.
+- [ ] **Always pass `sender` to `applySyncMessage`.** Privileged actions require a sender. Counter-advance requires sender to be a current group member. Omitting sender causes silent rejection.
+- [ ] **Bound your message store.** `consumedOps` is capped at 1000 entries per epoch. For high-throughput groups, ensure your transport delivers within the eviction window.
+- [ ] **Monitor clock drift.** Messages with timestamps more than 60 seconds in the future are rejected (`MAX_FUTURE_SKEW_SEC`). Fire-and-forget messages older than 5 minutes are dropped (`FIRE_AND_FORGET_FRESHNESS_SEC`).