@exortek/challenge 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+/**
+ * `@exortek/challenge` — signed, single-use challenge tokens for
+ * multi-step auth flows.
+ *
+ * A challenge is a small, HMAC-signed envelope that carries context
+ * across a redirect or a follow-up request without a server-side
+ * session: who is being challenged (`userId`), how they proved
+ * themselves so far (`method`), what step of the flow they've cleared
+ * (`step`), and any bespoke metadata the caller needs on the other
+ * side. The token is stateless by default; single-use enforcement and
+ * revocation are opt-in via a store the caller supplies.
+ *
+ * See the README for the full API and worked examples.
+ */
+export { ChallengeError, ErrorCode } from './errors.js';
+export type ChallengeMethod = 'totp' | 'hotp' | 'email_otp' | 'sms_otp' | 'backup_code' | 'passkey' | 'magic_link' | 'password' | 'webauthn' | 'oauth' | 'oidc' | string;
+export type IncrStore = {
+    /**
+     *   Atomic increment-with-expiry. First call returns `{ count: 1 }` and
+     *   arms a TTL; subsequent calls before expiry return the incremented
+     *   count. Used as compare-and-set for single-use enforcement.
+     */
+    incr: (key: string, ttlMs: number) => Promise<{
+        count: number;
+    }>;
+};
+export type ChallengePayload = {
+    jti: string;
+    iat: number;
+    exp: number;
+    userId?: string;
+    method?: ChallengeMethod;
+    step?: string;
+    nextStep?: string;
+    /**
+     * Only set when `ipBinding: true`.
+     */
+    ip?: string;
+    /**
+     * Only set when `ua` supplied.
+     */
+    ua?: string;
+    meta?: Record<string, unknown>;
+};
+export type CreateChallengeOptions = {
+    /**
+     *   HMAC-SHA256 secret. **Must be at least 32 raw bytes.** A string is
+     *   interpreted as UTF-8 — for a hex or base64 secret, decode to
+     *   Buffer first.
+     */
+    secret: string | Buffer | Uint8Array;
+    userId?: string;
+    method?: ChallengeMethod;
+    step?: string;
+    nextStep?: string;
+    ip?: string;
+    ua?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Duration string (`'5m'`) or ms integer.
+     */
+    expiresIn: string | number;
+    /**
+     * When true, the returned token can only be verified once — subsequent
+     * verifies with `consume: true` fail with `reason: 'replay'`. Requires
+     * `store` to be supplied.
+     */
+    singleUse?: boolean;
+    /**
+     * Any object exposing `incr(key, ttlMs) → { count }`. Compatible with
+     * `@exortek/security`'s rate-limit stores; also easy to wrap Redis.
+     */
+    store?: IncrStore;
+    /**
+     * When true, the caller-supplied `ip` is stamped into the payload and
+     * `verifyChallenge` will reject a request whose `ip` differs.
+     */
+    ipBinding?: boolean;
+    /**
+     * Wire-format prefix. Defaults to `'chall_v1'` — the value shipped
+     * with this package. Callers can override to brand the token
+     * family (e.g. `'server_challenge'`, `'myapp_v1'`); must match
+     * `/^[A-Za-z0-9_-]{1,32}$/`. The same prefix must be passed at
+     * verify time or verification returns `reason: 'malformed'`.
+     */
+    prefix?: string;
+    /**
+     * Override `Date.now()` for testing.
+     */
+    now?: number;
+};
+export type VerifyChallengeOptions = {
+    secret: string | Buffer | Uint8Array;
+    /**
+     * Enforce single-use. Requires `store` (typically the same one used
+     * at create time).
+     */
+    consume?: boolean;
+    store?: IncrStore;
+    expectedUserId?: string;
+    expectedMethod?: ChallengeMethod;
+    expectedStep?: string;
+    expectedNextStep?: string;
+    /**
+     * The current request's IP. Required to verify a token that was
+     * created with `ipBinding: true`; ignored otherwise.
+     */
+    ip?: string;
+    /**
+     * Wire-format prefix. Must match the value passed to
+     * `createChallenge` — a token minted with a different prefix will
+     * fail with `reason: 'malformed'`.
+     */
+    prefix?: string;
+    /**
+     * Override `Date.now()` for testing.
+     */
+    now?: number;
+};
+export type VerifyFailureReason = 'malformed' | 'bad_signature' | 'expired' | 'not_yet_valid' | 'user_mismatch' | 'method_mismatch' | 'step_mismatch' | 'next_step_mismatch' | 'ip_mismatch' | 'ip_missing' | 'replay' | 'store_unavailable';
+export type VerifyChallengeResult = {
+    valid: true;
+    payload: ChallengePayload;
+} | {
+    valid: false;
+    reason: VerifyFailureReason;
+};
+/**
+ * @typedef {'totp' | 'hotp' | 'email_otp' | 'sms_otp' | 'backup_code'
+ *   | 'passkey' | 'magic_link' | 'password' | 'webauthn' | 'oauth' | 'oidc'
+ *   | string} ChallengeMethod
+ */
+/**
+ * @typedef {object} IncrStore
+ * @property {(key: string, ttlMs: number) => Promise<{ count: number }>} incr
+ *   Atomic increment-with-expiry. First call returns `{ count: 1 }` and
+ *   arms a TTL; subsequent calls before expiry return the incremented
+ *   count. Used as compare-and-set for single-use enforcement.
+ */
+/**
+ * @typedef {object} ChallengePayload
+ * @property {string} jti
+ * @property {number} iat
+ * @property {number} exp
+ * @property {string} [userId]
+ * @property {ChallengeMethod} [method]
+ * @property {string} [step]
+ * @property {string} [nextStep]
+ * @property {string} [ip]                      Only set when `ipBinding: true`.
+ * @property {string} [ua]                      Only set when `ua` supplied.
+ * @property {Record<string, unknown>} [meta]
+ */
+/**
+ * @typedef {object} CreateChallengeOptions
+ * @property {string | Buffer | Uint8Array} secret
+ *   HMAC-SHA256 secret. **Must be at least 32 raw bytes.** A string is
+ *   interpreted as UTF-8 — for a hex or base64 secret, decode to
+ *   Buffer first.
+ * @property {string} [userId]
+ * @property {ChallengeMethod} [method]
+ * @property {string} [step]
+ * @property {string} [nextStep]
+ * @property {string} [ip]
+ * @property {string} [ua]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {string | number} expiresIn        Duration string (`'5m'`) or ms integer.
+ * @property {boolean} [singleUse=false]
+ *   When true, the returned token can only be verified once — subsequent
+ *   verifies with `consume: true` fail with `reason: 'replay'`. Requires
+ *   `store` to be supplied.
+ * @property {IncrStore} [store]
+ *   Any object exposing `incr(key, ttlMs) → { count }`. Compatible with
+ *   `@exortek/security`'s rate-limit stores; also easy to wrap Redis.
+ * @property {boolean} [ipBinding=false]
+ *   When true, the caller-supplied `ip` is stamped into the payload and
+ *   `verifyChallenge` will reject a request whose `ip` differs.
+ * @property {string} [prefix='chall_v1']
+ *   Wire-format prefix. Defaults to `'chall_v1'` — the value shipped
+ *   with this package. Callers can override to brand the token
+ *   family (e.g. `'server_challenge'`, `'myapp_v1'`); must match
+ *   `/^[A-Za-z0-9_-]{1,32}$/`. The same prefix must be passed at
+ *   verify time or verification returns `reason: 'malformed'`.
+ * @property {number} [now]                     Override `Date.now()` for testing.
+ */
+/**
+ * @typedef {object} VerifyChallengeOptions
+ * @property {string | Buffer | Uint8Array} secret
+ * @property {boolean} [consume=false]
+ *   Enforce single-use. Requires `store` (typically the same one used
+ *   at create time).
+ * @property {IncrStore} [store]
+ * @property {string} [expectedUserId]
+ * @property {ChallengeMethod} [expectedMethod]
+ * @property {string} [expectedStep]
+ * @property {string} [expectedNextStep]
+ * @property {string} [ip]
+ *   The current request's IP. Required to verify a token that was
+ *   created with `ipBinding: true`; ignored otherwise.
+ * @property {string} [prefix='chall_v1']
+ *   Wire-format prefix. Must match the value passed to
+ *   `createChallenge` — a token minted with a different prefix will
+ *   fail with `reason: 'malformed'`.
+ * @property {number} [now]                     Override `Date.now()` for testing.
+ */
+/**
+ * @typedef {'malformed' | 'bad_signature' | 'expired' | 'not_yet_valid'
+ *   | 'user_mismatch' | 'method_mismatch' | 'step_mismatch'
+ *   | 'next_step_mismatch' | 'ip_mismatch' | 'ip_missing' | 'replay'
+ *   | 'store_unavailable'} VerifyFailureReason
+ */
+/**
+ * @typedef {{ valid: true, payload: ChallengePayload }
+ *   | { valid: false, reason: VerifyFailureReason }} VerifyChallengeResult
+ */
+/**
+ * Create a signed challenge token.
+ *
+ *   const token = await createChallenge({
+ *     secret: process.env.CHALLENGE_SECRET,
+ *     userId: 'usr_123',
+ *     method: 'totp',
+ *     step: 'mfa_verified',
+ *     nextStep: 'login',
+ *     expiresIn: '5m',
+ *     singleUse: true,
+ *     store,
+ *   })
+ *
+ * @param {CreateChallengeOptions} options
+ * @returns {Promise<string>}
+ */
+export declare function createChallenge(options: CreateChallengeOptions): Promise<string>;
+/**
+ * Verify a challenge token. Returns `{ valid: true, payload }` on
+ * success or `{ valid: false, reason }` on any expected failure. Only
+ * throws on programmer errors (bad options, missing secret).
+ *
+ *   const res = await verifyChallenge(token, {
+ *     secret: process.env.CHALLENGE_SECRET,
+ *     consume: true,
+ *     store,
+ *     expectedUserId: pendingUserId,
+ *     expectedMethod: 'totp',
+ *     ip: req.ip,
+ *   })
+ *   if (!res.valid) return reply.code(401).send({ error: res.reason })
+ *
+ * @param {string} token
+ * @param {VerifyChallengeOptions} options
+ * @returns {Promise<VerifyChallengeResult>}
+ */
+export declare function verifyChallenge(token: string, options: VerifyChallengeOptions): Promise<VerifyChallengeResult>;