@markwharton/pwa-core 3.2.1 → 3.4.0

package/dist/server.js

@@ -27,6 +27,9 @@ exports.unauthorizedResponse = unauthorizedResponse;
 exports.forbiddenResponse = forbiddenResponse;
 exports.notFoundResponse = notFoundResponse;
 exports.conflictResponse = conflictResponse;
+exports.goneResponse = goneResponse;
+exports.tooManyRequestsResponse = tooManyRequestsResponse;
+exports.serviceUnavailableResponse = serviceUnavailableResponse;
 exports.validateRequired = validateRequired;
 exports.initErrorHandling = initErrorHandling;
 exports.initErrorHandlingFromEnv = initErrorHandlingFromEnv;
@@ -40,7 +43,29 @@ exports.useManagedIdentity = useManagedIdentity;
 exports.getTableClient = getTableClient;
 exports.clearTableClientCache = clearTableClientCache;
 exports.getEntityIfExists = getEntityIfExists;
+exports.upsertEntity = upsertEntity;
+exports.deleteEntity = deleteEntity;
+exports.listEntitiesByPartition = listEntitiesByPartition;
+exports.listEntitiesWithFilter = listEntitiesWithFilter;
 exports.generateRowKey = generateRowKey;
+exports.initSessionAuth = initSessionAuth;
+exports.initSessionAuthFromEnv = initSessionAuthFromEnv;
+exports.parseCookies = parseCookies;
+exports.createSessionCookie = createSessionCookie;
+exports.createLogoutCookie = createLogoutCookie;
+exports.getTrustedOrigin = getTrustedOrigin;
+exports.isValidEmail = isValidEmail;
+exports.isEmailAllowed = isEmailAllowed;
+exports.checkMagicLinkRateLimit = checkMagicLinkRateLimit;
+exports.createMagicLink = createMagicLink;
+exports.verifyMagicLink = verifyMagicLink;
+exports.validateSession = validateSession;
+exports.getSessionUser = getSessionUser;
+exports.destroySession = destroySession;
+exports.withSessionAuth = withSessionAuth;
+exports.withSessionAdminAuth = withSessionAdminAuth;
+exports.deleteExpiredSessions = deleteExpiredSessions;
+exports.deleteExpiredMagicLinks = deleteExpiredMagicLinks;
 const crypto_1 = require("crypto");
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const data_tables_1 = require("@azure/data-tables");
@@ -323,6 +348,45 @@ function conflictResponse(message) {
         jsonBody: { error: message }
     };
 }
+/**
+ * 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');
+ */
+function goneResponse(message) {
+    return {
+        status: shared_1.HTTP_STATUS.GONE,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * 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');
+ */
+function tooManyRequestsResponse(message) {
+    return {
+        status: shared_1.HTTP_STATUS.TOO_MANY_REQUESTS,
+        jsonBody: { error: message }
+    };
+}
+/**
+ * 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');
+ */
+function serviceUnavailableResponse(message) {
+    return {
+        status: shared_1.HTTP_STATUS.SERVICE_UNAVAILABLE,
+        jsonBody: { error: message }
+    };
+}
 /**
  * Validates that a required parameter is present.
  * Returns an error response if missing, null if valid.
@@ -360,12 +424,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)
  * @example
  * initErrorHandlingFromEnv(); // Uses process.env automatically
+ * initErrorHandlingFromEnv((op, msg) => sendAlert(op, msg));
  */
-function initErrorHandlingFromEnv(config = {}) {
-    // Future: read ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK, etc.
-    initErrorHandling(config);
+function initErrorHandlingFromEnv(callback) {
+    // Future: read ERROR_LOG_LEVEL, ERROR_INCLUDE_STACK, etc. from process.env
+    initErrorHandling({ callback });
 }
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
@@ -581,6 +647,66 @@ async function getEntityIfExists(client, partitionKey, rowKey) {
         throw error;
     }
 }
+/**
+ * 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' });
+ */
+async function upsertEntity(client, entity) {
+    await client.upsertEntity(entity, 'Replace');
+}
+/**
+ * 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);
+ */
+async function deleteEntity(client, partitionKey, rowKey) {
+    try {
+        await client.deleteEntity(partitionKey, rowKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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');
+ */
+async function listEntitiesByPartition(client, partitionKey) {
+    const filter = (0, data_tables_1.odata) `PartitionKey eq ${partitionKey}`;
+    return listEntitiesWithFilter(client, filter);
+}
+/**
+ * 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);
+ */
+async function listEntitiesWithFilter(client, filter) {
+    const entities = [];
+    for await (const entity of client.listEntities({ queryOptions: { filter } })) {
+        entities.push(entity);
+    }
+    return entities;
+}
 /**
  * Generate a unique row key from an identifier string.
  * Uses SHA-256 hash for consistent, URL-safe keys.
@@ -590,6 +716,574 @@ async function getEntityIfExists(client, partitionKey, rowKey) {
 function generateRowKey(identifier) {
     return (0, crypto_1.createHash)('sha256').update(identifier).digest('hex').substring(0, 32);
 }
+// Partition keys
+const USER_PARTITION = 'user';
+const SESSION_PARTITION = 'session';
+const MAGICLINK_PARTITION = 'magiclink';
+// Table names
+const USERS_TABLE = 'Users';
+const SESSIONS_TABLE = 'Sessions';
+const MAGIC_LINKS_TABLE = 'MagicLinks';
+// Session auth singleton state
+let sessionAuthConfig = null;
+// Default durations
+const DEFAULT_SESSION_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const DEFAULT_SESSION_REFRESH_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_MAGIC_LINK_EXPIRY_MS = 15 * 60 * 1000; // 15 minutes
+const DEFAULT_RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+const DEFAULT_RATE_LIMIT_MAX_REQUESTS = 5;
+const DEFAULT_COOKIE_NAME = 'app_session';
+/**
+ * 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'
+ * });
+ */
+function initSessionAuth(config) {
+    if (!config.sendEmail) {
+        throw new Error('sendEmail callback is required for session auth');
+    }
+    sessionAuthConfig = 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
+ * @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;
+ * });
+ */
+function initSessionAuthFromEnv(sendEmail) {
+    const allowedEmailsStr = process.env.ALLOWED_EMAILS;
+    const adminEmailsStr = process.env.ADMIN_EMAILS;
+    initSessionAuth({
+        cookieName: process.env.SESSION_COOKIE_NAME,
+        appBaseUrl: process.env.APP_BASE_URL,
+        allowedEmails: allowedEmailsStr
+            ? allowedEmailsStr.split(',').map(e => e.trim().toLowerCase())
+            : undefined,
+        allowedDomain: process.env.ALLOWED_DOMAIN,
+        adminEmails: adminEmailsStr
+            ? adminEmailsStr.split(',').map(e => e.trim().toLowerCase())
+            : undefined,
+        sendEmail
+    });
+}
+/**
+ * Gets the session auth configuration.
+ * @returns The session auth config
+ * @throws Error if initSessionAuth() has not been called
+ */
+function getSessionAuthConfig() {
+    if (!sessionAuthConfig) {
+        throw new Error('Session auth not initialized. Call initSessionAuth() first.');
+    }
+    return sessionAuthConfig;
+}
+// --- Cookie Management ---
+/**
+ * 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'];
+ */
+function parseCookies(request) {
+    const cookieHeader = request.headers.get('cookie');
+    if (!cookieHeader)
+        return {};
+    return cookieHeader.split(';').reduce((cookies, cookie) => {
+        const [name, ...rest] = cookie.trim().split('=');
+        if (name && rest.length > 0) {
+            cookies[name] = decodeURIComponent(rest.join('='));
+        }
+        return cookies;
+    }, {});
+}
+/**
+ * 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) } };
+ */
+function createSessionCookie(sessionId) {
+    const config = getSessionAuthConfig();
+    const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+    const durationMs = config.sessionDurationMs ?? DEFAULT_SESSION_DURATION_MS;
+    const sameSite = config.sameSite ?? 'Strict';
+    const expires = new Date(Date.now() + durationMs);
+    const isProduction = process.env.NODE_ENV === 'production';
+    return [
+        `${cookieName}=${encodeURIComponent(sessionId)}`,
+        `Expires=${expires.toUTCString()}`,
+        'Path=/',
+        'HttpOnly',
+        isProduction ? 'Secure' : '',
+        `SameSite=${sameSite}`
+    ].filter(Boolean).join('; ');
+}
+/**
+ * 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() } };
+ */
+function createLogoutCookie() {
+    const config = getSessionAuthConfig();
+    const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+    return [
+        `${cookieName}=`,
+        'Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+        'Path=/',
+        'HttpOnly'
+    ].join('; ');
+}
+// --- SWA Preview URL Support ---
+/**
+ * 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;
+ */
+function getTrustedOrigin(origin) {
+    if (!origin)
+        return undefined;
+    const config = getSessionAuthConfig();
+    const appBaseUrl = config.appBaseUrl;
+    if (!appBaseUrl)
+        return undefined;
+    try {
+        const originUrl = new URL(origin);
+        const baseUrl = new URL(appBaseUrl);
+        // Exact hostname match
+        if (originUrl.hostname === baseUrl.hostname) {
+            return origin;
+        }
+        // Localhost-to-localhost match (local development)
+        if (originUrl.hostname === 'localhost' && baseUrl.hostname === 'localhost') {
+            return origin;
+        }
+        // SWA preview slot match: preview hostname starts with the same app name prefix
+        // e.g., base: witty-sand-0a9e33800.5.azurestaticapps.net
+        //     preview: witty-sand-0a9e33800-19.5.azurestaticapps.net
+        const baseHostParts = baseUrl.hostname.split('.');
+        const originHostParts = originUrl.hostname.split('.');
+        if (baseHostParts.length >= 3 &&
+            originHostParts.length >= 3 &&
+            baseHostParts.slice(-2).join('.') === 'azurestaticapps.net' &&
+            originHostParts.slice(-2).join('.') === 'azurestaticapps.net') {
+            // Extract app name (part before the first dot in the subdomain)
+            const baseAppName = baseHostParts[0].split('-').slice(0, -1).join('-');
+            const originAppName = originHostParts[0].split('-').slice(0, -1).join('-');
+            if (baseAppName && originAppName && originAppName.startsWith(baseAppName)) {
+                return origin;
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// --- Email/Domain Validation ---
+/**
+ * Validates an email address format.
+ * @param email - The email address to validate
+ * @returns True if the email format is valid
+ */
+function isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+/**
+ * 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
+ */
+function isEmailAllowed(email) {
+    const config = getSessionAuthConfig();
+    const normalizedEmail = email.toLowerCase();
+    const hasAllowedEmails = config.allowedEmails && config.allowedEmails.length > 0;
+    const hasAllowedDomain = !!config.allowedDomain;
+    // If neither is configured, allow all
+    if (!hasAllowedEmails && !hasAllowedDomain) {
+        return true;
+    }
+    // Check exact email match
+    if (hasAllowedEmails && config.allowedEmails.includes(normalizedEmail)) {
+        return true;
+    }
+    // Check domain match
+    if (hasAllowedDomain && normalizedEmail.endsWith(config.allowedDomain.toLowerCase())) {
+        return true;
+    }
+    return false;
+}
+// --- Rate Limiting ---
+/**
+ * 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
+ */
+async function checkMagicLinkRateLimit(email) {
+    const config = getSessionAuthConfig();
+    const windowMs = config.rateLimitWindowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS;
+    const maxRequests = config.rateLimitMaxRequests ?? DEFAULT_RATE_LIMIT_MAX_REQUESTS;
+    const client = await getTableClient(MAGIC_LINKS_TABLE);
+    const allLinks = await listEntitiesByPartition(client, MAGICLINK_PARTITION);
+    const windowStart = new Date(Date.now() - windowMs).toISOString();
+    const normalizedEmail = email.toLowerCase();
+    const recentLinks = allLinks.filter(link => link.email.toLowerCase() === normalizedEmail && link.createdAt >= windowStart);
+    return recentLinks.length < maxRequests;
+}
+// --- Magic Link Token Operations ---
+/**
+ * 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 } };
+ */
+async function createMagicLink(email, request) {
+    const config = getSessionAuthConfig();
+    const normalizedEmail = email.trim().toLowerCase();
+    // Validate email format
+    if (!isValidEmail(normalizedEmail)) {
+        return (0, shared_1.err)('Valid email required', shared_1.HTTP_STATUS.BAD_REQUEST);
+    }
+    // Check allowlist
+    if (!isEmailAllowed(normalizedEmail)) {
+        return (0, shared_1.err)('Email not allowed', shared_1.HTTP_STATUS.FORBIDDEN);
+    }
+    // Check rate limit
+    if (!(await checkMagicLinkRateLimit(normalizedEmail))) {
+        return (0, shared_1.err)('Too many requests', shared_1.HTTP_STATUS.TOO_MANY_REQUESTS);
+    }
+    const token = (0, crypto_1.randomUUID)();
+    const now = new Date();
+    const expiryMs = config.magicLinkExpiryMs ?? DEFAULT_MAGIC_LINK_EXPIRY_MS;
+    const expiresAt = new Date(now.getTime() + expiryMs);
+    const magicLinkEntity = {
+        partitionKey: MAGICLINK_PARTITION,
+        rowKey: token,
+        email: normalizedEmail,
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        used: false
+    };
+    const client = await getTableClient(MAGIC_LINKS_TABLE);
+    await upsertEntity(client, magicLinkEntity);
+    // Resolve magic link URL using trusted origin
+    const trustedOrigin = getTrustedOrigin(request.headers.get('origin'));
+    const baseUrl = trustedOrigin ?? config.appBaseUrl ?? '';
+    const magicLink = `${baseUrl}/verify?token=${token}`;
+    const emailSent = await config.sendEmail(normalizedEmail, magicLink);
+    if (!emailSent) {
+        return (0, shared_1.err)('Email service unavailable', shared_1.HTTP_STATUS.SERVICE_UNAVAILABLE);
+    }
+    return (0, shared_1.ok)(token);
+}
+/**
+ * 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 } };
+ */
+async function verifyMagicLink(token) {
+    const config = getSessionAuthConfig();
+    // Look up magic link
+    const magicLinksClient = await getTableClient(MAGIC_LINKS_TABLE);
+    const magicLinkEntity = await getEntityIfExists(magicLinksClient, MAGICLINK_PARTITION, token);
+    if (!magicLinkEntity) {
+        return (0, shared_1.err)('Invalid or expired link', shared_1.HTTP_STATUS.NOT_FOUND);
+    }
+    if (magicLinkEntity.used) {
+        return (0, shared_1.err)('Link already used', shared_1.HTTP_STATUS.GONE);
+    }
+    if (new Date(magicLinkEntity.expiresAt) < new Date()) {
+        return (0, shared_1.err)('Link expired', shared_1.HTTP_STATUS.GONE);
+    }
+    const email = magicLinkEntity.email.toLowerCase();
+    const now = new Date().toISOString();
+    // Get or create user
+    const usersClient = await getTableClient(USERS_TABLE);
+    let userEntity = await getEntityIfExists(usersClient, USER_PARTITION, email);
+    const isAdminUser = config.adminEmails
+        ? config.adminEmails.map(e => e.toLowerCase()).includes(email)
+        : false;
+    if (!userEntity) {
+        userEntity = {
+            partitionKey: USER_PARTITION,
+            rowKey: email,
+            id: (0, crypto_1.randomUUID)(),
+            email,
+            isAdmin: isAdminUser || undefined,
+            createdAt: now,
+            lastLoginAt: now
+        };
+    }
+    else {
+        userEntity.lastLoginAt = now;
+        userEntity.isAdmin = isAdminUser || undefined;
+    }
+    await upsertEntity(usersClient, userEntity);
+    // Create session
+    const durationMs = config.sessionDurationMs ?? DEFAULT_SESSION_DURATION_MS;
+    const sessionId = (0, crypto_1.randomUUID)();
+    const sessionExpiresAt = new Date(Date.now() + durationMs).toISOString();
+    const sessionEntity = {
+        partitionKey: SESSION_PARTITION,
+        rowKey: sessionId,
+        id: sessionId,
+        userId: userEntity.id,
+        email: userEntity.email,
+        createdAt: now,
+        expiresAt: sessionExpiresAt,
+        lastAccessedAt: now
+    };
+    const sessionsClient = await getTableClient(SESSIONS_TABLE);
+    await upsertEntity(sessionsClient, sessionEntity);
+    // Mark token as used
+    magicLinkEntity.used = true;
+    await upsertEntity(magicLinksClient, magicLinkEntity);
+    const user = {
+        id: userEntity.id,
+        email: userEntity.email,
+        isAdmin: userEntity.isAdmin,
+        createdAt: userEntity.createdAt,
+        lastLoginAt: userEntity.lastLoginAt
+    };
+    const sessionCookie = createSessionCookie(sessionId);
+    return (0, shared_1.ok)({ user, sessionCookie });
+}
+// --- Session Validation ---
+/**
+ * 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();
+ */
+async function validateSession(request) {
+    const config = getSessionAuthConfig();
+    const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+    const cookies = parseCookies(request);
+    const sessionId = cookies[cookieName];
+    if (!sessionId)
+        return null;
+    try {
+        const sessionsClient = await getTableClient(SESSIONS_TABLE);
+        const sessionEntity = await getEntityIfExists(sessionsClient, SESSION_PARTITION, sessionId);
+        if (!sessionEntity)
+            return null;
+        // Check expiry
+        if (new Date(sessionEntity.expiresAt) < new Date())
+            return null;
+        // Get user
+        const usersClient = await getTableClient(USERS_TABLE);
+        const userEntity = await getEntityIfExists(usersClient, USER_PARTITION, sessionEntity.email.toLowerCase());
+        if (!userEntity)
+            return null;
+        const user = {
+            id: userEntity.id,
+            email: userEntity.email,
+            isAdmin: userEntity.isAdmin,
+            createdAt: userEntity.createdAt,
+            lastLoginAt: userEntity.lastLoginAt
+        };
+        const session = {
+            id: sessionEntity.id,
+            userId: sessionEntity.userId,
+            email: sessionEntity.email,
+            createdAt: sessionEntity.createdAt,
+            expiresAt: sessionEntity.expiresAt,
+            lastAccessedAt: sessionEntity.lastAccessedAt
+        };
+        // Sliding window: refresh if close to expiry
+        let refreshedCookie;
+        const refreshThreshold = config.sessionRefreshThresholdMs ?? DEFAULT_SESSION_REFRESH_THRESHOLD_MS;
+        const durationMs = config.sessionDurationMs ?? DEFAULT_SESSION_DURATION_MS;
+        const timeUntilExpiry = new Date(sessionEntity.expiresAt).getTime() - Date.now();
+        if (timeUntilExpiry < refreshThreshold) {
+            const now = new Date().toISOString();
+            const newExpiresAt = new Date(Date.now() + durationMs).toISOString();
+            const updatedSession = {
+                ...sessionEntity,
+                expiresAt: newExpiresAt,
+                lastAccessedAt: now
+            };
+            await upsertEntity(sessionsClient, updatedSession);
+            refreshedCookie = createSessionCookie(sessionId);
+        }
+        return { user, session, refreshedCookie };
+    }
+    catch {
+        return null;
+    }
+}
+// --- 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
+ * @example
+ * const result = await getSessionUser(request);
+ * if (!result) return unauthorizedResponse();
+ * return { headers: result.headers, jsonBody: { user: result.user } };
+ */
+async function getSessionUser(request) {
+    const result = await validateSession(request);
+    if (!result)
+        return null;
+    const headers = result.refreshedCookie
+        ? { 'Set-Cookie': result.refreshedCookie }
+        : undefined;
+    return { user: result.user, headers };
+}
+/**
+ * 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 } };
+ */
+async function destroySession(request) {
+    const config = getSessionAuthConfig();
+    const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+    const cookies = parseCookies(request);
+    const sessionId = cookies[cookieName];
+    if (sessionId) {
+        const sessionsClient = await getTableClient(SESSIONS_TABLE);
+        await deleteEntity(sessionsClient, SESSION_PARTITION, sessionId);
+    }
+    return createLogoutCookie();
+}
+// --- Higher-Order Auth Wrappers ---
+/**
+ * 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 } };
+ *   })
+ * });
+ */
+function withSessionAuth(handler) {
+    return async (request, context) => {
+        const result = await getSessionUser(request);
+        if (!result) {
+            return unauthorizedResponse('Not authenticated');
+        }
+        const response = await handler(request, context, result);
+        // Merge refresh cookie headers
+        if (result.headers) {
+            response.headers = { ...result.headers, ...response.headers };
+        }
+        return response;
+    };
+}
+/**
+ * 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 } };
+ *   })
+ * });
+ */
+function withSessionAdminAuth(handler) {
+    return async (request, context) => {
+        const result = await getSessionUser(request);
+        if (!result) {
+            return unauthorizedResponse('Not authenticated');
+        }
+        if (!result.user.isAdmin) {
+            return forbiddenResponse('Admin access required');
+        }
+        const response = await handler(request, context, result);
+        // Merge refresh cookie headers
+        if (result.headers) {
+            response.headers = { ...result.headers, ...response.headers };
+        }
+        return response;
+    };
+}
+// --- Cleanup ---
+/**
+ * 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`);
+ */
+async function deleteExpiredSessions() {
+    const client = await getTableClient(SESSIONS_TABLE);
+    const sessions = await listEntitiesByPartition(client, SESSION_PARTITION);
+    const now = new Date();
+    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)
+                deleted++;
+        }
+    }
+    return deleted;
+}
+/**
+ * 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`);
+ */
+async function deleteExpiredMagicLinks() {
+    const client = await getTableClient(MAGIC_LINKS_TABLE);
+    const links = await listEntitiesByPartition(client, MAGICLINK_PARTITION);
+    const now = new Date();
+    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)
+                deleted++;
+        }
+    }
+    return deleted;
+}
 // =============================================================================
 // Re-exports from shared (for convenience)
 // =============================================================================