@proteinjs/user-server 1.21.0 → 1.21.1

package/src/routes/executePasswordReset.ts

@@ -1,20 +1,19 @@
 import { Route } from '@proteinjs/server-api';
-import { getDbAsSystem } from '@proteinjs/db';
-import { routes, tables } from '@proteinjs/user';
+import { routes } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
-import moment from 'moment';
 import { PasswordHasher } from '../authentication/PasswordHasher';
+import { PasswordResetToken } from '../authentication/PasswordResetToken';
 
 /**
  * Route handler for executing a password reset.
  *
- * This function handles the process of resetting a user's password using a provided reset token.
- * It verifies the token, checks its expiration, and updates the user's password if everything is valid.
+ * Resolves the presented token through `PasswordResetToken` — which refuses anything but a
+ * well-formed token before any lookup — checks its expiry, and redeems it: the new password is
+ * written and the token cleared in one conditional update, so a token resets a password once.
+ * The token itself never reaches the log.
  *
  * @bodyParam {string} token - The password reset token.
  * @bodyParam {string} newPassword - The new password for the user.
- *
- * @throws {Error} If there's an issue with the database operations or if the token is invalid or expired.
  */
 export const executePasswordReset: Route = {
   path: routes.executePasswordReset.path,
@@ -22,33 +21,35 @@ export const executePasswordReset: Route = {
   onRequest: async (request, response): Promise<void> => {
     const logger = new Logger({ name: 'executePasswordReset' });
     const { token, newPassword } = request.body;
-    const db = getDbAsSystem();
+    if (typeof newPassword !== 'string' || newPassword.length === 0) {
+      response.status(400).send({ error: 'New password cannot be blank' });
+      return;
+    }
 
-    // Find user with the given reset token
-    const user = await db.get(tables.User, { passwordResetToken: token });
-    if (!user) {
-      logger.info({ message: `Invalid reset token used`, obj: { token } });
+    const resetToken = new PasswordResetToken();
+    const resolution = await resetToken.resolve(token);
+    if (resolution.status === 'malformed' || resolution.status === 'unknown') {
+      logger.info({
+        message: `Invalid reset token used`,
+        obj: { reason: resolution.status, token: resetToken.fingerprint(token) },
+      });
       response.status(400).send({ error: 'Invalid or expired reset token' });
       return;
     }
 
-    // Check if token is expired
-    const currentTime = moment();
-    const tokenExpiration = moment(user.passwordResetTokenExpiration);
-    if (currentTime.isAfter(tokenExpiration)) {
-      logger.info({ message: `Expired reset token used`, obj: { email: user.email } });
+    if (resolution.status === 'expired') {
+      logger.info({ message: `Expired reset token used`, obj: { email: resolution.user.email } });
       response.status(400).send({ error: 'Reset token has expired' });
       return;
     }
 
-    // Update user's password
+    const { user } = resolution;
     const hashedPassword = await new PasswordHasher().hash(newPassword);
-    await db.update(tables.User, {
-      id: user.id,
-      password: hashedPassword,
-      passwordResetToken: null,
-      passwordResetTokenExpiration: null,
-    });
+    if (!(await resetToken.redeem(user, resolution.token, hashedPassword))) {
+      logger.info({ message: `Reset token already redeemed`, obj: { email: user.email } });
+      response.status(400).send({ error: 'Invalid or expired reset token' });
+      return;
+    }
 
     logger.info({ message: `Password successfully reset`, obj: { email: user.email } });
     response.send({ message: 'Password has been successfully reset' });

package/src/routes/initiatePasswordReset.ts

@@ -7,7 +7,7 @@ import {
   EmailSender,
   getDefaultPasswordResetEmailConfigFactory as getDefaultConfigFactory,
 } from '@proteinjs/email-server';
-import { lib } from 'crypto-js';
+import { PasswordResetToken } from '../authentication/PasswordResetToken';
 
 /**
  * Route for initiating a password reset process.
@@ -62,7 +62,7 @@ export const initiatePasswordReset: Route = {
     }
 
     // Generate reset token
-    const passwordResetToken = lib.WordArray.random(32).toString();
+    const passwordResetToken = new PasswordResetToken().mint();
     const passwordResetTokenExpiration = moment().add(1, 'hour');
 
     try {

package/src/routes/validateResetPasswordToken.ts

@@ -1,8 +1,7 @@
 import { Route } from '@proteinjs/server-api';
-import { getDbAsSystem } from '@proteinjs/db';
-import { routes, tables } from '@proteinjs/user';
+import { routes } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
-import moment from 'moment';
+import { PasswordResetToken } from '../authentication/PasswordResetToken';
 
 export const validateResetPasswordToken: Route = {
   path: routes.validateResetToken.path,
@@ -10,26 +9,24 @@ export const validateResetPasswordToken: Route = {
   onRequest: async (request, response): Promise<void> => {
     const logger = new Logger({ name: 'validateResetToken' });
     const { token } = request.query;
-    const db = getDbAsSystem();
-
     if (!token) {
       response.status(400).send({ isValid: false, message: 'No token provided' });
       return;
     }
 
-    // Find user with the given reset token
-    const user = await db.get(tables.User, { passwordResetToken: token });
-    if (!user) {
-      logger.info({ message: `Invalid reset token used`, obj: { token } });
+    const resetToken = new PasswordResetToken();
+    const resolution = await resetToken.resolve(token);
+    if (resolution.status === 'malformed' || resolution.status === 'unknown') {
+      logger.info({
+        message: `Invalid reset token used`,
+        obj: { reason: resolution.status, token: resetToken.fingerprint(token) },
+      });
       response.status(200).send({ isValid: false, message: 'Invalid token' });
       return;
     }
 
-    // Check if token is expired
-    const currentTime = moment();
-    const tokenExpiration = moment(user.passwordResetTokenExpiration);
-    if (currentTime.isAfter(tokenExpiration)) {
-      logger.info({ message: `Expired reset token used`, obj: { email: user.email } });
+    if (resolution.status === 'expired') {
+      logger.info({ message: `Expired reset token used`, obj: { email: resolution.user.email } });
       response.status(200).send({ isValid: false, message: 'Token has expired' });
       return;
     }
@@ -38,6 +35,6 @@ export const validateResetPasswordToken: Route = {
     // read-only `autocomplete="username"` field so password managers associate the updated
     // password with the stored credential. The token was delivered to this very inbox, so a
     // valid-token holder learns nothing new; invalid/expired verdicts stay email-free.
-    response.status(200).send({ isValid: true, email: user.email });
+    response.status(200).send({ isValid: true, email: resolution.user.email });
   },
 };

package/test/ExecutePasswordReset.test.ts

@@ -0,0 +1,224 @@
+import moment, { Moment } from 'moment';
+import { getDbAsSystem } from '@proteinjs/db';
+import { Logger } from '@proteinjs/logger';
+import { tables, User } from '@proteinjs/user';
+import { executePasswordReset } from '../src/routes/executePasswordReset';
+import { PasswordHasher } from '../src/authentication/PasswordHasher';
+import { PasswordResetToken } from '../src/authentication/PasswordResetToken';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `POST /user/execute-password-reset`. The token is the only credential this route accepts, so
+ * the lookup must never be built from anything but a well-formed token: a `null` in the body
+ * renders as `IS NULL` and matches every account with no pending reset, an empty string matches
+ * an emptied column, and other types reach the driver. Covered here, outcomes only (rows
+ * written), against the Spanner emulator:
+ * - an absent, null, empty or malformed token: 400, and no password in the table changes — an
+ *   account with no pending reset is never matched, whatever the request carries;
+ * - a live token resets the password once: the row verifies the new password, the token and its
+ *   expiry are cleared, and the same token presented again is refused;
+ * - an expired token, or a token whose row carries no expiry, is refused;
+ * - a blank new password is refused without consuming the token;
+ * - the presented token never reaches the log;
+ * - the token owner's own contract: mint shape, the stored-vs-presented match, liveness, and the
+ *   conditional redemption.
+ */
+
+type RouteOutcome = { status: number; body?: any };
+
+const invokeExecute = async (body: Record<string, unknown>): Promise<RouteOutcome> => {
+  const outcome: RouteOutcome = { status: 200 };
+  const response = {
+    status(code: number) {
+      outcome.status = code;
+      return this;
+    },
+    send(body?: unknown) {
+      outcome.body = body;
+    },
+  };
+  await executePasswordReset.onRequest({ body } as never, response as never);
+  return outcome;
+};
+
+const mintToken = () => new PasswordResetToken().mint();
+
+const armResetToken = async (email: string, token: string | null, expiration: Moment | null): Promise<User> => {
+  const user = await testEnv.createUser({ name: 'Reset User', email });
+  await getDbAsSystem().update(tables.User, {
+    id: user.id,
+    passwordResetToken: token,
+    passwordResetTokenExpiration: expiration,
+  });
+  return user;
+};
+
+const userRow = async (id: string) => await getDbAsSystem().get(tables.User, { id });
+
+/** Every password in the table, by email — the whole-table outcome a refused request must leave untouched. */
+const passwordsByEmail = async (): Promise<Record<string, string>> => {
+  const byEmail: Record<string, string> = {};
+  for (const user of await getDbAsSystem().query(tables.User, {})) {
+    byEmail[user.email] = user.password;
+  }
+  return byEmail;
+};
+
+type TokenInternals = {
+  matches(stored: string | null | undefined, presented: string): boolean;
+  isLive(expiration: Moment | null | undefined): boolean;
+};
+
+describe('executePasswordReset route', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    // No pending reset — the account a `null` token's `IS NULL` filter would match.
+    await testEnv.createUser({ name: 'Idle User', email: 'reset-idle@test.local' });
+    // An emptied token column — the account an empty token would match.
+    await armResetToken('reset-emptied@test.local', '', moment().add(1, 'hour'));
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  describe('a request without a well-formed token is refused before any lookup', () => {
+    it.each([
+      ['absent', {}],
+      ['null', { token: null }],
+      ['empty', { token: '' }],
+      ['not a token string', { token: 'tok-valid-1' }],
+      ['a number', { token: 123 }],
+      ['an array', { token: ['a', 'b'] }],
+      ['an object', { token: { passwordResetToken: null } }],
+    ])('%s: 400, and no password in the table changes', async (_label, tokenField) => {
+      const before = await passwordsByEmail();
+
+      const outcome = await invokeExecute({ ...tokenField, newPassword: 'hijacked' });
+
+      expect(outcome.status).toBe(400);
+      expect(outcome.body).toEqual({ error: 'Invalid or expired reset token' });
+      expect(await passwordsByEmail()).toEqual(before);
+    });
+  });
+
+  it('a live token resets the password once: the row verifies it, the token clears, a re-presentation is refused', async () => {
+    const token = mintToken();
+    const user = await armResetToken('reset-live@test.local', token, moment().add(1, 'hour'));
+
+    const first = await invokeExecute({ token, newPassword: 'first new password' });
+
+    expect(first.status).toBe(200);
+    expect(first.body).toEqual({ message: 'Password has been successfully reset' });
+    const afterFirst = await userRow(user.id);
+    await expect(new PasswordHasher().verify(afterFirst.password, 'first new password')).resolves.toBe(true);
+    expect(afterFirst.passwordResetToken).toBeNull();
+    expect(afterFirst.passwordResetTokenExpiration).toBeNull();
+
+    const second = await invokeExecute({ token, newPassword: 'second new password' });
+
+    expect(second.status).toBe(400);
+    expect((await userRow(user.id)).password).toBe(afterFirst.password);
+  });
+
+  it('an expired token is refused and changes nothing', async () => {
+    const token = mintToken();
+    const user = await armResetToken('reset-expired@test.local', token, moment().subtract(1, 'minute'));
+    const before = (await userRow(user.id)).password;
+
+    const outcome = await invokeExecute({ token, newPassword: 'hijacked' });
+
+    expect(outcome.status).toBe(400);
+    expect(outcome.body).toEqual({ error: 'Reset token has expired' });
+    const row = await userRow(user.id);
+    expect(row.password).toBe(before);
+    expect(row.passwordResetToken).toBe(token);
+  });
+
+  it('a token whose row carries no expiry is refused — never live by omission', async () => {
+    const token = mintToken();
+    const user = await armResetToken('reset-no-expiry@test.local', token, null);
+    const before = (await userRow(user.id)).password;
+
+    const outcome = await invokeExecute({ token, newPassword: 'hijacked' });
+
+    expect(outcome.status).toBe(400);
+    expect((await userRow(user.id)).password).toBe(before);
+  });
+
+  it('a blank new password is refused without consuming the token', async () => {
+    const token = mintToken();
+    const user = await armResetToken('reset-blank@test.local', token, moment().add(1, 'hour'));
+    const before = (await userRow(user.id)).password;
+
+    for (const newPassword of ['', undefined, 42]) {
+      const outcome = await invokeExecute({ token, newPassword });
+      expect(outcome.status).toBe(400);
+    }
+
+    const row = await userRow(user.id);
+    expect(row.password).toBe(before);
+    expect(row.passwordResetToken).toBe(token);
+  });
+
+  it('the presented token never reaches the log', async () => {
+    const token = mintToken(); // well-formed, never issued
+    const info = jest.spyOn(Logger.prototype, 'info');
+    try {
+      await invokeExecute({ token, newPassword: 'hijacked' });
+
+      expect(info).toHaveBeenCalled();
+      for (const [entry] of info.mock.calls) {
+        expect(JSON.stringify(entry)).not.toContain(token);
+      }
+    } finally {
+      info.mockRestore();
+    }
+  });
+
+  describe('PasswordResetToken', () => {
+    const internals = new PasswordResetToken() as unknown as TokenInternals;
+
+    it('mints 64 lowercase hex characters, fresh each time', () => {
+      const token = mintToken();
+
+      expect(token).toMatch(/^[0-9a-f]{64}$/);
+      expect(mintToken()).not.toBe(token);
+    });
+
+    it('a stored token matches only the same string — never an absent or emptied one', () => {
+      const token = mintToken();
+
+      expect(internals.matches(token, token)).toBe(true);
+      expect(internals.matches(mintToken(), token)).toBe(false);
+      expect(internals.matches(null, token)).toBe(false);
+      expect(internals.matches(undefined, token)).toBe(false);
+      expect(internals.matches('', token)).toBe(false);
+    });
+
+    it('an expiry is live only as a valid timestamp in the future', () => {
+      expect(internals.isLive(moment().add(1, 'minute'))).toBe(true);
+      expect(internals.isLive(moment().subtract(1, 'minute'))).toBe(false);
+      expect(internals.isLive(null)).toBe(false);
+      expect(internals.isLive(undefined)).toBe(false);
+      expect(internals.isLive(moment.invalid())).toBe(false);
+    });
+
+    it('redeem writes only while the row still carries the token', async () => {
+      const live = mintToken();
+      const user = await armResetToken('reset-redeem@test.local', live, moment().add(1, 'hour'));
+      const before = (await userRow(user.id)).password;
+
+      await expect(new PasswordResetToken().redeem(user, mintToken(), 'other-hash')).resolves.toBe(false);
+      expect((await userRow(user.id)).password).toBe(before);
+
+      await expect(new PasswordResetToken().redeem(user, live, 'new-hash')).resolves.toBe(true);
+      const row = await userRow(user.id);
+      expect(row.password).toBe('new-hash');
+      expect(row.passwordResetToken).toBeNull();
+      expect(row.passwordResetTokenExpiration).toBeNull();
+    });
+  });
+});

package/test/ValidateResetToken.test.ts

@@ -2,6 +2,7 @@ import moment from 'moment';
 import { getDbAsSystem } from '@proteinjs/db';
 import { tables } from '@proteinjs/user';
 import { validateResetPasswordToken } from '../src/routes/validateResetPasswordToken';
+import { PasswordResetToken } from '../src/authentication/PasswordResetToken';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -12,7 +13,9 @@ const testEnv = new UserServerTestEnvironment();
  * `autocomplete="username"` field so password managers can associate the updated password
  * with the stored credential. The email only ever rides a VALID token's response — the
  * token was delivered to that very inbox, so it reveals nothing the holder doesn't know —
- * while invalid/expired verdicts stay email-free (no account-probing oracle).
+ * while invalid/expired verdicts stay email-free (no account-probing oracle). A query value
+ * that is not a well-formed token (a parsed object or array, a string of another shape) is
+ * invalid without a lookup.
  */
 
 type RouteOutcome = { status?: number; body?: any };
@@ -32,6 +35,8 @@ const invokeValidate = async (query: Record<string, unknown>): Promise<RouteOutc
   return outcome;
 };
 
+const mintToken = () => new PasswordResetToken().mint();
+
 const armResetToken = async (email: string, token: string, expiration: moment.Moment) => {
   const user = await testEnv.createUser({ name: 'Reset User', email });
   await getDbAsSystem().update(tables.User, {
@@ -51,18 +56,20 @@ describe('validateResetPasswordToken route', () => {
   });
 
   it('a valid token resolves isValid WITH the account email (the reset form identifier)', async () => {
-    await armResetToken('reset-valid@test.local', 'tok-valid-1', moment().add(1, 'hour'));
+    const token = mintToken();
+    await armResetToken('reset-valid@test.local', token, moment().add(1, 'hour'));
 
-    const outcome = await invokeValidate({ token: 'tok-valid-1' });
+    const outcome = await invokeValidate({ token });
 
     expect(outcome.status).toBe(200);
     expect(outcome.body).toEqual({ isValid: true, email: 'reset-valid@test.local' });
   });
 
   it('an expired token resolves invalid and leaks no email', async () => {
-    await armResetToken('reset-expired@test.local', 'tok-expired-1', moment().subtract(1, 'minute'));
+    const token = mintToken();
+    await armResetToken('reset-expired@test.local', token, moment().subtract(1, 'minute'));
 
-    const outcome = await invokeValidate({ token: 'tok-expired-1' });
+    const outcome = await invokeValidate({ token });
 
     expect(outcome.status).toBe(200);
     expect(outcome.body.isValid).toBe(false);
@@ -70,13 +77,24 @@ describe('validateResetPasswordToken route', () => {
   });
 
   it('an unknown token resolves invalid and leaks no email', async () => {
-    const outcome = await invokeValidate({ token: 'tok-never-issued' });
+    const outcome = await invokeValidate({ token: mintToken() });
 
     expect(outcome.status).toBe(200);
     expect(outcome.body.isValid).toBe(false);
     expect(outcome.body.email).toBeUndefined();
   });
 
+  it.each([
+    ['a string of another shape', 'tok-never-issued'],
+    ['a parsed array', ['a', 'b']],
+    ['a parsed object', { passwordResetToken: null }],
+  ])('%s resolves invalid without a lookup and leaks no email', async (_label, token) => {
+    const outcome = await invokeValidate({ token });
+
+    expect(outcome.status).toBe(200);
+    expect(outcome.body).toEqual({ isValid: false, message: 'Invalid token' });
+  });
+
   it('a missing token is a 400', async () => {
     const outcome = await invokeValidate({});