@proteinjs/user-server 1.22.0 → 1.22.1

package/test/InitiatePasswordReset.test.ts

@@ -0,0 +1,250 @@
+import { createHash } from 'crypto';
+import moment from 'moment';
+import { getDbAsSystem } from '@proteinjs/db';
+import { EmailSender, MailSink } from '@proteinjs/email-server';
+import { SourceRepository } from '@proteinjs/reflection';
+import { tables } from '@proteinjs/user';
+import { initiatePasswordReset } from '../src/routes/initiatePasswordReset';
+import { executePasswordReset } from '../src/routes/executePasswordReset';
+import { PasswordHasher } from '../src/authentication/PasswordHasher';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+import { LogCapture } from './LogCapture';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `POST /user/initiate-password-reset`, end to end against the Spanner emulator and the mail
+ * sink — outcomes only (the mail recorded, the row written):
+ * - the token travels in the mailed link and nowhere else: the row stores its SHA-256 digest and
+ *   an expiry an hour out, never the token, and the link's token then resets the password;
+ * - a send that fails withdraws the token, so asking again straight away mails a link;
+ * - a second request inside five minutes is throttled: no new mail, the row unchanged;
+ * - an unknown address gets the same response and no mail;
+ * - a request with no body, or no usable email: 400, no mail, nothing changes;
+ * - no minted token, no leading characters of one and no full digest reach the log — on the
+ *   mailed path, the throttled repeat, the unknown address, or the failed send's error line.
+ */
+
+type RouteOutcome = { status: number; body?: any };
+
+const invoke = async (route: typeof initiatePasswordReset, request: 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 route.onRequest(request as never, response as never);
+  return outcome;
+};
+
+const GENERIC = { message: 'If an account with that email exists, we have sent a password reset link.' };
+
+const sha256Hex = (value: string) => createHash('sha256').update(value).digest('hex');
+
+const userRow = async (email: string) => await getDbAsSystem().get(tables.User, { email });
+
+/** Every stored reset token in the table, by email — the whole-table outcome a refused request must leave untouched. */
+const tokensByEmail = async (): Promise<Record<string, string | null | undefined>> => {
+  const byEmail: Record<string, string | null | undefined> = {};
+  for (const user of await getDbAsSystem().query(tables.User, {})) {
+    byEmail[user.email] = user.passwordResetToken;
+  }
+  return byEmail;
+};
+
+/** The token in a reset mail's link. */
+const tokenInLink = (mailText: string | undefined): string => {
+  const token = /[?&]token=([0-9a-f]{64})\b/.exec(mailText ?? '')?.[1];
+  if (!token) {
+    throw new Error('The mail carries no reset link');
+  }
+  return token;
+};
+
+/** The token in the newest mailed reset link. */
+const mailedToken = (): string => tokenInLink(MailSink.get().list(1)[0]?.text);
+
+type SourceRepositoryInternals = { objectCache: Record<string, unknown[]> };
+
+describe('initiatePasswordReset route', () => {
+  const originalTransport = process.env.EMAIL_TRANSPORT;
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    process.env.EMAIL_TRANSPORT = 'sink';
+    const objectCache = (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+    objectCache['@proteinjs/email-server/DefaultEmailConfigFactory'] = [
+      {
+        getEmailConfig: () => ({
+          host: 'smtp.test.local',
+          port: 465,
+          secure: true,
+          from: '"Example" <hi@example.com>',
+        }),
+      },
+    ];
+    objectCache['@proteinjs/email-server/DefaultPasswordResetEmailConfigFactory'] = [
+      {
+        getConfig: () => ({
+          getEmailContent: (resetPathWithToken: string) => ({
+            text: `Reset your password: https://app.test.local/${resetPathWithToken}`,
+          }),
+        }),
+      },
+    ];
+  });
+
+  beforeEach(() => {
+    MailSink.get().clear();
+  });
+
+  afterAll(async () => {
+    if (originalTransport === undefined) {
+      delete process.env.EMAIL_TRANSPORT;
+    } else {
+      process.env.EMAIL_TRANSPORT = originalTransport;
+    }
+    await testEnv.afterAll();
+  });
+
+  it("the token travels only in the mailed link: the row stores its digest and an hour's expiry, and the link's token resets the password", async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-live@test.local' });
+
+    const outcome = await invoke(initiatePasswordReset, { body: { email: 'Initiate-Live@test.local' } });
+
+    expect(outcome).toEqual({ status: 200, body: GENERIC });
+    const [mail] = MailSink.get().list();
+    expect(mail.to).toEqual(['initiate-live@test.local']);
+    const token = mailedToken();
+    const armed = await userRow('initiate-live@test.local');
+    expect(armed.passwordResetToken).toBe(sha256Hex(token));
+    expect(JSON.stringify(armed)).not.toContain(token);
+    const minutesOut = moment(armed.passwordResetTokenExpiration).diff(moment(), 'minutes', true);
+    expect(minutesOut).toBeGreaterThan(59);
+    expect(minutesOut).toBeLessThanOrEqual(60);
+
+    const reset = await invoke(executePasswordReset, { body: { token, newPassword: 'a new password' } });
+
+    expect(reset.status).toBe(200);
+    const row = await userRow('initiate-live@test.local');
+    await expect(new PasswordHasher().verify(row.password, 'a new password')).resolves.toBe(true);
+    expect(row.passwordResetToken).toBeNull();
+  });
+
+  it('a send that fails withdraws the token — asking again straight away mails a link', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-send-fails@test.local' });
+    const send = jest
+      .spyOn(EmailSender.prototype, 'sendEmail')
+      .mockRejectedValueOnce(new Error('Failed to send email'));
+    try {
+      const failed = await invoke(initiatePasswordReset, { body: { email: 'initiate-send-fails@test.local' } });
+
+      expect(failed.status).toBe(500);
+      const withdrawn = await userRow('initiate-send-fails@test.local');
+      expect(withdrawn.passwordResetToken).toBeNull();
+      expect(withdrawn.passwordResetTokenExpiration).toBeNull();
+    } finally {
+      send.mockRestore();
+    }
+
+    const again = await invoke(initiatePasswordReset, { body: { email: 'initiate-send-fails@test.local' } });
+
+    expect(again).toEqual({ status: 200, body: GENERIC });
+    expect(MailSink.get().list()).toHaveLength(1);
+    expect((await userRow('initiate-send-fails@test.local')).passwordResetToken).toBe(sha256Hex(mailedToken()));
+  });
+
+  it('a second request inside five minutes is throttled: no new mail, the row unchanged', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-throttled@test.local' });
+    await invoke(initiatePasswordReset, { body: { email: 'initiate-throttled@test.local' } });
+    const armed = await userRow('initiate-throttled@test.local');
+
+    const second = await invoke(initiatePasswordReset, { body: { email: 'initiate-throttled@test.local' } });
+
+    expect(second).toEqual({ status: 200, body: GENERIC });
+    expect(MailSink.get().list()).toHaveLength(1);
+    expect((await userRow('initiate-throttled@test.local')).passwordResetToken).toBe(armed.passwordResetToken);
+  });
+
+  it('a token minted more than five minutes ago is replaced: a new link is mailed and the old token stops working', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-replaced@test.local' });
+    await invoke(initiatePasswordReset, { body: { email: 'initiate-replaced@test.local' } });
+    const first = mailedToken();
+    const armed = await userRow('initiate-replaced@test.local');
+    await getDbAsSystem().update(tables.User, {
+      id: armed.id,
+      passwordResetTokenExpiration: moment().add(54, 'minutes'),
+    });
+
+    await invoke(initiatePasswordReset, { body: { email: 'initiate-replaced@test.local' } });
+
+    expect(MailSink.get().list()).toHaveLength(2);
+    const second = mailedToken();
+    expect(second).not.toBe(first);
+    expect((await userRow('initiate-replaced@test.local')).passwordResetToken).toBe(sha256Hex(second));
+    const stale = await invoke(executePasswordReset, { body: { token: first, newPassword: 'hijacked' } });
+    expect(stale.status).toBe(400);
+  });
+
+  it('no minted token, no leading characters of one and no full digest reach the log — mailed, throttled, unknown, failed send', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-log@test.local' });
+    await testEnv.createUser({ name: 'Reset User', email: 'initiate-log-send-fails@test.local' });
+    let mailed = '';
+    let withdrawn = '';
+
+    const log = await LogCapture.during(async () => {
+      await invoke(initiatePasswordReset, { body: { email: 'initiate-log@test.local' } });
+      mailed = mailedToken();
+      await invoke(initiatePasswordReset, { body: { email: 'initiate-log@test.local' } });
+      await invoke(initiatePasswordReset, { body: { email: 'initiate-log-nobody@test.local' } });
+      // The send fails after the mail was built: the token it carried is the one withdrawn.
+      const send = jest.spyOn(EmailSender.prototype, 'sendEmail').mockImplementationOnce(async (mail) => {
+        withdrawn = tokenInLink(mail.text as string);
+        throw new Error('Failed to send email');
+      });
+      try {
+        const failed = await invoke(initiatePasswordReset, { body: { email: 'initiate-log-send-fails@test.local' } });
+        expect(failed.status).toBe(500);
+      } finally {
+        send.mockRestore();
+      }
+    });
+
+    // The capture saw the route's lines: the throttle, the unknown address and the failed send logged.
+    expect(log.text).toContain('Password reset requested too soon for user');
+    expect(log.text).toContain('Password reset requested for non-existent user');
+    expect(log.text).toContain('Failed to send password reset email');
+    expect(withdrawn).not.toBe(mailed);
+    for (const token of [mailed, withdrawn]) {
+      log.expectFreeOf(token);
+    }
+  });
+
+  it('an unknown address gets the same response and no mail', async () => {
+    const outcome = await invoke(initiatePasswordReset, { body: { email: 'initiate-nobody@test.local' } });
+
+    expect(outcome).toEqual({ status: 200, body: GENERIC });
+    expect(MailSink.get().list()).toHaveLength(0);
+  });
+
+  it.each([
+    ['no body', {}],
+    ['a null body', { body: null }],
+    ['no email', { body: {} }],
+    ['a blank email', { body: { email: '' } }],
+    ['an email that is not a string', { body: { email: { toLowerCase: null } } }],
+  ])('a request with %s: 400, no mail, no token minted', async (_label, request) => {
+    const tokensBefore = await tokensByEmail();
+
+    const outcome = await invoke(initiatePasswordReset, request);
+
+    expect(outcome.status).toBe(400);
+    expect(MailSink.get().list()).toHaveLength(0);
+    expect(await tokensByEmail()).toEqual(tokensBefore);
+  });
+});

package/test/LogCapture.ts

@@ -0,0 +1,54 @@
+import { createHash } from 'crypto';
+
+/**
+ * Everything the process wrote while a run executed, as a log reader would see it: every
+ * `console` call at every level (where the default log writer sends each entry, whichever logger
+ * produced it) and every direct stdout/stderr write, one string per write. Nothing is filtered by
+ * logger name or level, so the capture holds exactly what the default configuration emits.
+ */
+export class LogCapture {
+  /** How many leading characters of a token count as the token showing up in a log. */
+  private static readonly TOKEN_PREFIX_LENGTH = 12;
+
+  private constructor(readonly lines: string[]) {}
+
+  static async during(run: () => Promise<void>): Promise<LogCapture> {
+    const lines: string[] = [];
+    const consoleSpies = (['log', 'info', 'warn', 'error', 'debug'] as const).map((level) =>
+      jest.spyOn(console, level).mockImplementation((...parts: unknown[]) => {
+        lines.push(parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' '));
+      })
+    );
+    const streamSpies = [process.stdout, process.stderr].map((stream) => {
+      const write = stream.write.bind(stream) as (...args: unknown[]) => boolean;
+      return jest.spyOn(stream, 'write').mockImplementation(((...args: unknown[]) => {
+        lines.push(String(args[0]));
+        return write(...args);
+      }) as never);
+    });
+    try {
+      await run();
+    } finally {
+      [...consoleSpies, ...streamSpies].forEach((spy) => spy.mockRestore());
+    }
+    return new LogCapture(lines);
+  }
+
+  get text(): string {
+    return this.lines.join('\n');
+  }
+
+  /**
+   * Fails unless the log is free of `token` in every form that would let a log reader act on it
+   * or tie a line to a row: the token, the SHA-256 digest a row stores for it, and the token's
+   * own leading characters — a log reference to a token is cut from its digest, never from the
+   * token. Letter case is ignored.
+   */
+  expectFreeOf(token: string): void {
+    const text = this.text.toLowerCase();
+    const digest = createHash('sha256').update(token).digest('hex');
+    expect(text).not.toContain(token.toLowerCase());
+    expect(text).not.toContain(digest);
+    expect(text).not.toContain(token.slice(0, LogCapture.TOKEN_PREFIX_LENGTH).toLowerCase());
+  }
+}

package/test/MalformedResetTokens.ts

@@ -0,0 +1,27 @@
+/**
+ * The `token` field of a request that does not carry a well-formed reset token: every type a
+ * parsed body or query string can deliver, and every near-miss of the token's shape. The
+ * near-misses are cut from a LIVE token, so a shape check that loosens (a lost anchor, a wider
+ * length, a case-insensitive class, a missing type check) would be looking up something derived
+ * from a real credential — and the suites that use this table assert that no lookup is built.
+ */
+export class MalformedResetTokens {
+  static readonly CASES: [label: string, tokenField: (liveToken: string) => Record<string, unknown>][] = [
+    ['absent', () => ({})],
+    ['undefined', () => ({ token: undefined })],
+    ['null', () => ({ token: null })],
+    ['empty', () => ({ token: '' })],
+    ['a string of another shape', () => ({ token: 'tok-valid-1' })],
+    ['a number', () => ({ token: 123 })],
+    ['true', () => ({ token: true })],
+    ['an array', () => ({ token: ['a', 'b'] })],
+    ['an array holding the live token', (liveToken) => ({ token: [liveToken] })],
+    ['an object', () => ({ token: { passwordResetToken: null } })],
+    ['63 hex characters of the live token', (liveToken) => ({ token: liveToken.slice(0, 63) })],
+    ['the live token and one more hex character', (liveToken) => ({ token: `${liveToken}a` })],
+    ['the live token in uppercase hex', (liveToken) => ({ token: liveToken.toUpperCase() })],
+    ['the live token and a trailing newline', (liveToken) => ({ token: `${liveToken}\n` })],
+    ['the live token after a leading space', (liveToken) => ({ token: ` ${liveToken}` })],
+    ['64 characters that are not hex', () => ({ token: 'g'.repeat(64) })],
+  ];
+}

package/test/ValidateResetToken.test.ts

@@ -1,9 +1,13 @@
+import { createHash } from 'crypto';
 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';
+import { DbTraffic } from './DbTraffic';
+import { LogCapture } from './LogCapture';
+import { MalformedResetTokens } from './MalformedResetTokens';
 
 const testEnv = new UserServerTestEnvironment();
 
@@ -14,8 +18,15 @@ const testEnv = new UserServerTestEnvironment();
  * 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). 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.
+ * that is not a well-formed token — every type a parsed query string can deliver, and every
+ * near-miss cut from a live token — is invalid without a lookup: nothing reaches the database
+ * (no lookup built, no statement run), which the verdict alone could not prove, since a wrongly
+ * admitted value still matches no row. The row stores the token's SHA-256 digest, never the
+ * token: the stored digest presented as a token is invalid — it has a token's shape, so the one
+ * lookup it builds is by the digest OF the presented value — and so is a token an earlier
+ * release stored in clear. No token, no leading characters of one and no full digest reach the
+ * log. Live tokens are seeded through `PasswordResetToken.mint`, so the suite moves with what
+ * the owner stores.
  */
 
 type RouteOutcome = { status?: number; body?: any };
@@ -35,15 +46,19 @@ const invokeValidate = async (query: Record<string, unknown>): Promise<RouteOutc
   return outcome;
 };
 
-const mintToken = () => new PasswordResetToken().mint();
+const sha256Hex = (value: string) => createHash('sha256').update(value).digest('hex');
 
-const armResetToken = async (email: string, token: string, expiration: moment.Moment) => {
+/** A well-formed token that was never issued to anyone. */
+const unissuedToken = () => sha256Hex(`never issued ${Math.random()}`);
+
+/** A user with a token minted by the owner; `expiration` (when given) replaces the expiry the mint stored. */
+const armResetToken = async (email: string, expiration?: moment.Moment): Promise<string> => {
   const user = await testEnv.createUser({ name: 'Reset User', email });
-  await getDbAsSystem().update(tables.User, {
-    id: user.id,
-    passwordResetToken: token,
-    passwordResetTokenExpiration: expiration,
-  });
+  const token = await new PasswordResetToken().mint(user);
+  if (expiration !== undefined) {
+    await getDbAsSystem().update(tables.User, { id: user.id, passwordResetTokenExpiration: expiration });
+  }
+  return token;
 };
 
 describe('validateResetPasswordToken route', () => {
@@ -56,8 +71,7 @@ describe('validateResetPasswordToken route', () => {
   });
 
   it('a valid token resolves isValid WITH the account email (the reset form identifier)', async () => {
-    const token = mintToken();
-    await armResetToken('reset-valid@test.local', token, moment().add(1, 'hour'));
+    const token = await armResetToken('reset-valid@test.local');
 
     const outcome = await invokeValidate({ token });
 
@@ -66,8 +80,7 @@ describe('validateResetPasswordToken route', () => {
   });
 
   it('an expired token resolves invalid and leaks no email', async () => {
-    const token = mintToken();
-    await armResetToken('reset-expired@test.local', token, moment().subtract(1, 'minute'));
+    const token = await armResetToken('reset-expired@test.local', moment().subtract(1, 'minute'));
 
     const outcome = await invokeValidate({ token });
 
@@ -77,28 +90,99 @@ describe('validateResetPasswordToken route', () => {
   });
 
   it('an unknown token resolves invalid and leaks no email', async () => {
-    const outcome = await invokeValidate({ token: mintToken() });
+    const outcome = await invokeValidate({ token: unissuedToken() });
 
     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 });
+  it('the stored digest presented as a token resolves invalid — the row holds nothing that can be presented', async () => {
+    const token = await armResetToken('reset-digest@test.local');
+    const row = await getDbAsSystem().get(tables.User, { email: 'reset-digest@test.local' });
+    expect(row.passwordResetToken).toBe(sha256Hex(token));
+
+    const { result: outcome, traffic } = await DbTraffic.during(
+      testEnv.spannerDriver,
+      async () => await invokeValidate({ token: row.passwordResetToken })
+    );
 
     expect(outcome.status).toBe(200);
     expect(outcome.body).toEqual({ isValid: false, message: 'Invalid token' });
+    expect(traffic.lookups).toEqual([{ passwordResetToken: sha256Hex(sha256Hex(token)) }]);
+    expect(traffic.statements).toBe(1);
+    expect(traffic.writes).toBe(0);
   });
 
-  it('a missing token is a 400', async () => {
-    const outcome = await invokeValidate({});
+  it('a token an earlier release stored in clear resolves invalid — no migration, the person asks again', async () => {
+    const clearToken = unissuedToken();
+    const user = await testEnv.createUser({ name: 'Reset User', email: 'reset-stored-in-clear@test.local' });
+    await getDbAsSystem().update(tables.User, {
+      id: user.id,
+      passwordResetToken: clearToken,
+      passwordResetTokenExpiration: moment().add(1, 'hour'),
+    });
 
-    expect(outcome.status).toBe(400);
-    expect(outcome.body.isValid).toBe(false);
+    const outcome = await invokeValidate({ token: clearToken });
+
+    expect(outcome.status).toBe(200);
+    expect(outcome.body).toEqual({ isValid: false, message: 'Invalid token' });
+  });
+
+  describe('a query without a well-formed token is invalid without a lookup', () => {
+    let liveToken: string;
+
+    beforeAll(async () => {
+      liveToken = await armResetToken('reset-shapes@test.local');
+    });
+
+    it.each(MalformedResetTokens.CASES)(
+      '%s: invalid, no email, and nothing reaches the database',
+      async (_label, tokenField) => {
+        const query = tokenField(liveToken);
+
+        const { result: outcome, traffic } = await DbTraffic.during(
+          testEnv.spannerDriver,
+          async () => await invokeValidate(query)
+        );
+
+        // Nothing usable in the query is a 400; anything else that is not a token is an invalid token.
+        expect(outcome).toEqual(
+          query.token
+            ? { status: 200, body: { isValid: false, message: 'Invalid token' } }
+            : { status: 400, body: { isValid: false, message: 'No token provided' } }
+        );
+        expect(traffic).toEqual(DbTraffic.NONE);
+      }
+    );
+
+    it('after every refusal the live token is still valid', async () => {
+      const outcome = await invokeValidate({ token: liveToken });
+
+      expect(outcome.body).toEqual({ isValid: true, email: 'reset-shapes@test.local' });
+    });
+  });
+
+  it('no token, no leading characters of one and no full digest reach the log — every verdict', async () => {
+    const live = await armResetToken('reset-log-live@test.local');
+    const expired = await armResetToken('reset-log-expired@test.local', moment().subtract(1, 'minute'));
+    const unissued = unissuedToken();
+
+    const log = await LogCapture.during(async () => {
+      await invokeValidate({ token: unissued });
+      await invokeValidate({ token: live.toUpperCase() });
+      await invokeValidate({ token: sha256Hex(live) });
+      await invokeValidate({ token: expired });
+      await invokeValidate({ token: live });
+    });
+
+    // The capture saw the route's lines: the refusals above logged.
+    expect(log.text).toContain('Invalid reset token used');
+    expect(log.text).toContain('Expired reset token used');
+    expect(log.lines.length).toBeGreaterThanOrEqual(4);
+    // The digest presented as a token is covered by `live`: its full digest is what was presented.
+    for (const token of [unissued, live, expired]) {
+      log.expectFreeOf(token);
+    }
   });
 });

package/test/emulatorLock.js

@@ -7,11 +7,10 @@
  * FAILED_PRECONDITION). This lock closes that gap for this package: a lockfile in os.tmpdir()
  * keyed by the emulator host string, held for the whole jest run via globalSetup/globalTeardown.
  *
- * The lockfile PATH FORMULA must stay byte-identical to the fleet's canonical implementation
- * (`EmulatorLock.lockFilePathFor` in @n3xah/thought-common/test) so suites from every repo
- * pointed at the same emulator actually contend on the same file. The logic is duplicated here
- * because this repo sits BELOW @n3xah in the dependency layering (thought-common itself depends
- * on @proteinjs/user) — future extraction target: @proteinjs/db-driver-spanner/test, beside
+ * The lockfile PATH FORMULA must stay byte-identical in every copy of this lock (other
+ * repositories' suites, a consumer application's suites) so runs pointed at the same emulator
+ * actually contend on the same file. The logic is duplicated here because no shared package
+ * carries it yet — future extraction target: @proteinjs/db-driver-spanner/test, beside
  * SpannerEmulatorProvisioner.
  */
 const crypto = require('crypto');
@@ -30,7 +29,7 @@ function lockFilePathFor(host) {
     .replace(/^-+|-+$/g, '')
     .slice(0, 64);
   const hash = crypto.createHash('sha1').update(host).digest('hex').slice(0, 8);
-  return path.join(os.tmpdir(), `n3xa-spanner-emulator-${slug}-${hash}.lock`);
+  return path.join(os.tmpdir(), `spanner-emulator-${slug}-${hash}.lock`);
 }
 
 function isPidAlive(pid) {

package/test/emulatorLock.test.ts

@@ -0,0 +1,32 @@
+import crypto from 'crypto';
+import os from 'os';
+import path from 'path';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { lockFilePathFor } = require('./emulatorLock') as { lockFilePathFor: (host: string) => string };
+
+/**
+ * The lockfile path is a CONTRACT between every copy of the emulator lock: two jest runs only
+ * serialize when they compute the same file for the same emulator host. The formula is pinned
+ * here byte for byte — a neutral `spanner-emulator-` name (no application's name belongs in a
+ * shared lock), the sanitized host slug, and the first 8 hex characters of the host's sha1.
+ */
+describe('emulatorLock.lockFilePathFor', () => {
+  const expectedFor = (host: string, slug: string) =>
+    path.join(
+      os.tmpdir(),
+      `spanner-emulator-${slug}-${crypto.createHash('sha1').update(host).digest('hex').slice(0, 8)}.lock`
+    );
+
+  it('names the lock by the emulator alone: spanner-emulator-<slug>-<sha1[0..8]>.lock in os.tmpdir()', () => {
+    expect(lockFilePathFor('localhost:9010')).toBe(expectedFor('localhost:9010', 'localhost-9010'));
+    expect(lockFilePathFor('127.0.0.1:9710')).toBe(expectedFor('127.0.0.1:9710', '127-0-0-1-9710'));
+  });
+
+  it('gives two emulators two files, and one emulator the same file every time', () => {
+    expect(lockFilePathFor('localhost:9010')).toBe(lockFilePathFor('localhost:9010'));
+    expect(lockFilePathFor('localhost:9010')).not.toBe(lockFilePathFor('localhost:9011'));
+    // The hash keeps hosts apart even when their slugs collide.
+    expect(lockFilePathFor('localhost:9010')).not.toBe(lockFilePathFor('localhost-9010'));
+  });
+});

package/test/emulatorLockName.test.ts

@@ -0,0 +1,33 @@
+import os from 'os';
+import path from 'path';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { lockFilePathFor } = require('./emulatorLock') as { lockFilePathFor: (host: string) => string };
+
+/**
+ * The emulator lock's FILE NAME is a contract between every copy of the lock: two jest runs
+ * serialize on a shared emulator only when they compute the same file for the same host. No
+ * shared package carries the lock yet, so the contract is pinned by value — this table is the
+ * same, row for row, in every repository that keeps a copy. A change to a row here is a change
+ * to all of them, made in the same window; a copy that drifts stops contending, silently.
+ */
+// [emulator host, lock file name, what the row pins]
+const LOCK_FILE_NAMES: [string, string, string][] = [
+  ['localhost:9010', 'spanner-emulator-localhost-9010-0091e79a.lock', 'the default shared emulator'],
+  [
+    'localhost-9010',
+    'spanner-emulator-localhost-9010-493b66d1.lock',
+    'the same slug as the row above: the hash alone keeps two hosts apart',
+  ],
+  [
+    '[emulator.a-host-name-long-enough-to-run-past-the-sixty-four-cap.example.test]:9010',
+    'spanner-emulator-emulator-a-host-name-long-enough-to-run-past-the-sixty-four-cap--fe958a1a.lock',
+    'edge dashes trimmed first, the slug capped at 64 second (the cap lands on a dash, and it stays)',
+  ],
+];
+
+describe('the emulator lock file name (the contract every copy of the lock shares)', () => {
+  it.each(LOCK_FILE_NAMES)('%s locks on %s (%s)', (host, fileName) => {
+    expect(lockFilePathFor(host)).toBe(path.join(os.tmpdir(), fileName));
+  });
+});