otp-guard 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+import { O as OtpStore } from './store-mOFmlT-6.cjs';
+export { a as OtpRecord } from './store-mOFmlT-6.cjs';
+
+/** Duration in milliseconds, or a short string: "30s", "5m", "2h", "1d". */
+type Duration = number | `${number}${'s' | 'm' | 'h' | 'd'}`;
+/**
+ * Character set for generated codes.
+ *
+ * - `numeric` — digits only. The right default for SMS.
+ * - `alphanumeric` — excludes I, L, O, U, 0, 1 to avoid transcription errors
+ *   when a code is read aloud or copied by hand.
+ * - `base32` — RFC 4648 alphabet, for codes that feed other systems.
+ */
+type Alphabet = 'numeric' | 'alphanumeric' | 'base32';
+interface RateWindow {
+    count: number;
+    window: Duration;
+}
+type VerifyFailure = 'invalid' | 'expired' | 'locked' | 'bind_mismatch';
+/** Metadata passed to observability hooks. */
+interface HookEvent {
+    /**
+     * The raw identity. Treat as personal data: do not ship it to an APM or
+     * third-party log sink. Use `keyHash` for that.
+     */
+    key: string;
+    /** Stable, non-reversible identifier derived from key and purpose. Safe to log. */
+    keyHash: string;
+    purpose: string;
+    scope?: string;
+}
+/**
+ * Observability callbacks.
+ *
+ * Hooks are advisory. Exceptions thrown inside them are swallowed, so a
+ * broken metrics pipeline cannot break authentication.
+ */
+interface Hooks {
+    onIssue?(e: HookEvent): void;
+    onRateLimited?(e: HookEvent & {
+        reason: 'cooldown' | 'rate_limited';
+        /** Which of the three limits rejected the request. */
+        limit: 'cooldown' | 'key' | 'scope';
+    }): void;
+    onVerifyFailure?(e: HookEvent & {
+        reason: VerifyFailure;
+        attempts: number;
+    }): void;
+    onLockout?(e: HookEvent): void;
+    onStoreError?(e: {
+        operation: string;
+        error: unknown;
+    }): void;
+}
+interface OtpKitOptions {
+    store: OtpStore;
+    /**
+     * Server-side secret mixed into every hash and every store key. Rotating it
+     * invalidates all outstanding codes, which is a legitimate emergency lever.
+     *
+     * Minimum 16 characters. Generate with:
+     * `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+     *
+     * Keep it out of the database the hashes live in — that separation is the
+     * entire point of a pepper.
+     */
+    pepper: string;
+    /** Characters per code. 4–32. Default 6. */
+    length?: number;
+    /** Character set. Default `"numeric"`. */
+    alphabet?: Alphabet;
+    /** How long a code stays valid. Default `"5m"`. */
+    ttl?: Duration;
+    /** Failed attempts before the key is locked. Default 5. */
+    maxAttempts?: number;
+    /**
+     * How long a lockout persists. Independent of `ttl` on purpose: if the
+     * attempt counter expired alongside the code, a resend would refresh the
+     * attacker's guess budget and `maxAttempts` would be decorative.
+     * Default `"15m"`.
+     */
+    lockoutWindow?: Duration;
+    /**
+     * How long an expired record is retained past `ttl` so that `verify` can
+     * answer `"expired"` rather than `"invalid"`.
+     *
+     * Without this the record dies with its TTL and an expired code is
+     * indistinguishable from a wrong one, which denies the user the only
+     * message that tells them what to do ("request a new code"). Retention is
+     * safe: validity is decided by `expiresAt`, not by the record's existence.
+     *
+     * Set to a small value to reduce storage. Default `"10m"`.
+     */
+    expiredGrace?: Duration;
+    /** Minimum gap between issues for the same key. Default `"60s"`. */
+    resendCooldown?: Duration;
+    /** Cap on issues per key per window. Default 5 per hour. */
+    maxSendsPerKey?: RateWindow;
+    /**
+     * Cap on issues per caller-supplied scope (IP, device id, tenant).
+     * This is the limit that stops OTP-pumping fraud, where an attacker cycles
+     * through numbers to burn your SMS credit. Requires `scope` on `issue`.
+     * Default 20 per hour.
+     */
+    maxSendsPerScope?: RateWindow;
+    /** Reject `key`, `purpose`, `scope`, or `bindToken` longer than this. Default 256. */
+    maxInputLength?: number;
+    /** Namespace prefix for all store keys. Default `"otp"`. */
+    prefix?: string;
+    /** Observability callbacks. */
+    hooks?: Hooks;
+    /** Injectable clock. Intended for tests. */
+    now?: () => number;
+}
+interface IssueInput {
+    /** Identity being verified — phone number, email, user id. */
+    key: string;
+    /**
+     * Purpose scope. A code issued for one purpose will not verify another,
+     * so a phished login code cannot be replayed against a payment.
+     * Default `"default"`.
+     */
+    purpose?: string;
+    /** Rate-limit scope, typically `req.ip`. Enables `maxSendsPerScope`. */
+    scope?: string;
+    /**
+     * Binds the code to a session or device. The same value must be presented
+     * at verify, which narrows the window for an attacker who intercepts the
+     * code but not the session.
+     */
+    bindToken?: string;
+}
+type IssueResult = {
+    ok: true;
+    /**
+     * Plaintext code. Returned once and never stored. Send it; do not log
+     * it, and do not put it in an error message.
+     */
+    code: string;
+    expiresAt: number;
+    /** Epoch millis before which a resend will be refused. */
+    resendAfter: number;
+} | {
+    ok: false;
+    reason: 'cooldown' | 'rate_limited';
+    /** Epoch millis at which the caller may retry. */
+    retryAfter: number;
+};
+interface VerifyInput {
+    key: string;
+    code: string;
+    /** Must match the purpose the code was issued under. */
+    purpose?: string;
+    /** Required if the code was issued with a `bindToken`. */
+    bindToken?: string;
+}
+type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: VerifyFailure;
+    /** Attempts remaining before lockout, when knowable. */
+    attemptsLeft?: number;
+};
+interface OtpKit {
+    issue(input: IssueInput): Promise<IssueResult>;
+    verify(input: VerifyInput): Promise<VerifyResult>;
+    /** Clear the outstanding code, attempt counter, and lockout for a key. */
+    reset(key: string, purpose?: string): Promise<void>;
+    /** Release store-owned resources. */
+    close(): Promise<void>;
+}
+
+/**
+ * Create an OTP issuer/verifier.
+ *
+ * @example
+ * ```ts
+ * import { createOtpKit, memoryStore } from 'otp-guard';
+ *
+ * const otp = createOtpKit({
+ *   store: memoryStore(),
+ *   pepper: process.env.OTP_PEPPER!,
+ *   ttl: '5m',
+ *   maxAttempts: 5,
+ * });
+ *
+ * const issued = await otp.issue({ key: '+919812345678', purpose: 'login' });
+ * if (issued.ok) await sms.send(issued.code);
+ *
+ * const result = await otp.verify({
+ *   key: '+919812345678',
+ *   code: '123456',
+ *   purpose: 'login',
+ * });
+ * ```
+ *
+ * @throws {OtpConfigError} if the options are invalid.
+ */
+declare function createOtpKit(options: OtpKitOptions): OtpKit;
+
+interface MemoryStoreOptions {
+    /** Injectable clock. Intended for tests. */
+    now?: () => number;
+    /**
+     * Hard cap on retained entries. When exceeded, the soonest-expiring entries
+     * are dropped first. Prevents unbounded growth from codes that are issued
+     * and never verified. Default 100_000.
+     */
+    maxEntries?: number;
+    /** Sweep interval for expired entries in ms. Default 60_000. 0 disables. */
+    sweepIntervalMs?: number;
+}
+/**
+ * Process-local store.
+ *
+ * Suitable for tests, CLIs, and single-instance apps. NOT suitable behind a
+ * load balancer: counters live in one process's heap, so N instances means N
+ * times your intended rate limit.
+ *
+ * @example
+ * ```ts
+ * const otp = createOtpKit({ store: memoryStore(), pepper });
+ * ```
+ */
+declare function memoryStore(opts?: MemoryStoreOptions): OtpStore;
+
+/**
+ * Thrown when the underlying store fails.
+ *
+ * otp-guard fails closed: a store outage means codes cannot be issued or
+ * verified, never that verification silently succeeds. Catch this at your
+ * route layer and return 503.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await otp.verify({ key, code });
+ * } catch (err) {
+ *   if (err instanceof OtpStoreError) return reply.status(503).send();
+ *   throw err;
+ * }
+ * ```
+ */
+declare class OtpStoreError extends Error {
+    /** Which store operation failed, e.g. "acquire_cooldown". */
+    readonly operation: string;
+    constructor(operation: string, cause: unknown);
+}
+/**
+ * Thrown for caller mistakes: invalid configuration, malformed or oversized
+ * identifiers. Always a programming error, never a runtime condition to
+ * handle gracefully.
+ */
+declare class OtpConfigError extends Error {
+    constructor(message: string);
+}
+
+export { type Alphabet, type Duration, type HookEvent, type Hooks, type IssueInput, type IssueResult, type MemoryStoreOptions, OtpConfigError, type OtpKit, type OtpKitOptions, OtpStore, OtpStoreError, type RateWindow, type VerifyFailure, type VerifyInput, type VerifyResult, createOtpKit, memoryStore };

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { O as OtpStore } from './store-mOFmlT-6.js';
+export { a as OtpRecord } from './store-mOFmlT-6.js';
+
+/** Duration in milliseconds, or a short string: "30s", "5m", "2h", "1d". */
+type Duration = number | `${number}${'s' | 'm' | 'h' | 'd'}`;
+/**
+ * Character set for generated codes.
+ *
+ * - `numeric` — digits only. The right default for SMS.
+ * - `alphanumeric` — excludes I, L, O, U, 0, 1 to avoid transcription errors
+ *   when a code is read aloud or copied by hand.
+ * - `base32` — RFC 4648 alphabet, for codes that feed other systems.
+ */
+type Alphabet = 'numeric' | 'alphanumeric' | 'base32';
+interface RateWindow {
+    count: number;
+    window: Duration;
+}
+type VerifyFailure = 'invalid' | 'expired' | 'locked' | 'bind_mismatch';
+/** Metadata passed to observability hooks. */
+interface HookEvent {
+    /**
+     * The raw identity. Treat as personal data: do not ship it to an APM or
+     * third-party log sink. Use `keyHash` for that.
+     */
+    key: string;
+    /** Stable, non-reversible identifier derived from key and purpose. Safe to log. */
+    keyHash: string;
+    purpose: string;
+    scope?: string;
+}
+/**
+ * Observability callbacks.
+ *
+ * Hooks are advisory. Exceptions thrown inside them are swallowed, so a
+ * broken metrics pipeline cannot break authentication.
+ */
+interface Hooks {
+    onIssue?(e: HookEvent): void;
+    onRateLimited?(e: HookEvent & {
+        reason: 'cooldown' | 'rate_limited';
+        /** Which of the three limits rejected the request. */
+        limit: 'cooldown' | 'key' | 'scope';
+    }): void;
+    onVerifyFailure?(e: HookEvent & {
+        reason: VerifyFailure;
+        attempts: number;
+    }): void;
+    onLockout?(e: HookEvent): void;
+    onStoreError?(e: {
+        operation: string;
+        error: unknown;
+    }): void;
+}
+interface OtpKitOptions {
+    store: OtpStore;
+    /**
+     * Server-side secret mixed into every hash and every store key. Rotating it
+     * invalidates all outstanding codes, which is a legitimate emergency lever.
+     *
+     * Minimum 16 characters. Generate with:
+     * `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+     *
+     * Keep it out of the database the hashes live in — that separation is the
+     * entire point of a pepper.
+     */
+    pepper: string;
+    /** Characters per code. 4–32. Default 6. */
+    length?: number;
+    /** Character set. Default `"numeric"`. */
+    alphabet?: Alphabet;
+    /** How long a code stays valid. Default `"5m"`. */
+    ttl?: Duration;
+    /** Failed attempts before the key is locked. Default 5. */
+    maxAttempts?: number;
+    /**
+     * How long a lockout persists. Independent of `ttl` on purpose: if the
+     * attempt counter expired alongside the code, a resend would refresh the
+     * attacker's guess budget and `maxAttempts` would be decorative.
+     * Default `"15m"`.
+     */
+    lockoutWindow?: Duration;
+    /**
+     * How long an expired record is retained past `ttl` so that `verify` can
+     * answer `"expired"` rather than `"invalid"`.
+     *
+     * Without this the record dies with its TTL and an expired code is
+     * indistinguishable from a wrong one, which denies the user the only
+     * message that tells them what to do ("request a new code"). Retention is
+     * safe: validity is decided by `expiresAt`, not by the record's existence.
+     *
+     * Set to a small value to reduce storage. Default `"10m"`.
+     */
+    expiredGrace?: Duration;
+    /** Minimum gap between issues for the same key. Default `"60s"`. */
+    resendCooldown?: Duration;
+    /** Cap on issues per key per window. Default 5 per hour. */
+    maxSendsPerKey?: RateWindow;
+    /**
+     * Cap on issues per caller-supplied scope (IP, device id, tenant).
+     * This is the limit that stops OTP-pumping fraud, where an attacker cycles
+     * through numbers to burn your SMS credit. Requires `scope` on `issue`.
+     * Default 20 per hour.
+     */
+    maxSendsPerScope?: RateWindow;
+    /** Reject `key`, `purpose`, `scope`, or `bindToken` longer than this. Default 256. */
+    maxInputLength?: number;
+    /** Namespace prefix for all store keys. Default `"otp"`. */
+    prefix?: string;
+    /** Observability callbacks. */
+    hooks?: Hooks;
+    /** Injectable clock. Intended for tests. */
+    now?: () => number;
+}
+interface IssueInput {
+    /** Identity being verified — phone number, email, user id. */
+    key: string;
+    /**
+     * Purpose scope. A code issued for one purpose will not verify another,
+     * so a phished login code cannot be replayed against a payment.
+     * Default `"default"`.
+     */
+    purpose?: string;
+    /** Rate-limit scope, typically `req.ip`. Enables `maxSendsPerScope`. */
+    scope?: string;
+    /**
+     * Binds the code to a session or device. The same value must be presented
+     * at verify, which narrows the window for an attacker who intercepts the
+     * code but not the session.
+     */
+    bindToken?: string;
+}
+type IssueResult = {
+    ok: true;
+    /**
+     * Plaintext code. Returned once and never stored. Send it; do not log
+     * it, and do not put it in an error message.
+     */
+    code: string;
+    expiresAt: number;
+    /** Epoch millis before which a resend will be refused. */
+    resendAfter: number;
+} | {
+    ok: false;
+    reason: 'cooldown' | 'rate_limited';
+    /** Epoch millis at which the caller may retry. */
+    retryAfter: number;
+};
+interface VerifyInput {
+    key: string;
+    code: string;
+    /** Must match the purpose the code was issued under. */
+    purpose?: string;
+    /** Required if the code was issued with a `bindToken`. */
+    bindToken?: string;
+}
+type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: VerifyFailure;
+    /** Attempts remaining before lockout, when knowable. */
+    attemptsLeft?: number;
+};
+interface OtpKit {
+    issue(input: IssueInput): Promise<IssueResult>;
+    verify(input: VerifyInput): Promise<VerifyResult>;
+    /** Clear the outstanding code, attempt counter, and lockout for a key. */
+    reset(key: string, purpose?: string): Promise<void>;
+    /** Release store-owned resources. */
+    close(): Promise<void>;
+}
+
+/**
+ * Create an OTP issuer/verifier.
+ *
+ * @example
+ * ```ts
+ * import { createOtpKit, memoryStore } from 'otp-guard';
+ *
+ * const otp = createOtpKit({
+ *   store: memoryStore(),
+ *   pepper: process.env.OTP_PEPPER!,
+ *   ttl: '5m',
+ *   maxAttempts: 5,
+ * });
+ *
+ * const issued = await otp.issue({ key: '+919812345678', purpose: 'login' });
+ * if (issued.ok) await sms.send(issued.code);
+ *
+ * const result = await otp.verify({
+ *   key: '+919812345678',
+ *   code: '123456',
+ *   purpose: 'login',
+ * });
+ * ```
+ *
+ * @throws {OtpConfigError} if the options are invalid.
+ */
+declare function createOtpKit(options: OtpKitOptions): OtpKit;
+
+interface MemoryStoreOptions {
+    /** Injectable clock. Intended for tests. */
+    now?: () => number;
+    /**
+     * Hard cap on retained entries. When exceeded, the soonest-expiring entries
+     * are dropped first. Prevents unbounded growth from codes that are issued
+     * and never verified. Default 100_000.
+     */
+    maxEntries?: number;
+    /** Sweep interval for expired entries in ms. Default 60_000. 0 disables. */
+    sweepIntervalMs?: number;
+}
+/**
+ * Process-local store.
+ *
+ * Suitable for tests, CLIs, and single-instance apps. NOT suitable behind a
+ * load balancer: counters live in one process's heap, so N instances means N
+ * times your intended rate limit.
+ *
+ * @example
+ * ```ts
+ * const otp = createOtpKit({ store: memoryStore(), pepper });
+ * ```
+ */
+declare function memoryStore(opts?: MemoryStoreOptions): OtpStore;
+
+/**
+ * Thrown when the underlying store fails.
+ *
+ * otp-guard fails closed: a store outage means codes cannot be issued or
+ * verified, never that verification silently succeeds. Catch this at your
+ * route layer and return 503.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await otp.verify({ key, code });
+ * } catch (err) {
+ *   if (err instanceof OtpStoreError) return reply.status(503).send();
+ *   throw err;
+ * }
+ * ```
+ */
+declare class OtpStoreError extends Error {
+    /** Which store operation failed, e.g. "acquire_cooldown". */
+    readonly operation: string;
+    constructor(operation: string, cause: unknown);
+}
+/**
+ * Thrown for caller mistakes: invalid configuration, malformed or oversized
+ * identifiers. Always a programming error, never a runtime condition to
+ * handle gracefully.
+ */
+declare class OtpConfigError extends Error {
+    constructor(message: string);
+}
+
+export { type Alphabet, type Duration, type HookEvent, type Hooks, type IssueInput, type IssueResult, type MemoryStoreOptions, OtpConfigError, type OtpKit, type OtpKitOptions, OtpStore, OtpStoreError, type RateWindow, type VerifyFailure, type VerifyInput, type VerifyResult, createOtpKit, memoryStore };