Token Handling

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" },
);

// Return the token through your chosen authentication transport.

The function accepts two arguments:

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

SignOptions

The SignOptions interface configures token generation.

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:

The cookie is set with the name ANTELOPEJS_AUTH and the signed token as its value. The function replaces the response's existing Set-Cookie header and returns a Promise<ServerResponse> that resolves to the same response object once the header has been set. It does not send or end the response.

CookieOptions

The CookieOptions interface supplies attributes to the authentication cookie. The current serializer writes keys literally, omits false and undefined, writes true as a standalone directive, and converts other values with String(value).

Do not rely on maxAge, signed, or expires for browser lifetime or extra signing guarantees in this implementation. Use a standards-compliant cookie serializer when those features are required, and keep token expiration in SignOptions. No cookie attributes are added by default.

CookieOptions has no sameSite field. If your deployment requires SameSite, serialize the cookie yourself and set the response header, as in the authentication flow. Do not cast unsupported options into this type.

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 instanceof Error ? error.message : String(error),
  );
}

The function accepts two arguments:

VerifyOptions

The VerifyOptions interface configures token validation.

Example with verify options

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

// Limit token age without bypassing expiration or not-before checks.
const userData = await ValidateRaw(token, {
  maxAge: "30m",
});

Leave ignoreExpiration and ignoreNotBefore unset for normal authentication. They deliberately bypass time checks; use them only when you have a separate, explicit policy for accepting such tokens. A successful ValidateRaw<T> verifies the token through your provider but does not validate the payload against T at runtime.