Рецепт: хранение паролей — хеширование и проверка

npm init -y
npm pkg set type=module
npm install argon2@0.45 bcryptjs@3
npm install -D typescript @types/node@24 vitest

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test", "scripts"]
}

import * as argon2 from "argon2";
import bcrypt from "bcryptjs";

// OWASP Password Storage Cheat Sheet: Argon2id, at least m=19 MiB, t=2, p=1.
// Benchmark on your server: raise memoryCost or timeCost while a hash stays well under a second.
export const ARGON2_OPTIONS = {
  type: argon2.argon2id,
  memoryCost: 19_456, // KiB, i.e. 19 MiB
  timeCost: 2,
  parallelism: 1,
} as const;

export type VerifyResult =
  | { valid: false }
  // newHash !== null: store it instead of the old hash
  | { valid: true; newHash: string | null };

export function hashPassword(password: string): Promise<string> {
  // A new random salt every time; algorithm, parameters and salt go into the PHC string
  return argon2.hash(password, ARGON2_OPTIONS);
}

const isArgon2 = (hash: string) => hash.startsWith("$argon2");
const isBcrypt = (hash: string) => /^\$2[aby]\$\d{2}\$/.test(hash);

export async function verifyPassword(password: string, storedHash: string): Promise<VerifyResult> {
  if (isArgon2(storedHash)) {
    if (!(await argon2.verify(storedHash, password))) return { valid: false };
    // needsRehash compares m, t, p and the version, but not the variant (argon2i, argon2d)
    const outdated = !storedHash.startsWith("$argon2id$") || argon2.needsRehash(storedHash, ARGON2_OPTIONS);
    return { valid: true, newHash: outdated ? await hashPassword(password) : null };
  }
  if (isBcrypt(storedHash)) {
    // Legacy hash: check it with bcrypt one last time and replace it with Argon2id
    if (!(await bcrypt.compare(password, storedHash))) return { valid: false };
    return { valid: true, newHash: await hashPassword(password) };
  }
  throw new Error("Unknown password hash format");
}

import { randomBytes } from "node:crypto";
import { hashPassword, verifyPassword } from "./password.ts";

export type UserRecord = { id: string; email: string; passwordHash: string };

export interface UserStore {
  findByEmail(email: string): Promise<UserRecord | null>;
  updatePasswordHash(userId: string, passwordHash: string): Promise<void>;
}

// A hash of a random password with the current parameters. An unknown email is checked
// against it, so the answer takes as long as for a real account with a wrong password.
let dummyHash: Promise<string> | undefined;
const getDummyHash = () => (dummyHash ??= hashPassword(randomBytes(32).toString("base64url")));

export async function authenticate(
  store: UserStore,
  email: string,
  password: string,
): Promise<UserRecord | null> {
  const user = await store.findByEmail(email.trim().toLowerCase());
  const result = await verifyPassword(password, user?.passwordHash ?? (await getDummyHash()));
  if (!user || !result.valid) return null;

  if (result.newHash !== null) {
    // Rehash on login: new parameters or a migration from bcrypt
    await store.updatePasswordHash(user.id, result.newHash);
    return { ...user, passwordHash: result.newHash };
  }
  return user;
}

import * as argon2 from "argon2";

// Run on the production server (or the same instance type), not on a laptop
const candidates = [
  { memoryCost: 19_456, timeCost: 2 }, // OWASP minimum
  { memoryCost: 47_104, timeCost: 1 }, // OWASP alternative: 46 MiB, t=1
  { memoryCost: 65_536, timeCost: 3 }, // RFC 9106 second recommended option (p=4 there)
];

for (const params of candidates) {
  const options: argon2.HashOptions = { type: argon2.argon2id, parallelism: 1, ...params };
  await argon2.hash("warm-up", options);
  const start = performance.now();
  for (let i = 0; i < 10; i++) await argon2.hash("benchmark password", options);
  const ms = (performance.now() - start) / 10;
  console.log(`m=${params.memoryCost} KiB, t=${params.timeCost}, p=1: ${ms.toFixed(1)} ms per hash`);
}

$ node scripts/bench.ts
m=19456 KiB, t=2, p=1: 21.8 ms per hash
m=47104 KiB, t=1, p=1: 33.7 ms per hash
m=65536 KiB, t=3, p=1: 115.1 ms per hash

import * as argon2 from "argon2";
import bcrypt from "bcryptjs";
import { describe, expect, it } from "vitest";
import { hashPassword, verifyPassword } from "../src/password.ts";

const PASSWORD = "correct horse battery staple";
const CURRENT = /^\$argon2id\$v=19\$m=19456,p=1,t=2\$/;

describe("hashPassword / verifyPassword", () => {
  it("produces an Argon2id PHC string with the OWASP parameters and a unique salt", async () => {
    const first = await hashPassword(PASSWORD);
    const second = await hashPassword(PASSWORD);
    expect(first).toMatch(CURRENT);
    expect(first).not.toBe(second);
  });

  it("accepts the right password and rejects a wrong one", async () => {
    const hash = await hashPassword(PASSWORD);
    expect(await verifyPassword(PASSWORD, hash)).toEqual({ valid: true, newHash: null });
    expect(await verifyPassword("wrong password", hash)).toEqual({ valid: false });
  });

  it("returns a new hash when the stored one uses old parameters", async () => {
    const old = await argon2.hash(PASSWORD, { type: argon2.argon2id, memoryCost: 12_288, timeCost: 3, parallelism: 1 });
    const result = await verifyPassword(PASSWORD, old);
    expect(result).toEqual({ valid: true, newHash: expect.stringMatching(CURRENT) });
  });

  it("returns a new hash for argon2i with the same parameters", async () => {
    const old = await argon2.hash(PASSWORD, { type: argon2.argon2i, memoryCost: 19_456, timeCost: 2, parallelism: 1 });
    const result = await verifyPassword(PASSWORD, old);
    expect(result).toEqual({ valid: true, newHash: expect.stringMatching(CURRENT) });
  });

  it("migrates a legacy bcrypt hash only after the right password", async () => {
    const legacy = await bcrypt.hash(PASSWORD, 10);
    expect(await verifyPassword("wrong password", legacy)).toEqual({ valid: false });
    const result = await verifyPassword(PASSWORD, legacy);
    expect(result).toEqual({ valid: true, newHash: expect.stringMatching(CURRENT) });
  });

  it("refuses an unknown hash format instead of guessing", async () => {
    await expect(verifyPassword(PASSWORD, "5e884898da28047151d0e56f8dc6292773603d0d")).rejects.toThrow(
      "Unknown password hash format",
    );
  });
});

import bcrypt from "bcryptjs";
import { beforeEach, describe, expect, it } from "vitest";
import { authenticate, type UserRecord, type UserStore } from "../src/login.ts";
import { hashPassword } from "../src/password.ts";

class InMemoryUsers implements UserStore {
  readonly byEmail = new Map<string, UserRecord>();
  updates = 0;

  async findByEmail(email: string) {
    return this.byEmail.get(email) ?? null;
  }

  async updatePasswordHash(userId: string, passwordHash: string) {
    for (const user of this.byEmail.values()) {
      if (user.id === userId) user.passwordHash = passwordHash;
    }
    this.updates++;
  }
}

const PASSWORD = "correct horse battery staple";
let store: InMemoryUsers;

beforeEach(async () => {
  store = new InMemoryUsers();
  store.byEmail.set("anna@example.com", { id: "u1", email: "anna@example.com", passwordHash: await hashPassword(PASSWORD) });
  store.byEmail.set("old@example.com", { id: "u2", email: "old@example.com", passwordHash: await bcrypt.hash(PASSWORD, 10) });
});

async function medianMs(run: () => Promise<unknown>, times = 5): Promise<number> {
  const results: number[] = [];
  for (let i = 0; i < times; i++) {
    const start = performance.now();
    await run();
    results.push(performance.now() - start);
  }
  return results.sort((a, b) => a - b)[Math.floor(times / 2)]!;
}

describe("authenticate", () => {
  it("logs in with the right password and keeps a current hash", async () => {
    const user = await authenticate(store, " Anna@Example.com ", PASSWORD);
    expect(user?.id).toBe("u1");
    expect(store.updates).toBe(0);
  });

  it("returns null for a wrong password and for an unknown email", async () => {
    expect(await authenticate(store, "anna@example.com", "wrong password")).toBeNull();
    expect(await authenticate(store, "nobody@example.com", PASSWORD)).toBeNull();
  });

  it("moves a bcrypt user to Argon2id on login", async () => {
    const user = await authenticate(store, "old@example.com", PASSWORD);
    expect(user?.passwordHash).toMatch(/^\$argon2id\$/);
    expect(store.byEmail.get("old@example.com")?.passwordHash).toMatch(/^\$argon2id\$/);
    expect(await authenticate(store, "old@example.com", PASSWORD)).not.toBeNull();
    expect(store.updates).toBe(1);
  });

  it("does not touch the stored hash after a wrong password", async () => {
    const before = store.byEmail.get("old@example.com")?.passwordHash;
    await authenticate(store, "old@example.com", "wrong password");
    expect(store.byEmail.get("old@example.com")?.passwordHash).toBe(before);
    expect(store.updates).toBe(0);
  });

  it("spends comparable time on an unknown email and on a wrong password", async () => {
    await authenticate(store, "warm-up@example.com", PASSWORD); // the dummy hash is computed once
    const unknown = await medianMs(() => authenticate(store, "nobody@example.com", PASSWORD));
    const wrong = await medianMs(() => authenticate(store, "anna@example.com", "wrong password"));
    expect(unknown).toBeGreaterThan(wrong * 0.5);
  });
});

$ npx tsc -p .
$ npx vitest run --reporter=verbose

RUN  v5.0.3 …

 ✓ test/password.test.ts > hashPassword / verifyPassword > produces an Argon2id PHC string with the OWASP parameters and a unique salt 49ms
 ✓ test/login.test.ts > authenticate > logs in with the right password and keeps a current hash 115ms
 ✓ test/password.test.ts > hashPassword / verifyPassword > accepts the right password and rejects a wrong one 66ms
 ✓ test/password.test.ts > hashPassword / verifyPassword > returns a new hash when the stored one uses old parameters 64ms
 ✓ test/login.test.ts > authenticate > returns null for a wrong password and for an unknown email 165ms
 ✓ test/password.test.ts > hashPassword / verifyPassword > returns a new hash for argon2i with the same parameters 78ms
 ✓ test/password.test.ts > hashPassword / verifyPassword > migrates a legacy bcrypt hash only after the right password 234ms
 ✓ test/password.test.ts > hashPassword / verifyPassword > refuses an unknown hash format instead of guessing 1ms
 ✓ test/login.test.ts > authenticate > moves a bcrypt user to Argon2id on login 216ms
 ✓ test/login.test.ts > authenticate > does not touch the stored hash after a wrong password 145ms
 ✓ test/login.test.ts > authenticate > spends comparable time on an unknown email and on a wrong password 303ms

 Test Files  2 passed (2)
      Tests  11 passed (11)