@proteinjs/user-server 1.21.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/user-server",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "User server components",
   "publishConfig": {
     "access": "public"
@@ -24,7 +24,7 @@
   "dependencies": {
     "@proteinjs/db": "^1.47.0",
     "@proteinjs/db-file": "^1.5.3",
-    "@proteinjs/email-server": "^1.3.0",
+    "@proteinjs/email-server": "^1.4.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/server": "^3.5.1",
@@ -59,5 +59,5 @@
   },
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
-  "gitHead": "b41385de00be0c41a62e4aa1d37b0cf56907d192"
+  "gitHead": "37d5b1a621fbaf23e1571282b4bbbd466a33ede5"
 }

package/src/authentication/PasswordResetToken.ts

@@ -0,0 +1,96 @@
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import moment, { Moment } from 'moment';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables, User } from '@proteinjs/user';
+
+export type PasswordResetResolution =
+  | { status: 'malformed' }
+  | { status: 'unknown' }
+  | { status: 'expired'; user: User }
+  | { status: 'live'; user: User; token: string };
+
+/**
+ * The password-reset token's one owner: its shape, its mint, the lookup that maps a presented
+ * value back to the user it was issued to, and its single-use redemption.
+ *
+ * A token is 32 bytes from the platform CSPRNG, hex-encoded (64 lowercase hex characters),
+ * stored on the user row beside its expiry until it is redeemed or expires.
+ *
+ * Resolution refuses anything that is not a value of that shape BEFORE any lookup. A query
+ * filter built from a request value that is not a token does not compare the way a token does:
+ * `null` renders as `IS NULL` and would match every account with no pending reset, an empty
+ * string matches an emptied column, and other types reach the driver. The row the lookup
+ * returns is then re-checked in code — its stored token must be a string equal to the presented
+ * one (compared in constant time) and its expiry a real timestamp still in the future — so the
+ * outcome never rests on how the storage compares.
+ */
+export class PasswordResetToken {
+  private static readonly SHAPE = /^[0-9a-f]{64}$/;
+
+  mint(): string {
+    return randomBytes(32).toString('hex');
+  }
+
+  async resolve(presented: unknown): Promise<PasswordResetResolution> {
+    const token = this.parse(presented);
+    if (token === undefined) {
+      return { status: 'malformed' };
+    }
+
+    const user = await getDbAsSystem().get(tables.User, { passwordResetToken: token });
+    if (!user || !this.matches(user.passwordResetToken, token)) {
+      return { status: 'unknown' };
+    }
+
+    if (!this.isLive(user.passwordResetTokenExpiration)) {
+      return { status: 'expired', user };
+    }
+
+    return { status: 'live', user, token };
+  }
+
+  /**
+   * Write the new credential and clear the token in one conditional update: the row must still
+   * carry this token at write time, so two presentations of the same token cannot both succeed.
+   * Resolves false when the token was already redeemed.
+   */
+  async redeem(user: User, token: string, hashedPassword: string): Promise<boolean> {
+    const updated = await getDbAsSystem().update(
+      tables.User,
+      { password: hashedPassword, passwordResetToken: null, passwordResetTokenExpiration: null },
+      { id: user.id, passwordResetToken: token }
+    );
+    return updated === 1;
+  }
+
+  /** A log-safe reference to a presented token: a short digest of a well-formed one, never the value itself. */
+  fingerprint(presented: unknown): string | undefined {
+    const token = this.parse(presented);
+    if (token === undefined) {
+      return undefined;
+    }
+
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+  }
+
+  private parse(presented: unknown): string | undefined {
+    return typeof presented === 'string' && PasswordResetToken.SHAPE.test(presented) ? presented : undefined;
+  }
+
+  private matches(stored: string | null | undefined, presented: string): boolean {
+    if (typeof stored !== 'string' || stored.length !== presented.length) {
+      return false;
+    }
+
+    return timingSafeEqual(Buffer.from(stored), Buffer.from(presented));
+  }
+
+  private isLive(expiration: Moment | null | undefined): boolean {
+    if (!expiration) {
+      return false;
+    }
+
+    const expiresAt = moment(expiration);
+    return expiresAt.isValid() && moment().isBefore(expiresAt);
+  }
+}

package/src/routes/devMail.ts

@@ -0,0 +1,72 @@
+import { Route } from '@proteinjs/server-api';
+import { MailSink } from '@proteinjs/email-server';
+
+/**
+ * DEV-ONLY mail door: reads the process's mail sink (`@proteinjs/email-server` MailSink — the
+ * messages a development sender recorded instead of transporting), so automated dev-loop testing
+ * reads an invite or reset link from the sink instead of needing a real inbox, and nothing a dev
+ * server composes ever has to reach a real address to be verified.
+ *
+ *   GET /dev/mail[?n=<count>]  the last n messages (default 20, at most MailSink.CAPACITY), newest
+ *                              first: id, at, from, to, subject, the body's first link, refused, url
+ *   GET /dev/mail/<id>         the rendered message — its html part, or its text part as text/plain
+ *
+ * Double-gated exactly like `/dev/login` (devLogin.ts), acting only when BOTH hold; otherwise the
+ * paths answer 404 as if unregistered:
+ * 1. `process.env.DEVELOPMENT` — the dev-server switch, never set in prod images.
+ * 2. `DEV_AUTO_LOGIN_EMAIL` — the explicit per-launch dev opt-in.
+ */
+const DEFAULT_COUNT = 20;
+
+const gatesOpen = (): boolean =>
+  !!process.env.DEVELOPMENT && (process.env.DEV_AUTO_LOGIN_EMAIL ?? '').trim().length > 0;
+
+export const devMail: Route = {
+  path: '/dev/mail',
+  method: 'get',
+  onRequest: async (request, response): Promise<void> => {
+    if (!gatesOpen()) {
+      response.status(404).send();
+      return;
+    }
+    const requested = Number(request.query?.n);
+    const count = Number.isInteger(requested) && requested > 0 ? Math.min(requested, MailSink.CAPACITY) : DEFAULT_COUNT;
+    const messages = MailSink.get()
+      .list(count)
+      .map(({ id, at, from, to, subject, link, refused }) => ({
+        id,
+        at,
+        from,
+        to,
+        subject,
+        link,
+        refused,
+        url: `/dev/mail/${id}`,
+      }));
+    response.status(200).json({ messages });
+  },
+};
+
+export const devMailMessage: Route = {
+  path: '/dev/mail/:id',
+  method: 'get',
+  onRequest: async (request, response): Promise<void> => {
+    if (!gatesOpen()) {
+      response.status(404).send();
+      return;
+    }
+    const record = MailSink.get().get(String(request.params?.id ?? ''));
+    if (!record) {
+      response.status(404).send();
+      return;
+    }
+    if (record.html !== undefined) {
+      response.status(200).type('html').send(record.html);
+      return;
+    }
+    response
+      .status(200)
+      .type('text')
+      .send(record.text ?? '');
+  },
+};

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/DevMail.test.ts

@@ -0,0 +1,151 @@
+import { EmailSender, MailSink } from '@proteinjs/email-server';
+import { devMail, devMailMessage } from '../src/routes/devMail';
+
+/**
+ * `GET /dev/mail` and `GET /dev/mail/<id>` — the dev-only door onto the mail sink, gated exactly
+ * like `/dev/login`: `DEVELOPMENT` AND `DEV_AUTO_LOGIN_EMAIL`, else 404 as if unregistered. With
+ * the gates open, the last invite a development sender recorded is readable — its link off the
+ * list, its rendered html off the message — so a lane never needs a real inbox. No database:
+ * the sink is the process's own ring.
+ */
+
+const ENV_EMAIL = 'dev@test.local';
+
+type Outcome = { status?: number; body?: unknown; type?: string };
+
+const invoke = async (
+  route: typeof devMail,
+  { query, params }: { query?: Record<string, unknown>; params?: Record<string, string> } = {}
+): Promise<Outcome> => {
+  const outcome: Outcome = {};
+  const response = {
+    status(code: number) {
+      outcome.status = code;
+      return this;
+    },
+    type(kind: string) {
+      outcome.type = kind;
+      return this;
+    },
+    send(body?: unknown) {
+      outcome.body = body;
+    },
+    json(body: unknown) {
+      outcome.body = body;
+    },
+  };
+  await route.onRequest({ query: query ?? {}, params: params ?? {} } as never, response as never);
+  return outcome;
+};
+
+const INVITE_LINK = 'http://localhost:7985/auth/signup?token=abc123';
+const INVITE_HTML = `<html><body><p>You are invited.</p><a href="${INVITE_LINK}">Accept</a></body></html>`;
+
+/** The product's path onto the sink: a development sender with a real-looking SMTP config, no opt-in. */
+const sendInviteThroughSender = async (to: string): Promise<void> => {
+  await new EmailSender({
+    host: 'smtp.test.local',
+    port: 465,
+    secure: true,
+    auth: { user: 'mailbox@test.local', pass: 'unused' },
+    from: '"Example" <hi@example.com>',
+  }).sendEmail({ to, subject: "You're invited", text: `Accept your invite: ${INVITE_LINK}`, html: INVITE_HTML });
+};
+
+describe('devMail routes', () => {
+  const originalEnv = {
+    DEVELOPMENT: process.env.DEVELOPMENT,
+    DEV_AUTO_LOGIN_EMAIL: process.env.DEV_AUTO_LOGIN_EMAIL,
+    EMAIL_TRANSPORT: process.env.EMAIL_TRANSPORT,
+    EMAIL_ALLOW_REAL_SEND: process.env.EMAIL_ALLOW_REAL_SEND,
+  };
+
+  beforeEach(() => {
+    process.env.DEVELOPMENT = 'true';
+    process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
+    delete process.env.EMAIL_TRANSPORT;
+    delete process.env.EMAIL_ALLOW_REAL_SEND;
+    MailSink.get().clear();
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it("lists the last sent messages newest first — the invite's recipient, subject, first link and timestamp — and the message renders its html", async () => {
+    await sendInviteThroughSender('earlier@test.local');
+    await sendInviteThroughSender('lane-after@test.local');
+
+    const list = await invoke(devMail);
+    expect(list.status).toBe(200);
+    const { messages } = list.body as { messages: Array<Record<string, unknown>> };
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toMatchObject({
+      to: ['lane-after@test.local'],
+      subject: "You're invited",
+      link: INVITE_LINK,
+      from: 'hi@example.com',
+      refused: true,
+    });
+    expect(typeof messages[0].id).toBe('string');
+    expect(Date.parse(String(messages[0].at))).not.toBeNaN();
+    expect(messages[0].url).toBe(`/dev/mail/${messages[0].id}`);
+    expect(messages[1].to).toEqual(['earlier@test.local']);
+
+    const message = await invoke(devMailMessage, { params: { id: String(messages[0].id) } });
+    expect(message.status).toBe(200);
+    expect(message.type).toBe('html');
+    expect(message.body).toBe(INVITE_HTML);
+  });
+
+  it('?n= bounds the list; a text-only message renders as text; an unknown id is 404', async () => {
+    process.env.EMAIL_TRANSPORT = 'sink';
+    await new EmailSender({ host: 'h', port: 465, secure: true, from: '"Example" <hi@example.com>' }).sendEmail({
+      to: 'a@test.local',
+      subject: 'Plain',
+      text: 'just text',
+    });
+    await sendInviteThroughSender('b@test.local');
+
+    const one = await invoke(devMail, { query: { n: '1' } });
+    expect((one.body as { messages: unknown[] }).messages).toHaveLength(1);
+    const all = await invoke(devMail, { query: { n: 'garbage' } });
+    const { messages } = all.body as { messages: Array<{ id: string; subject: string; refused: boolean }> };
+    expect(messages.map((m) => m.subject)).toEqual(["You're invited", 'Plain']);
+    expect(messages[1].refused).toBe(false);
+
+    const plain = await invoke(devMailMessage, { params: { id: messages[1].id } });
+    expect(plain.status).toBe(200);
+    expect(plain.type).toBe('text');
+    expect(plain.body).toBe('just text');
+
+    expect((await invoke(devMailMessage, { params: { id: 'nope' } })).status).toBe(404);
+  });
+
+  it('DEVELOPMENT unset → 404 on both paths, even with messages in the sink', async () => {
+    await sendInviteThroughSender('lane@test.local');
+    const [record] = MailSink.get().list();
+    delete process.env.DEVELOPMENT;
+
+    expect((await invoke(devMail)).status).toBe(404);
+    expect((await invoke(devMailMessage, { params: { id: record.id } })).status).toBe(404);
+  });
+
+  it('DEV_AUTO_LOGIN_EMAIL unset (or blank) → 404 on both paths', async () => {
+    await sendInviteThroughSender('lane@test.local');
+    const [record] = MailSink.get().list();
+
+    delete process.env.DEV_AUTO_LOGIN_EMAIL;
+    expect((await invoke(devMail)).status).toBe(404);
+    expect((await invoke(devMailMessage, { params: { id: record.id } })).status).toBe(404);
+
+    process.env.DEV_AUTO_LOGIN_EMAIL = '   ';
+    expect((await invoke(devMail)).status).toBe(404);
+  });
+});