Auth

Token Handling

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

Token generation

`SignRaw`

The SignRaw function signs arbitrary data and returns a token string.

import { SignRaw } from "@antelopejs/interface-auth";

const token = await SignRaw(
  { userId: 123, role: "admin" },
  { expiresIn: "1h" },
);

console.log(token); // Signed token string

The function accepts two arguments:

Argument	Type	Description
`data`	`string \| Buffer \| object`	The data to sign
`options`	`SignOptions` (optional)	Signing configuration options

SignRaw returns a Promise<string> that resolves to the signed token.

`SignOptions`

The SignOptions interface configures token generation.

Property	Type	Description
`expiresIn`	`string \| number`	Token expiration time as seconds or a timespan string (e.g., `"1h"`, `"2d"`)
`notBefore`	`string \| number`	Duration before which the token is not valid

`SignServerResponse`

The SignServerResponse function signs data and attaches the resulting token as a cookie on the HTTP response.

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

async function login(res: ServerResponse) {
  const userData = { userId: 123, role: "user" };

  await SignServerResponse(
    res,
    userData,
    { expiresIn: "1h" },
    { httpOnly: true, secure: true, path: "/" },
  );
}

The function accepts four arguments:

Argument	Type	Description
`res`	`ServerResponse`	The HTTP response object
`data`	`string \| Buffer \| object`	The data to sign
`signOptions`	`SignOptions` (optional)	Signing configuration options
`cookieOptions`	`CookieOptions` (optional)	Cookie configuration options

The cookie is set with the name ANTELOPEJS_AUTH and the signed token as its value. The function returns a Promise<ServerResponse> that resolves to the same response object once the cookie header has been set.

`CookieOptions`

The CookieOptions interface configures the authentication cookie.

Property	Type	Description
`maxAge`	`number`	Maximum age in milliseconds
`signed`	`boolean`	Whether the cookie should be signed
`expires`	`Date`	Specific date when the cookie expires
`httpOnly`	`boolean`	Prevents client-side JavaScript from accessing the cookie
`path`	`string`	URL path for which the cookie is valid
`domain`	`string`	Domain for which the cookie is valid
`secure`	`boolean`	Only sends the cookie over HTTPS

Token validation

`ValidateRaw`

The ValidateRaw function verifies a token and returns the data contained within it.

import { ValidateRaw } from "@antelopejs/interface-auth";

try {
  const userData = await ValidateRaw<{ userId: number; role: string }>(token);
  console.log(userData); // { userId: 123, role: "admin" }
} catch (error) {
  console.error("Invalid token:", error.message);
}

The function accepts two arguments:

Argument	Type	Description
`token`	`string` (optional)	The signed token to verify
`options`	`VerifyOptions` (optional)	Verification configuration

`VerifyOptions`

The VerifyOptions interface configures token validation.

Property	Type	Description
`ignoreExpiration`	`boolean`	If `true`, expired tokens are still considered valid
`ignoreNotBefore`	`boolean`	If `true`, tokens not yet valid are accepted
`maxAge`	`string \| number`	Maximum allowed age of the token

Example with verify options

import { ValidateRaw } from "@antelopejs/interface-auth";

// Accept tokens up to 30 minutes old, ignoring the not-before field
const userData = await ValidateRaw(token, {
  maxAge: "30m",
  ignoreNotBefore: true,
});

Authentication Basics

Authentication verifies the identity of users or systems accessing your API. The Interface Auth provides a complete system for token-based authentication with customizable sources, verifiers, and validators.

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.