Authorization Code Flow, Step by Step

import { randomBytes, createHash } from 'crypto';

const PROVIDER = {
  authorize: 'https://accounts.google.com/o/oauth2/v2/auth',
  token: 'https://oauth2.googleapis.com/token',
};
const REDIRECT_URI = 'https://abc.com/auth/callback';

// ---------- Step 2: start ----------
app.get('/auth/google', (req, res) => {
  const state = randomBytes(16).toString('base64url');
  const verifier = randomBytes(32).toString('base64url');
  const challenge = createHash('sha256').update(verifier).digest('base64url');

  // Both values must survive the round-trip, and must not be readable by JS.
  res.cookie('oauth_tx', JSON.stringify({ state, verifier }), {
    httpOnly: true, secure: true, sameSite: 'lax',
    maxAge: 10 * 60e3, path: '/auth',
  });

  const url = new URL(PROVIDER.authorize);
  url.search = new URLSearchParams({
    client_id: process.env.GOOGLE_CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: 'code',
    scope: 'openid email profile',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
    prompt: 'select_account',
  }).toString();

  res.redirect(url.toString());
});

// ---------- Steps 6-8: callback ----------
app.get('/auth/callback', async (req, res) => {
  const { code, state, error } = req.query;
  if (error) return res.redirect('/login?error=' + encodeURIComponent(String(error)));

  const tx = JSON.parse(req.cookies.oauth_tx || '{}');
  res.clearCookie('oauth_tx', { path: '/auth' });

  // CSRF protection on the callback — refuse anything that does not match.
  if (!tx.state || tx.state !== state) {
    return res.status(400).json({ error: 'invalid_state' });
  }

  const tokenRes = await fetch(PROVIDER.token, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: String(code),
      redirect_uri: REDIRECT_URI,
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      code_verifier: tx.verifier,
    }),
  });
  if (!tokenRes.ok) return res.status(502).json({ error: 'token_exchange_failed' });

  const { id_token, access_token, refresh_token } = await tokenRes.json();

  // Identity comes from the ID TOKEN, verified — never from the access token.
  const claims = await verifyIdToken(id_token);
  const user = await upsertUser({
    provider: 'google', providerId: claims.sub,
    email: claims.email, emailVerified: claims.email_verified, name: claims.name,
  });
  if (refresh_token) await storeProviderRefreshToken(user.id, refresh_token);

  // Your own session — the provider's tokens stay on the server.
  res.cookie('sid', await createSession(user.id, req), COOKIE_OPTIONS);
  res.redirect('/dashboard');
});

# WITHOUT state — "login CSRF" / account linking attack

1. Attacker starts a login at your app with THEIR OWN Google account
   and stops at the callback, capturing:
     https://abc.com/auth/callback?code=ATTACKER_CODE

2. Attacker gets the victim to visit that URL (email, image tag, redirect).

3. Your app exchanges ATTACKER_CODE and links the VICTIM's session to the
   ATTACKER's Google identity.

4. The victim now uploads documents, saves cards, writes notes...
   into an account the attacker can log into at will.

# WITH state

2'. The victim's browser has no oauth_tx cookie, or it holds a different
    state value → mismatch → 400, flow aborted.

# state is not a nicety. It is the CSRF token of the OAuth callback.