@markwharton/pwa-core 3.4.2 → 4.0.0

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.
  * @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
  */
-export declare function requireAdmin(authHeader: string | null): AuthResult<RoleTokenPayload>;
+export declare function requireAdmin(authHeader: string | null): Result<RoleTokenPayload>;
 /**
  * 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,7 +441,8 @@ 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>;
     /** Base URL for magic links and SWA preview URL validation */
     appBaseUrl?: string;
@@ -480,16 +464,25 @@ 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>;
+}): void;
 /**
  * Parses cookies from a request's Cookie header.
  * @param request - Request object with headers.get() method
@@ -582,37 +575,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: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
+}): Promise<Result<{
     user: SessionUser;
     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: {
     headers: {
         get(name: string): string | null;
     };
-}): Promise<{
+}): Promise<Result<{
     user: SessionUser;
     headers?: Record<string, string>;
-} | null>;
+}>>;
 /**
  * Destroys the current session and returns a logout cookie string.
  * @param request - Request object with headers.get() method
@@ -676,4 +669,41 @@ export declare function deleteExpiredSessions(): Promise<number>;
  * context.log(`Cleaned up ${deleted} expired magic links`);
  */
 export declare function deleteExpiredMagicLinks(): Promise<number>;
+/**
+ * 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();
+ * }
+ */
+export declare function hasKeyVaultReferences(): boolean;
+/**
+ * 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`);
+ * }
+ */
+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';