@proteinjs/user-server 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/user-server",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "User server components",
   "publishConfig": {
     "access": "public"
@@ -22,14 +22,15 @@
     "test": "jest --runInBand --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db": "^1.28.1",
-    "@proteinjs/db-file": "^1.4.5",
+    "@proteinjs/db": "^1.34.1",
+    "@proteinjs/db-file": "^1.5.1",
     "@proteinjs/email-server": "^1.3.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.1.12",
     "@proteinjs/server": "^3.2.1",
     "@proteinjs/server-api": "^3.0.11",
-    "@proteinjs/user": "^1.8.0",
+    "@proteinjs/user": "^1.9.0",
+    "argon2": "^0.45.1",
     "crypto-js": "4.0.0",
     "express-session": "1.17.1",
     "heic-decode": "^2.1.0",
@@ -37,12 +38,13 @@
     "sharp": "0.33.4"
   },
   "devDependencies": {
-    "@proteinjs/db-driver-spanner": "^1.16.0",
+    "@proteinjs/db-driver-spanner": "^1.22.1",
     "@proteinjs/reflection-build": "^1.4.10",
     "@types/crypto-js": "4.0.1",
     "@types/express-session": "1.17.0",
     "@types/jest": "29.5.5",
     "@types/node": "14.0.13",
+    "@types/nodemailer": "6.4.15",
     "@typescript-eslint/eslint-plugin": "7.8.0",
     "@typescript-eslint/parser": "7.8.0",
     "eslint": "8.57.0",
@@ -54,5 +56,5 @@
   },
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
-  "gitHead": "ca5406c5d08120454950abcb42a54bf77531b3e0"
+  "gitHead": "9f0638dcd6baef3d93c04ef399dcd8909ea7cf45"
 }

package/src/authentication/PasswordHasher.ts

@@ -0,0 +1,87 @@
+import { createHash, timingSafeEqual } from 'crypto';
+import * as argon2 from 'argon2';
+
+/**
+ * `human` credentials are human-chosen (low-entropy) and get the full KDF; `machine` credentials
+ * are 256-bit generated secrets (MachineCredentials mint) where key stretching adds no security —
+ * the secret's entropy already exceeds any brute-force budget — and a ~100ms KDF would tax the
+ * bridge's log-in-fresh-per-poll pattern for nothing, so they stay sha256.
+ */
+export type PasswordHashMode = 'human' | 'machine';
+
+/**
+ * The one owner of credential hashing. Every path that writes or checks the user table's
+ * `password` column goes through this class: authenticate (login), Signup.createAccount,
+ * executePasswordReset, UpdateUserInfo.updatePassword, AccountDeletion re-auth, and
+ * MachineCredentials minting.
+ *
+ * Exactly two self-describing at-rest formats:
+ * - argon2id encoded (`$argon2id$v=19$m=...,t=...,p=...$<salt>$<hash>`) — human passwords.
+ *   The per-user random salt and the cost parameters live inside the encoded string.
+ * - sha256 hex (64 chars, never starts with `$`) — the legacy human format (pre-KDF rows,
+ *   upgraded in place on next login via verify-then-rehash) AND the permanent machine format
+ *   (see `PasswordHashMode`).
+ */
+export class PasswordHasher {
+  /**
+   * argon2id cost, pinned so a package upgrade can't silently change what we write: 64 MiB
+   * memory, 3 passes, parallelism 4 — RFC 9106's second recommended parameter set (its
+   * memory-constrained option). Measured ~23ms/hash on an M-series dev machine — the ~100ms
+   * class on typical server vCPUs.
+   */
+  private static readonly ARGON2_OPTIONS: argon2.HashOptions = {
+    type: argon2.argon2id,
+    memoryCost: 65536,
+    timeCost: 3,
+    parallelism: 4,
+  };
+
+  private static readonly ARGON2ID_PREFIX = '$argon2id$';
+
+  async hash(password: string, mode: PasswordHashMode = 'human'): Promise<string> {
+    if (mode === 'machine') {
+      return this.sha256Hex(password);
+    }
+
+    return await argon2.hash(password, PasswordHasher.ARGON2_OPTIONS);
+  }
+
+  /**
+   * Format-discriminating verify. `storedHash` absent means the row has no credential yet
+   * (a machine row before its first mint) — no password matches it.
+   */
+  async verify(storedHash: string | null | undefined, password: string): Promise<boolean> {
+    if (!storedHash) {
+      return false;
+    }
+
+    if (storedHash.startsWith(PasswordHasher.ARGON2ID_PREFIX)) {
+      return await argon2.verify(storedHash, password);
+    }
+
+    return this.constantTimeEqual(storedHash, this.sha256Hex(password));
+  }
+
+  /**
+   * True when a verified credential should be re-written in the current format: legacy sha256
+   * under `human` mode. Machine rows never rehash — sha256 IS their current format.
+   */
+  needsRehash(storedHash: string, mode: PasswordHashMode = 'human'): boolean {
+    if (mode === 'machine') {
+      return false;
+    }
+
+    return !storedHash.startsWith(PasswordHasher.ARGON2ID_PREFIX);
+  }
+
+  /** Byte-identical to the legacy crypto-js `sha256(value).toString()` (UTF-8 in, lowercase hex out). */
+  private sha256Hex(value: string): string {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+  }
+
+  private constantTimeEqual(stored: string, candidate: string): boolean {
+    const storedBytes = Buffer.from(stored, 'utf8');
+    const candidateBytes = Buffer.from(candidate, 'utf8');
+    return storedBytes.length === candidateBytes.length && timingSafeEqual(storedBytes, candidateBytes);
+  }
+}

package/src/authentication/UserStatusTableWatcher.ts

@@ -0,0 +1,56 @@
+import { QueryBuilder, Table, TableWatcher, getDbAsSystem } from '@proteinjs/db';
+import { User, tables } from '@proteinjs/user';
+import { Logger } from '@proteinjs/logger';
+
+/**
+ * The one owner of "deactivated ⇒ sessions die": any user-table update writing
+ * `status: 'deactivated'` deletes the account's session rows (SocketIOSessionWatcher kicks the
+ * live sockets on that delete). Because the writers all go through `Db.update` — the staff
+ * toggle (SetUserStatus), account deletion, and the boot sync deactivating machine accounts
+ * removed from source — this fires for every present and future deactivation path.
+ *
+ * The delete runs post-commit (`runAfterCommit`): a transactional status flip that rolls back
+ * must not have killed sessions, and socket kicks must observe committed truth.
+ */
+export class UserStatusTableWatcher implements TableWatcher<User> {
+  private logger = new Logger({ name: this.constructor.name });
+
+  name(): string {
+    return this.constructor.name;
+  }
+
+  table(): Table<User> {
+    return tables.User;
+  }
+
+  async afterUpdate<T extends User>(recordUpdateCount: number, record: Partial<T>, qb: QueryBuilder<T>): Promise<void> {
+    if (record.status !== 'deactivated' || recordUpdateCount === 0) {
+      return;
+    }
+
+    if (!record.id) {
+      // Every deactivation writer today updates by record id. A future query-based writer must
+      // extend this watcher — surface it loudly instead of silently leaving sessions alive.
+      this.logger.error({
+        message: `Deactivation write without a record id — sessions NOT killed. Extend UserStatusTableWatcher for query-based status writers.`,
+      });
+      return;
+    }
+
+    const db = getDbAsSystem();
+    await db.runAfterCommit(async () => {
+      const user = await db.get(tables.User, { id: record.id });
+      if (!user) {
+        return; // row deleted since the flip — nothing to resolve sessions against
+      }
+
+      const deletedSessions = await db.delete(tables.Session, { userEmail: user.email });
+      if (deletedSessions > 0) {
+        this.logger.info({
+          message: `Deactivation killed sessions`,
+          obj: { email: user.email, sessions: deletedSessions },
+        });
+      }
+    });
+  }
+}

package/src/authentication/authenticate.ts

@@ -1,8 +1,8 @@
-import sha256 from 'crypto-js/sha256';
 import { getDbAsSystem } from '@proteinjs/db';
 import { tables } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import { DefaultAdminCredentials } from './DefaultAdminCredentials';
+import { PasswordHasher } from './PasswordHasher';
 
 export function createAuthentication(defaultAdminCredentials?: { username: string; password: string }) {
   if (defaultAdminCredentials) {
@@ -24,13 +24,38 @@ export async function authenticate(email: string, password: string): Promise<tru
     return true;
   }
 
-  const users = await getDbAsSystem().query(tables.User, {
-    email: email.toLowerCase(),
-    password: sha256(password).toString(),
-  });
-  if (users.length < 1) {
+  // Fetch by EMAIL ONLY and compare in code — never query by password hash. Query-by-hash
+  // forced every stored credential into one deterministic queryable value (unsalted sha256);
+  // in-code comparison is what lets the stored format be salted and per-user.
+  const db = getDbAsSystem();
+  const user = await db.get(tables.User, { email: email.toLowerCase() });
+  const hasher = new PasswordHasher();
+  if (!user || !(await hasher.verify(user.password, password))) {
     return 'User name or password incorrect';
   }
 
+  // Verify-then-rehash: the just-proven password re-hashes a legacy sha256 row into the
+  // current format in place — the only moment the plaintext is available to migrate with.
+  // Machine rows (isLoadedFromSource) never rehash: sha256 IS their format (see PasswordHasher).
+  const mode = user.isLoadedFromSource === true ? 'machine' : 'human';
+  if (hasher.needsRehash(user.password, mode)) {
+    await db.update(tables.User, { id: user.id, password: await hasher.hash(password) });
+  }
+
+  // Deactivated accounts are refused a new session even with correct credentials; the session
+  // side of the same gate lives in userCache (deactivated sessions resolve as guest).
+  if (user.status === 'deactivated') {
+    // Pending-deletion accounts (deactivated by the account-deletion flow, not the staff toggle)
+    // may authenticate: logging back in IS the cancel signal — the login route runs the cancel
+    // hook before request.login and decides. No purgeAfter check here: the cancel's CAS claim is
+    // the arbiter, so a user beating the purge walker to a just-expired window wins honestly.
+    if (user.deleteRequestedAt != null) {
+      return true;
+    }
+
+    logger.warn({ message: 'Refused login for deactivated account', obj: { email: email.toLowerCase() } });
+    return 'This account has been deactivated';
+  }
+
   return true;
 }

package/src/authorization/userCache.ts

@@ -1,9 +1,12 @@
 import moment from 'moment';
 import { SessionDataCache } from '@proteinjs/server-api';
 import { getDbAsSystem } from '@proteinjs/db';
+import { Logger } from '@proteinjs/logger';
 import { User, tables, guestUser, USER_SESSION_CACHE_KEY } from '@proteinjs/user';
 import { DefaultAdminCredentials } from '../authentication/DefaultAdminCredentials';
 
+const logger = new Logger({ name: 'userCache' });
+
 export const userCache: SessionDataCache<User> = {
   key: USER_SESSION_CACHE_KEY,
   create: async (sessionId: string, userEmail: string): Promise<User> => {
@@ -23,8 +26,28 @@ export const userCache: SessionDataCache<User> = {
         };
         user = adminUser;
       } else {
-        user = await getDbAsSystem().get(tables.User, { email: userEmail.toLowerCase() });
-        delete (user as any)['password'];
+        const accountUser = await getDbAsSystem().get(tables.User, { email: userEmail.toLowerCase() });
+        if (accountUser && accountUser.status === 'deactivated') {
+          // The session half of the deactivation gate (login half in authenticate): the session
+          // cache is rebuilt per request, so a live session stops resolving the moment the
+          // account is deactivated — every request runs as the unauthenticated guest.
+          logger.warn({
+            message: `Session references a deactivated account; resolving as unauthenticated`,
+            obj: { sessionId, userEmail },
+          });
+        } else if (accountUser) {
+          delete (accountUser as any)['password'];
+          user = accountUser;
+        } else {
+          // A session can outlive its account (row deleted, or a dev auto-login for a never-created
+          // email). Resolve it to the unauthenticated guest session — the client sees no
+          // authenticated user and re-logs. Throwing here escapes the per-request session-cache
+          // build as an unhandled rejection and downs the process.
+          logger.warn({
+            message: `Session references an account that does not exist; resolving as unauthenticated`,
+            obj: { sessionId, userEmail },
+          });
+        }
       }
     }
 

package/src/emails/AccountDeletionEmailConfigs.ts

@@ -0,0 +1,79 @@
+import { Loadable, SourceRepository } from '@proteinjs/reflection';
+import Mail from 'nodemailer/lib/mailer';
+import { Moment } from 'moment';
+
+/**
+ * Config-factory seams for the two account-deletion emails (the PasswordResetEmailConfig
+ * pattern; the interfaces live here because @proteinjs/email-server is a registry package).
+ * Both emails are self-contained notifications, so each getter carries default content (the
+ * PasswordUpdatedEmailConfig precedent) — an app implements the factory to override.
+ */
+
+export interface AccountDeletionRequestedEmailConfig {
+  /** @see https://nodemailer.com/message/ for all available options */
+  options?: Mail.Options;
+  /** @param purgeAfter when the grace window ends and the account is permanently erased */
+  getEmailContent: (purgeAfter: Moment) => {
+    text: string;
+    html?: string;
+  };
+}
+
+export interface DefaultAccountDeletionRequestedEmailConfigFactory extends Loadable {
+  getConfig(): AccountDeletionRequestedEmailConfig;
+}
+
+export const getDefaultAccountDeletionRequestedEmailConfigFactory =
+  (): DefaultAccountDeletionRequestedEmailConfigFactory => {
+    const defaultFactory: DefaultAccountDeletionRequestedEmailConfigFactory = {
+      getConfig: () => ({
+        options: { subject: 'Your account is scheduled for deletion' },
+        getEmailContent: (purgeAfter: Moment) => ({
+          text:
+            `Your account is scheduled for deletion. Your content is no longer visible to you or to ` +
+            `anyone you shared it with. You can change your mind until ${purgeAfter.format('MMMM D, YYYY')} ` +
+            `by simply logging back in — that restores everything, including shares. After that date, your ` +
+            `account and everything in it are permanently removed from our systems, and we'll email you to ` +
+            `confirm when it's done. If you didn't request this, log back in now to cancel.`,
+        }),
+      }),
+    };
+
+    const retrievedFactory = SourceRepository.get().object<DefaultAccountDeletionRequestedEmailConfigFactory>(
+      '@proteinjs/user-server/DefaultAccountDeletionRequestedEmailConfigFactory'
+    );
+
+    return retrievedFactory || defaultFactory;
+  };
+
+export interface AccountDeletedEmailConfig {
+  /** @see https://nodemailer.com/message/ for all available options */
+  options?: Mail.Options;
+  getEmailContent: () => {
+    text: string;
+    html?: string;
+  };
+}
+
+export interface DefaultAccountDeletedEmailConfigFactory extends Loadable {
+  getConfig(): AccountDeletedEmailConfig;
+}
+
+export const getDefaultAccountDeletedEmailConfigFactory = (): DefaultAccountDeletedEmailConfigFactory => {
+  const defaultFactory: DefaultAccountDeletedEmailConfigFactory = {
+    getConfig: () => ({
+      options: { subject: 'Your account has been deleted' },
+      getEmailContent: () => ({
+        text:
+          `Your account and everything in it have been permanently removed from our systems. ` +
+          `This is the confirmation you were promised when you requested deletion. Goodbye, and thank you.`,
+      }),
+    }),
+  };
+
+  const retrievedFactory = SourceRepository.get().object<DefaultAccountDeletedEmailConfigFactory>(
+    '@proteinjs/user-server/DefaultAccountDeletedEmailConfigFactory'
+  );
+
+  return retrievedFactory || defaultFactory;
+};

package/src/emails/AccountDeletionEmails.ts

@@ -0,0 +1,39 @@
+import { Moment } from 'moment';
+import { EmailSender } from '@proteinjs/email-server';
+import {
+  getDefaultAccountDeletedEmailConfigFactory,
+  getDefaultAccountDeletionRequestedEmailConfigFactory,
+} from './AccountDeletionEmailConfigs';
+
+/**
+ * Thin sender for the two account-deletion emails: deletion-requested (at deactivation — the
+ * only cancel channel an account-takeover victim has) and the store-required completion
+ * confirmation (sent by the purge walker after the user row is gone). Content comes from the
+ * config factories beside this class; transport is the app's DefaultEmailConfigFactory SMTP
+ * config via EmailSender.
+ */
+export class AccountDeletionEmails {
+  async sendDeletionRequested(to: string, purgeAfter: Moment): Promise<void> {
+    const config = getDefaultAccountDeletionRequestedEmailConfigFactory().getConfig();
+    const { text, html } = config.getEmailContent(purgeAfter);
+    await new EmailSender().sendEmail({
+      to,
+      subject: 'Your account is scheduled for deletion',
+      text,
+      html,
+      ...config.options,
+    });
+  }
+
+  async sendAccountDeleted(to: string): Promise<void> {
+    const config = getDefaultAccountDeletedEmailConfigFactory().getConfig();
+    const { text, html } = config.getEmailContent();
+    await new EmailSender().sendEmail({
+      to,
+      subject: 'Your account has been deleted',
+      text,
+      html,
+      ...config.options,
+    });
+  }
+}

package/src/routes/devLogin.ts

@@ -1,28 +1,66 @@
 import { Route } from '@proteinjs/server-api';
 import { Logger } from '@proteinjs/logger';
+import { Signup } from '../services/Signup';
 
 const logger = new Logger({ name: 'devLogin' });
 
+/** Lowercased domain of an email address (the whole string when there is no `@`, which can never
+ *  equal a real env domain — so malformed params fall out at the domain rail). */
+const emailDomain = (address: string) => address.slice(address.lastIndexOf('@') + 1).toLowerCase();
+
 /**
- * DEV-ONLY session bootstrap: `GET /dev/login` establishes a session for the account named by
- * `DEV_AUTO_LOGIN_EMAIL` — no credentials involved — so automated dev-loop testing (agent-driven
- * browsers) can self-serve a session instead of stalling on the login form every time a cookie
- * is lost.
+ * DEV-ONLY session bootstrap: `GET /dev/login` establishes a session — no credentials involved —
+ * so automated dev-loop testing (agent-driven browsers) can self-serve a session instead of
+ * stalling on the login form. `?email=<addr>` selects the session's account so parallel
+ * verification can fan out over distinct users; absent, the `DEV_AUTO_LOGIN_EMAIL` account is
+ * used as before.
  *
  * Double-gated, acts only when BOTH hold; otherwise the path answers 404 as if unregistered:
  * 1. `process.env.DEVELOPMENT` — the dev-server switch, never set in prod images.
- * 2. `DEV_AUTO_LOGIN_EMAIL` — explicit per-launch opt-in naming exactly one account.
+ * 2. `DEV_AUTO_LOGIN_EMAIL` — explicit per-launch opt-in naming the default account.
+ *
+ * Domain rail: `?email` must share `DEV_AUTO_LOGIN_EMAIL`'s domain — even a dev server must not
+ * mint sessions (much less accounts) for arbitrary domains; anything else answers 400.
+ *
+ * A missing account is created through the normal signup creation path (`Signup.createAccount`)
+ * as a normal test user — password `test`, matching the seeded test-account convention, so
+ * interactive login works for the same identity. Composes with userCache's missing-account→guest
+ * seam: that covers sessions whose account was deleted AFTER minting; this ensures dev-minted
+ * sessions reference a real account from the start.
  */
 export const devLogin: Route = {
   path: '/dev/login',
   method: 'get',
   onRequest: async (request: any, response): Promise<void> => {
-    const email = (process.env.DEV_AUTO_LOGIN_EMAIL ?? '').trim();
-    if (!process.env.DEVELOPMENT || !email) {
+    const envEmail = (process.env.DEV_AUTO_LOGIN_EMAIL ?? '').trim();
+    if (!process.env.DEVELOPMENT || !envEmail) {
       response.status(404).send();
       return;
     }
 
+    let email = envEmail;
+    const emailParam = request.query?.email;
+    if (emailParam !== undefined) {
+      const requested = typeof emailParam === 'string' ? emailParam.trim() : '';
+      if (emailDomain(requested) !== emailDomain(envEmail)) {
+        response.status(400).send(`/dev/login only accepts accounts on the @${emailDomain(envEmail)} domain`);
+        return;
+      }
+      email = requested;
+    }
+    email = email.toLowerCase();
+
+    const creation = await new Signup().createAccount({
+      name: email.slice(0, email.indexOf('@')),
+      email,
+      password: 'test',
+      emailVerified: false, // same shape an inviteless signup produces
+      invitedBy: null,
+    });
+    if (creation === 'created') {
+      logger.info({ message: 'Dev auto-login created missing test account', obj: { email } });
+    }
+
     await new Promise((resolve) => request.login(email, resolve));
     // Explicit save before redirecting: with a DB-backed session store, save-on-response-end
     // races the redirected GET / — the follow-up request can read the session row before the

package/src/routes/executePasswordReset.ts

@@ -3,7 +3,7 @@ import { getDbAsSystem } from '@proteinjs/db';
 import { routes, tables } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import moment from 'moment';
-import sha256 from 'crypto-js/sha256';
+import { PasswordHasher } from '../authentication/PasswordHasher';
 
 /**
  * Route handler for executing a password reset.
@@ -42,7 +42,7 @@ export const executePasswordReset: Route = {
     }
 
     // Update user's password
-    const hashedPassword = sha256(newPassword).toString();
+    const hashedPassword = await new PasswordHasher().hash(newPassword);
     await db.update(tables.User, {
       id: user.id,
       password: hashedPassword,

package/src/routes/login.ts

@@ -1,6 +1,7 @@
 import { Route } from '@proteinjs/server-api';
 import { routes } from '@proteinjs/user';
 import { authenticate } from '../authentication/authenticate';
+import { AccountDeletion } from '../services/AccountDeletion';
 
 export const login: Route = {
   path: routes.login.path,
@@ -21,6 +22,28 @@ export const login: Route = {
       return;
     }
 
+    // Cancel-by-login: a pending-deletion account's successful authentication IS the cancel
+    // signal. The restore runs synchronously here, BEFORE request.login, so the first
+    // authenticated paint sees the fully restored account (no transient).
+    let outcome: Awaited<ReturnType<AccountDeletion['cancelPendingDeletion']>>;
+    try {
+      outcome = await new AccountDeletion().cancelPendingDeletion(credentials.email);
+    } catch (error) {
+      // Security boundary: the login response never carries internal error detail — an
+      // attacker probing emails must learn nothing from failure shapes (founder ruling
+      // 2026-08-18 after a watcher error surfaced verbatim in the login form). The real
+      // error stays loud in the server log.
+      console.error('cancelPendingDeletion failed during login', error);
+      response.send({ error: 'Unable to log in right now. Please try again.' });
+      return;
+    }
+    if (outcome === 'purging') {
+      const error = 'This account is being deleted and can no longer be restored.';
+      console.error(error);
+      response.send({ error });
+      return;
+    }
+
     await new Promise((resolve, reject) => {
       request.login(credentials.email, resolve);
     });