@auth0/auth0-express 1.0.0-beta.1 → 1.0.0-beta.2

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 (81) hide show
  1. package/README.md +25 -2
  2. package/dist/app-base-url.d.ts +31 -0
  3. package/dist/app-base-url.d.ts.map +1 -0
  4. package/dist/app-base-url.js +102 -0
  5. package/dist/app-base-url.js.map +1 -0
  6. package/dist/config.d.ts +15 -0
  7. package/dist/config.d.ts.map +1 -0
  8. package/dist/config.js +102 -0
  9. package/dist/config.js.map +1 -0
  10. package/dist/errors/index.d.ts +6 -0
  11. package/dist/errors/index.d.ts.map +1 -0
  12. package/dist/errors/index.js +9 -0
  13. package/dist/errors/index.js.map +1 -0
  14. package/dist/handlers/backchannel-logout-handler.d.ts +3 -0
  15. package/dist/handlers/backchannel-logout-handler.d.ts.map +1 -0
  16. package/dist/handlers/backchannel-logout-handler.js +15 -0
  17. package/dist/handlers/backchannel-logout-handler.js.map +1 -0
  18. package/dist/handlers/callback-handler.d.ts +4 -0
  19. package/dist/handlers/callback-handler.d.ts.map +1 -0
  20. package/dist/handlers/callback-handler.js +18 -0
  21. package/dist/handlers/callback-handler.js.map +1 -0
  22. package/dist/handlers/login-handler.d.ts +4 -0
  23. package/dist/handlers/login-handler.d.ts.map +1 -0
  24. package/dist/handlers/login-handler.js +64 -0
  25. package/dist/handlers/login-handler.js.map +1 -0
  26. package/dist/handlers/logout-handler.d.ts +4 -0
  27. package/dist/handlers/logout-handler.d.ts.map +1 -0
  28. package/dist/handlers/logout-handler.js +15 -0
  29. package/dist/handlers/logout-handler.js.map +1 -0
  30. package/dist/index.d.ts +11 -343
  31. package/dist/index.d.ts.map +1 -0
  32. package/dist/index.js +8 -521
  33. package/dist/index.js.map +1 -1
  34. package/dist/middleware/claim-auth.d.ts +28 -0
  35. package/dist/middleware/claim-auth.d.ts.map +1 -0
  36. package/dist/middleware/claim-auth.js +2 -0
  37. package/dist/middleware/claim-auth.js.map +1 -0
  38. package/dist/middleware/claim-check.d.ts +41 -0
  39. package/dist/middleware/claim-check.d.ts.map +1 -0
  40. package/dist/middleware/claim-check.js +62 -0
  41. package/dist/middleware/claim-check.js.map +1 -0
  42. package/dist/middleware/claim-equals.d.ts +27 -0
  43. package/dist/middleware/claim-equals.d.ts.map +1 -0
  44. package/dist/middleware/claim-equals.js +48 -0
  45. package/dist/middleware/claim-equals.js.map +1 -0
  46. package/dist/middleware/claim-includes.d.ts +37 -0
  47. package/dist/middleware/claim-includes.d.ts.map +1 -0
  48. package/dist/middleware/claim-includes.js +68 -0
  49. package/dist/middleware/claim-includes.js.map +1 -0
  50. package/dist/middleware/require-auth.d.ts +44 -0
  51. package/dist/middleware/require-auth.d.ts.map +1 -0
  52. package/dist/middleware/require-auth.js +57 -0
  53. package/dist/middleware/require-auth.js.map +1 -0
  54. package/dist/router.d.ts +34 -0
  55. package/dist/router.d.ts.map +1 -0
  56. package/dist/router.js +76 -0
  57. package/dist/router.js.map +1 -0
  58. package/dist/store/express-cookie-handler.d.ts +17 -0
  59. package/dist/store/express-cookie-handler.d.ts.map +1 -0
  60. package/dist/store/express-cookie-handler.js +30 -0
  61. package/dist/store/express-cookie-handler.js.map +1 -0
  62. package/dist/store/request-context.d.ts +36 -0
  63. package/dist/store/request-context.d.ts.map +1 -0
  64. package/dist/store/request-context.js +49 -0
  65. package/dist/store/request-context.js.map +1 -0
  66. package/dist/types/express.d.ts +13 -0
  67. package/dist/types/express.d.ts.map +1 -0
  68. package/dist/types/express.js +2 -0
  69. package/dist/types/express.js.map +1 -0
  70. package/dist/types.d.ts +125 -0
  71. package/dist/types.d.ts.map +1 -0
  72. package/dist/types.js +2 -0
  73. package/dist/types.js.map +1 -0
  74. package/dist/utils.d.ts +35 -0
  75. package/dist/utils.d.ts.map +1 -0
  76. package/dist/utils.js +146 -0
  77. package/dist/utils.js.map +1 -0
  78. package/package.json +9 -8
  79. package/dist/index.cjs +0 -566
  80. package/dist/index.cjs.map +0 -1
  81. package/dist/index.d.cts +0 -343
package/dist/index.d.cts DELETED
@@ -1,343 +0,0 @@
1
- import { Request, Response, Router, NextFunction } from 'express';
2
- import { DomainResolver, SessionStore, SessionConfiguration, DiscoveryCacheOptions, ServerClient } from '@auth0/auth0-server-js';
3
- export { DiscoveryCacheOptions, DomainResolver, InvalidConfigurationError } from '@auth0/auth0-server-js';
4
-
5
- /**
6
- * Options passed to custom session store implementations.
7
- *
8
- * These options provide access to the Express request and response objects,
9
- * which are needed for cookie and session management operations.
10
- *
11
- * @example
12
- * ```typescript
13
- * class CustomSessionStore implements SessionStore<StoreOptions> {
14
- * async get(id: string, options: StoreOptions) {
15
- * const { request, response } = options;
16
- * // Access cookies, headers, etc.
17
- * }
18
- * }
19
- * ```
20
- */
21
- interface StoreOptions {
22
- /** Express request object */
23
- request: Request;
24
- /** Express response object */
25
- response: Response;
26
- }
27
- /**
28
- * Configuration options for Auth0 authentication in Express applications.
29
- *
30
- * Environment variable support:
31
- * - AUTH0_DOMAIN or ISSUER_BASE_URL: Auth0 domain
32
- * - AUTH0_CLIENT_ID or CLIENT_ID: Client ID
33
- * - AUTH0_CLIENT_SECRET or CLIENT_SECRET: Client secret
34
- * - APP_BASE_URL or BASE_URL: Application base URL
35
- * - AUTH0_SESSION_SECRET or SECRET: Session encryption secret
36
- * - AUTH0_AUDIENCE: Optional API audience
37
- *
38
- * @example
39
- * ```typescript
40
- * const options: Auth0Options = {
41
- * domain: 'tenant.auth0.com',
42
- * clientId: 'your_client_id',
43
- * clientSecret: 'your_client_secret',
44
- * appBaseUrl: 'http://localhost:3000',
45
- * sessionSecret: process.env.SESSION_SECRET
46
- * };
47
- * ```
48
- */
49
- interface Auth0Options {
50
- /**
51
- * Auth0 domain (e.g., 'tenant.auth0.com') without protocol.
52
- *
53
- * Provide a `DomainResolver` function to resolve the Auth0 custom domain
54
- * per request (Multiple Custom Domains). The resolver receives the Express
55
- * request context (`{ request, response }`) and returns the domain string.
56
- */
57
- domain: string | DomainResolver<StoreOptions>;
58
- /** Auth0 application client ID */
59
- clientId: string;
60
- /** Auth0 application client secret (required for token exchange) */
61
- clientSecret?: string;
62
- /** Private key for client assertion authentication (alternative to clientSecret) */
63
- clientAssertionSigningKey?: string | CryptoKey;
64
- /** Algorithm for client assertion signing (e.g., 'RS256') */
65
- clientAssertionSigningAlg?: string;
66
- /** API audience for requesting access tokens */
67
- audience?: string;
68
- /**
69
- * Base URL of your application (e.g., 'http://localhost:3000').
70
- *
71
- * - Provide a single URL string for a static base URL (default behavior).
72
- * - Provide an array of allowed URLs to validate the incoming request origin
73
- * against an allow-list (recommended for dynamic/preview deployments).
74
- * - Omit it (or set `APP_BASE_URL`/`BASE_URL` empty) to infer the base URL
75
- * from the incoming request host at runtime.
76
- */
77
- appBaseUrl?: string | string[];
78
- /** Enable Pushed Authorization Requests (PAR) for enhanced security */
79
- pushedAuthorizationRequests?: boolean;
80
- /** Secret for encrypting session cookies (minimum 32 characters recommended) */
81
- sessionSecret: string;
82
- /** Custom session store implementation (defaults to cookie-based sessions) */
83
- sessionStore?: SessionStore<StoreOptions>;
84
- /** Advanced session configuration (cookie settings, timeouts, etc.) */
85
- sessionConfiguration?: SessionConfiguration;
86
- /**
87
- * Whether to mount the default routes for login, logout, callback and backchannel logout.
88
- * Routes: /auth/login, /auth/callback, /auth/logout, /auth/backchannel-logout
89
- * @default true
90
- */
91
- mountRoutes?: boolean;
92
- /**
93
- * Custom fetch implementation for HTTP requests.
94
- * Useful for proxies, custom headers, or testing.
95
- */
96
- customFetch?: typeof fetch;
97
- /**
98
- * Optional discovery cache configuration for OIDC metadata and JWKS.
99
- * `ttl` is in seconds. Cache entries are scoped per resolved domain, which
100
- * matters for MCD deployments serving many domains. Defaults to the
101
- * `ServerClient` defaults (TTL 600s, max 100 entries) when omitted.
102
- */
103
- discoveryCache?: DiscoveryCacheOptions;
104
- /** Custom paths for authentication routes (only used if mountRoutes is true) */
105
- routes?: {
106
- /** Login route path @default '/auth/login' */
107
- login?: string;
108
- /** OAuth callback route path @default '/auth/callback' */
109
- callback?: string;
110
- /** Logout route path @default '/auth/logout' */
111
- logout?: string;
112
- /** Backchannel logout route path @default '/auth/backchannel-logout' */
113
- backchannelLogout?: string;
114
- };
115
- }
116
-
117
- declare global {
118
- namespace Express {
119
- interface Request {
120
- auth0: {
121
- client: ServerClient<StoreOptions>;
122
- };
123
- }
124
- }
125
- }
126
-
127
- /**
128
- * Creates an Express router with Auth0 authentication middleware.
129
- *
130
- * This is the main entry point for the Auth0 Express SDK. It configures
131
- * authentication routes and attaches the Auth0 client to the request object.
132
- *
133
- * @param opts - Configuration options for Auth0 authentication
134
- * @returns Express Router configured with Auth0 authentication
135
- *
136
- * @example
137
- * ```typescript
138
- * import express from 'express';
139
- * import { createAuth0 } from '@auth0/auth0-express';
140
- *
141
- * const app = express();
142
- *
143
- * // Using environment variables (AUTH0_DOMAIN, AUTH0_CLIENT_ID, etc.)
144
- * app.use(createAuth0());
145
- *
146
- * // Or with explicit configuration
147
- * app.use(createAuth0({
148
- * domain: 'tenant.auth0.com',
149
- * clientId: 'your_client_id',
150
- * clientSecret: 'your_client_secret',
151
- * appBaseUrl: 'http://localhost:3000',
152
- * sessionSecret: process.env.SESSION_SECRET
153
- * }));
154
- * ```
155
- */
156
- declare function createAuth0(opts?: Partial<Auth0Options>): Router;
157
-
158
- /**
159
- * Options for the requiresAuth middleware.
160
- */
161
- interface RequiresAuthOptions {
162
- /**
163
- * If true, returns a 401 status instead of redirecting to login.
164
- * Useful for API routes that should not redirect.
165
- *
166
- * Default: false (redirects to login)
167
- */
168
- returnTo?: string;
169
- }
170
- /**
171
- * Middleware to require authentication for a route.
172
- *
173
- * If the user is not authenticated:
174
- * - For HTML requests (browser): Redirects to /auth/login with returnTo parameter
175
- * - For API requests (JSON): Returns 401 Unauthorized
176
- *
177
- * @param options - Optional configuration for the middleware
178
- * @returns Express middleware function
179
- *
180
- * @example
181
- * ```typescript
182
- * // Protect a route
183
- * app.get('/profile', requiresAuth(), (req, res) => {
184
- * res.json({ user: await req.auth0.client.getUser() });
185
- * });
186
- *
187
- * // Protect an API route (returns 401 instead of redirecting)
188
- * app.get('/api/me', requiresAuth(), async (req, res) => {
189
- * const user = await req.auth0.client.getUser();
190
- * res.json({ user });
191
- * });
192
- *
193
- * // Custom return URL after login
194
- * app.get('/admin', requiresAuth({ returnTo: '/admin' }), (req, res) => {
195
- * res.send('Admin page');
196
- * });
197
- * ```
198
- */
199
- declare function requiresAuth(options?: RequiresAuthOptions): (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
200
-
201
- /**
202
- * Type for a function that checks claims and returns true if authorized.
203
- *
204
- * @param req - The Express request, for authorization logic that depends on the
205
- * request (e.g. route params, query, headers).
206
- * @param claims - The authenticated user's claims.
207
- */
208
- type ClaimCheckFunction = (req: Request, claims: Record<string, unknown>) => boolean | Promise<boolean>;
209
- /**
210
- * Options for claim-based authorization middleware.
211
- */
212
- interface ClaimAuthOptions {
213
- /**
214
- * Custom error message to send when authorization fails.
215
- */
216
- errorMessage?: string;
217
- /**
218
- * Custom status code to return when authorization fails.
219
- * Default: 403 (Forbidden)
220
- */
221
- statusCode?: number;
222
- }
223
- /**
224
- * Primitive JSON types that can be compared.
225
- */
226
- type JSONPrimitive = string | number | boolean | null;
227
-
228
- /**
229
- * Middleware to check if a claim includes specific values.
230
- *
231
- * The claim may be an array, or a space-delimited string (such as a
232
- * scope-style `"read:users delete:users"` claim), which is split on spaces
233
- * before checking.
234
- *
235
- * Returns 403 Forbidden if the claim doesn't include all required values
236
- * or user is not authenticated.
237
- *
238
- * @param claim - The name of the claim to check
239
- * @param values - The values that must be present in the claim
240
- * @param options - Optional configuration
241
- * @returns Express middleware function
242
- *
243
- * @example
244
- * ```typescript
245
- * // Require user to have specific permissions
246
- * app.delete('/users/:id', claimIncludes('permissions', ['delete:users']), (req, res) => {
247
- * res.send('User deleted');
248
- * });
249
- *
250
- * // Require multiple permissions
251
- * app.post('/admin/users', claimIncludes('permissions', ['create:users', 'admin:access']), (req, res) => {
252
- * res.send('User created');
253
- * });
254
- *
255
- * // Check roles
256
- * app.get('/dashboard', claimIncludes('roles', ['editor', 'admin']), (req, res) => {
257
- * res.send('Dashboard');
258
- * });
259
- * ```
260
- */
261
- declare function claimIncludes(claim: string, values: unknown[], options?: ClaimAuthOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
262
-
263
- /**
264
- * Middleware to check if a claim equals a specific value.
265
- *
266
- * Returns 403 Forbidden if the claim doesn't match or user is not authenticated.
267
- *
268
- * @param claim - The name of the claim to check
269
- * @param value - The expected value of the claim
270
- * @param options - Optional configuration
271
- * @returns Express middleware function
272
- *
273
- * @example
274
- * ```typescript
275
- * // Require user to be an admin
276
- * app.get('/admin', claimEquals('role', 'admin'), (req, res) => {
277
- * res.send('Admin dashboard');
278
- * });
279
- *
280
- * // Check organization membership
281
- * app.get('/org', claimEquals('org_id', 'org_123'), (req, res) => {
282
- * res.send('Organization page');
283
- * });
284
- * ```
285
- */
286
- declare function claimEquals(claim: string, value: JSONPrimitive, options?: ClaimAuthOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
287
-
288
- /**
289
- * Middleware to check claims using a custom validation function.
290
- *
291
- * Returns 403 Forbidden if the validation function returns false
292
- * or user is not authenticated.
293
- *
294
- * @param checkFn - A function that receives the Express request and the user
295
- * claims and returns true if authorized
296
- * @param options - Optional configuration
297
- * @returns Express middleware function
298
- *
299
- * @example
300
- * ```typescript
301
- * // Custom claim validation
302
- * app.get('/premium', claimCheck((req, claims) => {
303
- * return claims.subscription === 'premium' && !claims.subscription_expired;
304
- * }), (req, res) => {
305
- * res.send('Premium content');
306
- * });
307
- *
308
- * // Complex authorization logic using the request
309
- * app.delete('/posts/:id', claimCheck(async (req, claims) => {
310
- * const post = await getPost(req.params.id);
311
- * return claims.sub === post.authorId || claims.role === 'admin';
312
- * }), (req, res) => {
313
- * res.send('Post deleted');
314
- * });
315
- *
316
- * // With custom error message
317
- * app.get('/beta', claimCheck(
318
- * (req, claims) => claims.beta_access === true,
319
- * { errorMessage: 'Beta access required' }
320
- * ), (req, res) => {
321
- * res.send('Beta features');
322
- * });
323
- * ```
324
- */
325
- declare function claimCheck(checkFn: ClaimCheckFunction, options?: ClaimAuthOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
326
-
327
- /**
328
- * Checks if a string is a valid HTTP or HTTPS URL.
329
- */
330
- declare function isUrl(value: string): boolean;
331
- /**
332
- * Resolves the application base URL for the current request.
333
- *
334
- * - `string`: used as-is (static configuration).
335
- * - `undefined`: inferred from the request host (dynamic mode).
336
- * - `string[]`: the request origin is matched against the allow-list; the
337
- * matching origin is returned, otherwise an error is thrown.
338
- *
339
- * @throws {InvalidConfigurationError} When the base URL cannot be resolved.
340
- */
341
- declare function resolveAppBaseUrl(appBaseUrl: string | string[] | undefined, req?: Request): string;
342
-
343
- export { type Auth0Options, type ClaimAuthOptions, type ClaimCheckFunction, type RequiresAuthOptions, type StoreOptions, claimCheck, claimEquals, claimIncludes, createAuth0, isUrl, requiresAuth, resolveAppBaseUrl };