@markwharton/pwa-core 3.2.1 → 3.4.0

package/dist/server.d.ts

@@ -3,9 +3,9 @@
  *
  * Includes: JWT auth, API keys, HTTP responses, Azure Table Storage
  */
-import { HttpResponseInit, InvocationContext } from '@azure/functions';
+import { HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
 import { TableClient } from '@azure/data-tables';
-import { Result, BaseJwtPayload, RoleTokenPayload } from './shared';
+import { Result, BaseJwtPayload, RoleTokenPayload, SessionUser, SessionInfo } from './shared';
 /**
  * Initializes the JWT authentication system. Call once at application startup.
  * @param config - Configuration object
@@ -200,6 +200,30 @@ export declare function notFoundResponse(resource: string): HttpResponseInit;
  * if (existingUser) return conflictResponse('Email already registered');
  */
 export declare function conflictResponse(message: string): HttpResponseInit;
+/**
+ * Creates a 410 Gone response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (linkUsed) return goneResponse('Link already used');
+ */
+export declare function goneResponse(message: string): HttpResponseInit;
+/**
+ * Creates a 429 Too Many Requests response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (rateLimited) return tooManyRequestsResponse('Too many requests');
+ */
+export declare function tooManyRequestsResponse(message: string): HttpResponseInit;
+/**
+ * Creates a 503 Service Unavailable response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!emailSent) return serviceUnavailableResponse('Email service unavailable');
+ */
+export declare function serviceUnavailableResponse(message: string): HttpResponseInit;
 /**
  * Validates that a required parameter is present.
  * Returns an error response if missing, null if valid.
@@ -235,12 +259,12 @@ export declare function initErrorHandling(config?: {
  * Initializes error handling from environment variables.
  * Currently a no-op but provides consistent API for future error config
  * (e.g., ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK).
+ * @param callback - Optional callback invoked when handleFunctionError is called (fire-and-forget)
  * @example
  * initErrorHandlingFromEnv(); // Uses process.env automatically
+ * initErrorHandlingFromEnv((op, msg) => sendAlert(op, msg));
  */
-export declare function initErrorHandlingFromEnv(config?: {
-    callback?: ErrorCallback;
-}): void;
+export declare function initErrorHandlingFromEnv(callback?: ErrorCallback): void;
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
  * Use in catch blocks to avoid exposing internal error details to clients.
@@ -359,6 +383,50 @@ export declare function clearTableClientCache(): void;
  * if (!user) return notFoundResponse('User');
  */
 export declare function getEntityIfExists<T extends object>(client: TableClient, partitionKey: string, rowKey: string): Promise<T | null>;
+/**
+ * Upserts (insert or replace) an entity in Azure Table Storage.
+ * @typeParam T - The entity type with partitionKey and rowKey
+ * @param client - The TableClient instance
+ * @param entity - The entity to upsert
+ * @example
+ * await upsertEntity(client, { partitionKey: 'user', rowKey: 'john', name: 'John' });
+ */
+export declare function upsertEntity<T extends {
+    partitionKey: string;
+    rowKey: string;
+}>(client: TableClient, entity: T): Promise<void>;
+/**
+ * Deletes an entity from Azure Table Storage.
+ * Returns true on success, false on error (swallows errors).
+ * @param client - The TableClient instance
+ * @param partitionKey - The partition key
+ * @param rowKey - The row key
+ * @returns True if deleted successfully, false on error
+ * @example
+ * const deleted = await deleteEntity(client, 'session', sessionId);
+ */
+export declare function deleteEntity(client: TableClient, partitionKey: string, rowKey: string): Promise<boolean>;
+/**
+ * Lists all entities in a partition.
+ * @typeParam T - The entity type
+ * @param client - The TableClient instance
+ * @param partitionKey - The partition key to filter by
+ * @returns Array of entities in the partition
+ * @example
+ * const sessions = await listEntitiesByPartition<SessionEntity>(client, 'session');
+ */
+export declare function listEntitiesByPartition<T extends object>(client: TableClient, partitionKey: string): Promise<T[]>;
+/**
+ * Lists entities matching a custom OData filter.
+ * @typeParam T - The entity type
+ * @param client - The TableClient instance
+ * @param filter - OData filter string (use the odata template tag from @azure/data-tables)
+ * @returns Array of matching entities
+ * @example
+ * const filter = odata`PartitionKey eq ${'user'} and email eq ${'john@example.com'}`;
+ * const users = await listEntitiesWithFilter<UserEntity>(client, filter);
+ */
+export declare function listEntitiesWithFilter<T extends object>(client: TableClient, filter: string): Promise<T[]>;
 /**
  * Generate a unique row key from an identifier string.
  * Uses SHA-256 hash for consistent, URL-safe keys.
@@ -366,4 +434,243 @@ export declare function getEntityIfExists<T extends object>(client: TableClient,
  * @returns A 32-character hex string suitable for Azure Table Storage row keys
  */
 export declare function generateRowKey(identifier: string): string;
-export { Result, ok, okVoid, err, getErrorMessage, BaseJwtPayload, UserTokenPayload, UsernameTokenPayload, RoleTokenPayload, hasUsername, hasRole, isAdmin, HTTP_STATUS, HttpStatus, ErrorResponse } from './shared';
+/**
+ * Configuration for session-based authentication.
+ */
+export interface SessionAuthConfig {
+    /** Cookie name for the session (default: 'app_session') */
+    cookieName?: string;
+    /** Session duration in ms (default: 30 days) */
+    sessionDurationMs?: number;
+    /** Refresh threshold in ms - refresh session if within this time of expiry (default: 24 hours) */
+    sessionRefreshThresholdMs?: number;
+    /** Magic link token expiry in ms (default: 15 minutes) */
+    magicLinkExpiryMs?: number;
+    /** Rate limit window in ms (default: 1 hour) */
+    rateLimitWindowMs?: number;
+    /** Max magic link requests per email per window (default: 5) */
+    rateLimitMaxRequests?: number;
+    /** SameSite cookie attribute (default: 'Strict') */
+    sameSite?: 'Strict' | 'Lax';
+    /** Specific emails allowed (empty = allow all) */
+    allowedEmails?: string[];
+    /** Domain allowlist suffix (e.g., '@company.com') */
+    allowedDomain?: string;
+    /** Emails that get isAdmin=true */
+    adminEmails?: string[];
+    /** Base URL for magic links and SWA preview URL validation */
+    appBaseUrl?: string;
+    /** Required callback to send magic link emails */
+    sendEmail: (to: string, magicLink: string) => Promise<boolean>;
+}
+/**
+ * Initializes session-based authentication. Call once at application startup.
+ * @param config - Session auth configuration
+ * @throws Error if sendEmail callback is not provided
+ * @example
+ * initSessionAuth({
+ *   sendEmail: async (to, magicLink) => { await resend.emails.send(...); return true; },
+ *   allowedEmails: ['admin@example.com'],
+ *   appBaseUrl: 'https://myapp.com'
+ * });
+ */
+export declare function initSessionAuth(config: SessionAuthConfig): void;
+/**
+ * Initializes session auth from environment variables.
+ * Reads: SESSION_COOKIE_NAME, APP_BASE_URL, ALLOWED_EMAILS, ALLOWED_DOMAIN, ADMIN_EMAILS.
+ * @param sendEmail - Required callback to send magic link emails
+ * @throws Error if sendEmail is not provided
+ * @example
+ * initSessionAuthFromEnv(async (to, magicLink) => {
+ *   await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
+ *   return true;
+ * });
+ */
+export declare function initSessionAuthFromEnv(sendEmail: (to: string, magicLink: string) => Promise<boolean>): void;
+/**
+ * Parses cookies from a request's Cookie header.
+ * @param request - Request object with headers.get() method
+ * @returns Record of cookie name/value pairs
+ * @example
+ * const cookies = parseCookies(request);
+ * const sessionId = cookies['app_session'];
+ */
+export declare function parseCookies(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): Record<string, string>;
+/**
+ * Creates a Set-Cookie header value for a session cookie.
+ * @param sessionId - The session ID to store in the cookie
+ * @returns Cookie string for the Set-Cookie header
+ * @example
+ * return { headers: { 'Set-Cookie': createSessionCookie(sessionId) } };
+ */
+export declare function createSessionCookie(sessionId: string): string;
+/**
+ * Creates a Set-Cookie header value that clears the session cookie.
+ * @returns Cookie string for the Set-Cookie header
+ * @example
+ * return { headers: { 'Set-Cookie': createLogoutCookie() } };
+ */
+export declare function createLogoutCookie(): string;
+/**
+ * Validates a request origin for SWA preview/staging deployments.
+ * Returns the trusted origin if it matches the configured appBaseUrl:
+ * - Exact hostname match (production)
+ * - Localhost-to-localhost match (local development)
+ * - App name prefix match for SWA preview slots
+ * @param origin - The request Origin header value
+ * @returns The trusted origin URL, or undefined if not trusted
+ * @example
+ * const trusted = getTrustedOrigin(request.headers.get('origin'));
+ * const baseUrl = trusted ?? config.appBaseUrl;
+ */
+export declare function getTrustedOrigin(origin: string | null): string | undefined;
+/**
+ * Validates an email address format.
+ * @param email - The email address to validate
+ * @returns True if the email format is valid
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Checks if an email is allowed by the configured allowlist.
+ * Checks both allowedEmails (exact match) and allowedDomain (suffix match).
+ * If neither is configured, allows all emails.
+ * @param email - The email address to check
+ * @returns True if the email is allowed
+ */
+export declare function isEmailAllowed(email: string): boolean;
+/**
+ * Checks if a magic link request is within rate limits.
+ * @param email - The email address to check
+ * @returns True if within limits, false if rate limited
+ */
+export declare function checkMagicLinkRateLimit(email: string): Promise<boolean>;
+/**
+ * Creates a magic link token, stores it, and sends an email.
+ * @param email - The email address to send the magic link to
+ * @param request - Request object (used to resolve SWA preview origin)
+ * @returns Result with the token on success, or error with statusCode
+ * @example
+ * const result = await createMagicLink(email, request);
+ * if (!result.ok) return { status: result.statusCode, jsonBody: { error: result.error } };
+ */
+export declare function createMagicLink(email: string, request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): Promise<Result<string>>;
+/**
+ * Verifies a magic link token, creates/updates the user, and creates a session.
+ * @param token - The magic link token to verify
+ * @returns Result with user and sessionCookie on success, or error with statusCode
+ * @example
+ * const result = await verifyMagicLink(token);
+ * if (!result.ok) return { status: result.statusCode, jsonBody: { error: result.error } };
+ * return { headers: { 'Set-Cookie': result.data.sessionCookie }, jsonBody: { user: result.data.user } };
+ */
+export declare function verifyMagicLink(token: string): Promise<Result<{
+    user: SessionUser;
+    sessionCookie: string;
+}>>;
+/**
+ * Validates a session cookie and returns the user and session info.
+ * Performs sliding window refresh if the session is close to expiry.
+ * @param request - Request object with headers.get() method
+ * @returns User, session, and optional refreshed cookie, or null if invalid
+ * @example
+ * const result = await validateSession(request);
+ * if (!result) return unauthorizedResponse();
+ */
+export declare function validateSession(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): Promise<{
+    user: SessionUser;
+    session: SessionInfo;
+    refreshedCookie?: string;
+} | null>;
+/**
+ * Convenience function: validates session and returns user with optional refresh headers.
+ * @param request - Request object with headers.get() method
+ * @returns User and optional Set-Cookie headers, or null if not authenticated
+ * @example
+ * const result = await getSessionUser(request);
+ * if (!result) return unauthorizedResponse();
+ * return { headers: result.headers, jsonBody: { user: result.user } };
+ */
+export declare function getSessionUser(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): Promise<{
+    user: SessionUser;
+    headers?: Record<string, string>;
+} | null>;
+/**
+ * Destroys the current session and returns a logout cookie string.
+ * @param request - Request object with headers.get() method
+ * @returns Cookie string for the Set-Cookie header
+ * @example
+ * const cookie = await destroySession(request);
+ * return { headers: { 'Set-Cookie': cookie }, jsonBody: { success: true } };
+ */
+export declare function destroySession(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): Promise<string>;
+/**
+ * Wraps a handler with session authentication.
+ * Returns 401 if not authenticated. Automatically handles session refresh cookies.
+ * @param handler - The handler function that receives the authenticated user
+ * @returns A wrapped handler function
+ * @example
+ * app.http('myEndpoint', {
+ *   handler: withSessionAuth(async (request, context, auth) => {
+ *     return { jsonBody: { user: auth.user } };
+ *   })
+ * });
+ */
+export declare function withSessionAuth(handler: (request: HttpRequest, context: InvocationContext, auth: {
+    user: SessionUser;
+    headers?: Record<string, string>;
+}) => Promise<HttpResponseInit>): (request: HttpRequest, context: InvocationContext) => Promise<HttpResponseInit>;
+/**
+ * Wraps a handler with session admin authentication.
+ * Returns 401 if not authenticated, 403 if not admin.
+ * @param handler - The handler function that receives the authenticated admin user
+ * @returns A wrapped handler function
+ * @example
+ * app.http('adminEndpoint', {
+ *   handler: withSessionAdminAuth(async (request, context, auth) => {
+ *     return { jsonBody: { admin: auth.user.email } };
+ *   })
+ * });
+ */
+export declare function withSessionAdminAuth(handler: (request: HttpRequest, context: InvocationContext, auth: {
+    user: SessionUser;
+    headers?: Record<string, string>;
+}) => Promise<HttpResponseInit>): (request: HttpRequest, context: InvocationContext) => Promise<HttpResponseInit>;
+/**
+ * Deletes expired sessions from storage. Call periodically (e.g., timer trigger).
+ * @returns Number of sessions deleted
+ * @example
+ * // Timer trigger
+ * const deleted = await deleteExpiredSessions();
+ * context.log(`Cleaned up ${deleted} expired sessions`);
+ */
+export declare function deleteExpiredSessions(): Promise<number>;
+/**
+ * Deletes expired magic links from storage. Call periodically (e.g., timer trigger).
+ * @returns Number of magic links deleted
+ * @example
+ * // Timer trigger
+ * const deleted = await deleteExpiredMagicLinks();
+ * context.log(`Cleaned up ${deleted} expired magic links`);
+ */
+export declare function deleteExpiredMagicLinks(): Promise<number>;
+export { Result, ok, okVoid, err, getErrorMessage, BaseJwtPayload, UserTokenPayload, UsernameTokenPayload, RoleTokenPayload, hasUsername, hasRole, isAdmin, HTTP_STATUS, HttpStatus, ErrorResponse, SessionUser, SessionInfo, MagicLinkRequest, SessionAuthResponse } from './shared';