Authentication Fundamentals

# TaskFlow Authentication Mental Model

Authentication answers: Who is this caller?
Authorization answers: What may this authenticated caller do?

Target direction for later phases:

Browser
  -> authentication provider (Supabase Auth in Phase 17)
  -> authenticated session
  -> access token
  -> Next.js
  -> Authorization: Bearer <access-token>
  -> NestJS authentication guard
  -> verified identity
  -> service/business logic
  -> authorization/ownership checks

Do not accept userId from the browser as proof of identity.
Do not put credentials, refresh tokens, session identifiers, or long-lived bearer tokens in URLs.

# Bearer token request
GET /tasks HTTP/1.1
Host: api.example.com
Authorization: Bearer <access-token>

# Example hardened session cookie shape (illustrative)
Set-Cookie: __Host-taskflow_session=<opaque-id>; Path=/; Secure; HttpOnly; SameSite=Lax

# Do NOT do this
GET /tasks?access_token=<token>
GET /tasks?userId=<browser-supplied-id>

# Do NOT log these
Authorization: Bearer ...
Cookie: ...
password=...
refresh_token=...

# JWT Claims Reference

A JWT commonly contains registered claims such as:

- iss - issuer
- sub - subject
- aud - intended audience
- exp - expiration time
- nbf - not before
- iat - issued at
- jti - token identifier

Important: Base64url decoding is not validation. A resource server must verify the cryptographic signature and enforce the claims required by its security policy. JWT payloads are not automatically confidential. Do not put secrets into ordinary signed JWT claims.

# Phase 17 Readiness

Before Supabase Auth integration, the learner should be able to explain:

1. Identity vs credential vs session.
2. Authentication vs authorization.
3. Access token vs refresh token.
4. Why bearer tokens are credentials.
5. Why decoding a JWT does not prove authenticity.
6. What iss, sub, aud, and exp mean.
7. Why browser token storage is a security decision.
8. HttpOnly / Secure / SameSite cookie attributes.
9. XSS vs CSRF at a high level.
10. Why NestJS must derive identity from a verified token rather than from userId supplied by the caller.

# Authentication Security Checklist

- Keep authentication and authorization conceptually separate.
- Prefer a mature identity provider over writing password authentication from scratch.
- Passwords must never be stored in plaintext.
- Password storage uses a slow password hashing function, not a fast general-purpose hash.
- Use HTTPS for authentication and authenticated requests.
- Treat bearer tokens like credentials.
- Validate JWT signature plus application-required claims such as issuer, audience, and expiration.
- Never trust a JWT only because it can be decoded.
- Keep access tokens short-lived.
- Protect refresh tokens more strongly than access tokens and support rotation/revocation where the provider does.
- Avoid browser localStorage/sessionStorage for authentication tokens when a safer HttpOnly cookie or BFF/session pattern is available.
- Cookie-based sessions should use Secure, HttpOnly, and an intentional SameSite policy.
- Cookie authentication requires CSRF reasoning.
- JavaScript-readable token storage requires strong XSS reasoning.
- Do not log passwords, access tokens, refresh tokens, session IDs, authorization headers, or cookies.
- Logout is a lifecycle operation, not merely hiding the UI.
- Re-authenticate for sensitive operations when product risk justifies it.
- Rate-limit authentication endpoints and monitor suspicious behavior.