@antelopejs/interface-auth

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

Part of AntelopeJS, the TypeScript framework where modules depend on contracts and the application chooses the provider. Built by the team behind AntelopeJS DMS.

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

License

Apache-2.0