@otp-service/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 otp-service contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,100 @@
+type OtpChannel = "email" | "sms";
+interface ChallengeRecord {
+    attemptsRemaining: number;
+    channel: OtpChannel;
+    challengeId: string;
+    createdAt: Date;
+    expiresAt: Date;
+    otpHash: string;
+    purpose: string;
+    recipient: string;
+}
+interface ChallengeStore {
+    create(record: ChallengeRecord): Promise<void>;
+    delete(challengeId: string): Promise<void>;
+    get(challengeId: string): Promise<ChallengeRecord | null>;
+    update(record: ChallengeRecord): Promise<void>;
+}
+interface DeliveryRequest {
+    challengeId: string;
+    channel: OtpChannel;
+    expiresAt: Date;
+    otp: string;
+    purpose: string;
+    recipient: string;
+}
+interface OtpDelivery {
+    sendChallenge(request: DeliveryRequest): Promise<void>;
+}
+type OtpDeliveryOutcome = "DEFINITIVE_FAILURE" | "OUTCOME_UNKNOWN";
+declare class OtpDeliveryError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    readonly deliveryOutcome: OtpDeliveryOutcome;
+    readonly provider: string;
+    readonly retryable: boolean;
+    constructor(input: {
+        cause?: unknown;
+        code: string;
+        deliveryOutcome: OtpDeliveryOutcome;
+        message: string;
+        provider: string;
+        retryable: boolean;
+    });
+}
+interface OtpSigner {
+    hash(otp: string): string;
+    verify(otp: string, otpHash: string): boolean;
+}
+interface OtpPolicy {
+    maxVerifyAttempts: number;
+    otpLength: number;
+    ttlSeconds: number;
+}
+interface CreateOtpServiceOptions {
+    challengeIdGenerator?: () => string;
+    clock?: () => Date;
+    delivery: OtpDelivery;
+    otpGenerator?: (length: number) => string;
+    policy: OtpPolicy;
+    signer: OtpSigner;
+    store: ChallengeStore;
+}
+interface GenerateChallengeInput {
+    channel: OtpChannel;
+    purpose: string;
+    recipient: string;
+}
+interface GenerateChallengeResult {
+    challengeId: string;
+    expiresAt: Date;
+    status: "CHALLENGE_CREATED";
+}
+interface VerifyChallengeInput {
+    challengeId: string;
+    otp: string;
+}
+type VerifyChallengeResult = {
+    challengeId: string;
+    status: "VERIFIED";
+} | {
+    attemptsRemaining: number;
+    challengeId: string;
+    status: "INVALID";
+} | {
+    challengeId: string;
+    status: "EXPIRED";
+} | {
+    challengeId: string;
+    status: "ATTEMPTS_EXCEEDED";
+};
+interface OtpService {
+    generateChallenge(input: GenerateChallengeInput): Promise<GenerateChallengeResult>;
+    verifyChallenge(input: VerifyChallengeInput): Promise<VerifyChallengeResult>;
+}
+declare function createOtpService(options: CreateOtpServiceOptions): OtpService;
+declare function hmacOtpSigner(input: {
+    secret: string;
+}): OtpSigner;
+
+export { type ChallengeRecord, type ChallengeStore, type CreateOtpServiceOptions, type DeliveryRequest, type GenerateChallengeInput, type GenerateChallengeResult, type OtpChannel, type OtpDelivery, OtpDeliveryError, type OtpDeliveryOutcome, type OtpPolicy, type OtpService, type OtpSigner, type VerifyChallengeInput, type VerifyChallengeResult, createOtpService, hmacOtpSigner };

package/dist/index.js

@@ -0,0 +1,173 @@
+import { randomUUID, createHmac, timingSafeEqual, randomInt } from 'crypto';
+
+// src/index.ts
+var OtpDeliveryError = class extends Error {
+  code;
+  cause;
+  deliveryOutcome;
+  provider;
+  retryable;
+  constructor(input) {
+    super(input.message);
+    this.name = "OtpDeliveryError";
+    this.code = input.code;
+    this.deliveryOutcome = input.deliveryOutcome;
+    this.provider = input.provider;
+    this.retryable = input.retryable;
+    this.cause = input.cause;
+  }
+};
+function createOtpService(options) {
+  const clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+  const challengeIdGenerator = options.challengeIdGenerator ?? randomUUID;
+  const otpGenerator = options.otpGenerator ?? defaultOtpGenerator;
+  const policy = validatePolicy(options.policy);
+  return {
+    async generateChallenge(input) {
+      validateGenerateChallengeInput(input);
+      const createdAt = clock();
+      const expiresAt = new Date(createdAt.getTime() + policy.ttlSeconds * 1e3);
+      const challengeId = challengeIdGenerator();
+      const otp = otpGenerator(policy.otpLength);
+      const record = {
+        attemptsRemaining: policy.maxVerifyAttempts,
+        challengeId,
+        channel: input.channel,
+        createdAt,
+        expiresAt,
+        otpHash: options.signer.hash(otp),
+        purpose: input.purpose,
+        recipient: input.recipient
+      };
+      await options.store.create(record);
+      try {
+        await options.delivery.sendChallenge({
+          challengeId,
+          channel: input.channel,
+          expiresAt,
+          otp,
+          purpose: input.purpose,
+          recipient: input.recipient
+        });
+      } catch (error) {
+        if (error instanceof OtpDeliveryError && error.deliveryOutcome === "DEFINITIVE_FAILURE") {
+          await options.store.delete(challengeId);
+        }
+        throw error;
+      }
+      return {
+        challengeId,
+        expiresAt,
+        status: "CHALLENGE_CREATED"
+      };
+    },
+    async verifyChallenge(input) {
+      validateVerifyChallengeInput(input);
+      const record = await options.store.get(input.challengeId);
+      if (record === null) {
+        return {
+          challengeId: input.challengeId,
+          status: "EXPIRED"
+        };
+      }
+      if (record.expiresAt.getTime() <= clock().getTime()) {
+        await options.store.delete(record.challengeId);
+        return {
+          challengeId: record.challengeId,
+          status: "EXPIRED"
+        };
+      }
+      if (record.attemptsRemaining <= 0) {
+        await options.store.delete(record.challengeId);
+        return {
+          challengeId: record.challengeId,
+          status: "ATTEMPTS_EXCEEDED"
+        };
+      }
+      if (options.signer.verify(input.otp, record.otpHash)) {
+        await options.store.delete(record.challengeId);
+        return {
+          challengeId: record.challengeId,
+          status: "VERIFIED"
+        };
+      }
+      const attemptsRemaining = record.attemptsRemaining - 1;
+      const nextRecord = {
+        ...record,
+        attemptsRemaining
+      };
+      if (attemptsRemaining <= 0) {
+        await options.store.update(nextRecord);
+        return {
+          challengeId: record.challengeId,
+          status: "ATTEMPTS_EXCEEDED"
+        };
+      }
+      await options.store.update(nextRecord);
+      return {
+        attemptsRemaining,
+        challengeId: record.challengeId,
+        status: "INVALID"
+      };
+    }
+  };
+}
+function hmacOtpSigner(input) {
+  if (input.secret.trim().length === 0) {
+    throw new Error("OTP signer secret must not be empty.");
+  }
+  return {
+    hash(otp) {
+      return createHmac("sha256", input.secret).update(otp).digest("hex");
+    },
+    verify(otp, otpHash) {
+      const hashedOtp = createHmac("sha256", input.secret).update(otp).digest("hex");
+      const expected = Buffer.from(otpHash, "hex");
+      const actual = Buffer.from(hashedOtp, "hex");
+      if (expected.length !== actual.length) {
+        return false;
+      }
+      return timingSafeEqual(actual, expected);
+    }
+  };
+}
+function defaultOtpGenerator(length) {
+  let otp = "";
+  for (let index = 0; index < length; index += 1) {
+    otp += randomInt(0, 10).toString();
+  }
+  return otp;
+}
+function validateGenerateChallengeInput(input) {
+  if (input.channel !== "sms" && input.channel !== "email") {
+    throw new Error("Challenge channel must be either sms or email.");
+  }
+  requireNonEmptyString(input.recipient, "Challenge recipient must not be empty.");
+  requireNonEmptyString(input.purpose, "Challenge purpose must not be empty.");
+}
+function validatePolicy(policy) {
+  if (!Number.isInteger(policy.maxVerifyAttempts) || policy.maxVerifyAttempts <= 0) {
+    throw new Error("OTP policy maxVerifyAttempts must be a positive integer.");
+  }
+  if (!Number.isInteger(policy.otpLength) || policy.otpLength < 4) {
+    throw new Error("OTP policy otpLength must be an integer greater than or equal to 4.");
+  }
+  if (!Number.isInteger(policy.ttlSeconds) || policy.ttlSeconds <= 0) {
+    throw new Error("OTP policy ttlSeconds must be a positive integer.");
+  }
+  return policy;
+}
+function validateVerifyChallengeInput(input) {
+  requireNonEmptyString(input.challengeId, "Challenge ID must not be empty.");
+  requireNonEmptyString(input.otp, "OTP input must not be empty.");
+}
+function requireNonEmptyString(value, message) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(message);
+  }
+  return value.trim();
+}
+
+export { OtpDeliveryError, createOtpService, hmacOtpSigner };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { createHmac, randomInt, randomUUID, timingSafeEqual } from \"node:crypto\";\n\nexport type OtpChannel = \"email\" | \"sms\";\n\nexport interface ChallengeRecord {\n  attemptsRemaining: number;\n  channel: OtpChannel;\n  challengeId: string;\n  createdAt: Date;\n  expiresAt: Date;\n  otpHash: string;\n  purpose: string;\n  recipient: string;\n}\n\nexport interface ChallengeStore {\n  create(record: ChallengeRecord): Promise<void>;\n  delete(challengeId: string): Promise<void>;\n  get(challengeId: string): Promise<ChallengeRecord | null>;\n  update(record: ChallengeRecord): Promise<void>;\n}\n\nexport interface DeliveryRequest {\n  challengeId: string;\n  channel: OtpChannel;\n  expiresAt: Date;\n  otp: string;\n  purpose: string;\n  recipient: string;\n}\n\nexport interface OtpDelivery {\n  sendChallenge(request: DeliveryRequest): Promise<void>;\n}\n\nexport type OtpDeliveryOutcome = \"DEFINITIVE_FAILURE\" | \"OUTCOME_UNKNOWN\";\n\nexport class OtpDeliveryError extends Error {\n  readonly code: string;\n  override readonly cause?: unknown;\n  readonly deliveryOutcome: OtpDeliveryOutcome;\n  readonly provider: string;\n  readonly retryable: boolean;\n\n  constructor(input: {\n    cause?: unknown;\n    code: string;\n    deliveryOutcome: OtpDeliveryOutcome;\n    message: string;\n    provider: string;\n    retryable: boolean;\n  }) {\n    super(input.message);\n    this.name = \"OtpDeliveryError\";\n    this.code = input.code;\n    this.deliveryOutcome = input.deliveryOutcome;\n    this.provider = input.provider;\n    this.retryable = input.retryable;\n    this.cause = input.cause;\n  }\n}\n\nexport interface OtpSigner {\n  hash(otp: string): string;\n  verify(otp: string, otpHash: string): boolean;\n}\n\nexport interface OtpPolicy {\n  maxVerifyAttempts: number;\n  otpLength: number;\n  ttlSeconds: number;\n}\n\nexport interface CreateOtpServiceOptions {\n  challengeIdGenerator?: () => string;\n  clock?: () => Date;\n  delivery: OtpDelivery;\n  otpGenerator?: (length: number) => string;\n  policy: OtpPolicy;\n  signer: OtpSigner;\n  store: ChallengeStore;\n}\n\nexport interface GenerateChallengeInput {\n  channel: OtpChannel;\n  purpose: string;\n  recipient: string;\n}\n\nexport interface GenerateChallengeResult {\n  challengeId: string;\n  expiresAt: Date;\n  status: \"CHALLENGE_CREATED\";\n}\n\nexport interface VerifyChallengeInput {\n  challengeId: string;\n  otp: string;\n}\n\nexport type VerifyChallengeResult =\n  | { challengeId: string; status: \"VERIFIED\" }\n  | { attemptsRemaining: number; challengeId: string; status: \"INVALID\" }\n  | { challengeId: string; status: \"EXPIRED\" }\n  | { challengeId: string; status: \"ATTEMPTS_EXCEEDED\" };\n\nexport interface OtpService {\n  generateChallenge(input: GenerateChallengeInput): Promise<GenerateChallengeResult>;\n  verifyChallenge(input: VerifyChallengeInput): Promise<VerifyChallengeResult>;\n}\n\nexport function createOtpService(options: CreateOtpServiceOptions): OtpService {\n  const clock = options.clock ?? (() => new Date());\n  const challengeIdGenerator = options.challengeIdGenerator ?? randomUUID;\n  const otpGenerator = options.otpGenerator ?? defaultOtpGenerator;\n  const policy = validatePolicy(options.policy);\n\n  return {\n    async generateChallenge(input) {\n      validateGenerateChallengeInput(input);\n\n      const createdAt = clock();\n      const expiresAt = new Date(createdAt.getTime() + policy.ttlSeconds * 1000);\n      const challengeId = challengeIdGenerator();\n      const otp = otpGenerator(policy.otpLength);\n      const record: ChallengeRecord = {\n        attemptsRemaining: policy.maxVerifyAttempts,\n        challengeId,\n        channel: input.channel,\n        createdAt,\n        expiresAt,\n        otpHash: options.signer.hash(otp),\n        purpose: input.purpose,\n        recipient: input.recipient\n      };\n\n      await options.store.create(record);\n\n      try {\n        await options.delivery.sendChallenge({\n          challengeId,\n          channel: input.channel,\n          expiresAt,\n          otp,\n          purpose: input.purpose,\n          recipient: input.recipient\n        });\n      } catch (error) {\n        if (error instanceof OtpDeliveryError && error.deliveryOutcome === \"DEFINITIVE_FAILURE\") {\n          await options.store.delete(challengeId);\n        }\n\n        throw error;\n      }\n\n      return {\n        challengeId,\n        expiresAt,\n        status: \"CHALLENGE_CREATED\"\n      };\n    },\n\n    async verifyChallenge(input) {\n      validateVerifyChallengeInput(input);\n\n      const record = await options.store.get(input.challengeId);\n      if (record === null) {\n        return {\n          challengeId: input.challengeId,\n          status: \"EXPIRED\"\n        };\n      }\n\n      if (record.expiresAt.getTime() <= clock().getTime()) {\n        await options.store.delete(record.challengeId);\n        return {\n          challengeId: record.challengeId,\n          status: \"EXPIRED\"\n        };\n      }\n\n      if (record.attemptsRemaining <= 0) {\n        await options.store.delete(record.challengeId);\n        return {\n          challengeId: record.challengeId,\n          status: \"ATTEMPTS_EXCEEDED\"\n        };\n      }\n\n      if (options.signer.verify(input.otp, record.otpHash)) {\n        await options.store.delete(record.challengeId);\n        return {\n          challengeId: record.challengeId,\n          status: \"VERIFIED\"\n        };\n      }\n\n      const attemptsRemaining = record.attemptsRemaining - 1;\n      const nextRecord: ChallengeRecord = {\n        ...record,\n        attemptsRemaining\n      };\n\n      if (attemptsRemaining <= 0) {\n        await options.store.update(nextRecord);\n        return {\n          challengeId: record.challengeId,\n          status: \"ATTEMPTS_EXCEEDED\"\n        };\n      }\n\n      await options.store.update(nextRecord);\n      return {\n        attemptsRemaining,\n        challengeId: record.challengeId,\n        status: \"INVALID\"\n      };\n    }\n  };\n}\n\nexport function hmacOtpSigner(input: { secret: string }): OtpSigner {\n  if (input.secret.trim().length === 0) {\n    throw new Error(\"OTP signer secret must not be empty.\");\n  }\n\n  return {\n    hash(otp) {\n      return createHmac(\"sha256\", input.secret).update(otp).digest(\"hex\");\n    },\n    verify(otp, otpHash) {\n      const hashedOtp = createHmac(\"sha256\", input.secret).update(otp).digest(\"hex\");\n      const expected = Buffer.from(otpHash, \"hex\");\n      const actual = Buffer.from(hashedOtp, \"hex\");\n\n      if (expected.length !== actual.length) {\n        return false;\n      }\n\n      return timingSafeEqual(actual, expected);\n    }\n  };\n}\n\nfunction defaultOtpGenerator(length: number): string {\n  let otp = \"\";\n\n  for (let index = 0; index < length; index += 1) {\n    otp += randomInt(0, 10).toString();\n  }\n\n  return otp;\n}\n\nfunction validateGenerateChallengeInput(input: GenerateChallengeInput): void {\n  if (input.channel !== \"sms\" && input.channel !== \"email\") {\n    throw new Error(\"Challenge channel must be either sms or email.\");\n  }\n\n  requireNonEmptyString(input.recipient, \"Challenge recipient must not be empty.\");\n  requireNonEmptyString(input.purpose, \"Challenge purpose must not be empty.\");\n}\n\nfunction validatePolicy(policy: OtpPolicy): OtpPolicy {\n  if (!Number.isInteger(policy.maxVerifyAttempts) || policy.maxVerifyAttempts <= 0) {\n    throw new Error(\"OTP policy maxVerifyAttempts must be a positive integer.\");\n  }\n\n  if (!Number.isInteger(policy.otpLength) || policy.otpLength < 4) {\n    throw new Error(\"OTP policy otpLength must be an integer greater than or equal to 4.\");\n  }\n\n  if (!Number.isInteger(policy.ttlSeconds) || policy.ttlSeconds <= 0) {\n    throw new Error(\"OTP policy ttlSeconds must be a positive integer.\");\n  }\n\n  return policy;\n}\n\nfunction validateVerifyChallengeInput(input: VerifyChallengeInput): void {\n  requireNonEmptyString(input.challengeId, \"Challenge ID must not be empty.\");\n  requireNonEmptyString(input.otp, \"OTP input must not be empty.\");\n}\n\nfunction requireNonEmptyString(value: unknown, message: string): string {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new Error(message);\n  }\n\n  return value.trim();\n}\n"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@otp-service/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Framework-agnostic OTP domain logic for Node.js services.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Suraj-H/otp-service-package-v2.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Suraj-H/otp-service-package-v2/issues"
+  },
+  "homepage": "https://github.com/Suraj-H/otp-service-package-v2/tree/main/packages/core#readme",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "clean": "rm -rf dist",
+    "lint": "eslint src test",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}