@markwharton/pwa-core 3.5.0 → 4.0.1

package/dist/server.d.ts

@@ -23,12 +23,11 @@ export declare 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
  */
-export declare function initAuthFromEnv(minLength?: number): void;
+export declare function initAuthFromEnv(): void;
 /**
  * Gets the configured JWT secret.
  * @returns The JWT secret string
@@ -75,50 +74,31 @@ export declare function generateToken<T extends object>(payload: T, expiresIn?:
  * 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.
+ * 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);
  */
-export declare function requireAuth<T extends BaseJwtPayload>(authHeader: string | null): AuthResult<T>;
+export declare function requireAuth<T extends BaseJwtPayload>(authHeader: string | null): Result<T>;
 /**
- * Requires admin role. Use with RoleTokenPayload.
+ * Requires admin role. Generic like requireAuth — callers can extend RoleTokenPayload.
  * @param authHeader - The Authorization header value
- * @returns AuthResult with RoleTokenPayload on success, or HTTP response on failure
+ * @returns Result with payload 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
  */
-export declare function requireAdmin(authHeader: string | null): AuthResult<RoleTokenPayload>;
+export declare function requireAdmin<T extends RoleTokenPayload = RoleTokenPayload>(authHeader: string | null): Result<T>;
 /**
  * Extracts API key from the X-API-Key header.
  * @param request - Request object with headers.get() method
@@ -259,12 +239,14 @@ 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)
+ * @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) });
  */
-export declare function initErrorHandlingFromEnv(callback?: ErrorCallback): void;
+export declare function initErrorHandlingFromEnv(config?: {
+    onError?: 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.
@@ -397,15 +379,16 @@ export declare function upsertEntity<T extends {
 }>(client: TableClient, entity: T): Promise<void>;
 /**
  * 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);
  */
-export declare function deleteEntity(client: TableClient, partitionKey: string, rowKey: string): Promise<boolean>;
+export declare function deleteEntity(client: TableClient, partitionKey: string, rowKey: string): Promise<Result<boolean>>;
 /**
  * Lists all entities in a partition.
  * @typeParam T - The entity type
@@ -458,8 +441,12 @@ export interface SessionAuthConfig {
     allowedDomain?: string;
     /** Emails that get isAdmin=true */
     adminEmails?: string[];
-    /** Custom email validation callback (overrides default allowedEmails/allowedDomain check). Supports async for database lookups. */
+    /** Additional email validation. Called after built-in domain/admin checks reject.
+     *  Can only widen access, never narrow it. Supports async for database lookups. */
     isEmailAllowed?: (email: string) => boolean | Promise<boolean>;
+    /** Transform base SessionUser into an app-specific user type.
+     *  Called after session validation succeeds. Enables generic session functions. */
+    resolveUser?: (user: SessionUser) => Promise<SessionUser> | SessionUser;
     /** Base URL for magic links and SWA preview URL validation */
     appBaseUrl?: string;
     /** Required callback to send magic link emails */
@@ -480,16 +467,28 @@ 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
- * @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),
+ * });
  */
-export declare function initSessionAuthFromEnv(sendEmail: (to: string, magicLink: string) => Promise<boolean>, overrides?: Partial<Omit<SessionAuthConfig, 'sendEmail'>>): void;
+export declare function initSessionAuthFromEnv(config: {
+    sendEmail: (to: string, magicLink: string) => Promise<boolean>;
+    /** Additional email validation. Called after built-in domain/admin checks reject.
+     *  Can only widen access, never narrow it. */
+    isEmailAllowed?: (email: string) => boolean | Promise<boolean>;
+    /** Transform base SessionUser into an app-specific user type.
+     *  Called after session validation succeeds. Enables generic session functions. */
+    resolveUser?: (user: SessionUser) => Promise<SessionUser> | SessionUser;
+}): void;
 /**
  * Parses cookies from a request's Cookie header.
  * @param request - Request object with headers.get() method
@@ -582,37 +581,37 @@ export declare function verifyMagicLink(token: string): Promise<Result<{
  * 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();
  */
-export declare function validateSession(request: {
+export declare function validateSession<T extends SessionUser = SessionUser>(request: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
-    user: SessionUser;
+}): Promise<Result<{
+    user: T;
     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
+ * @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!;
  */
-export declare function getSessionUser(request: {
+export declare function getSessionUser<T extends SessionUser = SessionUser>(request: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
-    user: SessionUser;
+}): Promise<Result<{
+    user: T;
     headers?: Record<string, string>;
-} | null>;
+}>>;
 /**
  * Destroys the current session and returns a logout cookie string.
  * @param request - Request object with headers.get() method
@@ -638,8 +637,8 @@ export declare function destroySession(request: {
  *   })
  * });
  */
-export declare function withSessionAuth(handler: (request: HttpRequest, context: InvocationContext, auth: {
-    user: SessionUser;
+export declare function withSessionAuth<T extends SessionUser = SessionUser>(handler: (request: HttpRequest, context: InvocationContext, auth: {
+    user: T;
     headers?: Record<string, string>;
 }) => Promise<HttpResponseInit>): (request: HttpRequest, context: InvocationContext) => Promise<HttpResponseInit>;
 /**
@@ -654,8 +653,8 @@ export declare function withSessionAuth(handler: (request: HttpRequest, context:
  *   })
  * });
  */
-export declare function withSessionAdminAuth(handler: (request: HttpRequest, context: InvocationContext, auth: {
-    user: SessionUser;
+export declare function withSessionAdminAuth<T extends SessionUser = SessionUser>(handler: (request: HttpRequest, context: InvocationContext, auth: {
+    user: T;
     headers?: Record<string, string>;
 }) => Promise<HttpResponseInit>): (request: HttpRequest, context: InvocationContext) => Promise<HttpResponseInit>;
 /**
@@ -703,4 +702,14 @@ export declare function hasKeyVaultReferences(): boolean;
  * }
  */
 export declare function resolveKeyVaultReferences(): Promise<number>;
+/**
+ * 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);
+ */
+export declare function resultToResponse(result: Result<unknown>): HttpResponseInit;
 export { Result, ok, okVoid, err, getErrorMessage, BaseJwtPayload, UserTokenPayload, UsernameTokenPayload, RoleTokenPayload, hasUsername, hasRole, isAdmin, HTTP_STATUS, HttpStatus, ErrorResponse, SessionUser, SessionInfo, MagicLinkRequest, SessionAuthResponse } from './shared';

package/dist/server.js

@@ -101,6 +101,7 @@ 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");
@@ -130,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
     });
 }
 /**
@@ -225,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.
+ * Requires admin role. Generic like requireAuth — callers can extend RoleTokenPayload.
  * @param authHeader - The Authorization header value
- * @returns AuthResult with RoleTokenPayload on success, or HTTP response on failure
+ * @returns Result with payload 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;
 }
@@ -459,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.
@@ -695,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'));
     }
 }
 /**
@@ -788,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({
@@ -810,8 +817,9 @@ function initSessionAuthFromEnv(sendEmail, overrides) {
         adminEmails: adminEmailsStr
             ? adminEmailsStr.split(',').map(e => e.trim().toLowerCase())
             : undefined,
-        ...overrides,
-        sendEmail
+        isEmailAllowed: config.isEmailAllowed,
+        resolveUser: config.resolveUser,
+        sendEmail: config.sendEmail,
     });
 }
 /**
@@ -1007,10 +1015,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);
     }
@@ -1123,10 +1132,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();
@@ -1134,27 +1143,31 @@ 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;
-        const user = {
+            return (0, shared_1.err)('User not found', shared_1.HTTP_STATUS.UNAUTHORIZED);
+        const baseUser = {
             id: userEntity.id,
             email: userEntity.email,
             isAdmin: userEntity.isAdmin,
             createdAt: userEntity.createdAt,
             lastLoginAt: userEntity.lastLoginAt
         };
+        // Resolve to app-specific user type if callback is configured
+        const user = (config.resolveUser
+            ? await config.resolveUser(baseUser)
+            : baseUser);
         const session = {
             id: sessionEntity.id,
             userId: sessionEntity.userId,
@@ -1179,30 +1192,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.
@@ -1239,13 +1252,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;
     };
@@ -1265,16 +1278,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;
     };
@@ -1295,8 +1308,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++;
         }
     }
@@ -1317,8 +1330,8 @@ 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++;
         }
     }
@@ -1432,6 +1445,24 @@ async function resolveKeyVaultReferences() {
     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