@markwharton/pwa-core 3.4.2 → 4.0.0

package/dist/server.js

@@ -4,6 +4,39 @@
  *
  * Includes: JWT auth, API keys, HTTP responses, Azure Table Storage
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -66,6 +99,9 @@ exports.withSessionAuth = withSessionAuth;
 exports.withSessionAdminAuth = withSessionAdminAuth;
 exports.deleteExpiredSessions = deleteExpiredSessions;
 exports.deleteExpiredMagicLinks = deleteExpiredMagicLinks;
+exports.hasKeyVaultReferences = hasKeyVaultReferences;
+exports.resolveKeyVaultReferences = resolveKeyVaultReferences;
+exports.resultToResponse = resultToResponse;
 const crypto_1 = require("crypto");
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const data_tables_1 = require("@azure/data-tables");
@@ -95,15 +131,13 @@ function initAuth(config) {
 /**
  * Initializes JWT authentication from environment variables.
  * Reads JWT_SECRET from process.env.
- * @param minLength - Minimum required secret length (default: 32)
  * @throws Error if JWT_SECRET is missing or too short
  * @example
  * initAuthFromEnv(); // Uses process.env.JWT_SECRET
  */
-function initAuthFromEnv(minLength = 32) {
+function initAuthFromEnv() {
     initAuth({
         secret: process.env.JWT_SECRET,
-        minLength
     });
 }
 /**
@@ -190,41 +224,41 @@ exports.DEFAULT_TOKEN_EXPIRY_SECONDS = DEFAULT_TOKEN_EXPIRY_DAYS * 24 * 60 * 60;
 // Auth Helpers
 // =============================================================================
 /**
- * Validates auth header and returns typed payload or error response.
+ * Validates auth header and returns typed payload or error result.
  * @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
+ * @returns Result with payload on success, or error with status on failure
  * @example
  * const auth = requireAuth<UsernameTokenPayload>(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
- * console.log(auth.payload.username);
+ * if (!auth.ok) return resultToResponse(auth);
+ * console.log(auth.data.username);
  */
 function requireAuth(authHeader) {
     const token = extractToken(authHeader);
     if (!token) {
-        return { authorized: false, response: unauthorizedResponse() };
+        return (0, shared_1.err)('Unauthorized', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
     const result = validateToken(token);
     if (!result.ok) {
-        return { authorized: false, response: unauthorizedResponse(result.error) };
+        return (0, shared_1.err)(result.error ?? 'Unauthorized', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
-    return { authorized: true, payload: result.data };
+    return (0, shared_1.ok)(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
+ * @returns Result with RoleTokenPayload on success, or error with status on failure
  * @example
  * const auth = requireAdmin(request.headers.get('Authorization'));
- * if (!auth.authorized) return auth.response;
+ * if (!auth.ok) return resultToResponse(auth);
  * // User is admin
  */
 function requireAdmin(authHeader) {
     const auth = requireAuth(authHeader);
-    if (!auth.authorized)
+    if (!auth.ok)
         return auth;
-    if (!(0, shared_1.isAdmin)(auth.payload)) {
-        return { authorized: false, response: forbiddenResponse('Admin access required') };
+    if (!(0, shared_1.isAdmin)(auth.data)) {
+        return (0, shared_1.err)('Admin access required', shared_1.HTTP_STATUS.FORBIDDEN);
     }
     return auth;
 }
@@ -424,14 +458,14 @@ 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)
+ * @param config - Optional config with onError callback invoked when handleFunctionError is called (fire-and-forget)
  * @example
  * initErrorHandlingFromEnv(); // Uses process.env automatically
- * initErrorHandlingFromEnv((op, msg) => sendAlert(op, msg));
+ * initErrorHandlingFromEnv({ onError: (op, msg) => sendAlert(op, msg) });
  */
-function initErrorHandlingFromEnv(callback) {
+function initErrorHandlingFromEnv(config) {
     // Future: read ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK, etc. from process.env
-    initErrorHandling({ callback });
+    initErrorHandling({ callback: config?.onError });
 }
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
@@ -660,21 +694,25 @@ async function upsertEntity(client, entity) {
 }
 /**
  * Deletes an entity from Azure Table Storage.
- * Returns true on success, false on error (swallows errors).
+ * Returns ok(true) if deleted, ok(false) if not found (not an error), err() on real failures.
  * @param client - The TableClient instance
  * @param partitionKey - The partition key
  * @param rowKey - The row key
- * @returns True if deleted successfully, false on error
+ * @returns Result with true if deleted, false if not found, or error on failure
  * @example
- * const deleted = await deleteEntity(client, 'session', sessionId);
+ * const result = await deleteEntity(client, 'session', sessionId);
+ * if (!result.ok) console.error(result.error);
  */
 async function deleteEntity(client, partitionKey, rowKey) {
     try {
         await client.deleteEntity(partitionKey, rowKey);
-        return true;
+        return (0, shared_1.ok)(true);
     }
-    catch {
-        return false;
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return (0, shared_1.ok)(false);
+        }
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Delete failed'));
     }
 }
 /**
@@ -753,16 +791,20 @@ function initSessionAuth(config) {
 /**
  * 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
- * @param overrides - Optional config overrides (e.g., isEmailAllowed callback)
+ * Only callbacks go in the config object — data comes from env vars.
+ * Use initSessionAuth() directly for full control.
+ * @param config - Required config with sendEmail callback and optional isEmailAllowed
  * @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;
- * }, { isEmailAllowed: async (email) => lookupInDatabase(email) });
+ * initSessionAuthFromEnv({
+ *   sendEmail: async (to, magicLink) => {
+ *     await resend.emails.send({ to, html: `<a href="${magicLink}">Sign In</a>` });
+ *     return true;
+ *   },
+ *   isEmailAllowed: async (email) => lookupInDatabase(email),
+ * });
  */
-function initSessionAuthFromEnv(sendEmail, overrides) {
+function initSessionAuthFromEnv(config) {
     const allowedEmailsStr = process.env.ALLOWED_EMAILS;
     const adminEmailsStr = process.env.ADMIN_EMAILS;
     initSessionAuth({
@@ -775,8 +817,8 @@ function initSessionAuthFromEnv(sendEmail, overrides) {
         adminEmails: adminEmailsStr
             ? adminEmailsStr.split(',').map(e => e.trim().toLowerCase())
             : undefined,
-        ...overrides,
-        sendEmail
+        isEmailAllowed: config.isEmailAllowed,
+        sendEmail: config.sendEmail,
     });
 }
 /**
@@ -972,10 +1014,11 @@ async function createMagicLink(email, request) {
     if (!isValidEmail(normalizedEmail)) {
         return (0, shared_1.err)('Valid email required', shared_1.HTTP_STATUS.BAD_REQUEST);
     }
-    // Check allowlist (custom callback overrides default)
-    const emailAllowed = config.isEmailAllowed
-        ? await config.isEmailAllowed(normalizedEmail)
-        : isEmailAllowed(normalizedEmail);
+    // Check allowlist (built-in first, custom extends — can only widen access)
+    const emailAllowed = isEmailAllowed(normalizedEmail)
+        || (config.isEmailAllowed
+            ? await config.isEmailAllowed(normalizedEmail)
+            : false);
     if (!emailAllowed) {
         return (0, shared_1.err)('Email not allowed', shared_1.HTTP_STATUS.FORBIDDEN);
     }
@@ -1088,10 +1131,10 @@ async function verifyMagicLink(token) {
  * 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
+ * @returns Result with user, session, and optional refreshed cookie
  * @example
  * const result = await validateSession(request);
- * if (!result) return unauthorizedResponse();
+ * if (!result.ok) return unauthorizedResponse();
  */
 async function validateSession(request) {
     const config = getSessionAuthConfig();
@@ -1099,20 +1142,20 @@ async function validateSession(request) {
     const cookies = parseCookies(request);
     const sessionId = cookies[cookieName];
     if (!sessionId)
-        return null;
+        return (0, shared_1.err)('No session cookie', shared_1.HTTP_STATUS.UNAUTHORIZED);
     try {
         const sessionsClient = await getTableClient(SESSIONS_TABLE);
         const sessionEntity = await getEntityIfExists(sessionsClient, SESSION_PARTITION, sessionId);
         if (!sessionEntity)
-            return null;
+            return (0, shared_1.err)('Invalid session', shared_1.HTTP_STATUS.UNAUTHORIZED);
         // Check expiry
         if (new Date(sessionEntity.expiresAt) < new Date())
-            return null;
+            return (0, shared_1.err)('Session expired', shared_1.HTTP_STATUS.UNAUTHORIZED);
         // Get user
         const usersClient = await getTableClient(USERS_TABLE);
         const userEntity = await getEntityIfExists(usersClient, USER_PARTITION, sessionEntity.email.toLowerCase());
         if (!userEntity)
-            return null;
+            return (0, shared_1.err)('User not found', shared_1.HTTP_STATUS.UNAUTHORIZED);
         const user = {
             id: userEntity.id,
             email: userEntity.email,
@@ -1144,30 +1187,30 @@ async function validateSession(request) {
             await upsertEntity(sessionsClient, updatedSession);
             refreshedCookie = createSessionCookie(sessionId);
         }
-        return { user, session, refreshedCookie };
+        return (0, shared_1.ok)({ user, session, refreshedCookie });
     }
     catch {
-        return null;
+        return (0, shared_1.err)('Session validation failed', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
 }
 // --- Session Operations ---
 /**
  * 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
+ * @returns Result with user and optional Set-Cookie headers
  * @example
  * const result = await getSessionUser(request);
- * if (!result) return unauthorizedResponse();
- * return { headers: result.headers, jsonBody: { user: result.user } };
+ * if (!result.ok) return resultToResponse(result);
+ * const { user, headers } = result.data!;
  */
 async function getSessionUser(request) {
     const result = await validateSession(request);
-    if (!result)
-        return null;
-    const headers = result.refreshedCookie
-        ? { 'Set-Cookie': result.refreshedCookie }
+    if (!result.ok)
+        return result;
+    const headers = result.data.refreshedCookie
+        ? { 'Set-Cookie': result.data.refreshedCookie }
         : undefined;
-    return { user: result.user, headers };
+    return (0, shared_1.ok)({ user: result.data.user, headers });
 }
 /**
  * Destroys the current session and returns a logout cookie string.
@@ -1204,13 +1247,13 @@ async function destroySession(request) {
 function withSessionAuth(handler) {
     return async (request, context) => {
         const result = await getSessionUser(request);
-        if (!result) {
+        if (!result.ok) {
             return unauthorizedResponse('Not authenticated');
         }
-        const response = await handler(request, context, result);
+        const response = await handler(request, context, result.data);
         // Merge refresh cookie headers
-        if (result.headers) {
-            response.headers = { ...result.headers, ...response.headers };
+        if (result.data.headers) {
+            response.headers = { ...result.data.headers, ...response.headers };
         }
         return response;
     };
@@ -1230,16 +1273,16 @@ function withSessionAuth(handler) {
 function withSessionAdminAuth(handler) {
     return async (request, context) => {
         const result = await getSessionUser(request);
-        if (!result) {
+        if (!result.ok) {
             return unauthorizedResponse('Not authenticated');
         }
-        if (!result.user.isAdmin) {
+        if (!result.data.user.isAdmin) {
             return forbiddenResponse('Admin access required');
         }
-        const response = await handler(request, context, result);
+        const response = await handler(request, context, result.data);
         // Merge refresh cookie headers
-        if (result.headers) {
-            response.headers = { ...result.headers, ...response.headers };
+        if (result.data.headers) {
+            response.headers = { ...result.data.headers, ...response.headers };
         }
         return response;
     };
@@ -1260,8 +1303,8 @@ async function deleteExpiredSessions() {
     let deleted = 0;
     for (const session of sessions) {
         if (new Date(session.expiresAt) < now) {
-            const success = await deleteEntity(client, SESSION_PARTITION, session.rowKey);
-            if (success)
+            const result = await deleteEntity(client, SESSION_PARTITION, session.rowKey);
+            if (result.ok && result.data)
                 deleted++;
         }
     }
@@ -1282,14 +1325,139 @@ async function deleteExpiredMagicLinks() {
     let deleted = 0;
     for (const link of links) {
         if (new Date(link.expiresAt) < now || link.used) {
-            const success = await deleteEntity(client, MAGICLINK_PARTITION, link.rowKey);
-            if (success)
+            const result = await deleteEntity(client, MAGICLINK_PARTITION, link.rowKey);
+            if (result.ok && result.data)
                 deleted++;
         }
     }
     return deleted;
 }
 // =============================================================================
+// Key Vault Secret Resolution
+// =============================================================================
+/**
+ * Pattern to match Azure Key Vault references in environment variables.
+ * Format: @Microsoft.KeyVault(SecretUri=https://{vault}.vault.azure.net/secrets/{name}[/{version}])
+ */
+const KEY_VAULT_PATTERN = /^@Microsoft\.KeyVault\(SecretUri=(.+)\)$/;
+/**
+ * Parses a Key Vault secret URI into vault URL, secret name, and optional version.
+ * @param secretUri - Full Key Vault secret URI
+ * @returns Parsed components or null if invalid
+ */
+function parseSecretUri(secretUri) {
+    try {
+        const url = new URL(secretUri);
+        const pathParts = url.pathname.split('/').filter(Boolean);
+        // Expected: /secrets/{name} or /secrets/{name}/{version}
+        if (pathParts.length < 2 || pathParts[0] !== 'secrets') {
+            return null;
+        }
+        return {
+            vaultUrl: `${url.protocol}//${url.host}`,
+            secretName: pathParts[1],
+            secretVersion: pathParts[2]
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks if any environment variables contain Key Vault references.
+ * Useful for skipping resolution in development environments.
+ * @returns True if any env vars match the @Microsoft.KeyVault pattern
+ * @example
+ * if (hasKeyVaultReferences()) {
+ *   await resolveKeyVaultReferences();
+ * }
+ */
+function hasKeyVaultReferences() {
+    for (const value of Object.values(process.env)) {
+        if (value && KEY_VAULT_PATTERN.test(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolves all @Microsoft.KeyVault(SecretUri=...) references in process.env.
+ * Replaces env var values in-place with the resolved secret values.
+ * Uses DefaultAzureCredential for authentication (managed identity in Azure, az cli locally).
+ *
+ * Requires @azure/keyvault-secrets as a peer dependency.
+ *
+ * @returns Number of secrets resolved
+ * @throws Error if any secret resolution fails (fail-fast)
+ * @example
+ * // In sessionAuthInit.ts (before any other initialization):
+ * if (hasKeyVaultReferences()) {
+ *   const count = await resolveKeyVaultReferences();
+ *   console.log(`Resolved ${count} Key Vault secrets`);
+ * }
+ */
+async function resolveKeyVaultReferences() {
+    // Dynamic import - only loaded when Key Vault references are present
+    const { SecretClient } = await Promise.resolve().then(() => __importStar(require('@azure/keyvault-secrets')));
+    // Group env vars by vault URL to reuse clients
+    const vaultSecrets = new Map();
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!value)
+            continue;
+        const match = value.match(KEY_VAULT_PATTERN);
+        if (!match)
+            continue;
+        const parsed = parseSecretUri(match[1]);
+        if (!parsed) {
+            throw new Error(`Invalid Key Vault secret URI in ${key}: ${match[1]}`);
+        }
+        const existing = vaultSecrets.get(parsed.vaultUrl) ?? [];
+        existing.push({ envKey: key, secretName: parsed.secretName, secretVersion: parsed.secretVersion });
+        vaultSecrets.set(parsed.vaultUrl, existing);
+    }
+    if (vaultSecrets.size === 0) {
+        return 0;
+    }
+    const cred = getCredential();
+    let resolved = 0;
+    for (const [vaultUrl, secrets] of vaultSecrets) {
+        const client = new SecretClient(vaultUrl, cred);
+        for (const { envKey, secretName, secretVersion } of secrets) {
+            try {
+                const secret = await client.getSecret(secretName, secretVersion ? { version: secretVersion } : undefined);
+                if (!secret.value) {
+                    throw new Error(`Secret '${secretName}' in ${vaultUrl} has no value`);
+                }
+                process.env[envKey] = secret.value;
+                resolved++;
+            }
+            catch (error) {
+                const message = (0, shared_1.getErrorMessage)(error, 'Unknown error');
+                throw new Error(`Failed to resolve Key Vault secret '${secretName}' for ${envKey}: ${message}`);
+            }
+        }
+    }
+    return resolved;
+}
+// =============================================================================
+// Result Conversion Helper
+// =============================================================================
+/**
+ * Convert a failed Result to an HttpResponseInit.
+ * Use after checking `!result.ok` to return the error as an HTTP response.
+ * @param result - A failed Result (ok=false)
+ * @returns HttpResponseInit with the error status and message
+ * @example
+ * const auth = requireAuth<UsernameTokenPayload>(authHeader);
+ * if (!auth.ok) return resultToResponse(auth);
+ */
+function resultToResponse(result) {
+    return {
+        status: result.status ?? shared_1.HTTP_STATUS.INTERNAL_ERROR,
+        jsonBody: { error: result.error ?? 'Unknown error' }
+    };
+}
+// =============================================================================
 // Re-exports from shared (for convenience)
 // =============================================================================
 var shared_2 = require("./shared");

package/dist/shared.d.ts

@@ -15,13 +15,13 @@
  * { ok: false, error: 'Token expired' }
  *
  * // With status code (HTTP/push operations)
- * { ok: false, error: 'Subscription expired', statusCode: 410 }
+ * { ok: false, error: 'Subscription expired', status: 410 }
  */
 export interface Result<T> {
     ok: boolean;
     data?: T;
     error?: string;
-    statusCode?: number;
+    status?: number;
 }
 /**
  * Creates a success result with data.
@@ -41,13 +41,13 @@ 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
+ * @param status - 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>;
+export declare function err<T = never>(error: string, status?: number): Result<T>;
 /**
  * Base JWT payload - all tokens include these fields
  * Projects extend this with their specific fields

package/dist/shared.js

@@ -35,15 +35,15 @@ function okVoid() {
 /**
  * Creates a failure result with an error message.
  * @param error - The error message
- * @param statusCode - Optional HTTP status code for API/push operations
+ * @param status - 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);
  */
-function err(error, statusCode) {
-    return statusCode !== undefined
-        ? { ok: false, error, statusCode }
+function err(error, status) {
+    return status !== undefined
+        ? { ok: false, error, status }
         : { ok: false, error };
 }
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "3.4.2",
+  "version": "4.0.0",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,12 +30,19 @@
   "peerDependencies": {
     "@azure/data-tables": "^13.0.0",
     "@azure/identity": "^4.0.0",
+    "@azure/keyvault-secrets": "^4.0.0",
     "jsonwebtoken": "^9.0.0"
   },
+  "peerDependenciesMeta": {
+    "@azure/keyvault-secrets": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@azure/data-tables": "^13.2.2",
     "@azure/functions": "^4.5.0",
     "@azure/identity": "^4.5.0",
+    "@azure/keyvault-secrets": "^4.10.0",
     "@types/jsonwebtoken": "^9.0.5",
     "@types/node": "^20.10.0",
     "jsonwebtoken": "^9.0.2",