@proteinjs/user-server 1.7.0 → 1.8.0

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

@@ -27,7 +27,15 @@ export const userCache: SessionDataCache<User> = {
         user = adminUser;
       } else {
         const accountUser = await getDbAsSystem().get(tables.User, { email: userEmail.toLowerCase() });
-        if (accountUser) {
+        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 {

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/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);
     });