@antelopejs/interface-auth 0.0.4 → 0.0.6

package/docs/1.introduction.md

@@ -0,0 +1,27 @@
+# Interface Auth Documentation
+
+## Overview
+
+The Interface Auth provides a decorator-based framework for implementing authentication and authorization in TypeScript applications. It offers token signing, verification, and flexible parameter decorators for securing API endpoints.
+
+This interface depends on the [Interface API](https://github.com/AntelopeJS/interface-api) package, which provides the decorator infrastructure for parameter injection.
+
+## Core concepts
+
+The authentication system is built around three main layers:
+
+- **Token handling** - Sign and verify authentication tokens using `SignRaw`, `ValidateRaw`, and `SignServerResponse`.
+- **Authentication decorators** - The `@Authentication` decorator and `CreateAuthDecorator` function inject verified user data into handler parameters.
+- **Customizable pipeline** - Configure custom sources, verifiers, and validators to adapt the authentication flow.
+
+## Installation
+
+```bash
+npm install @antelopejs/interface-auth
+```
+
+## Documentation sections
+
+- [Authentication Basics](./2.authentication.md) - Authentication flow, sources, verifiers, and validators
+- [Token Handling](./3.token-handling.md) - Token generation and validation functions
+- [Parameter Decoration](./4.parameter-decoration.md) - Authentication decorators and custom providers

package/docs/2.authentication.md

@@ -0,0 +1,169 @@
+# 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.
+
+## Authentication flow
+
+A typical authentication flow consists of four steps:
+
+1. **Token generation** - Sign user data into a token using `SignRaw` or `SignServerResponse`.
+2. **Token storage** - Store the token on the client (cookie, header, local storage).
+3. **Token validation** - Verify the token when the client makes a request.
+4. **Authorization** - Check whether the authenticated user has permission to access the requested resource.
+
+### Example authentication flow
+
+```typescript
+import { SignRaw, Authentication } from "@antelopejs/interface-auth";
+import { Controller, Post, Get, JSONBody, HTTPResult } from "@antelopejs/interface-api";
+
+class UserController extends Controller("/users") {
+  @Post("login")
+  async login(@JSONBody() credentials: { email: string; password: string }) {
+    // Validate credentials against your data store
+    const user = await validateUserCredentials(credentials);
+
+    // Step 1: Generate a token
+    const token = await SignRaw(
+      { userId: user.id, role: user.role },
+      { expiresIn: "1h" },
+    );
+
+    // Step 2: Return token to the client
+    const result = new HTTPResult(200, {
+      success: true,
+      user: { id: user.id, role: user.role },
+    });
+
+    result.addHeader(
+      "Set-Cookie",
+      `ANTELOPEJS_AUTH=${token}; HttpOnly; Path=/`,
+    );
+
+    return result;
+  }
+
+  @Get("profile")
+  async getProfile(
+    @Authentication() userData: { userId: number; role: string },
+  ) {
+    // Steps 3 & 4: Token is automatically validated
+    // If the token is invalid, an error is thrown before this code runs
+    return { user: await getUserProfile(userData.userId) };
+  }
+}
+```
+
+## Authentication sources
+
+An `AuthSource` function extracts the authentication token from the incoming HTTP request. The default source checks two locations in order:
+
+1. **Custom header** - The `x-antelopejs-auth` header
+2. **Cookie** - The `ANTELOPEJS_AUTH` cookie
+
+### Create a custom source
+
+Implement the `AuthSource` type to extract tokens from a different location.
+
+```typescript
+import { CreateAuthDecorator, AuthSource } from "@antelopejs/interface-auth";
+import type { IncomingMessage } from "node:http";
+
+const bearerTokenSource: AuthSource = (req: IncomingMessage) => {
+  const header = req.headers.authorization;
+  if (header?.startsWith("Bearer ")) {
+    return header.slice(7);
+  }
+  return undefined;
+};
+
+const BearerAuth = CreateAuthDecorator({
+  source: bearerTokenSource,
+});
+```
+
+The `AuthSource` type signature is:
+
+```typescript
+type AuthSource = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => string | undefined;
+```
+
+## Authentication verifiers
+
+An `AuthVerifier` function validates the token and extracts its payload. The default verifier uses `ValidateRaw`, which delegates to the underlying token verification implementation (typically JWT).
+
+### Create a custom verifier
+
+```typescript
+import { CreateAuthDecorator, AuthVerifier } from "@antelopejs/interface-auth";
+
+const base64Verifier: AuthVerifier<{ userId: string }> = (data?: string) => {
+  if (!data) {
+    throw new Error("No authentication data provided");
+  }
+  try {
+    const decoded = Buffer.from(data, "base64").toString("utf-8");
+    return JSON.parse(decoded);
+  } catch {
+    throw new Error("Invalid authentication data");
+  }
+};
+
+const Base64Auth = CreateAuthDecorator({
+  authenticator: base64Verifier,
+});
+```
+
+The `AuthVerifier` type signature is:
+
+```typescript
+type AuthVerifier<T = unknown> = (
+  data?: string,
+  options?: VerifyOptions,
+) => Promise<T> | T;
+```
+
+## Authentication validators
+
+An `AuthValidator` function performs additional checks on the verified data. Validators run after the verifier and can transform the result or throw an error to reject the request.
+
+```typescript
+import { CreateAuthDecorator, AuthValidator } from "@antelopejs/interface-auth";
+
+interface UserPayload {
+  userId: number;
+  role: string;
+}
+
+const adminValidator: AuthValidator<UserPayload, UserPayload> = (userData) => {
+  if (!userData || userData.role !== "admin") {
+    throw new Error("Admin access required");
+  }
+  return userData;
+};
+
+const AdminOnly = CreateAuthDecorator({
+  validator: adminValidator,
+});
+```
+
+The `AuthValidator` type signature is:
+
+```typescript
+type AuthValidator<T = unknown, R = unknown> = (
+  data: T,
+) => Promise<R> | R;
+```
+
+## Authentication pipeline
+
+The complete authentication pipeline processes the request through three stages:
+
+```
+source(req, res) => authenticator(token, options) => validator(data) => Parameter
+```
+
+Each stage is optional and falls back to the default behavior when not specified. The `source` extracts the token, the `authenticator` verifies it, and the `validator` performs any additional checks before the data is injected into the handler parameter.

package/docs/3.token-handling.md

@@ -0,0 +1,129 @@
+# 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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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,
+});
+```

package/docs/4.parameter-decoration.md

@@ -0,0 +1,172 @@
+# 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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-auth",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "AntelopeJS interface for JWT authentication and session management",
   "keywords": [
     "antelopejs",
@@ -17,7 +17,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -35,11 +37,9 @@
     "release": "pnpm run lint && pnpm run prepack && release-it",
     "test": "pnpm run build && ajs module test ."
   },
-  "dependencies": {
-    "@antelopejs/interface-api": "^0.0.3",
-    "@antelopejs/interface-core": "^0.0.3"
-  },
   "devDependencies": {
+    "@antelopejs/interface-api": "^0.0.5",
+    "@antelopejs/interface-core": "^0.0.5",
     "@biomejs/biome": "2.3.2",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
@@ -52,10 +52,17 @@
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "@antelopejs/interface-api": ">=0.0.3 <1.0.0",
+    "@antelopejs/interface-core": ">=0.0.3 <1.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },
   "antelopeJs": {
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }

package/skills/auth-interface/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: auth-interface
+description: AntelopeJS interface for token-based authentication - signing and verifying auth tokens (SignRaw, ValidateRaw, SignServerResponse) and injecting the verified payload into interface-api controllers via the @Authentication decorator or custom decorators from CreateAuthDecorator. Use when code imports "@antelopejs/interface-auth", when securing controller routes, generating or validating auth/JWT tokens, injecting authenticated user data into handler parameters, or when implementing an auth provider for internal.Verify/internal.Sign.
+category: antelopejs-interface
+tags: [antelopejs, auth, jwt, tokens, decorators]
+---
+
+# @antelopejs/interface-auth
+
+Token authentication for AntelopeJS modules. Two layers:
+
+- **Proxy crossings** (need a provider module loaded, e.g. a JWT module): `internal.Verify` and `internal.Sign`, wrapped by `SignRaw`, `ValidateRaw`, and `SignServerResponse`. Always async.
+- **Consumer-side helpers** (no crossing by themselves): `Authentication` and `CreateAuthDecorator`, which build parameter providers on top of `@antelopejs/interface-api`.
+
+## Imports
+
+All symbols come from the package root (the exports map exposes no other code subpaths):
+
+```ts
+import {
+  Authentication, CreateAuthDecorator,
+  SignRaw, ValidateRaw, SignServerResponse,
+  internal, // provider side only
+  type AuthSource, type AuthVerifier, type AuthValidator,
+  type SignOptions, type VerifyOptions, type CookieOptions,
+} from "@antelopejs/interface-auth";
+```
+
+`@antelopejs/interface-api` and `@antelopejs/interface-core` are peerDependencies — the consuming module must have them installed.
+
+## Consuming
+
+```ts
+import { Controller, Get, Post } from "@antelopejs/interface-api";
+import { Authentication, SignRaw } from "@antelopejs/interface-auth";
+
+interface LibrarianSession { id: string; branch: string; }
+
+class LibrarianController extends Controller("/librarians") {
+  @Post("login")
+  async login() {
+    // Sign a payload into a token (proxy call to the auth provider)
+    return SignRaw({ id: "lib-7", branch: "riverside" }, { expiresIn: "1h" });
+  }
+
+  @Get("desk")
+  async getDesk(@Authentication() librarian: LibrarianSession) {
+    // Token was read from the request, verified, and injected
+    return { id: librarian.id, branch: librarian.branch };
+  }
+}
+```
+
+Custom pipelines use `CreateAuthDecorator({ source?, authenticator?, authenticatorOptions?, validator? })`; the callbacks run as `source(req, res)` → `authenticator(data, authenticatorOptions)` → `validator(data)` → injected parameter.
+
+## Providing
+
+An auth backend module implements the two proxy points:
+
+```ts
+import { ImplementInterface } from "@antelopejs/interface-core";
+import { internal } from "@antelopejs/interface-auth";
+
+ImplementInterface(internal, {
+  Verify: (token, options) => decodeAndVerify(token, options), // return payload, throw on invalid
+  Sign: (data, options) => signToken(data, options),           // return token string
+});
+```
+
+Declare `"antelopeJs": { "implements": ["@antelopejs/interface-auth"] }` in the provider's package.json.
+
+## Gotchas
+
+- `SignRaw` / `ValidateRaw` / `SignServerResponse` are interface proxy calls: they return Promises and only resolve once a provider module is attached. While a provider module is loaded but not yet attached, earlier calls are queued, not failed — always `await`. But when no loaded module provides the interface (e.g. a stubbed `optionalDependencies` entry), the core neutralizes the proxies and those calls reject instead of queuing.
+- Default token source (`internal.defaultSource`): the `x-antelopejs-auth` request header, falling back to the `ANTELOPEJS_AUTH` cookie. `SignServerResponse` sets that same cookie via `Set-Cookie`.
+- `@Authentication(validator?)` accepts an optional validator at the use site; it overrides any validator configured in `CreateAuthDecorator`.
+- Decorators from `CreateAuthDecorator` (including `Authentication`) apply to parameters, properties, and whole classes (class-level registers a provider for the controller) — NOT to methods; decorating a method silently registers nothing and can break other parameter decorators on that handler.
+- `expiresIn` / `notBefore` (SignOptions) and `maxAge` (VerifyOptions) accept a number of seconds or a timespan string such as `"1h"`.
+- Rejection is exception-based: a failed verification or validator throws, it does not return `undefined`.
+
+## Deeper reference
+
+See this package's `docs/` chapters — Introduction, Authentication Basics, Token Handling, Parameter Decoration — and the shipped `dist/index.d.ts` for full TSDoc signatures. Do not duplicate them here.