@jmlq/auth-plugin-jose 🧩

🎯 Objective

@jmlq/auth-plugin-jose is the infrastructure plugin that implements ITokenServicePort from @jmlq/auth using the jose library.

Its real responsibility is:

• generate access tokens and refresh tokens,
• verify signed tokens,
• normalize cryptographic configuration,
• translate technical errors from jose into core-compatible errors.

The recommended entry point is createJoseTokenService(...).

⭐ Importance

This plugin allows the @jmlq/auth core to remain independent from the specific JWT technology.

In practice:

• the core depends on ITokenServicePort,
• this plugin implements that contract,
• the host decides whether to use HS256, RS256, or ES256,
• business logic remains in @jmlq/auth.

🏗️ Architecture (quick view)

• createJoseTokenService(...) validates minimal preconditions and builds JoseTokenService.
• JoseTokenService encapsulates SignJWT, jwtVerify, decodeJwt, importPKCS8, and importSPKI.
• jose-error.mapper.ts translates technical errors into core error codes.
• audience is used only for issuing; it is not passed to jwtVerify during verification.

➡️ See details in: architecture.md

🔧 Implementation

5.1 Installation

npm i @jmlq/auth @jmlq/auth-plugin-jose jose

5.2 Dependencies

Direct dependencies of the package:

• @jmlq/auth
• jose

5.3 Quickstart (quick implementation)

Recommended real usage from infrastructure:

import { createJoseTokenService } from "@jmlq/auth-plugin-jose";

const tokenService = createJoseTokenService(
  {
    keyMaterial: {
      alg: "RS256",
      privateKey: process.env.JWT_PRIVATE_KEY!,
      publicKey: process.env.JWT_PUBLIC_KEY!,
    },
    issuer: process.env.JWT_ISSUER,
    audience: process.env.JWT_AUDIENCE,
    clockSkewSeconds: Number(process.env.JWT_CLOCK_SKEW_SECONDS ?? 5),
    defaultExpiresIn: {
      accessToken: "15m",
      refreshToken: "7d",
    },
  },
  {
    createAuthError,
  },
);

Also valid with HS256:

const tokenService = createJoseTokenService(
  {
    keyMaterial: {
      alg: "HS256",
      secret: process.env.JWT_SECRET!,
    },
    issuer: process.env.JWT_ISSUER,
    audience: process.env.JWT_AUDIENCE,
    defaultExpiresIn: {
      accessToken: "15m",
      refreshToken: "7d",
    },
  },
  { createAuthError },
);

5.4 Environment variables (.env) 📦

The plugin does not read .env directly. The host resolves variables and builds JoseTokenServiceOptions.

Typical variables consistent with this integration:

process.env.JWT_SECRET;
process.env.JWT_PRIVATE_KEY;
process.env.JWT_PUBLIC_KEY;
process.env.JWT_ISSUER;
process.env.JWT_AUDIENCE;
process.env.JWT_CLOCK_SKEW_SECONDS;

5.5 Helpers and key functionalities

createJoseTokenService(...)

Real signature:

createJoseTokenService(
  options: JoseTokenServiceOptions,
  deps: { createAuthError: CreateAuthErrorFn },
)

Real responsibilities:

• validate keyMaterial,
• require createAuthError,
• build a concrete implementation of ITokenServicePort.

JoseTokenServiceOptions

Real public configuration:

export interface JoseTokenServiceOptions {
  keyMaterial: JoseKeyMaterial;
  issuer?: string;
  audience?: string | string[];
  clockSkewSeconds?: number;
  defaultExpiresIn?: {
    accessToken?: string;
    refreshToken?: string;
  };
}

JoseKeyMaterial

type JoseKeyMaterial =
  | { alg: "HS256"; secret: string }
  | { alg: "RS256" | "ES256"; privateKey: string; publicKey: string };

Real cryptographic material validation

The plugin validates:

• HS256 requires secret
• RS256 / ES256 require privateKey and publicKey

Audience: important behavior

Real rule implemented in the plugin:

• audience is used for signing (jwt.setAudience(...))
• audience is not passed to jwtVerify(...)

This prevents turning aud into a mandatory requirement during verification.

✅ Checklist (quick steps)

• Install
• Define keyMaterial according to algorithm
• Build the service with createJoseTokenService
• Integrate it into the host infrastructure
• Verify audience and clock skew rules
• Review troubleshooting

🧩 Implementation Example

• View real integration and documentation

📌 Menu

• Architecture
• Configuration
• Express Integration
• Troubleshooting

🔗 References

• @jmlq/auth

⬅️ 🌐 Ecosystem

• @jmlq