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