@ppabari/strio 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,885 @@
+import { R as RandomStringOptions, E as EntropyResult, V as ValidateOptions, c as ValidationResult } from './zod-CINbFpp9.cjs';
+export { a as RandomStringResult, b as RandomStringSchemaOptions, S as StartWith, r as randomStringSchema } from './zod-CINbFpp9.cjs';
+
+/**
+ * short-id.ts
+ * Collision-resistant short IDs with an optional checksum character.
+ *
+ * A checksum character (Luhn-style mod-N) is appended to the random
+ * portion so that single-character transcription errors are detectable
+ * without a database lookup. The checksum uses the same charset as the
+ * random portion — the output looks uniform.
+ *
+ * Format: [prefix_][random chars][checksum char]
+ *
+ * @example
+ * const id = generateId({ prefix: 'usr' });
+ * // → 'usr_K3xP9mQr2L4c'  (10 random + 1 checksum = 11 chars after prefix)
+ *
+ * validateId('usr_K3xP9mQr2L4c', { prefix: 'usr' });
+ * // → { valid: true, ... }
+ */
+interface ShortIdOptions {
+    /**
+     * Optional prefix string, e.g. `'usr'` → `'usr_K3xP9mQr'`.
+     * An underscore separator is added automatically between prefix and random part.
+     * Set `separator: ''` to disable.
+     */
+    prefix?: string;
+    /**
+     * Separator between prefix and random portion.
+     * @default '_'
+     */
+    separator?: string;
+    /**
+     * Length of the random portion (before checksum is added).
+     * Total random section = randomLength + 1 (checksum).
+     * @default 12
+     */
+    randomLength?: number;
+    /**
+     * Character pool for the random portion. Accepts a charset alias
+     * (e.g. `'base58'`) or a raw character string.
+     * @default base58 (no ambiguous chars)
+     */
+    charset?: string;
+    /**
+     * Whether to append a checksum character.
+     * Disable only if you need exact length control.
+     * @default true
+     */
+    checksum?: boolean;
+}
+interface ShortIdValidateOptions {
+    /** Expected prefix (without separator). */
+    prefix?: string;
+    /** Separator used when the ID was generated. @default '_' */
+    separator?: string;
+    /** Charset used when the ID was generated. @default base58 */
+    charset?: string;
+    /** Whether the ID was generated with a checksum. @default true */
+    checksum?: boolean;
+}
+interface ShortIdValidateResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Generate a collision-resistant short ID.
+ *
+ * @example
+ * generateId()                          // → 'K3xP9mQr2L4Xc'
+ * generateId({ prefix: 'usr' })         // → 'usr_K3xP9mQr2L4Xc'
+ * generateId({ prefix: 'inv', randomLength: 8 }) // → 'inv_K3xP9mQrc'
+ * generateId({ charset: 'base62' })     // → '4jK9mQr2L4Xz3'
+ */
+declare function generateId(options?: ShortIdOptions): string;
+/**
+ * Validate a short ID against a known config.
+ * Checks prefix, separator, and checksum integrity.
+ *
+ * @example
+ * validateId('usr_K3xP9mQr2L4Xc', { prefix: 'usr' })
+ * // → { valid: true, errors: [] }
+ *
+ * validateId('usr_K3xP9mQr2L4Xa', { prefix: 'usr' })
+ * // → { valid: false, errors: ['Checksum mismatch — ID may be corrupted or mistyped.'] }
+ */
+declare function validateId(id: string, options?: ShortIdValidateOptions): ShortIdValidateResult;
+
+/**
+ * expiring-token.ts
+ * Time-bound tokens with tamper-evident expiry encoding.
+ *
+ * Token format (base62-encoded, no separators):
+ *   [8 chars: expiry epoch seconds in base62] + [random payload]
+ *
+ * The expiry is prepended to the random portion, then the whole thing
+ * is encoded so it looks like a uniform random string. A simple XOR
+ * checksum guards against accidental corruption (not cryptographic —
+ * use a signed JWT if you need HMAC-level tamper protection).
+ *
+ * @example
+ * const { token, expiresAt } = generateExpiringToken({ ttlSeconds: 900 });
+ * // later…
+ * const result = verifyToken(token);
+ * result.valid      // true / false
+ * result.expiresAt  // Date
+ * result.expired    // boolean
+ */
+interface ExpiringTokenOptions {
+    /**
+     * How long (in seconds) before the token expires.
+     * @default 900 (15 minutes)
+     */
+    ttlSeconds?: number;
+    /**
+     * Length of the random payload (not counting the expiry prefix).
+     * Total token length = payloadLength + 8.
+     * @default 24
+     */
+    payloadLength?: number;
+}
+interface ExpiringTokenResult {
+    /** The opaque token string to store / transmit. */
+    token: string;
+    /** When this token stops being valid. */
+    expiresAt: Date;
+    /** Total token length in characters. */
+    length: number;
+}
+interface TokenVerifyResult {
+    /** Whether the token is structurally valid AND not yet expired. */
+    valid: boolean;
+    /** Whether the token format could be parsed (regardless of expiry). */
+    parsed: boolean;
+    /** Whether the token has passed its expiry time. */
+    expired: boolean;
+    /** Expiry time, if the token could be parsed. */
+    expiresAt: Date | null;
+    /** Seconds remaining (negative if expired). */
+    secondsRemaining: number | null;
+}
+/**
+ * Generate a self-expiring token.
+ *
+ * @example
+ * // Password reset link (15 min)
+ * const { token } = generateExpiringToken({ ttlSeconds: 900 });
+ *
+ * // Magic login link (10 min), longer payload
+ * const { token, expiresAt } = generateExpiringToken({
+ *   ttlSeconds: 600,
+ *   payloadLength: 32,
+ * });
+ */
+declare function generateExpiringToken(options?: ExpiringTokenOptions): ExpiringTokenResult;
+/**
+ * Verify an expiring token. Returns whether it's valid and unexpired.
+ *
+ * @example
+ * const result = verifyToken(token);
+ * if (!result.valid) {
+ *   if (result.expired) throw new Error('Token expired');
+ *   throw new Error('Invalid token');
+ * }
+ */
+declare function verifyToken(token: string): TokenVerifyResult;
+
+/**
+ * stream.ts
+ * Async generator (iterator) API for memory-efficient bulk generation.
+ *
+ * Unlike the `count` option (which allocates a Set of N strings upfront),
+ * the stream API yields strings one at a time — safe for generating
+ * hundreds of thousands of IDs without blowing the heap.
+ *
+ * @example Basic usage
+ * for await (const token of randomStringStream({ length: 24 })) {
+ *   await db.insert({ token });
+ * }
+ * // Runs forever — break when done
+ *
+ * @example Generate exactly N
+ * import { take } from '@ppabari/strio';
+ * const ids = await take(randomStringStream({ length: 12 }), 10_000);
+ *
+ * @example Unique-only stream
+ * const stream = uniqueRandomStringStream({ length: 8, charset: 'base36' });
+ * for await (const id of stream) { ... }
+ */
+
+/**
+ * Infinite async generator that yields random strings from the given options.
+ * Each value is independently generated (not deduplicated).
+ *
+ * Use `take()` or a `break` statement to stop the stream.
+ * For bulk operations, prefer `take(randomStringStream(opts), n)` over
+ * the `count` option — it avoids allocating a full Set upfront.
+ */
+declare function randomStringStream(options?: RandomStringOptions): AsyncGenerator<string, never, unknown>;
+/**
+ * Infinite async generator that yields globally unique strings.
+ * Deduplication is maintained via an in-memory Set.
+ *
+ * ⚠️  Memory grows with consumption. For very large sets (>1M), consider
+ * a probabilistic structure (Bloom filter) or external dedup store instead.
+ */
+declare function uniqueRandomStringStream(options?: RandomStringOptions): AsyncGenerator<string, never, unknown>;
+/**
+ * Collect the first `n` values from any async iterable into an array.
+ * Works with both `randomStringStream` and `uniqueRandomStringStream`.
+ *
+ * @example
+ * const tokens = await take(randomStringStream({ length: 32 }), 500);
+ * // → string[] of 500 tokens
+ */
+declare function take<T>(iterable: AsyncIterable<T>, n: number): Promise<T[]>;
+/**
+ * Like `take`, but filters values through a predicate.
+ * Pulls from the stream until `n` values satisfy `predicate`.
+ *
+ * @example
+ * // Get 10 tokens that start with a digit
+ * const tokens = await takeWhere(
+ *   randomStringStream({ length: 12 }),
+ *   10,
+ *   t => /^[0-9]/.test(t)
+ * );
+ */
+declare function takeWhere<T>(iterable: AsyncIterable<T>, n: number, predicate: (value: T) => boolean): Promise<T[]>;
+
+/**
+ * passphrase.ts
+ * Human-memorable passphrase generation using the EFF Large Wordlist.
+ *
+ * Each word is selected using cryptographically secure randomness.
+ * A 4-word passphrase gives ~51 bits of entropy; 6 words gives ~77 bits.
+ *
+ * The built-in wordlist is a curated 1296-word subset (6^4 = 1296) of the
+ * EFF Large Wordlist, suitable for 4-dice rolls. We use a 256-word subset
+ * here for bundle efficiency — for maximum entropy use the `customWords` option
+ * with the full EFF list.
+ *
+ * @example
+ * generatePassphrase()
+ * // → 'correct-horse-battery-staple'
+ *
+ * generatePassphrase({ words: 5, separator: ' ', capitalize: true })
+ * // → 'Correct Horse Battery Staple Fence'
+ */
+/**
+ * 512-word curated subset — common, unambiguous English words.
+ * Large enough for good entropy while keeping bundle size small.
+ * Each word is 3–8 characters, avoiding technical jargon and offensive terms.
+ */
+declare const WORD_LIST: readonly string[];
+interface PassphraseOptions {
+    /**
+     * Number of words in the passphrase.
+     * More words = more entropy. 4 words ≈ 51 bits, 6 words ≈ 77 bits.
+     * @default 4
+     */
+    words?: number;
+    /**
+     * Separator between words.
+     * @default '-'
+     */
+    separator?: string;
+    /**
+     * Capitalize the first letter of each word.
+     * @default false
+     */
+    capitalize?: boolean;
+    /**
+     * Append a random digit to the end for services that require numbers.
+     * @default false
+     */
+    appendDigit?: boolean;
+    /**
+     * Use a custom word list instead of the built-in list.
+     * Must contain at least 2 words.
+     */
+    customWords?: readonly string[];
+    /**
+     * Prefix the passphrase with a fixed string.
+     */
+    prefix?: string;
+}
+interface PassphraseResult {
+    /** The generated passphrase string. */
+    passphrase: string;
+    /** Number of words used. */
+    wordCount: number;
+    /** Entropy estimate in bits. */
+    entropyBits: number;
+}
+/**
+ * Generate a human-memorable passphrase from random dictionary words.
+ *
+ * @example
+ * generatePassphrase()
+ * // → { passphrase: 'stone-river-proud-flame', wordCount: 4, entropyBits: 50.9 }
+ *
+ * generatePassphrase({ words: 5, separator: ' ', capitalize: true })
+ * // → { passphrase: 'Stone River Proud Flame Beach', wordCount: 5, entropyBits: 63.7 }
+ */
+declare function generatePassphrase(options?: PassphraseOptions): PassphraseResult;
+
+/**
+ * entropy.ts
+ * Estimate the Shannon entropy and strength of a random string configuration.
+ */
+
+/**
+ * Estimates the entropy of strings generated by the given options.
+ *
+ * For pattern-based strings, each placeholder contributes independently.
+ * For length-based strings, entropy = log2(charsetSize) * effectiveLength.
+ *
+ * @example
+ * const e = estimateEntropy({ length: 32, uppercase: true, lowercase: true, numeric: true });
+ * console.log(e.bits);     // ~190
+ * console.log(e.strength); // 'very-strong'
+ */
+declare function estimateEntropy(options?: RandomStringOptions): EntropyResult;
+
+/**
+ * validate.ts
+ * Validate that a string conforms to a given RandomStringOptions config.
+ */
+
+/**
+ * Checks whether `str` satisfies the given validation rules.
+ *
+ * @example
+ * const result = validateRandomString('abc123', {
+ *   minLength: 6,
+ *   requireNumeric: true,
+ *   requireLowercase: true,
+ * });
+ * result.valid; // true
+ *
+ * @example
+ * const result = validateRandomString('abc', { requireNumeric: true });
+ * result.valid;  // false
+ * result.errors; // ['Must contain at least one numeric digit.']
+ */
+declare function validateRandomString(str: string, options?: ValidateOptions): ValidationResult;
+
+/**
+ * charset-aliases.ts
+ * Named character set aliases for common encoding schemes.
+ * Pass any alias name as the `charset` option in generateRandomString.
+ *
+ * @example
+ * import { generateRandomString, CHARSET_ALIASES } from '@ppabari/strio';
+ * generateRandomString({ charset: CHARSET_ALIASES.base58, length: 22 });
+ * // or via string shorthand:
+ * generateRandomString({ charset: 'base58', length: 22 });
+ */
+declare const CHARSET_ALIASES: Record<string, string>;
+type CharsetAlias = keyof typeof CHARSET_ALIASES;
+/**
+ * Resolve a charset value: if it matches a known alias, return the
+ * corresponding character string; otherwise return the value as-is.
+ *
+ * This is called inside buildCharset so alias names work transparently
+ * as the `charset` option.
+ *
+ * @example
+ * resolveCharsetAlias('base58') // → '123456789ABCDEF...'
+ * resolveCharsetAlias('abc')    // → 'abc'
+ */
+declare function resolveCharsetAlias(value: string): string;
+
+/**
+ * presets.ts
+ * Ready-to-use named presets for common use cases.
+ * Each preset is a plain `RandomStringOptions` object — pass it directly
+ * to `generateRandomString` or spread it to customise.
+ *
+ * @example
+ * import { generateRandomString, PRESETS } from 'secure-random-string';
+ * const token = generateRandomString(PRESETS.TOKEN);
+ * const longToken = generateRandomString({ ...PRESETS.TOKEN, length: 64 });
+ */
+declare const PRESETS: {
+    /**
+     * API token / session key.
+     * 32-char alphanumeric (no symbols), readable=false for max entropy.
+     * ~190 bits of entropy.
+     */
+    readonly TOKEN: {
+        length: number;
+        numeric: true;
+        lowercase: true;
+        uppercase: true;
+        symbols: false;
+    };
+    /**
+     * Strong password.
+     * 20 chars, all character types including symbols.
+     * ~131 bits of entropy.
+     */
+    readonly PASSWORD: {
+        length: number;
+        numeric: true;
+        lowercase: true;
+        uppercase: true;
+        symbols: true;
+    };
+    /**
+     * Human-readable token — no ambiguous characters (0/O/l/I/1).
+     * Safe to read aloud or transcribe from a screen.
+     * 16 chars, ~93 bits of entropy.
+     */
+    readonly READABLE: {
+        length: number;
+        numeric: true;
+        lowercase: true;
+        uppercase: true;
+        symbols: false;
+        readable: true;
+    };
+    /**
+     * URL-safe slug identifier.
+     * Lowercase letters and digits only, starts with a letter.
+     * 12 chars, ~62 bits of entropy.
+     */
+    readonly SLUG: {
+        length: number;
+        numeric: true;
+        lowercase: true;
+        uppercase: false;
+        symbols: false;
+        startWith: "alphabet";
+    };
+    /**
+     * Lowercase hex string.
+     * Compatible with UUID hex components, color codes, hash representations.
+     * 32 chars (128-bit equivalent), ~128 bits of entropy.
+     */
+    readonly HEX: {
+        length: number;
+        charset: string;
+    };
+    /**
+     * Numeric PIN code. 6 digits, starts with a non-zero digit.
+     * ~17 bits of entropy — suitable for short-lived OTP codes.
+     */
+    readonly PIN: {
+        length: number;
+        numeric: true;
+        lowercase: false;
+        uppercase: false;
+        symbols: false;
+        exclude: string;
+        startWith: "numeric";
+    };
+    /**
+     * UUID-like string (not RFC 4122 compliant, but same visual format).
+     * Uses `pattern` to produce 8-4-4-4-12 hex grouping.
+     * ~122 bits of entropy (same as UUIDv4).
+     */
+    readonly UUID_LIKE: {
+        pattern: string;
+        charset: string;
+    };
+    /**
+     * Short alphanumeric ID — suitable for database record IDs.
+     * 8 chars, uppercase alphanumeric, starts with a letter.
+     * ~41 bits — good for IDs when combined with a namespace/prefix.
+     */
+    readonly SHORT_ID: {
+        length: number;
+        numeric: true;
+        lowercase: false;
+        uppercase: true;
+        symbols: false;
+        startWith: "alphabet";
+    };
+    /**
+     * Invitation / redemption code.
+     * 16 chars, readable (no ambiguous chars), pattern grouped for readability.
+     * @example 'KXPZ-9MR2-LQ4Y-8WVN'
+     */
+    readonly INVITE_CODE: {
+        pattern: string;
+        readable: true;
+    };
+};
+type PresetName = keyof typeof PRESETS;
+
+/**
+ * secrets.ts
+ * Cryptographic secret and key generation utilities.
+ *
+ * Covers the full lifecycle of secrets used in real applications:
+ *   - Raw bytes                   → generateBytes()
+ *   - Hex keys (AES, ChaCha20)    → generateHexKey()
+ *   - Base64 keys (cloud imports) → generateBase64Key()
+ *   - JWT secrets (HS256/384/512) → generateJwtSecret()
+ *   - Structured API keys         → generateApiKey()
+ *   - Numeric OTP codes           → generateOtp()
+ *   - Secret masking for logs     → maskSecret()
+ *   - Constant-time comparison    → timingSafeEqual()
+ *   - Framework secret helpers    → generateCookieSecret() etc.
+ *
+ * All functions use crypto.getRandomValues() — the same bias-free
+ * engine as the rest of strio.
+ */
+/**
+ * Generate `n` cryptographically secure random bytes.
+ * Returns a `Uint8Array` — the native format accepted by Web Crypto,
+ * Node's `crypto`, and virtually every encryption library.
+ *
+ * @example
+ * const key = generateBytes(32);           // 32-byte (256-bit) key material
+ * await crypto.subtle.importKey('raw', key, 'AES-GCM', false, ['encrypt']);
+ *
+ * const iv = generateBytes(12);            // AES-GCM initialisation vector
+ * const nonce = generateBytes(24);         // XSalsa20 nonce
+ */
+declare function generateBytes(length: number): Uint8Array;
+/**
+ * Generate a random key of `bits` length, returned as a lowercase hex string.
+ * The standard format for raw key material in most Node.js crypto libraries,
+ * Redis ACL passwords, database encryption keys, and many cloud services.
+ *
+ * @param bits - Key size in bits. Must be a positive multiple of 8.
+ *               Common values: 128, 192, 256 (AES), 512 (HMAC-SHA512).
+ *
+ * @example
+ * generateHexKey(256)   // → 64-char hex  (AES-256 key)
+ * generateHexKey(128)   // → 32-char hex  (AES-128 key)
+ * generateHexKey(512)   // → 128-char hex (HMAC-SHA512 key)
+ *
+ * // Use directly with Node crypto:
+ * const key = generateHexKey(256);
+ * const cipher = crypto.createCipheriv('aes-256-gcm', Buffer.from(key, 'hex'), iv);
+ */
+declare function generateHexKey(bits?: number): string;
+type Base64Variant = 'standard' | 'url-safe' | 'url-safe-no-pad';
+/**
+ * Generate a random key of `bits` length, returned as a base64 string.
+ *
+ * Three variants:
+ * - `'standard'`          — includes `+`, `/`, `=` padding (AWS, most CLIs)
+ * - `'url-safe'`          — replaces `+`→`-`, `/`→`_`, keeps `=` (cookies, headers)
+ * - `'url-safe-no-pad'`   — same but no `=` padding (JWT, URL query params)
+ *
+ * @param bits - Key size in bits. Must be a positive multiple of 8.
+ * @param variant - Output encoding variant. Default: `'url-safe-no-pad'`.
+ *
+ * @example
+ * generateBase64Key(256)                          // → url-safe, no padding (default)
+ * generateBase64Key(256, 'standard')              // → standard base64 with padding
+ * generateBase64Key(256, 'url-safe')              // → url-safe with padding
+ *
+ * // AWS KMS / GCP import format:
+ * const keyMaterial = generateBase64Key(256, 'standard');
+ *
+ * // Cookie signing secret (express-session, iron-session):
+ * const secret = generateBase64Key(256, 'url-safe-no-pad');
+ */
+declare function generateBase64Key(bits?: number, variant?: Base64Variant): string;
+type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512';
+type JwtSecretFormat = 'base64url' | 'hex' | 'utf8-like';
+interface JwtSecretOptions {
+    /**
+     * HMAC algorithm this secret will be used with.
+     * Determines the minimum key length enforced automatically.
+     * @default 'HS256'
+     */
+    algorithm?: JwtAlgorithm;
+    /**
+     * Output format.
+     * - `'base64url'`   — RFC 4648 §5, no padding. Default. Works with jsonwebtoken,
+     *                     jose, @auth/core, NextAuth, Fastify JWT, Lucia.
+     * - `'hex'`         — lowercase hex. Works with jose when you import as `'oct'`.
+     * - `'utf8-like'`   — base62 string. Usable directly as a string secret in older
+     *                     libraries that accept plain strings (not recommended for new code).
+     * @default 'base64url'
+     */
+    format?: JwtSecretFormat;
+    /**
+     * Override the key size in bits. Must be ≥ the algorithm minimum.
+     * Defaults to the algorithm's minimum (256 / 384 / 512).
+     */
+    bits?: number;
+}
+interface JwtSecretResult {
+    /** The secret value — pass this to your JWT library. */
+    secret: string;
+    /** Algorithm this secret was generated for. */
+    algorithm: JwtAlgorithm;
+    /** Actual key size in bits. */
+    bits: number;
+    /** Output format. */
+    format: JwtSecretFormat;
+    /**
+     * Usage example string for the most common library (jsonwebtoken).
+     * Handy for logging/debugging during setup.
+     */
+    example: string;
+}
+/**
+ * Generate a cryptographically secure JWT signing secret.
+ *
+ * Enforces RFC 7518 minimum key lengths:
+ *   - HS256 → minimum 256 bits (32 bytes)
+ *   - HS384 → minimum 384 bits (48 bytes)
+ *   - HS512 → minimum 512 bits (64 bytes)
+ *
+ * @example
+ * // Default — HS256, base64url
+ * const { secret } = generateJwtSecret();
+ * jwt.sign(payload, secret, { algorithm: 'HS256' });
+ *
+ * // HS512 for maximum security
+ * const { secret } = generateJwtSecret({ algorithm: 'HS512' });
+ *
+ * // For jose / @auth/core
+ * const { secret } = generateJwtSecret({ algorithm: 'HS256', format: 'base64url' });
+ * // Set as AUTH_SECRET env var for NextAuth v5
+ *
+ * // For libraries expecting hex
+ * const { secret } = generateJwtSecret({ format: 'hex' });
+ */
+declare function generateJwtSecret(options?: JwtSecretOptions): JwtSecretResult;
+interface ApiKeyOptions {
+    /**
+     * Key type prefix, e.g. `'sk'` (secret key), `'pk'` (public key), `'tok'`.
+     * @default 'sk'
+     */
+    type?: string;
+    /**
+     * Environment prefix, e.g. `'live'`, `'test'`, `'dev'`.
+     * Omit to produce a key with no environment segment.
+     */
+    environment?: 'live' | 'test' | 'dev' | string;
+    /**
+     * Entropy of the random portion in bits.
+     * @default 256
+     */
+    bits?: number;
+    /**
+     * Charset for the random portion.
+     * @default 'base62'
+     */
+    charset?: 'base62' | 'base58' | 'hex' | string;
+    /**
+     * Separator between segments.
+     * @default '_'
+     */
+    separator?: string;
+}
+interface ApiKeyResult {
+    /** The full API key string. */
+    key: string;
+    /** The prefix segment, e.g. `'sk_live'`. */
+    prefix: string;
+    /** Character count of the random portion (not including prefix or separator). */
+    randomLength: number;
+    /** Entropy of the random portion in bits. */
+    bits: number;
+}
+/**
+ * Generate a structured API key in the style of Stripe, GitHub, or OpenAI.
+ *
+ * Format: `{type}_{environment}_{randomPortion}`
+ * e.g.    `strio_live_K3xP9mQr2LzYw7NvTq8sHfGbJ5cD4eAK3xP9mQr2LzY`
+ *
+ * @example
+ * generateApiKey()
+ * // → { key: 'strio_live_K3xP9mQr2LzYw7Nv...',  prefix: 'sk_live', ... }
+ *
+ * generateApiKey({ type: 'sk', environment: 'test', bits: 256 })
+ * // → 'strio_test_K3xP9mQr...'
+ *
+ * generateApiKey({ type: 'tok', bits: 128 })
+ * // → 'tok_K3xP9mQr2LzYw7Nv'
+ *
+ * generateApiKey({ type: 'pk', environment: 'live', charset: 'hex' })
+ * // → 'pub_live_a3f7c2b9...'
+ */
+declare function generateApiKey(options?: ApiKeyOptions): ApiKeyResult;
+interface OtpOptions {
+    /**
+     * Number of digits in the OTP.
+     * @default 6
+     */
+    digits?: number;
+    /**
+     * Whether to allow a leading zero.
+     * Set to `false` to ensure the first digit is 1–9 (e.g. for display in SMS).
+     * @default true
+     */
+    allowLeadingZero?: boolean;
+}
+interface OtpResult {
+    /** The OTP as a zero-padded string (e.g. `'048392'`). */
+    code: string;
+    /** The OTP as a number (e.g. `48392`). */
+    value: number;
+    /** Number of digits. */
+    digits: number;
+}
+/**
+ * Generate a cryptographically secure numeric OTP (one-time password).
+ * Uses modular arithmetic on a secure random integer — no modulo bias
+ * for digit counts up to 9 (10^9 < 2^30 < 2^32, safe in float64).
+ *
+ * @example
+ * generateOtp()              // → { code: '483920', value: 483920, digits: 6 }
+ * generateOtp({ digits: 8 }) // → { code: '04839201', value: 4839201, digits: 8 }
+ *
+ * // SMS-friendly (no leading zero)
+ * generateOtp({ allowLeadingZero: false })
+ *
+ * // Use just the code string
+ * const { code } = generateOtp();
+ * await sms.send(phone, `Your code is ${code}`);
+ */
+declare function generateOtp(options?: OtpOptions): OtpResult;
+interface MaskSecretOptions {
+    /**
+     * Number of characters to reveal at the start of the secret.
+     * `0` reveals nothing (prefix only).
+     * @default 0 (show prefix only, mask everything else)
+     */
+    visibleStart?: number;
+    /**
+     * Number of characters to reveal at the end.
+     * @default 4
+     */
+    visibleEnd?: number;
+    /**
+     * Character used to mask the hidden portion.
+     * @default '*'
+     */
+    maskChar?: string;
+    /**
+     * Minimum number of mask characters shown, regardless of secret length.
+     * Prevents inferring length from short secrets.
+     * @default 4
+     */
+    minMaskLength?: number;
+    /**
+     * Maximum mask characters shown (caps a very long mask).
+     * @default 8
+     */
+    maxMaskLength?: number;
+    /**
+     * Known prefix segments to preserve literally before masking begins.
+     * e.g. `['strio_live_', 'strio_test_']` — the prefix is kept, the rest is masked.
+     * If the secret starts with one of these, the prefix is shown and
+     * `visibleStart` is counted from after the prefix.
+     */
+    knownPrefixes?: string[];
+}
+/**
+ * Mask a secret string for safe logging, display, or debugging.
+ * Preserves enough context to identify the key without exposing it.
+ *
+ * @example
+ * maskSecret('myapp_live_K3xP9mQr2LzYw7NvTq8sHfGb')
+ * // → 'strio_live_****...w7Nv'  (auto-detects 'strio_live_' prefix)
+ *
+ * maskSecret('supersecretpassword')
+ * // → '****...word'
+ *
+ * maskSecret('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.abc123')
+ * // → '****...123'
+ *
+ * // Custom reveal
+ * maskSecret('myapp_live_K3xP9mQr2LzY', { visibleEnd: 6 })
+ * // → 'strio_live_****...LzY'
+ */
+declare function maskSecret(secret: string, options?: MaskSecretOptions): string;
+/**
+ * Compare two strings or byte arrays in constant time.
+ * Prevents timing attacks where an attacker infers secret content by
+ * measuring how long a comparison takes.
+ *
+ * **Always use this instead of `===` when comparing tokens, secrets,
+ * HMAC signatures, or any security-sensitive value.**
+ *
+ * The comparison time is proportional to `max(a.length, b.length)` —
+ * it does not short-circuit on mismatch.
+ *
+ * @returns `true` if the values are identical, `false` otherwise.
+ *
+ * @example
+ * // Comparing incoming token against stored token
+ * if (!timingSafeEqual(incomingToken, storedToken)) {
+ *   throw new Error('Invalid token');
+ * }
+ *
+ * // Also works with Uint8Array (e.g. HMAC comparison)
+ * const valid = timingSafeEqual(computedHmac, expectedHmac);
+ */
+declare function timingSafeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean;
+/**
+ * Generate a cookie signing secret for session libraries.
+ *
+ * Compatible with:
+ *   - express-session (`secret` option)
+ *   - iron-session (`password` option)
+ *   - lucia (`sessionCookieOptions.password`)
+ *   - cookie-signature
+ *
+ * Returns a 256-bit base64url string by default — long enough to resist
+ * brute force while remaining pasteable in .env files.
+ *
+ * @example
+ * // express-session
+ * app.use(session({ secret: generateCookieSecret() }));
+ *
+ * // iron-session
+ * const sessionOptions = { password: generateCookieSecret(), cookieName: 'session' };
+ *
+ * // .env usage
+ * console.log(`COOKIE_SECRET="${generateCookieSecret()}"`);
+ */
+declare function generateCookieSecret(bits?: number): string;
+/**
+ * Generate an encryption key suitable for AES-GCM or AES-CBC.
+ *
+ * @param keySize - `128`, `192`, or `256` bits. Default: 256.
+ * @param format  - `'hex'` (default) or `'base64'` or `'bytes'`.
+ *
+ * @example
+ * generateAesKey()             // → 64-char hex (AES-256)
+ * generateAesKey(128)          // → 32-char hex (AES-128)
+ * generateAesKey(256, 'base64') // → base64url string
+ * generateAesKey(256, 'bytes') // → Uint8Array
+ */
+declare function generateAesKey(keySize?: 128 | 192 | 256, format?: 'hex' | 'base64' | 'bytes'): string | Uint8Array;
+/**
+ * Generate a secret for Next.js / NextAuth / Auth.js.
+ * Sets AUTH_SECRET in your .env file — used to sign JWTs and cookies.
+ * Output matches what `npx auth secret` generates.
+ *
+ * @example
+ * const secret = generateNextAuthSecret();
+ * console.log(`AUTH_SECRET="${secret}"`);
+ */
+declare function generateNextAuthSecret(): string;
+/**
+ * Generate a Django SECRET_KEY compatible string.
+ * Django expects a long random string of printable ASCII characters —
+ * at least 50 characters, no restrictions beyond that.
+ *
+ * @example
+ * const key = generateDjangoSecretKey();
+ * console.log(`SECRET_KEY="${key}"`);
+ */
+declare function generateDjangoSecretKey(): string;
+/**
+ * Generate a Rails / rack secret_key_base compatible string.
+ * Rails expects a 128+ character hex string for its key base.
+ *
+ * @example
+ * const key = generateRailsSecretKeyBase();
+ * console.log(`SECRET_KEY_BASE="${key}"`);
+ */
+declare function generateRailsSecretKeyBase(): string;
+
+/**
+ * @ppabari/strio
+ *
+ * Cryptographically secure string generation for Node.js and browsers.
+ * Zero dependencies. Fully typed. Bias-free.
+ */
+
+declare function generateRandomString(options?: RandomStringOptions & {
+    count?: 1;
+}): string;
+declare function generateRandomString(options: RandomStringOptions & {
+    count: number;
+}): string[];
+declare function generateRandomStringAsync(options?: RandomStringOptions): Promise<string | string[]>;
+
+export { type ApiKeyOptions, type ApiKeyResult, WORD_LIST as BUILT_IN_WORD_LIST, type Base64Variant, CHARSET_ALIASES, type CharsetAlias, EntropyResult, type ExpiringTokenOptions, type ExpiringTokenResult, type JwtAlgorithm, type JwtSecretFormat, type JwtSecretOptions, type JwtSecretResult, type MaskSecretOptions, type OtpOptions, type OtpResult, PRESETS, type PassphraseOptions, type PassphraseResult, type PresetName, RandomStringOptions, type ShortIdOptions, type ShortIdValidateOptions, type ShortIdValidateResult, type TokenVerifyResult, ValidateOptions, ValidationResult, estimateEntropy, generateAesKey, generateApiKey, generateBase64Key, generateBytes, generateCookieSecret, generateDjangoSecretKey, generateExpiringToken, generateHexKey, generateId, generateJwtSecret, generateNextAuthSecret, generateOtp, generatePassphrase, generateRailsSecretKeyBase, generateRandomString, generateRandomStringAsync, maskSecret, randomStringStream, resolveCharsetAlias, take, takeWhere, timingSafeEqual, uniqueRandomStringStream, validateId, validateRandomString, verifyToken };