@markwharton/pwa-core 1.7.0 → 2.0.0

package/dist/server.js

@@ -0,0 +1,476 @@
+"use strict";
+/**
+ * pwa-core/server - Server-side utilities for Azure Functions
+ *
+ * Includes: JWT auth, API keys, HTTP responses, Azure Table Storage
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_STATUS = exports.isAdmin = exports.hasRole = exports.hasUsername = exports.getErrorMessage = exports.err = exports.okVoid = exports.ok = exports.DEFAULT_TOKEN_EXPIRY_SECONDS = exports.DEFAULT_TOKEN_EXPIRY = void 0;
+exports.initAuth = initAuth;
+exports.getJwtSecret = getJwtSecret;
+exports.extractToken = extractToken;
+exports.validateToken = validateToken;
+exports.generateToken = generateToken;
+exports.generateLongLivedToken = generateLongLivedToken;
+exports.requireAuth = requireAuth;
+exports.requireAdmin = requireAdmin;
+exports.extractApiKey = extractApiKey;
+exports.hashApiKey = hashApiKey;
+exports.validateApiKey = validateApiKey;
+exports.generateApiKey = generateApiKey;
+exports.badRequestResponse = badRequestResponse;
+exports.unauthorizedResponse = unauthorizedResponse;
+exports.forbiddenResponse = forbiddenResponse;
+exports.notFoundResponse = notFoundResponse;
+exports.conflictResponse = conflictResponse;
+exports.handleFunctionError = handleFunctionError;
+exports.isNotFoundError = isNotFoundError;
+exports.isConflictError = isConflictError;
+exports.initStorage = initStorage;
+exports.initStorageFromEnv = initStorageFromEnv;
+exports.useManagedIdentity = useManagedIdentity;
+exports.getTableClient = getTableClient;
+exports.clearTableClientCache = clearTableClientCache;
+exports.generateRowKey = generateRowKey;
+const crypto_1 = require("crypto");
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const data_tables_1 = require("@azure/data-tables");
+const identity_1 = require("@azure/identity");
+const shared_1 = require("./shared");
+// =============================================================================
+// JWT Authentication
+// =============================================================================
+let jwtSecret = null;
+/**
+ * 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);
+ */
+function initAuth(secret, minLength = 32) {
+    if (!secret || secret.length < minLength) {
+        throw new Error(`JWT_SECRET must be at least ${minLength} characters`);
+    }
+    jwtSecret = secret;
+}
+/**
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
+ */
+function getJwtSecret() {
+    if (!jwtSecret) {
+        throw new Error('Auth not initialized. Call initAuth() first.');
+    }
+    return jwtSecret;
+}
+/**
+ * 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'));
+ */
+function extractToken(authHeader) {
+    if (!authHeader?.startsWith('Bearer ')) {
+        return null;
+    }
+    return authHeader.slice(7);
+}
+/**
+ * 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);
+ * }
+ */
+function validateToken(token) {
+    try {
+        const payload = jsonwebtoken_1.default.verify(token, getJwtSecret());
+        if (typeof payload === 'object' && payload !== null) {
+            return (0, shared_1.ok)(payload);
+        }
+        return (0, shared_1.err)('Invalid token payload');
+    }
+    catch (error) {
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Token validation failed'));
+    }
+}
+/**
+ * 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');
+ */
+function generateToken(payload, expiresIn = '7d') {
+    return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn });
+}
+/**
+ * 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' });
+ */
+function generateLongLivedToken(payload, expiresInDays = 3650) {
+    return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn: `${expiresInDays}d` });
+}
+// =============================================================================
+// Token Expiry Constants
+// =============================================================================
+/** Default token expiry in days (single source of truth) */
+const DEFAULT_TOKEN_EXPIRY_DAYS = 7;
+/** Default token expiry string for generateToken (7 days) */
+exports.DEFAULT_TOKEN_EXPIRY = `${DEFAULT_TOKEN_EXPIRY_DAYS}d`;
+/** Default token expiry in seconds (7 days = 604800 seconds) */
+exports.DEFAULT_TOKEN_EXPIRY_SECONDS = DEFAULT_TOKEN_EXPIRY_DAYS * 24 * 60 * 60;
+// =============================================================================
+// Auth Helpers
+// =============================================================================
+/**
+ * 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);
+ */
+function requireAuth(authHeader) {
+    const token = extractToken(authHeader);
+    if (!token) {
+        return { authorized: false, response: unauthorizedResponse() };
+    }
+    const result = validateToken(token);
+    if (!result.ok) {
+        return { authorized: false, response: unauthorizedResponse(result.error) };
+    }
+    return { authorized: true, payload: result.data };
+}
+/**
+ * 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
+ */
+function requireAdmin(authHeader) {
+    const auth = requireAuth(authHeader);
+    if (!auth.authorized)
+        return auth;
+    if (!(0, shared_1.isAdmin)(auth.payload)) {
+        return { authorized: false, response: forbiddenResponse('Admin access required') };
+    }
+    return auth;
+}
+// =============================================================================
+// API Key Authentication
+// =============================================================================
+/**
+ * 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);
+ */
+function extractApiKey(request) {
+    return request.headers.get('X-API-Key');
+}
+/**
+ * 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 });
+ */
+function hashApiKey(apiKey) {
+    return (0, crypto_1.createHash)('sha256').update(apiKey).digest('hex');
+}
+/**
+ * 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();
+ */
+function validateApiKey(apiKey, storedHash) {
+    const keyHash = hashApiKey(apiKey);
+    if (keyHash === storedHash) {
+        return (0, shared_1.okVoid)();
+    }
+    return (0, shared_1.err)('Invalid API key');
+}
+/**
+ * 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
+ */
+function generateApiKey() {
+    return (0, crypto_1.randomBytes)(32).toString('hex');
+}
+// =============================================================================
+// HTTP Response Helpers
+// =============================================================================
+/**
+ * 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');
+ */
+function badRequestResponse(message) {
+    return {
+        status: shared_1.HTTP_STATUS.BAD_REQUEST,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * Creates a 401 Unauthorized response.
+ * @param message - The error message (default: 'Unauthorized')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!token) return unauthorizedResponse();
+ */
+function unauthorizedResponse(message = 'Unauthorized') {
+    return {
+        status: shared_1.HTTP_STATUS.UNAUTHORIZED,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * 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');
+ */
+function forbiddenResponse(message = 'Forbidden') {
+    return {
+        status: shared_1.HTTP_STATUS.FORBIDDEN,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * 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' }
+ */
+function notFoundResponse(resource) {
+    return {
+        status: shared_1.HTTP_STATUS.NOT_FOUND,
+        jsonBody: { error: `${resource} not found` }
+    };
+}
+/**
+ * Creates a 409 Conflict response.
+ * @param message - The conflict error message
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (existingUser) return conflictResponse('Email already registered');
+ */
+function conflictResponse(message) {
+    return {
+        status: shared_1.HTTP_STATUS.CONFLICT,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * 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);
+ * }
+ */
+function handleFunctionError(error, context) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    context.error(`Function error: ${message}`);
+    return {
+        status: shared_1.HTTP_STATUS.INTERNAL_ERROR,
+        jsonBody: { error: 'Internal server error' }
+    };
+}
+/**
+ * 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;
+ * }
+ */
+function isNotFoundError(error) {
+    return (error instanceof Error &&
+        'statusCode' in error &&
+        error.statusCode === 404);
+}
+/**
+ * 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;
+ * }
+ */
+function isConflictError(error) {
+    return (error instanceof Error &&
+        'statusCode' in error &&
+        error.statusCode === 409);
+}
+// =============================================================================
+// Azure Table Storage
+// =============================================================================
+// Cache table clients to avoid repeated connections
+const tableClients = new Map();
+// Configuration
+let storageAccountName;
+let storageConnectionString;
+/**
+ * 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' });
+ */
+function initStorage(config) {
+    storageAccountName = config.accountName;
+    storageConnectionString = config.connectionString;
+}
+/**
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
+ */
+function initStorageFromEnv() {
+    initStorage({
+        accountName: process.env.STORAGE_ACCOUNT_NAME,
+        connectionString: process.env.AzureWebJobsStorage
+    });
+}
+/**
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
+ */
+function useManagedIdentity() {
+    return !!storageAccountName && !storageConnectionString?.includes('UseDevelopmentStorage');
+}
+/**
+ * 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' });
+ */
+async function getTableClient(tableName) {
+    // Return cached client if available
+    const cached = tableClients.get(tableName);
+    if (cached) {
+        return cached;
+    }
+    let client;
+    if (useManagedIdentity()) {
+        // Azure: Use managed identity
+        const credential = new identity_1.DefaultAzureCredential();
+        const endpoint = `https://${storageAccountName}.table.core.windows.net`;
+        client = new data_tables_1.TableClient(endpoint, tableName, credential);
+    }
+    else if (storageConnectionString) {
+        // Local/Azurite: Use connection string
+        client = data_tables_1.TableClient.fromConnectionString(storageConnectionString, tableName);
+    }
+    else {
+        throw new Error('Storage not configured. Set STORAGE_ACCOUNT_NAME or AzureWebJobsStorage.');
+    }
+    // Create table if it doesn't exist
+    try {
+        await client.createTable();
+    }
+    catch (error) {
+        // Ignore "table already exists" errors (409 Conflict)
+        const tableError = error;
+        if (tableError.statusCode !== 409) {
+            throw error;
+        }
+    }
+    // Cache and return
+    tableClients.set(tableName, client);
+    return client;
+}
+/**
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
+ */
+function clearTableClientCache() {
+    tableClients.clear();
+}
+/**
+ * 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
+ */
+function generateRowKey(identifier) {
+    return (0, crypto_1.createHash)('sha256').update(identifier).digest('hex').substring(0, 32);
+}
+// =============================================================================
+// Re-exports from shared (for convenience)
+// =============================================================================
+var shared_2 = require("./shared");
+Object.defineProperty(exports, "ok", { enumerable: true, get: function () { return shared_2.ok; } });
+Object.defineProperty(exports, "okVoid", { enumerable: true, get: function () { return shared_2.okVoid; } });
+Object.defineProperty(exports, "err", { enumerable: true, get: function () { return shared_2.err; } });
+Object.defineProperty(exports, "getErrorMessage", { enumerable: true, get: function () { return shared_2.getErrorMessage; } });
+Object.defineProperty(exports, "hasUsername", { enumerable: true, get: function () { return shared_2.hasUsername; } });
+Object.defineProperty(exports, "hasRole", { enumerable: true, get: function () { return shared_2.hasRole; } });
+Object.defineProperty(exports, "isAdmin", { enumerable: true, get: function () { return shared_2.isAdmin; } });
+Object.defineProperty(exports, "HTTP_STATUS", { enumerable: true, get: function () { return shared_2.HTTP_STATUS; } });

package/dist/shared.d.ts

@@ -0,0 +1,150 @@
+/**
+ * pwa-core/shared - Types, constants, and utilities for both server and client
+ *
+ * This module has NO Node.js dependencies and can be safely imported in browsers.
+ */
+/**
+ * Standard result type for operations that can fail.
+ * Used consistently across all modules (auth, push, client).
+ *
+ * @example
+ * // Success
+ * { ok: true, data: user }
+ *
+ * // Failure
+ * { ok: false, error: 'Token expired' }
+ *
+ * // With status code (HTTP/push operations)
+ * { ok: false, error: 'Subscription expired', statusCode: 410 }
+ */
+export interface Result<T> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    statusCode?: number;
+}
+/**
+ * Creates a success result with data.
+ * @param data - The success payload
+ * @returns A Result with ok=true and the provided data
+ * @example
+ * return ok({ user: 'john', role: 'admin' });
+ */
+export declare function ok<T>(data: T): Result<T>;
+/**
+ * Creates a success result with no data.
+ * @returns A Result with ok=true and no data
+ * @example
+ * return okVoid(); // { ok: true }
+ */
+export declare function okVoid(): Result<void>;
+/**
+ * Creates a failure result with an error message.
+ * @param error - The error message
+ * @param statusCode - Optional HTTP status code for API/push operations
+ * @returns A Result with ok=false and the error details
+ * @example
+ * return err('Token expired');
+ * return err('Subscription gone', 410);
+ */
+export declare function err<T>(error: string, statusCode?: number): Result<T>;
+/**
+ * Base JWT payload - all tokens include these fields
+ * Projects extend this with their specific fields
+ */
+export interface BaseJwtPayload {
+    iat: number;
+    exp: number;
+}
+/**
+ * Standard user token payload
+ * Used by: azure-pwa-starter, azure-alert-service (admin), onsite-monitor
+ */
+export interface UserTokenPayload extends BaseJwtPayload {
+    authenticated: true;
+    tokenType: 'user' | 'machine';
+}
+/**
+ * Username-based token payload
+ * Used by: financial-tracker
+ */
+export interface UsernameTokenPayload extends BaseJwtPayload {
+    username: string;
+}
+/**
+ * Role-based token payload
+ * Used by: azure-alert-service
+ */
+export interface RoleTokenPayload extends BaseJwtPayload {
+    authenticated: true;
+    tokenType: 'user' | 'machine';
+    role: 'admin' | 'viewer';
+    viewerTokenId?: string;
+}
+/**
+ * Type guard to check if a JWT payload contains a username field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a string username field
+ * @example
+ * if (hasUsername(payload)) {
+ *   console.log(payload.username); // TypeScript knows username exists
+ * }
+ */
+export declare function hasUsername(payload: BaseJwtPayload): payload is UsernameTokenPayload;
+/**
+ * Type guard to check if a JWT payload contains a role field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a role field
+ * @example
+ * if (hasRole(payload)) {
+ *   console.log(payload.role); // 'admin' | 'viewer'
+ * }
+ */
+export declare function hasRole(payload: BaseJwtPayload): payload is RoleTokenPayload;
+/**
+ * Checks if a JWT payload represents an admin user.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has role='admin'
+ * @example
+ * if (!isAdmin(payload)) {
+ *   return httpForbidden('Admin access required');
+ * }
+ */
+export declare function isAdmin(payload: BaseJwtPayload): boolean;
+/**
+ * HTTP status codes - use instead of magic numbers
+ */
+export declare const HTTP_STATUS: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_ERROR: 500;
+    readonly SERVICE_UNAVAILABLE: 503;
+};
+export type HttpStatus = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];
+/**
+ * Standard error response structure
+ */
+export interface ErrorResponse {
+    error: string;
+    details?: string;
+}
+/**
+ * Extracts error message from unknown error, with fallback.
+ * @param error - The caught error (unknown type)
+ * @param fallback - Default message if error is not an Error instance
+ * @returns The error message string
+ * @example
+ * } catch (error) {
+ *     return err(getErrorMessage(error, 'Operation failed'));
+ * }
+ */
+export declare function getErrorMessage(error: unknown, fallback: string): string;