const token = localStorage.getItem("access_token");
const payload = jwtDecode(token);

if (payload.role === "admin") {
  showAdminButton();
}

Decode     -> parse token structure
Validate   -> prove token integrity and acceptability
Authorize  -> decide whether a subject may perform an action on a resource

What does this token say?

Was this token legitimately issued, still acceptable, and intended for this recipient?

Given current state, may this subject perform this action on this resource?

header.payload.signature

import { jwtDecode } from "jwt-decode";

type AccessTokenClaims = {
  iss?: string;
  sub?: string;
  aud?: string | string[];
  exp?: number;
  iat?: number;
  nbf?: number;
  scope?: string;
  tenant_id?: string;
  org_id?: string;
};

export function decodeAccessTokenUnsafe(token: string): AccessTokenClaims | null {
  try {
    return jwtDecode<AccessTokenClaims>(token);
  } catch {
    return null;
  }
}

Decode success != valid token
Decode success != active session
Decode success != current permission
Decode success != allowed action

type RefreshPlan =
  | { kind: "refresh-at"; epochMs: number }
  | { kind: "refresh-now" }
  | { kind: "unknown" };

export function planRefreshFromDecodedExp(
  claims: { exp?: number } | null,
  options: {
    serverTimeOffsetMs: number;
    refreshBeforeMs: number;
  }
): RefreshPlan {
  if (!claims?.exp) return { kind: "unknown" };

  const serverNowMs = Date.now() + options.serverTimeOffsetMs;
  const expiresAtMs = claims.exp * 1000;
  const refreshAtMs = expiresAtMs - options.refreshBeforeMs;

  if (refreshAtMs <= serverNowMs) {
    return { kind: "refresh-now" };
  }

  return { kind: "refresh-at", epochMs: refreshAtMs };
}

Decoded expiry may trigger refresh early.
Server response remains authoritative.

preferred_username
picture
locale
name

Useful for reducing flicker.
Not authoritative for business logic.

export function DevTokenInspector({ token }: { token: string | null }) {
  if (process.env.NODE_ENV === "production") return null;
  if (!token) return null;

  const claims = decodeAccessTokenUnsafe(token);

  return (
    <details>
      <summary>Decoded token claims</summary>
      <pre>{JSON.stringify(redactClaims(claims), null, 2)}</pre>
    </details>
  );
}

function redactClaims(claims: unknown) {
  if (!claims || typeof claims !== "object") return claims;

  const copy = { ...(claims as Record<string, unknown>) };
  delete copy.email;
  delete copy.phone_number;
  delete copy.address;
  return copy;
}

If token says tenant_id = A,
avoid immediately rendering tenant B layout while /session is loading.

Decoded claim -> provisional state
/session response -> committed state

function DeleteCaseButton({ caseId }: { caseId: string }) {
  const token = useAccessToken();
  const claims = token ? jwtDecode<{ role?: string }>(token) : null;

  if (claims?.role !== "admin") return null;

  return <button onClick={() => deleteCase(caseId)}>Delete</button>;
}

function DeleteCaseButton({ caseId }: { caseId: string }) {
  const permission = useCan({ action: "case.delete", resource: { type: "case", id: caseId } });

  if (permission.status === "loading") return null;
  if (!permission.allowed) return null;

  return <button onClick={() => deleteCase(caseId)}>Delete</button>;
}

DELETE /cases/:caseId
  -> authenticate request
  -> resolve subject
  -> load case
  -> verify tenant boundary
  -> evaluate policy case.delete
  -> write audit event
  -> delete or deny

scope = "read:cases write:cases"

subject.role
subject.tenant
case.owner
case.status
case.confidentiality
case.assignedTeam
case.region
currentTime
approvalState
regulatoryHold

ID token exists -> user is logged into my app -> user may access resources

ID token or auth code proves identity flow completed.
Application server establishes app session.
Application session controls app access.

GET /session

{
  "authenticated": true,
  "user": {
    "id": "usr_123",
    "displayName": "Ari"
  },
  "activeTenant": {
    "id": "tenant_456",
    "name": "Regulatory Ops"
  },
  "assurance": {
    "level": "mfa",
    "expiresAt": "2026-07-08T09:30:00Z"
  }
}

Token tenant_id = tenant_a
Request URL = /tenants/tenant_b/cases/123

// Bad
console.log("claims", jwtDecode(token));

// Less bad, still dev-only
logger.debug("token_exp", { exp: claims.exp, aud: claims.aud });

Decode more claims.

Ask the backend for the exact projection the frontend needs.

type SessionProjection =
  | {
      status: "anonymous";
    }
  | {
      status: "authenticated";
      user: {
        id: string;
        displayName: string;
        avatarUrl?: string;
      };
      activeTenant: {
        id: string;
        name: string;
      };
      assurance: {
        level: "password" | "mfa" | "phishing-resistant";
        stepUpRequiredFor: string[];
      };
      expiresAt: string;
    };

GET /session

{
  "status": "authenticated",
  "user": {
    "id": "usr_123",
    "displayName": "Maya Putri"
  },
  "activeTenant": {
    "id": "tnt_001",
    "name": "Financial Conduct"
  },
  "assurance": {
    "level": "mfa",
    "stepUpRequiredFor": ["payment.approve", "case.delete"]
  },
  "expiresAt": "2026-07-08T09:30:00Z"
}

Bad:
  Any component can decode and branch on claims.

Better:
  Only auth/session module can decode.
  It exposes safe derived values.

// auth/tokenClaims.ts
import { jwtDecode } from "jwt-decode";

export type RawJwtClaims = {
  iss?: string;
  sub?: string;
  aud?: string | string[];
  exp?: number;
  iat?: number;
  nbf?: number;
  scope?: string;
  tenant_id?: string;
};

export type TokenDiagnostics = {
  issuer?: string;
  audience?: string | string[];
  expiresAt?: string;
  issuedAt?: string;
  tenantHint?: string;
};

export function decodeClaimsForAuthModuleOnly(token: string): RawJwtClaims | null {
  try {
    return jwtDecode<RawJwtClaims>(token);
  } catch {
    return null;
  }
}

export function toTokenDiagnostics(claims: RawJwtClaims | null): TokenDiagnostics {
  return {
    issuer: claims?.iss,
    audience: claims?.aud,
    expiresAt: claims?.exp ? new Date(claims.exp * 1000).toISOString() : undefined,
    issuedAt: claims?.iat ? new Date(claims.iat * 1000).toISOString() : undefined,
    tenantHint: claims?.tenant_id,
  };
}

Rule:
  jwtDecode may only be imported inside src/auth/**

// eslint.config.js
export default [
  {
    rules: {
      "no-restricted-imports": [
        "error",
        {
          paths: [
            {
              name: "jwt-decode",
              message: "Decode tokens only inside src/auth. Use session and permission APIs in components.",
            },
          ],
        },
      ],
    },
  },
];

import { z } from "zod";

const AccessTokenClaimSchema = z.object({
  iss: z.string().optional(),
  sub: z.string().optional(),
  aud: z.union([z.string(), z.array(z.string())]).optional(),
  exp: z.number().int().positive().optional(),
  iat: z.number().int().positive().optional(),
  nbf: z.number().int().positive().optional(),
  scope: z.string().optional(),
  tenant_id: z.string().optional(),
});

export function parseDecodedClaims(value: unknown) {
  const result = AccessTokenClaimSchema.safeParse(value);
  return result.success ? result.data : null;
}

The decoded object has the expected shape.

The token signature is valid.
The issuer is trusted.
The audience matches.
The token is unexpired.
The session is active.
The user still has permission.

Token claims are not fresh enough for fine-grained authorization.

If a wrong answer creates only a temporary visual glitch, decoded claims may be acceptable.
If a wrong answer exposes sensitive data or enables mutation, decoded claims are not acceptable.

<AuthContext.Provider value={{ user: jwtDecode(token) }}>
  {children}
</AuthContext.Provider>

AuthContext.user.role
AuthContext.user.groups
AuthContext.user.scope
AuthContext.user.tenant_id
AuthContext.user.email

type AuthContextValue = {
  session: SessionProjection;
  refreshSession: () => Promise<void>;
  logout: () => Promise<void>;
};

type PermissionContextValue = {
  can: (input: PermissionInput) => PermissionDecision;
  refreshPermissions: () => Promise<void>;
};

import { createContext, useContext } from "react";

export type AuthSession =
  | { status: "loading" }
  | { status: "anonymous" }
  | {
      status: "authenticated";
      user: {
        id: string;
        displayName: string;
      };
      activeTenant: {
        id: string;
        name: string;
      };
      expiresAt: string;
    }
  | { status: "expired" }
  | { status: "error"; recoverable: boolean };

type AuthContextValue = {
  session: AuthSession;
  refresh: () => Promise<void>;
  logout: () => Promise<void>;
};

const AuthContext = createContext<AuthContextValue | null>(null);

export function useAuth() {
  const value = useContext(AuthContext);
  if (!value) throw new Error("useAuth must be used inside AuthProvider");
  return value;
}

raw token
raw decoded claims
role string from JWT
permission decision based on JWT

const claims = jwtDecode(token);
return claims.exp > Date.now() / 1000 ? <Outlet /> : <Navigate to="/login" />;

export async function protectedLoader({ request }: LoaderFunctionArgs) {
  const session = await getSessionFromServer(request);

  if (session.status === "anonymous") {
    throw redirect(`/login?returnTo=${encodeURIComponent(new URL(request.url).pathname)}`);
  }

  if (session.status !== "authenticated") {
    throw new Response("Session unavailable", { status: 503 });
  }

  return { session };
}

async function restoreSession(): Promise<AuthSession> {
  const response = await fetch("/session", {
    credentials: "include",
    headers: { Accept: "application/json" },
  });

  if (response.status === 401) return { status: "anonymous" };
  if (!response.ok) return { status: "error", recoverable: true };

  return response.json();
}

Session identity    -> Who is interacting with the app?
Permission contract -> What actions should UI expose?
Enforcement policy  -> What does the backend allow now?

{
  "resource": {
    "type": "case",
    "id": "case_123"
  },
  "actions": {
    "case.view": {
      "allowed": true
    },
    "case.assign": {
      "allowed": false,
      "reason": "CASE_LOCKED"
    },
    "case.close": {
      "allowed": false,
      "reason": "REQUIRES_SUPERVISOR_REVIEW"
    }
  }
}

function CaseActions({ caseId }: { caseId: string }) {
  const permissions = useCasePermissions(caseId);

  if (permissions.status !== "ready") return null;

  return (
    <ActionBar>
      {permissions.can("case.assign") && <AssignButton caseId={caseId} />}
      {permissions.can("case.close") && <CloseCaseButton caseId={caseId} />}
    </ActionBar>
  );
}

jwt.role
jwt.scope
jwt.groups

export function isAdmin(token: string): boolean {
  const claims = jwtDecode<{ role?: string }>(token);
  return claims.role === "admin";
}

export function getTokenExpiryHint(token: string): Date | null;
export function getTokenDiagnostics(token: string): TokenDiagnostics;
export function getProvisionalTenantHint(token: string): string | null;

isLoggedIn
isAdmin
hasScope
canEdit
canDelete
canApprove

type DecodeResult<T> =
  | { ok: true; claims: T }
  | { ok: false; reason: "missing" | "malformed" };

export function safeDecodeToken<T>(token: string | null): DecodeResult<T> {
  if (!token) return { ok: false, reason: "missing" };

  try {
    return { ok: true, claims: jwtDecode<T>(token) };
  } catch {
    return { ok: false, reason: "malformed" };
  }
}

Malformed token
  -> clear in-memory token
  -> attempt session refresh if refresh channel exists
  -> otherwise mark session anonymous/expired
  -> do not render protected data

Security-sensitive UI should be backed by server-issued UI authorization data.

{
  "sub": "usr_123",
  "email": "maya@example.com",
  "roles": ["admin", "case_manager", "auditor"],
  "groups": ["group_a", "group_b", "group_c"],
  "permissions": [
    "case.create",
    "case.update",
    "case.delete",
    "case.assign",
    "report.export",
    "tenant.manage"
  ],
  "tenants": ["tenant_a", "tenant_b", "tenant_c"]
}

Token carries minimal credential claims.
/session returns minimal session projection.
/permissions returns app-specific permission decisions.
Resource APIs enforce current policy.

iss
sub
aud
exp
iat
nbf
jti or token id when appropriate
scope if using OAuth resource scopes

email
phone
name
picture
tenant list
group list
role list
permission list
regulatory attributes
case assignment data

it("returns null for malformed token", () => {
  expect(decodeAccessTokenUnsafe("not-a-jwt")).toBeNull();
});

it("plans proactive refresh before token expiry", () => {
  const claims = { exp: 1000 };

  const plan = planRefreshFromDecodedExp(claims, {
    serverTimeOffsetMs: 0,
    refreshBeforeMs: 30_000,
  });

  expect(plan.kind).toBe("refresh-at");
});

src/auth/**        allowed
src/components/**  forbidden
src/features/**    forbidden except auth diagnostics

Given token role=admin
And server permission says case.delete=false
Then Delete button is hidden or disabled
And DELETE /cases/:id still returns 403

Client-side token decoding checklist:

[ ] Is token decoding isolated inside auth/session infrastructure?
[ ] Are business components prevented from importing jwtDecode directly?
[ ] Is decoded data used only as hint, diagnostic, or refresh scheduling input?
[ ] Are role/scope/group claims not used as enforcement authority?
[ ] Are tenant claims not used to enforce tenant boundary?
[ ] Is /session or equivalent used for committed session state?
[ ] Is /permissions or loader data used for security-sensitive UI exposure?
[ ] Does backend still authorize every protected read/write?
[ ] Are decoded claims excluded from logs, analytics, and error breadcrumbs?
[ ] Are malformed tokens handled without rendering protected content?
[ ] Are stale-claim scenarios tested?
[ ] Is token payload minimal and free of unnecessary PII?

Decode for hints.
Validate at trust boundary.
Authorize at resource boundary.
Audit at mutation boundary.