@markwharton/pwa-core 1.7.0 → 2.0.0

package/dist/server.d.ts

@@ -0,0 +1,283 @@
+/**
+ * pwa-core/server - Server-side utilities for Azure Functions
+ *
+ * Includes: JWT auth, API keys, HTTP responses, Azure Table Storage
+ */
+import { HttpResponseInit, InvocationContext } from '@azure/functions';
+import { TableClient } from '@azure/data-tables';
+import { Result, BaseJwtPayload, RoleTokenPayload } from './shared';
+/**
+ * Initializes the JWT authentication system. Call once at application startup.
+ * @param secret - The JWT secret key (from environment variable)
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if secret is missing or too short
+ * @example
+ * initAuth(process.env.JWT_SECRET);
+ */
+export declare function initAuth(secret: string | undefined, minLength?: number): void;
+/**
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
+ */
+export declare function getJwtSecret(): string;
+/**
+ * Extracts the Bearer token from an Authorization header.
+ * @param authHeader - The Authorization header value
+ * @returns The token string, or null if not a valid Bearer token
+ * @example
+ * const token = extractToken(request.headers.get('Authorization'));
+ */
+export declare function extractToken(authHeader: string | null): string | null;
+/**
+ * Validates and decodes a JWT token.
+ * @typeParam T - The expected payload type (extends object)
+ * @param token - The JWT token string to validate
+ * @returns Result with decoded payload on success, or error message on failure
+ * @example
+ * const result = validateToken<UserPayload>(token);
+ * if (result.ok) {
+ *   console.log(result.data.username);
+ * }
+ */
+export declare function validateToken<T extends object>(token: string): Result<T>;
+/**
+ * Generates a signed JWT token with the given payload.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresIn - Token expiration time (default: '7d')
+ * @returns The signed JWT token string
+ * @example
+ * const token = generateToken({ userId: '123', role: 'admin' }, '1h');
+ */
+export declare function generateToken<T extends object>(payload: T, expiresIn?: string): string;
+/**
+ * Generates a long-lived JWT token for machine/API access.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresInDays - Token expiration in days (default: 3650 = 10 years)
+ * @returns The signed JWT token string
+ * @example
+ * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
+ */
+export declare function generateLongLivedToken<T extends object>(payload: T, expiresInDays?: number): string;
+/**
+ * Successful auth result with typed payload.
+ */
+export interface AuthSuccess<T extends BaseJwtPayload> {
+    authorized: true;
+    payload: T;
+}
+/**
+ * Failed auth result with HTTP response.
+ */
+export interface AuthFailure {
+    authorized: false;
+    response: HttpResponseInit;
+}
+/**
+ * Discriminated union for auth results.
+ * Use `auth.authorized` to narrow the type.
+ */
+export type AuthResult<T extends BaseJwtPayload> = AuthSuccess<T> | AuthFailure;
+/** Default token expiry string for generateToken (7 days) */
+export declare const DEFAULT_TOKEN_EXPIRY = "7d";
+/** Default token expiry in seconds (7 days = 604800 seconds) */
+export declare const DEFAULT_TOKEN_EXPIRY_SECONDS: number;
+/**
+ * Validates auth header and returns typed payload or error response.
+ * @typeParam T - The expected payload type (extends BaseJwtPayload)
+ * @param authHeader - The Authorization header value
+ * @returns AuthResult with payload on success, or HTTP response on failure
+ * @example
+ * const auth = requireAuth<UsernameTokenPayload>(request.headers.get('Authorization'));
+ * if (!auth.authorized) return auth.response;
+ * console.log(auth.payload.username);
+ */
+export declare function requireAuth<T extends BaseJwtPayload>(authHeader: string | null): AuthResult<T>;
+/**
+ * Requires admin role. Use with RoleTokenPayload.
+ * @param authHeader - The Authorization header value
+ * @returns AuthResult with RoleTokenPayload on success, or HTTP response on failure
+ * @example
+ * const auth = requireAdmin(request.headers.get('Authorization'));
+ * if (!auth.authorized) return auth.response;
+ * // User is admin
+ */
+export declare function requireAdmin(authHeader: string | null): AuthResult<RoleTokenPayload>;
+/**
+ * Extracts API key from the X-API-Key header.
+ * @param request - Request object with headers.get() method
+ * @returns The API key string, or null if not present
+ * @example
+ * const apiKey = extractApiKey(request);
+ */
+export declare function extractApiKey(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): string | null;
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ * Store this hash in your database, never the raw key.
+ * @param apiKey - The raw API key to hash
+ * @returns The SHA-256 hash as a hex string
+ * @example
+ * const hash = hashApiKey(rawKey);
+ * await db.save({ apiKeyHash: hash });
+ */
+export declare function hashApiKey(apiKey: string): string;
+/**
+ * Validates an API key against a stored hash.
+ * @param apiKey - The API key from the request
+ * @param storedHash - The hash stored in your database
+ * @returns Result with ok=true if valid, or error message if invalid
+ * @example
+ * const result = validateApiKey(apiKey, user.apiKeyHash);
+ * if (!result.ok) return httpUnauthorized();
+ */
+export declare function validateApiKey(apiKey: string, storedHash: string): Result<void>;
+/**
+ * Generates a cryptographically secure API key.
+ * @returns A random 64-character hex string (32 bytes)
+ * @example
+ * const apiKey = generateApiKey();
+ * // Return to user once, store hash in database
+ */
+export declare function generateApiKey(): string;
+/**
+ * Creates a 400 Bad Request response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!body.email) return badRequestResponse('Email is required');
+ */
+export declare function badRequestResponse(message: string): HttpResponseInit;
+/**
+ * Creates a 401 Unauthorized response.
+ * @param message - The error message (default: 'Unauthorized')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!token) return unauthorizedResponse();
+ */
+export declare function unauthorizedResponse(message?: string): HttpResponseInit;
+/**
+ * Creates a 403 Forbidden response.
+ * @param message - The error message (default: 'Forbidden')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!isAdmin(payload)) return forbiddenResponse('Admin access required');
+ */
+export declare function forbiddenResponse(message?: string): HttpResponseInit;
+/**
+ * Creates a 404 Not Found response.
+ * @param resource - The name of the resource that wasn't found
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!user) return notFoundResponse('User');
+ * // Returns: { error: 'User not found' }
+ */
+export declare function notFoundResponse(resource: string): HttpResponseInit;
+/**
+ * Creates a 409 Conflict response.
+ * @param message - The conflict error message
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (existingUser) return conflictResponse('Email already registered');
+ */
+export declare function conflictResponse(message: string): HttpResponseInit;
+/**
+ * Handles unexpected errors safely by logging details and returning a generic message.
+ * Use in catch blocks to avoid exposing internal error details to clients.
+ * @param error - The caught error
+ * @param context - Azure Functions InvocationContext for logging
+ * @returns Azure Functions HttpResponseInit with 500 status
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   return handleFunctionError(error, context);
+ * }
+ */
+export declare function handleFunctionError(error: unknown, context: InvocationContext): HttpResponseInit;
+/**
+ * Checks if an error is an Azure Table Storage "not found" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 404
+ * @example
+ * try {
+ *   await tableClient.getEntity(pk, rk);
+ * } catch (error) {
+ *   if (isNotFoundError(error)) return notFoundResponse('Entity');
+ *   throw error;
+ * }
+ */
+export declare function isNotFoundError(error: unknown): boolean;
+/**
+ * Checks if an error is an Azure Table Storage "conflict" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 409
+ * @example
+ * try {
+ *   await tableClient.createEntity(entity);
+ * } catch (error) {
+ *   if (isConflictError(error)) return conflictResponse('Entity already exists');
+ *   throw error;
+ * }
+ */
+export declare function isConflictError(error: unknown): boolean;
+/**
+ * Initializes Azure Table Storage configuration. Call once at application startup.
+ * @param config - Storage configuration options
+ * @param config.accountName - Azure Storage account name (for managed identity)
+ * @param config.connectionString - Connection string (for local development)
+ * @example
+ * // Production (Azure with managed identity)
+ * initStorage({ accountName: 'mystorageaccount' });
+ *
+ * // Local development (Azurite)
+ * initStorage({ connectionString: 'UseDevelopmentStorage=true' });
+ */
+export declare function initStorage(config: {
+    accountName?: string;
+    connectionString?: string;
+}): void;
+/**
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
+ */
+export declare function initStorageFromEnv(): void;
+/**
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
+ */
+export declare function useManagedIdentity(): boolean;
+/**
+ * Gets a TableClient for the specified table, creating the table if needed.
+ * Clients are cached for reuse across requests.
+ * @param tableName - The Azure Table Storage table name
+ * @returns A configured TableClient instance
+ * @throws Error if storage is not configured
+ * @example
+ * const client = await getTableClient('users');
+ * await client.createEntity({ partitionKey: 'pk', rowKey: 'rk', name: 'John' });
+ */
+export declare function getTableClient(tableName: string): Promise<TableClient>;
+/**
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
+ */
+export declare function clearTableClientCache(): void;
+/**
+ * Generate a unique row key from an identifier string.
+ * Uses SHA-256 hash for consistent, URL-safe keys.
+ * @param identifier - The string to hash (e.g., subscription endpoint, user ID)
+ * @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';