@antelopejs/interface-auth 0.0.7 → 0.2.0

package/dist/tests/index.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":";;AAAA,+BAA8B;AAC9B,6DAAuD;AACvD,0BAA0C;AAc1C,MAAM,SAAS,GAAc;IAC3B,OAAO,EAAE;QACP,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,eAAe;QACtB,QAAQ,EAAE,uBAAuB;KAClC;IACD,SAAS,EAAE;QACT,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,iBAAiB;QACxB,QAAQ,EAAE,uBAAuB;KAClC;CACF,CAAC;AAEF,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,oBAAoB,EAAE,KAAK,IAAI,EAAE;QAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC;QACnC,MAAM,KAAK,GAAG,MAAM,IAAA,WAAO,EAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,MAAM,YAAY,GAAG,MAAM,IAAA,eAAW,EAAC,KAAK,CAAC,CAAC;QAE9C,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/D,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,YAAY,GAAG,mBAAmB,CAAC;QAEzC,IAAI,CAAC;YACH,MAAM,IAAA,eAAW,EAAC,YAAY,CAAC,CAAC;YAChC,aAAM,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAA,aAAM,EAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,0BAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC;QACnC,MAAM,KAAK,GAAG,MAAM,IAAA,WAAO,EAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAE5D,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,MAAM,IAAA,eAAW,EAAC,KAAK,CAAC,CAAC;YACzB,aAAM,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAA,aAAM,EAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,0BAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/tests/local-build.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/local-build.test.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const node_http_1 = require("node:http");
+const node_net_1 = require("node:net");
+const interface_core_1 = require("@antelopejs/interface-core");
+const __1 = require("..");
+const signedToken = "signed-token";
+const signCalls = [];
+const verifyCalls = [];
+let verifyOutcome;
+function requestWith(headers) {
+    const request = new node_http_1.IncomingMessage(new node_net_1.Socket());
+    Object.assign(request.headers, headers);
+    return request;
+}
+function newResponse() {
+    return new node_http_1.ServerResponse(new node_http_1.IncomingMessage(new node_net_1.Socket()));
+}
+function resetProviderState() {
+    signCalls.length = 0;
+    verifyCalls.length = 0;
+    verifyOutcome = () => ({});
+}
+function implementProviders() {
+    (0, interface_core_1.ImplementInterface)({ Sign: __1.internal.Sign, Verify: __1.internal.Verify }, {
+        Sign: async (...args) => {
+            signCalls.push(args);
+            return signedToken;
+        },
+        Verify: async (...args) => {
+            verifyCalls.push(args);
+            return verifyOutcome();
+        },
+    });
+}
+describe("Auth interface built from this repository", () => {
+    before(implementProviders);
+    beforeEach(resetProviderState);
+    it("SignRaw hands the payload and options to the Sign provider", async () => {
+        const token = await (0, __1.SignRaw)({ userId: "u1" }, { expiresIn: "1h" });
+        (0, chai_1.expect)(token).to.equal(signedToken);
+        (0, chai_1.expect)(signCalls).to.deep.equal([[{ userId: "u1" }, { expiresIn: "1h" }]]);
+    });
+    it("ValidateRaw returns the payload of the Verify provider", async () => {
+        verifyOutcome = () => ({ name: "Bob" });
+        const payload = await (0, __1.ValidateRaw)("the-token", { maxAge: "1h" });
+        (0, chai_1.expect)(payload).to.deep.equal({ name: "Bob" });
+        (0, chai_1.expect)(verifyCalls).to.deep.equal([["the-token", { maxAge: "1h" }]]);
+    });
+    it("ValidateRaw rejects with the error of the Verify provider", async () => {
+        const failure = new Error("rejected by the provider");
+        verifyOutcome = () => {
+            throw failure;
+        };
+        let caught;
+        try {
+            await (0, __1.ValidateRaw)("bad-token");
+        }
+        catch (error) {
+            caught = error;
+        }
+        (0, chai_1.expect)(caught).to.equal(failure);
+    });
+});
+describe("Auth helpers built from this repository", () => {
+    before(implementProviders);
+    beforeEach(resetProviderState);
+    it("set-cookie uses standalone boolean directives", async () => {
+        const response = newResponse();
+        await (0, __1.SignServerResponse)(response, { userId: "user-7" }, { expiresIn: "1h" }, { httpOnly: true });
+        const setCookieHeader = response.getHeader("set-cookie");
+        (0, chai_1.expect)(setCookieHeader).to.be.a("string");
+        (0, chai_1.expect)(setCookieHeader).to.match(/^ANTELOPEJS_AUTH=/);
+        (0, chai_1.expect)(setCookieHeader).to.match(/httpOnly/);
+        (0, chai_1.expect)(setCookieHeader).to.not.match(/httpOnly=true/);
+    });
+    it("SignServerResponse serializes cookie attributes literally and omits false ones", async () => {
+        const bare = newResponse();
+        const attributed = newResponse();
+        await (0, __1.SignServerResponse)(bare, { userId: "u1" });
+        await (0, __1.SignServerResponse)(attributed, { userId: "u1" }, undefined, {
+            path: "/",
+            maxAge: 60,
+            secure: true,
+            httpOnly: false,
+        });
+        (0, chai_1.expect)(bare.getHeader("set-cookie")).to.equal(`ANTELOPEJS_AUTH=${signedToken}`);
+        (0, chai_1.expect)(attributed.getHeader("set-cookie")).to.equal(`ANTELOPEJS_AUTH=${signedToken}; path=/; maxAge=60; secure`);
+    });
+    it("defaultSource reads the header first and the cookie otherwise", () => {
+        const response = newResponse();
+        const headerAndCookie = requestWith({
+            "x-antelopejs-auth": "from-header",
+            cookie: "ANTELOPEJS_AUTH=from-cookie",
+        });
+        const cookieOnly = requestWith({
+            cookie: "other=1; ANTELOPEJS_AUTH=from-cookie; more=2",
+        });
+        (0, chai_1.expect)(__1.internal.defaultSource(headerAndCookie, response)).to.equal("from-header");
+        (0, chai_1.expect)(__1.internal.defaultSource(cookieOnly, response)).to.equal("from-cookie");
+        (0, chai_1.expect)(__1.internal.defaultSource(requestWith({}), response)).to.equal(undefined);
+    });
+    it("CheckAuthentication verifies through the Verify provider and applies the validator", async () => {
+        verifyOutcome = () => ({ id: 1 });
+        const request = requestWith({ "x-antelopejs-auth": "the-token" });
+        const callbacks = {
+            source: __1.internal.defaultSource,
+            authenticator: __1.ValidateRaw,
+            authenticatorOptions: {},
+            validator: undefined,
+        };
+        const plain = await __1.internal.CheckAuthentication(request, newResponse(), callbacks);
+        const validated = await __1.internal.CheckAuthentication(request, newResponse(), {
+            ...callbacks,
+            validator: (claims) => ({ claims, validated: true }),
+        });
+        (0, chai_1.expect)(plain).to.deep.equal({ id: 1 });
+        (0, chai_1.expect)(validated).to.deep.equal({ claims: { id: 1 }, validated: true });
+        (0, chai_1.expect)(verifyCalls).to.deep.equal([
+            ["the-token", {}],
+            ["the-token", {}],
+        ]);
+    });
+    it("CheckAuthentication calls the callbacks without the callbacks object as receiver", async () => {
+        const receivers = [];
+        const callbacks = {
+            source() {
+                receivers.push(this);
+                return "the-token";
+            },
+            authenticator() {
+                receivers.push(this);
+                return { id: 1 };
+            },
+            authenticatorOptions: {},
+            validator() {
+                receivers.push(this);
+                return "validated";
+            },
+        };
+        const result = await __1.internal.CheckAuthentication(requestWith({}), newResponse(), callbacks);
+        (0, chai_1.expect)(result).to.equal("validated");
+        (0, chai_1.expect)(receivers).to.deep.equal([undefined, undefined, undefined]);
+    });
+});
+//# sourceMappingURL=local-build.test.js.map

package/dist/tests/local-build.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-build.test.js","sourceRoot":"","sources":["../../src/tests/local-build.test.ts"],"names":[],"mappings":"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"}

package/docs/1.introduction.md

@@ -1,27 +1,67 @@
-# Interface Auth Documentation
+---
+title: Authenticate API requests
+description: Install the auth interface, protect a first endpoint with a verified token, and pick where to plug in your own source, verifier, or validator.
+mode: how-to
+---
 
 ## 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.
+Use `@antelopejs/interface-auth` to sign tokens and inject verified payloads into API handlers. Your application still owns credential checks, payload validation, and permission rules. A valid signature alone does not grant access to a resource.
 
-This interface depends on the [Interface API](https://github.com/AntelopeJS/interface-api) package, which provides the decorator infrastructure for parameter injection.
+This interface depends on the [interface-api](https://github.com/AntelopeJS/interface-api) package, which provides the decorators that inject parameters.
 
 ## Core concepts
 
-The authentication system is built around three main layers:
+The interface has three 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.
+- Token handling. `SignRaw`, `ValidateRaw`, and `SignServerResponse` sign and verify tokens.
+- Authentication decorators. The `@Authentication` decorator and the `CreateAuthDecorator` function inject verified payloads into handler parameters.
+- A pipeline you can change. Custom sources, verifiers, and validators replace each step of the flow.
 
 ## Installation
 
 ```bash
-npm install @antelopejs/interface-auth
+pnpm add @antelopejs/interface-auth
 ```
 
+## Protect an endpoint
+
+Start with a running AntelopeJS API module and an authentication module that implements this interface. Installing the package does not configure signing keys or attach a token implementation.
+
+This controller requires a verified token for `GET /account`. It returns no claims, so you can check that your provider and transport work before you add payload validation.
+
+```ts docs-check
+import { Controller, Get } from "@antelopejs/interface-api";
+import { Authentication } from "@antelopejs/interface-auth";
+
+@Authentication()
+class AccountController extends Controller("/account") {
+  @Get("")
+  status() {
+    return { authenticated: true };
+  }
+}
+```
+
+Send an issued token in `x-antelopejs-auth` to receive `{ "authenticated": true }`. A missing or invalid token must fail verification before the handler runs. This route checks authentication only, not permission to read another user's account.
+
+1. **Issue a token after you check the credentials.** Use [token handling](./3.token-handling.md) to choose `SignRaw` or `SignServerResponse` and set an expiry.
+2. **Choose one transport.** The default source reads a raw token from `x-antelopejs-auth`, then tries `ANTELOPEJS_AUTH` only when the header is absent. For `Authorization: Bearer`, use the [custom source example](./2.authentication.md#create-a-custom-source).
+3. **Require authentication.** Add [a parameter, property, or class decorator](./4.parameter-decoration.md) to the controller.
+4. **Enforce your policy.** Validate the payload shape, and throw when the caller lacks permission. A validator that returns `false` injects `false`. It does not deny access.
+
+## Choose where to customize
+
+| You need to change         | Customize       | Keep this boundary                           |
+| -------------------------- | --------------- | -------------------------------------------- |
+| Where the token comes from | `source`        | Extraction does not establish trust.         |
+| How the token is verified  | `authenticator` | Verify before you return a payload.          |
+| Who may use the endpoint   | `validator`     | Throw to reject. Return the value to inject. |
+
+Before you expose the route, test a missing token, an invalid token, and a valid token without the required permission, as well as the successful request. See [authentication and authorization](./2.authentication.md) for the complete pipeline.
+
 ## 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
+- [Authentication and authorization](./2.authentication.md) covers the flow, sources, verifiers, and validators.
+- [Token handling](./3.token-handling.md) covers the functions that sign and verify tokens.
+- [Require authentication in controllers](./4.parameter-decoration.md) covers the decorators and custom decorators.

package/docs/2.authentication.md

@@ -1,19 +1,25 @@
-# Authentication Basics
+---
+title: Authentication and authorization
+description: How the auth interface turns a request into an injected payload, through a source, an authenticator, and an optional validator, and which part of the policy stays in your application.
+mode: explanation
+---
 
-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 establishes trust in a token. Authorization decides what its holder may do. This interface connects token verification to API parameter injection. Your application supplies credential checks, payload validation, and access rules.
 
 ## Authentication flow
 
-A typical authentication flow consists of four steps:
+An authentication flow has 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.
+1. Token generation. `SignRaw` or `SignServerResponse` signs user data into a token.
+2. Token transport. The client sends the token in the chosen header or cookie. You choose the client's storage and CSRF protection. This interface configures neither.
+3. Token validation. The server verifies the token on each request.
+4. Authorization. Your code checks whether the authenticated user may access the requested resource.
 
 ### Example authentication flow
 
-```typescript
+The persistence functions in this example, `validateUserCredentials` and `getUserProfile`, belong to your application. The profile route verifies a token. A validator would add the payload shape and resource permissions. For production cookies, you also decide the Secure, SameSite, expiry, and CSRF policy of your deployment.
+
+```typescript fragment
 import { SignRaw, Authentication } from "@antelopejs/interface-auth";
 import {
   Controller,
@@ -43,7 +49,7 @@ class UserController extends Controller("/users") {
 
     result.addHeader(
       "Set-Cookie",
-      `ANTELOPEJS_AUTH=${token}; HttpOnly; Path=/`,
+      `ANTELOPEJS_AUTH=${token}; HttpOnly; Secure; SameSite=Lax; Path=/`,
     );
 
     return result;
@@ -53,21 +59,23 @@ class UserController extends Controller("/users") {
   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
+    // Step 3: the token is verified. Resource authorization is application policy.
+    // An invalid token rejects the request before this code runs.
     return { user: await getUserProfile(userData.userId) };
   }
 }
 ```
 
+This cookie example requires HTTPS. `SameSite=Lax` is a starting policy for same-site browser use. It does not replace a decision on CSRF protection or cross-site requirements. The helpers named above are application code, not a complete login implementation.
+
 ## 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
+1. The `x-antelopejs-auth` header.
+2. The `ANTELOPEJS_AUTH` cookie.
 
-The header contains the raw token, not `Bearer <token>`. A present header takes precedence even when it is empty or invalid; authentication does not retry with the cookie after verification fails. The default source does not read `Authorization`.
+The header contains the raw token, not `Bearer <token>`. A present header takes precedence even when it is empty or invalid. Authentication does not retry with the cookie after verification fails. The default source does not read `Authorization`.
 
 ### Create a custom source
 
@@ -93,6 +101,8 @@ const BearerAuth = CreateAuthDecorator({
 The `AuthSource` type signature is:
 
 ```typescript
+import type { IncomingMessage, ServerResponse } from "node:http";
+
 type AuthSource = (
   req: IncomingMessage,
   res: ServerResponse,
@@ -101,7 +111,7 @@ type AuthSource = (
 
 ## 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).
+An `AuthVerifier` function validates the token and extracts its payload. The default verifier is `ValidateRaw`, which calls the module that implements this interface, such as `@antelopejs/auth-jwt` for JSON Web Tokens.
 
 ### Create a custom verifier
 
@@ -116,13 +126,8 @@ const userVerifier: AuthVerifier<{ userId: string }> = async (
   data,
   options,
 ) => {
-  const payload = await ValidateRaw<unknown>(data, options);
-  if (
-    typeof payload !== "object" ||
-    payload === null ||
-    !("userId" in payload) ||
-    typeof payload.userId !== "string"
-  ) {
+  const payload = await ValidateRaw(data, options);
+  if (typeof payload === "string" || typeof payload.userId !== "string") {
     throw new Error("Invalid user payload");
   }
   return { userId: payload.userId };
@@ -133,12 +138,14 @@ const UserAuth = CreateAuthDecorator({
 });
 ```
 
-A verifier must establish trust in the token before returning its payload. Decoding Base64 or parsing JSON alone does not authenticate a request. The generic argument to `ValidateRaw<T>` describes the expected result for TypeScript; it does not validate the payload's shape.
+A verifier must establish trust in the token before it returns the payload. Decoding Base64 or parsing JSON alone does not authenticate a request. `ValidateRaw` returns an `AuthClaims`, which is `string | JsonObject`. The interface does not know the shape of what you signed, so reading a field needs a check like the one above. A configured validator receives the verifier's return type as its input.
 
 The `AuthVerifier` type signature is:
 
 ```typescript
-type AuthVerifier<T = unknown> = (
+import type { AuthClaims, VerifyOptions } from "@antelopejs/interface-auth";
+
+type AuthVerifier<T = AuthClaims> = (
   data?: string,
   options?: VerifyOptions,
 ) => Promise<T> | T;
@@ -146,21 +153,16 @@ type AuthVerifier<T = unknown> = (
 
 ## 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.
+An `AuthValidator` function runs extra checks on the verified data. Validators run after the verifier. A validator 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") {
+const adminValidator: AuthValidator = (claims) => {
+  if (typeof claims === "string" || claims.role !== "admin") {
     throw new Error("Admin access required");
   }
-  return userData;
+  return claims;
 };
 
 const AdminOnly = CreateAuthDecorator({
@@ -171,15 +173,25 @@ const AdminOnly = CreateAuthDecorator({
 The `AuthValidator` type signature is:
 
 ```typescript
-type AuthValidator<T = unknown, R = unknown> = (data: T) => Promise<R> | R;
+import type { AuthClaims } from "@antelopejs/interface-auth";
+
+type AuthValidator<T = AuthClaims, R = unknown> = (data: T) => Promise<R> | R;
 ```
 
+Without an `authenticator`, a validator receives the `AuthClaims` the default verifier returns. When you also configure an `authenticator`, the validator receives whatever that authenticator returns, so a typed verifier such as `userVerifier` above gives the validator a typed value.
+
 ## Authentication pipeline
 
-The complete authentication pipeline processes the request through three stages:
+The pipeline takes the request through three stages:
 
-```
-source(req, res) => authenticator(token, options) => validator(data) => Parameter
-```
+![The source extracts a token, the authenticator verifies it, and an optional validator enforces policy before injection. A thrown error stops injection.](./assets/authentication-pipeline.svg "illustration"){width="480"}
+
+An omitted `source` or `authenticator` callback uses the default. There is no default policy validator. Without one, the decorator injects the verified payload unchanged.
+
+| Stage           | Input                          | Output               | Failure boundary                                               |
+| --------------- | ------------------------------ | -------------------- | -------------------------------------------------------------- |
+| `source`        | Request and response           | Token or `undefined` | Missing input still reaches the authenticator.                 |
+| `authenticator` | Token and verification options | Verified payload     | A thrown error or rejected promise stops processing.           |
+| `validator`     | Verified payload               | Value to inject      | Throw to deny access. A falsy return value is not a rejection. |
 
-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.
+A validator passed to a decorator call replaces the configured validator. It does not run after it as an extra check. To compose validators, keep the shared policy in a function that each validator calls.

package/docs/3.token-handling.md

@@ -1,6 +1,10 @@
-# Token Handling
+---
+title: Token handling
+description: Reference for SignRaw, SignServerResponse, and ValidateRaw, with their options, argument types, return values, and cookie serialization limits.
+mode: reference
+---
 
-The Interface Auth provides functions for generating and validating authentication tokens. These functions serve as the foundation for the authentication system.
+`@antelopejs/interface-auth` exports three functions that sign and verify tokens. The decorators call `ValidateRaw` by default.
 
 ## Token generation
 
@@ -16,15 +20,17 @@ const token = await SignRaw(
   { expiresIn: "1h" },
 );
 
-console.log(token); // Signed token string
+// Return the token through your chosen authentication transport.
 ```
 
 The function accepts two arguments:
 
-| Argument  | Type                         | Description                   |
-| --------- | ---------------------------- | ----------------------------- |
-| `data`    | `string \| Buffer \| object` | The data to sign              |
-| `options` | `SignOptions` (optional)     | Signing configuration options |
+| Argument  | Type                             | Description                   |
+| --------- | -------------------------------- | ----------------------------- |
+| `data`    | `string \| Buffer \| JsonObject` | The data to sign              |
+| `options` | `SignOptions` (optional)         | Signing configuration options |
+
+`JsonObject` maps string keys to JSON values: `string`, `number`, `boolean`, `null`, arrays, and nested objects. A `Date`, a class instance, or a function is a compile error. Convert it first, for example with `date.toISOString()`. A key whose value is `undefined` is accepted, and serialization drops it. An object typed with an `interface` has no index signature and is not assignable. Declare it with a `type` alias, or spread it into a literal.
 
 `SignRaw` returns a `Promise<string>` that resolves to the signed token.
 
@@ -32,10 +38,12 @@ The function accepts two arguments:
 
 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                                 |
+| Property    | Type                 | Description                                                                     |
+| ----------- | -------------------- | ------------------------------------------------------------------------------- |
+| `expiresIn` | `number \| TimeSpan` | Token expiration time as seconds or a timespan string, such as `"1h"` or `"2d"` |
+| `notBefore` | `number \| TimeSpan` | Duration before which the token is not valid                                    |
+
+`TimeSpan` is the timespan grammar of the `ms` package. It is a number followed by an optional unit in any case, with or without a space, such as `"90"`, `"2h"`, or `"7 days"`. A bare number string counts milliseconds. A string outside this grammar, such as `"soon"`, does not compile.
 
 ### `SignServerResponse`
 
@@ -59,30 +67,32 @@ async function login(res: ServerResponse) {
 
 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  |
+| Argument        | Type                             | Description                   |
+| --------------- | -------------------------------- | ----------------------------- |
+| `res`           | `ServerResponse`                 | The HTTP response object      |
+| `data`          | `string \| Buffer \| JsonObject` | 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 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)`.
+The `CookieOptions` interface supplies attributes to the authentication cookie. The serializer writes keys literally and omits `false` and `undefined` values. It writes `true` as a standalone directive and converts other values with `String(value)`.
 
-| Property   | Type      | Description                                                                     |
-| ---------- | --------- | ------------------------------------------------------------------------------- |
-| `maxAge`   | `number`  | Written as `maxAge=<number>`; not converted to the standard `Max-Age` attribute |
-| `signed`   | `boolean` | Written as a directive when true; does not add a cookie signature               |
-| `expires`  | `Date`    | Written using `String(date)`, not an explicit HTTP-date formatter               |
-| `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                                                |
+| Property   | Type      | Description                                                           |
+| ---------- | --------- | --------------------------------------------------------------------- |
+| `maxAge`   | `number`  | Written as `maxAge=<number>`, not as the standard `Max-Age` attribute |
+| `signed`   | `boolean` | Written as a directive when true. It does not add a cookie signature. |
+| `expires`  | `Date`    | Written using `String(date)`, not an explicit HTTP-date formatter     |
+| `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                                      |
 
-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.
+`maxAge`, `signed`, and `expires` do not set the browser lifetime or add a signature. When you need those features, use a standards-compliant cookie serializer, and keep token expiration in `SignOptions`. The function adds no cookie attributes 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](./2.authentication.md#example-authentication-flow). Do not cast unsupported options into this type.
 
 ## Token validation
 
@@ -93,11 +103,16 @@ The `ValidateRaw` function verifies a token and returns the data contained withi
 ```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);
+async function inspect(token: string) {
+  try {
+    const claims = await ValidateRaw(token);
+    console.log(claims); // { userId: 123, role: "admin", iat: ..., exp: ... } with auth-jwt
+  } catch (error) {
+    console.error(
+      "Invalid token:",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
 }
 ```
 
@@ -108,6 +123,10 @@ The function accepts two arguments:
 | `token`   | `string` (optional)        | The signed token to verify |
 | `options` | `VerifyOptions` (optional) | Verification configuration |
 
+`ValidateRaw` returns a `Promise<AuthClaims>`, where `AuthClaims` is `string | JsonObject`. The value is the signed string, or the JSON object that was signed. `ValidateRaw` has no type parameter. Read a field only after you check it, or pass the result to a parser of your own. A [custom verifier](./2.authentication.md#create-a-custom-verifier) does that once for every route.
+
+The promise rejects when the token is missing or fails verification. The rejection value comes from the implementation and is not always an `Error`. `@antelopejs/auth-jwt` rejects with an `HTTPResult`: status 401 for a missing token and 403 for an invalid or expired one. The example above handles both kinds of value.
+
 ### `VerifyOptions`
 
 The `VerifyOptions` interface configures token validation.
@@ -123,9 +142,12 @@ The `VerifyOptions` interface configures token validation.
 ```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,
-});
+// Limit token age without bypassing expiration or not-before checks.
+async function verifyRecent(token: string) {
+  return ValidateRaw(token, {
+    maxAge: "30m",
+  });
+}
 ```
+
+Leave `ignoreExpiration` and `ignoreNotBefore` unset for normal authentication. They bypass the time checks. Set them only when a separate, explicit policy accepts such tokens. A successful `ValidateRaw` call verifies the token through your provider. It does not check the shape of the payload.