@sigil-security/core 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,546 @@
+/**
+ * CryptoProvider abstraction for all cryptographic operations.
+ *
+ * All crypto operations in sigil-core go through this interface —
+ * never call `crypto.subtle` directly from token/validation code.
+ *
+ * Default implementation: WebCryptoCryptoProvider (ships with core, zero deps).
+ * Extension point for KMS/HSM/Node native — documented, not built until needed.
+ */
+interface CryptoProvider {
+    /**
+     * Signs data with HMAC-SHA256.
+     * Returns the full 256-bit MAC (NO truncation).
+     */
+    sign(key: CryptoKey, data: Uint8Array): Promise<ArrayBuffer>;
+    /**
+     * Verifies an HMAC-SHA256 signature.
+     * MUST be constant-time (crypto.subtle.verify is inherently constant-time).
+     */
+    verify(key: CryptoKey, signature: ArrayBuffer, data: Uint8Array): Promise<boolean>;
+    /**
+     * Derives an HMAC signing key from a master secret using HKDF-SHA256.
+     *
+     * @param master - Master secret as raw bytes
+     * @param salt - HKDF salt string (e.g., "sigil-v1")
+     * @param info - HKDF info string with domain separation (e.g., "csrf-signing-key-1")
+     */
+    deriveKey(master: ArrayBuffer, salt: string, info: string): Promise<CryptoKey>;
+    /**
+     * Generates cryptographically secure random bytes.
+     * Uses crypto.getRandomValues (NOT Math.random).
+     */
+    randomBytes(length: number): Uint8Array;
+    /**
+     * Computes SHA-256 hash of the input data.
+     * Returns the full 256-bit (32-byte) digest.
+     */
+    hash(data: Uint8Array): Promise<ArrayBuffer>;
+}
+
+declare const TOKEN_BRAND: unique symbol;
+declare const ONESHOT_TOKEN_BRAND: unique symbol;
+/** Branded string type for regular CSRF tokens */
+type TokenString = string & {
+    readonly [TOKEN_BRAND]: 'SigilToken';
+};
+/** Branded string type for one-shot tokens */
+type OneShotTokenString = string & {
+    readonly [ONESHOT_TOKEN_BRAND]: 'SigilOneShotToken';
+};
+/** Key ID size in bytes (8-bit key identifier) */
+declare const KID_SIZE = 1;
+/** Nonce size in bytes (128-bit random) */
+declare const NONCE_SIZE = 16;
+/** Timestamp size in bytes (int64 big-endian) */
+declare const TIMESTAMP_SIZE = 8;
+/** Context hash size in bytes (SHA-256 output) */
+declare const CONTEXT_SIZE = 32;
+/** MAC size in bytes (HMAC-SHA256, full 256-bit, NO truncation) */
+declare const MAC_SIZE = 32;
+/** Action hash size in bytes (SHA-256 of action string) */
+declare const ACTION_SIZE = 32;
+/**
+ * Regular token raw size: kid(1) + nonce(16) + ts(8) + ctx(32) + mac(32) = 89 bytes FIXED
+ */
+declare const TOKEN_RAW_SIZE: number;
+/**
+ * One-shot token raw size: nonce(16) + ts(8) + action(32) + ctx(32) + mac(32) = 120 bytes FIXED
+ */
+declare const ONESHOT_RAW_SIZE: number;
+/** Regular token field offsets */
+declare const TOKEN_OFFSETS: {
+    /** kid starts at byte 0 */
+    readonly KID: 0;
+    /** nonce starts at byte 1 */
+    readonly NONCE: 1;
+    /** timestamp starts at byte 17 */
+    readonly TIMESTAMP: number;
+    /** context starts at byte 25 */
+    readonly CONTEXT: number;
+    /** mac starts at byte 57 */
+    readonly MAC: number;
+};
+/** One-shot token field offsets */
+declare const ONESHOT_OFFSETS: {
+    /** nonce starts at byte 0 */
+    readonly NONCE: 0;
+    /** timestamp starts at byte 16 */
+    readonly TIMESTAMP: 16;
+    /** action starts at byte 24 */
+    readonly ACTION: number;
+    /** context starts at byte 56 */
+    readonly CONTEXT: number;
+    /** mac starts at byte 88 */
+    readonly MAC: number;
+};
+/** Parsed regular token (extracted from wire format) */
+interface ParsedToken {
+    readonly kid: number;
+    readonly nonce: Uint8Array;
+    readonly timestamp: number;
+    readonly context: Uint8Array;
+    readonly mac: Uint8Array;
+}
+/** Parsed one-shot token (extracted from wire format) */
+interface ParsedOneShotToken {
+    readonly nonce: Uint8Array;
+    readonly timestamp: number;
+    readonly action: Uint8Array;
+    readonly context: Uint8Array;
+    readonly mac: Uint8Array;
+}
+/** Token validation result */
+type ValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/** Token generation result */
+type GenerationResult = {
+    readonly success: true;
+    readonly token: TokenString;
+    readonly expiresAt: number;
+} | {
+    readonly success: false;
+    readonly reason: string;
+};
+/** One-shot token generation result */
+type OneShotGenerationResult = {
+    readonly success: true;
+    readonly token: OneShotTokenString;
+    readonly expiresAt: number;
+} | {
+    readonly success: false;
+    readonly reason: string;
+};
+/** Default token TTL in milliseconds (20 minutes) */
+declare const DEFAULT_TOKEN_TTL_MS: number;
+/** Default grace window in milliseconds (60 seconds) */
+declare const DEFAULT_GRACE_WINDOW_MS: number;
+/** Default one-shot token TTL in milliseconds (5 minutes) */
+declare const DEFAULT_ONESHOT_TTL_MS: number;
+/** Default nonce cache max entries */
+declare const DEFAULT_NONCE_CACHE_MAX = 10000;
+/** Default nonce cache TTL in milliseconds (5 minutes) */
+declare const DEFAULT_NONCE_CACHE_TTL_MS: number;
+
+/**
+ * Domain separation for HKDF key derivation.
+ *
+ * Different token types derive keys from different HKDF paths,
+ * closing the cross-protocol attack surface:
+ *
+ * - `csrf`: Regular CSRF token signing keys
+ * - `oneshot`: One-shot token signing keys
+ * - `internal`: Internal/service-to-service signing keys
+ */
+type KeyDomain = 'csrf' | 'oneshot' | 'internal';
+/**
+ * Derives a signing key using HKDF-SHA256 with domain separation.
+ *
+ * Key derivation path:
+ * ```
+ * HKDF(master, salt="sigil-v1", info="{domain}-signing-key-{kid}")
+ * ```
+ *
+ * A key derived for one domain CANNOT validate tokens from another domain.
+ * This closes the cross-protocol attack surface.
+ *
+ * @param cryptoProvider - CryptoProvider for HKDF operations
+ * @param master - Master secret as raw bytes
+ * @param kid - Key identifier (8-bit)
+ * @param domain - Key domain for separation (csrf/oneshot/internal)
+ * @returns Derived HMAC-SHA256 CryptoKey
+ */
+declare function deriveSigningKey(cryptoProvider: CryptoProvider, master: ArrayBuffer, kid: number, domain: KeyDomain): Promise<CryptoKey>;
+
+/**
+ * A single key entry in the keyring.
+ */
+interface KeyEntry {
+    /** Key identifier (8-bit, embedded in token) */
+    readonly kid: number;
+    /** Derived HMAC-SHA256 CryptoKey */
+    readonly cryptoKey: CryptoKey;
+    /** Timestamp when this key was created */
+    readonly createdAt: number;
+}
+/**
+ * Keyring holds max 3 keys (active + 2 previous) per domain.
+ *
+ * - Token generation: ALWAYS uses the active key
+ * - Token validation: tries ALL keys in the keyring (match by kid from token)
+ * - Rotation: new key becomes active, oldest dropped if > MAX_KEYS
+ */
+interface Keyring {
+    /** All keys in the keyring, ordered newest-first */
+    readonly keys: readonly KeyEntry[];
+    /** The kid of the currently active key */
+    readonly activeKid: number;
+    /** The domain this keyring belongs to */
+    readonly domain: KeyDomain;
+}
+/**
+ * Creates a new keyring with an initial key.
+ *
+ * @param cryptoProvider - CryptoProvider for key derivation
+ * @param masterSecret - Master secret as raw bytes
+ * @param initialKid - Initial key identifier (8-bit)
+ * @param domain - Key domain for HKDF separation
+ * @returns A new Keyring with one key
+ */
+declare function createKeyring(cryptoProvider: CryptoProvider, masterSecret: ArrayBuffer, initialKid: number, domain: KeyDomain): Promise<Keyring>;
+/**
+ * Rotates the keyring: new key becomes active, oldest dropped if > MAX_KEYS.
+ *
+ * @param keyring - Current keyring to rotate
+ * @param cryptoProvider - CryptoProvider for key derivation
+ * @param masterSecret - Master secret as raw bytes
+ * @param newKid - New key identifier (must be unique in keyring)
+ * @returns Updated Keyring with the new active key
+ */
+declare function rotateKey(keyring: Keyring, cryptoProvider: CryptoProvider, masterSecret: ArrayBuffer, newKid: number): Promise<Keyring>;
+/**
+ * Resolves a key by kid from the keyring.
+ * Returns undefined if no matching key is found.
+ *
+ * Token validation tries ALL keys to support key rotation overlap.
+ */
+declare function resolveKey(keyring: Keyring, kid: number): KeyEntry | undefined;
+/**
+ * Returns the active key entry from the keyring.
+ * Token generation ALWAYS uses the active key.
+ */
+declare function getActiveKey(keyring: Keyring): KeyEntry | undefined;
+
+/**
+ * NonceCache interface for one-shot token replay detection.
+ *
+ * - In-memory LRU + TTL (custom implementation, no external dependency)
+ * - Atomic compare-and-swap for `markUsed` flag — prevents race conditions
+ * - Cache is an optimization, NOT a security guarantee — must fail-open if unavailable
+ * - NO external storage (Redis, DB) — in-memory only
+ */
+interface NonceCache {
+    /**
+     * Checks if a nonce exists in the cache (has been seen).
+     */
+    has(nonce: Uint8Array): boolean;
+    /**
+     * Atomic compare-and-swap: marks a nonce as used.
+     * Returns true if successfully marked (nonce was NOT previously used).
+     * Returns false if the nonce was already used (replay detected).
+     */
+    markUsed(nonce: Uint8Array): boolean;
+    /**
+     * Adds a nonce to the cache with a TTL.
+     * If the cache is at capacity, the oldest (LRU) entry is evicted.
+     */
+    add(nonce: Uint8Array, ttlMs: number): void;
+    /** Current number of entries in the cache */
+    readonly size: number;
+}
+/**
+ * Configuration for the nonce cache.
+ */
+interface NonceCacheConfig {
+    /** Maximum number of entries (default: 10,000) */
+    readonly maxEntries?: number;
+    /** Default TTL for entries in milliseconds (default: 5 minutes) */
+    readonly defaultTTLMs?: number;
+}
+/**
+ * Creates an in-memory LRU + TTL nonce cache.
+ *
+ * Design constraints:
+ * - Max 10k entries (~1MB memory at ~100 bytes per entry)
+ * - 5 minute TTL (matches one-shot token TTL)
+ * - LRU eviction when capacity is reached
+ * - Atomic CAS for markUsed (single-threaded JS = naturally atomic)
+ * - Non-distributed, non-persistent
+ *
+ * @param config - Optional cache configuration
+ * @returns NonceCache instance
+ */
+declare function createNonceCache(config?: NonceCacheConfig): NonceCache;
+
+/**
+ * Default CryptoProvider implementation using the WebCrypto API.
+ *
+ * - HMAC-SHA256 for sign/verify (full 256-bit, NO truncation)
+ * - HKDF-SHA256 for key derivation (RFC 5869)
+ * - crypto.getRandomValues for secure randomness
+ * - SHA-256 for hashing
+ *
+ * Zero external dependencies. Works in Node 18+, Bun, Deno, and Edge runtimes.
+ */
+declare class WebCryptoCryptoProvider implements CryptoProvider {
+    /**
+     * Signs data with HMAC-SHA256 using WebCrypto.
+     * Returns full 256-bit (32-byte) MAC, NO truncation.
+     */
+    sign(key: CryptoKey, data: Uint8Array): Promise<ArrayBuffer>;
+    /**
+     * Verifies an HMAC-SHA256 signature using WebCrypto.
+     * Inherently constant-time via crypto.subtle.verify.
+     */
+    verify(key: CryptoKey, signature: ArrayBuffer, data: Uint8Array): Promise<boolean>;
+    /**
+     * Derives an HMAC-SHA256 signing key from a master secret via HKDF-SHA256.
+     *
+     * HKDF (RFC 5869) with:
+     * - Hash: SHA-256
+     * - Salt: encoded string
+     * - Info: encoded string (includes domain separation)
+     * - Output: HMAC-SHA256 key, 256-bit, non-extractable
+     */
+    deriveKey(master: ArrayBuffer, salt: string, info: string): Promise<CryptoKey>;
+    /**
+     * Generates cryptographically secure random bytes via crypto.getRandomValues.
+     * NEVER uses Math.random.
+     */
+    randomBytes(length: number): Uint8Array;
+    /**
+     * Computes SHA-256 hash via WebCrypto.
+     * Returns full 256-bit (32-byte) digest.
+     */
+    hash(data: Uint8Array): Promise<ArrayBuffer>;
+}
+
+/**
+ * Generates a CSRF token.
+ *
+ * Steps:
+ * 1. Generate nonce: crypto.randomBytes(16)
+ * 2. Get current timestamp
+ * 3. Compute context (provided or SHA-256(0x00), ALWAYS 32 bytes)
+ * 4. Assemble payload: kid | nonce | ts | ctx
+ * 5. Sign: HMAC-SHA256(derived_key, payload)
+ * 6. Encode: base64url(kid | nonce | ts | ctx | mac)
+ *
+ * Token wire format: 89 bytes raw → base64url encoded
+ * ```
+ * [ kid:1 ][ nonce:16 ][ ts:8 ][ ctx:32 ][ mac:32 ]
+ * ```
+ *
+ * @param cryptoProvider - CryptoProvider for crypto operations
+ * @param key - Active KeyEntry from the keyring
+ * @param context - Optional 32-byte context binding hash
+ * @param ttlMs - Token TTL in milliseconds (default: 20 minutes)
+ * @param now - Current timestamp override for testing
+ */
+declare function generateToken(cryptoProvider: CryptoProvider, key: KeyEntry, context?: Uint8Array, ttlMs?: number, now?: number): Promise<GenerationResult>;
+/**
+ * Parses a token string into its constituent fields.
+ *
+ * Uses fixed offsets — no length oracle. Token must be exactly 89 bytes raw.
+ *
+ * Parse offsets:
+ * - kid @ 0 (1 byte)
+ * - nonce @ 1 (16 bytes)
+ * - ts @ 17 (8 bytes)
+ * - ctx @ 25 (32 bytes)
+ * - mac @ 57 (32 bytes)
+ *
+ * @returns ParsedToken or null if the token cannot be parsed
+ */
+declare function parseToken(tokenString: string): ParsedToken | null;
+/**
+ * Assembles the payload bytes from a parsed token for MAC verification.
+ * Returns: kid | nonce | ts | ctx
+ */
+declare function assemblePayload(parsed: ParsedToken): Uint8Array;
+/**
+ * Serializes token fields into a TokenString.
+ *
+ * @param kid - Key identifier (8-bit)
+ * @param nonce - 16-byte nonce
+ * @param ts - Timestamp as milliseconds
+ * @param ctx - 32-byte context hash
+ * @param mac - 32-byte MAC
+ */
+declare function serializeToken(kid: number, nonce: Uint8Array, ts: number, ctx: Uint8Array, mac: Uint8Array): TokenString;
+
+/**
+ * Validates a CSRF token using the Deterministic Failure Model.
+ *
+ * **CRITICAL (spec Section 5.8):**
+ * ALL validation steps MUST complete. No early return. Single exit point.
+ * Timing is deterministic regardless of which step fails.
+ *
+ * Steps:
+ * 1. Parse token (constant-time length check)
+ * 2. Resolve key from keyring (match by kid)
+ * 3. TTL check (within TTL or grace window)
+ * 4. HMAC verify (constant-time via crypto.subtle.verify) — runs even if earlier steps failed
+ * 5. Context check (if expected context provided)
+ *
+ * `reason` captures the LAST failure (internal logging only).
+ * Client receives ONLY `{ valid: false, reason: "CSRF validation failed" }`.
+ *
+ * @param cryptoProvider - CryptoProvider for HMAC verification
+ * @param keyring - Keyring to resolve keys from
+ * @param tokenString - The token string to validate
+ * @param expectedContext - Optional expected 32-byte context hash
+ * @param ttlMs - Token TTL in milliseconds (default: 20 minutes)
+ * @param graceWindowMs - Grace window in milliseconds (default: 60 seconds)
+ * @param now - Current timestamp override for testing
+ */
+declare function validateToken(cryptoProvider: CryptoProvider, keyring: Keyring, tokenString: string, expectedContext?: Uint8Array, ttlMs?: number, graceWindowMs?: number, now?: number): Promise<ValidationResult>;
+/**
+ * Validates token TTL against the current time.
+ *
+ * @param tokenTimestamp - Token creation timestamp (milliseconds)
+ * @param ttlMs - Token TTL in milliseconds
+ * @param graceWindowMs - Grace window after TTL (for in-flight requests)
+ * @param now - Current timestamp
+ * @returns Whether the token is within TTL or within the grace window
+ */
+declare function validateTTL(tokenTimestamp: number, ttlMs: number, graceWindowMs: number, now: number): {
+    withinTTL: boolean;
+    inGraceWindow: boolean;
+};
+/**
+ * Constant-time buffer comparison.
+ *
+ * Compares all bytes regardless of where a mismatch occurs.
+ * Length difference is also detected without early return.
+ *
+ * @param a - First buffer
+ * @param b - Second buffer
+ * @returns true if buffers are identical, false otherwise
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Computes context binding hash from string bindings.
+ *
+ * Context is ALWAYS 32 bytes (SHA-256 output) — eliminates length oracle.
+ *
+ * - If bindings provided: `SHA-256(len1 + binding1 + \0 + len2 + binding2 + \0 + ...)`
+ * - If no bindings: `SHA-256(0x00)` — zero-padded, NEVER empty
+ *
+ * Uses length-prefixed encoding with null-byte separators to prevent
+ * concatenation collisions: `ctx("ab","cd") !== ctx("a","bcd") !== ctx("abcd")`.
+ *
+ * @param cryptoProvider - CryptoProvider for hashing
+ * @param bindings - Strings to bind into context (e.g., sessionId, userId, origin)
+ * @returns 32-byte context hash
+ */
+declare function computeContext(cryptoProvider: CryptoProvider, ...bindings: string[]): Promise<Uint8Array>;
+/**
+ * Returns the empty context value: SHA-256(0x00).
+ *
+ * Used when no context binding is specified.
+ * Always returns exactly 32 bytes — never an empty buffer.
+ *
+ * @param cryptoProvider - CryptoProvider for hashing
+ * @returns 32-byte empty context hash
+ */
+declare function emptyContext(cryptoProvider: CryptoProvider): Promise<Uint8Array>;
+
+/**
+ * Computes the action binding hash: SHA-256(actionString).
+ *
+ * Example: SHA-256("POST:/api/account/delete") → 32 bytes.
+ * Token is bound to a specific action — cross-action replay is impossible.
+ */
+declare function computeAction(cryptoProvider: CryptoProvider, action: string): Promise<Uint8Array>;
+/**
+ * Generates a one-shot token.
+ *
+ * One-shot tokens are:
+ * - Bound to a specific action (e.g., "POST:/api/account/delete")
+ * - Used exactly once (replay protection via nonce cache)
+ * - Signed with a domain-separated key (oneshot HKDF path)
+ *
+ * Wire format: 120 bytes raw → base64url encoded
+ * ```
+ * [ nonce:16 ][ ts:8 ][ action:32 ][ ctx:32 ][ mac:32 ]
+ * ```
+ *
+ * @param cryptoProvider - CryptoProvider for crypto operations
+ * @param key - KeyEntry derived with 'oneshot' domain
+ * @param action - Action string to bind (e.g., "POST:/api/account/delete")
+ * @param context - Optional 32-byte context binding hash
+ * @param ttlMs - Token TTL in milliseconds (default: 5 minutes)
+ * @param now - Current timestamp override for testing
+ */
+declare function generateOneShotToken(cryptoProvider: CryptoProvider, key: KeyEntry, action: string, context?: Uint8Array, ttlMs?: number, now?: number): Promise<OneShotGenerationResult>;
+/**
+ * Parses a one-shot token string into its constituent fields.
+ *
+ * Uses fixed offsets — no length oracle. Token must be exactly 120 bytes raw.
+ *
+ * Parse offsets:
+ * - nonce @ 0 (16 bytes)
+ * - ts @ 16 (8 bytes)
+ * - action @ 24 (32 bytes)
+ * - ctx @ 56 (32 bytes)
+ * - mac @ 88 (32 bytes)
+ *
+ * @returns ParsedOneShotToken or null if the token cannot be parsed
+ */
+declare function parseOneShotToken(tokenString: string): ParsedOneShotToken | null;
+/**
+ * Validates a one-shot token using the Deterministic Failure Model.
+ *
+ * Additional checks over regular validation:
+ * - Action binding: token must match the expected action
+ * - Nonce replay: token nonce must not have been used before (via NonceCache)
+ *
+ * ALL validation steps MUST complete. No early return. Single exit point.
+ *
+ * @param cryptoProvider - CryptoProvider for HMAC verification
+ * @param key - KeyEntry derived with 'oneshot' domain
+ * @param tokenString - The one-shot token string to validate
+ * @param expectedAction - The expected action string (e.g., "POST:/api/account/delete")
+ * @param nonceCache - NonceCache for replay detection
+ * @param expectedContext - Optional expected 32-byte context hash
+ * @param ttlMs - Token TTL in milliseconds (default: 5 minutes)
+ * @param now - Current timestamp override for testing
+ */
+declare function validateOneShotToken(cryptoProvider: CryptoProvider, key: KeyEntry, tokenString: string, expectedAction: string, nonceCache: NonceCache, expectedContext?: Uint8Array, ttlMs?: number, now?: number): Promise<ValidationResult>;
+
+/**
+ * Encodes a Uint8Array to base64url string (RFC 4648, no padding).
+ * Pure function, zero dependencies.
+ */
+declare function toBase64Url(buffer: Uint8Array): string;
+/**
+ * Decodes a base64url string (RFC 4648, no padding) to Uint8Array.
+ * Pure function, zero dependencies.
+ *
+ * @throws {Error} If the input is not valid base64url
+ */
+declare function fromBase64Url(encoded: string): Uint8Array;
+/**
+ * Converts a Uint8Array to a proper ArrayBuffer.
+ * Handles the Uint8Array.buffer -> ArrayBufferLike type issue.
+ * Always creates a clean copy with its own ArrayBuffer.
+ */
+declare function toArrayBuffer(uint8: Uint8Array): ArrayBuffer;
+
+export { ACTION_SIZE, CONTEXT_SIZE, type CryptoProvider, DEFAULT_GRACE_WINDOW_MS, DEFAULT_NONCE_CACHE_MAX, DEFAULT_NONCE_CACHE_TTL_MS, DEFAULT_ONESHOT_TTL_MS, DEFAULT_TOKEN_TTL_MS, type GenerationResult, KID_SIZE, type KeyDomain, type KeyEntry, type Keyring, MAC_SIZE, NONCE_SIZE, type NonceCache, type NonceCacheConfig, ONESHOT_OFFSETS, ONESHOT_RAW_SIZE, type OneShotGenerationResult, type OneShotTokenString, type ParsedOneShotToken, type ParsedToken, TIMESTAMP_SIZE, TOKEN_OFFSETS, TOKEN_RAW_SIZE, type TokenString, type ValidationResult, WebCryptoCryptoProvider, assemblePayload, computeAction, computeContext, constantTimeEqual, createKeyring, createNonceCache, deriveSigningKey, emptyContext, fromBase64Url, generateOneShotToken, generateToken, getActiveKey, parseOneShotToken, parseToken, resolveKey, rotateKey, serializeToken, toArrayBuffer, toBase64Url, validateOneShotToken, validateTTL, validateToken };