Spec-Driven Development

"we need POST /auth/forgot-password by EOD.
 just the basic flow — email, link, done."

"add a forgot-password endpoint that emails the user a reset link"

async function forgotPassword(req, res) {
  const { email } = req.body
  const user = await db.users.findByEmail(email)
  if (!user) return res.status(404).json({ error: "User not found" })

  const token = crypto.randomUUID()
  await db.tokens.create({ userId: user.id, token })
  await sendEmail(user.email, `Reset link: /reset?token=${token}`)

  return res.json({ ok: true })
}

if (!user) return res.status(404).json({ error: "User not found" })  // unknown email
return res.json({ ok: true })                                         // known email

$ for email in $(cat customer-list.txt); do
>   curl -X POST /auth/forgot-password -d "{\"email\":\"$email\"}"
> done

await db.tokens.create({ userId: user.id, token })

Who triggered it?            (userId)
From what IP?                (req.ip)
At what time?                (timestamp)
Did the user complete it?    (resetCompletedAt)

# specs/forgot-password.yaml
endpoint: POST /auth/forgot-password
version: "1.0"

inputs:
  - name: email   type: Email   required: true

invariants:
  - response is identical for known and unknown emails    # no enumeration
  - max 5 requests / hour / IP
  - max 3 requests / hour / email
  - token TTL <= 15 minutes
  - token is single-use (usedAt set on first use)
  - token stored as SHA-256 hash, never plaintext

outputs:
  status: 202 Accepted
  body:   { ok: true }

side_effects:
  - email sent IF user exists
  - audit log entry: { userId?, ip, requestedAt }

// tests/forgot-password.test.ts — every test names a spec line

it("returns identical 202 body for known and unknown emails", ...)
it("rate-limits at 5 requests / hour / IP", ...)
it("rate-limits at 3 requests / hour / email", ...)
it("rejects tokens older than 15 minutes", ...)
it("rejects already-used tokens", ...)
it("stores token as SHA-256 hash, not plaintext", ...)
it("writes audit log entry on every request, including unknown emails", ...)

async function forgotPassword(req, res) {
  const email = await EmailSchema.parseAsync(req.body.email)

  await rateLimitByIp(req.ip, { max: 5, window: "1h" })        // ← invariant
  await rateLimitByEmail(email, { max: 3, window: "1h" })       // ← invariant

  const user = await db.users.findByEmail(email)
  if (user) {
    const token = crypto.randomBytes(32).toString("hex")
    await db.tokens.create({
      userId:    user.id,
      tokenHash: sha256(token),                                  // ← invariant
      expiresAt: addMinutes(new Date(), 15),                     // ← invariant
      usedAt:    null,                                           // ← invariant
    })
    await sendEmail(user.email, `Reset: /reset?token=${token}`) // ← side_effect
  }

  await audit.log({ userId: user?.id, ip: req.ip, action: "forgot-password" })
  return res.status(202).json({ ok: true })                      // ← invariant
}

✓  returns identical 202 body for known and unknown emails
✓  rate-limits at 5 requests / hour / IP
✓  rate-limits at 3 requests / hour / email
✓  rejects tokens older than 15 minutes
✓  rejects already-used tokens
✓  stores token as SHA-256 hash, not plaintext
✓  writes audit log entry on every request, including unknown emails

# specs/forgot-password.yaml — one new invariant
invariants:
  - new password length >= 12 chars      # ← added

// src/auth/reset.ts
if (newPassword.length < 12) throw new PasswordTooShort()
await db.users.update({ id: user.id, password: hash(newPassword) })