Auth

Parameter Decoration

The Interface Auth provides decorators for integrating authentication into API controllers. These decorators extract, verify, and inject authentication data into handler parameters, class properties, and entire controller classes.

The `@Authentication` decorator

The @Authentication decorator retrieves and validates a token from the default sources (header or cookie) and injects the verified payload into the parameter.

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

class UserController extends Controller("/users") {
  @Get("profile")
  async getProfile(@Authentication() user: { id: string; name: string }) {
    return {
      id: user.id,
      name: user.name,
    };
  }
}

If the token is missing or invalid, the request fails with an error response before the handler executes.

Inline validators

Pass a validator function directly to the @Authentication decorator for one-off validation logic.

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

class PaymentController extends Controller("/payments") {
  @Post()
  async createPayment(
    @Authentication((user: any) => {
      if (!user.paymentPermissions) {
        throw new Error("Payment permissions required");
      }
      return user;
    })
    user: any,
  ) {
    // Process payment
    return { success: true };
  }
}

Create custom decorators with `CreateAuthDecorator`

The CreateAuthDecorator function creates a reusable authentication decorator with custom source, authenticator, and validator functions.

import { CreateAuthDecorator } from "@antelopejs/interface-auth";
import type { IncomingMessage } from "node:http";

// Admin-only decorator
export const AdminAuth = CreateAuthDecorator({
  validator: (user: any) => {
    if (!user || user.role !== "admin") {
      throw new Error("Admin access required");
    }
    return user;
  },
});

// API key decorator with custom source and authenticator
export const ApiKeyAuth = CreateAuthDecorator({
  source: (req: IncomingMessage) => req.headers["x-api-key"] as string,
  authenticator: async (apiKey?: string) => {
    if (!apiKey) return null;
    const user = await validateApiKey(apiKey);
    return user;
  },
});

`CreateAuthDecorator` options

The function accepts an object with the following properties:

Property	Type	Description
`source`	`AuthSource`	Extracts the token from the request (defaults to header/cookie)
`authenticator`	`AuthVerifier<T>`	Verifies the token and returns the payload
`authenticatorOptions`	`VerifyOptions`	Options passed to the authenticator
`validator`	`AuthValidator<T, R>`	Validates and transforms the authenticated data

All properties are optional. When omitted, the default behavior is used.

Class-level authentication

The @Authentication decorator can be applied to an entire controller class. This ensures that all routes within that controller require authentication, without decorating each handler individually.

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

@Authentication()
class UserController extends Controller("/users") {
  @Get("profile")
  async getProfile() {
    // Only authenticated users can access this endpoint
    return { message: "Authenticated profile access" };
  }

  @Post("settings")
  async updateSettings() {
    // This route is also protected
    return { success: true };
  }
}

Class-level with role-based access

Combine class-level authentication with a validator to enforce role-based access for all routes in a controller.

import { Controller } from "@antelopejs/interface-api";
import { Authentication } from "@antelopejs/interface-auth";

@Authentication((user: any) => {
  if (!user || user.role !== "admin") {
    throw new Error("Admin access required");
  }
  return user;
})
class AdminController extends Controller("/admin") {
  // All routes require admin authentication
}

Property-level authentication

Apply @Authentication to a class property to access the authenticated user data throughout the controller. The property is populated automatically for each request.

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

class UserController extends Controller("/users") {
  @Authentication()
  private user!: { id: string; name: string };

  @Get("profile")
  async getProfile() {
    return {
      id: this.user.id,
      name: this.user.name,
    };
  }

  @Get("settings")
  async getSettings() {
    // The same user data is available in all handlers
    return { userId: this.user.id, theme: "dark" };
  }
}

Decorator scope summary

The @Authentication decorator (and any custom decorator created with CreateAuthDecorator) can be applied at three levels:

Scope	Effect
Parameter	Injects the verified payload into a single handler parameter
Property	Populates a class property with the verified payload for all handlers
Class	Requires authentication for every route in the controller

Token Handling

The Interface Auth provides functions for generating and validating authentication tokens. These functions serve as the foundation for the authentication system.

Interface Core Documentation