@proteinjs/user-server 1.20.2 → 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/src/services/Signup.ts

@@ -19,6 +19,7 @@ import {
   EmailSender,
   getDefaultInviteEmailConfigFactory,
   getDefaultSignupConfirmationEmailConfigFactory,
+  InviteEmailConfig,
 } from '@proteinjs/email-server';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { PasswordHasher } from '../authentication/PasswordHasher';
@@ -75,7 +76,7 @@ export class Signup implements SignupService {
         // previously evaluated the check WITHOUT returning it, which made sendInvite/revokeInvite
         // effectively public — any caller (even logged out) could mint themselves a valid signup
         // token and bypass invite-only signup.
-        if (methodName === 'sendInvite' || methodName === 'revokeInvite') {
+        if (methodName === 'sendInvite' || methodName === 'resendInvite' || methodName === 'revokeInvite') {
           return UserAuth.hasPermission(USER_PERMISSIONS.users);
         }
 
@@ -159,17 +160,8 @@ export class Signup implements SignupService {
         return { sent: false, error: 'User already exists with that email.' };
       }
 
-      const emailSender = new EmailSender();
-      const defaultConfigFactory = getDefaultInviteEmailConfigFactory();
-      if (!defaultConfigFactory) {
-        throw new Error(
-          `Unable to find a @proteinjs/email-server/DefaultInviteEmailConfigFactory implementation when sending invite.`
-        );
-      }
-      const config = defaultConfigFactory.getConfig();
-
-      const token = lib.WordArray.random(32).toString();
-      const tokenExpiresAt = moment().add(INVITE_TOKEN_TTL_DAYS, 'days');
+      const config = this.inviteEmailConfig();
+      const { token, tokenExpiresAt } = this.mintInviteToken();
       let invite = await db.get(tables.Invite, { email: caseInsensitiveEmail });
       if (invite) {
         invite = {
@@ -188,15 +180,7 @@ export class Signup implements SignupService {
         });
       }
 
-      const { text, html } = config.getEmailContent(`${uiRoutes.auth.signup}?token=${token}`);
-      await emailSender.sendEmail({
-        to: caseInsensitiveEmail,
-        subject: config.options?.subject || `You're Invited`,
-        text,
-        html,
-        ...config.options,
-      });
-
+      await this.emailInvite(caseInsensitiveEmail, token, config);
       return { sent: true };
     } catch (error: any) {
       logger.error({ message: 'Error sending invite', obj: { email: caseInsensitiveEmail }, error });
@@ -207,6 +191,41 @@ export class Signup implements SignupService {
     }
   }
 
+  /**
+   * Re-sends a standing invite: the token in the earlier email stops working, a fresh token with
+   * a fresh expiry takes its place on the same row (never a second row), and the invite email goes
+   * out again through the same config. Refused when no invite stands for the address — there is
+   * nothing to re-send — and when the address already has an account (the invite was used).
+   * The inviter stays whoever sent it first.
+   */
+  async resendInvite(email: string): Promise<SendInviteResponse> {
+    const logger = new Logger({ name: 'Signup.resendInvite' });
+    const caseInsensitiveEmail = email.toLowerCase();
+    try {
+      const db = getDbAsSystem();
+      const userRecord = await db.get(tables.User, { email: caseInsensitiveEmail });
+      if (userRecord) {
+        return { sent: false, error: 'User already exists with that email.' };
+      }
+      const invite = await db.get(tables.Invite, { email: caseInsensitiveEmail });
+      if (!invite) {
+        return { sent: false, error: 'No invite exists for that email.' };
+      }
+
+      const config = this.inviteEmailConfig();
+      const { token, tokenExpiresAt } = this.mintInviteToken();
+      await db.update(tables.Invite, { ...invite, token, tokenExpiresAt });
+      await this.emailInvite(caseInsensitiveEmail, token, config);
+      return { sent: true };
+    } catch (error: any) {
+      logger.error({ message: 'Error re-sending invite', obj: { email: caseInsensitiveEmail }, error });
+      return {
+        sent: false,
+        error: 'Error occurred.',
+      };
+    }
+  }
+
   async revokeInvite(email: string): Promise<void> {
     if (!email) {
       throw new Error('No email was provided.');
@@ -322,4 +341,35 @@ export class Signup implements SignupService {
 
     return { status: 'valid', invite };
   }
+
+  /** The invite email content factory the consumer registers; its absence is a misconfiguration, said aloud. */
+  private inviteEmailConfig(): InviteEmailConfig {
+    const defaultConfigFactory = getDefaultInviteEmailConfigFactory();
+    if (!defaultConfigFactory) {
+      throw new Error(
+        `Unable to find a @proteinjs/email-server/DefaultInviteEmailConfigFactory implementation when sending invite.`
+      );
+    }
+    return defaultConfigFactory.getConfig();
+  }
+
+  /** A fresh redeemable token with its expiry from the TTL knob — the one minting path for send and re-send. */
+  private mintInviteToken(): { token: string; tokenExpiresAt: moment.Moment } {
+    return {
+      token: lib.WordArray.random(32).toString(),
+      tokenExpiresAt: moment().add(INVITE_TOKEN_TTL_DAYS, 'days'),
+    };
+  }
+
+  /** The invite email itself — the signup link carrying `token`, rendered by the consumer's config. */
+  private async emailInvite(email: string, token: string, config: InviteEmailConfig): Promise<void> {
+    const { text, html } = config.getEmailContent(`${uiRoutes.auth.signup}?token=${token}`);
+    await new EmailSender().sendEmail({
+      to: email,
+      subject: config.options?.subject || `You're Invited`,
+      text,
+      html,
+      ...config.options,
+    });
+  }
 }

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

@@ -0,0 +1,163 @@
+import moment from 'moment';
+
+/**
+ * Re-sending an invite (`SignupService.resendInvite`), against the emulator — outcomes on the row
+ * and on the transport fake, never call counts alone:
+ *
+ *  - the token in the earlier email stops resolving, the fresh one resolves to the SAME invite;
+ *  - the row count for the address stays one, its expiry re-stamped from the TTL knob, its inviter kept;
+ *  - exactly one email goes out for the re-send, to the address, carrying the fresh signup link;
+ *  - an address with no standing invite is refused: nothing written, nothing sent;
+ *  - an address that already has an account is refused the same way (the invite was used).
+ *
+ * The email transport is stubbed at the module boundary (the SignupInvite.test.ts pattern) — SMTP
+ * is an external transport; the config fake echoes the signup path so the link can be asserted.
+ * The service door (`serviceMetadata.auth`) is pinned here too: re-send rides the 'users' permission
+ * exactly like send and revoke — the earlier gap that left invite minting public must not reopen.
+ */
+
+const sendEmail = jest.fn();
+jest.mock('@proteinjs/email-server', () => ({
+  EmailSender: jest.fn().mockImplementation(() => ({ sendEmail })),
+  getDefaultInviteEmailConfigFactory: () => ({
+    getConfig: () => ({
+      options: { subject: 'Your invite' },
+      getEmailContent: (signupPathWithToken: string) => ({
+        text: `Accept: /${signupPathWithToken}`,
+        html: `<a href="/${signupPathWithToken}">Accept</a>`,
+      }),
+    }),
+  }),
+  getDefaultSignupConfirmationEmailConfigFactory: () => ({
+    getConfig: () => ({ getNewUserEmailContent: () => ({ text: 'welcome', html: '<p>welcome</p>' }) }),
+  }),
+}));
+
+import { getDbAsSystem } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+import { tables, UserAuth, USER_PERMISSIONS, type Invite, type User } from '@proteinjs/user';
+import { INVITE_TOKEN_TTL_DAYS, Signup } from '../src/services/Signup';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const TIMEOUT = 60_000;
+
+/** Tolerance for the clock advancing between the stamp and the assertion. */
+const CLOCK_SKEW_TOLERANCE_SECONDS = 60;
+
+const inviteRows = async (email: string): Promise<Invite[]> =>
+  (await getDbAsSystem().query(tables.Invite, { email })) as Invite[];
+
+/** The re-send's own transport call: the one addressed to `email` after the earlier `before` calls. */
+const emailsTo = (email: string) =>
+  sendEmail.mock.calls.map(([message]) => message).filter((message) => message.to === email);
+
+describe('SignupService.resendInvite — against the emulator', () => {
+  const env = new UserServerTestEnvironment();
+  let inviter: User;
+
+  beforeAll(async () => {
+    await env.beforeAll();
+    // The invite-mode factory the token lookup consults (`initializeSignup`) — seeded like the
+    // environment seeds its own loadables (the suites load src, never the generated source
+    // graph, so an unseeded lookup has no graph to walk); invite-optional, the library default.
+    (SourceRepository.get() as unknown as { objectCache: Record<string, unknown[]> }).objectCache[
+      '@proteinjs/user-server/DefaultInviteConfigFactory'
+    ] = [{ getConfig: () => ({ isInviteOnly: false }) }];
+    inviter = await env.createUser({ name: 'Inviter', email: 'inviter@example.com', roles: ['admin'] });
+    env.actAs(inviter);
+  }, TIMEOUT);
+
+  afterAll(async () => {
+    await env.afterAll();
+  }, TIMEOUT);
+
+  beforeEach(() => {
+    sendEmail.mockClear();
+  });
+
+  it(
+    'retires the earlier token, mints a fresh one on the SAME row, and emails the fresh link exactly once',
+    async () => {
+      const email = 'guest@example.com';
+      const sent = await new Signup().sendInvite(email);
+      expect(sent).toEqual({ sent: true });
+      const [standing] = await inviteRows(email);
+      const earlierToken = standing.token as string;
+      const earlierExpiry = moment(standing.tokenExpiresAt);
+      expect(emailsTo(email)).toHaveLength(1);
+
+      const resent = await new Signup().resendInvite('Guest@Example.com');
+      expect(resent).toEqual({ sent: true });
+
+      // One row — the same record, a fresh token, the inviter kept.
+      const rows = await inviteRows(email);
+      expect(rows).toHaveLength(1);
+      const [refreshed] = rows;
+      expect(refreshed.id).toBe(standing.id);
+      expect(refreshed.token).not.toBe(earlierToken);
+      expect(refreshed.invitedBy?._id).toBe(inviter.id);
+      // The expiry is re-stamped from the knob (fresh window), never left at the earlier stamp.
+      expect(moment(refreshed.tokenExpiresAt).isSameOrAfter(earlierExpiry)).toBe(true);
+      expect(
+        Math.abs(moment(refreshed.tokenExpiresAt).diff(moment().add(INVITE_TOKEN_TTL_DAYS, 'days'), 'seconds'))
+      ).toBeLessThan(CLOCK_SKEW_TOLERANCE_SECONDS);
+
+      // The earlier link is dead; the fresh one opens signup for this invite.
+      const earlier = await new Signup().initializeSignup(earlierToken);
+      expect(earlier.isReady).toBe(false);
+      expect(earlier.error).toMatch(/no longer valid/i);
+      const fresh = await new Signup().initializeSignup(refreshed.token as string);
+      expect(fresh.isReady).toBe(true);
+      expect(fresh.invite?.email).toBe(email);
+
+      // Exactly one more email, to the address, carrying the fresh token and none of the earlier one.
+      const messages = emailsTo(email);
+      expect(messages).toHaveLength(2);
+      const resend = messages[1];
+      expect(resend.subject).toBe('Your invite');
+      expect(resend.text).toContain(`signup?token=${refreshed.token}`);
+      expect(resend.html).toContain(`signup?token=${refreshed.token}`);
+      expect(resend.text).not.toContain(earlierToken);
+    },
+    TIMEOUT
+  );
+
+  it(
+    'refuses an address with no standing invite — nothing written, nothing sent',
+    async () => {
+      const email = 'nobody@example.com';
+      const response = await new Signup().resendInvite(email);
+      expect(response.sent).toBe(false);
+      expect(response.error).toMatch(/no invite/i);
+      expect(await inviteRows(email)).toHaveLength(0);
+      expect(emailsTo(email)).toHaveLength(0);
+    },
+    TIMEOUT
+  );
+
+  it(
+    'refuses an address that already has an account — the invite was used',
+    async () => {
+      const email = 'member@example.com';
+      await env.createUser({ name: 'Member', email });
+      const response = await new Signup().resendInvite(email);
+      expect(response.sent).toBe(false);
+      expect(response.error).toMatch(/already exists/i);
+      expect(emailsTo(email)).toHaveLength(0);
+    },
+    TIMEOUT
+  );
+
+  it('rides the users-permission door like send and revoke (never public)', () => {
+    const hasPermission = jest.spyOn(UserAuth, 'hasPermission');
+    try {
+      hasPermission.mockReturnValue(false);
+      expect(new Signup().serviceMetadata.auth.canAccess('resendInvite', ['x@example.com'])).toBe(false);
+      hasPermission.mockReturnValue(true);
+      expect(new Signup().serviceMetadata.auth.canAccess('resendInvite', ['x@example.com'])).toBe(true);
+      expect(hasPermission).toHaveBeenCalledWith(USER_PERMISSIONS.users);
+    } finally {
+      hasPermission.mockRestore();
+    }
+  });
+});