CMS Auth Documentation

Overview

The CMS Auth interface answers one question for the DMS: who is calling. It resolves the bearer token on an HTTP request into a User row, issues and validates the tokens that make such a request possible, records logins as sessions, binds the accounts a user owns on external login providers, and owns the users, sessions and user_external_identities tables together with their models.

It stops at identity. Deciding what an authenticated caller is allowed to do — permissions, roles, tenant membership — belongs to the cms interface, whose tenant guards build on the authenticateRequestUser function documented here.

The surface is published under two subpaths:

Key Features

• Request Authentication Decorators — Gate a route, a controller property, or a whole controller class on a valid bearer token with AuthUser and AuthRawUser, and receive the resolved User.
• Optional Authentication — Serve the same route to signed-in and anonymous callers with IfAuthUser, which injects User | undefined instead of rejecting the request.
• Owner-Only Gate — Restrict administration surfaces to platform owners with AuthOwnerOnly, which answers 403 to an authenticated non-owner.
• Composable Authentication — Build your own parameter providers on authenticateRequestUser, the same primitive the DMS tenant guards start from.
• Token Lifecycle — Issue and validate tenant-scoped access and refresh tokens, plus the short-lived two-factor and tenant-assignment tokens that stand between a password check and a real session.
• Revocable Sessions — Record each login as a Session row carrying its device, IP and current refresh token, so a single session or every session of a user can be revoked.
• User Table and Model — A User table with hashed passwords through HashModifier, and a UserModel with lookups by email and by owner flag.
• External Login Providers — Bind the accounts a user owns on GitHub, Google or any configured provider with linkExternalIdentity, and resolve a provider profile back to a user on the next login.
• Safe Responses — Strip authentication secrets from a user with sanitizeUser before returning it over HTTP.
• Account Emails — Send the second-factor, email-validation, password-reset and invite messages the authentication flows depend on.
• One Registration Path — Run the notifications and the USER_REGISTERED hook through announceRegistration, whichever flow created the account.

Dependencies

This interface relies on the following AntelopeJS packages:

• @antelopejs/interface-auth - CreateAuthDecorator, which builds the authentication decorators from a source, an authenticator and a validator.
• @antelopejs/interface-api - Controllers, RequestContext and HTTPResult, used to read the request and to reject it.
• @antelopejs/interface-database-decorators - Table definitions, the HashModifier mixin, and BasicDataModel for the user and session models.
• @antelopejs/interface-database - Query value proxies used by the owner lookups on UserModel.
• @antelopejs/interface-core - InterfaceFunction, which wires the token, sanitization and mail entry points to their implementation.

Quick Start

The following controller gates a route on an authenticated user and returns the account with its secrets stripped.

import { Controller, Get } from "@antelopejs/interface-api";
import {
  AuthUser,
  sanitizeUser,
} from "@antelopejs-private/cms/interfaces/cms-auth";
import type { User } from "@antelopejs-private/cms/interfaces/cms-auth/db";

export class ProfileController extends Controller("/api/profile") {
  @Get("")
  profile(@AuthUser() user: User): Promise<Partial<User>> {
    // 401 before this line runs when the token is missing or invalid
    return sanitizeUser(user);
  }
}

A client reaches it by sending the access token issued at login in the Authorization header, as Bearer <access token>.

Documentation Sections

• Authentication - Resolve a request to a user with the authentication decorators and authenticateRequestUser
• Tokens and Sessions - Issue and validate access, refresh, two-factor and tenant-assignment tokens, and record login sessions
• Users - The user table and model, password hashing, sanitization, the account mail entry points, and announcing a registration
• External Identities - Bind and read the accounts a user owns on external login providers