@antelopejs/interface-auth 0.0.5 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +79 -16
  2. package/dist/antelope.test.js +6 -12
  3. package/dist/antelope.test.js.map +1 -1
  4. package/dist/index.d.ts +28 -22
  5. package/dist/index.js +22 -19
  6. package/dist/index.js.map +1 -1
  7. package/dist/tests/index.test.js +1 -1
  8. package/dist/tests/index.test.js.map +1 -1
  9. package/docs/1.introduction.md +27 -0
  10. package/docs/2.authentication.md +185 -0
  11. package/docs/3.token-handling.md +131 -0
  12. package/docs/4.parameter-decoration.md +174 -0
  13. package/docs/tsconfig.json +12 -0
  14. package/package.json +42 -22
  15. package/skills/auth-interface/SKILL.md +93 -0
package/README.md CHANGED
@@ -1,31 +1,94 @@
1
- ![Auth](.github/social-card.png)
2
-
3
- # Interface Auth
1
+ # @antelopejs/interface-auth
4
2
 
5
3
  <div align="center">
6
- <a href="https://www.npmjs.com/package/@antelopejs/interface-auth"><img src="https://img.shields.io/npm/v/@antelopejs/interface-auth?style=for-the-badge&labelColor=000000&color=000000" alt="npm"></a>
7
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge&labelColor=000000"></a>
8
- <a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
9
- <a href="./docs/1.introduction.md"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
4
+ <a href="https://www.npmjs.com/package/@antelopejs/interface-auth"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-auth?style=for-the-badge&labelColor=000000&color=000000"></a>
5
+ <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-auth?style=for-the-badge&labelColor=000000&color=000000"></a>
6
+ <a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
7
+ <a href="https://interfaces.antelopejs.com/docs/auth"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
10
8
  </div>
11
9
 
12
- A decorator-based framework for implementing authentication and authorization in TypeScript. Interface Auth provides token signing, verification, and flexible decorator-based parameter injection for securing API endpoints.
10
+ The AntelopeJS contract for token authentication: sign and verify tokens, and inject the verified payload into API handlers with a decorator.
11
+
12
+ ## What it offers
13
+
14
+ - `SignRaw` and `ValidateRaw` sign a payload into a token and verify a token back into its payload.
15
+ - `SignServerResponse` signs a payload and attaches the token to a response as a cookie.
16
+ - `@Authentication()` reads the token from the `x-antelopejs-auth` header, falling back to the `ANTELOPEJS_AUTH` cookie when the header is absent, verifies it and injects the payload into a handler parameter.
17
+ - `CreateAuthDecorator` builds your own decorator with a custom source, verifier and validator.
18
+
19
+ ## Implementations
13
20
 
14
- ## Installation
21
+ | Module | Notes |
22
+ | ---------------------------------------------------------------- | --------------- |
23
+ | [`@antelopejs/auth-jwt`](https://github.com/AntelopeJS/auth-jwt) | JSON Web Tokens |
24
+
25
+ ## Install
26
+
27
+ Add the interface to the module that protects routes:
15
28
 
16
29
  ```bash
17
- npm install @antelopejs/interface-auth
30
+ pnpm add @antelopejs/interface-auth
18
31
  ```
19
32
 
33
+ Then add an implementation to the project, with an implementation of the API interface:
34
+
35
+ ```bash
36
+ ajs project modules add @antelopejs/auth-jwt @antelopejs/api
37
+ ```
38
+
39
+ ## Quick start
40
+
41
+ ```ts
42
+ import { Controller, Get, Post } from "@antelopejs/interface-api";
43
+ import { Authentication, SignRaw } from "@antelopejs/interface-auth";
44
+
45
+ interface Session {
46
+ id: string;
47
+ }
48
+
49
+ export class SessionController extends Controller("/session") {
50
+ @Post("login")
51
+ async login() {
52
+ return SignRaw({ id: "user-7" }, { expiresIn: "1h" });
53
+ }
54
+
55
+ @Get("me")
56
+ async me(@Authentication() session: Session) {
57
+ return { id: session.id };
58
+ }
59
+ }
60
+ ```
61
+
62
+ A request to `GET /session/me` without a valid token fails before the handler runs. Send the token unchanged in `x-antelopejs-auth`, without a `Bearer ` prefix. The login method only demonstrates signing; validate credentials before issuing tokens in a real application.
63
+
20
64
  ## Documentation
21
65
 
22
- Detailed documentation is available in the `docs` directory:
66
+ - [Introduction](./docs/1.introduction.md)
67
+ - [Authentication](./docs/2.authentication.md)
68
+ - [Token handling](./docs/3.token-handling.md)
69
+ - [Parameter decoration](./docs/4.parameter-decoration.md)
70
+
71
+ ## Compatibility
72
+
73
+ Use with `@antelopejs/core` 1.x and the following peer dependencies:
23
74
 
24
- - [Introduction](./docs/1.introduction.md) - Overview and core concepts
25
- - [Authentication Basics](./docs/2.authentication.md) - Authentication flow, sources, and verifiers
26
- - [Token Handling](./docs/3.token-handling.md) - Token generation and validation
27
- - [Parameter Decoration](./docs/4.parameter-decoration.md) - Authentication decorators and custom providers
75
+ <!-- docs-compat: ./package.json#peerDependencies -->
76
+
77
+ | Package | Range |
78
+ | ---------------------------- | ----------------- |
79
+ | `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
80
+ | `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
81
+
82
+ ## Contributing
83
+
84
+ Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
85
+
86
+ ```bash
87
+ pnpm install
88
+ pnpm lint
89
+ pnpm test
90
+ ```
28
91
 
29
92
  ## License
30
93
 
31
- This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
94
+ [Apache-2.0](./LICENSE)
package/dist/antelope.test.js CHANGED
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- const config_1 = require("@antelopejs/interface-core/config");
4
3
  const mongodb_memory_server_core_1 = require("mongodb-memory-server-core");
4
+ const config_1 = require("@antelopejs/interface-core/config");
5
5
  let mongod;
6
6
  exports.default = (0, config_1.defineConfig)({
7
7
  name: "interface-auth-test",
@@ -11,7 +11,7 @@ exports.default = (0, config_1.defineConfig)({
11
11
  source: {
12
12
  type: "package",
13
13
  package: "@antelopejs/auth-jwt",
14
- version: "1.0.0",
14
+ version: "1.0.3",
15
15
  },
16
16
  config: { secret: "test-secret-key-for-jwt" },
17
17
  },
@@ -19,24 +19,18 @@ exports.default = (0, config_1.defineConfig)({
19
19
  source: {
20
20
  type: "package",
21
21
  package: "@antelopejs/mongodb",
22
- version: "1.0.0",
23
- },
24
- },
25
- database_decorators: {
26
- source: {
27
- type: "package",
28
- package: "@antelopejs/database-decorators",
29
- version: "1.0.0",
22
+ version: "1.3.1",
30
23
  },
31
24
  },
32
25
  api: {
33
26
  source: {
34
27
  type: "package",
35
28
  package: "@antelopejs/api",
36
- version: "1.0.0",
29
+ version: "1.3.0",
37
30
  },
38
31
  config: {
39
32
  servers: [{ protocol: "http", host: "127.0.0.1", port: 5010 }],
33
+ publicBaseUrl: "http://127.0.0.1:5010",
40
34
  },
41
35
  },
42
36
  },
@@ -47,7 +41,7 @@ exports.default = (0, config_1.defineConfig)({
47
41
  return {
48
42
  modules: {
49
43
  mongodb: {
50
- config: { url: mongod.getUri() },
44
+ config: { url: mongod.getUri(), database: "antelopejs_test" },
51
45
  },
52
46
  },
53
47
  };
package/dist/antelope.test.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,8DAAiE;AACjE,2EAA+D;AAE/D,IAAI,MAAyB,CAAC;AAE9B,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,sBAAsB;gBAC/B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE,EAAE,MAAM,EAAE,yBAAyB,EAAE;SAC9C;QACD,OAAO,EAAE;YACP,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,qBAAqB;gBAC9B,OAAO,EAAE,OAAO;aACjB;SACF;QACD,mBAAmB,EAAE;YACnB,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iCAAiC;gBAC1C,OAAO,EAAE,OAAO;aACjB;SACF;QACD,GAAG,EAAE;YACH,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iBAAiB;gBAC1B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;aAC/D;SACF;KACF;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY;QACpB,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,MAAM,8CAAiB,CAAC,MAAM,EAAE,CAAC;YAC1C,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE;qBACjC;iBACF;aACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,2EAA+D;AAC/D,8DAAiE;AAEjE,IAAI,MAAyB,CAAC;AAE9B,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,sBAAsB;gBAC/B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE,EAAE,MAAM,EAAE,yBAAyB,EAAE;SAC9C;QACD,OAAO,EAAE;YACP,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,qBAAqB;gBAC9B,OAAO,EAAE,OAAO;aACjB;SACF;QACD,GAAG,EAAE;YACH,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iBAAiB;gBAC1B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBAC9D,aAAa,EAAE,uBAAuB;aACvC;SACF;KACF;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY;QACpB,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,MAAM,8CAAiB,CAAC,MAAM,EAAE,CAAC;YAC1C,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,iBAAiB,EAAE;qBAC9D;iBACF;aACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC,CAAC"}
package/dist/index.d.ts CHANGED
@@ -45,9 +45,13 @@ export type AuthValidator<T = unknown, R = unknown> = (data: T) => Promise<R> |
45
45
  /**
46
46
  * HTTP Cookie options for controlling how authentication cookies are set.
47
47
  *
48
- * @property maxAge - Number of milliseconds until the cookie expires
49
- * @property signed - Whether the cookie should be signed
50
- * @property expires - Specific date when the cookie expires
48
+ * Keys are serialized literally. False and undefined values are omitted;
49
+ * true values become standalone directives, and other values use String(value).
50
+ * No attributes are supplied by default.
51
+ *
52
+ * @property maxAge - Serialized as maxAge, not the standard Max-Age attribute
53
+ * @property signed - Serialized as a directive; does not add a cookie signature
54
+ * @property expires - Serialized with String(date), not an HTTP-date formatter
51
55
  * @property httpOnly - Whether the cookie is only accessible via HTTP(S) and not client JavaScript
52
56
  * @property path - URL path for which the cookie is valid
53
57
  * @property domain - Domain for which the cookie is valid
@@ -58,7 +62,6 @@ export type AuthValidator<T = unknown, R = unknown> = (data: T) => Promise<R> |
58
62
  * const secureOptions: CookieOptions = {
59
63
  * httpOnly: true,
60
64
  * secure: true,
61
- * maxAge: 3600000, // 1 hour
62
65
  * path: '/'
63
66
  * };
64
67
  * ```
@@ -185,6 +188,8 @@ export declare function ValidateRaw<T = unknown>(token?: string, options?: Verif
185
188
  export declare function SignRaw(data: AuthPayload, options?: SignOptions): Promise<string>;
186
189
  /**
187
190
  * Signs some data and attaches it to an HTTP Response object as a cookie.
191
+ * Replaces the Set-Cookie header with ANTELOPEJS_AUTH and the supplied attributes.
192
+ * Does not send or end the response. See {@link CookieOptions} for serialization limits.
188
193
  *
189
194
  * @param res - HTTP Response object to set the cookie on
190
195
  * @param data - Data to sign and attach
@@ -208,6 +213,8 @@ export declare function SignServerResponse(res: ServerResponse, data: AuthPayloa
208
213
  *
209
214
  * The callbacks are processed in the following order:
210
215
  * `source(req, res)` => `authenticator(prev, authenticatorOptions)` => `validator(prev)` => Parameter
216
+ * A validator must throw to deny access; its return value is injected unchanged.
217
+ * A validator passed to the decorator replaces the configured validator.
211
218
  *
212
219
  * @template R - The type of the final validator result
213
220
  * @template T - The type of the authenticated data before validation
@@ -216,10 +223,13 @@ export declare function SignServerResponse(res: ServerResponse, data: AuthPayloa
216
223
  * @param callbacks.authenticator - Verifies the signature
217
224
  * @param callbacks.authenticatorOptions - Options for verification
218
225
  * @param callbacks.validator - Custom validation step (overrideable with decorator call)
219
- * @returns A decorator for parameters, methods, properties, and classes
226
+ * @returns A decorator for parameters, properties, and classes
220
227
  *
221
228
  * @example
222
229
  * ```typescript
230
+ * import { Controller, Get } from '@antelopejs/interface-api';
231
+ * import { CreateAuthDecorator } from '@antelopejs/interface-auth';
232
+ *
223
233
  * // Create a custom auth decorator
224
234
  * const RequireAdmin = CreateAuthDecorator({
225
235
  * validator: (user: any) => {
@@ -231,11 +241,11 @@ export declare function SignServerResponse(res: ServerResponse, data: AuthPayloa
231
241
  * });
232
242
  *
233
243
  * // Use the decorator
234
- * class AdminController {
235
- * @Route('/admin/settings')
236
- * getSettings(@RequireAdmin() user: UserProfile) {
244
+ * class AdminController extends Controller('/admin') {
245
+ * @Get('settings')
246
+ * getSettings(@RequireAdmin() user: { role: string }) {
237
247
  * // Only admin users can access this
238
- * return { settings: this.adminSettings };
248
+ * return { role: user.role };
239
249
  * }
240
250
  * }
241
251
  * ```
@@ -243,7 +253,9 @@ export declare function SignServerResponse(res: ServerResponse, data: AuthPayloa
243
253
  export declare function CreateAuthDecorator<R = unknown, T = unknown>(callbacks: AuthDecoratorCallbacks<T, R>): (validator?: AuthValidator<T, R> | undefined) => import("@antelopejs/interface-core/decorators").ClassDecorator<import("@antelopejs/interface-core/decorators").Class<any, any[]>> & import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
244
254
  /**
245
255
  * Parameter Provider using the default source and signature verification callbacks.
246
- * This decorator can be applied to parameters, methods, properties, or classes to
256
+ * Reads the raw token from x-antelopejs-auth, falling back to ANTELOPEJS_AUTH
257
+ * only when the header is absent. Does not read Authorization or strip Bearer.
258
+ * This decorator can be applied to parameters, properties, or classes to
247
259
  * require authentication.
248
260
  *
249
261
  * @param validator - Optional custom validation callback
@@ -251,21 +263,15 @@ export declare function CreateAuthDecorator<R = unknown, T = unknown>(callbacks:
251
263
  *
252
264
  * @example
253
265
  * ```typescript
254
- * class UserController {
255
- * @Route('/profile')
256
- * getProfile(@Authentication user: UserProfile) {
266
+ * import { Controller, Get } from '@antelopejs/interface-api';
267
+ * import { Authentication } from '@antelopejs/interface-auth';
268
+ *
269
+ * class UserController extends Controller('/users') {
270
+ * @Get('profile')
271
+ * getProfile(@Authentication() user: { name: string; email: string }) {
257
272
  * // 'user' contains the authenticated user data
258
273
  * return { name: user.name, email: user.email };
259
274
  * }
260
- *
261
- * @Route('/admin')
262
- * adminPage(@Authentication((user) => {
263
- * if (user.role !== 'admin') throw new Error('Admin only');
264
- * return user;
265
- * }) user: UserProfile) {
266
- * // Only admins will reach this code
267
- * return { adminData: this.sensitiveData };
268
- * }
269
275
  * }
270
276
  * ```
271
277
  *
package/dist/index.js CHANGED
@@ -5,8 +5,8 @@ exports.ValidateRaw = ValidateRaw;
5
5
  exports.SignRaw = SignRaw;
6
6
  exports.SignServerResponse = SignServerResponse;
7
7
  exports.CreateAuthDecorator = CreateAuthDecorator;
8
- const interface_api_1 = require("@antelopejs/interface-api");
9
8
  const interface_core_1 = require("@antelopejs/interface-core");
9
+ const interface_api_1 = require("@antelopejs/interface-api");
10
10
  const decorators_1 = require("@antelopejs/interface-core/decorators");
11
11
  const AuthHeaderName = "x-antelopejs-auth";
12
12
  const AuthCookieName = "ANTELOPEJS_AUTH";
@@ -133,6 +133,8 @@ function SignRaw(data, options) {
133
133
  }
134
134
  /**
135
135
  * Signs some data and attaches it to an HTTP Response object as a cookie.
136
+ * Replaces the Set-Cookie header with ANTELOPEJS_AUTH and the supplied attributes.
137
+ * Does not send or end the response. See {@link CookieOptions} for serialization limits.
136
138
  *
137
139
  * @param res - HTTP Response object to set the cookie on
138
140
  * @param data - Data to sign and attach
@@ -161,6 +163,8 @@ function SignServerResponse(res, data, signOptions, cookieOptions) {
161
163
  *
162
164
  * The callbacks are processed in the following order:
163
165
  * `source(req, res)` => `authenticator(prev, authenticatorOptions)` => `validator(prev)` => Parameter
166
+ * A validator must throw to deny access; its return value is injected unchanged.
167
+ * A validator passed to the decorator replaces the configured validator.
164
168
  *
165
169
  * @template R - The type of the final validator result
166
170
  * @template T - The type of the authenticated data before validation
@@ -169,10 +173,13 @@ function SignServerResponse(res, data, signOptions, cookieOptions) {
169
173
  * @param callbacks.authenticator - Verifies the signature
170
174
  * @param callbacks.authenticatorOptions - Options for verification
171
175
  * @param callbacks.validator - Custom validation step (overrideable with decorator call)
172
- * @returns A decorator for parameters, methods, properties, and classes
176
+ * @returns A decorator for parameters, properties, and classes
173
177
  *
174
178
  * @example
175
179
  * ```typescript
180
+ * import { Controller, Get } from '@antelopejs/interface-api';
181
+ * import { CreateAuthDecorator } from '@antelopejs/interface-auth';
182
+ *
176
183
  * // Create a custom auth decorator
177
184
  * const RequireAdmin = CreateAuthDecorator({
178
185
  * validator: (user: any) => {
@@ -184,11 +191,11 @@ function SignServerResponse(res, data, signOptions, cookieOptions) {
184
191
  * });
185
192
  *
186
193
  * // Use the decorator
187
- * class AdminController {
188
- * @Route('/admin/settings')
189
- * getSettings(@RequireAdmin() user: UserProfile) {
194
+ * class AdminController extends Controller('/admin') {
195
+ * @Get('settings')
196
+ * getSettings(@RequireAdmin() user: { role: string }) {
190
197
  * // Only admin users can access this
191
- * return { settings: this.adminSettings };
198
+ * return { role: user.role };
192
199
  * }
193
200
  * }
194
201
  * ```
@@ -207,7 +214,9 @@ function CreateAuthDecorator(callbacks) {
207
214
  }
208
215
  /**
209
216
  * Parameter Provider using the default source and signature verification callbacks.
210
- * This decorator can be applied to parameters, methods, properties, or classes to
217
+ * Reads the raw token from x-antelopejs-auth, falling back to ANTELOPEJS_AUTH
218
+ * only when the header is absent. Does not read Authorization or strip Bearer.
219
+ * This decorator can be applied to parameters, properties, or classes to
211
220
  * require authentication.
212
221
  *
213
222
  * @param validator - Optional custom validation callback
@@ -215,21 +224,15 @@ function CreateAuthDecorator(callbacks) {
215
224
  *
216
225
  * @example
217
226
  * ```typescript
218
- * class UserController {
219
- * @Route('/profile')
220
- * getProfile(@Authentication user: UserProfile) {
227
+ * import { Controller, Get } from '@antelopejs/interface-api';
228
+ * import { Authentication } from '@antelopejs/interface-auth';
229
+ *
230
+ * class UserController extends Controller('/users') {
231
+ * @Get('profile')
232
+ * getProfile(@Authentication() user: { name: string; email: string }) {
221
233
  * // 'user' contains the authenticated user data
222
234
  * return { name: user.name, email: user.email };
223
235
  * }
224
- *
225
- * @Route('/admin')
226
- * adminPage(@Authentication((user) => {
227
- * if (user.role !== 'admin') throw new Error('Admin only');
228
- * return user;
229
- * }) user: UserProfile) {
230
- * // Only admins will reach this code
231
- * return { adminData: this.sensitiveData };
232
- * }
233
236
  * }
234
237
  * ```
235
238
  *
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/tests/index.test.js CHANGED
@@ -1,8 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ const chai_1 = require("chai");
3
4
  const interface_api_1 = require("@antelopejs/interface-api");
4
5
  const interface_auth_1 = require("@antelopejs/interface-auth");
5
- const chai_1 = require("chai");
6
6
  const testUsers = {
7
7
  default: {
8
8
  name: "Bob",
package/dist/tests/index.test.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"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"}
package/docs/1.introduction.md ADDED
@@ -0,0 +1,27 @@
1
+ # Interface Auth Documentation
2
+
3
+ ## Overview
4
+
5
+ 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.
6
+
7
+ This interface depends on the [Interface API](https://github.com/AntelopeJS/interface-api) package, which provides the decorator infrastructure for parameter injection.
8
+
9
+ ## Core concepts
10
+
11
+ The authentication system is built around three main layers:
12
+
13
+ - **Token handling** - Sign and verify authentication tokens using `SignRaw`, `ValidateRaw`, and `SignServerResponse`.
14
+ - **Authentication decorators** - The `@Authentication` decorator and `CreateAuthDecorator` function inject verified user data into handler parameters.
15
+ - **Customizable pipeline** - Configure custom sources, verifiers, and validators to adapt the authentication flow.
16
+
17
+ ## Installation
18
+
19
+ ```bash
20
+ npm install @antelopejs/interface-auth
21
+ ```
22
+
23
+ ## Documentation sections
24
+
25
+ - [Authentication Basics](./2.authentication.md) - Authentication flow, sources, verifiers, and validators
26
+ - [Token Handling](./3.token-handling.md) - Token generation and validation functions
27
+ - [Parameter Decoration](./4.parameter-decoration.md) - Authentication decorators and custom providers
package/docs/2.authentication.md ADDED
@@ -0,0 +1,185 @@
1
+ # Authentication Basics
2
+
3
+ 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.
4
+
5
+ ## Authentication flow
6
+
7
+ A typical authentication flow consists of four steps:
8
+
9
+ 1. **Token generation** - Sign user data into a token using `SignRaw` or `SignServerResponse`.
10
+ 2. **Token storage** - Store the token on the client (cookie, header, local storage).
11
+ 3. **Token validation** - Verify the token when the client makes a request.
12
+ 4. **Authorization** - Check whether the authenticated user has permission to access the requested resource.
13
+
14
+ ### Example authentication flow
15
+
16
+ ```typescript
17
+ import { SignRaw, Authentication } from "@antelopejs/interface-auth";
18
+ import {
19
+ Controller,
20
+ Post,
21
+ Get,
22
+ JSONBody,
23
+ HTTPResult,
24
+ } from "@antelopejs/interface-api";
25
+
26
+ class UserController extends Controller("/users") {
27
+ @Post("login")
28
+ async login(@JSONBody() credentials: { email: string; password: string }) {
29
+ // Validate credentials against your data store
30
+ const user = await validateUserCredentials(credentials);
31
+
32
+ // Step 1: Generate a token
33
+ const token = await SignRaw(
34
+ { userId: user.id, role: user.role },
35
+ { expiresIn: "1h" },
36
+ );
37
+
38
+ // Step 2: Return token to the client
39
+ const result = new HTTPResult(200, {
40
+ success: true,
41
+ user: { id: user.id, role: user.role },
42
+ });
43
+
44
+ result.addHeader(
45
+ "Set-Cookie",
46
+ `ANTELOPEJS_AUTH=${token}; HttpOnly; Path=/`,
47
+ );
48
+
49
+ return result;
50
+ }
51
+
52
+ @Get("profile")
53
+ async getProfile(
54
+ @Authentication() userData: { userId: number; role: string },
55
+ ) {
56
+ // Steps 3 & 4: Token is automatically validated
57
+ // If the token is invalid, an error is thrown before this code runs
58
+ return { user: await getUserProfile(userData.userId) };
59
+ }
60
+ }
61
+ ```
62
+
63
+ ## Authentication sources
64
+
65
+ An `AuthSource` function extracts the authentication token from the incoming HTTP request. The default source checks two locations in order:
66
+
67
+ 1. **Custom header** - The `x-antelopejs-auth` header
68
+ 2. **Cookie** - The `ANTELOPEJS_AUTH` cookie
69
+
70
+ 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`.
71
+
72
+ ### Create a custom source
73
+
74
+ Implement the `AuthSource` type to extract tokens from a different location.
75
+
76
+ ```ts docs-check
77
+ import { CreateAuthDecorator, AuthSource } from "@antelopejs/interface-auth";
78
+ import type { IncomingMessage } from "node:http";
79
+
80
+ const bearerTokenSource: AuthSource = (req: IncomingMessage) => {
81
+ const header = req.headers.authorization;
82
+ if (header?.startsWith("Bearer ")) {
83
+ return header.slice(7);
84
+ }
85
+ return undefined;
86
+ };
87
+
88
+ const BearerAuth = CreateAuthDecorator({
89
+ source: bearerTokenSource,
90
+ });
91
+ ```
92
+
93
+ The `AuthSource` type signature is:
94
+
95
+ ```typescript
96
+ type AuthSource = (
97
+ req: IncomingMessage,
98
+ res: ServerResponse,
99
+ ) => string | undefined;
100
+ ```
101
+
102
+ ## Authentication verifiers
103
+
104
+ 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).
105
+
106
+ ### Create a custom verifier
107
+
108
+ ```ts docs-check
109
+ import {
110
+ CreateAuthDecorator,
111
+ AuthVerifier,
112
+ ValidateRaw,
113
+ } from "@antelopejs/interface-auth";
114
+
115
+ const userVerifier: AuthVerifier<{ userId: string }> = async (
116
+ data,
117
+ options,
118
+ ) => {
119
+ const payload = await ValidateRaw<unknown>(data, options);
120
+ if (
121
+ typeof payload !== "object" ||
122
+ payload === null ||
123
+ !("userId" in payload) ||
124
+ typeof payload.userId !== "string"
125
+ ) {
126
+ throw new Error("Invalid user payload");
127
+ }
128
+ return { userId: payload.userId };
129
+ };
130
+
131
+ const UserAuth = CreateAuthDecorator({
132
+ authenticator: userVerifier,
133
+ });
134
+ ```
135
+
136
+ 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.
137
+
138
+ The `AuthVerifier` type signature is:
139
+
140
+ ```typescript
141
+ type AuthVerifier<T = unknown> = (
142
+ data?: string,
143
+ options?: VerifyOptions,
144
+ ) => Promise<T> | T;
145
+ ```
146
+
147
+ ## Authentication validators
148
+
149
+ 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.
150
+
151
+ ```typescript
152
+ import { CreateAuthDecorator, AuthValidator } from "@antelopejs/interface-auth";
153
+
154
+ interface UserPayload {
155
+ userId: number;
156
+ role: string;
157
+ }
158
+
159
+ const adminValidator: AuthValidator<UserPayload, UserPayload> = (userData) => {
160
+ if (!userData || userData.role !== "admin") {
161
+ throw new Error("Admin access required");
162
+ }
163
+ return userData;
164
+ };
165
+
166
+ const AdminOnly = CreateAuthDecorator({
167
+ validator: adminValidator,
168
+ });
169
+ ```
170
+
171
+ The `AuthValidator` type signature is:
172
+
173
+ ```typescript
174
+ type AuthValidator<T = unknown, R = unknown> = (data: T) => Promise<R> | R;
175
+ ```
176
+
177
+ ## Authentication pipeline
178
+
179
+ The complete authentication pipeline processes the request through three stages:
180
+
181
+ ```
182
+ source(req, res) => authenticator(token, options) => validator(data) => Parameter
183
+ ```
184
+
185
+ 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 ADDED
@@ -0,0 +1,131 @@
1
+ # Token Handling
2
+
3
+ The Interface Auth provides functions for generating and validating authentication tokens. These functions serve as the foundation for the authentication system.
4
+
5
+ ## Token generation
6
+
7
+ ### `SignRaw`
8
+
9
+ The `SignRaw` function signs arbitrary data and returns a token string.
10
+
11
+ ```typescript
12
+ import { SignRaw } from "@antelopejs/interface-auth";
13
+
14
+ const token = await SignRaw(
15
+ { userId: 123, role: "admin" },
16
+ { expiresIn: "1h" },
17
+ );
18
+
19
+ console.log(token); // Signed token string
20
+ ```
21
+
22
+ The function accepts two arguments:
23
+
24
+ | Argument | Type | Description |
25
+ | --------- | ---------------------------- | ----------------------------- |
26
+ | `data` | `string \| Buffer \| object` | The data to sign |
27
+ | `options` | `SignOptions` (optional) | Signing configuration options |
28
+
29
+ `SignRaw` returns a `Promise<string>` that resolves to the signed token.
30
+
31
+ ### `SignOptions`
32
+
33
+ The `SignOptions` interface configures token generation.
34
+
35
+ | Property | Type | Description |
36
+ | ----------- | ------------------ | ---------------------------------------------------------------------------- |
37
+ | `expiresIn` | `string \| number` | Token expiration time as seconds or a timespan string (e.g., `"1h"`, `"2d"`) |
38
+ | `notBefore` | `string \| number` | Duration before which the token is not valid |
39
+
40
+ ### `SignServerResponse`
41
+
42
+ The `SignServerResponse` function signs data and attaches the resulting token as a cookie on the HTTP response.
43
+
44
+ ```typescript
45
+ import { SignServerResponse } from "@antelopejs/interface-auth";
46
+ import type { ServerResponse } from "node:http";
47
+
48
+ async function login(res: ServerResponse) {
49
+ const userData = { userId: 123, role: "user" };
50
+
51
+ await SignServerResponse(
52
+ res,
53
+ userData,
54
+ { expiresIn: "1h" },
55
+ { httpOnly: true, secure: true, path: "/" },
56
+ );
57
+ }
58
+ ```
59
+
60
+ The function accepts four arguments:
61
+
62
+ | Argument | Type | Description |
63
+ | --------------- | ---------------------------- | ----------------------------- |
64
+ | `res` | `ServerResponse` | The HTTP response object |
65
+ | `data` | `string \| Buffer \| object` | The data to sign |
66
+ | `signOptions` | `SignOptions` (optional) | Signing configuration options |
67
+ | `cookieOptions` | `CookieOptions` (optional) | Cookie configuration options |
68
+
69
+ 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.
70
+
71
+ ### `CookieOptions`
72
+
73
+ 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)`.
74
+
75
+ | Property | Type | Description |
76
+ | ---------- | --------- | ------------------------------------------------------------------------------- |
77
+ | `maxAge` | `number` | Written as `maxAge=<number>`; not converted to the standard `Max-Age` attribute |
78
+ | `signed` | `boolean` | Written as a directive when true; does not add a cookie signature |
79
+ | `expires` | `Date` | Written using `String(date)`, not an explicit HTTP-date formatter |
80
+ | `httpOnly` | `boolean` | Prevents client-side JavaScript from accessing the cookie |
81
+ | `path` | `string` | URL path for which the cookie is valid |
82
+ | `domain` | `string` | Domain for which the cookie is valid |
83
+ | `secure` | `boolean` | Only sends the cookie over HTTPS |
84
+
85
+ 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.
86
+
87
+ ## Token validation
88
+
89
+ ### `ValidateRaw`
90
+
91
+ The `ValidateRaw` function verifies a token and returns the data contained within it.
92
+
93
+ ```typescript
94
+ import { ValidateRaw } from "@antelopejs/interface-auth";
95
+
96
+ try {
97
+ const userData = await ValidateRaw<{ userId: number; role: string }>(token);
98
+ console.log(userData); // { userId: 123, role: "admin" }
99
+ } catch (error) {
100
+ console.error("Invalid token:", error.message);
101
+ }
102
+ ```
103
+
104
+ The function accepts two arguments:
105
+
106
+ | Argument | Type | Description |
107
+ | --------- | -------------------------- | -------------------------- |
108
+ | `token` | `string` (optional) | The signed token to verify |
109
+ | `options` | `VerifyOptions` (optional) | Verification configuration |
110
+
111
+ ### `VerifyOptions`
112
+
113
+ The `VerifyOptions` interface configures token validation.
114
+
115
+ | Property | Type | Description |
116
+ | ------------------ | ------------------ | ---------------------------------------------------- |
117
+ | `ignoreExpiration` | `boolean` | If `true`, expired tokens are still considered valid |
118
+ | `ignoreNotBefore` | `boolean` | If `true`, tokens not yet valid are accepted |
119
+ | `maxAge` | `string \| number` | Maximum allowed age of the token |
120
+
121
+ ### Example with verify options
122
+
123
+ ```typescript
124
+ import { ValidateRaw } from "@antelopejs/interface-auth";
125
+
126
+ // Accept tokens up to 30 minutes old, ignoring the not-before field
127
+ const userData = await ValidateRaw(token, {
128
+ maxAge: "30m",
129
+ ignoreNotBefore: true,
130
+ });
131
+ ```
package/docs/4.parameter-decoration.md ADDED
@@ -0,0 +1,174 @@
1
+ # Parameter Decoration
2
+
3
+ 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.
4
+
5
+ ## The `@Authentication` decorator
6
+
7
+ 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.
8
+
9
+ ```typescript
10
+ import { Controller, Get } from "@antelopejs/interface-api";
11
+ import { Authentication } from "@antelopejs/interface-auth";
12
+
13
+ class UserController extends Controller("/users") {
14
+ @Get("profile")
15
+ async getProfile(@Authentication() user: { id: string; name: string }) {
16
+ return {
17
+ id: user.id,
18
+ name: user.name,
19
+ };
20
+ }
21
+ }
22
+ ```
23
+
24
+ If the token is missing or invalid, the request fails with an error response before the handler executes.
25
+
26
+ ### Inline validators
27
+
28
+ Pass a validator function directly to the `@Authentication` decorator for one-off validation logic.
29
+
30
+ ```typescript
31
+ import { Controller, Post } from "@antelopejs/interface-api";
32
+ import { Authentication } from "@antelopejs/interface-auth";
33
+
34
+ class PaymentController extends Controller("/payments") {
35
+ @Post()
36
+ async createPayment(
37
+ @Authentication((user: any) => {
38
+ if (!user.paymentPermissions) {
39
+ throw new Error("Payment permissions required");
40
+ }
41
+ return user;
42
+ })
43
+ user: any,
44
+ ) {
45
+ // Process payment
46
+ return { success: true };
47
+ }
48
+ }
49
+ ```
50
+
51
+ ## Create custom decorators with `CreateAuthDecorator`
52
+
53
+ The `CreateAuthDecorator` function creates a reusable authentication decorator with custom source, authenticator, and validator functions.
54
+
55
+ ```typescript
56
+ import { CreateAuthDecorator } from "@antelopejs/interface-auth";
57
+ import type { IncomingMessage } from "node:http";
58
+
59
+ // Admin-only decorator
60
+ export const AdminAuth = CreateAuthDecorator({
61
+ validator: (user: any) => {
62
+ if (!user || user.role !== "admin") {
63
+ throw new Error("Admin access required");
64
+ }
65
+ return user;
66
+ },
67
+ });
68
+
69
+ // API key decorator with custom source and authenticator
70
+ export const ApiKeyAuth = CreateAuthDecorator({
71
+ source: (req: IncomingMessage) => req.headers["x-api-key"] as string,
72
+ authenticator: async (apiKey?: string) => {
73
+ if (!apiKey) return null;
74
+ const user = await validateApiKey(apiKey);
75
+ return user;
76
+ },
77
+ });
78
+ ```
79
+
80
+ ### `CreateAuthDecorator` options
81
+
82
+ The function accepts an object with the following properties:
83
+
84
+ | Property | Type | Description |
85
+ | ---------------------- | --------------------- | --------------------------------------------------------------- |
86
+ | `source` | `AuthSource` | Extracts the token from the request (defaults to header/cookie) |
87
+ | `authenticator` | `AuthVerifier<T>` | Verifies the token and returns the payload |
88
+ | `authenticatorOptions` | `VerifyOptions` | Options passed to the authenticator |
89
+ | `validator` | `AuthValidator<T, R>` | Validates and transforms the authenticated data |
90
+
91
+ 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.
92
+
93
+ 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.
94
+
95
+ ## Class-level authentication
96
+
97
+ 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.
98
+
99
+ ```typescript
100
+ import { Controller, Get, Post } from "@antelopejs/interface-api";
101
+ import { Authentication } from "@antelopejs/interface-auth";
102
+
103
+ @Authentication()
104
+ class UserController extends Controller("/users") {
105
+ @Get("profile")
106
+ async getProfile() {
107
+ // Only authenticated users can access this endpoint
108
+ return { message: "Authenticated profile access" };
109
+ }
110
+
111
+ @Post("settings")
112
+ async updateSettings() {
113
+ // This route is also protected
114
+ return { success: true };
115
+ }
116
+ }
117
+ ```
118
+
119
+ ### Class-level with role-based access
120
+
121
+ Combine class-level authentication with a validator to enforce role-based access for all routes in a controller.
122
+
123
+ ```typescript
124
+ import { Controller } from "@antelopejs/interface-api";
125
+ import { Authentication } from "@antelopejs/interface-auth";
126
+
127
+ @Authentication((user: any) => {
128
+ if (!user || user.role !== "admin") {
129
+ throw new Error("Admin access required");
130
+ }
131
+ return user;
132
+ })
133
+ class AdminController extends Controller("/admin") {
134
+ // All routes require admin authentication
135
+ }
136
+ ```
137
+
138
+ ## Property-level authentication
139
+
140
+ Apply `@Authentication` to a class property to access the authenticated user data throughout the controller. The property is populated automatically for each request.
141
+
142
+ ```typescript
143
+ import { Controller, Get } from "@antelopejs/interface-api";
144
+ import { Authentication } from "@antelopejs/interface-auth";
145
+
146
+ class UserController extends Controller("/users") {
147
+ @Authentication()
148
+ private user!: { id: string; name: string };
149
+
150
+ @Get("profile")
151
+ async getProfile() {
152
+ return {
153
+ id: this.user.id,
154
+ name: this.user.name,
155
+ };
156
+ }
157
+
158
+ @Get("settings")
159
+ async getSettings() {
160
+ // The same user data is available in all handlers
161
+ return { userId: this.user.id, theme: "dark" };
162
+ }
163
+ }
164
+ ```
165
+
166
+ ## Decorator scope summary
167
+
168
+ The `@Authentication` decorator (and any custom decorator created with `CreateAuthDecorator`) can be applied at three levels:
169
+
170
+ | Scope | Effect |
171
+ | --------- | --------------------------------------------------------------------- |
172
+ | Parameter | Injects the verified payload into a single handler parameter |
173
+ | Property | Populates a class property with the verified payload for all handlers |
174
+ | Class | Requires authentication for every route in the controller |
package/docs/tsconfig.json ADDED
@@ -0,0 +1,12 @@
1
+ {
2
+ "extends": "../tsconfig.json",
3
+ "compilerOptions": {
4
+ "module": "ESNext",
5
+ "moduleResolution": "node",
6
+ "rootDir": "..",
7
+ "composite": false,
8
+ "incremental": false,
9
+ "noEmit": true
10
+ },
11
+ "include": ["../src", "./**/*.ts"]
12
+ }
package/package.json CHANGED
@@ -1,24 +1,31 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-auth",
3
- "version": "0.0.5",
4
- "description": "AntelopeJS interface for JWT authentication and session management",
3
+ "version": "0.0.7",
4
+ "description": "AntelopeJS interface for token authentication: sign and verify tokens and inject the verified payload into API handlers",
5
5
  "keywords": [
6
6
  "antelopejs",
7
- "interface",
8
7
  "auth",
9
- "jwt"
8
+ "authentication",
9
+ "interface",
10
+ "jwt",
11
+ "token"
10
12
  ],
13
+ "homepage": "https://interfaces.antelopejs.com/docs/auth",
14
+ "bugs": {
15
+ "url": "https://github.com/AntelopeJS/interface-auth/issues"
16
+ },
17
+ "license": "Apache-2.0",
11
18
  "repository": {
12
19
  "type": "git",
13
20
  "url": "git+https://github.com/AntelopeJS/interface-auth.git"
14
21
  },
15
- "license": "Apache-2.0",
16
- "packageManager": "pnpm@10.6.5",
17
- "main": "dist/index.js",
18
- "types": "dist/index.d.ts",
19
22
  "files": [
20
- "dist"
23
+ "dist",
24
+ "docs",
25
+ "skills"
21
26
  ],
27
+ "main": "dist/index.js",
28
+ "types": "dist/index.d.ts",
22
29
  "exports": {
23
30
  ".": {
24
31
  "types": "./dist/index.d.ts",
@@ -26,38 +33,51 @@
26
33
  },
27
34
  "./package.json": "./package.json"
28
35
  },
36
+ "publishConfig": {
37
+ "access": "public",
38
+ "provenance": true
39
+ },
29
40
  "scripts": {
30
41
  "build": "rimraf dist && tsc",
31
- "format": "biome format --write .",
32
- "lint:fix": "biome check --write .",
33
- "lint": "biome check .",
42
+ "format": "oxfmt .",
43
+ "lint:fix": "oxlint --fix",
44
+ "lint": "oxlint",
34
45
  "prepack": "pnpm run build",
35
46
  "release": "pnpm run lint && pnpm run prepack && release-it",
36
- "test": "pnpm run build && ajs module test ."
47
+ "test": "pnpm run build && ajs module test .",
48
+ "format:check": "oxfmt --check .",
49
+ "knip": "knip"
37
50
  },
38
51
  "devDependencies": {
39
- "@antelopejs/interface-api": "^0.0.5",
40
- "@antelopejs/interface-core": "^0.0.5",
41
- "@biomejs/biome": "2.3.2",
52
+ "@antelopejs/core": "^1.16.0",
53
+ "@antelopejs/interface-api": "^0.0.15",
54
+ "@antelopejs/interface-core": "^0.2.4",
55
+ "@antelopejs/tooling-configs": "^0.0.9",
42
56
  "@types/chai": "^4.3.20",
43
57
  "@types/mocha": "^10.0.10",
44
58
  "@types/node": "^22.19.15",
45
59
  "@types/semver": "^7.7.1",
46
60
  "chai": "^4.5.0",
61
+ "eslint-plugin-perfectionist": "^5.11.0",
62
+ "knip": "^6.34.0",
47
63
  "mongodb-memory-server-core": "^10.4.3",
64
+ "oxfmt": "^0.66.0",
65
+ "oxlint": "1.81.0",
66
+ "oxlint-tsgolint": "^7.0.2001",
48
67
  "release-it": "^19.2.4",
49
68
  "release-it-changelogen": "^0.1.0",
50
69
  "rimraf": "^6.1.3",
51
70
  "typescript": "^5.9.3"
52
71
  },
53
72
  "peerDependencies": {
54
- "@antelopejs/interface-api": ">=0.0.3 <1.0.0",
55
- "@antelopejs/interface-core": ">=0.0.3 <1.0.0"
56
- },
57
- "publishConfig": {
58
- "access": "public"
73
+ "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
74
+ "@antelopejs/interface-core": ">=0.2.4 <1.0.0"
59
75
  },
76
+ "packageManager": "pnpm@10.6.5",
60
77
  "antelopeJs": {
61
- "test": "src/antelope.test.ts"
78
+ "test": "src/antelope.test.ts",
79
+ "skills": [
80
+ "./skills"
81
+ ]
62
82
  }
63
83
  }
package/skills/auth-interface/SKILL.md ADDED
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: auth-interface
3
+ 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.
4
+ category: antelopejs-interface
5
+ tags: [antelopejs, auth, jwt, tokens, decorators]
6
+ ---
7
+
8
+ # @antelopejs/interface-auth
9
+
10
+ Token authentication for AntelopeJS modules. Two layers:
11
+
12
+ - **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.
13
+ - **Consumer-side helpers** (no crossing by themselves): `Authentication` and `CreateAuthDecorator`, which build parameter providers on top of `@antelopejs/interface-api`.
14
+
15
+ ## Imports
16
+
17
+ All symbols come from the package root (the exports map exposes no other code subpaths):
18
+
19
+ ```ts
20
+ import {
21
+ Authentication,
22
+ CreateAuthDecorator,
23
+ SignRaw,
24
+ ValidateRaw,
25
+ SignServerResponse,
26
+ internal, // provider side only
27
+ type AuthSource,
28
+ type AuthVerifier,
29
+ type AuthValidator,
30
+ type SignOptions,
31
+ type VerifyOptions,
32
+ type CookieOptions,
33
+ } from "@antelopejs/interface-auth";
34
+ ```
35
+
36
+ `@antelopejs/interface-api` and `@antelopejs/interface-core` are peerDependencies — the consuming module must have them installed.
37
+
38
+ ## Consuming
39
+
40
+ ```ts
41
+ import { Controller, Get, Post } from "@antelopejs/interface-api";
42
+ import { Authentication, SignRaw } from "@antelopejs/interface-auth";
43
+
44
+ interface LibrarianSession {
45
+ id: string;
46
+ branch: string;
47
+ }
48
+
49
+ class LibrarianController extends Controller("/librarians") {
50
+ @Post("login")
51
+ async login() {
52
+ // Sign a payload into a token (proxy call to the auth provider)
53
+ return SignRaw({ id: "lib-7", branch: "riverside" }, { expiresIn: "1h" });
54
+ }
55
+
56
+ @Get("desk")
57
+ async getDesk(@Authentication() librarian: LibrarianSession) {
58
+ // Token was read from the request, verified, and injected
59
+ return { id: librarian.id, branch: librarian.branch };
60
+ }
61
+ }
62
+ ```
63
+
64
+ Custom pipelines use `CreateAuthDecorator({ source?, authenticator?, authenticatorOptions?, validator? })`; the callbacks run as `source(req, res)` → `authenticator(data, authenticatorOptions)` → `validator(data)` → injected parameter.
65
+
66
+ ## Providing
67
+
68
+ An auth backend module implements the two proxy points:
69
+
70
+ ```ts
71
+ import { ImplementInterface } from "@antelopejs/interface-core";
72
+ import { internal } from "@antelopejs/interface-auth";
73
+
74
+ ImplementInterface(internal, {
75
+ Verify: (token, options) => decodeAndVerify(token, options), // return payload, throw on invalid
76
+ Sign: (data, options) => signToken(data, options), // return token string
77
+ });
78
+ ```
79
+
80
+ Declare `"antelopeJs": { "implements": ["@antelopejs/interface-auth"] }` in the provider's package.json.
81
+
82
+ ## Gotchas
83
+
84
+ - `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.
85
+ - 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`.
86
+ - `@Authentication(validator?)` accepts an optional validator at the use site; it overrides any validator configured in `CreateAuthDecorator`.
87
+ - 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.
88
+ - `expiresIn` / `notBefore` (SignOptions) and `maxAge` (VerifyOptions) accept a number of seconds or a timespan string such as `"1h"`.
89
+ - Rejection is exception-based: a failed verification or validator throws, it does not return `undefined`.
90
+
91
+ ## Deeper reference
92
+
93
+ 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.