@edium/halifax 2.1.0 → 2.2.0

package/dist/auth/strategies/PassportStrategies.d.ts

@@ -0,0 +1,94 @@
+import type { HttpRequest } from '../../core/types.js';
+import type { AuthContext, AuthorizeParams, AuthStrategy, SecurityScheme } from './types.js';
+/** Minimal structural interface for a Passport.js instance (avoids a hard dependency on `passport`). */
+export interface PassportLike {
+    /**
+     * Authenticates a request using the named strategy.
+     * @param strategy - Name of the registered Passport strategy.
+     * @param options - Authentication options (e.g. `{ session: false }`).
+     * @param callback - Called with the error or authenticated user on completion.
+     * @returns An Express-style middleware function that drives the authentication flow.
+     */
+    authenticate(strategy: string, options: {
+        session: boolean;
+    }, callback: (err: unknown, user: unknown) => void): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+}
+/** Options for {@link PassportJwtStrategy}. */
+export interface PassportJwtStrategyOptions {
+    /** A Passport instance with a JWT strategy registered. */
+    passport: PassportLike;
+    /** Name of the Passport strategy to invoke (default: `'jwt'`). */
+    strategy?: string;
+    /** Maps the raw Passport user payload to an {@link AuthContext}. Defaults to reading `sub`/`id`, `roles`, and `permissions`. */
+    mapUser?: (user: unknown) => AuthContext;
+}
+/** Delegates authentication to a caller-provided Passport authenticate wrapper. */
+export declare class PassportAuthStrategy implements AuthStrategy {
+    private readonly authenticateWithPassport;
+    /**
+     * @param authenticateWithPassport - Function that calls your Passport strategy
+     *   and resolves to an {@link AuthContext}.
+     */
+    constructor(authenticateWithPassport: (req: HttpRequest) => Promise<AuthContext> | AuthContext);
+    /**
+     * Delegates to the provided Passport authenticate wrapper.
+     * @param req - The incoming HTTP request.
+     * @returns The {@link AuthContext} resolved by the wrapper.
+     */
+    authenticate(req: HttpRequest): Promise<AuthContext>;
+}
+/** Authenticates via Passport's JWT strategy, invoking it programmatically without Express middleware. */
+export declare class PassportJwtStrategy implements AuthStrategy {
+    private readonly passport;
+    private readonly strategy;
+    private readonly mapUser;
+    /** @param options - Passport instance, optional strategy name, and optional user mapper. */
+    constructor(options: PassportJwtStrategyOptions);
+    /**
+     * Runs the Passport JWT authenticate handler and resolves to an {@link AuthContext}.
+     * @param req - The incoming HTTP request (must carry a `raw` property for Passport to read).
+     * @returns The resolved {@link AuthContext}.
+     * @throws {@link AuthenticationError} when Passport rejects the token or returns no user.
+     */
+    authenticate(req: HttpRequest): Promise<AuthContext>;
+    /**
+     * Returns `true` when the auth context satisfies all required permissions.
+     * @param params - Authorization context including required permissions and the resolved auth.
+     * @returns `true` when all required permissions are satisfied, `false` otherwise.
+     */
+    authorize(params: AuthorizeParams): boolean;
+    openApiScheme(): SecurityScheme;
+}
+/**
+ * Authenticates using Passport session cookies.
+ *
+ * Passport's session middleware must run before Halifax and populate `req.user`
+ * automatically — this strategy simply reads that value and maps it to an
+ * {@link AuthContext}. No passport instance is needed here.
+ *
+ * Prerequisites (add to your Express app before mounting Halifax):
+ * ```ts
+ * app.use(session({ ... }))
+ * app.use(passport.initialize())
+ * app.use(passport.session())
+ * ```
+ */
+export declare class PassportSessionStrategy implements AuthStrategy {
+    private readonly mapUser;
+    /** @param mapUser - Optional function to convert the raw session user to an {@link AuthContext}. */
+    constructor(mapUser?: (user: unknown) => AuthContext);
+    /**
+     * Reads `req.raw.user` (set by Passport session middleware) and maps it to an {@link AuthContext}.
+     * @param req - The incoming HTTP request whose `raw.user` property holds the session user.
+     * @returns The mapped {@link AuthContext}.
+     * @throws {@link AuthenticationError} when `req.raw.user` is absent (not authenticated).
+     */
+    authenticate(req: HttpRequest): AuthContext;
+    /**
+     * Returns `true` when the auth context satisfies all required permissions.
+     * @param params - Authorization context including required permissions and the resolved auth.
+     * @returns `true` when all required permissions are satisfied, `false` otherwise.
+     */
+    authorize(params: AuthorizeParams): boolean;
+    openApiScheme(): SecurityScheme;
+}

package/dist/auth/strategies/PassportStrategies.js

@@ -0,0 +1,142 @@
+import { AuthenticationError } from '../../errors/AuthenticationError.js';
+/**
+ * Extracts `userId`, `roles`, `permissions`, and `claims` from a raw Passport user payload.
+ * @param user - The raw user object returned by Passport (typically a decoded JWT payload).
+ * @returns A fully populated {@link AuthContext}.
+ */
+function defaultMapUser(user) {
+    const p = (user ?? {});
+    const userId = typeof p.sub === 'string' ? p.sub : typeof p.id === 'string' ? p.id : undefined;
+    const ctx = {
+        isAuthenticated: true,
+        roles: Array.isArray(p.roles) ? p.roles : [],
+        permissions: Array.isArray(p.permissions) ? p.permissions : [],
+        claims: p
+    };
+    if (userId !== undefined)
+        ctx.userId = userId;
+    return ctx;
+}
+function checkPermissions(auth, requiredPermissions) {
+    if (!requiredPermissions.length)
+        return true;
+    const permissions = new Set(auth.permissions ?? []);
+    const roles = new Set(auth.roles ?? []);
+    return requiredPermissions.every((p) => permissions.has(p) || roles.has(p));
+}
+/** Delegates authentication to a caller-provided Passport authenticate wrapper. */
+export class PassportAuthStrategy {
+    authenticateWithPassport;
+    /**
+     * @param authenticateWithPassport - Function that calls your Passport strategy
+     *   and resolves to an {@link AuthContext}.
+     */
+    constructor(authenticateWithPassport) {
+        this.authenticateWithPassport = authenticateWithPassport;
+    }
+    /**
+     * Delegates to the provided Passport authenticate wrapper.
+     * @param req - The incoming HTTP request.
+     * @returns The {@link AuthContext} resolved by the wrapper.
+     */
+    async authenticate(req) {
+        return await this.authenticateWithPassport(req);
+    }
+}
+/** Authenticates via Passport's JWT strategy, invoking it programmatically without Express middleware. */
+export class PassportJwtStrategy {
+    passport;
+    strategy;
+    mapUser;
+    /** @param options - Passport instance, optional strategy name, and optional user mapper. */
+    constructor(options) {
+        this.passport = options.passport;
+        this.strategy = options.strategy ?? 'jwt';
+        this.mapUser = options.mapUser ?? defaultMapUser;
+    }
+    /**
+     * Runs the Passport JWT authenticate handler and resolves to an {@link AuthContext}.
+     * @param req - The incoming HTTP request (must carry a `raw` property for Passport to read).
+     * @returns The resolved {@link AuthContext}.
+     * @throws {@link AuthenticationError} when Passport rejects the token or returns no user.
+     */
+    async authenticate(req) {
+        return new Promise((resolve, reject) => {
+            const handler = this.passport.authenticate(this.strategy, { session: false }, (err, user) => {
+                if (err) {
+                    reject(err instanceof Error ? err : new AuthenticationError(String(err)));
+                    return;
+                }
+                if (!user) {
+                    reject(new AuthenticationError('Unauthorized'));
+                    return;
+                }
+                resolve(this.mapUser(user));
+            });
+            handler(req.raw, {}, (err) => {
+                if (err)
+                    reject(err instanceof Error ? err : new AuthenticationError(String(err)));
+            });
+        });
+    }
+    /**
+     * Returns `true` when the auth context satisfies all required permissions.
+     * @param params - Authorization context including required permissions and the resolved auth.
+     * @returns `true` when all required permissions are satisfied, `false` otherwise.
+     */
+    authorize(params) {
+        return checkPermissions(params.auth, params.requiredPermissions);
+    }
+    openApiScheme() {
+        return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };
+    }
+}
+/**
+ * Authenticates using Passport session cookies.
+ *
+ * Passport's session middleware must run before Halifax and populate `req.user`
+ * automatically — this strategy simply reads that value and maps it to an
+ * {@link AuthContext}. No passport instance is needed here.
+ *
+ * Prerequisites (add to your Express app before mounting Halifax):
+ * ```ts
+ * app.use(session({ ... }))
+ * app.use(passport.initialize())
+ * app.use(passport.session())
+ * ```
+ */
+export class PassportSessionStrategy {
+    mapUser;
+    /** @param mapUser - Optional function to convert the raw session user to an {@link AuthContext}. */
+    constructor(mapUser) {
+        this.mapUser = mapUser ?? defaultMapUser;
+    }
+    /**
+     * Reads `req.raw.user` (set by Passport session middleware) and maps it to an {@link AuthContext}.
+     * @param req - The incoming HTTP request whose `raw.user` property holds the session user.
+     * @returns The mapped {@link AuthContext}.
+     * @throws {@link AuthenticationError} when `req.raw.user` is absent (not authenticated).
+     */
+    authenticate(req) {
+        const user = req.raw != null ? req.raw['user'] : undefined;
+        if (!user)
+            throw new AuthenticationError('Not authenticated');
+        return this.mapUser(user);
+    }
+    /**
+     * Returns `true` when the auth context satisfies all required permissions.
+     * @param params - Authorization context including required permissions and the resolved auth.
+     * @returns `true` when all required permissions are satisfied, `false` otherwise.
+     */
+    authorize(params) {
+        return checkPermissions(params.auth, params.requiredPermissions);
+    }
+    openApiScheme() {
+        return {
+            type: 'apiKey',
+            in: 'cookie',
+            name: 'connect.sid',
+            description: 'Passport session cookie.'
+        };
+    }
+}

package/dist/auth/strategies/types.d.ts

@@ -0,0 +1,70 @@
+import type { CrudAction, HttpRequest, ResourceDefinition } from '../../core/types.js';
+/** Resolved user identity and access information returned by {@link AuthStrategy.authenticate}. */
+export interface AuthContext {
+    /** Unique identifier for the authenticated user. */
+    userId?: string;
+    /** Roles granted to the user (checked against `requiredPermissions`). */
+    roles?: string[];
+    /** Explicit permission strings granted to the user. */
+    permissions?: string[];
+    /** Raw claims from the token or session payload. */
+    claims?: Record<string, unknown>;
+    /** Always `true` for a successfully authenticated context. */
+    isAuthenticated: boolean;
+}
+/** Parameters passed to {@link AuthStrategy.authorize}. */
+export interface AuthorizeParams {
+    /** The resolved authentication context for the current request. */
+    auth: AuthContext;
+    /** The CRUD action being performed. */
+    action: CrudAction;
+    /** The resource being accessed. */
+    resource: ResourceDefinition;
+    /** Permissions required for this action on this resource. */
+    requiredPermissions: string[];
+    /** The incoming request. */
+    req: HttpRequest;
+}
+/**
+ * An OpenAPI 3.1 security scheme descriptor returned by {@link AuthStrategy.openApiScheme}.
+ * The spec generator uses this to populate `components/securitySchemes` and the global
+ * `security` requirement — so the Swagger UI "Authorize" button works out of the box.
+ */
+export type SecurityScheme = {
+    type: 'apiKey';
+    in: 'header' | 'query' | 'cookie';
+    name: string;
+    description?: string;
+} | {
+    type: 'http';
+    scheme: 'bearer';
+    bearerFormat?: string;
+    description?: string;
+} | {
+    type: 'http';
+    scheme: 'basic';
+    description?: string;
+};
+/** Contract for pluggable authentication and authorisation strategies. */
+export interface AuthStrategy {
+    /**
+     * Authenticate the request and return the caller's identity.
+     * @param req - The incoming HTTP request.
+     * @returns The resolved {@link AuthContext}, or a promise that resolves to one.
+     * @throws {@link AuthenticationError} when the request cannot be authenticated.
+     */
+    authenticate(req: HttpRequest): Promise<AuthContext> | AuthContext;
+    /**
+     * Determine whether the authenticated caller may perform `action`.
+     * @param params - Authorization context including the auth, action, resource, and required permissions.
+     * @returns `true` to allow, `false` to deny.
+     */
+    authorize?(params: AuthorizeParams): Promise<boolean> | boolean;
+    /**
+     * Describes this strategy's security scheme for OpenAPI spec generation.
+     * When implemented, the spec generator automatically wires up `components/securitySchemes`
+     * and the global `security` requirement — no manual `OpenApiOptions.securityScheme` needed.
+     * Return `undefined` (or omit the method) for unauthenticated / custom strategies.
+     */
+    openApiScheme?(): SecurityScheme | undefined;
+}

package/dist/core/crudRouter.d.ts

@@ -1,7 +1,10 @@
 import { type AuthContext, type AuthStrategy } from '../auth/AuthStrategy.js';
 import { type CacheStore } from '../core/cache/index.js';
+import { type OpenApiOptions } from '../openapi/index.js';
 import { type ResourceDefinition } from '../core/types.js';
 import type { HttpRequest, HttpServer } from '../core/types.js';
+import { normalizeError } from '../core/handlerUtils.js';
+export { normalizeError };
 /** Context handed to {@link TenantOptions.resolveId} for the current request. */
 export interface TenantResolveContext {
     /** The resolved authentication context for the request. */
@@ -22,8 +25,6 @@ export interface TenantOptions {
      * derived from the authenticated session/token — never from client-supplied input.
      * Return `null`/`undefined` to signal "no tenant"; combined with {@link TenantOptions.strict}
      * this either denies the request (default) or serves it unscoped.
-     * @param ctx - The auth context, request, and resource being accessed.
-     * @returns The tenant key, or null/undefined when none applies.
      */
     resolveId: (ctx: TenantResolveContext) => unknown | Promise<unknown>;
     /**
@@ -51,10 +52,14 @@ export interface CrudApiOptions {
     /**
      * Wrap every success response body under a single key (e.g. `'data'` → `{ "data": <body> }`)
      * for all resources. Per-resource {@link ResourceDefinition.envelope} takes precedence.
-     * Error responses are never enveloped. Omit (or set `null`/`''`) for bare bodies — the
-     * default, and backward compatible.
+     * Error responses are never enveloped.
      */
     envelope?: string | null;
+    /**
+     * Enable OpenAPI 3.1 spec generation and interactive docs. When set, Halifax registers two
+     * additional routes: `GET /openapi.json` (raw spec) and `GET /docs` (Swagger UI).
+     */
+    openapi?: OpenApiOptions;
     /**
      * API-wide read-through caching. Provide a `store` (defaults to an in-process
      * {@link InMemoryCacheStore}) and/or a default `ttlSeconds` applied to every resource that
@@ -76,25 +81,13 @@ export interface CrudApiOptions {
         bustHeader?: string;
     };
 }
-/**
- * Converts any thrown value to a structured `{ status, code, message, details }` object.
- * {@link HttpError} subclasses preserve their status; all other errors become 500.
- * @param error - The caught value to normalise (may be any type).
- * @returns A plain object with `status`, `code`, `message`, and optional `details`.
- */
-export declare function normalizeError(error: unknown): {
-    status: number;
-    code: string;
-    message: string;
-    details?: unknown;
-};
 /**
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
  * Routes are controlled by `resource.permissions` merged with {@link defaultCrudPermissions}.
  *
- * @param server - The HTTP server adapter to register routes on (e.g. {@link ExpressHttpServer}).
+ * @param server - The HTTP server adapter to register routes on.
  * @param resources - Resource definitions to wire up as CRUD endpoints.
- * @param options - Auth strategy and query-builder path overrides.
+ * @param options - Auth strategy, tenant config, envelope, caching, and OpenAPI overrides.
  */
 export declare function registerCrudApi(server: HttpServer, resources: ResourceDefinition[], options?: CrudApiOptions): void;