@jazzmind/busibox-app 3.0.18

package/dist/lib/next/middleware.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Authentication Middleware Helpers
+ *
+ * Zero Trust Authentication Architecture:
+ * - Session tokens are RS256-signed JWTs from authz
+ * - JWTs can be verified locally or validated against authz for revocation check
+ * - Session JWTs are used as subject_token for downstream token exchange
+ *
+ * Quiet Mode: Set X-Quiet-Logs header to suppress verbose middleware logging.
+ * Useful for polling endpoints to reduce log noise.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { isInvalidSessionError } from '@jazzmind/busibox-app';
+import type { AuthenticatedUser } from '../../types/next-auth';
+export { isInvalidSessionError };
+/**
+ * Get session JWT from request cookies.
+ * Returns the raw JWT string for use in token exchange.
+ *
+ * @param request - Next.js request object
+ * @returns Session JWT string or null
+ */
+export declare function getSessionJwt(request: NextRequest): string | null;
+/**
+ * Get session JWT from cookies (for Server Components)
+ */
+export declare function getSessionJwtFromCookies(): Promise<string | null>;
+/**
+ * Get current session from request.
+ * Zero Trust: All sessions are RS256-signed JWTs from authz.
+ * JWT claims are validated locally (signature verification happens at token exchange).
+ *
+ * @param request - Next.js request object
+ * @returns Session object or null if not authenticated
+ */
+export declare function getSession(request: NextRequest): Promise<{
+    user: {
+        id: string;
+        email: string;
+        status: string;
+        roles: {
+            id: string;
+            name: string;
+        }[];
+    };
+    session: {
+        id: string;
+        token: string;
+        expiresAt: Date;
+    };
+} | null>;
+/**
+ * Get current user from session
+ *
+ * Uses roles embedded in the session JWT - no additional API calls needed.
+ *
+ * @param request - Next.js request object
+ * @returns Authenticated user with roles or null
+ */
+export declare function getCurrentUser(request: NextRequest): Promise<AuthenticatedUser | null>;
+/**
+ * Get basic session user (without roles lookup)
+ * Useful for endpoints that just need user identity
+ *
+ * @param request - Next.js request object
+ * @returns Basic user info or null
+ */
+export declare function getSessionUser(request: NextRequest): Promise<{
+    id: string;
+    email: string;
+} | null>;
+export interface AuthenticatedUserWithSession extends AuthenticatedUser {
+    sessionJwt: string;
+}
+/**
+ * Get current user from cookies (for Server Components)
+ *
+ * @returns Authenticated user with roles or null
+ */
+export declare function getCurrentUserFromCookies(): Promise<AuthenticatedUser | null>;
+/**
+ * Get current user with session JWT from cookies (for Server Components that need Zero Trust exchange)
+ *
+ * User roles are embedded directly in the session JWT - no additional API calls needed.
+ *
+ * @returns Authenticated user with roles and session JWT, or null
+ */
+export declare function getCurrentUserWithSessionFromCookies(): Promise<AuthenticatedUserWithSession | null>;
+/**
+ * Require authentication for a route
+ * Returns 401 if not authenticated
+ *
+ * @param request - Next.js request object
+ * @returns User object if authenticated, or error response
+ */
+export declare function requireAuth(request: NextRequest): Promise<{
+    user: AuthenticatedUser;
+    sessionJwt: string;
+} | NextResponse>;
+/**
+ * Require admin role for a route
+ * Returns 401 if not authenticated, 403 if not admin
+ *
+ * Uses roles from the session JWT first (faster), falls back to authz service.
+ *
+ * @param request - Next.js request object
+ * @returns User object if admin, or error response
+ */
+export declare function requireAdminAuth(request: NextRequest): Promise<{
+    user: AuthenticatedUser;
+    sessionJwt: string;
+} | NextResponse>;
+export { type AuthzAudience };
+export interface AuthWithTokenResult {
+    user: AuthenticatedUser;
+    sessionJwt: string;
+    apiToken: string;
+    isTestUser?: boolean;
+}
+/**
+ * Require authentication AND exchange the session JWT for a downstream API token.
+ *
+ * Combines session validation with Zero Trust token exchange in a single call.
+ * Use this in API routes that need to call downstream services (agent-api, data-api, etc.).
+ *
+ * Falls back to TEST_SESSION_JWT env var for local development when no token is present.
+ *
+ * @param request - Next.js request object
+ * @param audience - Target service audience (defaults to DEFAULT_API_AUDIENCE env or 'backend-api')
+ * @param scopes - Optional scopes to request
+ * @returns Auth result with user info and API token, or 401 NextResponse
+ */
+export declare function requireAuthWithTokenExchange(request: NextRequest, audience?: AuthzAudience, scopes?: string[]): Promise<AuthWithTokenResult | NextResponse>;
+/**
+ * Optional authentication with token exchange.
+ *
+ * Returns auth result if a valid session exists, null otherwise.
+ * Use for endpoints that work with or without authentication.
+ *
+ * @param request - Next.js request object
+ * @param audience - Target service audience
+ * @param scopes - Optional scopes to request
+ * @returns Auth result or null
+ */
+export declare function optionalAuthWithTokenExchange(request: NextRequest, audience?: AuthzAudience, scopes?: string[]): Promise<AuthWithTokenResult | null>;
+/**
+ * Simple helper to check if a user has Admin role.
+ *
+ * Used after getSessionUser() for a simple role check without full authentication.
+ * For full admin auth with JWT validation, use requireAdminAuth() instead.
+ *
+ * @param user - User object with roles array
+ * @returns true if user has Admin role
+ */
+export declare function requireAdmin(user: {
+    id?: string;
+    email?: string;
+    roles?: string[];
+} | null): boolean;
+/**
+ * Extract IP address from request
+ *
+ * @param request - Next.js request object
+ * @returns IP address string
+ */
+export declare function getIpAddress(request: NextRequest): string | undefined;
+/**
+ * Extract user agent from request
+ *
+ * @param request - Next.js request object
+ * @returns User agent string
+ */
+export declare function getUserAgent(request: NextRequest): string | undefined;
+/**
+ * Create success API response
+ *
+ * @param data - Response data
+ * @param status - HTTP status code
+ * @returns NextResponse
+ */
+export declare function apiSuccess<T>(data: T, status?: number): NextResponse<{
+    success: boolean;
+    data: T;
+}>;
+/**
+ * Create error API response
+ *
+ * @param error - Error message
+ * @param status - HTTP status code
+ * @returns NextResponse
+ */
+export declare function apiError(error: string, status?: number): NextResponse<{
+    success: boolean;
+    error: string;
+}>;
+/**
+ * Create error API response that signals the client should logout.
+ *
+ * Used when the session is permanently invalid (e.g., signing key changed,
+ * token expired, token revoked). The client should clear cookies and redirect
+ * to login.
+ *
+ * Response includes `requireLogout: true` flag that client apps should check.
+ * Also clears the session cookie to help with immediate logout.
+ *
+ * @param error - Error message
+ * @param errorCode - Machine-readable error code (e.g., 'invalid_subject_token_key')
+ * @returns NextResponse with 401 status and logout signal
+ */
+export declare function apiErrorRequireLogout(error: string, errorCode?: string): NextResponse<{
+    success: boolean;
+    error: string;
+    errorCode: string | undefined;
+    requireLogout: boolean;
+}>;
+/**
+ * Handle errors in API routes, with special handling for invalid session errors.
+ *
+ * If the error is an InvalidSessionError (e.g., token key mismatch), returns
+ * a response that signals the client should logout.
+ *
+ * @param error - The caught error
+ * @param defaultMessage - Default error message if not an InvalidSessionError
+ * @returns NextResponse
+ */
+export declare function handleApiError(error: unknown, defaultMessage?: string): NextResponse<{
+    success: boolean;
+    error: string;
+}>;
+/**
+ * Parse JSON body from request safely
+ *
+ * @param request - Next.js request object
+ * @returns Parsed JSON or null if invalid
+ */
+export declare function parseJsonBody(request: NextRequest): Promise<any>;
+/**
+ * Validate required fields in request body
+ *
+ * @param body - Request body object
+ * @param requiredFields - Array of required field names
+ * @returns Error message if validation fails, null if valid
+ */
+export declare function validateRequiredFields(body: any, requiredFields: string[]): string | null;
+import { type AuthzAudience } from '../authz/next-client';
+/**
+ * Get authorization header for downstream service using session JWT.
+ * Uses Zero Trust token exchange (subject_token) - no client credentials required.
+ *
+ * @param request - Next.js request object
+ * @param audience - Target service (e.g., 'data-api', 'search-api')
+ * @param scopes - Optional scopes to request
+ * @returns Authorization header string or null if not authenticated
+ */
+export declare function getDownstreamAuth(request: NextRequest, audience: AuthzAudience, scopes?: string[]): Promise<string | null>;
+/**
+ * Get authorization header for downstream service from cookies (for Server Components).
+ *
+ * @param audience - Target service
+ * @param scopes - Optional scopes
+ * @returns Authorization header string or null
+ */
+export declare function getDownstreamAuthFromCookies(audience: AuthzAudience, scopes?: string[]): Promise<string | null>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/lib/next/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/lib/next/middleware.ts"],"names":[],"mappings":"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"}