Encryption

Introduction

JCC Express MVC currently provides token cryptography (JWT signing/verification) rather than a general-purpose encrypt() / decrypt() string helper.

Main primitives live in jcc-express-mvc/lib/util/index.ts:

• jwtSign(payload, options?)
• jwtVerify(token)
• jwtTokenType(payload) (access / refresh / legacy)
• checkJwtAccessTokenPayload(payload)
• jwtSubjectId(payload)

JWT signing and verification

Implementation details:

• algorithm: HS256
• secret: JWT_SECRET
• verification includes clockTolerance: 30

Access vs refresh token typing

The framework distinguishes JWT kinds by typ claim:

• access tokens -> typ: "access"
• refresh tokens -> typ: "refresh"

Auth middleware uses checkJwtAccessTokenPayload(...) to reject refresh tokens on protected routes.

When JWT_REQUIRE_TYPED_TOKENS=true, legacy tokens (without typ) can be rejected.

Cookie transport for auth tokens

Auth cookies are set with shared options from authSessionCookieOptions():

• httpOnly: true
• sameSite: "lax"
• secure: APP_ENV === "production"
• path /

Used for:

• auth_token (access)
• refresh_token (refresh)

See Security/Authentication.md for full login/refresh/logout behavior.

Generating strong secrets

Use CLI key generation:

By default it writes a 32-byte random hex secret to JWT_SECRET in .env.

Useful variants:

Production safety checks

At bootstrap, assertProductionJwtSecret() enforces:

• JWT_SECRET length >= 32 chars in production
• not the default placeholder (app-generated-key)

If invalid, app startup throws a security error.

Important note

There is no built-in symmetric data encryption API (for example encrypt(text) / decrypt(text)) in the current framework code. If you need encrypted-at-rest fields or custom payload encryption, add a dedicated utility/service on top of Node crypto.

Summary

• Framework encryption surface is JWT signing + verification.
• Token typing (access vs refresh) is enforced in auth flow.
• Use key:generate and strong JWT_SECRET values for production safety.