@markwharton/pwa-core 4.0.1 → 4.1.0

package/dist/server.d.ts

@@ -417,10 +417,18 @@ export declare function listEntitiesWithFilter<T extends object>(client: TableCl
  * @returns A 32-character hex string suitable for Azure Table Storage row keys
  */
 export declare function generateRowKey(identifier: string): string;
+/**
+ * Authentication method for session auth.
+ * - 'magic-link': Email-based passwordless authentication (default)
+ * - 'easy-auth': Azure Static Web Apps Easy Auth (reads identity from x-ms-client-principal header)
+ */
+export type SessionAuthMethod = 'magic-link' | 'easy-auth';
 /**
  * Configuration for session-based authentication.
  */
 export interface SessionAuthConfig {
+    /** Authentication method (default: 'magic-link') */
+    authMethod?: SessionAuthMethod;
     /** Cookie name for the session (default: 'app_session') */
     cookieName?: string;
     /** Session duration in ms (default: 30 days) */
@@ -449,8 +457,8 @@ export interface SessionAuthConfig {
     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 */
-    sendEmail: (to: string, magicLink: string) => Promise<boolean>;
+    /** Callback to send magic link emails. Required for magic-link auth, ignored for easy-auth. */
+    sendEmail?: (to: string, magicLink: string) => Promise<boolean>;
 }
 /**
  * Initializes session-based authentication. Call once at application startup.
@@ -481,7 +489,10 @@ export declare function initSessionAuth(config: SessionAuthConfig): void;
  * });
  */
 export declare function initSessionAuthFromEnv(config: {
-    sendEmail: (to: string, magicLink: string) => Promise<boolean>;
+    /** Authentication method (default: 'magic-link'). Also reads AUTH_METHOD env var. */
+    authMethod?: SessionAuthMethod;
+    /** Callback to send magic link emails. Required for magic-link auth, ignored for easy-auth. */
+    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>;
@@ -597,6 +608,8 @@ export declare function validateSession<T extends SessionUser = SessionUser>(req
 }>>;
 /**
  * Convenience function: validates session and returns user with optional refresh headers.
+ * For magic-link auth, validates session cookie and handles sliding window refresh.
+ * For easy-auth, reads identity from SWA's x-ms-client-principal header.
  * @param request - Request object with headers.get() method
  * @returns Result with user and optional Set-Cookie headers
  * @example

package/dist/server.js

@@ -783,8 +783,9 @@ const DEFAULT_COOKIE_NAME = 'app_session';
  * });
  */
 function initSessionAuth(config) {
-    if (!config.sendEmail) {
-        throw new Error('sendEmail callback is required for session auth');
+    const method = config.authMethod ?? 'magic-link';
+    if (method === 'magic-link' && !config.sendEmail) {
+        throw new Error('sendEmail callback is required for magic-link auth');
     }
     sessionAuthConfig = config;
 }
@@ -807,7 +808,11 @@ function initSessionAuth(config) {
 function initSessionAuthFromEnv(config) {
     const allowedEmailsStr = process.env.ALLOWED_EMAILS;
     const adminEmailsStr = process.env.ADMIN_EMAILS;
+    const authMethod = config.authMethod
+        ?? process.env.AUTH_METHOD
+        ?? 'magic-link';
     initSessionAuth({
+        authMethod,
         cookieName: process.env.SESSION_COOKIE_NAME,
         appBaseUrl: process.env.APP_BASE_URL,
         allowedEmails: allowedEmailsStr
@@ -1010,6 +1015,12 @@ async function checkMagicLinkRateLimit(email) {
  */
 async function createMagicLink(email, request) {
     const config = getSessionAuthConfig();
+    if (config.authMethod === 'easy-auth') {
+        return (0, shared_1.err)('Magic links are not available in easy-auth mode', shared_1.HTTP_STATUS.BAD_REQUEST);
+    }
+    if (!config.sendEmail) {
+        return (0, shared_1.err)('sendEmail callback is not configured', shared_1.HTTP_STATUS.INTERNAL_ERROR);
+    }
     const normalizedEmail = email.trim().toLowerCase();
     // Validate email format
     if (!isValidEmail(normalizedEmail)) {
@@ -1062,6 +1073,9 @@ async function createMagicLink(email, request) {
  */
 async function verifyMagicLink(token) {
     const config = getSessionAuthConfig();
+    if (config.authMethod === 'easy-auth') {
+        return (0, shared_1.err)('Magic links are not available in easy-auth mode', shared_1.HTTP_STATUS.BAD_REQUEST);
+    }
     // Look up magic link
     const magicLinksClient = await getTableClient(MAGIC_LINKS_TABLE);
     const magicLinkEntity = await getEntityIfExists(magicLinksClient, MAGICLINK_PARTITION, token);
@@ -1198,9 +1212,82 @@ async function validateSession(request) {
         return (0, shared_1.err)('Session validation failed', shared_1.HTTP_STATUS.UNAUTHORIZED);
     }
 }
+/**
+ * Parses the SWA Easy Auth x-ms-client-principal header.
+ * @param request - Request object with headers.get() method
+ * @returns The client principal, or null if header is missing/invalid
+ */
+function parseEasyAuthPrincipal(request) {
+    const header = request.headers.get('x-ms-client-principal');
+    if (!header)
+        return null;
+    try {
+        const decoded = Buffer.from(header, 'base64').toString('utf-8');
+        const principal = JSON.parse(decoded);
+        if (!principal.userDetails)
+            return null;
+        return principal;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validates Easy Auth identity and returns user from the Users table.
+ * Creates the UserEntity on first sign-in (same as magic link flow).
+ * @param request - Request object with x-ms-client-principal header
+ * @returns Result with user (no session info or refresh cookies — SWA manages sessions)
+ */
+async function validateEasyAuth(request) {
+    const config = getSessionAuthConfig();
+    const principal = parseEasyAuthPrincipal(request);
+    if (!principal)
+        return (0, shared_1.err)('No Easy Auth identity', shared_1.HTTP_STATUS.UNAUTHORIZED);
+    const email = principal.userDetails.toLowerCase();
+    const now = new Date().toISOString();
+    const isAdminUser = config.adminEmails
+        ? config.adminEmails.map(e => e.toLowerCase()).includes(email)
+        : false;
+    // Get or create user (same pattern as verifyMagicLink)
+    const usersClient = await getTableClient(USERS_TABLE);
+    let userEntity = await getEntityIfExists(usersClient, USER_PARTITION, email);
+    if (!userEntity) {
+        userEntity = {
+            partitionKey: USER_PARTITION,
+            rowKey: email,
+            id: (0, crypto_1.randomUUID)(),
+            email,
+            isAdmin: isAdminUser || undefined,
+            createdAt: now,
+            lastLoginAt: now
+        };
+        await upsertEntity(usersClient, userEntity);
+    }
+    else {
+        // Update isAdmin and lastLoginAt on each request would be too expensive.
+        // Only update isAdmin if it changed.
+        if ((isAdminUser || undefined) !== userEntity.isAdmin) {
+            userEntity.isAdmin = isAdminUser || undefined;
+            await upsertEntity(usersClient, userEntity);
+        }
+    }
+    const baseUser = {
+        id: userEntity.id,
+        email: userEntity.email,
+        isAdmin: userEntity.isAdmin,
+        createdAt: userEntity.createdAt,
+        lastLoginAt: userEntity.lastLoginAt
+    };
+    const user = (config.resolveUser
+        ? await config.resolveUser(baseUser)
+        : baseUser);
+    return (0, shared_1.ok)({ user });
+}
 // --- Session Operations ---
 /**
  * Convenience function: validates session and returns user with optional refresh headers.
+ * For magic-link auth, validates session cookie and handles sliding window refresh.
+ * For easy-auth, reads identity from SWA's x-ms-client-principal header.
  * @param request - Request object with headers.get() method
  * @returns Result with user and optional Set-Cookie headers
  * @example
@@ -1209,6 +1296,13 @@ async function validateSession(request) {
  * const { user, headers } = result.data!;
  */
 async function getSessionUser(request) {
+    const config = getSessionAuthConfig();
+    if (config.authMethod === 'easy-auth') {
+        const result = await validateEasyAuth(request);
+        if (!result.ok)
+            return result;
+        return (0, shared_1.ok)({ user: result.data.user });
+    }
     const result = await validateSession(request);
     if (!result.ok)
         return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",