@maestro-js/password 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { CustomErrors } from '@maestro-js/custom-errors';
+import { Iso } from 'iso-fns2';
+import { Hash } from '@maestro-js/hash';
+
+declare function create<Id, Credentials extends {
+    password: string;
+}>(config: Password.Config<Id, Credentials>): Password.Service<Id, Credentials>;
+declare const Password: {
+    create: typeof create;
+    errors: {
+        ThrottledError: CustomErrors.CustomErrorConstructor<undefined, {}, "tooManyRequests">;
+        InvalidTokenError: CustomErrors.CustomErrorConstructor<undefined, {}, "unprocessableContent">;
+        ExpiredTokenError: CustomErrors.CustomErrorConstructor<undefined, {}, "unprocessableContent">;
+    };
+};
+declare namespace Password {
+    interface Service<Id, Credentials extends {
+        password: string;
+    }> {
+        verifyCredentials(credentials: Credentials): Promise<Password.Authenticatable<Id> | null>;
+        createPasswordResetToken: (authenticatableId: Id) => Promise<string>;
+        resetPassword: (options: {
+            authenticatableId: Id;
+            token: string;
+            newPassword: string;
+        }) => Promise<void>;
+    }
+    interface Config<Id, Credentials extends {
+        password: string;
+    }> {
+        getAuthenticatableByCredentials(credentials: Omit<Credentials, 'password'>): Promise<(Password.Authenticatable<Id> & {
+            passwordHash: string;
+        }) | null>;
+        updatePasswordHash(id: Id, passwordHash: string): Promise<void>;
+        updateCredentialsInvalidBefore(id: Id, date: Iso.Instant): Promise<void>;
+        /** Used for password hashing and verification. `Hash.drivers.bcrypt()` is recommended. */
+        hash: Hash.HashService;
+        passwordResetOptions?: Password.ResetOptions<Id>;
+    }
+    interface Authenticatable<Id> {
+        id: Id;
+        credentialsInvalidBefore: Iso.Instant | null;
+    }
+    interface ResetTokenRecord<Id> {
+        authenticatableId: Id;
+        selector: string;
+        verifierHash: string;
+        expirationDate: Iso.Instant;
+        createdDate: Iso.Instant;
+    }
+    interface ResetOptions<Id> {
+        create(record: Password.ResetTokenRecord<Id>): Promise<void>;
+        getBySelector(selector: string): Promise<Password.ResetTokenRecord<Id> | null>;
+        getByAuthenticatableId(authenticatableId: Id): Promise<Password.ResetTokenRecord<Id> | null>;
+        deleteByAuthenticatableId(authenticatableId: Id): Promise<void>;
+        /** Token lifetime in minutes. Default: 60 */
+        tokenExpirationMinutes?: number;
+        /** Minimum seconds between createToken calls for the same authenticatable. Default: 60 */
+        throttleSeconds?: number;
+    }
+}
+
+export { Password };

package/dist/index.js

@@ -0,0 +1,118 @@
+// src/index.ts
+import crypto from "crypto";
+import { CustomErrors } from "@maestro-js/custom-errors";
+import { instantFns } from "iso-fns2";
+function create(config) {
+  const hashService = config.hash;
+  const passwordResetOptions = config.passwordResetOptions;
+  async function verifyCredentials(credentials) {
+    const { password, ...input } = credentials;
+    const authenticatable = await config.getAuthenticatableByCredentials(input);
+    if (!authenticatable) {
+      await hashService.verify({ hash: await hashService.hash("password"), plaintext: "password" });
+      return null;
+    }
+    const isValid = await hashService.verify({ plaintext: password, hash: authenticatable.passwordHash });
+    if (!isValid) {
+      return null;
+    }
+    const needsRehash = await hashService.needsRehash(authenticatable.passwordHash);
+    if (needsRehash) {
+      const newHash = await hashService.hash(password);
+      await config.updatePasswordHash(authenticatable.id, newHash);
+    }
+    return { id: authenticatable.id, credentialsInvalidBefore: authenticatable.credentialsInvalidBefore };
+  }
+  async function createPasswordResetToken(authenticatableId) {
+    if (!passwordResetOptions) {
+      throw new Error("Password reset is not configured. Provide `passwordResetOptions` when creating the password service.");
+    }
+    const existing = await passwordResetOptions.getByAuthenticatableId(authenticatableId);
+    if (existing) {
+      const throttleExpiry = instantFns.add(existing.createdDate, { seconds: passwordResetOptions.throttleSeconds ?? 60 });
+      if (instantFns.now() < throttleExpiry) {
+        throw new PasswordResetThrottledError();
+      }
+    }
+    const selector = crypto.randomBytes(16).toString("base64url");
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const verifierHash = await config.hash.hash(verifier);
+    const now = instantFns.now();
+    const expirationDate = instantFns.add(now, { minutes: passwordResetOptions.tokenExpirationMinutes ?? 60 });
+    await passwordResetOptions.create({
+      authenticatableId,
+      selector,
+      verifierHash,
+      expirationDate,
+      createdDate: now
+    });
+    return `${selector}|${verifier}`;
+  }
+  async function resetPassword({
+    authenticatableId,
+    token,
+    newPassword
+  }) {
+    if (!passwordResetOptions) {
+      throw new Error("Password reset is not configured. Provide `passwordResetOptions` when creating the password service.");
+    }
+    const decoded = decodePasswordResetToken(token);
+    if (!decoded) {
+      throw new PasswordResetInvalidTokenError();
+    }
+    const record = await passwordResetOptions.getBySelector(decoded.selector);
+    if (!record) {
+      throw new PasswordResetInvalidTokenError();
+    }
+    const isValid = await config.hash.verify({ plaintext: decoded.verifier, hash: record.verifierHash });
+    if (!isValid) {
+      throw new PasswordResetInvalidTokenError();
+    }
+    if (record.expirationDate < instantFns.now()) {
+      throw new PasswordResetExpiredTokenError();
+    }
+    if (record.authenticatableId !== authenticatableId) {
+      throw new PasswordResetInvalidTokenError();
+    }
+    const passwordHash = await config.hash.hash(newPassword);
+    await config.updatePasswordHash(authenticatableId, passwordHash);
+    await config.updateCredentialsInvalidBefore(authenticatableId, instantFns.now());
+    await passwordResetOptions.deleteByAuthenticatableId(authenticatableId);
+  }
+  return {
+    verifyCredentials,
+    createPasswordResetToken,
+    resetPassword
+  };
+}
+var PasswordResetThrottledError = CustomErrors.create({
+  name: "PasswordResetThrottledError",
+  message: "Password reset requests are being throttled. Please try again later.",
+  httpStatusCode: "tooManyRequests"
+});
+var PasswordResetInvalidTokenError = CustomErrors.create({
+  name: "PasswordResetInvalidTokenError",
+  message: "The password reset token is invalid.",
+  httpStatusCode: "unprocessableContent"
+});
+var PasswordResetExpiredTokenError = CustomErrors.create({
+  name: "PasswordResetExpiredTokenError",
+  message: "The password reset token has expired.",
+  httpStatusCode: "unprocessableContent"
+});
+var Password = {
+  create,
+  errors: {
+    ThrottledError: PasswordResetThrottledError,
+    InvalidTokenError: PasswordResetInvalidTokenError,
+    ExpiredTokenError: PasswordResetExpiredTokenError
+  }
+};
+function decodePasswordResetToken(token) {
+  const [selector, verifier] = token.split("|");
+  if (!selector || !verifier) return null;
+  return { selector, verifier };
+}
+export {
+  Password
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@maestro-js/password",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "@maestro-js/custom-errors": "1.0.0-alpha.0",
+    "@maestro-js/hash": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}