@antelopejs/interface-auth

The AntelopeJS contract for token authentication. Sign and verify tokens and inject the verified payload into API handlers.

Documentation · Implementations · All interfaces and providers

The AntelopeJS contract for token authentication: sign and verify tokens, and inject the verified payload into API handlers with a decorator.

What it offers

• SignRaw and ValidateRaw sign a payload into a token and verify a token back into its payload.
• SignServerResponse signs a payload and attaches the token to a response as a cookie.
• @Authentication() reads the token from the x-antelopejs-auth header, or from the ANTELOPEJS_AUTH cookie when the header is absent. It verifies the token and injects the payload into a handler parameter.
• CreateAuthDecorator builds your own decorator with a custom source, verifier, and validator.

Implementations

Module	Notes
@antelopejs/auth-jwt	JSON Web Tokens

Install

Add the interface to the module that protects routes:

pnpm add @antelopejs/interface-auth

Then add an implementation to the project, with an implementation of the API interface:

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

Quick start

import { Controller, Get, Post } from "@antelopejs/interface-api";
import { Authentication, SignRaw } from "@antelopejs/interface-auth";

interface Session {
  id: string;
}

export class SessionController extends Controller("/session") {
  @Post("login")
  async login() {
    return SignRaw({ id: "user-7" }, { expiresIn: "1h" });
  }

  @Get("me")
  async me(@Authentication() session: Session) {
    return { id: session.id };
  }
}

A request to GET /session/me without a valid token fails before the handler runs. Send the token unchanged in x-antelopejs-auth, without a Bearer prefix. The login method only shows signing. In a real application, check the credentials before you issue a token.

The Session annotation describes the payload the application expects. It does not check it, so session.id is whatever the verified token carries. Add a shape-checking verifier before you rely on claims from tokens whose format nothing enforces.

Documentation

• Introduction
• Authentication
• Token handling
• Parameter decoration

Compatibility

The module declares these peer dependencies:

Package	Supported	Tested with
@antelopejs/interface-api	>=0.0.15 <1.0.0	0.2.0
@antelopejs/interface-core	>=0.2.4 <1.0.0	0.4.0

Contributing

Read CONTRIBUTING.md before you open a pull request. The local checks are:

pnpm install
pnpm lint
pnpm test

Part of AntelopeJS

AntelopeJS is the TypeScript framework where modules depend on contracts and the application chooses the provider. AntelopeJS DMS is built on it.

Area	Contracts	Providers
API	interface-api · interface-api-util · interface-data-api	api
Auth	interface-auth	auth-jwt
Database	interface-database · interface-database-decorators · interface-database-catalog · interface-mongodb · interface-rethinkdb	postgres · mongodb · rethinkdb
Redis	interface-redis · interface-redis-scheduler	redis
Email	interface-email	nodemailer · brevo
File storage	interface-file-storage	file-storage-local · file-storage-s3
Payments	interface-payment · interface-subscriptions · interface-stripe	stripe · mollie · checkout-com · payment-subscriptions

License

Apache-2.0