@spfn/auth 0.3.0-beta.23 → 0.3.0-beta.25

package/dist/nextjs/server.d.ts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { S as SessionData } from '../session-Dfwu5g2W.js';
-export { i as isSafeReturnPath } from '../session-Dfwu5g2W.js';
-import { K as KeyAlgorithmType } from '../types-DYyhze28.js';
+import { authApi } from '@spfn/auth';
+import { S as SessionData } from '../session-BbhAGZtA.js';
+export { i as isSafeReturnPath } from '../session-BbhAGZtA.js';
+import { K as KeyAlgorithmType } from '../types-CTdoTOxM.js';
 import { NextResponse, NextRequest } from 'next/server';
 
 interface RequireAuthProps {
@@ -19,6 +20,17 @@ interface RequireAuthProps {
      * Fallback UI to show instead of redirecting
      */
     fallback?: ReactNode;
+    /**
+     * Path to send a bound session whose key has run out (#97)
+     *
+     * Not the sign-in page: the person is still signed in and one WebAuthn
+     * ceremony puts a live key back in the cookie. The page this names is the
+     * app's own, and all it has to do is render a client component that calls
+     * `renewSession(api)` and returns them to where they were.
+     *
+     * @default env SPFN_AUTH_SESSION_RENEW_PATH, or '/auth/renew'
+     */
+    renewalPath?: string;
 }
 /**
  * Require Authentication Guard
@@ -38,8 +50,17 @@ interface RequireAuthProps {
  *   <PrivateContent />
  * </RequireAuth>
  * ```
+ *
+ * @example A bound session whose key ran out
+ * ```tsx
+ * // Sent to /account/renew instead of the sign-in page. That page renders a
+ * // client component calling renewSession(api).
+ * <RequireAuth renewalPath="/account/renew">
+ *   <DashboardContent />
+ * </RequireAuth>
+ * ```
  */
-declare function RequireAuth({ children, redirectTo, fallback, }: RequireAuthProps): Promise<react_jsx_runtime.JSX.Element>;
+declare function RequireAuth({ children, redirectTo, renewalPath, fallback, }: RequireAuthProps): Promise<react_jsx_runtime.JSX.Element>;
 
 interface RequireRoleProps {
     /**
@@ -140,29 +161,26 @@ declare function RequirePermission({ permissions, children, redirectTo, fallback
  *
  * Uses authApi to check permissions in real-time
  */
+
+/**
+ * A bound session whose key has run out, seen from a server component.
+ *
+ * The third state `getAuthSessionData` answers with, and the reason it is a
+ * sentinel rather than `null`: a server component's `api.` call goes through the
+ * same proxy a browser's does, so it meets the same renewal-required refusal —
+ * and `null` there would read as "not signed in" and send the person to the
+ * sign-in page, which is precisely the thing renewal exists to avoid. A server
+ * component cannot run a WebAuthn ceremony, so the guard hands the work to a page
+ * that can.
+ */
+declare const RENEWAL_REQUIRED = "renewal-required";
+type AuthSessionData = Awaited<ReturnType<typeof authApi.getAuthSession.call>>;
+/** What a guard gets back: the session, the renewal sentinel, or nothing. */
+type AuthSessionState = AuthSessionData | typeof RENEWAL_REQUIRED | null;
 /**
  * Get current auth session with roles and permissions via API
  */
-declare function getAuthSessionData(): Promise<{
-    role: {
-        id: number;
-        name: string;
-        displayName: string;
-        priority: number;
-    };
-    permissions: {
-        id: number;
-        name: string;
-        displayName: string;
-        category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
-    }[];
-    userId: number;
-    publicId: string;
-    email: string | null;
-    emailVerified: boolean;
-    phoneVerified: boolean;
-    hasPassword: boolean;
-} | null>;
+declare function getAuthSessionData(): Promise<AuthSessionState>;
 /**
  * Get user role
  */
@@ -351,6 +369,18 @@ interface OAuthCallbackOptions {
      * @default '/auth/error'
      */
     errorRedirectUrl?: string;
+    /**
+     * App page that asks for the second factor, when the callback carries a
+     * step-up challenge instead of a session (#95).
+     *
+     * An override for `SPFN_AUTH_MFA_CONFIRM_PATH`, which is where every other
+     * app-page path in this package lives; the env var is the one to set, and
+     * this exists for an app mounting two handlers on different screens. The
+     * handler redirects to it with `?challenge=` and `?returnUrl=`.
+     *
+     * @default env SPFN_AUTH_MFA_CONFIRM_PATH, then '/auth/mfa'
+     */
+    mfaPath?: string;
 }
 /**
  * Create OAuth callback handler for Next.js API Route
@@ -361,6 +391,11 @@ interface OAuthCallbackOptions {
  * 3. Creates full session and saves to cookie
  * 4. Redirects to returnUrl
  *
+ * When the account has a second factor and this device is new to it (#95) the
+ * backend sends `mfaChallenge` in place of `userId` and `keyId`. No session is
+ * sealed; the browser goes to `SPFN_AUTH_MFA_CONFIRM_PATH` with the challenge,
+ * and the session is sealed by `mfaVerifyInterceptor` once the page proves it.
+ *
  * @example
  * ```typescript
  * // /api/auth/callback/route.ts

package/dist/nextjs/server.js

@@ -158,6 +158,18 @@ var COOKIE_NAMES = {
   get OAUTH_PENDING() {
     return `spfn_oauth_pending${getCookieSuffix()}`;
   },
+  /**
+   * Pending second-factor session (privateKey, keyId, challengeHash) (#95)
+   *
+   * Its own name and its own audience, separate from OAUTH_PENDING. The two
+   * coexist: a person who starts a social login in one tab while a password
+   * step-up is outstanding in another has both flows live, and one name would
+   * mean the second overwrote the first — sealing a session with a private key
+   * that does not match the key being activated.
+   */
+  get MFA_PENDING() {
+    return `spfn_mfa_pending${getCookieSuffix()}`;
+  },
   /** OAuth CSRF nonce — double-submit against the (encrypted) state.nonce at callback */
   get OAUTH_CSRF() {
     return `spfn_oauth_csrf${getCookieSuffix()}`;
@@ -215,6 +227,10 @@ function getSessionTtl(override) {
   }
   return 7 * 24 * 60 * 60;
 }
+function getSessionRenewPath() {
+  return env3.SPFN_AUTH_SESSION_RENEW_PATH?.trim() || DEFAULT_SESSION_RENEW_PATH;
+}
+var DEFAULT_SESSION_RENEW_PATH = "/auth/renew";
 
 // src/nextjs/session-helpers.ts
 import { env as env4 } from "@spfn/auth/config";
@@ -268,20 +284,21 @@ async function clearSession() {
   cookieStore.delete(COOKIE_NAMES.SESSION_KEY_ID);
   cookieStore.delete(COOKIE_NAMES.CSRF);
 }
-async function getPendingSessionKey() {
+async function getPendingSessionKey(purpose) {
   const secret = env4.SPFN_AUTH_SESSION_SECRET;
   const encoder = new TextEncoder();
-  const data = encoder.encode(`oauth-pending:${secret}`);
+  const data = encoder.encode(purpose === "oauth" ? `oauth-pending:${secret}` : `mfa-pending:${secret}`);
   const hashBuffer = await crypto.subtle.digest("SHA-256", data);
   return new Uint8Array(hashBuffer);
 }
 async function sealPendingSession(data, ttl = 600) {
-  const key = await getPendingSessionKey();
-  return await new jose2.EncryptJWT({ data }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime(`${ttl}s`).setIssuer("spfn-auth").setAudience("spfn-oauth").encrypt(key);
+  return await sealFor("oauth", data, ttl);
+}
+async function sealFor(purpose, data, ttl) {
+  return await new jose2.EncryptJWT({ data }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime(`${ttl}s`).setIssuer("spfn-auth").setAudience(purpose === "oauth" ? "spfn-oauth" : "spfn-mfa").encrypt(await getPendingSessionKey(purpose));
 }
 async function unsealPendingSession(jwt) {
-  const key = await getPendingSessionKey();
-  const { payload } = await jose2.jwtDecrypt(jwt, key, {
+  const { payload } = await jose2.jwtDecrypt(jwt, await getPendingSessionKey("oauth"), {
     issuer: "spfn-auth",
     audience: "spfn-oauth"
   });
@@ -309,36 +326,48 @@ async function clearPendingSession() {
 
 // src/nextjs/guards/auth-utils.ts
 import { authApi } from "@spfn/auth";
+import { SessionRenewalRequiredError } from "@spfn/auth/errors";
+var RENEWAL_REQUIRED = "renewal-required";
 async function getAuthSessionData() {
   try {
     const session = await authApi.getAuthSession.call();
     authLogger.middleware.debug("Auth session retrieved", { name: session.role?.name });
     return session;
   } catch (error) {
+    if (isRenewalRequired(error)) {
+      authLogger.middleware.debug("Auth session needs renewing");
+      return RENEWAL_REQUIRED;
+    }
     authLogger.middleware.error("Failed to get auth session", { error });
     return null;
   }
 }
+function isRenewalRequired(error) {
+  return error instanceof SessionRenewalRequiredError || error?.name === "SessionRenewalRequiredError";
+}
+function resolvedSession(state) {
+  return state && state !== RENEWAL_REQUIRED ? state : null;
+}
 async function getUserRole() {
-  const session = await getAuthSessionData();
+  const session = resolvedSession(await getAuthSessionData());
   return session?.role?.name || null;
 }
 async function getUserPermissions() {
-  const session = await getAuthSessionData();
+  const session = resolvedSession(await getAuthSessionData());
   if (!session) {
     return [];
   }
   return session.permissions?.map((p) => p.name) || [];
 }
 async function hasAnyRole(requiredRoles) {
-  const session = await getAuthSessionData();
+  const session = resolvedSession(await getAuthSessionData());
   if (!session) {
     return false;
   }
   return requiredRoles.includes(session.role?.name);
 }
 async function hasAnyPermission(requiredPermissions) {
-  const session = await getAuthSessionData();
+  const session = resolvedSession(await getAuthSessionData());
   if (!session) {
     return false;
   }
@@ -351,6 +380,7 @@ import { Fragment, jsx } from "react/jsx-runtime";
 async function RequireAuth({
   children,
   redirectTo = "/auth/login",
+  renewalPath,
   fallback
 }) {
   const session = await getSession();
@@ -361,6 +391,9 @@ async function RequireAuth({
     redirect(redirectTo);
   }
   const serverSession = await getAuthSessionData();
+  if (serverSession === RENEWAL_REQUIRED) {
+    redirect(renewalPath ?? getSessionRenewPath());
+  }
   if (!serverSession) {
     redirect(redirectTo);
   }
@@ -441,6 +474,7 @@ function clearSessionCookies(response) {
 import { NextResponse } from "next/server";
 import { cookies as cookies2 } from "next/headers.js";
 import { env as env5 } from "@spfn/core/config";
+import { env as authEnv } from "@spfn/auth/config";
 import { logger as logger2 } from "@spfn/core/logger";
 
 // src/lib/return-path.ts
@@ -458,10 +492,65 @@ function isSafeReturnPath(returnPath) {
   return !/^\/[^/?#]*:/.test(returnPath);
 }
 
+// src/nextjs/interceptors/session-binding.ts
+import { SessionResealFailedError } from "@spfn/auth/errors";
+
+// src/server/lib/ua-family.ts
+var FAMILY_MARKERS = [
+  { family: "edge", marker: /\bEdg(?:A|iOS)?\// },
+  { family: "chrome", marker: /\b(?:Chrome|CriOS)\// },
+  { family: "firefox", marker: /\b(?:Firefox|FxiOS)\// },
+  { family: "safari", marker: /\bSafari\// }
+];
+function uaFamily(userAgent) {
+  if (!userAgent) {
+    return "other";
+  }
+  return FAMILY_MARKERS.find((entry) => entry.marker.test(userAgent))?.family ?? "other";
+}
+
+// src/nextjs/interceptors/cookie-options.ts
+function resolveSecure() {
+  const override = process.env.SPFN_AUTH_COOKIE_SECURE;
+  if (override !== void 0) {
+    return override === "true";
+  }
+  return process.env.NODE_ENV === "production";
+}
+var cookieSecure = resolveSecure();
+
+// src/nextjs/interceptors/session-binding.ts
+function bindingSessionFields(body, userAgent) {
+  if (body?.sessionBinding !== "passkey" || typeof body.keyExpiresAtMillis !== "number") {
+    return {};
+  }
+  return {
+    binding: "passkey",
+    keyExpiresAt: body.keyExpiresAtMillis,
+    ...userAgent ? { uaFamily: uaFamily(userAgent) } : {}
+  };
+}
+
 // src/nextjs/oauth-handlers.ts
 function safeReturnUrl(requested, defaultRedirect) {
   return requested && isSafeReturnPath(requested) ? requested : defaultRedirect;
 }
+function bindingFromQuery(searchParams) {
+  const expiresAt = Number(searchParams.get("keyExpiresAtMillis"));
+  if (searchParams.get("sessionBinding") !== "passkey" || !Number.isFinite(expiresAt)) {
+    return {};
+  }
+  return { sessionBinding: "passkey", keyExpiresAtMillis: expiresAt };
+}
+function mfaRedirect(request, challenge, returnUrl, configured) {
+  const path = configured || authEnv.SPFN_AUTH_MFA_CONFIRM_PATH || DEFAULT_MFA_CONFIRM_PATH;
+  const target = new URL(path, request.url);
+  target.searchParams.set("challenge", challenge);
+  target.searchParams.set("returnUrl", returnUrl);
+  logger2.debug("OAuth callback needs a second factor", { path });
+  return NextResponse.redirect(target);
+}
+var DEFAULT_MFA_CONFIRM_PATH = "/auth/mfa";
 function createOAuthCallbackHandler(options) {
   const defaultRedirect = options?.defaultRedirectUrl || "/";
   const errorRedirect = options?.errorRedirectUrl || "/auth/error";
@@ -476,6 +565,10 @@ function createOAuthCallbackHandler(options) {
       errorUrl.searchParams.set("error", error);
       return NextResponse.redirect(errorUrl);
     }
+    const mfaChallenge = searchParams.get("mfaChallenge");
+    if (mfaChallenge) {
+      return mfaRedirect(request, mfaChallenge, returnUrl, options?.mfaPath);
+    }
     if (!userId || !keyId) {
       logger2.error("OAuth callback missing required params", { userId: !!userId, keyId: !!keyId });
       const errorUrl = new URL(errorRedirect, request.url);
@@ -497,7 +590,8 @@ function createOAuthCallbackHandler(options) {
         userId,
         privateKey: pendingSession.privateKey,
         keyId: pendingSession.keyId,
-        algorithm: pendingSession.algorithm
+        algorithm: pendingSession.algorithm,
+        ...bindingSessionFields(bindingFromQuery(searchParams), request.headers.get("user-agent"))
       }, ttl);
       const redirectUrl = new URL(returnUrl, request.url);
       const response = NextResponse.redirect(redirectUrl);