otp-guard 0.1.0

package/dist/redis.js

@@ -0,0 +1,69 @@
+// src/stores/redis.ts
+function makeEval(client) {
+  const isNodeRedis = typeof client.pTTL === "function";
+  return async (script, keys, args) => {
+    if (isNodeRedis) {
+      return client.eval(script, { keys, arguments: args });
+    }
+    return client.eval(
+      script,
+      keys.length,
+      ...keys,
+      ...args
+    );
+  };
+}
+var SET_PX = `return redis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))`;
+var SET_NX_PX = `
+if redis.call('SET', KEYS[1], '1', 'NX', 'PX', tonumber(ARGV[1])) then
+  return 1
+end
+return 0`;
+var INCR_WINDOW = `
+local v = redis.call('INCR', KEYS[1])
+if v == 1 then redis.call('PEXPIRE', KEYS[1], tonumber(ARGV[1])) end
+return v`;
+var DECR_SAFE = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end
+local v = redis.call('DECR', KEYS[1])
+if v < 0 then redis.call('SET', KEYS[1], '0', 'KEEPTTL') return 0 end
+return v`;
+function redisStore(client) {
+  const run = makeEval(client);
+  const pttl = (key) => (client.pTTL ?? client.pttl).call(client, key);
+  return {
+    async get(key) {
+      const raw = await client.get(key);
+      if (!raw) return null;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        await client.del(key);
+        return null;
+      }
+    },
+    async set(key, record, ttlMs) {
+      await run(SET_PX, [key], [JSON.stringify(record), String(Math.ceil(ttlMs))]);
+    },
+    async del(key) {
+      await client.del(key);
+    },
+    async bumpCounter(key, ttlMs) {
+      return Number(await run(INCR_WINDOW, [key], [String(Math.ceil(ttlMs))]));
+    },
+    async decrCounter(key) {
+      await run(DECR_SAFE, [key], []);
+    },
+    async acquire(key, ttlMs) {
+      return Number(await run(SET_NX_PX, [key], [String(Math.ceil(ttlMs))])) === 1;
+    },
+    async ttl(key) {
+      const v = await pttl(key);
+      return v > 0 ? v : 0;
+    }
+  };
+}
+
+export { redisStore };
+//# sourceMappingURL=redis.js.map
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stores/redis.ts"],"names":[],"mappings":"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","file":"redis.js","sourcesContent":["import type { OtpRecord, OtpStore } from '../store.js';\n\n/**\n * Structural type satisfied by both `redis` v4+ and `ioredis`, so otp-guard\n * needs no Redis dependency of its own and works with whichever client the\n * host app already has.\n */\nexport interface RedisLike {\n  get(key: string): Promise<string | null>;\n  del(key: string): Promise<unknown>;\n  eval(script: string, ...args: unknown[]): Promise<unknown>;\n  set?(key: string, value: string, options?: unknown): Promise<unknown>;\n  pTTL?(key: string): Promise<number>;\n  pttl?(key: string): Promise<number>;\n}\n\n/**\n * The two clients disagree on `eval`'s signature:\n *\n * - ioredis:    `eval(script, numkeys, ...keys, ...args)`\n * - node-redis: `eval(script, { keys, arguments })`\n *\n * Detected once at construction rather than sniffed on every call. Both\n * branches are covered by the integration suite — this is the single most\n * likely place for a \"works on my machine\" bug.\n */\nfunction makeEval(client: RedisLike) {\n  const isNodeRedis = typeof client.pTTL === 'function';\n  return async (script: string, keys: string[], args: string[]): Promise<unknown> => {\n    if (isNodeRedis) {\n      return client.eval(script, { keys, arguments: args } as never);\n    }\n    return (client.eval as (...a: unknown[]) => Promise<unknown>)(\n      script,\n      keys.length,\n      ...keys,\n      ...args,\n    );\n  };\n}\n\n/**\n * Atomic set-with-expiry. One round trip, so there is never a window in which\n * a record exists without a TTL — that window would be a permanently valid\n * one-time code.\n */\nconst SET_PX = `return redis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))`;\n\n/**\n * Atomic test-and-set. Returns 1 only for the caller that took the lock,\n * which is what makes the resend cooldown race-free across instances.\n */\nconst SET_NX_PX = `\nif redis.call('SET', KEYS[1], '1', 'NX', 'PX', tonumber(ARGV[1])) then\n  return 1\nend\nreturn 0`;\n\n/** Increment, setting expiry only on the first increment: a fixed window. */\nconst INCR_WINDOW = `\nlocal v = redis.call('INCR', KEYS[1])\nif v == 1 then redis.call('PEXPIRE', KEYS[1], tonumber(ARGV[1])) end\nreturn v`;\n\n/** Decrement without resurrecting an expired key or dropping below zero. */\nconst DECR_SAFE = `\nif redis.call('EXISTS', KEYS[1]) == 0 then return 0 end\nlocal v = redis.call('DECR', KEYS[1])\nif v < 0 then redis.call('SET', KEYS[1], '0', 'KEEPTTL') return 0 end\nreturn v`;\n\n/**\n * Redis-backed store. The correct choice for anything running more than one\n * process, since all state and counters are shared.\n *\n * @example\n * ```ts\n * import { createOtpKit } from 'otp-guard';\n * import { redisStore } from 'otp-guard/redis';\n *\n * const otp = createOtpKit({ store: redisStore(redis), pepper });\n * ```\n */\nexport function redisStore(client: RedisLike): OtpStore {\n  const run = makeEval(client);\n  const pttl = (key: string) =>\n    (client.pTTL ?? client.pttl)!.call(client, key) as Promise<number>;\n\n  return {\n    async get(key) {\n      const raw = await client.get(key);\n      if (!raw) return null;\n      try {\n        return JSON.parse(raw) as OtpRecord;\n      } catch {\n        // A corrupt or foreign value in our namespace: clear it and treat the\n        // code as absent, rather than throwing on every subsequent verify.\n        await client.del(key);\n        return null;\n      }\n    },\n    async set(key, record, ttlMs) {\n      await run(SET_PX, [key], [JSON.stringify(record), String(Math.ceil(ttlMs))]);\n    },\n    async del(key) {\n      await client.del(key);\n    },\n    async bumpCounter(key, ttlMs) {\n      return Number(await run(INCR_WINDOW, [key], [String(Math.ceil(ttlMs))]));\n    },\n    async decrCounter(key) {\n      await run(DECR_SAFE, [key], []);\n    },\n    async acquire(key, ttlMs) {\n      return Number(await run(SET_NX_PX, [key], [String(Math.ceil(ttlMs))])) === 1;\n    },\n    async ttl(key) {\n      const v = await pttl(key);\n      return v > 0 ? v : 0;\n    },\n  };\n}\n"]}

package/dist/store-mOFmlT-6.d.cts

@@ -0,0 +1,49 @@
+/**
+ * What is persisted for an outstanding code.
+ *
+ * The plaintext code never appears here — only its HMAC.
+ */
+interface OtpRecord {
+    /** HMAC of the code, bound to its identity and purpose. */
+    hash: string;
+    /** Epoch millis at which the code stops being valid. */
+    expiresAt: number;
+    /** HMAC of a token that must be replayed at verify time, if bound. */
+    bindHash?: string;
+}
+/**
+ * Storage contract.
+ *
+ * Implementations MUST guarantee the following. These are not performance
+ * suggestions — each one closes a specific attack.
+ *
+ * - `set` writes value and expiry atomically. A window in which a record
+ *   exists without a TTL is a permanently valid one-time code.
+ * - `acquire` is atomic test-and-set. Two concurrent callers must never both
+ *   receive `true`. This is what makes the resend cooldown race-free, and
+ *   therefore what stops one user action sending two SMS.
+ * - `bumpCounter` increments atomically and sets the expiry only on the first
+ *   increment, giving a fixed window rather than a sliding one.
+ * - `decrCounter` must not resurrect an expired key or go below zero.
+ *
+ * A store that satisfies these on a single process (see `memoryStore`) is
+ * still only safe for a single process: counters that live in one instance's
+ * heap multiply your effective rate limit by your instance count.
+ */
+interface OtpStore {
+    get(key: string): Promise<OtpRecord | null>;
+    set(key: string, record: OtpRecord, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /** Atomic increment with fixed-window expiry. Returns the new value. */
+    bumpCounter(key: string, ttlMs: number): Promise<number>;
+    /** Compensating decrement, used to refund quota when issuing fails. */
+    decrCounter(key: string): Promise<void>;
+    /** Atomic test-and-set. True only for the caller that took the lock. */
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+    /** Remaining ttl in ms, or 0 if absent. */
+    ttl(key: string): Promise<number>;
+    /** Release owned resources (timers, connections). Optional. */
+    close?(): Promise<void> | void;
+}
+
+export type { OtpStore as O, OtpRecord as a };

package/dist/store-mOFmlT-6.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What is persisted for an outstanding code.
+ *
+ * The plaintext code never appears here — only its HMAC.
+ */
+interface OtpRecord {
+    /** HMAC of the code, bound to its identity and purpose. */
+    hash: string;
+    /** Epoch millis at which the code stops being valid. */
+    expiresAt: number;
+    /** HMAC of a token that must be replayed at verify time, if bound. */
+    bindHash?: string;
+}
+/**
+ * Storage contract.
+ *
+ * Implementations MUST guarantee the following. These are not performance
+ * suggestions — each one closes a specific attack.
+ *
+ * - `set` writes value and expiry atomically. A window in which a record
+ *   exists without a TTL is a permanently valid one-time code.
+ * - `acquire` is atomic test-and-set. Two concurrent callers must never both
+ *   receive `true`. This is what makes the resend cooldown race-free, and
+ *   therefore what stops one user action sending two SMS.
+ * - `bumpCounter` increments atomically and sets the expiry only on the first
+ *   increment, giving a fixed window rather than a sliding one.
+ * - `decrCounter` must not resurrect an expired key or go below zero.
+ *
+ * A store that satisfies these on a single process (see `memoryStore`) is
+ * still only safe for a single process: counters that live in one instance's
+ * heap multiply your effective rate limit by your instance count.
+ */
+interface OtpStore {
+    get(key: string): Promise<OtpRecord | null>;
+    set(key: string, record: OtpRecord, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /** Atomic increment with fixed-window expiry. Returns the new value. */
+    bumpCounter(key: string, ttlMs: number): Promise<number>;
+    /** Compensating decrement, used to refund quota when issuing fails. */
+    decrCounter(key: string): Promise<void>;
+    /** Atomic test-and-set. True only for the caller that took the lock. */
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+    /** Remaining ttl in ms, or 0 if absent. */
+    ttl(key: string): Promise<number>;
+    /** Release owned resources (timers, connections). Optional. */
+    close?(): Promise<void> | void;
+}
+
+export type { OtpStore as O, OtpRecord as a };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "otp-guard",
+  "version": "0.1.0",
+  "description": "Secure one-time passcodes for Node: hashed storage, constant-time verify, single use, and the three rate limits everyone forgets.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js",
+      "require": "./dist/redis.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:integration": "REDIS_URL=redis://127.0.0.1:6379 vitest run",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build"
+  },
+  "keywords": [
+    "otp",
+    "one-time-password",
+    "otp-verification",
+    "2fa",
+    "mfa",
+    "sms-otp",
+    "email-otp",
+    "authentication",
+    "rate-limit",
+    "redis"
+  ],
+  "license": "MIT",
+  "author": "Deepak Chauhan <deepak@vocso.com> (https://www.vocso.com)",
+  "homepage": "https://github.com/vocso-com/otp-guard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vocso-com/otp-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vocso-com/otp-guard/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@redis/client": "^1.6.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.39.5",
+    "ioredis": "^5.4.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^2.1.0"
+  }
+}