canary-kit 2.6.2 → 2.7.1

package/llms-full.txt

@@ -38,9 +38,9 @@ import { deriveToken, deriveDuressToken, verifyToken, deriveLivenessToken, deriv
 import { encodeAsWords, encodeAsPin, encodeAsHex, encodeToken } from 'canary-kit/encoding'
 import { createSession, generateSeed, deriveSeed, SESSION_PRESETS } from 'canary-kit/session'
 import { WORDLIST, WORDLIST_SIZE, getWord, indexOf } from 'canary-kit/wordlist'
-import { KINDS, buildGroupEvent, buildSeedDistributionEvent, buildMemberUpdateEvent, buildReseedEvent, buildWordUsedEvent, buildBeaconEvent } from 'canary-kit/nostr'
+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 ─────────────────────────────────────────────────────────────
@@ -177,7 +184,7 @@ interface Session {
 
 // ── Beacon ────────────────────────────────────────────────────────────────────
 
-/** Decrypted content of a kind 20800 location beacon event. */
+/** Decrypted content of an encrypted location beacon (kind 20078 signal). */
 interface BeaconPayload {
   geohash: string
   precision: number
@@ -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.
@@ -1007,117 +1039,126 @@ WORDLIST[2047]  // 'zoo'
 
 ## canary-kit/nostr
 
-Nostr event builders for the CANARY NIP. All builders return unsigned events (`UnsignedEvent`) — sign with your own Nostr library (e.g. `nostr-tools`).
+Nostr event builders for SSG (Simple Shared Secret) groups. Uses standard Nostr kinds — no custom event kinds. All builders return unsigned events (`UnsignedEvent`) — sign with your own Nostr library (e.g. `nostr-tools`).
+
+Three event kinds are used:
+- **kind 30078** (parameterised replaceable) — group state and stored signals. The d-tag uses the `ssg/` namespace prefix.
+- **kind 20078** (ephemeral) — real-time signals between group members.
+- **kind 14** (rumour / unsigned inner event) — NIP-17 gift-wrapped DMs carrying seed distribution, reseed, and other private payloads.
 
 ### KINDS
 
 ```typescript
 const KINDS = {
-  group:            38_800,  // replaceable — group announcement
-  seedDistribution: 28_800,  // ephemeral — seed delivery to member
-  memberUpdate:     38_801,  // replaceable — add/remove member
-  reseed:           28_801,  // ephemeral — new seed broadcast
-  wordUsed:         28_802,  // ephemeral — burn-after-use notification
-  beacon:           20_800,  // ephemeral — encrypted location beacon
+  groupState: 30_078,  // parameterised replaceable — group state and stored signals
+  signal:     20_078,  // ephemeral — real-time signals
+  giftWrap:    1_059,  // NIP-17 gift wrap (consumer wraps kind 14 rumours)
 } as const
 ```
 
-### buildGroupEvent(params)
+### buildGroupStateEvent(params)
 
-Build a kind 38800 group announcement event.
+Build an unsigned kind 30078 group state event. The d-tag uses plaintext `ssg/<groupId>` since content is NIP-44 encrypted. Includes NIP-32 labels for the SSG namespace and p-tags for each member.
 
 ```typescript
-buildGroupEvent(params: GroupEventParams): UnsignedEvent
+buildGroupStateEvent(params: GroupStateEventParams): UnsignedEvent
 
-buildGroupEvent({
+interface GroupStateEventParams {
+  groupId: string
+  members: string[]           // hex pubkeys
+  encryptedContent: string    // NIP-44 encrypted group config
+  rotationInterval?: number   // seconds between word rotations
+  tolerance?: number          // counter tolerance window
+  expiration?: number         // NIP-40 expiration (unix seconds)
+}
+
+buildGroupStateEvent({
   groupId: 'alpine-team-1',
-  name: 'Alpine Team',
   members: ['<alice-pubkey>', '<bob-pubkey>'],
+  encryptedContent: '<NIP-44 encrypted group config>',
   rotationInterval: 86_400,
-  wordCount: 2,
-  wordlist: 'en-v1',
-  encryptedContent: '<NIP-44 encrypted group metadata>',
-  expiration: Math.floor(Date.now() / 1000) + 30 * 86_400,  // 30 days
+  tolerance: 1,
+  expiration: Math.floor(Date.now() / 1000) + 30 * 86_400,
 })
-// { kind: 38800, content: '...', tags: [['d','alpine-team-1'],['name','Alpine Team'],['p','<alice>'],['p','<bob>'],['rotation','86400'],['words','2'],['wordlist','en-v1'],['expiration','...']], created_at: ... }
+// { kind: 30078, content: '...', tags: [['d','ssg/alpine-team-1'],['p','<alice>'],['p','<bob>'],['L','ssg'],['l','group','ssg'],['rotation','86400'],['tolerance','1'],['expiration','...']], created_at: ... }
 ```
 
-### buildSeedDistributionEvent(params)
+### buildStoredSignalEvent(params)
 
-Build a kind 28800 seed distribution event, sent privately to each member.
+Build an unsigned kind 30078 stored signal event. The d-tag uses a SHA-256 hash of the group ID (for privacy) scoped by signal type: `ssg/<SHA256(groupId)>:<signalType>`. Includes a 7-day NIP-40 expiration tag.
 
 ```typescript
-buildSeedDistributionEvent(params: SeedDistributionParams): UnsignedEvent
+buildStoredSignalEvent(params: StoredSignalEventParams): UnsignedEvent
 
-buildSeedDistributionEvent({
-  recipientPubkey: '<alice-pubkey>',
-  groupEventId: '<kind-38800-event-id>',
-  encryptedContent: '<NIP-44 encrypted seed for alice>',
-})
-// { kind: 28800, content: '...', tags: [['p','<alice>'],['e','<group-id>']], created_at: ... }
-```
-
-### buildMemberUpdateEvent(params)
-
-Build a kind 38801 member update event.
-
-```typescript
-buildMemberUpdateEvent(params: MemberUpdateParams): UnsignedEvent
+interface StoredSignalEventParams {
+  groupId: string
+  signalType: string          // e.g. 'counter-advance', 'word-used'
+  encryptedContent: string
+}
 
-buildMemberUpdateEvent({
+buildStoredSignalEvent({
   groupId: 'alpine-team-1',
-  action: 'add',
-  memberPubkey: '<charlie-pubkey>',
-  reseed: true,
-  encryptedContent: '<encrypted update content>',
+  signalType: 'counter-advance',
+  encryptedContent: '<encrypted signal payload>',
 })
-// { kind: 38801, ... tags: [['d','alpine-team-1'],['action','add'],['p','<charlie>'],['reseed','true']], ... }
+// { kind: 30078, content: '...', tags: [['d','ssg/<hash>:counter-advance'],['expiration','...']], created_at: ... }
 ```
 
-### buildReseedEvent(params)
+### buildSignalEvent(params)
 
-Build a kind 28801 reseed event.
+Build an unsigned kind 20078 ephemeral signal event. The d-tag uses a SHA-256 hash of the group ID (for privacy). A t-tag carries the signal type. No expiration tag — ephemeral events are not stored by relays.
 
 ```typescript
-buildReseedEvent(params: ReseedParams): UnsignedEvent
+buildSignalEvent(params: SignalEventParams): UnsignedEvent
+
+interface SignalEventParams {
+  groupId: string
+  signalType: string          // e.g. 'beacon', 'word-used', 'counter-advance'
+  encryptedContent: string
+}
 
-buildReseedEvent({
-  groupEventId: '<kind-38800-event-id>',
-  reason: 'member_removed',
-  encryptedContent: '<NIP-44 encrypted new seed>',
+buildSignalEvent({
+  groupId: 'alpine-team-1',
+  signalType: 'beacon',
+  encryptedContent: '<AES-256-GCM encrypted beacon payload>',
 })
-// { kind: 28801, ... tags: [['e','<group-id>'],['reason','member_removed']], ... }
+// { kind: 20078, content: '...', tags: [['d','ssg/<hash>'],['t','beacon']], created_at: ... }
 ```
 
-Valid reason values: `'member_removed'` | `'compromise'` | `'scheduled'` | `'duress'`
+### buildRumourEvent(params)
 
-### buildWordUsedEvent(params)
+Build an unsigned kind 14 rumour event for NIP-17 gift wrapping. The consumer must set the `pubkey` field before computing the event ID, then seal (NIP-44 encrypt + kind 13) and gift-wrap (kind 1059) the rumour.
 
-Build a kind 28802 word-used (burn-after-use) notification event.
+Used for seed distribution, reseed notifications, and member updates — anything that must be sent privately to a specific member.
 
 ```typescript
-buildWordUsedEvent(params: WordUsedParams): UnsignedEvent
+buildRumourEvent(params: RumourEventParams): UnsignedEvent
+
+interface RumourEventParams {
+  recipientPubkey: string     // 64-char hex pubkey
+  subject: string             // e.g. 'ssg:seed-distribution', 'ssg:reseed', 'ssg:member-update'
+  encryptedContent: string    // NIP-44 encrypted payload
+  groupEventId?: string       // optional reference to the group state event
+}
 
-buildWordUsedEvent({
-  groupEventId: '<kind-38800-event-id>',
-  encryptedContent: '<encrypted burn notification>',
+buildRumourEvent({
+  recipientPubkey: '<alice-pubkey>',
+  subject: 'ssg:seed-distribution',
+  encryptedContent: '<NIP-44 encrypted seed>',
+  groupEventId: '<group-state-event-id>',
 })
-// { kind: 28802, ... tags: [['e','<group-id>']], ... }
+// { kind: 14, content: '...', tags: [['p','<alice>'],['subject','ssg:seed-distribution'],['e','<group-id>']], created_at: ... }
 ```
 
-### buildBeaconEvent(params)
+### hashGroupId(groupId)
 
-Build a kind 20800 encrypted location beacon event.
+SHA-256 hash a group ID for use in d-tags where privacy matters.
 
 ```typescript
-buildBeaconEvent(params: BeaconEventParams): UnsignedEvent
+hashGroupId(groupId: string): string
 
-buildBeaconEvent({
-  groupId: 'alpine-team-1',
-  encryptedContent: '<AES-256-GCM encrypted beacon payload>',
-  expiration: Math.floor(Date.now() / 1000) + 3600,  // 1 hour
-})
-// { kind: 20800, ... tags: [['h','alpine-team-1'],['expiration','...']], ... }
+hashGroupId('alpine-team-1')
+// '3a7f...' (64-char hex)
 ```
 
 ---
@@ -1150,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
@@ -1223,16 +1291,15 @@ Used with `createSession({ preset: '...' })`.
 
 ## Nostr Event Kinds
 
-| Kind | Type | Name | Description |
+Uses standard Nostr kinds — no custom event kinds.
+
+| Kind | Type | KINDS key | Description |
 |---|---|---|---|
-| 38800 | Replaceable | `group` | Group announcement with member list and configuration |
-| 28800 | Ephemeral | `seedDistribution` | Encrypted seed delivery to a specific member |
-| 38801 | Replaceable | `memberUpdate` | Add or remove a group member (with optional reseed) |
-| 28801 | Ephemeral | `reseed` | New seed broadcast after compromise or member removal |
-| 28802 | Ephemeral | `wordUsed` | Burn-after-use notification — advance counter for all members |
-| 20800 | Ephemeral | `beacon` | AES-256-GCM encrypted location beacon |
+| 30078 | Parameterised replaceable | `groupState` | Group state (d-tag `ssg/<groupId>`) and stored signals (d-tag `ssg/<hash>:<signalType>`) |
+| 20078 | Ephemeral | `signal` | Real-time signals between group members (beacon, word-used, counter-advance) |
+| 14 → 1059 | NIP-17 gift wrap | `giftWrap` | Seed distribution, reseed, member updates (kind 14 rumour sealed + wrapped) |
 
-Replaceable events (38xxx) use the `d` tag for addressability. Ephemeral events (28xxx, 20xxx) are not stored by relays.
+Kind 30078 events use the `ssg/` d-tag namespace prefix. Kind 20078 events hash the group ID in the d-tag for privacy. Kind 14 rumours are sealed (kind 13) and gift-wrapped (kind 1059) by the consumer — the library builds the unsigned rumour only.
 
 ---
 
@@ -1343,22 +1410,22 @@ 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
 ```
 
 ### Nostr Group Integration
 
-Publish group state and encrypted seeds to Nostr relays so all members can synchronise.
+Publish group state and encrypted seeds to Nostr relays so all members can synchronise. Uses standard Nostr kinds (30078, 20078, NIP-17 gift wrap) — no custom event kinds.
 
 ```typescript
-import { createGroup, syncCounter, deriveBeaconKey, encryptBeacon } from 'canary-kit'
+import { createGroup, deriveBeaconKey, encryptBeacon } from 'canary-kit'
 import {
   KINDS,
-  buildGroupEvent,
-  buildSeedDistributionEvent,
-  buildBeaconEvent,
+  buildGroupStateEvent,
+  buildSignalEvent,
+  buildRumourEvent,
 } from 'canary-kit/nostr'
 
 // 1. Create the group
@@ -1368,37 +1435,34 @@ let state = createGroup({
   preset: 'field-ops',
 })
 
-// 2. Publish a kind 38800 group event (encrypted content via NIP-44)
-const groupEvent = buildGroupEvent({
+// 2. Publish a kind 30078 group state event (encrypted content via NIP-44)
+const groupEvent = buildGroupStateEvent({
   groupId: 'alpine-team-1',
-  name: state.name,
   members: state.members,
-  rotationInterval: state.rotationInterval,
-  wordCount: state.wordCount,
-  wordlist: state.wordlist,
   encryptedContent: '<NIP-44 encrypted group config>',
-  expiration: Math.floor(Date.now() / 1000) + 30 * 86_400,
+  rotationInterval: state.rotationInterval,
 })
 // sign and publish groupEvent to relays
 
-// 3. Send seed to each member via kind 28800 (one event per member)
+// 3. Send seed to each member via NIP-17 gift wrap (kind 14 rumour → seal → wrap)
 for (const memberPubkey of state.members) {
-  const seedEvent = buildSeedDistributionEvent({
+  const rumour = buildRumourEvent({
     recipientPubkey: memberPubkey,
-    groupEventId: '<signed-group-event-id>',
+    subject: 'ssg:seed-distribution',
     encryptedContent: '<NIP-44 encrypted seed for this member>',
+    groupEventId: '<signed-group-event-id>',
   })
-  // sign and publish seedEvent
+  // set pubkey, compute id, then seal (kind 13) and gift-wrap (kind 1059)
 }
 
-// 4. Publish periodic location beacons (kind 20800)
+// 4. Publish periodic location beacons as kind 20078 ephemeral signals
 const beaconKey = deriveBeaconKey(state.seed)
 const encryptedBeacon = await encryptBeacon(beaconKey, 'gcpvjb', 6)
 
-const beaconEvent = buildBeaconEvent({
+const beaconEvent = buildSignalEvent({
   groupId: 'alpine-team-1',
+  signalType: 'beacon',
   encryptedContent: encryptedBeacon,
-  expiration: Math.floor(Date.now() / 1000) + state.beaconInterval * 2,
 })
 // sign and publish beaconEvent
 

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
@@ -100,19 +102,18 @@ Session methods:
 
 ### canary-kit/nostr
 
-Unsigned Nostr event builders for the CANARY protocol (NIP-CANARY). Sign events with your preferred Nostr library.
+Unsigned Nostr event builders for SSG (Simple Shared Secret) groups. Uses standard Nostr kinds — no custom event kinds. 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
+- KINDS — { groupState: 30078, signal: 20078, giftWrap: 1059 }
+- buildGroupStateEvent(params) → UnsignedEvent — kind 30078, d-tag `ssg/<groupId>`, p-tags for members, NIP-32 labels
+- buildStoredSignalEvent(params) → UnsignedEvent — kind 30078, d-tag `ssg/<SHA256(groupId)>:<signalType>`, 7-day expiration
+- buildSignalEvent(params) → UnsignedEvent — kind 20078 ephemeral, d-tag `ssg/<SHA256(groupId)>`, t-tag for signal type
+- buildRumourEvent(params) → UnsignedEvent — kind 14 rumour for NIP-17 gift wrapping (seed distribution, reseed, member updates)
+- hashGroupId(groupId) → string — SHA-256 hash a group ID for privacy-preserving d-tags
 
 ### canary-kit/beacon
 
-AES-256-GCM encrypted location beacons and duress alerts for Nostr kind 20800 events.
+AES-256-GCM encrypted location beacons and duress alerts. Beacons are published as kind 20078 ephemeral signal events.
 
 - deriveBeaconKey(seedHex) → Uint8Array
 - encryptBeacon(key, geohash, precision) → Promise\<string\>
@@ -125,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.6.2",
+  "version": "2.7.1",
   "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",
@@ -143,5 +145,9 @@
     "@scure/bip39": "^2.0.1",
     "nsec-tree": "^1.4.0",
     "spoken-token": "^2.0.2"
+  },
+  "funding": {
+    "type": "lightning",
+    "url": "lightning:thedonkey@strike.me"
   }
 }