npm i pg zod bcryptjs
npm i -D vitest @types/pg @types/bcryptjs

// lib/db.ts
import { Pool } from "pg";

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5,
});

create table users (
  id            uuid primary key default gen_random_uuid(),
  email         text not null unique,
  password_hash text not null,
  created_at    timestamptz not null default now()
);

create table reset_tokens (
  id         uuid primary key default gen_random_uuid(),
  user_id    uuid not null references users(id) on delete cascade,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

-- lets us find a user's still-open tokens quickly
create index reset_tokens_open_idx
  on reset_tokens (user_id)
  where used_at is null;

// lib/tokens.ts
import { randomBytes, createHash } from "node:crypto";

export const RESET_TTL_MINUTES = 60;

export function newResetToken() {
  const token = randomBytes(32).toString("base64url"); // 256 bits of randomness
  return { token, tokenHash: hashToken(token) };
}

export function hashToken(token: string) {
  return createHash("sha256").update(token).digest("hex");
}

// DON'T
const user = await findUserByEmail(email);
if (!user) return Response.json({ error: "No account with that email" }, { status: 404 });

await sendResetEmail(user.email, token);
return Response.json({ message: "Email sent" });

// app/api/auth/forgot-password/route.ts
import { z } from "zod";
import { pool } from "@/lib/db";
import { newResetToken, RESET_TTL_MINUTES } from "@/lib/tokens";
import { sendResetEmail } from "@/lib/email";

const Body = z.object({ email: z.string().email().max(254) });

const SAME_ANSWER = {
  message: "If that email is registered, a reset link is on its way.",
};

export async function POST(req: Request) {
  const parsed = Body.safeParse(await req.json().catch(() => null));
  if (!parsed.success) return Response.json({ error: "Invalid request" }, { status: 400 });

  const email = parsed.data.email.toLowerCase();
  const { rows } = await pool.query("select id, email from users where email = $1", [email]);
  const user = rows[0];

  if (user) {
    const { token, tokenHash } = newResetToken();
    await pool.query(
      `insert into reset_tokens (user_id, token_hash, expires_at)
       values ($1, $2, now() + make_interval(mins => $3))`,
      [user.id, tokenHash, RESET_TTL_MINUTES]
    );

    try {
      await sendResetEmail(user.email, token);
    } catch (err) {
      // swallow it: log for yourself, but never change the response
      console.error("reset email failed", { userId: user.id, err });
    }
  }

  return Response.json(SAME_ANSWER); // identical for known and unknown emails
}

// app/api/auth/login/route.ts (the relevant part)
import bcrypt from "bcryptjs";

const COST = 12;

// computed once, when the module loads, with the SAME cost as real hashes
const DUMMY_HASH = bcrypt.hashSync("this-account-does-not-exist", COST);

export async function POST(req: Request) {
  const { email, password } = await readAndValidate(req);

  const user = await findUserByEmail(email);

  // always run a compare, against the real hash or the dummy
  const hash = user?.password_hash ?? DUMMY_HASH;
  const ok = await bcrypt.compare(password, hash);

  if (!user || !ok) {
    return Response.json({ error: "Invalid email or password" }, { status: 401 });
  }

  return issueJwtFor(user);
}

// DON'T: three steps, no transaction
const found = await pool.query(
  "select user_id from reset_tokens where token_hash = $1 and used_at is null and expires_at > now()",
  [tokenHash]
);
if (found.rowCount === 0) return invalid();

await pool.query("update users set password_hash = $1 where id = $2", [newHash, found.rows[0].user_id]);
await pool.query("update reset_tokens set used_at = now() where token_hash = $1", [tokenHash]);

update reset_tokens
   set used_at = now()
 where token_hash = $1
   and used_at is null
   and expires_at > now()
returning user_id;

// app/api/auth/reset-password/route.ts
import { z } from "zod";
import bcrypt from "bcryptjs";
import { pool } from "@/lib/db";
import { hashToken } from "@/lib/tokens";

const Body = z.object({
  token: z.string().min(20).max(200),
  password: z.string().min(8).max(128),
});

const INVALID = { error: "This reset link is invalid or has expired." };

export async function POST(req: Request) {
  const parsed = Body.safeParse(await req.json().catch(() => null));
  if (!parsed.success) return Response.json({ error: "Invalid request" }, { status: 400 });

  const { token, password } = parsed.data;

  // slow work FIRST, outside the transaction
  const newHash = await bcrypt.hash(password, 12);
  const tokenHash = hashToken(token);

  const client = await pool.connect();
  try {
    await client.query("BEGIN");

    // 1. claim the token atomically
    const claimed = await client.query(
      `update reset_tokens
          set used_at = now()
        where token_hash = $1
          and used_at is null
          and expires_at > now()
      returning user_id`,
      [tokenHash]
    );

    if (claimed.rowCount === 0) {
      await client.query("ROLLBACK");
      return Response.json(INVALID, { status: 400 });
    }

    const userId = claimed.rows[0].user_id;

    // 2. set the new password
    await client.query("update users set password_hash = $1 where id = $2", [newHash, userId]);

    // 3. kill every other open token for this user (Bug 4, next step)
    await client.query(
      "update reset_tokens set used_at = now() where user_id = $1 and used_at is null",
      [userId]
    );

    await client.query("COMMIT");
    return Response.json({ message: "Password updated." });
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

update reset_tokens
   set used_at = now()
 where user_id = $1
   and used_at is null;

delete from reset_tokens
 where expires_at < now() - interval '7 days';

// tests/reset.race.test.ts
import { describe, it, expect } from "vitest";
import { POST as reset } from "@/app/api/auth/reset-password/route";
import { seedUserWithToken } from "./helpers";

function call(token: string, password: string) {
  return reset(
    new Request("http://test/api/auth/reset-password", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ token, password }),
    })
  );
}

describe("password reset", () => {
  it("lets only one of two simultaneous requests win", async () => {
    const { token } = await seedUserWithToken();

    const results = await Promise.all([
      call(token, "NewPassw0rd!A"),
      call(token, "NewPassw0rd!B"),
    ]);

    const statuses = results.map((r) => r.status).sort();
    expect(statuses).toEqual([200, 400]);
  });

  it("rejects the same token a second time", async () => {
    const { token } = await seedUserWithToken();
    expect((await call(token, "NewPassw0rd!A")).status).toBe(200);
    expect((await call(token, "NewPassw0rd!B")).status).toBe(400);
  });

  it("invalidates sibling tokens", async () => {
    const { token, siblingToken } = await seedUserWithToken({ siblings: 1 });
    expect((await call(token, "NewPassw0rd!A")).status).toBe(200);
    expect((await call(siblingToken, "NewPassw0rd!B")).status).toBe(400);
  });
});

// tests/helpers.ts: the shape of the seed helper
export async function seedUserWithToken(opts: { siblings?: number } = {}) {
  // 1. insert a user with a random email
  // 2. create a token with newResetToken(), insert its hash, expiring in 60 min
  // 3. optionally insert N more tokens for the same user
  // 4. return the raw tokens, because the hashes are useless to the caller
}

// app/reset-password/page.tsx
"use client";

import { Suspense, useState } from "react";
import { useSearchParams } from "next/navigation";

function ResetForm() {
  const token = useSearchParams().get("token") ?? "";
  const [password, setPassword] = useState("");
  const [state, setState] = useState<"idle" | "busy" | "done" | "error">("idle");

  async function submit(e: React.FormEvent) {
    e.preventDefault();
    setState("busy");
    const res = await fetch("/api/auth/reset-password", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ token, password }),
    });
    setState(res.ok ? "done" : "error");
  }

  if (!token) return <p>This link has no token. Get a fresh one.</p>;
  if (state === "done") return <p>Password updated. Sign-in works again.</p>;

  return (
    <form onSubmit={submit}>
      <label>
        New password
        <input
          type="password"
          minLength={8}
          autoComplete="new-password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />
      </label>
      <button disabled={state === "busy"}>Set password</button>
      {state === "error" && <p>This link is invalid or expired. Get a fresh one.</p>}
    </form>
  );
}

export default function Page() {
  return (
    <Suspense>
      <ResetForm />
    </Suspense>
  );
}

create table rate_limits (
  key          text        not null,
  window_start timestamptz not null,
  hits         int         not null default 1,
  primary key (key, window_start)
);

// lib/rate-limit.ts
import { pool } from "@/lib/db";

export async function allow(key: string, limit: number, windowSeconds = 60) {
  const { rows } = await pool.query(
    `insert into rate_limits (key, window_start, hits)
     values ($1, to_timestamp(floor(extract(epoch from now()) / $2) * $2), 1)
     on conflict (key, window_start)
     do update set hits = rate_limits.hits + 1
     returning hits`,
    [key, windowSeconds]
  );
  return rows[0].hits <= limit;
}

// at the top of forgot-password
const ip = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown";

if (!(await allow(`forgot:${ip}`, 5))) {
  // return the SAME answer: a different one would tell an attacker they were limited
  // on a real account but not a fake one
  return Response.json(SAME_ANSWER);
}