@proteinjs/user-server 1.8.0 → 1.9.0

package/src/routes/logout.ts

@@ -1,28 +1,23 @@
 import { Route } from '@proteinjs/server-api';
 import { routes } from '@proteinjs/user';
-import { destroySession } from '../authentication/destroySession';
 
+/**
+ * Logout rides passport's own `request.logout` (functional for store-backed sessions since
+ * passport 0.6, which added the callback form): it clears the user from the session and SAVES —
+ * a replayed old session id is logged out even before the id rotates — then REGENERATES the
+ * session id (fixation hygiene on the privilege change, mirroring login's rotation). The
+ * regenerate destroys the old session row through the store (`DbSessionStore.destroy`), whose
+ * row delete also disconnects the session's sockets (SocketIOSessionWatcher). The pre-0.6
+ * manual compensation — calling `destroySession` and nulling `session.passport.user` by hand
+ * because `request.logout` was broken — is retired with the workaround era that spawned it.
+ */
 export const logout: Route = {
   path: routes.logout.path,
   method: routes.logout.method,
   onRequest: async (request: any, response): Promise<void> => {
-    // request.logout();
-    // await request.session.destroy();
-    // await new Promise((resolve, reject) => {
-    //     request.session?.destroy((error: any) => {
-    //         if (error) {
-    //             reject(error);
-    //             return;
-    //         }
-
-    //         resolve();
-    //     });
-    // });
-    // delete request._passport?.session?.user;
-    // console.info(`request.sessionID: ${request.sessionID}`);
-    // console.info(`request.session?.id: ${request.session?.id}`);
-    await destroySession(request.sessionID);
-    request.session.passport.user = null;
+    await new Promise<void>((resolve, reject) =>
+      request.logout((error: unknown) => (error ? reject(error) : resolve()))
+    );
     response.redirect('/login');
   },
 };

package/src/routes/signup.ts

@@ -0,0 +1,55 @@
+import { Route } from '@proteinjs/server-api';
+import { Logger } from '@proteinjs/logger';
+import { UserSignup, routes } from '@proteinjs/user';
+import { establishSession } from '../authentication/establishSession';
+import { Signup } from '../services/Signup';
+
+const logger = new Logger({ name: 'signup' });
+
+/**
+ * `POST /user/signup` — create the account AND establish its session in the same request
+ * (auto-login), so a new user lands in the app instead of being bounced to the login form to
+ * re-type the credentials they just submitted. Signup lives at the route layer beside login
+ * because session establishment is a request-level concern services never see; the domain flow
+ * (invite validation, account creation, notification emails) stays owned by `Signup.createUser`.
+ *
+ * Body: `UserSignup` (+ optional invite `token`; the invite carries the email on that path).
+ * Response mirrors the login route's contract: 200 with `{}` on success, `{ error }` with
+ * user-readable copy otherwise.
+ *
+ * When the email is already registered the response is byte-identical to success but NO session
+ * is minted — auto-login must never hand out a session for an account the caller didn't just
+ * create; the caller falls through to the login screen exactly as before. Existence is reported
+ * to the mailbox owner by email, never to the caller.
+ */
+export const signup: Route = {
+  path: routes.signup.path,
+  method: routes.signup.method,
+  onRequest: async (request: any, response): Promise<void> => {
+    const body: Partial<UserSignup> & { token?: string } = request.body ?? {};
+    if (!body.name || !body.password) {
+      response.send({ error: 'Name and password cannot be blank' });
+      return;
+    }
+
+    let result;
+    try {
+      result = await new Signup().createUser(
+        { name: body.name, email: body.email, password: body.password },
+        body.token
+      );
+    } catch (error: any) {
+      // createUser throws plain-words errors deliberately (invite expired / invite required /
+      // email missing); the message is the user-facing contract, same as the RPC layer's.
+      logger.error({ message: 'Signup failed', error });
+      response.send({ error: error instanceof Error ? error.message : 'Sign up failed.' });
+      return;
+    }
+
+    if (result.outcome === 'created') {
+      await establishSession(request, result.email);
+    }
+
+    response.send({});
+  },
+};

package/src/routes/validateResetPasswordToken.ts

@@ -34,6 +34,10 @@ export const validateResetPasswordToken: Route = {
       return;
     }
 
-    response.status(200).send({ isValid: true });
+    // The account email rides the VALID response only: the reset page renders it as the
+    // 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 });
   },
 };

package/src/services/Signup.ts

@@ -55,6 +55,18 @@ export const getDefaultInviteConfigFactory = (): DefaultInviteConfigFactory => {
   return factory || defaultFactory;
 };
 
+/**
+ * `createUser`'s outcome, for the signup route's eyes only (it never crosses the wire): the
+ * route establishes a session on 'created' and must NOT on 'exists' — auto-login must never
+ * hand out a session for an account the caller didn't just create. The response body stays
+ * identical either way (existence is reported to the mailbox owner by email, not the caller).
+ */
+export type CreateUserResult = {
+  outcome: 'created' | 'exists';
+  /** The account email, lowercased — resolved from the invite when a token was provided. */
+  email: string;
+};
+
 export class Signup implements SignupService {
   public serviceMetadata = {
     auth: {
@@ -72,7 +84,13 @@ export class Signup implements SignupService {
     },
   };
 
-  async createUser(user: UserSignup, token?: string): Promise<void> {
+  /**
+   * The signup flow's account creation + notification emails. Not RPC-reachable (deliberately
+   * absent from the SignupService interface): its caller is the `routes.signup` ROUTE, which
+   * establishes the session (auto-login) from this result — a request-level concern services
+   * never see.
+   */
+  async createUser(user: UserSignup, token?: string): Promise<CreateUserResult> {
     const logger = new Logger({ name: 'Signup.createUser' });
     const db = getDbAsSystem();
 
@@ -116,7 +134,7 @@ export class Signup implements SignupService {
           ...config.options,
         });
       }
-      return;
+      return { outcome: 'exists', email };
     }
 
     const { text, html } = config.getNewUserEmailContent();
@@ -128,6 +146,7 @@ export class Signup implements SignupService {
       ...config.options,
     });
     logger.info({ message: `Created user`, obj: { email } });
+    return { outcome: 'created', email };
   }
 
   async sendInvite(email: string): Promise<SendInviteResponse> {

package/test/AccountDeletion.integration.test.ts

@@ -9,6 +9,7 @@ import { AccessGrant, ManifestGrant, User, UserRepo, guestUser, tables } from '@
 import { AccountDeletion } from '../src/services/AccountDeletion';
 import { authenticate } from '../src/authentication/authenticate';
 import { login } from '../src/routes/login';
+import { createPassportRequest } from './passportSessionHarness';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -110,9 +111,13 @@ describe('AccountDeletion — deactivation, manifest, resume, cancel-by-login',
     { id: outbound2.id, principal: userB.id, resource: r2, resourceTable: RESOURCE_TABLE, accessLevel: 'write' },
   ];
 
-  /** Drive the real login route with a fake request/response pair. */
+  /**
+   * Drive the real login route over REAL passport login machinery (passportSessionHarness):
+   * establishSession regenerates the id (fixation) and commits the session row before the route
+   * responds — both live inside passport's `request.login` now; ordering is pinned by
+   * SignupRoute.test.ts.
+   */
   const invokeLogin = async (email: string, password: string) => {
-    let loggedInAs: string | undefined;
     let sent: any;
     const response: any = {
       send: (body: any) => {
@@ -120,15 +125,13 @@ describe('AccountDeletion — deactivation, manifest, resume, cancel-by-login',
       },
       status: () => response,
     };
-    const request: any = {
-      body: { email, password },
-      login: (loginEmail: string, callback: () => void) => {
-        loggedInAs = loginEmail;
-        callback();
-      },
-    };
+    const { request, events } = await createPassportRequest({ body: { email, password } });
     await login.onRequest(request, response);
-    return { loggedInAs, sent };
+    return {
+      loggedInAs: request.session.passport?.user as string | undefined,
+      regenerated: events.includes('regenerate'),
+      sent,
+    };
   };
 
   it('the service door admits any signed-in account and refuses guests', () => {
@@ -358,10 +361,11 @@ describe('AccountDeletion — deactivation, manifest, resume, cancel-by-login',
     testEnv.actAs(userA);
     await new AccountDeletion().requestDeletion(PASSWORD_A);
 
-    const { loggedInAs, sent } = await invokeLogin(userA.email, PASSWORD_A);
+    const { loggedInAs, regenerated, sent } = await invokeLogin(userA.email, PASSWORD_A);
 
     expect(sent).toEqual({});
     expect(loggedInAs).toBe(userA.email);
+    expect(regenerated).toBe(true); // the login door inherits fresh-id-on-privilege-change
     expect((await userRow(userA.id)).status).toBe('active');
     expect(await grantRows()).toHaveLength(6);
     expect(await deletionRow(userA.id)).toBeFalsy();

package/test/DevLogin.test.ts

@@ -2,6 +2,7 @@ import { getDbAsSystem } from '@proteinjs/db';
 import { tables } from '@proteinjs/user';
 import { PasswordHasher } from '../src/authentication/PasswordHasher';
 import { devLogin } from '../src/routes/devLogin';
+import { createPassportRequest } from './passportSessionHarness';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -20,6 +21,7 @@ const ENV_EMAIL = 'dev@test.local';
 
 type RouteOutcome = {
   loggedInAs?: string;
+  sessionRegenerated: boolean;
   sessionSaved: boolean;
   status?: number;
   body?: unknown;
@@ -27,20 +29,11 @@ type RouteOutcome = {
 };
 
 const invokeDevLogin = async (query?: Record<string, unknown>): Promise<RouteOutcome> => {
-  const outcome: RouteOutcome = { sessionSaved: false };
-  const request = {
-    query,
-    login: (email: string, done: () => void) => {
-      outcome.loggedInAs = email;
-      done();
-    },
-    session: {
-      save: (done: () => void) => {
-        outcome.sessionSaved = true;
-        done();
-      },
-    },
-  };
+  // REAL passport login machinery (see passportSessionHarness): the full contract
+  // (regenerate → login → save) is pinned by SignupRoute.test.ts — here we assert the dev door
+  // INHERITS it.
+  const { request, events } = await createPassportRequest({ query });
+  const outcome: RouteOutcome = { sessionRegenerated: false, sessionSaved: false };
   const response = {
     status(code: number) {
       outcome.status = code;
@@ -54,6 +47,9 @@ const invokeDevLogin = async (query?: Record<string, unknown>): Promise<RouteOut
     },
   };
   await devLogin.onRequest(request as never, response as never);
+  outcome.loggedInAs = request.session.passport?.user;
+  outcome.sessionRegenerated = events.includes('regenerate');
+  outcome.sessionSaved = events.includes('save');
   return outcome;
 };
 
@@ -94,6 +90,7 @@ describe('devLogin route', () => {
     const outcome = await invokeDevLogin();
 
     expect(outcome.loggedInAs).toBe(ENV_EMAIL);
+    expect(outcome.sessionRegenerated).toBe(true); // fresh id on privilege change (fixation)
     expect(outcome.sessionSaved).toBe(true);
     expect(outcome.redirect).toBe('/');
     expect(outcome.status).toBeUndefined();

package/test/LogoutRoute.test.ts

@@ -0,0 +1,33 @@
+import { logout } from '../src/routes/logout';
+import { createPassportRequest } from './passportSessionHarness';
+
+/**
+ * `GET /user/logout` — logout through passport's own `request.logout` (functional for
+ * store-backed sessions since passport 0.6, which added the callback form): clear the user and
+ * SAVE (a replayed old session id is logged out even before the id rotates), then REGENERATE
+ * the session id (fixation hygiene on the privilege change, mirroring login's rotation; the
+ * regenerate is what tears down the old session row through the store). Driven over the REAL
+ * passport machinery (passportSessionHarness); outcomes asserted: the surviving session carries
+ * no user, the id was rotated, the request's user is cleared, and the client lands on /login.
+ */
+describe('logout route', () => {
+  it('clears the user, saves, regenerates the session id, and redirects to /login', async () => {
+    const { request, events } = await createPassportRequest();
+    await new Promise<void>((resolve, reject) =>
+      request.login('user@test.local', (error: unknown) => (error ? reject(error) : resolve()))
+    );
+    expect(request.session.passport.user).toBe('user@test.local'); // precondition: signed in
+    events.length = 0; // watch only the logout lifecycle
+
+    let redirect: string | undefined;
+    const response: any = { redirect: (path: string) => (redirect = path) };
+    await logout.onRequest(request as never, response as never);
+
+    // Save-then-regenerate: the old session id is deauthenticated even if its cookie is
+    // replayed, and the surviving session is a FRESH id with no user bound.
+    expect(events).toEqual(['save', 'regenerate']);
+    expect(request.session.passport?.user).toBeUndefined();
+    expect(request.user).toBeNull();
+    expect(redirect).toBe('/login');
+  });
+});

package/test/Signup.test.ts

@@ -61,9 +61,11 @@ describe('Signup service auth', () => {
     expect(canAccess('revokeInvite')).toBe(true);
   });
 
-  it('keeps the signup flow itself open (createUser / initializeSignup)', () => {
+  it('keeps the pre-submit signup flow open (initializeSignup)', () => {
+    // Account creation itself is no longer RPC-reachable — it moved to the signup ROUTE
+    // (src/routes/signup.ts, covered by SignupRoute.test.ts), which establishes the session
+    // in the same request (auto-login).
     setUser([]);
-    expect(canAccess('createUser')).toBe(true);
     expect(canAccess('initializeSignup')).toBe(true);
   });
 });

package/test/SignupRoute.test.ts

@@ -0,0 +1,219 @@
+import moment from 'moment';
+
+/**
+ * `POST /user/signup` — signup with auto-login. Signup used to be an RPC service, and services
+ * never see the request, so the client was bounced to the login form to type the credentials it
+ * had JUST submitted. Session establishment is a request-level concern; signup now lives at the
+ * route layer beside its siblings (login, dev login) and mints the session through the same
+ * single owner (`establishSession`) in the same request.
+ *
+ * Covered here, outcomes only (rows written, session minted), against the Spanner emulator:
+ * - plain signup: account row created, session established in the same request;
+ * - invited signup: email resolved from the invite, invite consumed, session established;
+ * - already-registered email: response body indistinguishable from success, but NO session —
+ *   auto-login must never hand out a session for an account the caller didn't just create;
+ * - invalid token / invite-only violations: honest error, no session, no account row.
+ *
+ * The email transport is stubbed at the module boundary (SignupInvite.test.ts pattern); the db
+ * stays real.
+ */
+
+const sendEmail = jest.fn();
+
+jest.mock('@proteinjs/email-server', () => ({
+  EmailSender: jest.fn().mockImplementation(() => ({ sendEmail })),
+  getDefaultInviteEmailConfigFactory: () => ({
+    getConfig: () => ({ getEmailContent: () => ({ text: 'invite', html: '<p>invite</p>' }) }),
+  }),
+  getDefaultSignupConfirmationEmailConfigFactory: () => ({
+    getConfig: () => ({
+      getNewUserEmailContent: () => ({ text: 'welcome', html: '<p>welcome</p>' }),
+      getExistingUserEmailContent: () => ({ text: 'exists', html: '<p>exists</p>' }),
+    }),
+  }),
+}));
+
+import { getDbAsSystem } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+import { tables } from '@proteinjs/user';
+import { signup } from '../src/routes/signup';
+import { createPassportRequest } from './passportSessionHarness';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+const INVITE_CONFIG_KEY = '@proteinjs/user-server/DefaultInviteConfigFactory';
+
+type ObjectCache = { objectCache: Record<string, unknown[]> };
+
+/** Seed the invite-config lookup (tests don't load the generated source graph). */
+const setInviteConfig = (factories: unknown[]) => {
+  (SourceRepository.get() as unknown as ObjectCache).objectCache[INVITE_CONFIG_KEY] = factories;
+};
+
+type RouteOutcome = {
+  loggedInAs?: string;
+  /**
+   * 'regenerate' / 'login' / 'save' in call order — recorded by the REAL passport 0.6 login
+   * machinery (see passportSessionHarness): regenerate FIRST (a fresh session id on privilege
+   * change, so an attacker-planted pre-auth sid never survives signup/login: session fixation),
+   * then the bind of the account onto the fresh session, then save (the row must commit before
+   * the response). Exactly one of each — a wrapper-level regenerate or save around
+   * `request.login` would double up and break the single-owner contract.
+   */
+  sessionEvents: string[];
+  status?: number;
+  body?: { error?: string };
+};
+
+const invokeSignup = async (body: Record<string, unknown>): Promise<RouteOutcome> => {
+  const { request, events } = await createPassportRequest({ body });
+  const outcome: RouteOutcome = { sessionEvents: events };
+  const response = {
+    status(code: number) {
+      outcome.status = code;
+      return this;
+    },
+    send(body?: unknown) {
+      outcome.body = body as RouteOutcome['body'];
+    },
+  };
+  await signup.onRequest(request as never, response as never);
+  // The OUTCOME of establishment: the account email bound onto the (post-regeneration) session.
+  outcome.loggedInAs = request.session.passport?.user;
+  return outcome;
+};
+
+const getUserRow = async (email: string) => await getDbAsSystem().get(tables.User, { email });
+const userRowCount = async (email: string) => (await getDbAsSystem().query(tables.User, { email })).length;
+
+describe('signup route — auto-login after signup', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    setInviteConfig([]); // default config: invite optional
+  }, 120000);
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    setInviteConfig([]);
+    const db = getDbAsSystem();
+    await db.delete(tables.Invite, {});
+    await db.delete(tables.User, {});
+  });
+
+  it('plain signup creates the account and establishes the session in the same request', async () => {
+    const outcome = await invokeSignup({
+      name: 'Plain Signup',
+      email: 'Signup.Plain@Test.local',
+      password: 'pw-plain-1',
+    });
+
+    expect(outcome.body).toEqual({});
+    expect(outcome.loggedInAs).toBe('signup.plain@test.local');
+    // Fresh id on privilege change (fixation), then login, then commit-before-response (the
+    // client's follow-up navigation must never race the store write and land on /login).
+    expect(outcome.sessionEvents).toEqual(['regenerate', 'login', 'save']);
+
+    const created = await getUserRow('signup.plain@test.local');
+    expect(created).toBeDefined();
+    // At-rest contract: argon2id from the first write (the per-login-migration KDF stores
+    // new credentials as argon2id directly — never a legacy sha256 row).
+    expect(created!.password).toMatch(/^\$argon2id\$/);
+    expect(created!.password).not.toContain('pw-plain-1');
+    expect(created!.emailVerified).toBe(false);
+    expect(created!.roles).toEqual([]);
+    expect(sendEmail).toHaveBeenCalledTimes(1); // welcome email still goes out
+  });
+
+  it('invited signup resolves the email from the invite, consumes it, and establishes the session', async () => {
+    const db = getDbAsSystem();
+    await db.insert(tables.Invite, {
+      email: 'invited@test.local',
+      token: 'invite-token-1',
+      tokenExpiresAt: moment().add(1, 'day'),
+      invitedBy: 'inviter-1',
+    });
+
+    const outcome = await invokeSignup({
+      name: 'Invited Signup',
+      password: 'pw-invited-1',
+      token: 'invite-token-1',
+    });
+
+    expect(outcome.body).toEqual({});
+    expect(outcome.loggedInAs).toBe('invited@test.local');
+    expect(outcome.sessionEvents).toEqual(['regenerate', 'login', 'save']);
+
+    const created = await getUserRow('invited@test.local');
+    expect(created).toBeDefined();
+    expect(created!.emailVerified).toBe(true); // the email came from the invite record
+    expect(created!.invitedBy).toBe('inviter-1');
+    expect(await db.get(tables.Invite, { token: 'invite-token-1' })).toBeUndefined();
+  });
+
+  it('an already-registered email answers indistinguishably but mints NO session', async () => {
+    await testEnv.createUser({ name: 'Existing User', email: 'existing@test.local' });
+
+    const outcome = await invokeSignup({
+      name: 'Existing User',
+      email: 'existing@test.local',
+      password: 'pw-existing-1',
+    });
+
+    // The response body must be exactly the success shape (anti-enumeration: existence is
+    // reported to the mailbox owner by email, never to the caller)...
+    expect(outcome.body).toEqual({});
+    // ...but auto-login must never mint a session for an account the caller didn't just create.
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(outcome.sessionEvents).toEqual([]);
+
+    expect(await userRowCount('existing@test.local')).toBe(1);
+    const existing = await getUserRow('existing@test.local');
+    expect(existing!.password).toBe('test'); // untouched — seeded by testEnv.createUser
+    expect(sendEmail).toHaveBeenCalledTimes(1); // "account already exists" email
+  });
+
+  it('an unknown invite token gets the honest error — no session, no account', async () => {
+    const outcome = await invokeSignup({
+      name: 'Token Guess',
+      password: 'pw-guess-1',
+      token: 'never-existed',
+    });
+
+    expect(outcome.body?.error).toMatch(/no longer valid/i);
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(outcome.sessionEvents).toEqual([]);
+    expect((await getDbAsSystem().query(tables.User, {})).length).toBe(0);
+  });
+
+  it('invite-only mode refuses a tokenless signup — no session, no account', async () => {
+    setInviteConfig([{ getConfig: () => ({ isInviteOnly: true }) }]);
+
+    const outcome = await invokeSignup({
+      name: 'No Invite',
+      email: 'no.invite@test.local',
+      password: 'pw-noinvite-1',
+    });
+
+    expect(outcome.body?.error).toMatch(/invite is required/i);
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(outcome.sessionEvents).toEqual([]);
+    expect(await getUserRow('no.invite@test.local')).toBeUndefined();
+  });
+
+  it('a blank name or password is refused before any write', async () => {
+    const missingName = await invokeSignup({ email: 'blank@test.local', password: 'pw-blank-1' });
+    expect(missingName.body?.error).toBeTruthy();
+    expect(missingName.sessionEvents).toEqual([]);
+
+    const missingPassword = await invokeSignup({ name: 'Blank', email: 'blank@test.local' });
+    expect(missingPassword.body?.error).toBeTruthy();
+    expect(missingPassword.sessionEvents).toEqual([]);
+
+    expect(await getUserRow('blank@test.local')).toBeUndefined();
+  });
+});

package/test/ValidateResetToken.test.ts

@@ -0,0 +1,86 @@
+import moment from 'moment';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { validateResetPasswordToken } from '../src/routes/validateResetPasswordToken';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `GET /user/validate-reset-token`. Beyond the valid/expired/unknown verdicts, the valid
+ * response carries the account EMAIL: the reset page renders it as the read-only
+ * `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).
+ */
+
+type RouteOutcome = { status?: number; body?: any };
+
+const invokeValidate = async (query: Record<string, unknown>): Promise<RouteOutcome> => {
+  const outcome: RouteOutcome = {};
+  const response = {
+    status(code: number) {
+      outcome.status = code;
+      return this;
+    },
+    send(body?: unknown) {
+      outcome.body = body;
+    },
+  };
+  await validateResetPasswordToken.onRequest({ query } as never, response as never);
+  return outcome;
+};
+
+const armResetToken = async (email: string, token: string, expiration: moment.Moment) => {
+  const user = await testEnv.createUser({ name: 'Reset User', email });
+  await getDbAsSystem().update(tables.User, {
+    id: user.id,
+    passwordResetToken: token,
+    passwordResetTokenExpiration: expiration,
+  });
+};
+
+describe('validateResetPasswordToken route', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  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 outcome = await invokeValidate({ token: 'tok-valid-1' });
+
+    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 outcome = await invokeValidate({ token: 'tok-expired-1' });
+
+    expect(outcome.status).toBe(200);
+    expect(outcome.body.isValid).toBe(false);
+    expect(outcome.body.email).toBeUndefined();
+  });
+
+  it('an unknown token resolves invalid and leaks no email', async () => {
+    const outcome = await invokeValidate({ token: 'tok-never-issued' });
+
+    expect(outcome.status).toBe(200);
+    expect(outcome.body.isValid).toBe(false);
+    expect(outcome.body.email).toBeUndefined();
+  });
+
+  it('a missing token is a 400', async () => {
+    const outcome = await invokeValidate({});
+
+    expect(outcome.status).toBe(400);
+    expect(outcome.body.isValid).toBe(false);
+  });
+});