Security Best Practice

Security Best Practice

You are auditing and hardening authentication code against modern (2024-2026) security best practices.

Rules

Individual security rules are in the rules/ directory, organized by impact priority. Read rules/_sections.md for the full taxonomy, and read individual rule files for checklists and fix patterns.

Critical Impact:

• rules/credential-storage.md — Password hashing (argon2id first), HIBP breach-check, pepper, secret management
• rules/error-handling.md — User enumeration, timing attacks, status/size symmetry, stack trace leaks

High Impact:

• rules/session-security.md — Token generation, __Host-/Partitioned cookies, JWT pitfalls, session fixation, rotation on state change
• rules/input-validation.md — SQL/NoSQL injection, XSS, SSRF, open redirect, schema validation
• rules/oauth-oidc.md — Code + PKCE, state/nonce, redirect-URI allow-list, account-linking pre-takeover
• rules/mfa-passkeys.md — TOTP replay prevention, WebAuthn verification, step-up, recovery codes
• rules/token-lifecycle.md — Password reset, email verification, magic link, OTP hashing & one-time use

Medium Impact:

• rules/rate-limiting.md — Multi-dim throttling (account + IP), SMS pumping, credential stuffing
• rules/csrf-protection.md — Origin / Fetch-Metadata, double-submit, SameSite caveats, CORS pitfalls

Lower Priority:

• rules/http-security-headers.md — HSTS, nonce-CSP, COOP/COEP/CORP, Clear-Site-Data, Trusted Types

Step 1: Detect Project Context

Before starting, scan the user's project to understand their stack:

1. Framework config files (next.config.*, package.json, go.mod, Cargo.toml, pyproject.toml, build.gradle*, pom.xml) 2. Existing auth code — route handlers for sign-up, sign-in, session, sign-out, password reset, email verification 3. Database/ORM setup and session storage (DB table, Redis, JWT) 4. Existing security measures (rate limiting, CSRF tokens, CSP headers, MFA, OAuth providers) 5. Whether the app uses cookies, Bearer tokens, or both (determines which rules apply)

Step 2: Choose Audit Scope

Use the AskUserQuestion tool to ask the user what they want to harden. Use multiSelect: true so they can pick multiple areas at once.

Ask "Which security areas do you want to audit and harden?" with header "Security audit scope".

• Credential storage — "Password hashing (argon2id/bcrypt), breach check, pepper, secret management"
• Session security — "Token generation, cookie flags, expiry, fixation, JWT pitfalls"
• Input validation — "SQL/NoSQL injection, XSS, SSRF, open redirect, schema validation"
• OAuth / OIDC — "Code + PKCE, state/nonce, redirect URIs, account linking pre-takeover"
• MFA & passkeys — "TOTP, WebAuthn, recovery codes, step-up flows"
• Short-lived tokens — "Password reset, email verification, magic link, OTP"
• Rate limiting & brute-force protection — "Multi-dim throttling, SMS pumping, credential stuffing"
• CSRF protection — "Cross-site request forgery for cookie-based auth"
• HTTP security headers — "CSP, HSTS, COOP/COEP, Clear-Site-Data"
• Error handling & information leakage — "Generic errors, no timing/size leaks, no user enumeration"
• Full audit (all of the above) — "Comprehensive security review"

Step 3: Run the Audit

For each selected area, read the corresponding rule file from rules/ and review the user's code against its checklist. Report findings as:

• PASS — implementation is correct
• FAIL — vulnerability or misconfiguration found (include file path, line number, and fix)
• MISSING — security control is absent (include where to add it and sample code)

After the audit, apply fixes directly to the code. For each fix, explain what was wrong and why the fix is necessary. Link to the relevant rule file for reference.

Step 4: Generate Report

After applying fixes, produce a summary table:

For any issues that cannot be auto-fixed (e.g., require infrastructure changes like adding Redis for rate limiting, configuring HSTS preload at the edge, registering OAuth redirect URIs with the IdP), list them as manual action items with clear instructions.

Step 5: Verify Fixes

After applying fixes: 1. If the project has tests, run them to ensure nothing broke 2. If the project has a linter, run it to verify code style 3. If the project has a build step, run it to check for compilation errors 4. If feasible, exercise the auth flows end-to-end (sign-up, sign-in, reset, logout) to confirm behavior

Implementation Rules

• Never weaken existing security. If the code already uses argon2id, do not downgrade to bcrypt. If cookies already have SameSite=Strict and the __Host- prefix, do not loosen them.
• Follow the project's existing patterns. If they use middleware for other concerns, add security middleware the same way. Match naming conventions, file structure, and error handling style.
• Do not add dependencies without asking. If a fix requires a new library (e.g. argon2, helmet, @simplewebauthn/server, hibp), ask the user before adding it.
• Adapt to the language/framework idioms. Use the canonical approach for each ecosystem (e.g. helmet middleware in Express, SecurityFilterChain in Spring Boot, middleware in Go/Chi).
• Be conservative with CSP. A too-strict Content-Security-Policy can break the application. Start in report-only mode, collect violations for 1–2 weeks, then enforce.
• Be conservative with HSTS preload. Removal takes weeks. Only preload once every subdomain serves HTTPS.
• Respect the auth-spec project rules. All auth code must be hand-written — no auth libraries (better-auth, next-auth, Auth.js, lucia, passport, etc.). Only allowed deps: web framework, ORM, password-hashing lib, WebAuthn verification lib, security-header/CSRF utility libs, and a rate-limit store client (e.g. Redis).

Sources

• OWASP Authentication Cheat Sheet
• OWASP Session Management Cheat Sheet
• OWASP Password Storage Cheat Sheet
• OWASP Multifactor Authentication Cheat Sheet
• OWASP Forgot Password Cheat Sheet
• OWASP Credential Stuffing Prevention Cheat Sheet
• OWASP API Security Top 10 (2023)
• NIST SP 800-63B rev.4 — Digital Identity Guidelines
• OAuth 2.0 Security Best Current Practice
• OAuth 2.1 (draft)
• W3C WebAuthn Level 3
• RFC 8725 — JWT BCP
• MDN HTTP Security Headers

Sections

Defines the organization and priority of security best practice rules.

Critical Impact

1. Credential Storage (credential-) Password hashing, secret management, breached-password checks, key rotation.

2. Error Handling & Information Leakage (error-) User enumeration, timing attacks, response-size/status symmetry, stack-trace leaks.

High Impact

3. Session Security (session-) Token generation, cookie flags (__Host-, Partitioned), session lifecycle, fixation prevention, JWT pitfalls.

4. Input Validation (input-) SQL/NoSQL injection, XSS, header injection, SSRF, open redirect, request body schema.

5. OAuth 2.0 / OIDC (oauth-) Authorization Code + PKCE, state/nonce, redirect-URI allow-listing, account-linking pre-takeover defense.

6. MFA, TOTP, Passkeys / WebAuthn (mfa-) Factor enrollment, recovery codes, step-up, passkey verification, TOTP replay prevention.

7. Short-Lived Token Lifecycle (token-) Password reset, email verification / change, magic link, OTP — hashing, one-time use, sibling invalidation.

Medium Impact

8. Rate Limiting & Brute-Force Protection (rate-limiting-) Multi-dimensional throttling (account + IP), SMS pumping, credential stuffing, CAPTCHA placement.

9. CSRF Protection (csrf-) Origin / Fetch-Metadata checks, double-submit token, SameSite caveats, CORS pitfalls.

Lower Priority

10. HTTP Security Headers (http-headers-) HSTS, CSP (nonce), COOP/COEP/CORP, Clear-Site-Data on logout, Trusted Types.

Rule Title

Impact: LEVEL

Brief explanation of what this rule checks and why it matters.

Checklist

Incorrect

// BAD: description of the problem

Correct

// GOOD: description of the fix

References

• Link to relevant standard or documentation

Credential Storage

Impact: CRITICAL

Weak password hashing or leaked secrets are the most direct path to mass account compromise. Every auth system must get credential storage right.

Checklist

Incorrect

// BAD: weak hashing
const hash = crypto.createHash('sha256').update(password).digest('hex');

// BAD: sending full password to remote breach API
await fetch(`https://api.example.com/check?password=${password}`);

# BAD: no max length — attacker can send 1MB password to DoS bcrypt/argon2
password = request.json["password"]

Correct

// GOOD: argon2id with reasonable parameters
import argon2 from 'argon2';
const hash = await argon2.hash(password, {
  type: argon2.argon2id,
  memoryCost: 19456, // 19 MiB
  timeCost: 2,
  parallelism: 1,
});

// GOOD: bcrypt with pre-hash to avoid 72-byte truncation
import bcrypt from 'bcrypt';
import crypto from 'crypto';
const prehashed = crypto.createHash('sha256').update(password).digest('base64');
const hash = await bcrypt.hash(prehashed, 12);

// GOOD: HIBP k-anonymity — only first 5 SHA-1 chars leave the server
const sha1 = crypto.createHash('sha1').update(password).digest('hex').toUpperCase();
const prefix = sha1.slice(0, 5);
const suffix = sha1.slice(5);
const res = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`);
const breached = (await res.text()).split('\n').some(line => line.startsWith(suffix));
if (breached) throw new Error('This password appears in known breaches. Please choose another.');

# GOOD: enforce bounds
password = request.json["password"]
if not (8 <= len(password) <= 128):
    return jsonify(error="Password must be 8-128 characters"), 400

References

• OWASP Password Storage Cheat Sheet (argon2id first)
• NIST SP 800-63B rev.4 — Memorized Secret Verifiers
• Have I Been Pwned — Pwned Passwords API (k-anonymity)
• RFC 9106 — Argon2 Memory-Hard Function

CSRF Protection

Impact: MEDIUM

If the app uses cookie-based authentication, CSRF allows attackers to perform actions as the logged-in user by tricking the browser into sending authenticated requests. SameSite=Lax alone is not sufficient — top-level GETs can still carry cookies, and GET → state change is a common mistake.

Checklist

Incorrect

// BAD: SameSite=Lax alone, no CSRF token, no Origin check
app.post('/api/change-email', (req, res) => {
  const session = getSessionFromCookie(req);
  updateEmail(session.userId, req.body.email);
});

// BAD: CORS reflecting Origin for credentialed requests — enables CSRF from any site
app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', req.headers.origin);
  res.setHeader('Access-Control-Allow-Credentials', 'true');
  next();
});

Correct

// GOOD: layered defense — Origin check + double-submit CSRF token
const ALLOWED_ORIGINS = new Set(['https://app.example.com']);

function csrfProtection(req, res, next) {
  if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return next();

  // 1. Fetch Metadata / Origin allow-list
  const origin = req.headers.origin || req.headers.referer;
  if (!origin || !ALLOWED_ORIGINS.has(new URL(origin).origin)) {
    return res.status(403).json({ error: 'Invalid origin' });
  }
  if (req.headers['sec-fetch-site'] === 'cross-site') {
    return res.status(403).json({ error: 'Cross-site request blocked' });
  }

  // 2. Double-submit token (constant-time compare)
  const cookieToken = req.cookies['__Host-csrf'];
  const headerToken = req.headers['x-csrf-token'];
  if (!cookieToken || !headerToken ||
      !crypto.timingSafeEqual(Buffer.from(cookieToken), Buffer.from(headerToken))) {
    return res.status(403).json({ error: 'CSRF token mismatch' });
  }
  next();
}

// GOOD: CSRF cookie — __Host- prefix + SameSite=Strict
res.setHeader('Set-Cookie',
  `__Host-csrf=${csrfToken}; HttpOnly=false; Secure; SameSite=Strict; Path=/`
);
// Note: CSRF cookie is intentionally NOT HttpOnly — JS reads it to echo in the X-CSRF-Token header.

References

• OWASP CSRF Prevention Cheat Sheet
• MDN — Sec-Fetch-Site (Fetch Metadata Request Headers)
• web.dev — Protect your resources from web attacks with Fetch Metadata

Error Handling & Information Leakage

Impact: CRITICAL

Verbose error messages and inconsistent response behavior leak whether accounts exist, what tech stack is used, and internal implementation details — all of which help attackers. The fix is not just the error body: attackers also observe status codes, response timing, and response size.

Checklist

Incorrect

// BAD: leaks whether email exists (text + status + timing)
const user = await db.user.findUnique({ where: { email } });
if (!user) return res.status(404).json({ error: "User not found" });
const ok = await bcrypt.compare(password, user.passwordHash);
if (!ok) return res.status(401).json({ error: "Wrong password" });

# BAD: stack trace in response
except Exception as e:
    return jsonify(error=str(e), trace=traceback.format_exc()), 500

// BAD: token comparison not constant-time
if (providedToken === expectedToken) { /* ... */ }

Correct

// GOOD: same status, same shape, constant-time-ish regardless of user existence
const DUMMY_HASH = '$argon2id$v=19$m=19456,t=2,p=1$...'; // pre-computed at boot

async function signIn(email, password) {
  const user = await db.user.findUnique({ where: { email } });
  const hash = user?.passwordHash ?? DUMMY_HASH;
  const ok = await argon2.verify(hash, password);
  if (!user || !ok) {
    return res.status(401).json({ error: "Invalid email or password" });
  }
  // ...
}

# GOOD: generic error, correlation ID, real details server-side
import uuid, logging
try:
    ...
except Exception:
    error_id = str(uuid.uuid4())
    logging.exception(f"auth error {error_id}")
    return jsonify(error="Internal server error", errorId=error_id), 500

// GOOD: constant-time token compare
import crypto from 'crypto';
const a = Buffer.from(providedToken);
const b = Buffer.from(expectedToken);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
  return res.status(401).json({ error: 'Invalid token' });
}

References

• OWASP Authentication Cheat Sheet — Authentication Responses
• CWE-209: Error Message Containing Sensitive Information
• CWE-208: Observable Timing Discrepancy
• OWASP Forgot Password Cheat Sheet

HTTP Security Headers

Impact: LOW (individually) / HIGH (cumulatively)

Security headers are a defense-in-depth layer. They don't prevent auth bugs directly, but they contain the blast radius of XSS, clickjacking, protocol downgrade, and cross-origin attacks. Auth routes deserve stricter headers than the rest of the site.

Checklist

Correct

// Middleware to set security headers on every response
function securityHeaders(req, res, next) {
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
  res.setHeader(
    'Content-Security-Policy',
    [
      "default-src 'self'",
      "base-uri 'none'",
      "object-src 'none'",
      "frame-ancestors 'none'",
      "form-action 'self'",
      `script-src 'self' 'nonce-${res.locals.cspNonce}' 'strict-dynamic'`,
      "style-src 'self' 'unsafe-inline'", // tighten later with hashes/nonces
      "img-src 'self' data:",
      "connect-src 'self'",
      "upgrade-insecure-requests",
    ].join('; ')
  );
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
  res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), interest-cohort=()');
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
  res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
  // COEP is stricter — turn on only after auditing embeds
  // res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
  res.removeHeader('X-Powered-By');
  next();
}

// On auth endpoints, add:
res.setHeader('Cache-Control', 'no-store');

// On logout:
res.setHeader('Clear-Site-Data', '"cookies", "storage", "cache"');

Notes

• Deploy CSP in report-only mode first (Content-Security-Policy-Report-Only) and collect violations for 1–2 weeks before enforcing. A too-strict CSP breaks the app.
• Prefer nonce-based CSP over 'unsafe-inline'. The nonce should be a per-request 128-bit random value.
• HSTS preload is a one-way trip — removal from the preload list takes weeks. Only preload once you're sure every subdomain serves HTTPS.

References

• MDN HTTP Security Headers
• OWASP Secure Headers Project
• web.dev — Why you need Cross-Origin Isolation
• MDN — Clear-Site-Data
• W3C — Trusted Types

Input Validation

Impact: HIGH

Unvalidated input is the root cause of SQL injection, XSS, header injection, SSRF, and open redirect — all of which can lead to account takeover or full system compromise. Validate at the boundary, with an explicit schema, allow-list where possible.

Checklist

Incorrect

// BAD: SQL injection
const user = await db.query(`SELECT * FROM users WHERE email = '${email}'`);

// BAD: NoSQL injection (no type check)
const user = await User.findOne({ email: req.body.email }); // {$ne: null} bypass

// BAD: open redirect
res.redirect(req.query.next);

// BAD: SSRF
const avatar = await fetch(req.body.avatarUrl);

// BAD: XSS via innerHTML
document.getElementById('welcome').innerHTML = `Welcome, ${user.name}`;

Correct

// GOOD: parameterized query + Zod schema + normalized email
import { z } from 'zod';
const SignInBody = z.object({
  email: z.string().email().max(254).toLowerCase(),
  password: z.string().min(8).max(128),
}).strict();
const { email, password } = SignInBody.parse(req.body);
const user = await db.query('SELECT * FROM users WHERE email = $1', [email]);

// GOOD: redirect allow-list (same-origin paths only)
const SAFE_NEXT = /^\/[a-zA-Z0-9/_-]*$/; // relative paths, no protocol-relative
const next = typeof req.query.next === 'string' && SAFE_NEXT.test(req.query.next)
  ? req.query.next
  : '/';
res.redirect(next);

// GOOD: SSRF — resolve + block private ranges
import dns from 'node:dns/promises';
import net from 'node:net';
async function safeFetch(url: string) {
  const parsed = new URL(url);
  if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error('bad scheme');
  const { address } = await dns.lookup(parsed.hostname);
  if (isPrivateIp(address)) throw new Error('blocked IP');
  return fetch(`${parsed.protocol}//${address}${parsed.pathname}`, {
    headers: { Host: parsed.hostname },
    redirect: 'manual', // follow manually so each hop is re-validated
  });
}

References

• OWASP SQL Injection Prevention Cheat Sheet
• OWASP Input Validation Cheat Sheet
• OWASP SSRF Prevention Cheat Sheet
• OWASP Unvalidated Redirects and Forwards Cheat Sheet
• CWE-601: URL Redirection to Untrusted Site (Open Redirect)

MFA, TOTP, Passkeys / WebAuthn

Impact: HIGH

MFA closes the "stolen password" attack class — but only if enrollment, recovery, and step-up flows don't themselves become bypasses. Passkeys / WebAuthn are the strongest modern option and should be the default for new systems.

Checklist — General MFA

Checklist — TOTP (RFC 6238)

Checklist — WebAuthn / Passkeys

Incorrect

// BAD: TOTP — no replay tracking, too-wide window
function verifyTotp(secret, code) {
  for (let w = -5; w <= 5; w++) { // 10 steps!
    if (totp(secret, nowStep() + w) === code) return true;
  }
  return false;
}

// BAD: password reset skips MFA
async function confirmReset(token, newPassword) {
  const userId = await consumeResetToken(token);
  await setPassword(userId, newPassword);
  await createSession(userId); // no MFA step — takeover complete
}

Correct

// GOOD: TOTP with replay protection and tight window
async function verifyTotp(user, code) {
  for (const step of [nowStep() - 1, nowStep(), nowStep() + 1]) {
    if (step <= user.totpLastUsedStep) continue; // replay
    if (constantTimeEq(totp(user.totpSecret, step), code)) {
      await db.user.update({ where: { id: user.id }, data: { totpLastUsedStep: step } });
      return true;
    }
  }
  return false;
}

// GOOD: password reset requires MFA before new session
async function confirmReset(token, newPassword) {
  const userId = await consumeResetToken(token);
  await setPassword(userId, newPassword);
  await revokeAllSessions(userId);
  if (await userHasMfa(userId)) {
    return { status: 'mfa_required', pendingId: issuePendingMfaSession(userId) };
  }
  return createSession(userId);
}

References

• OWASP Multifactor Authentication Cheat Sheet
• RFC 6238 — TOTP
• W3C WebAuthn Level 3
• passkeys.dev — Developer guidance
• FIDO Alliance — FIDO2 specs

OAuth 2.0 / OIDC Security

Impact: HIGH

OAuth bugs are the most common source of modern account takeover. The protocol is flexible; the specific choices you make decide whether "sign in with Google/GitHub" becomes a universal takeover primitive.

Checklist

Incorrect

// BAD: no state, no PKCE, implicit flow
const url = `https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=${id}&redirect_uri=${cb}`;

// BAD: account linking on unverified email
async function onGithubCallback(profile) {
  const existing = await db.user.findUnique({ where: { email: profile.email } });
  if (existing) {
    await db.account.create({ data: { userId: existing.id, provider: 'github', providerAccountId: profile.id } });
  }
}

Correct

// GOOD: authorization code + PKCE + state + nonce
const state = crypto.randomBytes(32).toString('hex');
const nonce = crypto.randomBytes(32).toString('hex');
const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
await setTempCookies({ state, nonce, verifier }); // HttpOnly, Secure, Path=/auth/callback

const url = new URL('https://accounts.google.com/o/oauth2/v2/auth');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id,
  redirect_uri, // EXACT match to what's registered
  scope: 'openid email profile',
  state,
  nonce,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString();

// GOOD: verified-email-only linking, keyed by provider account id
async function onGithubCallback(profile, verifiedEmails) {
  const emailVerified = verifiedEmails.some(e => e.email === profile.email && e.verified);
  const existingLink = await db.account.findUnique({
    where: { provider_providerAccountId: { provider: 'github', providerAccountId: profile.id } },
  });
  if (existingLink) return signInAsUser(existingLink.userId);

  if (!emailVerified) {
    // Don't auto-link. Sign in as a new user or prompt for manual link.
    return createNewUser({ email: profile.email, emailVerified: false });
  }
  const existing = await db.user.findUnique({ where: { email: profile.email } });
  if (existing) {
    await requireReAuth(); // step up before linking
    await db.account.create({
      data: { userId: existing.id, provider: 'github', providerAccountId: profile.id },
    });
  }
}

References

• OAuth 2.0 Security Best Current Practice (draft-ietf-oauth-security-topics)
• OAuth 2.1 (draft)
• RFC 7636 — PKCE
• RFC 8252 — OAuth 2.0 for Native Apps (BCP 212)
• OIDC Core — `nonce`
• Dirk Balfanz / Google — "Pre-Account Takeover" pattern via OAuth account linking

Rate Limiting & Brute-Force Protection

Impact: MEDIUM

Without rate limiting, attackers can brute-force passwords, credential-stuff leaked lists, spam sign-up, abuse verification endpoints, and burn money through SMS/email providers. Naive per-IP limits are trivially bypassed by rotating through residential proxies — combine dimensions.

Checklist

Implementation Notes

• For IP extraction behind proxies, trust X-Forwarded-For only from known load balancers. A naive req.headers['x-forwarded-for'] is attacker-controlled.
• When using sliding-window or token-bucket algorithms, document the window and burst. Don't silently change them — it affects support triage.
• Prefer fail-closed on the limiter: if Redis is down, reject auth attempts rather than letting them all through.

Refer to references/features/rate-limiting.md in the create-auth skill for full implementation details and code examples across languages.

References

• OWASP Blocking Brute Force Attacks
• OWASP Credential Stuffing Prevention Cheat Sheet
• IETF RFC 6585 — 429 Too Many Requests
• Twilio — Defending against SMS pumping fraud

Session Security

Impact: HIGH

Session tokens are bearer credentials — if an attacker obtains one, they have full access to the account. Weak generation, missing cookie flags, or improper lifecycle management are common attack vectors.

Checklist

Incorrect

// BAD: predictable token
const token = Date.now().toString(36) + Math.random().toString(36);

// BAD: cookie missing security flags, no prefix, stored raw
res.setHeader('Set-Cookie', `session=${token}`);
await db.session.create({ data: { token, userId } }); // raw token in DB

// BAD: JWT with no revocation path and no alg check
const payload = jwt.decode(req.headers.authorization.slice(7)); // no verify!

Correct

// GOOD: crypto-random token, hashed before storage
import crypto from 'crypto';
const token = crypto.randomBytes(32).toString('hex');
const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
await db.session.create({ data: { tokenHash, userId, expiresAt } });

res.setHeader('Set-Cookie',
  `__Host-session=${token}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${7 * 24 * 60 * 60}`
);

// GOOD: JWT verified with explicit algorithm allow-list
const decoded = jwt.verify(token, publicKey, {
  algorithms: ['EdDSA'], // explicit — prevents alg confusion
  issuer: 'https://auth.example.com',
  audience: 'api.example.com',
});

// GOOD: session fixation prevention — new ID on sign-in
async function signIn(email, password) {
  const user = await verifyPassword(email, password);
  await invalidateCurrentSession(req);          // kill pre-auth session
  const newToken = crypto.randomBytes(32).toString('hex');
  await createSession(user.id, hash(newToken));
  return newToken;
}

// GOOD: revoke siblings on password change
async function changePassword(userId, newPassword, currentSessionId) {
  await updatePasswordHash(userId, newPassword);
  await db.session.deleteMany({
    where: { userId, id: { not: currentSessionId } },
  });
}

References

• OWASP Session Management Cheat Sheet
• MDN — Cookie prefixes (`__Host-`, `__Secure-`)
• CHIPS — Cookies Having Independent Partitioned State
• OAuth 2.0 Refresh Token Rotation — RFC 6749 §10.4 + OAuth 2.0 Security BCP §4.14
• RFC 8725 — JSON Web Token Best Current Practices

Short-Lived Token Lifecycle

Impact: HIGH

Email-verification links, password-reset links, magic links, OTPs, and invitation tokens are all variants of the same primitive: a server-issued token a user presents to perform an action. Getting any of them wrong turns "forgot my password" into "take over any account".

Checklist — Common

Checklist — Password Reset

Checklist — Email Verification / Change

Checklist — Magic Link

Checklist — OTP / Verification Codes

Incorrect

// BAD: raw token in URL stored in plain text, no expiry, no one-time use
const token = crypto.randomUUID();
await db.resetToken.create({ data: { token, userId } });
sendEmail(`https://example.com/reset?token=${token}`);

// Later — found it? Great, let them set a password.
async function confirmReset(token, newPassword) {
  const row = await db.resetToken.findUnique({ where: { token } });
  if (!row) throw new Error('invalid');
  await setPassword(row.userId, newPassword);
  // row not deleted — token is reusable forever
}

Correct

// GOOD: hashed storage, one-time, short TTL, invalidated on use, sessions revoked
async function issueReset(email) {
  const user = await db.user.findUnique({ where: { email } });
  if (user) {
    const raw = crypto.randomBytes(32).toString('base64url');
    const hash = crypto.createHash('sha256').update(raw).digest('hex');
    await db.resetToken.deleteMany({ where: { userId: user.id } }); // invalidate siblings
    await db.resetToken.create({
      data: { userId: user.id, tokenHash: hash, expiresAt: new Date(Date.now() + 30 * 60_000) },
    });
    await sendEmail(user.email, `https://example.com/reset?t=${raw}`);
  }
  // Always same response:
  return { status: 'ok' };
}

async function confirmReset(raw, newPassword) {
  const hash = crypto.createHash('sha256').update(raw).digest('hex');
  const row = await db.resetToken.findUnique({ where: { tokenHash: hash } });
  if (!row || row.consumedAt || row.expiresAt < new Date()) {
    throw new HttpError(400, 'Invalid or expired link');
  }
  await db.$transaction([
    db.resetToken.update({ where: { id: row.id }, data: { consumedAt: new Date() } }),
    db.user.update({ where: { id: row.userId }, data: { passwordHash: await hashPassword(newPassword) } }),
    db.session.deleteMany({ where: { userId: row.userId } }),
    db.resetToken.deleteMany({ where: { userId: row.userId, consumedAt: null } }),
  ]);
  await notifyPasswordChanged(row.userId);
}

References

• OWASP Forgot Password Cheat Sheet
• OWASP Authentication Cheat Sheet — Password Recovery
• NIST SP 800-63B — Memorized Secret Verifier Recovery