canary-kit 0.9.0

package/dist/token.d.ts

@@ -0,0 +1,186 @@
+import { type TokenEncoding } from './encoding.js';
+/**
+ * Maximum allowed tolerance/maxTolerance value.
+ * Prevents pathological iteration: at MAX_TOLERANCE=10, the collision
+ * avoidance window is ±20 counters (41 iterations) — well within reason.
+ */
+export declare const MAX_TOLERANCE = 10;
+/**
+ * CANARY-DERIVE: Derive raw token bytes from a shared secret, context, and counter.
+ *
+ * When `identity` is omitted, derives a group-wide token:
+ *   HMAC-SHA256(secret, utf8(context) || counter_be32)
+ *
+ * When `identity` is provided, derives a per-member token:
+ *   HMAC-SHA256(secret, utf8(context) || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator prevents concatenation ambiguity between context and identity.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param counter - Time-based or usage counter (uint32).
+ * @param identity - Optional member pubkey for per-member tokens.
+ * @returns Raw 32-byte HMAC-SHA256 digest.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ * @throws {Error} If identity is provided but empty.
+ */
+export declare function deriveTokenBytes(secret: Uint8Array | string, context: string, counter: number, identity?: string): Uint8Array;
+/**
+ * CANARY-DERIVE: Derive an encoded token string.
+ *
+ * When `identity` is provided, produces a per-member token unique to that member.
+ * When omitted, produces the group-wide token (backwards-compatible).
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param counter - Time-based or usage counter (uint32).
+ * @param encoding - Output encoding format (default: single word from en-v1 wordlist).
+ * @param identity - Optional member pubkey for per-member tokens.
+ * @returns Encoded token string (word, PIN, or hex depending on encoding).
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ *
+ * @example
+ * ```ts
+ * deriveToken(seedHex, 'canary:group', 42)           // "falcon"
+ * deriveToken(seedHex, 'canary:group', 42, { format: 'pin', digits: 6 })  // "083721"
+ * ```
+ */
+export declare function deriveToken(secret: Uint8Array | string, context: string, counter: number, encoding?: TokenEncoding, identity?: string): string;
+/**
+ * CANARY-DURESS: Derive raw duress token bytes for a specific identity.
+ *
+ * Algorithm: HMAC-SHA256(secret, utf8(context + ":duress") || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator between the context suffix and identity prevents concatenation
+ * ambiguity (e.g. context="x:duress" + identity="" vs context="x" + identity=":duress").
+ *
+ * NOTE: Returns raw bytes without collision avoidance. Use deriveDuressToken()
+ * for encoded output with guaranteed non-collision against the normal token.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier (must be non-empty).
+ * @param counter - Time-based or usage counter (uint32).
+ * @returns Raw 32-byte HMAC-SHA256 digest.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ */
+export declare function deriveDuressTokenBytes(secret: Uint8Array | string, context: string, identity: string, counter: number): Uint8Array;
+/**
+ * CANARY-DURESS: Derive an encoded duress token with collision avoidance.
+ *
+ * If the duress token collides with any normal verification token within
+ * ±(2 × maxTolerance) counter values (at the encoding level), re-derives with
+ * incrementing suffix bytes (0x01, 0x02, ..., 0xFF) until distinct.
+ * The 2× factor accounts for worst-case counter drift: the deriver and verifier
+ * may each be off by maxTolerance in opposite directions.
+ * If all 255 suffixes collide (astronomically unlikely), throws an error
+ * rather than failing open.
+ *
+ * **maxTolerance is required** — it must match the tolerance used by verifiers.
+ * Using an insufficient value allows duress tokens to collide with normal tokens
+ * at distant counters, causing silent alarm suppression.
+ *
+ * **identities** — when provided, the forbidden set also includes per-member
+ * normal tokens for all identities across the collision avoidance window.
+ * Without this, a duress token for identity A could collide with the normal
+ * per-member token for identity B, causing false duress detection.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier for the duress signaller.
+ * @param counter - Time-based or usage counter (uint32).
+ * @param encoding - Output encoding format (default: single word from en-v1 wordlist).
+ * @param maxTolerance - Counter tolerance window used by verifiers; must match their value.
+ * @param identities - All group member pubkeys for cross-member collision avoidance.
+ * @returns Encoded duress token string guaranteed distinct from all normal tokens in the window.
+ * @throws {RangeError} If maxTolerance is negative, exceeds MAX_TOLERANCE, or is not an integer.
+ * @throws {Error} If collision avoidance fails after 255 retries.
+ */
+export declare function deriveDuressToken(secret: Uint8Array | string, context: string, identity: string, counter: number, encoding: TokenEncoding | undefined, maxTolerance: number, identities?: string[]): string;
+/** Result of verifying a token. */
+export interface TokenVerifyResult {
+    /** 'valid' = matches normal token, 'duress' = matches a duress token, 'invalid' = no match. */
+    status: 'valid' | 'duress' | 'invalid';
+    /** Identities of duress signallers (only when status = 'duress'). */
+    identities?: string[];
+}
+/** Options for token verification. */
+export interface VerifyOptions {
+    /** Output encoding to use for comparison (default: single word). */
+    encoding?: TokenEncoding;
+    /** Counter tolerance window: accept tokens within ±tolerance counter values (default: 0). */
+    tolerance?: number;
+}
+/**
+ * CANARY-DURESS: Verify a spoken/entered token against a group.
+ *
+ * Checks in priority order (exact-counter-first):
+ * 1. Normal verification token at exact counter → 'valid'
+ * 2. ALL identities' duress tokens (within tolerance window) → 'duress' with all matches
+ * 3. Normal verification token at remaining tolerance window → 'valid'
+ * 4. No match → 'invalid'
+ *
+ * Exact-counter normal is checked first because same-counter collision avoidance
+ * guarantees no ambiguity. Duress across the full window is checked next so that
+ * duress at the exact counter is never masked by normal at an adjacent counter.
+ *
+ * Per CANARY-DURESS: the verifier MUST check all identities and collect all matches.
+ * The verifier MUST NOT short-circuit after the first duress match.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array).
+ * @param context - Context string for domain separation.
+ * @param counter - Current time-based counter.
+ * @param input - The spoken/entered token to verify.
+ * @param identities - Array of member pubkeys (max 100).
+ * @param options - Optional encoding and tolerance settings.
+ * @returns `{ status: 'valid' | 'duress' | 'invalid', identities?: string[] }`.
+ * @throws {RangeError} If tolerance exceeds MAX_TOLERANCE or identities exceeds 100.
+ *
+ * @example
+ * ```ts
+ * const result = verifyToken(seed, 'canary:group', counter, 'falcon', [alice, bob])
+ * if (result.status === 'duress') alert(`Duress from: ${result.identities}`)
+ * ```
+ */
+export declare function verifyToken(secret: Uint8Array | string, context: string, counter: number, input: string, identities: string[], options?: VerifyOptions): TokenVerifyResult;
+/**
+ * CANARY-DURESS: Derive a liveness heartbeat token for dead man's switch.
+ *
+ * Algorithm: HMAC-SHA256(secret, utf8(context + ":alive") || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator between the context suffix and identity prevents concatenation
+ * ambiguity.
+ *
+ * The liveness token proves both identity and knowledge of the secret.
+ * If heartbeats stop arriving, the implementation triggers its DMS response.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier of the heartbeat sender.
+ * @param counter - Time-based or usage counter (uint32).
+ * @returns Raw 32-byte HMAC-SHA256 digest for the liveness heartbeat.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ */
+export declare function deriveLivenessToken(secret: Uint8Array | string, context: string, identity: string, counter: number): Uint8Array;
+/** A pair of directional tokens keyed by role name. */
+export interface DirectionalPair {
+    [role: string]: string;
+}
+/**
+ * Derive a directional pair: two distinct tokens from the same secret,
+ * one per role. Each token uses context = `${namespace}\0${role}`.
+ *
+ * Neither token can be derived from the other without the shared secret.
+ * This prevents the "echo problem" where the second speaker could parrot
+ * the first.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array).
+ * @param namespace - Namespace prefix (e.g. `'aviva'`, `'dispatch'`).
+ * @param roles - Exactly two role names (e.g. `['caller', 'agent']`).
+ * @param counter - Current counter value.
+ * @param encoding - Output encoding format (default: single word).
+ * @returns Object keyed by role name, each value is the role's token string.
+ * @throws {Error} If roles does not contain exactly 2 entries, or roles are identical.
+ */
+export declare function deriveDirectionalPair(secret: Uint8Array | string, namespace: string, roles: [string, string], counter: number, encoding?: TokenEncoding): DirectionalPair;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAoB,MAAM,eAAe,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,aAAa,KAAK,CAAA;AAmC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CASZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,EAC1C,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAGR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,UAAU,CAIZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,YAAmB,EAC1C,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,MAAM,CA2CR;AAED,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,+FAA+F;IAC/F,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;IACtC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,iBAAiB,CAqEnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,UAAU,CAIZ;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,GACzC,eAAe,CAsBjB"}

package/dist/token.js

@@ -0,0 +1,344 @@
+import { hmacSha256, hexToBytes, concatBytes, timingSafeStringEqual } from './crypto.js';
+import { encodeToken, DEFAULT_ENCODING } from './encoding.js';
+/**
+ * Maximum allowed tolerance/maxTolerance value.
+ * Prevents pathological iteration: at MAX_TOLERANCE=10, the collision
+ * avoidance window is ±20 counters (41 iterations) — well within reason.
+ */
+export const MAX_TOLERANCE = 10;
+const encoder = new TextEncoder();
+function utf8(str) {
+    return encoder.encode(str);
+}
+function counterBe32(counter) {
+    if (!Number.isInteger(counter) || counter < 0 || counter > 0xFFFFFFFF) {
+        throw new RangeError(`Counter must be an integer 0–${0xFFFFFFFF}, got ${counter}`);
+    }
+    const buf = new Uint8Array(4);
+    const view = new DataView(buf.buffer);
+    view.setUint32(0, counter, false);
+    return buf;
+}
+// 128-bit (16-byte) minimum for the universal token API. The group layer
+// enforces 256-bit (32-byte) seeds per CANARY.md, but the universal API
+// supports contexts beyond group seeds where 128-bit keys may be appropriate
+// (e.g. per-session or per-task handoff secrets).
+const MIN_SECRET_BYTES = 16;
+/** Maximum identities in verifyToken to bound O(n²·t²) computational cost. */
+const MAX_MEMBERS = 100;
+function normaliseSecret(secret) {
+    const key = typeof secret === 'string' ? hexToBytes(secret) : secret;
+    if (key.length < MIN_SECRET_BYTES) {
+        throw new RangeError(`Secret must be at least ${MIN_SECRET_BYTES} bytes, got ${key.length}`);
+    }
+    return key;
+}
+/**
+ * CANARY-DERIVE: Derive raw token bytes from a shared secret, context, and counter.
+ *
+ * When `identity` is omitted, derives a group-wide token:
+ *   HMAC-SHA256(secret, utf8(context) || counter_be32)
+ *
+ * When `identity` is provided, derives a per-member token:
+ *   HMAC-SHA256(secret, utf8(context) || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator prevents concatenation ambiguity between context and identity.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param counter - Time-based or usage counter (uint32).
+ * @param identity - Optional member pubkey for per-member tokens.
+ * @returns Raw 32-byte HMAC-SHA256 digest.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ * @throws {Error} If identity is provided but empty.
+ */
+export function deriveTokenBytes(secret, context, counter, identity) {
+    if (identity !== undefined && identity === '') {
+        throw new Error('identity must be non-empty when provided');
+    }
+    const key = normaliseSecret(secret);
+    const data = identity
+        ? concatBytes(utf8(context), new Uint8Array([0x00]), utf8(identity), counterBe32(counter))
+        : concatBytes(utf8(context), counterBe32(counter));
+    return hmacSha256(key, data);
+}
+/**
+ * CANARY-DERIVE: Derive an encoded token string.
+ *
+ * When `identity` is provided, produces a per-member token unique to that member.
+ * When omitted, produces the group-wide token (backwards-compatible).
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param counter - Time-based or usage counter (uint32).
+ * @param encoding - Output encoding format (default: single word from en-v1 wordlist).
+ * @param identity - Optional member pubkey for per-member tokens.
+ * @returns Encoded token string (word, PIN, or hex depending on encoding).
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ *
+ * @example
+ * ```ts
+ * deriveToken(seedHex, 'canary:group', 42)           // "falcon"
+ * deriveToken(seedHex, 'canary:group', 42, { format: 'pin', digits: 6 })  // "083721"
+ * ```
+ */
+export function deriveToken(secret, context, counter, encoding = DEFAULT_ENCODING, identity) {
+    const bytes = deriveTokenBytes(secret, context, counter, identity);
+    return encodeToken(bytes, encoding);
+}
+/**
+ * CANARY-DURESS: Derive raw duress token bytes for a specific identity.
+ *
+ * Algorithm: HMAC-SHA256(secret, utf8(context + ":duress") || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator between the context suffix and identity prevents concatenation
+ * ambiguity (e.g. context="x:duress" + identity="" vs context="x" + identity=":duress").
+ *
+ * NOTE: Returns raw bytes without collision avoidance. Use deriveDuressToken()
+ * for encoded output with guaranteed non-collision against the normal token.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier (must be non-empty).
+ * @param counter - Time-based or usage counter (uint32).
+ * @returns Raw 32-byte HMAC-SHA256 digest.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ */
+export function deriveDuressTokenBytes(secret, context, identity, counter) {
+    const key = normaliseSecret(secret);
+    const data = concatBytes(utf8(context + ':duress'), new Uint8Array([0x00]), utf8(identity), counterBe32(counter));
+    return hmacSha256(key, data);
+}
+/**
+ * CANARY-DURESS: Derive an encoded duress token with collision avoidance.
+ *
+ * If the duress token collides with any normal verification token within
+ * ±(2 × maxTolerance) counter values (at the encoding level), re-derives with
+ * incrementing suffix bytes (0x01, 0x02, ..., 0xFF) until distinct.
+ * The 2× factor accounts for worst-case counter drift: the deriver and verifier
+ * may each be off by maxTolerance in opposite directions.
+ * If all 255 suffixes collide (astronomically unlikely), throws an error
+ * rather than failing open.
+ *
+ * **maxTolerance is required** — it must match the tolerance used by verifiers.
+ * Using an insufficient value allows duress tokens to collide with normal tokens
+ * at distant counters, causing silent alarm suppression.
+ *
+ * **identities** — when provided, the forbidden set also includes per-member
+ * normal tokens for all identities across the collision avoidance window.
+ * Without this, a duress token for identity A could collide with the normal
+ * per-member token for identity B, causing false duress detection.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier for the duress signaller.
+ * @param counter - Time-based or usage counter (uint32).
+ * @param encoding - Output encoding format (default: single word from en-v1 wordlist).
+ * @param maxTolerance - Counter tolerance window used by verifiers; must match their value.
+ * @param identities - All group member pubkeys for cross-member collision avoidance.
+ * @returns Encoded duress token string guaranteed distinct from all normal tokens in the window.
+ * @throws {RangeError} If maxTolerance is negative, exceeds MAX_TOLERANCE, or is not an integer.
+ * @throws {Error} If collision avoidance fails after 255 retries.
+ */
+export function deriveDuressToken(secret, context, identity, counter, encoding = DEFAULT_ENCODING, maxTolerance, identities) {
+    if (!Number.isInteger(maxTolerance) || maxTolerance < 0) {
+        throw new RangeError('maxTolerance must be a non-negative integer');
+    }
+    if (maxTolerance > MAX_TOLERANCE) {
+        throw new RangeError(`maxTolerance must be <= ${MAX_TOLERANCE}, got ${maxTolerance}`);
+    }
+    // Collect normal tokens within ±(2 × maxTolerance) for cross-counter collision avoidance.
+    // The 2× window accounts for worst-case counter drift between deriver and verifier.
+    const forbidden = new Set();
+    const window = 2 * maxTolerance;
+    const lo = Math.max(0, counter - window);
+    const hi = Math.min(0xFFFFFFFF, counter + window);
+    for (let c = lo; c <= hi; c++) {
+        // Group-wide (anonymous) token
+        forbidden.add(deriveToken(secret, context, c, encoding));
+        // Per-member tokens for all known identities
+        if (identities) {
+            for (const id of identities) {
+                forbidden.add(deriveToken(secret, context, c, encoding, id));
+            }
+        }
+    }
+    const key = normaliseSecret(secret);
+    const baseData = concatBytes(utf8(context + ':duress'), new Uint8Array([0x00]), utf8(identity), counterBe32(counter));
+    let bytes = hmacSha256(key, baseData);
+    let token = encodeToken(bytes, encoding);
+    // Collision avoidance: deterministic multi-suffix retry
+    let suffix = 1;
+    while (forbidden.has(token) && suffix <= 255) {
+        bytes = hmacSha256(key, concatBytes(baseData, new Uint8Array([suffix])));
+        token = encodeToken(bytes, encoding);
+        suffix++;
+    }
+    if (forbidden.has(token)) {
+        throw new Error('Duress token collision unresolvable after 255 retries');
+    }
+    return token;
+}
+/**
+ * CANARY-DURESS: Verify a spoken/entered token against a group.
+ *
+ * Checks in priority order (exact-counter-first):
+ * 1. Normal verification token at exact counter → 'valid'
+ * 2. ALL identities' duress tokens (within tolerance window) → 'duress' with all matches
+ * 3. Normal verification token at remaining tolerance window → 'valid'
+ * 4. No match → 'invalid'
+ *
+ * Exact-counter normal is checked first because same-counter collision avoidance
+ * guarantees no ambiguity. Duress across the full window is checked next so that
+ * duress at the exact counter is never masked by normal at an adjacent counter.
+ *
+ * Per CANARY-DURESS: the verifier MUST check all identities and collect all matches.
+ * The verifier MUST NOT short-circuit after the first duress match.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array).
+ * @param context - Context string for domain separation.
+ * @param counter - Current time-based counter.
+ * @param input - The spoken/entered token to verify.
+ * @param identities - Array of member pubkeys (max 100).
+ * @param options - Optional encoding and tolerance settings.
+ * @returns `{ status: 'valid' | 'duress' | 'invalid', identities?: string[] }`.
+ * @throws {RangeError} If tolerance exceeds MAX_TOLERANCE or identities exceeds 100.
+ *
+ * @example
+ * ```ts
+ * const result = verifyToken(seed, 'canary:group', counter, 'falcon', [alice, bob])
+ * if (result.status === 'duress') alert(`Duress from: ${result.identities}`)
+ * ```
+ */
+export function verifyToken(secret, context, counter, input, identities, options) {
+    const encoding = options?.encoding ?? DEFAULT_ENCODING;
+    const tolerance = options?.tolerance ?? 0;
+    if (!Number.isInteger(tolerance) || tolerance < 0) {
+        throw new RangeError('Tolerance must be a non-negative integer');
+    }
+    if (tolerance > MAX_TOLERANCE) {
+        throw new RangeError(`Tolerance must be <= ${MAX_TOLERANCE}, got ${tolerance}`);
+    }
+    if (identities.length > MAX_MEMBERS) {
+        throw new RangeError(`identities array must not exceed ${MAX_MEMBERS} entries, got ${identities.length}`);
+    }
+    const normalised = input.toLowerCase().trim().replace(/\s+/g, ' ');
+    // All branches are computed regardless of which matches first to reduce
+    // timing side-channels. Note: deriveDuressToken has variable cost due to
+    // its collision-avoidance retry loop, so timing protection is partial.
+    // For high-assurance use, pair with rate limiting.
+    const lo = Math.max(0, counter - tolerance);
+    const hi = Math.min(0xFFFFFFFF, counter + tolerance);
+    // 1. Check per-member tokens at exact counter (each member has a unique word)
+    let exactMember = null;
+    for (const identity of identities) {
+        if (timingSafeStringEqual(normalised, deriveToken(secret, context, counter, encoding, identity))) {
+            exactMember = identity;
+        }
+    }
+    // 2. Check duress tokens for ALL identities across entire tolerance window
+    const duressMatches = [];
+    for (const identity of identities) {
+        let found = false;
+        for (let c = lo; c <= hi; c++) {
+            if (timingSafeStringEqual(normalised, deriveDuressToken(secret, context, identity, c, encoding, tolerance, identities))) {
+                found = true;
+            }
+        }
+        if (found)
+            duressMatches.push(identity);
+    }
+    // 3. Check per-member tokens at remaining tolerance window (non-exact counters)
+    let toleranceMember = null;
+    for (const identity of identities) {
+        for (let c = lo; c <= hi; c++) {
+            if (c === counter)
+                continue; // already checked in step 1
+            if (timingSafeStringEqual(normalised, deriveToken(secret, context, c, encoding, identity))) {
+                toleranceMember = identity;
+            }
+        }
+    }
+    // 4. Also check group-wide token (backwards compat for anonymous verification)
+    let groupMatch = false;
+    for (let c = lo; c <= hi; c++) {
+        if (timingSafeStringEqual(normalised, deriveToken(secret, context, c, encoding))) {
+            groupMatch = true;
+        }
+    }
+    // Priority: duress always wins unless there's an exact-counter exact-member match
+    // (collision avoidance guarantees no ambiguity at the exact counter).
+    // An exact per-member match that also matches duress → duress wins (safety-first).
+    if (duressMatches.length > 0)
+        return { status: 'duress', identities: duressMatches };
+    if (exactMember)
+        return { status: 'valid', identities: [exactMember] };
+    if (toleranceMember)
+        return { status: 'valid', identities: [toleranceMember] };
+    if (groupMatch)
+        return { status: 'valid' };
+    return { status: 'invalid' };
+}
+/**
+ * CANARY-DURESS: Derive a liveness heartbeat token for dead man's switch.
+ *
+ * Algorithm: HMAC-SHA256(secret, utf8(context + ":alive") || 0x00 || utf8(identity) || counter_be32)
+ *
+ * The null-byte separator between the context suffix and identity prevents concatenation
+ * ambiguity.
+ *
+ * The liveness token proves both identity and knowledge of the secret.
+ * If heartbeats stop arriving, the implementation triggers its DMS response.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array, minimum 16 bytes).
+ * @param context - Context string for domain separation (e.g. `'canary:group'`).
+ * @param identity - Member pubkey or identifier of the heartbeat sender.
+ * @param counter - Time-based or usage counter (uint32).
+ * @returns Raw 32-byte HMAC-SHA256 digest for the liveness heartbeat.
+ * @throws {RangeError} If secret is too short or counter is out of range.
+ */
+export function deriveLivenessToken(secret, context, identity, counter) {
+    const key = normaliseSecret(secret);
+    const data = concatBytes(utf8(context + ':alive'), new Uint8Array([0x00]), utf8(identity), counterBe32(counter));
+    return hmacSha256(key, data);
+}
+/**
+ * Derive a directional pair: two distinct tokens from the same secret,
+ * one per role. Each token uses context = `${namespace}\0${role}`.
+ *
+ * Neither token can be derived from the other without the shared secret.
+ * This prevents the "echo problem" where the second speaker could parrot
+ * the first.
+ *
+ * @param secret - Shared secret (hex string or Uint8Array).
+ * @param namespace - Namespace prefix (e.g. `'aviva'`, `'dispatch'`).
+ * @param roles - Exactly two role names (e.g. `['caller', 'agent']`).
+ * @param counter - Current counter value.
+ * @param encoding - Output encoding format (default: single word).
+ * @returns Object keyed by role name, each value is the role's token string.
+ * @throws {Error} If roles does not contain exactly 2 entries, or roles are identical.
+ */
+export function deriveDirectionalPair(secret, namespace, roles, counter, encoding = DEFAULT_ENCODING) {
+    if (!namespace) {
+        throw new Error('namespace must be a non-empty string');
+    }
+    if (namespace.includes('\0')) {
+        throw new Error('namespace must not contain null bytes');
+    }
+    if (!roles[0] || !roles[1]) {
+        throw new Error('Both roles must be non-empty strings');
+    }
+    if (roles[0].includes('\0') || roles[1].includes('\0')) {
+        throw new Error('Roles must not contain null bytes');
+    }
+    if (roles[0] === roles[1]) {
+        throw new Error(`Roles must be distinct, got ["${roles[0]}", "${roles[1]}"]`);
+    }
+    // Use null-byte separator to prevent concatenation ambiguity
+    // (e.g. namespace "a:b" + role "c" vs namespace "a" + role "b:c")
+    return {
+        [roles[0]]: deriveToken(secret, `${namespace}\0${roles[0]}`, counter, encoding),
+        [roles[1]]: deriveToken(secret, `${namespace}\0${roles[1]}`, counter, encoding),
+    };
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/dist/verify.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Group-level word verification — thin wrapper around the universal token API.
+ *
+ * Maps verifyToken results to group-specific statuses:
+ * - 'verified' = exact counter match
+ * - 'duress'   = duress token detected (with member pubkeys)
+ * - 'stale'    = valid token from an adjacent counter (out of sync)
+ * - 'failed'   = no match
+ */
+export type VerifyStatus = 'verified' | 'duress' | 'stale' | 'failed';
+export interface VerifyResult {
+    /** The outcome of the verification check. */
+    status: VerifyStatus;
+    /** Pubkeys of members whose duress word matched (only when status = 'duress'). */
+    members?: string[];
+}
+/**
+ * Verify a spoken word against the group's current state.
+ *
+ * Checks in order:
+ * 1. Current verification word → verified
+ * 2. ALL members' duress words within tolerance window → duress (with all matching members)
+ * 3. Adjacent verification word within tolerance → stale (out of sync)
+ * 4. None matched → failed
+ *
+ * Per CANARY-DURESS: the verifier MUST check all identities and collect all matches.
+ * The verifier MUST NOT short-circuit after the first duress match.
+ *
+ * @param spokenWord - The word or phrase spoken/entered by the user (case-insensitive, trimmed).
+ * @param seedHex - Group seed as a hex string.
+ * @param memberPubkeys - Array of member pubkeys for per-member and duress checking.
+ * @param counter - Current effective counter for the group.
+ * @param wordCount - Number of words in the token (1, 2, or 3; default: 1).
+ * @param tolerance - Counter tolerance window: accept tokens within ±tolerance (default: 1).
+ * @returns `{ status: 'verified' | 'duress' | 'stale' | 'failed', members?: string[] }`.
+ * @throws {RangeError} If tolerance exceeds MAX_TOLERANCE or memberPubkeys exceeds 100.
+ *
+ * @example
+ * ```ts
+ * const result = verifyWord('falcon', seedHex, [alicePubkey, bobPubkey], counter)
+ * if (result.status === 'duress') alert(`Duress from: ${result.members}`)
+ * ```
+ */
+export declare function verifyWord(spokenWord: string, seedHex: string, memberPubkeys: string[], counter: number, wordCount?: 1 | 2 | 3, tolerance?: number): VerifyResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAErE,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,MAAM,EAAE,YAAY,CAAA;IACpB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,CAAC,GAAG,CAAC,GAAG,CAAK,EACxB,SAAS,GAAE,MAAU,GACpB,YAAY,CAkBd"}

package/dist/verify.js

@@ -0,0 +1,59 @@
+/**
+ * Group-level word verification — thin wrapper around the universal token API.
+ *
+ * Maps verifyToken results to group-specific statuses:
+ * - 'verified' = exact counter match
+ * - 'duress'   = duress token detected (with member pubkeys)
+ * - 'stale'    = valid token from an adjacent counter (out of sync)
+ * - 'failed'   = no match
+ */
+import { verifyToken, deriveToken } from './token.js';
+import { GROUP_CONTEXT } from './derive.js';
+import { timingSafeStringEqual } from './crypto.js';
+/**
+ * Verify a spoken word against the group's current state.
+ *
+ * Checks in order:
+ * 1. Current verification word → verified
+ * 2. ALL members' duress words within tolerance window → duress (with all matching members)
+ * 3. Adjacent verification word within tolerance → stale (out of sync)
+ * 4. None matched → failed
+ *
+ * Per CANARY-DURESS: the verifier MUST check all identities and collect all matches.
+ * The verifier MUST NOT short-circuit after the first duress match.
+ *
+ * @param spokenWord - The word or phrase spoken/entered by the user (case-insensitive, trimmed).
+ * @param seedHex - Group seed as a hex string.
+ * @param memberPubkeys - Array of member pubkeys for per-member and duress checking.
+ * @param counter - Current effective counter for the group.
+ * @param wordCount - Number of words in the token (1, 2, or 3; default: 1).
+ * @param tolerance - Counter tolerance window: accept tokens within ±tolerance (default: 1).
+ * @returns `{ status: 'verified' | 'duress' | 'stale' | 'failed', members?: string[] }`.
+ * @throws {RangeError} If tolerance exceeds MAX_TOLERANCE or memberPubkeys exceeds 100.
+ *
+ * @example
+ * ```ts
+ * const result = verifyWord('falcon', seedHex, [alicePubkey, bobPubkey], counter)
+ * if (result.status === 'duress') alert(`Duress from: ${result.members}`)
+ * ```
+ */
+export function verifyWord(spokenWord, seedHex, memberPubkeys, counter, wordCount = 1, tolerance = 1) {
+    const encodingOpt = wordCount === 1
+        ? undefined
+        : { format: 'words', count: wordCount };
+    const result = verifyToken(seedHex, GROUP_CONTEXT, counter, spokenWord, memberPubkeys, {
+        encoding: encodingOpt,
+        tolerance,
+    });
+    if (result.status === 'invalid')
+        return { status: 'failed' };
+    if (result.status === 'duress')
+        return { status: 'duress', members: result.identities };
+    // result.status === 'valid' — distinguish exact from stale
+    const normalised = spokenWord.toLowerCase().trim().replace(/\s+/g, ' ');
+    const exact = deriveToken(seedHex, GROUP_CONTEXT, counter, encodingOpt);
+    if (timingSafeStringEqual(normalised, exact))
+        return { status: 'verified' };
+    return { status: 'stale' };
+}
+//# sourceMappingURL=verify.js.map