JWT

Introduction

JCC Express MVC uses JSON Web Tokens (JWT) as the core auth token package surface.

Primary helpers:

• jwtSign(payload, options?)
• jwtVerify(token)
• jwtTokenType(payload)
• checkJwtAccessTokenPayload(payload)
• jwtSubjectId(payload)

These are exported from jcc-express-mvc (jwtSign, jwtVerify, jwtTokenType, and related helpers).

Basic usage

import { jwtSign, jwtVerify } from "jcc-express-mvc";

const accessToken = jwtSign({ id: 1, typ: "access" }, { expiresIn: "1h" });
const payload = jwtVerify(accessToken);

Token types

The framework distinguishes token kinds by typ:

• access
• refresh
• legacy (when typ is not present)

Auth guards and middleware validate that protected routes receive access-token payloads.

Model-issued tokens (createToken)

JCC Eloquent models can sign JWTs via createToken() when the class sets protected hasToken = true:

const user = await User.find(1);
const token = user.createToken({ id: user.id, typ: "access" });

Clients pass the token to apiAuth as Authorization: Bearer <token>. The middleware verifies the JWT, then uses the payload claims (minus exp, iat, typ) to reload the user from the database.

See Defining Model for setup, payload design, and route examples.

Cookies used by auth

JWTs are typically transported as:

• auth_token (access)
• refresh_token (refresh)

Cookie options are centralized by authSessionCookieOptions() in the util/auth flow.

CLI for secret generation

Generate JWT secret values with:

bun artisanNode key:generate

Useful variants:

bun artisanNode key:generate show
bun artisanNode key:generate JWT_SECRET

Security notes

• JWT signing uses JWT_SECRET
• production safety checks enforce strong secret values
• keep JWT_SECRET private and long enough for production

For full authentication flow (login, refresh, logout), see final-documentation/Security/Authentication.md.