antelopejs/auth-jwt

Official

Authentication and authorization module using JWT tokens

ajs project modules add @antelopejs/auth-jwt

Implementsauth

@antelopejs/auth-jwt

The AntelopeJS authentication module: it signs and verifies the auth interface's tokens as JSON Web Tokens, with jsonwebtoken.

Interfaces

Interface	Documentation
`@antelopejs/interface-auth`	Auth

The @Authentication decorator, custom auth decorators, token sources and cookies are documented on the interface pages. The module also depends on @antelopejs/interface-api, implemented by @antelopejs/api.

Install

ajs project modules add @antelopejs/auth-jwt
ajs project modules install

ajs project modules install adds @antelopejs/api when no module of the project implements the API interface yet.

Configuration

Sign with a shared secret:

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    "auth-jwt": {
      source: {
        type: "package",
        package: "@antelopejs/auth-jwt",
        version: "^1.0.3",
      },
      config: {
        secret: "change-me",
        signOptions: { expiresIn: "1h" },
        verifyOptions: { ignoreExpiration: false },
      },
    },
  },
  envOverrides: {
    JWT_SECRET: "modules.auth-jwt.config.secret",
  },
});

Or with a key pair read from disk at startup:

config: {
  signKey: "./keys/private.pem",
  verifyKey: "./keys/public.pem",
  signOptions: { algorithm: "RS256", expiresIn: "1h" },
  verifyOptions: { algorithms: ["RS256"] },
},

Key	Description
`secret`	Shared secret that signs and verifies tokens. Takes precedence over `signKey` and `verifyKey`.
`signKey`	Path of the private key file. Used with `verifyKey` when `secret` is not set.
`verifyKey`	Path of the public key file.
`signOptions`	Default `jsonwebtoken` sign options. `SignRaw` options override `expiresIn` and `notBefore`.
`verifyOptions`	Default `jsonwebtoken` verify options.

The module refuses to start without secret or both signKey and verifyKey. ajs project modules add writes secret: "your-secret-key": replace it before deploying.

Quick start

In the module that serves the routes, add both interfaces:

pnpm add @antelopejs/interface-api @antelopejs/interface-auth

Issue a token as a cookie, then read it back on a protected route:

import {
  Context,
  Controller,
  Get,
  Post,
  type RequestContext,
} from "@antelopejs/interface-api";
import { Authentication, SignServerResponse } from "@antelopejs/interface-auth";

interface Session {
  userId: string;
}

export class SessionController extends Controller("/session") {
  @Post("/login")
  async login(@Context() context: RequestContext) {
    await SignServerResponse(
      context.rawResponse,
      { userId: "42" },
      { expiresIn: "1h" },
      { httpOnly: true, path: "/" },
    );
    return { ok: true };
  }

  @Get("/me")
  me(@Authentication() session: Session) {
    return session;
  }
}

GET /session/me reads the token from the x-antelopejs-auth header or the ANTELOPEJS_AUTH cookie. It answers 401 when the token is missing and 403 when it is invalid or expired.

Documentation

Auth: the @antelopejs/interface-auth contract this module implements
Configuration: module sources, config blocks and config variables in antelope.config.ts

Compatibility

Package	Supported range
`@antelopejs/interface-auth`	`>=0.0.6 <1.0.0`
`@antelopejs/interface-api`	`>=0.0.13 <1.0.0`
`@antelopejs/interface-core`	`>=0.1.1 <1.0.0`

The module is developed and tested against @antelopejs/core ^1.13.4 on Node.js 24.

Contributing

pnpm install
pnpm dev            # run the playground/ project in watch mode
pnpm lint
pnpm format:check
pnpm knip
pnpm test           # build, then ajs module test

Read the contribution guidelines before opening a pull request.

License

Apache-2.0