otp-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepak Chauhan / VOCSO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# otp-guard
+
+Secure one-time passcodes for Node. Generate, hash, verify, rate-limit — nothing else.
+
+Zero runtime dependencies. ESM and CJS. Works with Redis, memory, or your own store.
+
+```bash
+npm i otp-guard
+```
+
+No SMS providers, no email templates, no framework coupling. You get a code back; sending it is your job.
+
+---
+
+## Most OTP implementations have at least three of these bugs
+
+| Bug | What it costs you | How otp-guard handles it |
+|---|---|---|
+| Codes stored in plaintext | A database dump hands over every live code | HMAC-SHA256 with a server-side pepper |
+| `Math.random()` | Predictable codes | `crypto.randomInt`, rejection-sampled |
+| `===` on the code | Timing side channel | Constant-time comparison |
+| Code reusable after success | Replay attacks | Deleted on first successful verify |
+| Attempt cap resets on resend | The cap is decorative | Lockout tracked per key, on its own window |
+| Rate limit only on verify | OTP-pumping burns your SMS budget | Independent caps per key **and** per scope |
+| One code works for any action | A login code authorises a withdrawal | Purpose scoping |
+| Different response for unknown users | Account enumeration | Identical shape and timing on both paths |
+| `SET` then `EXPIRE` | A crash between them leaves a permanent code | Single atomic command |
+| "Expired" reported as "invalid" | User never learns to request a new code | Records retained briefly past expiry |
+| Check-then-set cooldown | Concurrent requests send two SMS | Atomic test-and-set |
+| Identities as cache keys | Phone numbers sitting in Redis | Keys are HMACs, never the raw identity |
+
+## How this differs from otplib, otpauth, and speakeasy
+
+Those libraries implement **TOTP and HOTP** — the algorithms behind Google
+Authenticator and hardware tokens. They generate a code from a shared secret
+and a counter, and verify it statelessly.
+
+otp-guard solves the other problem: **delivered codes**. A random code you send
+over SMS, email, or WhatsApp, which has to be stored, expired, rate-limited,
+locked out, and consumed exactly once. That lifecycle is where the bugs above
+live, and none of it is in scope for a TOTP library.
+
+If you need authenticator-app support, use otplib. If you need "we texted you a
+code", use this. Plenty of apps need both.
+
+## Usage
+
+```ts
+import { createOtpKit } from 'otp-guard';
+import { redisStore } from 'otp-guard/redis';   // subpath: core stays Redis-free
+
+const otp = createOtpKit({
+  store: redisStore(redis),
+  pepper: process.env.OTP_PEPPER!,        // 16+ chars, from your secrets manager
+  length: 6,
+  ttl: '5m',
+  maxAttempts: 5,
+  lockoutWindow: '15m',
+  resendCooldown: '60s',
+  maxSendsPerKey: { count: 5, window: '1h' },
+  maxSendsPerScope: { count: 20, window: '1h' },
+});
+```
+
+### Issue
+
+```ts
+const res = await otp.issue({
+  key: '+919812345678',
+  purpose: 'login',
+  scope: req.ip,
+});
+
+if (!res.ok) {
+  return reply.status(429).send({ retryAfter: res.retryAfter });
+}
+
+await sms.send(res.code);   // returned once, never stored — do not log it
+```
+
+### Verify
+
+```ts
+const result = await otp.verify({
+  key: '+919812345678',
+  code: req.body.code,
+  purpose: 'login',
+});
+
+if (!result.ok) {
+  // 'invalid' | 'expired' | 'locked' | 'bind_mismatch'
+}
+```
+
+### Reset
+
+```ts
+await otp.reset('+919812345678', 'login');   // clears code, attempts, lockout
+```
+
+## Purpose scoping
+
+A code issued for `login` will not verify against `txn:withdraw`. Use a distinct
+purpose for every action that matters, so a phished login code cannot be replayed
+against a payment.
+
+## Session binding
+
+Pass a `bindToken` at issue time and the same value must be presented at verify.
+This stops an attacker who intercepts the code from redeeming it from their own
+session.
+
+```ts
+await otp.issue({ key, bindToken: session.id });
+await otp.verify({ key, code, bindToken: session.id });
+```
+
+## Rate limiting
+
+Three independent limits, because they stop three different attacks:
+
+| Limit | Stops | Default |
+|---|---|---|
+| `resendCooldown` | Users hammering "resend" | 60s |
+| `maxSendsPerKey` | Targeted harassment of one number | 5 / hour |
+| `maxSendsPerScope` | OTP-pumping fraud against your SMS budget | 20 / hour |
+
+The third is the one people skip and the one that produces a surprise invoice.
+Pass `scope: req.ip` (or a device id) to enable it.
+
+If a request is rejected, no quota is consumed — the cooldown is released and
+counters are refunded. The same holds if the store throws mid-issue.
+
+## Observability
+
+```ts
+createOtpKit({
+  hooks: {
+    onIssue: (e) => metrics.increment('otp.issued', { purpose: e.purpose }),
+    onLockout: (e) => log.warn({ keyHash: e.keyHash }, 'otp lockout'),
+    onRateLimited: (e) => metrics.increment('otp.limited', { limit: e.limit }),
+    onVerifyFailure: (e) => metrics.increment('otp.failed', { reason: e.reason }),
+    onStoreError: (e) => log.error(e, 'otp store error'),
+  },
+});
+```
+
+Every event carries `keyHash`, a stable non-reversible identifier that is safe
+to send to your APM. The raw `key` is also present — treat it as personal data
+and do not ship it off-box.
+
+Hooks are advisory: exceptions thrown inside them are swallowed, so a broken
+metrics pipeline cannot break authentication.
+
+## Failure policy
+
+otp-guard **fails closed**. If the store is unreachable, `issue` and `verify` both
+throw `OtpStoreError` rather than degrading open. Catch it at your route layer
+and return a 503 — never treat a store outage as a successful verification.
+
+```ts
+import { OtpStoreError } from 'otp-guard';
+
+try {
+  await otp.verify({ key, code });
+} catch (err) {
+  if (err instanceof OtpStoreError) return reply.status(503).send();
+  throw err;
+}
+```
+
+## Project layout
+
+```
+src/
+  otp.ts          createOtpKit — wiring only
+  runtime.ts      resolved config, key derivation, hook dispatch, store guard
+  issue.ts        reserve slot -> consume quota -> persist
+  verify.ts       lockout -> record -> binding -> comparison
+  crypto.ts       code generation, HMACs, constant-time compare
+  store.ts        the OtpStore contract and its atomicity requirements
+  errors.ts       OtpStoreError, OtpConfigError
+  types.ts        public options and results
+  stores/         memory and redis implementations
+```
+
+Runnable integrations for Express and Fastify are in [`examples/`](./examples).
+
+## Stores
+
+| Store | Use for |
+|---|---|
+| `memoryStore()` | Tests, CLIs, single-instance apps |
+| `redisStore(client)` | Anything running more than one process |
+
+`redisStore` is typed structurally and works with both `redis` v4+ and `ioredis`;
+both are covered by the integration suite. All multi-step operations run as Lua
+so they are atomic across instances.
+
+`memoryStore` sweeps expired entries on a timer and caps retained entries
+(default 100k) so it cannot grow without bound. Its counters are per-process, so
+behind a load balancer your effective rate limit is multiplied by your instance
+count. Don't use it there.
+
+For anything else — Postgres, DynamoDB, Cloudflare KV — implement `OtpStore`.
+The contract each method must satisfy is documented in `src/types.ts`; the
+atomicity requirements are not optional.
+
+## Choosing a pepper
+
+A random 32-byte hex string from your secrets manager:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Rotating it invalidates every outstanding code, which is a legitimate emergency
+lever. Keep it out of the database the hashes live in — that separation is the
+entire point.
+
+## Why not bcrypt or argon2?
+
+A 6-digit numeric code has a keyspace of 10⁶. A slow KDF adds real latency to
+every verify while barely raising the offline-cracking bar. The defences that
+actually matter are the short TTL, the attempt cap, and keeping the pepper
+outside the database.
+
+## Threat model
+
+**Handled:** database compromise, timing attacks, replay, brute force, account
+enumeration, OTP-pumping, cross-purpose replay, cross-instance races, key
+injection via crafted identities.
+
+**Not handled, by design:**
+
+- An attacker who controls the delivery channel — SIM swap, mailbox takeover,
+  malicious carrier. No OTP library can fix this; `bindToken` narrows it.
+- Clock skew between your instances. Codes expire on wall-clock time; keep NTP
+  running.
+- Denial of service against your own store.
+- Phishing. A user who reads their code to an attacker has defeated every
+  control here.
+
+## Not in scope
+
+Delivery (SMS, email, WhatsApp), TOTP/authenticator apps, magic links, and
+backup codes. Each is a different problem with a different failure mode.
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Security reports go to
+[SECURITY.md](./SECURITY.md), not the issue tracker.
+
+---
+
+Built and maintained by **[VOCSO](https://www.vocso.com)** — a product
+engineering team that has shipped authentication for fintech, marketplaces, and
+SaaS across India.
+
+More on building auth that survives an audit: [vocso.com/blog](https://www.vocso.com/blog/)