@antelopejs/auth-jwt

The AntelopeJS authentication module. It implements @antelopejs/interface-auth and signs and verifies its tokens as JSON Web Tokens with jsonwebtoken.

Part of AntelopeJS. Used by AntelopeJS DMS, the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.

Interfaces

The interface pages document the @Authentication decorator, custom auth decorators, token sources, and cookies. The module also depends on @antelopejs/interface-api, which @antelopejs/api implements.

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: "^2.0.0",
      },
      config: {
        secret: "change-me",
        signOptions: { expiresIn: "1h" },
        verifyOptions: { ignoreExpiration: false },
      },
    },
  },
  envOverrides: {
    JWT_SECRET: "modules.auth-jwt.config.secret",
  },
});

When the JWT_SECRET environment variable is set, envOverrides writes its value into secret.

To sign with a key pair instead, give the paths of the two key files. The module reads both files when it constructs.

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

The module refuses to start without secret or both signKey and verifyKey, and throws Invalid JWT config. ajs project modules add writes secret: "your-secret-key". Replace it before you deploy.

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 from the ANTELOPEJS_AUTH cookie when the header is absent. It answers 401 when the token is missing. It answers 403 when the token is invalid or expired, or when its payload is neither a string nor a JSON object, such as an array or a number.

Documentation

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

Compatibility

The generated table lists the interface packages and ranges this module loads, read from package.json.

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