canary-kit 2.7.0 → 2.7.2

package/INTEGRATION.md

@@ -367,19 +367,122 @@ authorisation:
 
 CANARY tokens rotate on a time-based counter (P4: Replay Resistance). For
 transaction-specific dynamic linking (required by FCA for remote electronic
-payments), construct the session namespace or counter from transaction parameters:
+payments), construct the session namespace or counter from transaction parameters.
+
+#### Full FCA SCA implementation
+
+```typescript
+import { createSession, deriveSeed, generateSeed } from 'canary-kit/session'
+```
+
+**Step 1: Server-side seed derivation (backend, runs once per customer)**
 
 ```typescript
+// The master key lives in an HSM — never in application code
+// deriveSeed uses HMAC-SHA256 with null-byte-separated components
+const customerSeed = deriveSeed(
+  hsmMasterKey,           // Uint8Array from HSM (min 16 bytes)
+  customerId,             // e.g. 'CUST-2026-00491'
+  seedVersion.toString(), // increment to rotate without re-enrolment
+)
+// Deliver customerSeed to the customer's app over TLS during login
+// Store in iOS Keychain / Android KeyStore (possession factor)
+```
+
+**Step 2: Standard call verification (agent side)**
+
+```typescript
+// Agent's desktop app — seed was derived from the same master_key + customer_id
 const session = createSession({
-  secret: seed,
-  namespace: `aviva:payment:${payeeId}:${amountPence}`,
+  secret: customerSeed,
+  namespace: 'aviva',
+  roles: ['caller', 'agent'],
+  myRole: 'agent',
+  preset: 'call',          // 30-second rotation, 1 word, ±1 tolerance
+  theirIdentity: customerId,
+})
+
+// Agent asks: "What's your verification word?"
+// Customer speaks their word from the app
+const result = session.verify(spokenWord)
+
+switch (result.status) {
+  case 'valid':
+    // Customer identity confirmed — two SCA factors satisfied:
+    //   Knowledge: customer knows the seed (derives the correct word)
+    //   Possession: seed stored on their device behind biometrics
+    const agentWord = session.myToken()
+    // Agent reads aloud: "Your confirmation word is: [agentWord]"
+    // Customer verifies on their app — bidirectional authentication
+    break
+
+  case 'duress':
+    // Customer spoke their duress word — they are under coercion
+    showVerified()                        // maintain plausible deniability
+    triggerDuressProtocol(result.identities) // silent security alert
+    break
+
+  case 'invalid':
+    // Word does not match — escalate to manual identity checks
+    escalateToSecurity()
+    break
+}
+```
+
+**Step 3: Transaction-specific dynamic linking (FCA requirement)**
+
+FCA SCA requires authentication codes to be dynamically linked to the specific
+transaction amount and payee for remote electronic payments. Encode transaction
+parameters into the session namespace:
+
+```typescript
+// Payment: £1,250.00 to payee 'ACME-CORP'
+const paymentSession = createSession({
+  secret: customerSeed,
+  namespace: `aviva:payment:ACME-CORP:125000`, // payee + amount in pence
   roles: ['caller', 'agent'],
   myRole: 'agent',
   preset: 'call',
   theirIdentity: customerId,
 })
+
+// This session produces different words from the standard session —
+// the token is cryptographically bound to the transaction parameters.
+// Changing the amount or payee produces a different word.
+const paymentWord = paymentSession.myToken()
+```
+
+**Step 4: Customer-side implementation (mobile app)**
+
+```typescript
+// Customer's app — same seed, same namespace, opposite role
+const customerSession = createSession({
+  secret: customerSeed,       // retrieved from Keychain/KeyStore
+  namespace: 'aviva',
+  roles: ['caller', 'agent'],
+  myRole: 'caller',           // customer is the caller
+  preset: 'call',
+  theirIdentity: 'aviva-agent',
+})
+
+// App displays:
+//   "Your word: [customerSession.myToken()]"     — speak this to the agent
+//   "Expect to hear: [customerSession.theirToken()]" — agent should say this
+//   Countdown bar showing seconds until rotation
 ```
 
+**Replacing SMS OTP with CANARY**
+
+| Property | SMS OTP | CANARY |
+|----------|---------|--------|
+| Factor type | Possession only (SIM) | Knowledge + Possession |
+| Phishing resistance | None (code can be relayed) | High (HMAC-derived, no transmittable code) |
+| Offline capable | No (requires SMS delivery) | Yes (derived locally after initial sync) |
+| Bidirectional | No (institution never proves identity) | Yes (mutual verification) |
+| Coercion resistance | None | Duress word triggers silent alert |
+| SIM-swap vulnerability | Critical | None (seed in device secure storage) |
+| Dynamic linking | Separate mechanism needed | Built into namespace construction |
+
 ### RBI Digital Payment Authentication (India)
 
 Pattern 1 satisfies the RBI's two-factor authentication requirement for digital
@@ -634,6 +737,229 @@ Nostr relays. The vault is a single JSON blob containing all group states,
 encrypted with the user's own keypair, published as a kind 30078 event with
 a `d` tag of `canary:vault`.
 
+## Distributed Deployment Architecture
+
+When deploying CANARY across multiple nodes (multi-region call centres, redundant
+backend services, or clustered enterprise systems), verification state must be
+synchronised without compromising the protocol's deepfake-proof guarantees.
+
+### Architecture overview
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Node A      │     │  Node B      │     │  Node C      │
+│  (London)    │     │  (Mumbai)    │     │  (Dubai)     │
+│              │     │              │     │              │
+│  GroupState   │◄───►│  GroupState   │◄───►│  GroupState   │
+│  applySyncMsg │     │  applySyncMsg │     │  applySyncMsg │
+│              │     │              │     │              │
+│  Verify ✓    │     │  Verify ✓    │     │  Verify ✓    │
+└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
+       │                    │                    │
+       └────────────────────┼────────────────────┘
+                            │
+                    ┌───────┴───────┐
+                    │  Nostr Relays │
+                    │  (sync layer) │
+                    └───────────────┘
+```
+
+### Key principle: verification is stateless, sync is not
+
+Verification word derivation (`deriveVerificationWord`, `deriveToken`,
+`session.myToken()`) is a pure function of `(seed, counter)`. Any node with the
+seed can derive the correct word independently. No network round-trip needed.
+
+State synchronisation is only required for:
+- **Counter advances** (burn-after-use rotation)
+- **Member changes** (join/leave triggers reseed)
+- **Reseed events** (new seed distribution)
+
+This means nodes can verify callers even during network partitions. Sync is
+an optimisation for counter freshness, not a requirement for verification.
+
+### Conflict resolution via authority invariants
+
+The sync protocol enforces six invariants (I1-I6) that guarantee convergence:
+
+```typescript
+import {
+  applySyncMessage,
+  decodeSyncMessage,
+  decryptEnvelope,
+  deriveGroupKey,
+  type SyncMessage,
+} from 'canary-kit/sync'
+
+// Each node maintains its own GroupState and applies messages identically
+function handleIncomingSync(
+  localState: GroupState,
+  encryptedPayload: string,
+  senderPubkey: string,
+): GroupState {
+  const groupKey = deriveGroupKey(localState.seed)
+  const decrypted = await decryptEnvelope(groupKey, encryptedPayload)
+  const msg = decodeSyncMessage(decrypted)
+  const nowSec = Math.floor(Date.now() / 1000)
+
+  // applySyncMessage enforces all invariants:
+  //   I1: sender must be in admins (for privileged actions)
+  //   I2: opId must not be consumed (replay protection)
+  //   I3: epoch must match local epoch (non-reseed ops)
+  //   I4: reseed epoch must be local.epoch + 1
+  //   I5: snapshot epoch must be >= local epoch
+  //   I6: stale epoch messages are dropped
+  return applySyncMessage(localState, msg, nowSec, senderPubkey)
+}
+```
+
+### Eventual consistency model
+
+CANARY's sync protocol guarantees **eventual consistency** across nodes:
+
+| Scenario | Resolution |
+|----------|------------|
+| Two nodes advance counter simultaneously | Monotonic rule: `effective(incoming) > effective(local)` — highest wins, lower is no-op |
+| Node misses a counter advance | Next advance carries the latest counter; stale node catches up |
+| Node misses a reseed | Stale node rejects subsequent messages (epoch mismatch I3); admin must re-invite |
+| Network partition heals | Nodes exchange messages; invariant checks accept valid, reject stale |
+| Duplicate message delivery | opId replay guard (I2) silently drops duplicates |
+| Clock skew between nodes | ±60 second future skew tolerance; counter derived from `floor(time / interval)` absorbs drift |
+
+### Multi-node sync implementation
+
+```typescript
+import {
+  encodeSyncMessage,
+  applySyncMessage,
+  applySyncMessageWithResult,
+  encryptEnvelope,
+  decryptEnvelope,
+  deriveGroupKey,
+  STORED_MESSAGE_TYPES,
+} from 'canary-kit/sync'
+import { buildSignalEvent, buildStoredSignalEvent } from 'canary-kit/nostr'
+
+// Publish a state change to all nodes via Nostr relay
+async function broadcastSync(
+  group: GroupState,
+  msg: SyncMessage,
+  signer: EventSigner,
+): Promise<void> {
+  const groupKey = deriveGroupKey(group.seed)
+  const encrypted = await encryptEnvelope(groupKey, encodeSyncMessage(msg))
+
+  // Stored messages (member changes, reseeds) use kind 30078
+  // so offline nodes receive them when they reconnect.
+  // Ephemeral messages (beacons, liveness) use kind 20078.
+  const event = STORED_MESSAGE_TYPES.has(msg.type)
+    ? buildStoredSignalEvent({
+        groupId: group.name,
+        signalType: msg.type,
+        encryptedContent: encrypted,
+      })
+    : buildSignalEvent({
+        groupId: group.name,
+        signalType: msg.type,
+        encryptedContent: encrypted,
+      })
+
+  const signed = await signer.sign({ ...event, pubkey: signer.pubkey })
+  await relay.publish(signed)
+}
+
+// Receive and apply sync messages from other nodes
+function onSyncMessage(
+  localState: GroupState,
+  encryptedPayload: string,
+  senderPubkey: string,
+): { state: GroupState; applied: boolean } {
+  const groupKey = deriveGroupKey(localState.seed)
+  const decrypted = await decryptEnvelope(groupKey, encryptedPayload)
+  const msg = decodeSyncMessage(decrypted)
+  const nowSec = Math.floor(Date.now() / 1000)
+
+  // applySyncMessageWithResult tells you whether the message was applied
+  // or silently rejected by invariant checks — useful for logging
+  const result = applySyncMessageWithResult(localState, msg, nowSec, senderPubkey)
+
+  if (!result.applied) {
+    // Message rejected — log for debugging (never log seed material)
+    auditLog.warn('sync_rejected', {
+      type: msg.type,
+      epoch: (msg as { epoch?: number }).epoch,
+      localEpoch: localState.epoch,
+      sender: senderPubkey,
+    })
+  }
+
+  return result
+}
+```
+
+### Handling network partitions
+
+During a partition, each node continues to derive and verify words locally.
+When the partition heals:
+
+1. **Counter advances** — the monotonic rule resolves ordering automatically.
+   Only the highest effective counter is kept; lower values are no-ops.
+
+2. **Member changes during partition** — if an admin added/removed members while
+   a node was partitioned, the node will reject post-reseed messages (epoch
+   mismatch). The admin must send a `state-snapshot` to catch up partitioned
+   nodes within the same epoch, or re-invite for cross-epoch recovery.
+
+3. **Verification during partition** — works normally. Words derive from
+   `(seed, counter)` which both sides share. The only risk is counter drift
+   if one side burned words (burn-after-use) while the other didn't. The
+   tolerance window (`±tolerance` counter values) absorbs small drift.
+
+### Error handling
+
+```typescript
+import { decodeSyncMessage } from 'canary-kit/sync'
+
+// decodeSyncMessage validates all fields and rejects malformed messages
+try {
+  const msg = decodeSyncMessage(payload)
+} catch (err) {
+  // Common rejection reasons:
+  //   'Unsupported protocol version' — sender is on a different protocol version
+  //   'Invalid sync message type'    — unknown message type (forward compatibility)
+  //   'not valid JSON'               — corrupted or tampered payload
+  // All are safe to log and discard
+}
+
+// applySyncMessage returns unchanged state on rejection (fail-closed)
+// Use applySyncMessageWithResult to distinguish applied from rejected
+const { state, applied } = applySyncMessageWithResult(group, msg, nowSec, sender)
+if (!applied) {
+  // Invariant violation — message is either:
+  //   - From a non-admin (I1)
+  //   - Replayed opId (I2)
+  //   - Wrong epoch (I3/I4/I6)
+  //   - Stale counter (monotonic check)
+  // Safe to discard. Do not retry.
+}
+```
+
+### Deepfake-proof guarantees in distributed deployments
+
+The distributed architecture preserves all CANARY security properties:
+
+| Property | How it's preserved across nodes |
+|----------|-------------------------------|
+| P1: Token Unpredictability | Each node derives tokens from the same `(seed, counter)` — pure HMAC-SHA256 |
+| P2: Duress Indistinguishability | Duress derivation is local; duress alerts propagate via encrypted sync |
+| P4: Replay Resistance | Counter monotonicity enforced by `applySyncMessage`; opId deduplication prevents replay |
+| P5: Coercion Resistance | Duress signals broadcast to all nodes via sync; all nodes alert security teams |
+| P6: Liveness Guarantee | Liveness heartbeats are fire-and-forget; freshness gate (300s) prevents stale replay |
+| P8: Timing Safety | Constant-time string comparison (`timingSafeStringEqual`) on every node |
+
+The sync layer is a consistency optimisation. The security properties are
+properties of the cryptographic derivation, not the transport.
+
 ## Licence
 
 MIT — same as canary-kit.

package/README.md

@@ -207,6 +207,23 @@ If you find canary-kit useful, consider sending a tip:
 - **Lightning:** `thedonkey@strike.me`
 - **Nostr zaps:** `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 MIT

package/SECURITY.md

@@ -4,7 +4,8 @@
 
 | Version | Supported |
 |---------|-----------|
-| 1.x.x   | Yes       |
+| 2.x.x   | Yes       |
+| 1.x.x   | No        |
 | < 1.0.0 | No        |
 
 ## Reporting a Vulnerability

package/llms-full.txt

@@ -40,7 +40,7 @@ import { createSession, generateSeed, deriveSeed, SESSION_PRESETS } from 'canary
 import { WORDLIST, WORDLIST_SIZE, getWord, indexOf } from 'canary-kit/wordlist'
 import { KINDS, buildGroupStateEvent, buildStoredSignalEvent, buildSignalEvent, buildRumourEvent, hashGroupId } from 'canary-kit/nostr'
 import { deriveBeaconKey, encryptBeacon, decryptBeacon, buildDuressAlert, encryptDuressAlert, decryptDuressAlert } from 'canary-kit/beacon'
-import { applySyncMessage, decodeSyncMessage, encodeSyncMessage, deriveGroupKey, deriveGroupSigningKey, hashGroupTag, encryptEnvelope, decryptEnvelope } from 'canary-kit/sync'
+import { applySyncMessage, applySyncMessageWithResult, decodeSyncMessage, encodeSyncMessage, deriveGroupKey, deriveGroupIdentity, hashGroupTag, encryptEnvelope, decryptEnvelope, PROTOCOL_VERSION, type SyncApplyResult, type SyncTransport, type EventSigner } from 'canary-kit/sync'
 ```
 
 ---
@@ -107,8 +107,10 @@ interface GroupConfig {
   rotationInterval?: number            // Seconds; overrides preset value
   wordCount?: 1 | 2 | 3               // Words per challenge; overrides preset value
   wordlist?: string                    // Wordlist identifier (default: 'en-v1')
+  tolerance?: number                   // Counter tolerance for verification (default: 1)
   beaconInterval?: number              // Beacon broadcast interval in seconds (default: 300)
   beaconPrecision?: number             // Geohash precision for normal beacons 1–11 (default: 6)
+  creator?: string                     // Pubkey of group creator — only the creator is admin at bootstrap. Must be in members. Without creator, admins is empty and all privileged sync ops are silently rejected.
 }
 
 /** Serialisable persistent state for a canary group. */
@@ -116,14 +118,19 @@ interface GroupState {
   name: string
   seed: string                         // 64-char hex (256-bit shared secret)
   members: string[]                    // Nostr pubkeys (64-char hex)
+  admins: string[]                     // Pubkeys with admin privileges (reseed, add/remove others). Set via GroupConfig.creator.
   rotationInterval: number             // Seconds
   wordCount: 1 | 2 | 3
   wordlist: string                     // e.g. 'en-v1'
   counter: number                      // Time-based counter at last sync
   usageOffset: number                  // Burn-after-use offset on top of counter
+  tolerance: number                    // Counter tolerance for verification
   createdAt: number                    // Unix timestamp
   beaconInterval: number               // Seconds
   beaconPrecision: number              // 1–11
+  epoch: number                        // Monotonic epoch — increments on reseed. Used for replay protection.
+  consumedOps: string[]                // Consumed operation IDs within current epoch. Cleared on epoch bump.
+  consumedOpsFloor?: number            // Timestamp floor: reject messages at or below this value (replay protection after consumedOps eviction)
 }
 
 // ── Group Presets ─────────────────────────────────────────────────────────────
@@ -429,16 +436,41 @@ const updated = addMember(state, '<charlie-pubkey>')
 
 ### removeMember(state, pubkey)
 
-Remove a member from the group and immediately reseed to invalidate the old shared secret. Returns new state — does not mutate.
+Remove a member from the group's member list. Does NOT reseed — the removed member still possesses the old seed. Use `removeMemberAndReseed()` instead unless you have a specific reason not to. Returns new state — does not mutate.
 
 ```typescript
 removeMember(state: GroupState, pubkey: string): GroupState
 
 const updated = removeMember(state, '<alice-pubkey>')
+// updated.seed === state.seed  (NOT reseeded — old seed still valid)
+// updated.members does not include alice
+```
+
+### removeMemberAndReseed(state, pubkey)
+
+Remove a member and immediately reseed, atomically invalidating the old seed. This is the recommended way to remove members — ensures forward secrecy by preventing the removed member from deriving future tokens or decrypting future beacons. Returns new state — does not mutate.
+
+```typescript
+removeMemberAndReseed(state: GroupState, pubkey: string): GroupState
+
+const updated = removeMemberAndReseed(state, '<alice-pubkey>')
 // updated.seed !== state.seed  (reseeded)
 // updated.members does not include alice
 ```
 
+### dissolveGroup(state)
+
+Dissolve a group, zeroing the seed and clearing all members. Preserves name and timestamps for audit trail. Callers MUST also delete the persisted record (IndexedDB, localStorage, backend) after calling this. Returns new state — does not mutate.
+
+```typescript
+dissolveGroup(state: GroupState): GroupState
+
+const dissolved = dissolveGroup(state)
+// dissolved.seed === '0'.repeat(64)
+// dissolved.members === []
+// dissolved.admins === []
+```
+
 ### syncCounter(state, nowSec?)
 
 Refresh the counter to the current time window. Call after loading persisted state. Returns new state — does not mutate.
@@ -1159,26 +1191,53 @@ type SyncMessage =
   | { type: 'liveness-checkin'; pubkey: string; timestamp: number; opId: string }
   | { type: 'state-snapshot'; seed: string; counter: number; usageOffset: number; members: string[]; admins: string[]; epoch: number; opId: string; timestamp: number; prevEpochSeed?: string }
 
-interface SyncResult {
-  state: GroupState
-  applied: boolean
-  reason?: string
+/** Result of applying a sync message, indicating whether it was accepted. */
+interface SyncApplyResult {
+  state: GroupState                    // The resulting group state (unchanged if rejected)
+  applied: boolean                     // Whether the message was applied
+}
+
+/** Minimal interface any sync transport must implement. */
+interface SyncTransport {
+  send(groupId: string, message: SyncMessage, recipients?: string[]): Promise<void>
+  subscribe(groupId: string, onMessage: (msg: SyncMessage, sender: string) => void): () => void
+  disconnect(): void
+}
+
+/** Abstracts event signing and NIP-44 encryption for transports that need it. */
+interface EventSigner {
+  pubkey: string
+  sign(event: unknown): Promise<unknown>
+  encrypt(plaintext: string, recipientPubkey: string): Promise<string>
+  decrypt(ciphertext: string, senderPubkey: string): Promise<string>
 }
 ```
 
 ### Functions
 
 ```typescript
-decodeSyncMessage(json: string): SyncMessage        // Parse and validate a JSON sync message
-encodeSyncMessage(msg: SyncMessage): string          // Serialise a sync message to JSON
-applySyncMessage(state: GroupState, msg: SyncMessage, sender?: string): SyncResult  // Apply a validated message to group state
+decodeSyncMessage(json: string): SyncMessage                              // Parse and validate a JSON sync message. Throws on invalid input or wrong protocolVersion.
+encodeSyncMessage(msg: SyncMessage): string                               // Serialise a sync message to JSON. Injects protocolVersion automatically.
+applySyncMessage(state: GroupState, msg: SyncMessage, nowSec?: number, sender?: string): GroupState  // Apply a sync message. Returns new state, or SAME REFERENCE if rejected (silent rejection).
+applySyncMessageWithResult(state: GroupState, msg: SyncMessage, nowSec?: number, sender?: string): SyncApplyResult  // Same as applySyncMessage but returns { state, applied } for observability.
 ```
 
+**IMPORTANT — silent rejection:** `applySyncMessage` returns the unchanged GroupState reference when a message is rejected. Common causes of silent rejection:
+- Privileged action without sender, or sender not in `group.admins` (I1)
+- Replayed opId already in `consumedOps` (I2)
+- Epoch mismatch: non-reseed ops must match local epoch (I3), reseed must be local epoch + 1 (I4)
+- Stale epoch for any privileged op (I6)
+- `counter-advance` without sender, or sender not in `group.members`
+- `counter-advance` that would regress the effective counter (monotonic)
+- Fire-and-forget messages older than 5 minutes or >60s in the future
+
+Use `applySyncMessageWithResult` when you need to log or alert on rejected messages.
+
 ### Envelope Encryption
 
 ```typescript
 deriveGroupKey(seed: string): Uint8Array             // Derive AES-256-GCM group key from seed
-deriveGroupSigningKey(seed: string): Uint8Array      // Derive HMAC signing key from seed
+deriveGroupIdentity(seed: string): Uint8Array      // Derive HMAC signing key from seed
 hashGroupTag(groupId: string): string                // Privacy-preserving group tag hash
 encryptEnvelope(key: Uint8Array, plaintext: string): Promise<string>  // AES-256-GCM encrypt
 decryptEnvelope(key: Uint8Array, ciphertext: string): Promise<string> // AES-256-GCM decrypt
@@ -1351,8 +1410,8 @@ state = advanceCounter(state)  // next call will use a different word
 state = addMember(state, '<diana-pubkey>')
 // Distribute new seed to diana via encrypted Nostr DM
 
-// Remove a compromised member (auto-reseeds)
-state = removeMember(state, '<charlie-pubkey>')
+// Remove a compromised member and reseed atomically
+state = removeMemberAndReseed(state, '<charlie-pubkey>')
 // Distribute new state.seed to remaining members
 ```
 

package/llms.txt

@@ -25,14 +25,16 @@ Core derivation:
 - verifyWord(spokenWord, seedHex, memberPubkeys, counter, wordCount?) → VerifyResult
 
 Group lifecycle:
-- createGroup(config) → GroupState
+- createGroup(config) → GroupState (config.creator sets initial admin; without creator, admins is empty)
 - 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
+- removeMember(state, pubkey) → GroupState (does NOT reseed)
+- removeMemberAndReseed(state, pubkey) → GroupState (recommended: removes + reseeds atomically)
+- dissolveGroup(state) → GroupState (zeroes seed, clears members)
+- syncCounter(state, nowSec?) → GroupState (refreshes counter to current time window, monotonic)
 
 Counter:
 - getCounter(timestampSec, rotationIntervalSec?) → number
@@ -124,18 +126,23 @@ Types: BeaconPayload ({ geohash, precision, timestamp }), DuressAlert ({ type, m
 
 ### canary-kit/sync
 
-Transport-agnostic group state synchronisation. Authority model with 6 invariants, replay protection, epoch boundaries.
+Transport-agnostic group state synchronisation. Authority model with 6 invariants, replay protection, epoch boundaries. See COOKBOOK.md for complete workflow examples.
 
-- decodeSyncMessage(json) → SyncMessage (validates and parses)
-- encodeSyncMessage(msg) → string (serialises to JSON)
-- applySyncMessage(state, msg, sender?) → SyncResult ({ state, applied, reason? })
+- decodeSyncMessage(json) → SyncMessage (validates and parses; throws on invalid input)
+- encodeSyncMessage(msg) → string (serialises to JSON; injects protocolVersion)
+- applySyncMessage(state, msg, nowSec?, sender?) → GroupState (apply a sync message; returns same reference if rejected)
+- applySyncMessageWithResult(state, msg, nowSec?, sender?) → SyncApplyResult ({ state, applied }) (same as above but indicates acceptance)
 - deriveGroupKey(seed) → Uint8Array (AES-256-GCM group key)
-- deriveGroupSigningKey(seed) → Uint8Array (HMAC signing key)
+- deriveGroupIdentity(seed) → Uint8Array (group identity 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
+IMPORTANT: applySyncMessage silently returns unchanged state when rejected. Privileged actions (member-join of others, reseed, state-snapshot) require sender in group.admins. counter-advance requires sender in group.members. Omitting sender causes silent rejection. Set creator in createGroup() to populate admins.
+
+Message types: member-join, member-leave, counter-advance, reseed, beacon, duress-alert, duress-clear, liveness-checkin, state-snapshot
+
+Types: SyncApplyResult ({ state: GroupState, applied: boolean }), SyncTransport (interface for pluggable transports), EventSigner (interface for Nostr signing)
 
 ## Quick Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canary-kit",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "Deepfake-proof identity verification. Open protocol, minimal dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,7 +46,9 @@
   "files": [
     "dist/",
     "LICENSE",
+    "API.md",
     "CANARY.md",
+    "COOKBOOK.md",
     "NIP-CANARY.md",
     "INTEGRATION.md",
     "SECURITY.md",