canary-kit 0.9.0

package/dist/index.js

@@ -0,0 +1,12 @@
+// src/index.ts
+export { WORDLIST, WORDLIST_SIZE, getWord, indexOf, } from './wordlist.js';
+export { getCounter, counterToBytes, counterFromEventId, DEFAULT_ROTATION_INTERVAL, MAX_COUNTER_OFFSET, } from './counter.js';
+export { GROUP_CONTEXT, deriveVerificationWord, deriveVerificationPhrase, deriveDuressWord, deriveDuressPhrase, deriveCurrentWord, } from './derive.js';
+export { verifyWord, } from './verify.js';
+export { createGroup, getCurrentWord, getCurrentDuressWord, advanceCounter, reseed, addMember, removeMember, removeMemberAndReseed, syncCounter, dissolveGroup, } from './group.js';
+export { PRESETS, } from './presets.js';
+export { deriveBeaconKey, deriveDuressKey, encryptBeacon, decryptBeacon, buildDuressAlert, encryptDuressAlert, decryptDuressAlert, } from './beacon.js';
+// --- CANARY Protocol (universal API) ---
+export { MAX_TOLERANCE, deriveTokenBytes, deriveToken, deriveDuressTokenBytes, deriveDuressToken, verifyToken, deriveLivenessToken, } from './token.js';
+export { encodeAsWords, encodeAsPin, encodeAsHex, encodeToken, DEFAULT_ENCODING, } from './encoding.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAe;AACf,OAAO,EACL,QAAQ,EACR,aAAa,EACb,OAAO,EACP,OAAO,GACR,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,UAAU,GAGX,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,MAAM,EACN,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,aAAa,GAGd,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,OAAO,GAGR,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAInB,MAAM,aAAa,CAAA;AAEpB,0CAA0C;AAC1C,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,GAGpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,WAAW,EAEX,gBAAgB,GACjB,MAAM,eAAe,CAAA"}

package/dist/nostr.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Canary Nostr event kinds (NIP-CANARY).
+ *
+ * - group + memberUpdate: parameterised replaceable (30000–39999)
+ * - seedDistribution, reseed, wordUsed: ephemeral (20000–29999)
+ * - beacon: ephemeral (20000–29999)
+ */
+export declare const KINDS: {
+    readonly group: 38800;
+    readonly seedDistribution: 28800;
+    readonly memberUpdate: 38801;
+    readonly reseed: 28801;
+    readonly wordUsed: 28802;
+    readonly beacon: 20800;
+};
+/** Unsigned Nostr event (consumer signs with their own library). */
+export interface UnsignedEvent {
+    kind: number;
+    content: string;
+    tags: string[][];
+    created_at: number;
+}
+export interface GroupEventParams {
+    groupId: string;
+    name: string;
+    members: string[];
+    rotationInterval: number;
+    wordCount: 1 | 2 | 3;
+    wordlist: string;
+    encryptedContent: string;
+    expiration?: number;
+}
+/**
+ * Build an unsigned kind 38800 group definition event.
+ *
+ * @param params - Group event parameters including groupId, name, members, and encrypted content.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupId/name are invalid, member pubkeys are malformed, rotationInterval is non-positive, or wordCount is not 1/2/3.
+ */
+export declare function buildGroupEvent(params: GroupEventParams): UnsignedEvent;
+export interface SeedDistributionParams {
+    recipientPubkey: string;
+    groupEventId: string;
+    encryptedContent: string;
+}
+/**
+ * Build an unsigned kind 28800 seed distribution event.
+ *
+ * @param params - Seed distribution parameters including recipient pubkey, group event ID, and encrypted seed.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If recipientPubkey or groupEventId are not valid 64-character hex strings.
+ */
+export declare function buildSeedDistributionEvent(params: SeedDistributionParams): UnsignedEvent;
+export interface MemberUpdateParams {
+    groupId: string;
+    action: 'add' | 'remove';
+    memberPubkey: string;
+    reseed: boolean;
+    encryptedContent: string;
+}
+/**
+ * Build an unsigned kind 38801 member update event (add or remove).
+ *
+ * @param params - Member update parameters including groupId, action ('add' | 'remove'), member pubkey, and reseed flag.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If action is not 'add' or 'remove', or pubkey/groupId are invalid.
+ */
+export declare function buildMemberUpdateEvent(params: MemberUpdateParams): UnsignedEvent;
+export interface ReseedParams {
+    groupEventId: string;
+    reason: 'member_removed' | 'compromise' | 'scheduled' | 'duress';
+    encryptedContent: string;
+}
+/**
+ * Build an unsigned kind 28801 reseed notification event.
+ *
+ * @param params - Reseed parameters including group event ID, reason, and encrypted new seed.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupEventId is not a valid 64-character hex string or reason is invalid.
+ */
+export declare function buildReseedEvent(params: ReseedParams): UnsignedEvent;
+export interface WordUsedParams {
+    groupEventId: string;
+    encryptedContent: string;
+}
+/**
+ * Build an unsigned kind 28802 word-used (burn-after-use) event.
+ *
+ * @param params - Word-used parameters including group event ID and encrypted content.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupEventId is not a valid 64-character hex string.
+ */
+export declare function buildWordUsedEvent(params: WordUsedParams): UnsignedEvent;
+export interface BeaconEventParams {
+    groupId: string;
+    encryptedContent: string;
+    expiration?: number;
+}
+/** Plaintext payload for kind 28800 (seed distribution). */
+export interface SeedDistributionPayload {
+    seed: string;
+    /** Allows re-seeding mid-window without waiting for the next natural time rotation. */
+    counter_offset: number;
+    /** The group's d-tag value (group identifier). */
+    group_d: string;
+}
+/** Plaintext payload for kind 38800 encrypted content (group configuration). */
+export interface GroupEventPayload {
+    description: string;
+    policies: {
+        invite_by: 'creator' | 'any_member';
+        reseed_by: 'creator' | 'any_admin';
+    };
+}
+/** Plaintext payload for kind 28801 (reseed notification). */
+export interface ReseedPayload {
+    seed: string;
+    reason: 'member_removed' | 'compromise' | 'scheduled' | 'duress';
+}
+/** Plaintext payload for kind 28802 (word used / burn-after-use). */
+export interface WordUsedPayload {
+    new_counter: number;
+    used_by: string;
+    duress: boolean;
+}
+/**
+ * Build an unsigned kind 20800 beacon event.
+ *
+ * @param params - Beacon event parameters including groupId, encrypted content, and optional expiration.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupId is invalid or expiration is not a non-negative integer.
+ */
+export declare function buildBeaconEvent(params: BeaconEventParams): UnsignedEvent;
+//# sourceMappingURL=nostr.d.ts.map

package/dist/nostr.d.ts.map

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

package/dist/nostr.js

@@ -0,0 +1,175 @@
+/**
+ * Canary Nostr event kinds (NIP-CANARY).
+ *
+ * - group + memberUpdate: parameterised replaceable (30000–39999)
+ * - seedDistribution, reseed, wordUsed: ephemeral (20000–29999)
+ * - beacon: ephemeral (20000–29999)
+ */
+export const KINDS = {
+    group: 38_800,
+    seedDistribution: 28_800,
+    memberUpdate: 38_801,
+    reseed: 28_801,
+    wordUsed: 28_802,
+    beacon: 20_800,
+};
+function now() {
+    return Math.floor(Date.now() / 1000);
+}
+const HEX_64_RE = /^[0-9a-f]{64}$/;
+const MAX_TAG_LENGTH = 256;
+function validatePubkey(pubkey, label) {
+    if (!HEX_64_RE.test(pubkey)) {
+        throw new Error(`Invalid ${label}: expected 64 lowercase hex characters, got ${pubkey.length} chars`);
+    }
+}
+function validateEventId(eventId, label) {
+    if (!HEX_64_RE.test(eventId)) {
+        throw new Error(`Invalid ${label}: expected 64 lowercase hex characters, got ${eventId.length} chars`);
+    }
+}
+function validateTagString(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid ${label}: must be a non-empty string`);
+    }
+    if (value.length > MAX_TAG_LENGTH) {
+        throw new Error(`Invalid ${label}: exceeds maximum length of ${MAX_TAG_LENGTH} characters`);
+    }
+}
+/**
+ * Build an unsigned kind 38800 group definition event.
+ *
+ * @param params - Group event parameters including groupId, name, members, and encrypted content.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupId/name are invalid, member pubkeys are malformed, rotationInterval is non-positive, or wordCount is not 1/2/3.
+ */
+export function buildGroupEvent(params) {
+    validateTagString(params.groupId, 'groupId');
+    validateTagString(params.name, 'name');
+    for (const m of params.members)
+        validatePubkey(m, 'member pubkey');
+    if (!Number.isInteger(params.rotationInterval) || params.rotationInterval <= 0) {
+        throw new Error(`Invalid rotationInterval: must be a positive integer, got ${params.rotationInterval}`);
+    }
+    if (params.wordCount !== 1 && params.wordCount !== 2 && params.wordCount !== 3) {
+        throw new Error(`Invalid wordCount: must be 1, 2, or 3, got ${params.wordCount}`);
+    }
+    const tags = [
+        ['d', params.groupId],
+        ['name', params.name],
+        ...params.members.map((m) => ['p', m]),
+        ['rotation', String(params.rotationInterval)],
+        ['words', String(params.wordCount)],
+        ['wordlist', params.wordlist],
+    ];
+    if (params.expiration !== undefined) {
+        if (!Number.isInteger(params.expiration) || params.expiration < 0) {
+            throw new Error('expiration must be a non-negative integer');
+        }
+        tags.push(['expiration', String(params.expiration)]);
+    }
+    return { kind: KINDS.group, content: params.encryptedContent, tags, created_at: now() };
+}
+/**
+ * Build an unsigned kind 28800 seed distribution event.
+ *
+ * @param params - Seed distribution parameters including recipient pubkey, group event ID, and encrypted seed.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If recipientPubkey or groupEventId are not valid 64-character hex strings.
+ */
+export function buildSeedDistributionEvent(params) {
+    validatePubkey(params.recipientPubkey, 'recipientPubkey');
+    validateEventId(params.groupEventId, 'groupEventId');
+    return {
+        kind: KINDS.seedDistribution,
+        content: params.encryptedContent,
+        tags: [
+            ['p', params.recipientPubkey],
+            ['e', params.groupEventId],
+        ],
+        created_at: now(),
+    };
+}
+/**
+ * Build an unsigned kind 38801 member update event (add or remove).
+ *
+ * @param params - Member update parameters including groupId, action ('add' | 'remove'), member pubkey, and reseed flag.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If action is not 'add' or 'remove', or pubkey/groupId are invalid.
+ */
+export function buildMemberUpdateEvent(params) {
+    if (params.action !== 'add' && params.action !== 'remove') {
+        throw new Error(`Invalid action: must be 'add' or 'remove', got '${params.action}'`);
+    }
+    validatePubkey(params.memberPubkey, 'memberPubkey');
+    validateTagString(params.groupId, 'groupId');
+    return {
+        kind: KINDS.memberUpdate,
+        content: params.encryptedContent,
+        tags: [
+            ['d', params.groupId],
+            ['action', params.action],
+            ['p', params.memberPubkey],
+            ['reseed', String(params.reseed)],
+        ],
+        created_at: now(),
+    };
+}
+const VALID_RESEED_REASONS = new Set(['member_removed', 'compromise', 'scheduled', 'duress']);
+/**
+ * Build an unsigned kind 28801 reseed notification event.
+ *
+ * @param params - Reseed parameters including group event ID, reason, and encrypted new seed.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupEventId is not a valid 64-character hex string or reason is invalid.
+ */
+export function buildReseedEvent(params) {
+    validateEventId(params.groupEventId, 'groupEventId');
+    if (!VALID_RESEED_REASONS.has(params.reason)) {
+        throw new Error(`Invalid reason: must be one of ${[...VALID_RESEED_REASONS].join(', ')}, got '${params.reason}'`);
+    }
+    return {
+        kind: KINDS.reseed,
+        content: params.encryptedContent,
+        tags: [
+            ['e', params.groupEventId],
+            ['reason', params.reason],
+        ],
+        created_at: now(),
+    };
+}
+/**
+ * Build an unsigned kind 28802 word-used (burn-after-use) event.
+ *
+ * @param params - Word-used parameters including group event ID and encrypted content.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupEventId is not a valid 64-character hex string.
+ */
+export function buildWordUsedEvent(params) {
+    validateEventId(params.groupEventId, 'groupEventId');
+    return {
+        kind: KINDS.wordUsed,
+        content: params.encryptedContent,
+        tags: [['e', params.groupEventId]],
+        created_at: now(),
+    };
+}
+/**
+ * Build an unsigned kind 20800 beacon event.
+ *
+ * @param params - Beacon event parameters including groupId, encrypted content, and optional expiration.
+ * @returns An {@link UnsignedEvent} ready to be signed and published.
+ * @throws {Error} If groupId is invalid or expiration is not a non-negative integer.
+ */
+export function buildBeaconEvent(params) {
+    validateTagString(params.groupId, 'groupId');
+    const tags = [['h', params.groupId]];
+    if (params.expiration !== undefined) {
+        if (!Number.isInteger(params.expiration) || params.expiration < 0) {
+            throw new Error('expiration must be a non-negative integer');
+        }
+        tags.push(['expiration', String(params.expiration)]);
+    }
+    return { kind: KINDS.beacon, content: params.encryptedContent, tags, created_at: now() };
+}
+//# sourceMappingURL=nostr.js.map

package/dist/nostr.js.map

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

package/dist/presets.d.ts

@@ -0,0 +1,26 @@
+/** Named threat-profile preset identifier. */
+export type PresetName = 'family' | 'field-ops' | 'enterprise' | 'event';
+/**
+ * A threat-profile preset — pre-configured group settings optimised for
+ * a specific risk level and use case.
+ */
+export interface GroupPreset {
+    /** Words per verification challenge. */
+    wordCount: 1 | 2 | 3;
+    /** Rotation interval in seconds. Must be a positive integer. */
+    rotationInterval: number;
+    /** Human-readable description of the preset's trade-offs. */
+    description: string;
+}
+/**
+ * Built-in threat-profile presets.
+ *
+ * | Preset       | Words | Rotation | Use case                           |
+ * |--------------|-------|----------|------------------------------------|
+ * | `family`     | 1     | 7 days   | Casual family/friend verification  |
+ * | `field-ops`  | 2     | 24 hours | Journalism, activism, field work   |
+ * | `enterprise` | 2     | 48 hours | Corporate incident response        |
+ * | `event`      | 1     | 4 hours  | Conferences, festivals, meetups    |
+ */
+export declare const PRESETS: Readonly<Record<PresetName, Readonly<GroupPreset>>>;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAEA,8CAA8C;AAC9C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAA;AAExE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACpB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CA8BtE,CAAA"}

package/dist/presets.js

@@ -0,0 +1,39 @@
+import { DEFAULT_ROTATION_INTERVAL } from './counter.js';
+/**
+ * Built-in threat-profile presets.
+ *
+ * | Preset       | Words | Rotation | Use case                           |
+ * |--------------|-------|----------|------------------------------------|
+ * | `family`     | 1     | 7 days   | Casual family/friend verification  |
+ * | `field-ops`  | 2     | 24 hours | Journalism, activism, field work   |
+ * | `enterprise` | 2     | 48 hours | Corporate incident response        |
+ * | `event`      | 1     | 4 hours  | Conferences, festivals, meetups    |
+ */
+export const PRESETS = Object.freeze({
+    family: Object.freeze({
+        wordCount: 1,
+        rotationInterval: DEFAULT_ROTATION_INTERVAL,
+        description: 'Casual verification for family and friends. Single word, weekly rotation. ' +
+            'Adequate for live voice/video calls where the attacker gets one attempt. ' +
+            'NOT suitable for text-based verification — 11 bits of entropy is trivially brute-forceable without rate limiting.',
+    }),
+    'field-ops': Object.freeze({
+        wordCount: 2,
+        rotationInterval: 86_400,
+        description: 'High-security preset for journalism, activism, and field operations. ' +
+            'Two-word phrases (~22 bits) with daily rotation. Use burn-after-use for maximum protection.',
+    }),
+    enterprise: Object.freeze({
+        wordCount: 2,
+        rotationInterval: 172_800,
+        description: 'Enterprise incident response. Two-word phrases with 48-hour rotation. ' +
+            'Balances security with operational convenience for larger teams.',
+    }),
+    event: Object.freeze({
+        wordCount: 1,
+        rotationInterval: 14_400,
+        description: 'Temporary groups for conferences, festivals, and meetups. ' +
+            'Single word with 4-hour rotation. Fast setup, easy to share at the door.',
+    }),
+});
+//# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAkBxD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,OAAO,GAAwD,MAAM,CAAC,MAAM,CAAC;IACxF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC;QACZ,gBAAgB,EAAE,yBAAyB;QAC3C,WAAW,EACT,4EAA4E;YAC5E,2EAA2E;YAC3E,mHAAmH;KACtH,CAAC;IACF,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC;QACzB,SAAS,EAAE,CAAC;QACZ,gBAAgB,EAAE,MAAM;QACxB,WAAW,EACT,uEAAuE;YACvE,6FAA6F;KAChG,CAAC;IACF,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC;QACxB,SAAS,EAAE,CAAC;QACZ,gBAAgB,EAAE,OAAO;QACzB,WAAW,EACT,wEAAwE;YACxE,kEAAkE;KACrE,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACnB,SAAS,EAAE,CAAC;QACZ,gBAAgB,EAAE,MAAM;QACxB,WAAW,EACT,4DAA4D;YAC5D,0EAA0E;KAC7E,CAAC;CACH,CAAC,CAAA"}

package/dist/session.d.ts

@@ -0,0 +1,114 @@
+import { type TokenVerifyResult, type DirectionalPair } from './token.js';
+import type { TokenEncoding } from './encoding.js';
+/**
+ * Generate a cryptographically secure 256-bit seed.
+ * Uses the global `crypto.getRandomValues` (Web Crypto API).
+ *
+ * @returns A 32-byte Uint8Array containing cryptographically secure random bytes.
+ */
+export declare function generateSeed(): Uint8Array;
+/**
+ * Derive a seed deterministically from a master key and string components.
+ *
+ * Algorithm: HMAC-SHA256(masterKey, utf8(components[0]) || 0x00 || utf8(components[1]) || ...)
+ *
+ * Null-byte separators prevent concatenation ambiguity.
+ *
+ * @param masterKey - Master key (hex string or Uint8Array, minimum 16 bytes).
+ * @param components - One or more string components for domain separation.
+ * @returns A deterministic 32-byte seed derived via HMAC-SHA256.
+ * @throws {RangeError} If master key is shorter than 16 bytes.
+ */
+export declare function deriveSeed(masterKey: Uint8Array | string, ...components: string[]): Uint8Array;
+/** Named session preset identifier. */
+export type SessionPresetName = 'call' | 'handoff';
+/** A session preset — pre-configured settings for a specific use case. */
+export interface SessionPreset {
+    /** Words per token. */
+    wordCount: number;
+    /** Rotation interval in seconds (0 = fixed counter, single-use). */
+    rotationSeconds: number;
+    /** Counter tolerance window. */
+    tolerance: number;
+    /** Whether this is a directional (two-party) preset. */
+    directional: boolean;
+    /** Human-readable description. */
+    description: string;
+}
+/**
+ * Built-in session presets for directional verification.
+ *
+ * | Preset    | Words | Rotation   | Tolerance | Use case                     |
+ * |-----------|-------|------------|-----------|------------------------------|
+ * | `call`    | 1     | 30 seconds | 1         | Phone verification           |
+ * | `handoff` | 1     | single-use | 0         | Physical handoff (rideshare) |
+ */
+export declare const SESSION_PRESETS: Readonly<Record<SessionPresetName, Readonly<SessionPreset>>>;
+/** Configuration for creating a directional verification session. */
+export interface SessionConfig {
+    /** Shared secret (hex string or Uint8Array). */
+    secret: Uint8Array | string;
+    /** Namespace prefix for context strings (e.g. 'aviva', 'dispatch'). */
+    namespace: string;
+    /** The two roles in the session (e.g. ['caller', 'agent']). */
+    roles: [string, string];
+    /** Which role I am. */
+    myRole: string;
+    /** Rotation interval in seconds (default: 30). */
+    rotationSeconds?: number;
+    /** Token encoding (default: words, count from preset or 1). */
+    encoding?: TokenEncoding;
+    /** Counter tolerance window (default: from preset or 0). */
+    tolerance?: number;
+    /**
+     * Their identity string for duress detection (e.g. customer ID).
+     *
+     * **WARNING:** When omitted, duress detection is completely disabled —
+     * a duress token from the other party will return `'invalid'` instead of
+     * `'duress'`. If duress detection is safety-critical for your use case,
+     * always provide this field.
+     */
+    theirIdentity?: string;
+    /** Session preset (overrides rotationSeconds, tolerance, encoding). */
+    preset?: SessionPresetName;
+    /** Fixed counter for single-use / handoff mode (ignores time-based rotation). */
+    counter?: number;
+}
+/** A role-aware, time-managed session for two-party verification. */
+export interface Session {
+    /** Get the current counter (time-based or fixed). */
+    counter(nowSec?: number): number;
+    /** Get the token I speak to prove my identity. */
+    myToken(nowSec?: number): string;
+    /** Get the token I expect to hear from the other party. */
+    theirToken(nowSec?: number): string;
+    /** Verify a word spoken to me against the other party's context. */
+    verify(spoken: string, nowSec?: number): TokenVerifyResult;
+    /** Get both tokens at once, keyed by role name. */
+    pair(nowSec?: number): DirectionalPair;
+}
+/**
+ * Create a directional verification session.
+ *
+ * Wraps the low-level token API with role awareness, time management,
+ * and optional duress detection.
+ *
+ * @param config - Session configuration including secret, namespace, roles, and optional preset.
+ * @returns A {@link Session} object with `myToken()`, `theirToken()`, `verify()`, `counter()`, and `pair()` methods.
+ * @throws {Error} If namespace is empty or contains null bytes, roles are invalid, or myRole is not in roles.
+ *
+ * @example
+ * ```ts
+ * const session = createSession({
+ *   secret: sharedSeed,
+ *   namespace: 'aviva',
+ *   roles: ['caller', 'agent'],
+ *   myRole: 'agent',
+ *   preset: 'call',
+ * })
+ * session.myToken()     // word I speak
+ * session.theirToken()  // word I expect to hear
+ * ```
+ */
+export declare function createSession(config: SessionConfig): Session;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAIlD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAIzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,GAAG,UAAU,EAAE,MAAM,EAAE,GACtB,UAAU,CAWZ;AAED,uCAAuC;AACvC,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAA;AAElD,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,WAAW,EAAE,OAAO,CAAA;IACpB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,CAoBvF,CAAA;AAEF,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,MAAM,EAAE,UAAU,GAAG,MAAM,CAAA;IAC3B,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC,kDAAkD;IAClD,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC,2DAA2D;IAC3D,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACnC,oEAAoE;IACpE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAC1D,mDAAmD;IACnD,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CA0F5D"}