Coder Legion - Recent posts tagged jwt

What Is Authentication? A Beginner's Guide (2026)

Tue, 01 Sep 2026 05:07:56 +0000

Every time you type your email and password into a login form, something is quietly deciding whether you actually get in. That decision — proving you are who you say you are — is called authentication, and it's one of those concepts every developer touches constantly but rarely stops to explain from scratch.

If you've ever wondered what actually happens between "click Sign In" and "welcome back," or mixed up authentication with authorization in an interview, this guide is for you. By the end, you'll know exactly what authentication is, how the major methods work under the hood, and how to build a basic authentication flow yourself.

What Is Authentication? (Quick Answer)

Authentication is the process of verifying that someone is who they claim to be. It answers one question: "Who are you?" This usually happens by checking a password, a code from your phone, a fingerprint, or a token — something only the real user should have or know.

Authentication is different from authorization, which answers a separate question: "What are you allowed to do?" A logged-in user is authenticated. Whether that user can delete another person's account is authorization. Mixing these two up is one of the most common beginner mistakes — keep them mentally separate from the start.

💡 Simple way to remember it: Authentication = ID check at the door. Authorization = the guest list that decides which rooms you can enter once you're inside.

Why Authentication Matters

Without proper authentication and authorization, an app that stores personal data could expose private information to unauthorized users. Authentication provides the identity context that many authorization, personalization, and auditing systems rely on.

It matters for a few concrete reasons:

Privacy — only the right person sees their own data
Security — prevents account takeover and unauthorized access
Personalization — apps can remember who you are across visits
Accountability — actions can be traced back to a real identity (important for admin tools, financial apps, audit logs)

Authentication vs. Authorization: The Difference That Trips Everyone Up

	Authentication	Authorization
Question it answers	Who are you?	What can you do?
Happens	First	After authentication
Example	Logging in with a password	Only admins can access `/admin`
Failure result	401 Unauthorized	403 Forbidden

Why the HTTP status codes are confusingly named: 401 Unauthorized actually means "you're not authenticated" (log in first), while 403 Forbidden means "you're authenticated, but not allowed to do this." Yes, 401 should really be called "Unauthenticated" — it's a long-standing naming quirk in the HTTP spec that trips up almost every developer at least once.

Related: Role-Based Access Control (RBAC) in Next.js 16 goes deep on the authorization half of this once you're ready for it.

How Authentication Works (Step by Step)

At a high level, almost every authentication system follows the same basic loop:

The user provides credentials — a password, a fingerprint, a one-time code, or an existing account from another provider (like signing in with Google)
The server verifies those credentials — checking a hashed password, validating a signed token, or confirming a biometric match
The server issues proof of identity — usually a session or a token, stored in a cookie or sent back to the client
That proof is sent with future requests — so the user doesn't have to log in again on every page

User submits credentials
        ↓
Server verifies credentials
        ↓
Server issues session/token
        ↓
Client stores it (cookie)
        ↓
Future requests include it
        ↓
Server verifies it's still valid

That last step — verifying the proof of identity on every request — is what keeps a user "logged in" without asking for their password on every single page.

The Main Types of Authentication

There isn't just one way to authenticate someone. Here are the methods you'll actually run into as a developer.

1. Password-Based Authentication

The classic: a username/email plus a password, checked against a hashed value stored in your database. Never store plain-text passwords — always hash them with a slow, password-specific hashing algorithm such as Argon2id. If it's not available, bcrypt or another appropriate password hashing algorithm can be used.

// lib/auth/hash-password.ts
import bcrypt from "bcryptjs";

const SALT_ROUNDS = 12;

export async function hashPassword(plainPassword: string): Promise<string> {
  return bcrypt.hash(plainPassword, SALT_ROUNDS);
}

export async function verifyPassword(
  plainPassword: string,
  hashedPassword: string
): Promise<boolean> {
  return bcrypt.compare(plainPassword, hashedPassword);
}

What's happening here: bcrypt.hash() doesn't just scramble the password — it applies a slow, computationally expensive algorithm on purpose, which increases the cost of each password guess and makes large-scale brute-force attacks significantly more expensive. SALT_ROUNDS = 12 is above OWASP's minimum bcrypt work factor of 10, but the right value depends on your server's hardware and traffic. Benchmark your production environment and choose a cost that makes password verification sufficiently expensive without creating unacceptable latency.

⚠️ bcrypt limitation: bcrypt has a hard 72-byte input limit, and most implementations (including bcryptjs) silently truncate anything past it rather than erroring. Because UTF-8 characters like emoji or accented letters can take up to 4 bytes each, a password that looks well under the limit in characters can still get silently cut short in bytes — which can cause two different passwords to be treated as equivalent after truncation.
OWASP currently recommends enforcing a maximum of 72 bytes (or less, depending on the implementation) when bcrypt is used. Because UTF-8 characters can occupy multiple bytes, a character-count limit alone doesn't necessarily correspond to bcrypt's byte limit.

⚠️ Common Mistake: Comparing passwords with a plain === check after "encrypting" them with something reversible like Base64. That's encoding, not hashing — it can be reversed instantly. Only use a dedicated password-hashing library.

2. Session-Based Authentication

After a successful login, the server creates a session record stored in server-side session storage such as a database or shared cache — and gives the browser a random session ID in an httpOnly cookie. On every request, the server looks up that ID to know who's logged in.

// lib/auth/session.ts
import { cookies } from "next/headers";
import { randomUUID } from "crypto";

export async function createSession(userId: string, expiresAt: Date) {
  // Generate a random, unguessable session ID — never store the raw
  // userId (or anything else predictable) directly as the cookie's
  // value. The cookie is a reference you look up server-side; it
  // should never double as proof of identity on its own.
  const sessionId = randomUUID();

  // Persist the mapping server-side, e.g.:
  // await db.session.create({ data: { sessionId, userId, expiresAt } });

  const cookieStore = await cookies();

  cookieStore.set("session_id", sessionId, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

Why each flag matters: httpOnly stops client-side JavaScript from reading the cookie (blocking a common XSS attack path). secure means it's only sent over HTTPS. sameSite: "lax" limits when the browser sends the cookie in cross-site requests and provides some CSRF protection. For state-changing operations, you should still implement an appropriate CSRF defense rather than relying on SameSite alone.

Pros: straightforward server-side revocation; deleting a session record can invalidate that session immediately, and deleting all of a user's sessions can log them out everywhere.
Cons: can require a server-side session lookup on authenticated requests, although caching can reduce the cost.

3. Token-Based Authentication (JWT)

Instead of looking anything up server-side, a JSON Web Token (JWT) packs the user's identity directly into a signed token. In a stateless JWT design, the server can verify the token cryptographically without looking up a session record in the database.

// lib/auth/jwt.ts
import { SignJWT, jwtVerify } from "jose";

const secretKey = new TextEncoder().encode(process.env.AUTH_SECRET);

export async function signToken(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId)
    .setIssuedAt()
    .setExpirationTime(expiresAt)
    .sign(secretKey);
}

export async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, secretKey, {
      algorithms: ["HS256"],
    });
    return payload;
  } catch {
    return null; // invalid or expired
  }
}

What's happening here: jose is the standard, actively maintained library for signing and verifying JWTs using the Web Crypto API — it works in Node.js, edge runtimes, and browsers. setSubject(userId) stores the user's ID in the token's standard sub claim. jwtVerify() automatically rejects the token if the signature doesn't match or if it's expired, so you never write manual expiry checks.

⚠️ Signing is not encryption. A JWT's payload is only base64url-encoded, not encrypted — anyone can decode and read it. The signature only proves it wasn't tampered with. Never put sensitive data (passwords, secrets) inside a JWT payload.

Pros: no database lookup needed to verify identity, works well across distributed/stateless servers.
Cons: harder to instantly revoke a single token before it expires (it's valid until it naturally expires unless you build extra machinery around it).

💡 For a deeper side-by-side of these two models — including how each behaves at scale — see Session vs JWT: Which Should You Use in Next.js 16?

OAuth 2.0 is an authorization framework that lets an application obtain limited access to resources on behalf of a user. It doesn't, by itself, define how an application verifies the user's identity.

For "Sign in with Google," "Sign in with Microsoft," and similar login flows, applications commonly use OpenID Connect (OIDC) — an identity layer built on top of OAuth 2.0. The identity provider authenticates the user and returns an ID token containing claims about that authentication.

User clicks "Sign in with GitHub"
        ↓
Redirected to GitHub
        ↓
User authenticates and approves access
        ↓
GitHub redirects back with a code
        ↓
Your server exchanges the code for tokens
        ↓
Your server validates the OIDC identity information
        ↓
Your app creates its own session

This is why OAuth is so popular for beginners and production apps alike — you outsource the hardest parts (password storage, breach risk, 2FA) to a provider that already does it well.

5. Multi-Factor Authentication (MFA / 2FA)

MFA requires more than one proof of identity — typically "something you know" (a password) plus "something you have" (a phone, an authenticator app code, a hardware key). Even if a password leaks, the attacker still can't get in without the second factor.

6. Passwordless Authentication (Magic Links & Passkeys)

Two increasingly common alternatives to passwords:

Magic links — the user enters their email, gets a one-time sign-in link, and clicking it logs them in. No password to remember or leak.
Passkeys (WebAuthn) — device-based authentication using Face ID, Windows Hello, or a hardware security key. No shared secret exists to steal in the first place, which makes passkeys resistant to phishing in a way passwords fundamentally aren't.

A Minimal Authentication Flow in Next.js

Here's a simplified but realistic login flow using Next.js 16, TypeScript, and session cookies — the same core pattern used by most production apps, just without the database wiring.

// actions/login.ts
"use server";

import { redirect } from "next/navigation";
import { verifyPassword } from "@/lib/auth/hash-password";
import { createSession } from "@/lib/auth/session";
import { z } from "zod";

const loginSchema = z.object({
  email: z.email(),
  password: z.string().min(8),
});

export async function login(prevState: unknown, formData: FormData) {
  const parsed = loginSchema.safeParse({
    email: formData.get("email"),
    password: formData.get("password"),
  });

  if (!parsed.success) {
    return { error: "Enter a valid email and password." };
  }

  // Look up the user in your database (pseudocode)
  const user = await db.user.findUnique({ where: { email: parsed.data.email } });

  if (!user || !(await verifyPassword(parsed.data.password, user.passwordHash))) {
    // Same generic error for both cases — don't reveal which one was wrong
    return { error: "Invalid email or password." };
  }

  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
  await createSession(user.id, expiresAt);

  redirect("/dashboard");
}

What's happening here: the form data is validated with Zod before touching the database — never trust raw input. Notice the login failure returns the same generic message whether the email doesn't exist or the password is wrong; revealing which one failed makes it easier for attackers to enumerate valid accounts. A working session gets created only after the password check succeeds, then the user is redirected.

⚠️ Common Mistake: Checking authentication only in proxy and assuming that's enough. Proxy-level checks are a good UX shortcut (fast redirect before a page even loads), but sensitive Server Actions, Route Handlers, and data-access functions should independently verify authentication and authorization rather than relying solely on proxy.ts.

Building this by hand is a great way to learn, but most production apps reach for a maintained library instead — see How to Add Auth.js (NextAuth v5) in Next.js 16, Add Clerk Authentication to Next.js 16, or (if you're already on Supabase) Supabase Auth vs Firebase Auth.

Common Authentication Mistakes to Avoid

Storing plain-text passwords — always hash with Argon2id or bcrypt, never store or log the raw password
Storing a predictable value as the session cookie — the cookie should be a random, unguessable reference, never the raw user ID or anything else an attacker could construct
Weak or reused session/JWT secrets — generate a long, random secret and never commit it to git
Revealing which field was wrong — "Invalid email" vs. "Invalid password" tells attackers an account exists
Skipping rate limiting — without it, attackers can brute-force passwords with unlimited attempts
Relying only on client-side checks — a hidden button or disabled form field doesn't stop a direct API request
Forgetting to expire sessions/tokens — every session and token should have a sane expiry, not live forever

Frequently Asked Questions

What is the difference between authentication and authorization?

Authentication confirms who someone is (logging in). Authorization decides what they're allowed to do once they're recognized (permissions, roles, access control). You always need authentication before authorization can happen.

Yes — a login system is simply the implementation of authentication. Whatever mechanism confirms a user's identity (password, OAuth, passkey) is functioning as authentication, regardless of what you call the feature.

What's the difference between sessions and JWTs?

A session stores authentication/session state on the server and gives the browser only a random reference ID, which allows instant revocation. A JWT stores the identity data directly inside a signed token the server can verify without a database lookup, trading easy revocation for less server-side state.

Keep JWT minimal — a JWT should not be treated as a general-purpose user profile or database replacement.

Do I need a library to build authentication, or can I build it myself?

You can build basic password + session authentication yourself using the patterns above, but for anything production-facing, an established library (Auth.js, Clerk, Better Auth, or your database provider's built-in auth) is strongly recommended — they handle edge cases like token rotation, breach detection, and secure defaults that are easy to get subtly wrong by hand.

Is two-factor authentication (2FA) actually necessary?

For anything holding sensitive data — financial info, personal messages, admin access — yes. 2FA dramatically reduces account takeover risk even when a password leaks, since the attacker also needs the second factor.

Are passkeys better than passwords?

Generally yes, from a security standpoint — passkeys are phishing-resistant because there's no shared secret to trick someone into revealing. Adoption is still growing, though, so most apps currently offer passkeys as an option alongside passwords rather than a full replacement.

Wrapping Up

Authentication boils down to one question — "who are you?" — answered through a password, a token, a device, or some combination of them. Once you separate authentication from authorization, the ecosystem becomes easier to understand: passwords and passkeys are authentication mechanisms, sessions and JWTs are ways to maintain authenticated state, and OAuth/OIDC provide delegated authorization and federated identity.

If you're building this in a real Next.js app, the next logical steps are wiring up role-based authorization on top of your authentication layer, and deciding between session-based and JWT-based auth based on whether instant revocation matters for your product.

Continue Learning

Free Developer Tools

Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.
Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.

Session vs JWT: Which Should You Use in Next.js 16?

Tue, 25 Aug 2026 04:12:26 +0000

You're building a login flow in Next.js 16, and you hit the question every auth tutorial glosses over: should the logged-in state live in a session or a JWT? Half the guides you find use one, half use the other, and almost none of them tell you why — or what breaks if you pick wrong.

Here's the annoying part: both approaches look nearly identical from the outside. A cookie gets set, the user stays logged in, everyone's happy. The difference only shows up later — when you need to log a user out of every device instantly, when your app scales past one server, or when you're debugging why a "revoked" user can still hit your API for another six days.

By the end of this guide, you'll know exactly how sessions and JWTs work under the hood, see real, working code for both in Next.js 16 — using jose, Server Actions, and proxy.ts — and know which one actually fits your project instead of copying whatever the last tutorial you read happened to use.

Why This Is Tricky

Most explanations of "session vs JWT" get stuck comparing them as if they're two totally separate technologies. They're not. In both approaches, the browser stores a cookie. The real difference is what that cookie contains, and where the source of truth lives:

Session-based auth: the cookie holds a random ID. The actual user data lives in your database. Every request that needs to know "who is this?" looks it up server-side.
JWT-based auth: the cookie holds the user data itself, cryptographically signed. Your server can verify it's untampered without ever touching a database.

That one distinction — lookup vs. self-contained — is what drives every tradeoff in this post: revocation, scaling, latency, and how much you need to trust the cookie itself.

💡 Tip: If you've used Auth.js (NextAuth v5), you've already used both without necessarily noticing — its session: { strategy: "jwt" } and session: { strategy: "database" } options are exactly this same choice, just configured for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (no manual useMemo/useCallback needed)
Tailwind CSS for the (minimal) UI examples

You don't need a real database to follow along — the JWT section has zero dependencies, and the session section uses a generic db client you can swap for Postgres, Supabase, or whatever you're already using.

How Sessions Work

💡 Think of it like: a coat check ticket. The ticket itself is just a number — it means nothing on its own. The actual coat (your user data) stays with the attendant (your database). Lose the ticket, and the attendant can also just... stop honoring it. Instantly.

User logs in with the right credentials.
Your server generates a random token, stores it in a sessions table alongside the user's ID and an expiry, and sends that token back as an httpOnly cookie.
On every request, your server takes the cookie value, looks it up in the database, and either finds a valid session or doesn't.
To log someone out — including forcibly, from your side — you delete the row. Done. The cookie is now worthless.

The tradeoff: every authenticated request costs a database round trip (unless you cache it), but you get instant, guaranteed revocation.

How JWTs Work

💡 Think of it like: a sealed, signed letter. Anyone can read what's inside once it's opened, but nobody can forge your signature or quietly edit the contents without breaking the seal. The letter is self-sufficient — you don't need to call anyone to confirm it's real, just check the seal.

User logs in with the right credentials.
Your server creates a token containing the user's ID (and whatever else you want) and signs it with a secret key.
On every request, your server checks the signature against that same secret. If it matches, the data inside is trusted — no database lookup required.
To log someone out, you delete the cookie client-side. But if someone already has a copy of that token, it's still valid — and still verifiable — until it naturally expires. There's no built-in way to say "actually, ignore this one."

The tradeoff: verification is fast and needs no database, but you give up the ability to instantly kill a single session without extra machinery.

⚠️ Common Mistake: Calling a JWT stored in a cookie a "session" and assuming it behaves like one. It doesn't — a JWT has no server-side record at all unless you deliberately build one (see the revocation section below). If your mental model is "session," you'll be surprised the first time you try to force-logout a user and nothing happens.

⚠️ Cookie size limits: browsers cap a single cookie at roughly 4KB, and most reverse proxies (Nginx, Cloudflare) reject requests once the total header size gets much past 8KB. A session-ID cookie is always tiny — it's just a random string. A JWT cookie grows with every claim you cram into the payload (roles, permissions, profile fields). Stuff enough into it and the cookie silently fails to set, or your CDN starts 400-ing requests, with no obvious error pointing back at "your JWT got too big." Keep JWT payloads minimal — an ID and maybe a role, not a serialized user object.

Step 1: Set Up the Shared Pieces

Both approaches need somewhere to keep a signing secret. Add one to your environment file:

# .env.local
SESSION_SECRET=your-long-random-secret-here

Generate a strong value instead of typing something memorable:

node -e "console.log(crypto.randomBytes(32).toString('hex'))"

⚠️ Common Mistake: Committing SESSION_SECRET to git, or reusing your .env.local value in production. Treat it exactly like a database password — if it leaks, an attacker can forge valid sessions for any user, for either approach below.

Step 2: Build JWT-Based Auth with `jose`

jose is the standard library for signing and verifying JWTs in an Edge-compatible way — it uses the Web Crypto API instead of Node's crypto module, so it works identically in Server Actions, Route Handlers, and proxy.ts.

npm install jose

Create the sign/verify helpers

// lib/jwt/session.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";

const secretKey = process.env.SESSION_SECRET;
const encodedKey = new TextEncoder().encode(secretKey);

export async function encrypt(userId: string, expiresAt: Date) {
  return new SignJWT({})
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId) // sub — who this token belongs to
    .setIssuedAt() // iat — when it was issued
    .setExpirationTime(expiresAt) // exp — when it stops being valid
    .sign(encodedKey);
}

export async function decrypt(token: string | undefined = "") {
  try {
    const { payload } = await jwtVerify(token, encodedKey, {
      algorithms: ["HS256"],
    });
    return payload; // payload.sub is the userId; iat/exp are unix seconds
  } catch {
    // Invalid signature, tampered payload, or expired token
    return null;
  }
}

What's happening here: instead of a custom userId field, this uses the standard, registered JWT claims — sub (subject, via .setSubject()), iat (issued-at, via .setIssuedAt()), and exp (expiry, via .setExpirationTime()). These three are part of the JWT spec itself, not a jose-specific convention, so any JWT library — in any language — knows how to read them. jwtVerify automatically checks exp and rejects an expired token before your code ever sees the payload, so you never write manual date comparisons.

⚠️ Signing is not encryption. SignJWT — despite this file calling the wrapper functions encrypt/decrypt for readability — does not hide the payload. A JWT's contents are only base64url-encoded, not encrypted, so anyone who intercepts the cookie (or just opens DevTools → Application → Cookies) can decode and read sub, iat, and exp in plain text. What the signature guarantees is that the payload wasn't tampered with — change one character and jwtVerify rejects it. Never put anything genuinely secret (passwords, tokens for other services, PII you wouldn't want exposed) inside a signed JWT. If you actually need to hide the contents too, that's a different primitive — JWE — which jose supports separately via EncryptJWT/jwtDecrypt.

💡 Do you still need setExpirationTime if you also track expiry elsewhere? No — and the version above deliberately avoids the redundancy. Compute the expiry date once, and hand that same Date to both setExpirationTime() (for the JWT's own exp claim) and the cookie's expires option, as shown in the next step. Two separately-computed "7 days from now" values can drift apart by milliseconds and give you two conflicting sources of truth for the same thing — pick one.

// lib/jwt/actions.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { encrypt } from "./session";

export async function createSession(userId: string) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
  const session = await encrypt(userId, expiresAt); // same Date used for exp and the cookie
  const cookieStore = await cookies();

  cookieStore.set("session", session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: "lax",
    path: "/",
  });
}

export async function deleteSession() {
  const cookieStore = await cookies();
  cookieStore.delete("session");
  redirect("/login");
}

What's happening here: httpOnly: true keeps the cookie invisible to client-side JavaScript, which stops it from being stolen via an XSS attack. secure: true means it's only ever sent over HTTPS. sameSite: "lax" blocks the cookie from being attached to most cross-site requests, which is your main defense against CSRF here. None of this is JWT-specific — you'd want the exact same flags on a session-ID cookie too.

Verify the session with a Data Access Layer

Don't scatter decrypt() calls across every page. Centralize verification in one cached function — this is what Next.js's own docs call a Data Access Layer (DAL).

// lib/jwt/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { decrypt } from "./session";

export const verifySession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;
  const session = await decrypt(token);

  if (!session?.sub) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.sub };
});

What's happening here: wrapping this in React's cache() means that no matter how many components on the same page call verifySession(), the actual decrypt-and-check logic only runs once per request — every subsequent call reuses the result. session.sub is the standard claim set by .setSubject() earlier, so this reads it back out under a friendlier userId name for the rest of your app. Call this at the top of any Server Component, Server Action, or Route Handler that needs to know who's logged in.

// app/dashboard/page.tsx
import { verifySession } from "@/lib/jwt/dal";

export default async function DashboardPage() {
  const { userId } = await verifySession();

  return <h1>Welcome back, user {userId}</h1>;
}

Add an optimistic check in `proxy.ts`

In Next.js 16, middleware.ts was renamed to proxy.ts — same file convention, same idea. It's the first thing that runs before a request reaches a page, which makes it a good place for a fast, optimistic redirect. Full verification still happens in the DAL above — proxy.ts just avoids letting an obviously-unauthenticated request render a protected page at all.

// proxy.ts
import { NextRequest, NextResponse } from "next/server";

const protectedRoutes = ["/dashboard"];
const publicRoutes = ["/login", "/signup"];

export default function proxy(req: NextRequest) {
  const path = req.nextUrl.pathname;
  const isProtectedRoute = protectedRoutes.some((route) => path.startsWith(route));
  const isPublicRoute = publicRoutes.includes(path);

  // Optimistic check only — we just look for the cookie's presence.
  // We deliberately don't verify the signature here; that happens
  // in verifySession() inside the Data Access Layer.
  const cookie = req.cookies.get("session")?.value;

  if (isProtectedRoute && !cookie) {
    return NextResponse.redirect(new URL("/login", req.nextUrl));
  }

  if (isPublicRoute && cookie) {
    return NextResponse.redirect(new URL("/dashboard", req.nextUrl));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

⚠️ Common Mistake: Treating proxy.ts as your only security check. It's a UX nicety that avoids a flash of protected content — it is not a substitute for re-verifying the session inside every Server Action and Route Handler that actually touches data. A request can always be sent directly, bypassing whatever page it "should" have come from.

Step 3: Build Database-Backed Sessions

Now the other approach — a real session table your server checks on each request.

Create the sessions table

-- Works for Postgres/Supabase; adjust types for your database
create table sessions (
  token_hash text primary key,
  user_id uuid not null references auth.users(id) on delete cascade,
  expires_at timestamptz not null,
  created_at timestamptz not null default now()
);

create index idx_sessions_user_id on sessions (user_id);

What's happening here: notice the primary key is token_hash, not token. We never store the raw session token in the database — only its hash. This mirrors how you'd never store a plaintext password: if your database ever leaked, an attacker with the hashes still couldn't reconstruct a working cookie.

⚠️ Cleanup: expiring a session only stops it from being accepted — the expires_at < now() check in verifyDbSession below handles that. It does not delete the row. Left alone, this table grows forever, one row per login, most of them long past their expiry date. Run a scheduled cleanup — a Vercel Cron job hitting a small Route Handler once a day is enough for most apps:
delete from sessions where expires_at < now();
This is purely a housekeeping/performance concern (an unbounded table gets slower to index and back up over time), not a security one — an expired row is already useless for authentication either way.

// lib/db-session/create.ts
import "server-only";
import { randomBytes, createHash } from "crypto";
import { cookies } from "next/headers";
import { db } from "@/lib/db";

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

export async function createDbSession(userId: string) {
  const token = randomBytes(32).toString("hex"); // goes to the browser
  const tokenHash = hashToken(token); // goes to the database
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);

  await db.session.create({
    data: { tokenHash, userId, expiresAt },
  });

  const cookieStore = await cookies();
  cookieStore.set("session", token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

What's happening here: randomBytes(32) generates a token with enough entropy that guessing it is computationally infeasible — this is the piece doing the actual security work, not the hashing. We hash it with SHA-256 purely so a database leak doesn't hand out working session tokens; the browser still holds the real, unhashed token in its cookie.

Verify the session (with caching, so it doesn't hit the database on every render)

// lib/db-session/dal.ts
import "server-only";
import { cache } from "react";
import { cookies } from "next/headers";
import { createHash } from "crypto";
import { redirect } from "next/navigation";
import { db } from "@/lib/db";

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

export const verifyDbSession = cache(async () => {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (!token) redirect("/login");

  const tokenHash = hashToken(token);
  const session = await db.session.findUnique({
    where: { tokenHash },
    include: { user: true },
  });

  if (!session || session.expiresAt < new Date()) {
    redirect("/login");
  }

  return { isAuth: true, userId: session.userId, user: session.user };
});

What's happening here: just like the JWT version, cache() means one database lookup per request no matter how many components ask "who's logged in?" This is the piece that makes database sessions viable in practice — without it, a page with five components each checking auth would fire five identical queries.

Revoking a session — the whole point of this approach

// lib/db-session/delete.ts
"use server";

import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { createHash } from "crypto";
import { db } from "@/lib/db";

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

export async function deleteDbSession() {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;

  if (token) {
    await db.session.delete({ where: { tokenHash: hashToken(token) } }).catch(() => {});
  }

  cookieStore.delete("session");
  redirect("/login");
}

// Force-logout every session for a user — e.g. after a password reset
export async function revokeAllSessionsForUser(userId: string) {
  await db.session.deleteMany({ where: { userId } });
}

What's happening here: revokeAllSessionsForUser is the function you can't build with plain JWTs — one query, and every device that user is logged in on is instantly signed out, because the next request they make finds no matching row. This is the single biggest practical reason teams reach for database sessions over JWTs.

proxy.ts looks identical to the JWT version above — it's still just checking whether the session cookie exists, since that check never needed to know which auth strategy is behind it.

Session vs JWT: Side-by-Side

	Session (database)	JWT
Where the data lives	Server-side (database row)	Inside the token itself
Cookie contents	Random, meaningless ID	Signed, self-contained payload
Instant revocation	✅ Delete the row	❌ Not without extra machinery
Force-logout everywhere	✅ One query	❌ Requires a blocklist or short expiry + refresh
Per-request cost	One DB lookup (cacheable per request)	No DB call — just signature verification
Works well at scale / multi-server	Needs a shared database (usually already true)	Naturally stateless, nothing to share
Payload can go stale	No — always reads current data	Yes — data inside is frozen until re-issued
Implementation complexity	Slightly more (schema, hashing, cleanup)	Slightly less (no schema needed)
Best for	Apps where instant revocation matters <br/> (banking, admin tools, anything security-sensitive)	High-traffic, distributed systems where avoiding a <br/>DB hit per request matters

💡 Tip: "JWTs don't need a database" is true for verification, but most real apps still store something — a refresh-token table, a denylist, or at minimum a passwordChangedAt timestamp checked against the token's iat (issued-at) claim. The stateless promise of JWTs is a little softer in practice than it sounds in theory.

A Closer Look: What "Horizontal Scaling" Actually Means Here

"Naturally stateless" in the table above is doing a lot of work, so let's unpack it. Say your app runs on five server instances behind a load balancer — a request from the same user could land on a different instance every time.

With database sessions: whichever instance handles the request just needs to reach the same database everyone else does. In practice this is a non-issue for most Next.js apps, since you already have one shared database — every instance was already talking to it for everything else. The "scaling problem" people worry about here mostly doesn't exist unless you're deliberately running sessions in something instance-local, like in-memory storage (don't do that).
With JWTs: verification needs nothing but the signing secret, which every instance already has as an environment variable. No instance has to coordinate with any other instance, or with a database, to answer "is this token valid?" That's genuinely useful once you're running at the edge — Cloudflare Workers, Vercel Edge Functions — across multiple regions, where a round trip to a single-region database could add real, noticeable latency to every request.

So the honest version: for a typical app with one shared Postgres/Supabase database, this isn't really a deciding factor — you're already "horizontally scaled" for sessions for free. It starts to matter once you're running truly distributed, multi-region, or edge-first infrastructure where a database round trip per request is a real, measured cost, not a hypothetical one.

Sliding (Rolling) Sessions

So far, every example here uses a fixed expiry — log in, get 7 days, and after 7 days you're logged out no matter how active you were. A sliding session (also called a rolling session) instead extends the expiry every time the user does something, so an active user effectively never gets logged out, while an idle one still expires on schedule.

With database sessions, this is simple: on every successful verifyDbSession() call, update that row's expires_at to "now + 7 days" again.
```
// Inside verifyDbSession, after confirming the session is valid
await db.session.update({
  where: { tokenHash },
  data: { expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) },
});
```
One extra write per (cached) verification — cheap, and the source of truth (the row) is already being touched anyway.

💡 Tip: In production it's common to only extend the session once every few hours instead of on every request to avoid unnecessary writes.

With JWTs, this is more work: the exp claim is baked into the signature at issue time — you can't quietly extend it without re-signing a brand-new token and setting a brand-new cookie on the response. Doable inside a Route Handler or Server Action (create a fresh token with a new expiresAt, call cookies().set() again), but it means writing a cookie back on requests that otherwise wouldn't need one, which is easy to forget to wire up consistently across every route.

💡 Tip: If "stay logged in while active, expire after a week of silence" is a real requirement for your app, that alone is a reasonable tie-breaker toward database sessions — it's a one-line update there versus meaningfully more plumbing with JWTs.

Can You Get Revocation With JWTs?

Yes, with a tradeoff. Two common patterns:

Short expiry + refresh tokens. Issue an access token that expires in 10–15 minutes, plus a longer-lived refresh token stored in the database. To revoke, you delete the refresh token — the access token is still technically valid, but only for a few more minutes, which is an acceptable blast radius for most apps.
A denylist. Keep a small, fast-to-check store (Redis is the usual choice) of token IDs (jti claims) that have been explicitly revoked. Every verification also checks this list. This reintroduces a lookup on every request — at that point, you've mostly reinvented database sessions with extra steps.

Neither of these makes JWTs behave exactly like sessions — they just narrow the gap. If instant, guaranteed revocation is a hard requirement (think: a compromised admin account), database sessions remove the problem entirely instead of managing around it.

Which One Should You Actually Use?

Building a typical SaaS dashboard, internal tool, or content site? Database sessions. The DB hit is cheap with caching, and "log this user out right now" is a feature you'll eventually need, even if you don't think so today.
Building something with genuinely massive, distributed, stateless traffic (think: an API consumed by thousands of independent clients, or infrastructure where adding a database round trip to every request is a real cost)? JWTs earn their keep here.
Already using Auth.js or Clerk? You don't have to choose by hand — Auth.js exposes session: { strategy: "jwt" | "database" } directly, and Clerk manages this decision for you behind its own infrastructure.
Not sure yet? Default to database sessions. It's the safer, more debuggable choice, and the performance cost is rarely the bottleneck people assume it'll be — cache the lookup with cache() as shown above and it disappears from your profiler.

Frequently Asked Questions

Can I combine both approaches?

Yes — this is actually what "refresh tokens" are: a short-lived JWT for fast verification, backed by a database-stored refresh token for revocation. You get JWT-speed reads most of the time, with a real revocation point when you need one.

No, and the difference matters for security. An httpOnly cookie can't be read by client-side JavaScript, so it's protected from XSS attacks that steal tokens. localStorage is fully readable by any script running on your page — a single XSS vulnerability anywhere in your dependency tree can leak every token stored there. Always use httpOnly cookies for auth tokens in a Next.js app.

Does `proxy.ts` need to fully verify the session on every request?

No, and for JWT-based auth verifying in proxy.ts with jose is genuinely fine performance-wise since it needs no database call. The stronger rule is: never treat proxy.ts as your only check. Always re-verify inside the Server Action or Route Handler that actually reads or writes data — proxy.ts can be bypassed by hitting that endpoint directly.

Why hash the session token before storing it in the database?

The same reason you hash passwords — if your database is ever compromised (a leaked backup, a misconfigured access policy), the attacker gets a list of hashes they can't turn back into working session cookies. It costs you one sha256 call per request, which is effectively free.

Which one does Auth.js use by default?

Auth.js defaults to the "jwt" strategy unless you configure a database adapter, in which case it switches to "database" automatically. You can also set session: { strategy: "jwt" } explicitly even with an adapter configured, if you want JWTs for speed while still persisting user accounts.

Wrapping Up

Sessions and JWTs aren't competing standards — they're two different answers to "where does the source of truth for a logged-in user live?" Sessions keep it on your server, trading a database lookup for instant, total control over who stays logged in. JWTs keep it in the token itself, trading that control for verification that never has to leave the request.

For most Next.js apps, start with database sessions — the caching pattern above keeps the performance cost near zero, and you'll be glad revocation is a solved problem the first time you actually need it. Reach for JWTs specifically when you've measured that the database hit matters, not because a tutorial defaulted to it.

From here, a natural next step is wiring either pattern into a real login form with Zod validating the credentials before they ever reach your session logic, or layering role-based permissions on top of whichever session strategy you pick.

Continue Learning

Useful Resources

Stop Pasting JWTs Into Random Websites. Here's What I Built Instead.

Tue, 02 Jun 2026 06:43:46 +0000

By Abu Sufyan · Lead Systems Architect, WebToolkit Pro

Every week, thousands of developers do something they know they shouldn't.

They open a new browser tab, navigate to some third-party JWT decoder, and paste a live production token directly into it.

That token probably contains a user ID. Maybe a role claim. Maybe an internal service identifier that maps to something sensitive in your infrastructure. And it just left your browser.

I know, because I used to do it too.

The Incident That Made Me Stop

In late 2024, I was debugging an auth issue on a client's Node.js API — a financial services platform. Standard stuff: the access token wasn't refreshing correctly and I needed to inspect the payload quickly to verify the exp claim.

I instinctively opened a well-known JWT decoder site and pasted the token.

Then I stopped.

I was working in a production environment. That token belonged to a real user — a client of theirs. It contained a sub (subject) claim with a UUID that mapped directly to their user database. It contained an iat and exp. And most critically, it contained a roles claim: ["admin", "finance_read"].

I had just sent a production admin token to a third-party server I knew nothing about.

The site claimed it was "client-side only." But I couldn't verify that. There was no open-source repo I could inspect. No audit trail. No CSP headers I could check. Just a text box and a promise.

That afternoon, I filed an internal incident report and started building a replacement.

What Makes a JWT Decoder Dangerous

Before I get to what I built, it's worth understanding exactly why this matters technically — not just philosophically.

A JWT has three parts: header, payload, and signature. The first two are just Base64url-encoded JSON. Decoding them requires zero network traffic. It's pure string manipulation you can do in two lines of JavaScript:

const [header, payload] = token.split('.');
const decoded = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));

That's it. There is no cryptographic reason a JWT decoder needs to contact any server whatsoever.

And yet, when you paste a token into most online decoders, your token travels over the network to a server. That server may or may not be logging requests. It may be behind a CDN that caches POST bodies. It may be owned by a company whose threat model you have no visibility into.

The attack surface is real:

Session hijacking if the token is still valid and the attacker can replay it against your API
Claim exposure — user IDs, email addresses, role names, tenant identifiers
Infrastructure mapping — the iss (issuer) claim often reveals internal service URLs or identity provider endpoints
Algorithm fingerprinting — the alg header tells an attacker exactly what signing algorithm you're using, useful for crafting exploit attempts

The Architecture: Zero-Knowledge Client-Side Decoding

What I built — the Offline JWT Decoder at WebToolkit Pro — operates on a simple constraint: nothing ever leaves the browser tab.

Here's the actual execution model:

User pastes token → Browser JS splits on '.'
                  → atob() decodes header + payload
                  → JSON.parse() reconstructs the object
                  → Rendered directly into DOM

No fetch(). No XMLHttpRequest(). No WebSocket. No Service Worker relay.

To verify this yourself: open DevTools → Network tab → paste a token → watch. Zero outbound requests. The network panel stays empty.

The implementation uses the Web Crypto API for signature verification — which also runs entirely in the browser sandbox. There are no API keys, no backend, no telemetry. The Content Security Policy on the page blocks outbound requests at the browser level, so even if a malicious script injection somehow occurred, it couldn't exfiltrate the token.

Beyond Decoding: The Signature Verification Problem

Most online JWT decoders only decode. They don't verify.

Decoding tells you what's inside the token. Verification tells you whether to trust it.

The difference matters enormously in debugging scenarios. If you're diagnosing an auth failure, you need to know:

Is the token malformed? (decoding fails)
Is it expired? (check exp vs current timestamp)
Is the signature valid against the expected public key? (actual cryptographic verification)

Point 3 is where most tools fall apart. They skip it entirely, leaving you with no way to confirm whether the token was legitimately issued or tampered with.

The JWT Debugger & Inspector I built handles all three. You can paste your JWKS (JSON Web Key Set) endpoint URL or paste the raw public key directly, and the tool performs RS256/ES256 signature verification locally using window.crypto.subtle.verify() — the same Web Crypto primitive your browser uses for HTTPS.

// What's happening under the hood
const key = await crypto.subtle.importKey(
  'jwk',
  jwkPublicKey,
  { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
  false,
  ['verify']
);

const isValid = await crypto.subtle.verify(
  'RSASSA-PKCS1-v1_5',
  key,
  signature,
  data
);

No server. No SDK. Pure browser cryptography.

The `alg: none` Attack — Why Your Decoder Needs to Flag This

While building this, I added one feature that I think every JWT tool should have: automatic detection of the alg: none exploit vector.

Here's the attack. Some JWT libraries — particularly older versions — accept tokens where the algorithm is set to none and the signature is empty. An attacker who knows this can forge a token with any payload they want:

// Header
{
  "alg": "none",
  "typ": "JWT"
}
// Payload
{
  "sub": "1234567890",
  "roles": ["admin"],
  "iat": 1516239022
}
// Signature: empty string

This gets concatenated as base64(header).base64(payload). — note the trailing dot with no signature.

The decoder flags this immediately with a warning: ⚠ Algorithm "none" detected. This token carries no cryptographic integrity guarantee. Reject in production.

It's a small thing, but it's the kind of context-aware output you only get from a tool built by someone who actually works with these tokens in production.

What I Learned Building Privacy-First Tools

This JWT decoder is one of 150+ tools I've built at WebToolkit Pro. Every single one follows the same constraint: your data never leaves your browser.

Password generator. Hash generator. Base64 encoder. Regex tester. JSON formatter. AES encryption tool. All of them execute entirely client-side.

Building this way taught me a few things:

WebAssembly changed what's possible. Operations that used to require a server — like Argon2 password hashing, which is deliberately memory-intensive — can now run in the browser via WASM. The Argon2 Hasher generates production-grade password hashes locally in under a second.

Web Workers are underused. For tools that process large inputs (the JSON formatter handles payloads up to 50MB), moving the parsing off the main thread via Web Workers keeps the UI responsive. No spinners, no freezes.

The hardest part isn't the crypto — it's the UX. Security tools have a reputation for being hostile to use. I spent more time on the output formatting and error messaging than on the underlying algorithms. A tool that correctly identifies an exp claim mismatch but displays it as a raw timestamp integer has failed its user.

Try It Yourself

If you're debugging JWTs today, open DevTools first. Network tab, record. Then go to wtkpro.site/tools/jwt-decoder and paste your token.

Watch the network panel stay silent.

That silence is the feature.

# How Authentication Really Works (JWT vs Session vs OAuth)

Fri, 17 Apr 2026 06:14:22 +0000

Whenever you log in to a website…

You enter:

Email
Password

And suddenly…

You are “logged in”

But what actually happens behind the scenes?

How does the system remember you?

Let’s break it down simply

First: What is Authentication?

Authentication =

“Proving that you are who you say you are”

Example:

Login form
OTP verification
Google login

⚙️ Basic Flow (Before JWT / Session / OAuth)

User enters email + password
Server verifies credentials
Now server needs to “remember” the user

This is where things get interesting

1. Session-Based Authentication

How It Works

User logs in
Server creates a session
Stores session in database/memory
Sends a session ID to browser (via cookie)

Now:

Every request → sends session ID
Server checks → “Yes, this is the user”

Flow

✅ Pros

Simple to implement
Easy to invalidate (logout)

❌ Cons

Server has to store sessions
Not scalable for large systems

⚡ 2. JWT (JSON Web Token)

How It Works

Instead of storing session on server…

Server gives token to user

This token contains:

User ID
Expiry time
Signature

Example:

header.payload.signature

Now:

Client stores JWT (localStorage / cookie)
Sends it with every request

Server:

Verifies token → allows access

Flow

✅ Pros

Stateless (no server storage)
Scalable
Fast

❌ Cons

Hard to revoke instantly
Needs proper security handling

How It Works

Instead of creating your own login system…

You use another provider

Example:

“Login with Google”
“Login with GitHub”

Flow

User clicks Google login
Redirect to Google
User authenticates
Google sends token back
Your app trusts Google → logs user in

✅ Pros

No need to manage passwords
More secure
Faster user onboarding

❌ Cons

Dependency on third-party
Slightly complex setup

JWT vs Session vs OAuth (Simple Comparison)

Feature	Session	JWT	OAuth
Storage	Server	Client	Third-party
Scalability	Medium	High	High
Complexity	Easy	Medium	Medium-Hard
Use Case	Small apps	APIs / SPAs	Social login

When to Use What?

Small app → Session
Modern API / frontend → JWT
Social login → OAuth

Many apps use combination (JWT + OAuth)

⚠️ Common Mistakes

Storing JWT insecurely ❌
Not setting expiry ❌
Weak session management ❌

Security matters a lot here

Final Thought

Authentication looks simple on UI…

But behind the scenes:

It’s all about trust, identity, and security

As a developer:

Understanding this = real backend skill

Now next time you click “Login”…

You know exactly what’s happening

Advance Auth Templete

Fri, 30 Jan 2026 11:40:29 +0000

Advance Auth (TypeScript) – Production-Ready Auth Template for Real Projects

I built a modular, production-grade authentication template so I never have to rewrite auth again, and now you don’t either.

This is not a demo. This is a fork-and-build foundation for real SaaS, startups, and side projects.

Repo: https://github.com/SAYOUNCDR/Advance-Auth

What’s inside

A full auth system written in TypeScript + Node + Express, designed the way it should be done in real backends:

JWT access + refresh token rotation

RBAC (User / Admin roles)

Google OAuth

Email verification flow

Forgot / Reset password

2FA with TOTP (Google Authenticator)

Zod validation everywhere

Modular, clean architecture

Secure password hashing (bcrypt)

Token versioning, secure cookie handling

Ready for scaling and extension

⚠️ What’s left (being honest)

Only two things are pending:

Final rate limiting middleware wiring

A few extra security hardening checks

The core system is already solid and usable.

Why this matters

Auth is boring, repetitive, and easy to mess up.

Now you can:

Fork this repo

Plug in your business logic

Start building features immediately

Modify or extend auth without pain

No rewrites. No hacks. No copy-paste hell.

️ Stack

TypeScript

Node.js + Express

MongoDB (Mongoose)

JWT

Zod

OAuth

Nodemailer

otplib (2FA)

Who should use this

Indie hackers

Startup founders

Full-stack devs

Anyone tired of rebuilding auth from scratch

Fork it, break it, improve it, ship with it.

If you care about clean backend engineering, this is for you.

Building Secure JWT Auth in NestJS: Argon2, Redis Blacklisting, and Token Rotation

Sun, 18 Jan 2026 17:16:38 +0000

Imagine you've just watched your first tutorial on authentication. You spin up a login flow, add some JWTs, and call it done. Then you push to production and realize those tutorials skipped the hard parts—token revocation, session management, replay attacks.

It's not enough to have a login endpoint. Production auth means thinking like an attacker and handling edge cases that basic tutorials ignore. Let's talk about what actually secure authentication looks like in NestJS and how to implement it without the security holes.

When a developer says they are "implementing auth," they are usually talking about two distinct but inseparable concepts: Authentication and Authorization. When building robust systems, these go hand in hand.

Authentication (AuthN) vs. Authorization (AuthZ)

Authentication is about identity. It answers "Who are you?" using credentials like email/password, passkeys, or biometrics.
Authorization is about permissions. It answers "What can you do?" Once we know who you are, we use strategies like Role-Based Access Control (RBAC) to ensure you only touch the resources you're allowed to.

The NestJS Toolkit: Passport and Guards

In the NestJS ecosystem, we don't reinvent the wheel. We use Passport.js, the industry standard for Node.js authentication. NestJS wraps this in @nestjs/passport and provides AuthGuards.

Guards are the "bouncers" of your application. When a request hits a protected route, the Guard intercepts it, extracts the token, and validates it before the request ever reaches your controller logic.

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(
    private readonly reflector: Reflector,
    private readonly redis: RedisService,
  ) {
    super();
  }

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (isPublic) return true;

    const request = context.switchToHttp().getRequest();
    if (!request.headers['authorization']) return false;

    const token = request.headers['authorization'].split(' ')[1] as string;

    // Check if the token was manually revoked (logout)
    const isBlacklisted = await this.redis.isTokenBlacklisted(token);
    if (isBlacklisted) return false;

    const result = super.canActivate(context);
    return result instanceof Promise ? result : (result as boolean);
  }
}

Secure Onboarding: Why Argon2?

For sign-up, you need to store passwords. I chose Argon2 over the more common Bcrypt. Argon2 was the winner of the Password Hashing Competition for a reason: it's memory-intensive.

Unlike older algorithms, Argon2 allows you to configure memory usage, making it significantly harder to crack using specialized hardware like GPUs or ASICs. It essentially punishes brute-force attempts with slow, high-resource computation.

Registration (Hashing)

When a user signs up, the plain-text password is transformed into a hash before being stored in the database.

// UsersService
import { hash } from '@node-rs/argon2';

async create(data: CreateUserDto): Promise<User> {
  let userData = { ...data };
  if (data.password) {
    const passwordHash = await hash(data.password); //
    userData = { ...userData, password: passwordHash };
  }
  return await this.prisma.user.create({ data: userData });
}

Crucially, we never "decrypt" a password. When a user logs in:

We retrieve the stored hash from the DB.
We take the plain-text password provided in the login form.
We run the provided password through the same hashing process (including the "salt" stored within the hash).
If the resulting hash matches the stored one, the user is verified.

import { verify } from '@node-rs/argon2';

// AuthService
async validateUser(email: string, password: string): Promise<UserEntity | undefined> {
  const user = await this.usersService.findOneByEmail(email);
  if (user && user.password) {
    /* The verify function automatically creates a hash of the plain
password and compares it against our stored password hash */
    const isPasswordValid = await verify(user.password, password);
    if (isPasswordValid) return new UserEntity(user);
    throw new UnauthorizedException('Password is not valid');
  }
}

The Dual-Token Strategy

Once verified, we generate two tokens.

1. The Access Token (Short-lived & Stateless)

Signed with a secret key, this contains the user’s ID and metadata. We set this to 15 minutes. This is the industry standard because it limits the "blast radius"—if a token is stolen, it’s only useful for a tiny window.

2. The Refresh Token (Long-lived & Stateful)

Signed with a completely different secret (this is vital for security), we set this to 7 days. Unlike the access token, we store this in our database (Prisma) because it needs to be stateful. We also attach a unique JTI (JWT ID) when signing the token to allow for efficient database lookups after decoding the JWT.

By storing it, we gain a "Kill Switch." If we detect suspicious activity, we can manually revoke that specific token in the DB, preventing it from ever being used to generate a new access token. Here's how we create and store the refresh token in our database:

import { randomUUID } from 'node:crypto';

// JwtRefreshService
async create(payload: CreateRefreshTokenDto): Promise<string> {
  const tokenId = randomUUID(); // Unique ID for this token
  const refresh_token = this.jwtService.sign(
    { ...payload, jti: tokenId },
    {
      secret: this.configService.get('JWT_REFRESH_SECRET'),
      expiresIn: '7d',
    },
  );

  const hashed_refresh_token = await hash(refresh_token);

  await this.prisma.refreshToken.create({
    data: {
      id: tokenId,
      token: hashed_refresh_token,
      userId: payload.sub,
      absolute_limit_at: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // Hard session limit
      isRevoked: false,
    },
  });

  return refresh_token;
}

Solving the "Stateless Revocation" Problem with Redis

The biggest flaw in JWTs is that they are stateless. If a user logs out, their Access Token is still technically valid until those 15 minutes are up.

To fix this without destroying performance, we use Redis.

Redis is an in-memory key-value store. Because it lives in RAM, it provides the sub-millisecond read/writes we need to check every single incoming request without slowing down the API. On logout, we "blacklist" the access token in Redis for the remainder of its lifespan. Our JwtAuthGuard then checks Redis on every request: if the token is in the blacklist, access is denied. When the user logs out, we calculate how long until the access token would naturally expire and blacklist it for exactly that duration:

// RedisService implementation
async blacklistToken(token: string, ttl: number): Promise<void> {
  await this.redis.set(`blacklist:${token}`, '1', { EX: ttl }); //
}

async isTokenBlacklisted(token: string): Promise<boolean> {
    const result = await this.redis.exists(`blacklist:${token}`);
    return result === 1;
 }

// JwtAuthGuard
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
    // existing authorization logic

    // Check if the token was manually revoked (logout)
    const isBlacklisted = await this.redis.isTokenBlacklisted(token);
    if (isBlacklisted) return false;

    // return result
   }
}

// Logout logic
async logout(data: { userId: string; access_token: string; refresh_token: string }) {
  const access_token_payload = await this.jwtService.verifyAsync(data.access_token);
  const ttl = access_token_payload.exp - Math.floor(Date.now() / 1000);
  
  if (ttl > 0) {
    await this.redisService.blacklistToken(data.access_token, ttl); //
  }
  // ... proceed to revoke refresh token
}

Refresh Token Rotation & Absolute Limits

What if a refresh token is stolen? An attacker could theoretically stay logged in for 7 days. We solve this with Refresh Token Rotation.

Every time a user uses a Refresh Token to get a new Access Token, we:

Invalidate the old Refresh Token.
Issue a brand-new Refresh Token.

The Absolute Time Limit

To prevent a session from being kept alive forever by rotation, we implement an Absolute Time Limit (e.g., 90 days). This is set at the initial login. Every time a token rotates, that original 90-day timestamp is carried forward. Once we hit that date, no more rotations are allowed—the user must log in with their password again.

// rotateRefreshToken logic
async rotateRefreshToken(payload: RotateRefreshTokenDto) {
  const { old_refresh_token_id, time_limit, sub, email, deviceInfo } = payload;
  
  await this.revokeRefreshToken(old_refresh_token_id); // Invalidate old

  const new_refresh_token = this.jwtService.sign(
        {
          email,
          sub,
          deviceInfo,
        },
        {
          secret: this.configService.get<string>('JWT_REFRESH_SECRET'),
          expiresIn: '7d',
        },
      );
  
  // Create new token record with the original time_limit
  await this.prisma.refreshToken.create({
    data: {
      token: await hash(new_refresh_token),
      userId: sub,
      absolute_limit_at: time_limit, // Carry forward absolute limit
      isRevoked: false,
    },
  });
}

  async revokeRefreshToken(token_id: string) {
    try {
      await this.prisma.refreshToken.update({
        where: {
          id: token_id,
        },
        data: {
          isRevoked: true,
        },
      });
    } catch (error) {
      if (error instanceof Prisma.PrismaClientKnownRequestError) {
        if (error.code === 'P2025') {
          throw new NotFoundException('Token not found');
        }
      }
      throw error;
    }
  }

  @Public()
  @UseGuards(JwtRefreshAuthGuard)
  @Post('refresh')
  async refresh(
    @Request()
    req: RequestType & {
      user: { email: string; id: string; refreshToken: string };
    },
    @Response({ passthrough: true }) res: ResponseType,
  ) {
    if (req.user) {
      const tokens = await this.authService.refreshTokens({
        userId: req.user.id ?? '',
        email: req.user.email ?? '',
        token: req.user.refreshToken ?? '',
      });

      res.cookie('titan_refresh_token', tokens?.refresh_token, {
        httpOnly: true,
        secure: true,
        sameSite: 'strict',
      });

      return { access_token: tokens?.access_token };
    }
  }

Reuse Detection (The "Nuclear" Option)

If a token that was already revoked is used, it signals a potential theft. The system responds by revoking all tokens for that user.

// validateToken snippet
if (storedToken?.isRevoked) {
  // Nuke 'em
  await this.prisma.refreshToken.updateMany({
    where: { userId: payload.userId },
    data: { isRevoked: true }, // Revoke all active sessions for this user
  });
  throw new UnauthorizedException('Token reuse detected. Please login again');
}

One thing to note is that while we return the access token to the user in the response body, we have to set the refresh token as a http-only cookie.

  @Post('login')
@UseGuards(LocalAuthGuard)
async login(
  @Request() req: RequestType & { user: UserEntity },
  @Response({ passthrough: true }) res: ResponseType,
) {
  const deviceInfo = req.headers['user-agent'] || 'Unknown Device';

  const { access_token, refresh_token } = await this.authService.login(
    req.user,
    deviceInfo,
  );

  // Securely set the Refresh Token as a cookie
  res.cookie('titan_refresh_token', refresh_token, {
    httpOnly: true, // Prevents JS from reading the cookie
    secure: true,   // Only sent over HTTPS
    sameSite: 'strict', // Protects against CSRF
    path: '/auth/refresh', // Optional: Only send cookie to the refresh endpoint
  });

  // Send the Access Token in the body for the frontend to store in memory
  return { access_token };
}

The reason for this is to make the refresh token invisible to the client-side javascript. Even if an attacker successfully runs a script on your page, they cannot "read" the refresh token. We also set secure: true (ensuring it's only sent over HTTPS) and sameSite: strict to protect against CSRF attacks.

As for the access token, the frontend receives it in the JSON response and typically stores it in memory (a variable). While it's still technically vulnerable to XSS, because it isn't persisted in storage, it's much harder to exfiltrate, and its short 15-minute lifespan limits the damage if it is compromised

Conclusion

At the end of the day, writing code alone doesn't build a secure authentication system. We need to constantly balance security, speed, and user experience. By thinking like an attacker, we can turn standard JWTs into a fortified system using tools like Redis and techniques like Refresh Rotation. It takes a bit more effort to set up, but the peace of mind knowing you’ve accounted for edge cases like token theft or stale sessions is well worth the complexity, especially in sensitive applications.

Summary of our Security Workflow

Memory-Hard Hashing: Used Argon2 to ensure passwords are resistant to GPU-based cracking.
Dual-Token Architecture: Balanced security with short-lived (15 min) access tokens and long-lived (7 day) refresh tokens.
Real-time Revocation: Leveraged Redis for sub-millisecond access token blacklisting upon logout.
Session Lifecycle Management: Implemented 90-day absolute time limits to ensure no session lasts forever.
Automatic Breach Detection: Enabled Refresh Token Rotation with a "nuclear" reuse detection trigger that invalidates all user sessions if a stolen token is detected.

Technical Stack Overview

Tool	Purpose	Key Feature
NestJS	Backend Framework	Modular architecture and robust dependency injection.
Passport.js	Auth Logic	Industry-standard middleware for handling JWT strategies.
Argon2	Password and Token Hashing	Memory-intensive hashing
Prisma	Database ORM	Type-safe interaction with our stateful Refresh Token storage.
Redis	In-Memory Store	Rapid read/write operations for stateless token revocation (blacklisting).
JWT	Tokenization	Secure, encoded payload delivery for AuthN and AuthZ.

Authentication Tokens: Your Digital VIP Pass

Wed, 24 Sep 2025 13:05:12 +0000

In today's connected world, we all want to access our favorite apps and websites without re-entering our password every two seconds. That's where authentication tokens, or "auth tokens," come in. Think of them like a digital VIP pass. When you log in with your username and password, the server checks your credentials and, if everything's good, hands you a special token. Instead of sending your password with every request, your app sends this token. The server then uses the token to confirm you're still you, and you can access all the cool stuff you're supposed to.

How It Works: A Simple Flow

The basic process is pretty straightforward:

Login: You enter your username and password on an application's login screen.
Verification: The application sends your credentials to its server for verification.
Token Generation: If your credentials are correct, the server generates a unique auth token.
Token Received: The server sends this token back to your application, which stores it, usually in a cookie or local storage.
Access: From now on, whenever you need to access a protected resource, like your profile page or your shopping cart, the application includes the token in the request header.
Token Validation: The server receives the request, validates the token, and grants access if it's valid.

This system is great for scalability because the server doesn't need to remember who is logged in. This makes the server stateless, which is a huge plus for performance and building microservice architectures.

Types of Tokens You'll Encounter

There are a few different types of tokens, each with its own pros and cons.

1. JSON Web Tokens (JWTs)

A JWT (pronounced "jot") is a popular type of token that's self-contained. This means all the necessary user information is right inside the token itself. A JWT is made up of three parts, separated by periods:

Header: Describes the token type and the signing algorithm.
Payload: Contains "claims," which are statements about the user and the token. This is where you'd find user ID, roles, and the token's expiration date.
Signature: A unique signature created using a secret key. This is what the server uses to verify that the token hasn't been tampered with.

Because a JWT contains everything the server needs to know, the server doesn't have to perform a database lookup for every request. This makes them really fast and efficient.

Here's a quick Python example using the PyJWT library to create a JWT:

import jwt
import datetime

payload_data = {
    'sub': '1234567890',
    'name': 'John Doe',
    'iat': datetime.datetime.now(datetime.timezone.utc),
    'exp': datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=30)
}

secret_key = 'your_super_secret_key' # In a real app, use an environment variable!

token = jwt.encode(payload_data, secret_key, algorithm='HS256')

print(token)

You can then decode and verify this token on the server side to get the payload data.

2. Opaque Tokens

Unlike JWTs, opaque tokens are just random strings of characters. The client can't read anything from them. They are essentially a reference to a record stored in the server's database. When a server receives an opaque token, it has to go to the database to look up the token and retrieve the associated user data and permissions.

Pros & Cons:

JWTs: Fast, scalable, and don't require database lookups. The downside is that once issued, they can't be easily revoked before they expire.
Opaque Tokens: More secure since no information is exposed to the client. They are also easily revocable. The trade-off is that they require a database lookup on every request, which can add overhead.

3. Hybrid Tokens

A common and secure pattern is to use a hybrid approach. This combines the best of both worlds. You'll often see this with OAuth 2.0:

Short-lived Access Token: This is a JWT, used for accessing resources. It's valid for a short time (e.g., 15 minutes), so if it's stolen, the attacker doesn't have much time to use it.
Long-lived Refresh Token: This is an opaque token, used to get a new access token once the old one expires. It's stored securely and can be revoked by the server if needed. This prevents a user from having to log in again every 15 minutes.

This approach balances the performance benefits of JWTs with the security and revocability of opaque tokens.

Conclusion: Which One Should You Use?

The choice of token depends on your application's needs. For a simple app where you want to keep things fast and stateless, a JWT might be the perfect fit. For a system that requires a high level of security and granular control over token revocation, a hybrid model is often the way to go. No matter which you choose, understanding how they work is a crucial skill for any developer building secure and scalable applications.

Understanding JWT: From Basics to Advanced Security

Fri, 28 Feb 2025 19:34:07 +0000

Introduction: The Evolution of Web Authentication

Early days of the web, authentication was relatively simple - users would log in, and servers would store their session information. However, as applications grew more complex and moved toward distributed systems and microservices, this traditional approach faced scalability challenges. JSON Web Tokens (JWTs), a revolutionary solution that changed how we handle authentication and authorization in modern web applications.

JWTs represent a paradigm shift in web security. Instead of the server keeping track of who's logged in, it issues a secure, self-contained token that holds all necessary information about the user. Think of it like a digital passport - once issued by a trusted authority, it can be verified anywhere without needing to check back with the issuing country. This approach has become increasingly important in our interconnected world of cloud services, mobile applications, and API-driven architectures.

Part 1: JWT Fundamentals

What is a JWT?

A JSON Web Token is a compact, self-contained way to securely transmit information between parties as a JSON object. Think of it as a digital passport that proves your identity and permissions in the web world. Each JWT contains three essential parts:

Header: The metadata section that describes the token's type and the signing algorithm used
Payload: The actual data (called "claims") about the user and additional metadata
Signature: A verification seal that ensures the token hasn't been tampered with

When these three parts are combined, you get something that looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The Anatomy of a JWT: Understanding the Structure

Before diving into how JWTs work, let's examine their structure in detail. A JWT consists of three distinct parts, each encoded in Base64URL format and separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header (The Metadata)

The header contains information about how the token itself is constructed. It typically includes:

{
  "alg": "HS256",    // The algorithm used for signing
  "typ": "JWT"       // The type of token
}

2. Payload (The Claims)

The payload carries the actual information about the user and token metadata. It contains claims, which are statements about an entity (typically the user) and additional metadata.

There are three types of claims:

Public Claims: Custom claims registered in the IANA JSON Web Token Registry
Private Claims: Custom claims created for sharing information between parties
Registered Claims: Predefined claims like:

{
  "iss": "auth.service.com",  // Issuer
  "sub": "user123",           // Subject
  "exp": 1516239022,         // Expiration Time
  "iat": 1516232822          // Issued At
}

3. Signature (The Verification Seal)

The signature is created by taking the encoded header, encoded payload, and a secret key, then applying the algorithm specified in the header. For example, with HMAC SHA256:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret
)

This signature ensures that the token hasn't been modified in transit and verifies its authenticity.

How Does JWT Work in Practice?

The journey of a JWT follows a simple flow:

Authentication: When you log in successfully, the server creates a JWT containing information about your identity and permissions
Token Storage: Your application receives and stores this token
Authorization: For subsequent requests, your application includes this token in the header
Verification: The server checks the token's signature and grants access if it's valid

This process eliminates the need for the server to store session information, making JWTs perfect for modern, scalable applications.

Part 2: The Security Challenge

Common JWT Vulnerabilities

While JWTs are powerful, they're not immune to security issues. Here are the key vulnerabilities to watch out for:

Signature Verification Flaws

The signature is like a tamper-evident seal on a package. If the verification process is flawed or the secret key is weak, attackers can modify the token's contents without detection. This is particularly dangerous because it could allow unauthorized access to protected resources.

Algorithm Confusion Attacks

JWTs support multiple signing algorithms, including a dangerous "none" algorithm. If your server isn't configured properly, an attacker might trick it into accepting an unsigned token, effectively bypassing security checks altogether.

Client-Side Storage Risks

Many applications store JWTs in browser storage (localStorage or sessionStorage), making them vulnerable to Cross-Site Scripting (XSS) attacks. Think of this like keeping your house key in an obvious place - if someone gains access to your browser's JavaScript environment, they could steal your token.

The Revocation Challenge

Unlike traditional session tokens, JWTs don't have a built-in way to be invalidated before they expire. This means if a token is compromised, it remains valid until its expiration time, potentially giving attackers a window of opportunity.

Part 3: Building a Secure JWT Implementation

Essential Security Practices

Let's explore how to implement JWTs securely:

1. Secure Communication

Always transmit JWTs over HTTPS. This encrypts the token during transmission, preventing eavesdropping attacks. It's like sending sensitive documents through a secure courier service instead of regular mail.

2. Smart Token Storage

Instead of using browser storage, use HttpOnly cookies with the Secure flag enabled. This approach prevents JavaScript access to the token while ensuring it's only transmitted over secure connections. The cookie settings might look like this:

Set-Cookie: access_token=<token>;
            HttpOnly;
            Secure;
            SameSite=Strict;
            Path=/api

3. Token Lifecycle Management

Implement a robust token lifecycle strategy:

Set short expiration times for access tokens (15-30 minutes)
Use refresh tokens for obtaining new access tokens
Maintain a token blacklist for revoked tokens
Implement token rotation to regularly replace active tokens

4. Payload Security

Be mindful of what you include in your token payload:

Never store sensitive data like passwords or credit card numbers
Minimize the payload size to reduce overhead
Consider encrypting certain claims if they contain sensitive information

Advanced Security Measures

Going beyond the basics:

1. Fingerprinting

Include device or context information in the token to detect potential token theft:

{
  "sub": "1234567890",
  "fingerprint": "device_id|user_agent|ip_hash",
  "exp": 1516239022
}

2. Audience Validation

Specify and validate the intended recipient of the token to prevent token reuse across different services:

{
  "aud": "https://api.myservice.com",
  "sub": "1234567890",
  "exp": 1516239022
}

Part 4: The Future of JWT Security

Emerging Security Enhancements

The security landscape is constantly evolving, and JWT security is no exception. Here are some promising developments:

1. Quantum-Resistant Algorithms

As quantum computing advances, new signing algorithms resistant to quantum attacks are being developed. These will ensure JWTs remain secure even in a post-quantum world.

2. Dynamic Validation

Future implementations might include real-time validation systems that can instantly revoke tokens based on security events or user behavior changes.

3. Enhanced Standards

The JWT standard continues to evolve with new security features and best practices. Stay updated with the latest JWT specifications and security recommendations from the IETF.

Conclusion

JWTs represent a powerful solution for modern web authentication and authorization, but their security requires careful consideration and implementation. By understanding both the fundamentals and security challenges, and by implementing robust security measures, you can harness the benefits of JWTs while maintaining strong security.

Learn on JWT, OAuth, OIDC, and SAML: https://guptadeepak.com/demystifying-jwt-oauth-oidc-and-saml-a-technical-guide/

Quick Reference: JWT Security Checklist

✓ Use strong, unique signing keys
✓ Implement proper algorithm validation
✓ Store tokens securely (HttpOnly cookies)
✓ Set appropriate token expiration
✓ Implement token rotation
✓ Validate token claims thoroughly
✓ Monitor for security updates
✓ Use HTTPS exclusively
✓ Implement proper error handling
✓ Regular security audits

Coder Legion - Recent posts tagged jwt

What Is Authentication? A Beginner's Guide (2026)

What Is Authentication? (Quick Answer)

Why Authentication Matters

Authentication vs. Authorization: The Difference That Trips Everyone Up

How Authentication Works (Step by Step)

The Main Types of Authentication

1. Password-Based Authentication

2. Session-Based Authentication

3. Token-Based Authentication (JWT)

4. OAuth / OpenID Connect (Social Login)

5. Multi-Factor Authentication (MFA / 2FA)

6. Passwordless Authentication (Magic Links & Passkeys)

A Minimal Authentication Flow in Next.js

Common Authentication Mistakes to Avoid

Frequently Asked Questions

What is the difference between authentication and authorization?

Is a login system the same thing as authentication?

What's the difference between sessions and JWTs?

Do I need a library to build authentication, or can I build it myself?

Is two-factor authentication (2FA) actually necessary?

Are passkeys better than passwords?

Wrapping Up

Continue Learning

Free Developer Tools

Session vs JWT: Which Should You Use in Next.js 16?

Why This Is Tricky

Prerequisites

How Sessions Work

How JWTs Work

Step 1: Set Up the Shared Pieces

Step 2: Build JWT-Based Auth with jose

Create the sign/verify helpers

Create the session cookie on login

Verify the session with a Data Access Layer

Add an optimistic check in proxy.ts

Step 3: Build Database-Backed Sessions

Create the sessions table

Create the session on login

Verify the session (with caching, so it doesn't hit the database on every render)

Revoking a session — the whole point of this approach

Session vs JWT: Side-by-Side

A Closer Look: What "Horizontal Scaling" Actually Means Here

Sliding (Rolling) Sessions

Can You Get Revocation With JWTs?

Which One Should You Actually Use?

Frequently Asked Questions

Can I combine both approaches?

Is storing a JWT in a cookie the same as storing it in localStorage?

Does proxy.ts need to fully verify the session on every request?

Why hash the session token before storing it in the database?

Which one does Auth.js use by default?

Wrapping Up

Continue Learning

Useful Resources

Stop Pasting JWTs Into Random Websites. Here's What I Built Instead.

The Incident That Made Me Stop

What Makes a JWT Decoder Dangerous

The Architecture: Zero-Knowledge Client-Side Decoding

Beyond Decoding: The Signature Verification Problem

The alg: none Attack — Why Your Decoder Needs to Flag This

What I Learned Building Privacy-First Tools

Try It Yourself

Links

# How Authentication Really Works (JWT vs Session vs OAuth)

First: What is Authentication?

⚙️ Basic Flow (Before JWT / Session / OAuth)

1. Session-Based Authentication

How It Works

Flow

✅ Pros

❌ Cons

⚡ 2. JWT (JSON Web Token)

How It Works

Flow

✅ Pros

❌ Cons

3. OAuth (Login with Google, GitHub)

How It Works

Flow

Step 2: Build JWT-Based Auth with `jose`

Add an optimistic check in `proxy.ts`

Does `proxy.ts` need to fully verify the session on every request?

The `alg: none` Attack — Why Your Decoder Needs to Flag This