@antelopejs/interface-auth 0.0.7 → 0.2.0

package/docs/4.parameter-decoration.md

@@ -1,10 +1,14 @@
-# Parameter Decoration
+---
+title: Require authentication in controllers
+description: Protect a handler, a property, or a whole controller with @Authentication, and build reusable decorators with CreateAuthDecorator.
+mode: how-to
+---
 
-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.
+Use a parameter decorator when one handler needs the payload. Use a property decorator when several methods need it. Use a class decorator when every route must authenticate without receiving the payload. Pick one scope per need. You do not have to combine them.
 
 ## The `@Authentication` decorator
 
-The `@Authentication` decorator retrieves and validates a token from `x-antelopejs-auth`, or from the `ANTELOPEJS_AUTH` cookie when the header is absent, and injects the verified payload into the parameter.
+The `@Authentication` decorator reads a token from `x-antelopejs-auth`, or from the `ANTELOPEJS_AUTH` cookie when the header is absent. It verifies the token and injects the verified payload into the parameter.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -21,7 +25,9 @@ class UserController extends Controller("/users") {
 }
 ```
 
-If the token is missing or invalid, the request fails with an error response before the handler executes.
+If the token is missing or invalid, the verifier rejects and the handler does not run. With `@antelopejs/auth-jwt`, the response is a 401 for a missing token and a 403 for an invalid one.
+
+The payload annotations in these examples describe the token format the application expects. They do not check it. Add a [shape-checking verifier](./2.authentication.md#create-a-custom-verifier) before you read claims from tokens whose format nothing enforces yet. The API provider decides how an ordinary thrown error becomes an HTTP response. Throwing an `Error` does not set a 401 or 403 status.
 
 ### Inline validators
 
@@ -34,13 +40,15 @@ import { Authentication } from "@antelopejs/interface-auth";
 class PaymentController extends Controller("/payments") {
   @Post()
   async createPayment(
-    @Authentication((user: any) => {
-      if (!user.paymentPermissions) {
+    @Authentication((claims) => {
+      if (typeof claims === "string" || !claims.paymentPermissions) {
         throw new Error("Payment permissions required");
       }
-      return user;
+      return claims;
     })
-    user: any,
+    user: {
+      paymentPermissions: string[];
+    },
   ) {
     // Process payment
     return { success: true };
@@ -50,51 +58,59 @@ class PaymentController extends Controller("/payments") {
 
 ## Create custom decorators with `CreateAuthDecorator`
 
-The `CreateAuthDecorator` function creates a reusable authentication decorator with custom source, authenticator, and validator functions.
+The `CreateAuthDecorator` function creates a reusable authentication decorator from custom source, authenticator, and validator functions. `validateApiKey` in the example below belongs to your application.
 
-```typescript
+```typescript fragment
 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") {
+  validator: (claims) => {
+    if (typeof claims === "string" || claims.role !== "admin") {
       throw new Error("Admin access required");
     }
-    return user;
+    return claims;
   },
 });
 
 // API key decorator with custom source and authenticator
 export const ApiKeyAuth = CreateAuthDecorator({
-  source: (req: IncomingMessage) => req.headers["x-api-key"] as string,
+  source: (req: IncomingMessage) => {
+    const key = req.headers["x-api-key"];
+    return typeof key === "string" ? key : undefined;
+  },
   authenticator: async (apiKey?: string) => {
-    if (!apiKey) return null;
+    if (!apiKey) throw new Error("API key required");
     const user = await validateApiKey(apiKey);
+    if (!user) throw new Error("Invalid API key");
     return user;
   },
 });
 ```
 
+`validateApiKey` is your application's lookup and verification function. If the authenticator returned `null` for a missing or invalid key, the handler would run with `null`. This example throws instead.
+
 ### `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                 |
+| Property               | Type                  | Description                                                           |
+| ---------------------- | --------------------- | --------------------------------------------------------------------- |
+| `source`               | `AuthSource`          | Extracts the token from the request. Defaults to header, then 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. The default source reads the header, then the cookie. The default authenticator calls `ValidateRaw`, and the default verification options are `{}`. Without a validator, the decorator injects the verified payload unchanged.
 
-All properties are optional. The default source reads the header/cookie, the default authenticator calls `ValidateRaw`, and the default verification options are `{}`. Without a validator, the verified payload is passed through unchanged.
+TypeScript infers `T` and `R` from the callbacks. Without an `authenticator`, `T` is `AuthClaims`, which is `string | JsonObject`. A validator then checks the claims before it reads them, as in `AdminAuth` above. With an `authenticator`, `T` is what the authenticator returns, and the validator receives that type. To name both type arguments, write `CreateAuthDecorator<T, R>` with an `authenticator`. A single type argument names `R` when there is no `authenticator`, and `T` when there is one.
 
-A validator passed to a decorator call replaces the configured validator; the two do not compose. Return a transformed value to inject it, or throw to deny access. Returning `false` or `null` does not reject the request. A custom authenticator that accepts a missing token also permits it unless a validator throws.
+A validator passed to a decorator call replaces the configured validator. The two do not compose. Return a transformed value to inject it, or throw to deny access. Returning `false` or `null` does not reject the request. A custom authenticator that accepts a missing token lets the request through unless a validator throws.
 
 ## 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.
+Apply the `@Authentication` decorator to a controller class to require authentication on every route of that controller. You do not need to decorate each handler.
 
 ```typescript
 import { Controller, Get, Post } from "@antelopejs/interface-api";
@@ -124,11 +140,11 @@ Combine class-level authentication with a validator to enforce role-based access
 import { Controller } from "@antelopejs/interface-api";
 import { Authentication } from "@antelopejs/interface-auth";
 
-@Authentication((user: any) => {
-  if (!user || user.role !== "admin") {
+@Authentication((claims) => {
+  if (typeof claims === "string" || claims.role !== "admin") {
     throw new Error("Admin access required");
   }
-  return user;
+  return claims;
 })
 class AdminController extends Controller("/admin") {
   // All routes require admin authentication
@@ -137,7 +153,7 @@ class AdminController extends Controller("/admin") {
 
 ## 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.
+Apply `@Authentication` to a class property to read the authenticated user data in every handler of the controller. The API module sets the property on each request.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -165,7 +181,7 @@ class UserController extends Controller("/users") {
 
 ## Decorator scope summary
 
-The `@Authentication` decorator (and any custom decorator created with `CreateAuthDecorator`) can be applied at three levels:
+The `@Authentication` decorator, and any custom decorator that `CreateAuthDecorator` creates, applies at three levels:
 
 | Scope     | Effect                                                                |
 | --------- | --------------------------------------------------------------------- |

package/docs/assets/authentication-pipeline.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 480" role="img" aria-labelledby="title desc">
+  <title id="title">Authentication: extraction, trust, policy</title>
+  <desc id="desc">A source extracts a token. An authenticator verifies it. An optional validator checks policy. Only successful processing injects the result. Throwing stops injection.</desc>
+  <rect width="480" height="480" rx="16" fill="#f5f7fb"/>
+  <g font-family="system-ui, sans-serif" fill="#172b45">
+    <text x="24" y="36" font-size="20" font-weight="700">From request to trusted input</text>
+    <rect x="24" y="58" width="432" height="84" rx="10" fill="#e1ecfa"/>
+    <text x="42" y="87" font-size="18" font-weight="700">1 · Source</text>
+    <text x="42" y="116" font-size="16">Extract the token; do not trust it yet.</text>
+    <path d="M240 148v20m-6-6 6 6 6-6" fill="none" stroke="#526780" stroke-width="2"/>
+    <rect x="24" y="176" width="432" height="84" rx="10" fill="#d9eee8"/>
+    <text x="42" y="205" font-size="18" font-weight="700">2 · Authenticator</text>
+    <text x="42" y="234" font-size="16">Verify the token and return its payload.</text>
+    <path d="M240 266v20m-6-6 6 6 6-6" fill="none" stroke="#526780" stroke-width="2"/>
+    <rect x="24" y="294" width="432" height="84" rx="10" fill="#eee6fb"/>
+    <text x="42" y="323" font-size="18" font-weight="700">3 · Validator (optional)</text>
+    <text x="42" y="352" font-size="16">Check policy; return the value to inject.</text>
+    <text x="24" y="416" font-size="16" font-weight="700">Success → inject the resulting value.</text>
+    <text x="24" y="447" font-size="16" fill="#913a31">Throw → stop. Returning false does not deny.</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-auth",
-  "version": "0.0.7",
+  "version": "0.2.0",
   "description": "AntelopeJS interface for token authentication: sign and verify tokens and inject the verified payload into API handlers",
   "keywords": [
     "antelopejs",
@@ -46,13 +46,22 @@
     "release": "pnpm run lint && pnpm run prepack && release-it",
     "test": "pnpm run build && ajs module test .",
     "format:check": "oxfmt --check .",
-    "knip": "knip"
+    "knip": "knip",
+    "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
+    "checks": "antelopejs-checks",
+    "size": "antelopejs-check-size",
+    "sync": "antelopejs-sync",
+    "sync:check": "antelopejs-sync --check",
+    "typecheck": "tsc --noEmit",
+    "suppressions": "antelopejs-suppressions",
+    "suppressions:update": "antelopejs-suppressions --update"
   },
   "devDependencies": {
+    "@antelopejs/auth-jwt": "1.0.3",
     "@antelopejs/core": "^1.16.0",
-    "@antelopejs/interface-api": "^0.0.15",
-    "@antelopejs/interface-core": "^0.2.4",
-    "@antelopejs/tooling-configs": "^0.0.9",
+    "@antelopejs/interface-api": "^0.2.0",
+    "@antelopejs/interface-core": "^0.4.0",
+    "@antelopejs/tooling-configs": "^0.2.17",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -60,6 +69,7 @@
     "chai": "^4.5.0",
     "eslint-plugin-perfectionist": "^5.11.0",
     "knip": "^6.34.0",
+    "lefthook": "^2.2.2",
     "mongodb-memory-server-core": "^10.4.3",
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",
@@ -74,10 +84,19 @@
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
+  "pnpm": {
+    "overrides": {
+      "@antelopejs/auth-jwt>@antelopejs/interface-auth": "link:.",
+      "@antelopejs/interface-core": "0.4.0"
+    }
+  },
   "antelopeJs": {
     "test": "src/antelope.test.ts",
     "skills": [
       "./skills"
-    ]
+    ],
+    "docs": {
+      "standard": true
+    }
   }
 }

package/skills/auth-interface/SKILL.md

@@ -24,9 +24,12 @@ import {
   ValidateRaw,
   SignServerResponse,
   internal, // provider side only
+  type AuthClaims,
   type AuthSource,
   type AuthVerifier,
   type AuthValidator,
+  type JsonObject,
+  type JsonValue,
   type SignOptions,
   type VerifyOptions,
   type CookieOptions,
@@ -61,7 +64,9 @@ class LibrarianController extends Controller("/librarians") {
 }
 ```
 
-Custom pipelines use `CreateAuthDecorator({ source?, authenticator?, authenticatorOptions?, validator? })`; the callbacks run as `source(req, res)` → `authenticator(data, authenticatorOptions)` → `validator(data)` → injected parameter.
+Custom pipelines use `CreateAuthDecorator({ source?, authenticator?, authenticatorOptions?, validator? })`; the callbacks run as `source(req, res)` → `authenticator(data, authenticatorOptions)` → `validator(data)` → injected parameter. Without an `authenticator` the validator receives an `AuthClaims`; with one it receives what the authenticator returns.
+
+`ValidateRaw` has no type parameter: it returns `AuthClaims` (`string | JsonObject`). To read fields, parse the claims once, in a custom `authenticator` (`async (token, options) => parseSession(await ValidateRaw(token, options))`) or at the call site.
 
 ## Providing
 
@@ -72,7 +77,7 @@ 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
+  Verify: (token, options) => decodeAndVerify(token, options), // return the AuthClaims (string or JSON object), throw on invalid
   Sign: (data, options) => signToken(data, options), // return token string
 });
 ```
@@ -81,6 +86,7 @@ Declare `"antelopeJs": { "implements": ["@antelopejs/interface-auth"] }` in the
 
 ## Gotchas
 
+- The data passed to `SignRaw` / `SignServerResponse` is a `string`, a `Buffer` or a `JsonObject`. A `Date`, a class instance or an `interface`-typed object (no index signature) is a compile error; convert it or use a `type` alias. `undefined`-valued keys are accepted.
 - `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`.

package/skills/auth-interface/cases.json

@@ -0,0 +1,73 @@
+{
+  "version": 1,
+  "cases": [
+    {
+      "id": "protect-route",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "How do I protect a route with authentication?",
+      "origin": "docs-assistant",
+      "expect": {
+        "skills": ["auth-interface"],
+        "acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
+        "mustMention": ["Authentication"]
+      }
+    },
+    {
+      "id": "protect-route-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "what do i need to do so my route is protected?",
+      "origin": "docs-assistant",
+      "expect": {
+        "skills": ["auth-interface"],
+        "acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
+        "mustMention": ["Authentication"]
+      }
+    },
+    {
+      "id": "auth-interface-dms-neighbour",
+      "area": "dms",
+      "style": "clean",
+      "prompt": "In the DMS, only administrators should open the billing page. Register a permission for it and gate the page.",
+      "expect": {
+        "skills": ["dms-auth"],
+        "acceptable": ["dms", "dms-pages"],
+        "avoid": ["auth-interface"]
+      }
+    },
+    {
+      "id": "auth-interface-cookie-response",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "After login I want the signed token set as a cookie on the response instead of returned in the body. What do I call?",
+      "expect": {
+        "skills": ["auth-interface"],
+        "acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
+        "mustMention": ["SignServerResponse"]
+      }
+    },
+    {
+      "id": "auth-interface-token-expiry-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "token dies too quick, how do i make it last a day",
+      "expect": {
+        "skills": ["auth-interface"],
+        "acceptable": ["antelopejs", "ajs-consume-interface"],
+        "mustMention": ["SignRaw", "expiresIn"]
+      }
+    },
+    {
+      "id": "auth-interface-typed-claims",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "ValidateRaw<Profile>(token) no longer compiles. How do I get a typed profile out of a verified token?",
+      "expect": {
+        "skills": ["auth-interface"],
+        "acceptable": ["antelopejs", "ajs-consume-interface"],
+        "mustMention": ["AuthClaims"]
+      }
+    }
+  ]
+}