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

package/dist/nextjs/api.js

@@ -209,6 +209,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()}`;
@@ -438,10 +450,116 @@ function pushCsrfCookieRemoval(setCookies) {
   });
 }
 
+// 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/error-envelope.ts
+function refusalEnvelope(error, setCookies = []) {
+  return {
+    status: error.statusCode,
+    body: refusalBody(error),
+    setCookies
+  };
+}
+function refusalBody(error) {
+  const body = error.toJSON();
+  return {
+    ...body,
+    error: {
+      code: body.__type,
+      message: body.message,
+      requestId: mintRequestId()
+    }
+  };
+}
+function mintRequestId() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+// 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) } : {}
+  };
+}
+var sessionBindingInterceptor = {
+  pathPattern: "/_auth/session/binding",
+  method: "POST",
+  response: async (ctx, next) => {
+    const sessionCookie = ctx.cookies.get(COOKIE_NAMES.SESSION);
+    if (ctx.response.status !== 200 || !sessionCookie) {
+      await next();
+      return;
+    }
+    try {
+      const session = await unsealSession(sessionCookie);
+      await pushResealed(ctx.setCookies, applyBinding(session, ctx.response.body, ctx.request.headers));
+    } catch (error) {
+      authLogger.interceptor.general.error("Failed to re-seal the session after a binding change", error);
+      refuseAsUnsealable(ctx);
+    }
+    await next();
+  }
+};
+function refuseAsUnsealable(ctx) {
+  const refusal2 = refusalEnvelope(new SessionResealFailedError());
+  ctx.response.status = refusal2.status;
+  ctx.response.ok = false;
+  ctx.response.body = refusal2.body;
+  for (const name of [COOKIE_NAMES.SESSION, COOKIE_NAMES.SESSION_KEY_ID]) {
+    ctx.setCookies.push({ name, value: "", options: { maxAge: 0, path: "/" } });
+  }
+  pushCsrfCookieRemoval(ctx.setCookies);
+}
+function applyBinding(session, body, requestHeaders) {
+  const { binding, keyExpiresAt, uaFamily: sealedFamily, ...unbound } = session;
+  if (body?.mode !== "passkey") {
+    return unbound;
+  }
+  const fields = bindingSessionFields(
+    { sessionBinding: body.mode, keyExpiresAtMillis: body.keyExpiresAtMillis },
+    requestHeaders["user-agent"]
+  );
+  return { ...unbound, ...fields, ...sealedFamily ? { uaFamily: sealedFamily } : {} };
+}
+async function pushResealed(setCookies, session) {
+  const ttl = getSessionTtl();
+  const options = {
+    httpOnly: true,
+    secure: cookieSecure,
+    sameSite: "lax",
+    maxAge: ttl,
+    path: "/"
+  };
+  setCookies.push({ name: COOKIE_NAMES.SESSION, value: await sealSession(session, ttl), options });
+  setCookies.push({ name: COOKIE_NAMES.SESSION_KEY_ID, value: session.keyId, options });
+  await pushCsrfCookie(setCookies, session.keyId, ttl);
+}
+
 // src/nextjs/interceptors/login-register.ts
 var ROTATING_SIGN_IN_PATHS = /* @__PURE__ */ new Set(["/_auth/login", "/_auth/passkeys/login/verify"]);
 var loginRegisterInterceptor = {
-  pathPattern: /^\/_auth\/(login|register|invitations\/accept|signup\/password|password\/reset\/complete|passkeys\/login\/verify)$/,
+  pathPattern: /^\/_auth\/(login|register|invitations\/accept|signup\/password|password\/reset\/complete|passkeys\/login\/verify|session\/renew\/verify)$/,
   method: "POST",
   request: async (ctx, next) => {
     const oldKeyId = ctx.cookies.get(COOKIE_NAMES.SESSION_KEY_ID);
@@ -482,7 +600,8 @@ var loginRegisterInterceptor = {
         userId: userData.userId,
         privateKey: ctx.metadata.privateKey,
         keyId: ctx.metadata.keyId,
-        algorithm: ctx.metadata.algorithm
+        algorithm: ctx.metadata.algorithm,
+        ...bindingSessionFields(userData, ctx.request.headers["user-agent"])
       };
       const sealed = await sealSession(sessionData, ttl);
       ctx.setCookies.push({
@@ -516,6 +635,155 @@ var loginRegisterInterceptor = {
   }
 };
 
+// src/nextjs/interceptors/mfa-verify.ts
+import { SessionPendingExpiredError, SessionPendingMismatchError } from "@spfn/auth/errors";
+
+// src/server/lib/link-credentials.ts
+import crypto3 from "crypto";
+import { env as env4 } from "@spfn/auth/config";
+function hashCredential(secret) {
+  return crypto3.createHash("sha256").update(secret).digest("base64url");
+}
+
+// src/nextjs/session-helpers.ts
+import * as jose2 from "jose";
+import { cookies } from "next/headers.js";
+import { env as env5 } from "@spfn/auth/config";
+import { logger } from "@spfn/core/logger";
+async function getPendingSessionKey(purpose) {
+  const secret = env5.SPFN_AUTH_SESSION_SECRET;
+  const encoder = new TextEncoder();
+  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) {
+  return await sealFor("oauth", data, ttl);
+}
+async function sealPendingMfaSession(data, ttl = 600) {
+  return await sealFor("mfa", 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(jwt2) {
+  const { payload } = await jose2.jwtDecrypt(jwt2, await getPendingSessionKey("oauth"), {
+    issuer: "spfn-auth",
+    audience: "spfn-oauth"
+  });
+  return payload.data;
+}
+async function unsealPendingMfaSession(jwt2) {
+  const { payload } = await jose2.jwtDecrypt(jwt2, await getPendingSessionKey("mfa"), {
+    issuer: "spfn-auth",
+    audience: "spfn-mfa"
+  });
+  return payload.data;
+}
+
+// src/nextjs/interceptors/mfa-verify.ts
+var MFA_PATH_PATTERN = /^\/_auth\/(login|password\/reset\/complete|oauth\/[\w-]+\/native|oauth\/finalize|mfa\/verify)$/;
+var PENDING_TTL_SECONDS = 600;
+function challengeSecretOf(body) {
+  const challenge = body?.challenge;
+  if (typeof challenge === "string") {
+    return challenge;
+  }
+  const secret = challenge?.secret;
+  return typeof secret === "string" ? secret : void 0;
+}
+async function pendingKeyFor(ctx) {
+  if (ctx.metadata.privateKey && ctx.metadata.keyId) {
+    return {
+      privateKey: ctx.metadata.privateKey,
+      keyId: ctx.metadata.keyId,
+      algorithm: ctx.metadata.algorithm
+    };
+  }
+  const oauthPending = ctx.cookies.get(COOKIE_NAMES.OAUTH_PENDING);
+  return oauthPending ? await unsealPendingSession(oauthPending) : null;
+}
+async function bakePendingCookie(ctx) {
+  const secret = challengeSecretOf(ctx.response.body);
+  const pending = secret ? await pendingKeyFor(ctx) : null;
+  if (!secret || !pending) {
+    return;
+  }
+  ctx.setCookies.push({
+    name: COOKIE_NAMES.MFA_PENDING,
+    value: await sealPendingMfaSession({ ...pending, challengeHash: hashCredential(secret) }, PENDING_TTL_SECONDS),
+    options: {
+      httpOnly: true,
+      secure: cookieSecure,
+      sameSite: "lax",
+      maxAge: PENDING_TTL_SECONDS,
+      path: "/"
+    }
+  });
+  authLogger.interceptor.login.debug("Second-factor pending cookie set", { keyId: pending.keyId });
+}
+function refuse(ctx, error) {
+  authLogger.interceptor.login.warn("Second-factor session not sealed", { reason: error.name });
+  ctx.response.ok = false;
+  ctx.response.status = error.statusCode;
+  ctx.response.statusText = "Unauthorized";
+  ctx.response.body = refusalBody(error);
+}
+async function sealVerifiedSession(ctx) {
+  const cookie = ctx.cookies.get(COOKIE_NAMES.MFA_PENDING);
+  if (!cookie) {
+    refuse(ctx, new SessionPendingExpiredError());
+    return;
+  }
+  const pending = await unsealPendingMfaSession(cookie);
+  const { userId, keyId, challengeHash } = ctx.response.body || {};
+  if (pending.challengeHash !== challengeHash || pending.keyId !== keyId) {
+    refuse(ctx, new SessionPendingMismatchError());
+    return;
+  }
+  const ttl = getSessionTtl();
+  const sealed = await sealSession({
+    userId,
+    privateKey: pending.privateKey,
+    keyId: pending.keyId,
+    algorithm: pending.algorithm,
+    ...bindingSessionFields(ctx.response.body, ctx.request.headers["user-agent"])
+  }, ttl);
+  pushSessionCookies(ctx, sealed, pending.keyId, ttl);
+  await pushCsrfCookie(ctx.setCookies, pending.keyId, ttl);
+}
+function pushSessionCookies(ctx, sealed, keyId, ttl) {
+  const options = { httpOnly: true, secure: cookieSecure, sameSite: "lax", path: "/" };
+  ctx.setCookies.push({ name: COOKIE_NAMES.SESSION, value: sealed, options: { ...options, maxAge: ttl } });
+  ctx.setCookies.push({ name: COOKIE_NAMES.SESSION_KEY_ID, value: keyId, options: { ...options, maxAge: ttl } });
+  ctx.setCookies.push({ name: COOKIE_NAMES.MFA_PENDING, value: "", options: { ...options, maxAge: 0 } });
+}
+var mfaVerifyInterceptor = {
+  pathPattern: MFA_PATH_PATTERN,
+  method: "POST",
+  response: async (ctx, next) => {
+    try {
+      if (ctx.response.status === 202) {
+        await bakePendingCookie(ctx);
+      } else if (ctx.response.status === 200 && ctx.path === "/_auth/mfa/verify") {
+        await sealVerifiedSession(ctx);
+      }
+    } catch (error) {
+      authLogger.interceptor.login.error("Second-factor session handling failed", error);
+      if (ctx.path === "/_auth/mfa/verify") {
+        refuse(ctx, new SessionPendingExpiredError());
+      }
+    }
+    await next();
+  }
+};
+
+// src/nextjs/interceptors/general-auth.ts
+import { SessionContextChangedError, SessionRenewalRequiredError } from "@spfn/auth/errors";
+
+// src/nextjs/interceptors/session-renew.ts
+var SESSION_RENEW_PATH_PATTERN = /^\/_auth\/session\/renew\/(options|verify)$/;
+
 // src/nextjs/interceptors/general-auth.ts
 function requiresAuth(path) {
   const publicPaths = [
@@ -525,11 +793,38 @@ function requiresAuth(path) {
     // Send verification code
     /^\/_auth\/codes\/verify$/,
     // Verify code
-    /^\/_auth\/exists$/
+    /^\/_auth\/exists$/,
     // Check account exists
+    // The two halves of a second-factor step-up (#95). Public for the same
+    // reason `login` is — the key they activate is inactive until they
+    // succeed, so there is nothing to sign them with — and public *here* for
+    // one more: a browser holding a stale session cookie would otherwise have
+    // this rule refresh or clear that session on the way out, over the fresh
+    // one `mfaVerifyInterceptor` just sealed.
+    /^\/_auth\/mfa\/verify$/,
+    /^\/_auth\/mfa\/verify\/options$/
   ];
   return !publicPaths.some((pattern) => pattern.test(path));
 }
+function contextChanged(session, userAgent) {
+  return session.binding === "passkey" && Boolean(session.uaFamily) && Boolean(userAgent) && uaFamily(userAgent) !== session.uaFamily;
+}
+function refuseAsContextChanged(ctx) {
+  authLogger.interceptor.general.warn("Bound session presented from a different browser family", {
+    path: ctx.path,
+    sealed: ctx.metadata.sealedUaFamily,
+    presented: ctx.metadata.presentedUaFamily
+  });
+  const cleared = [
+    { name: COOKIE_NAMES.SESSION, value: "", options: { maxAge: 0, path: "/" } },
+    { name: COOKIE_NAMES.SESSION_KEY_ID, value: "", options: { maxAge: 0, path: "/" } },
+    { name: COOKIE_NAMES.CSRF, value: "", options: { maxAge: 0, path: "/" } }
+  ];
+  ctx.abort = refusalEnvelope(new SessionContextChangedError(), cleared);
+}
+function isKeyExpiredRefusal(body) {
+  return body?.__type === "KeyExpiredError";
+}
 var generalAuthInterceptor = {
   pathPattern: "*",
   // Match all paths, filter by requiresAuth()
@@ -569,6 +864,13 @@ var generalAuthInterceptor = {
       if (await refuseInvalidCsrf(ctx, session.keyId)) {
         return;
       }
+      const presented = ctx.request.headers.get("user-agent");
+      if (contextChanged(session, presented)) {
+        ctx.metadata.sealedUaFamily = session.uaFamily;
+        ctx.metadata.presentedUaFamily = uaFamily(presented);
+        refuseAsContextChanged(ctx);
+        return;
+      }
       const needsRefresh = await shouldRefreshSession(sessionCookie, 24);
       if (needsRefresh) {
         authLogger.interceptor.general.debug("Session needs refresh (within 24h of expiry)");
@@ -591,6 +893,7 @@ var generalAuthInterceptor = {
       ctx.metadata.userId = session.userId;
       ctx.metadata.keyId = session.keyId;
       ctx.metadata.sessionValid = true;
+      ctx.metadata.sessionBound = session.binding === "passkey";
     } catch (error) {
       const err = error;
       const msg = err.message.toLowerCase();
@@ -611,7 +914,12 @@ var generalAuthInterceptor = {
     await next();
   },
   response: async (ctx, next) => {
-    if (ctx.response.status === 401 && ctx.metadata.sessionValid) {
+    if (ctx.response.status === 401 && ctx.metadata.sessionValid && ctx.metadata.sessionBound && isKeyExpiredRefusal(ctx.response.body)) {
+      ctx.response.body = refusalEnvelope(new SessionRenewalRequiredError()).body;
+      await next();
+      return;
+    }
+    if (ctx.response.status === 401 && ctx.metadata.sessionValid && !SESSION_RENEW_PATH_PATTERN.test(ctx.path)) {
       authLogger.interceptor.general.warn("Backend returned 401, clearing session");
       ctx.setCookies.push({
         name: COOKIE_NAMES.SESSION,
@@ -761,6 +1069,11 @@ var keyRotationInterceptor = {
       ctx.metadata.newKeyId = newKeyPair.keyId;
       ctx.metadata.newAlgorithm = newKeyPair.algorithm;
       ctx.metadata.userId = currentSession.userId;
+      ctx.metadata.bindingFields = currentSession.binding ? {
+        binding: currentSession.binding,
+        keyExpiresAt: currentSession.keyExpiresAt,
+        ...currentSession.uaFamily ? { uaFamily: currentSession.uaFamily } : {}
+      } : {};
     } catch (error) {
       const err = error;
       authLogger.interceptor.keyRotation.error("Failed to prepare key rotation", err);
@@ -783,7 +1096,8 @@ var keyRotationInterceptor = {
         userId: ctx.metadata.userId,
         privateKey: ctx.metadata.newPrivateKey,
         keyId: ctx.metadata.newKeyId,
-        algorithm: ctx.metadata.newAlgorithm
+        algorithm: ctx.metadata.newAlgorithm,
+        ...ctx.metadata.bindingFields
       };
       const sealed = await sealSession(newSessionData, ttl);
       ctx.setCookies.push({
@@ -818,10 +1132,10 @@ var keyRotationInterceptor = {
 };
 
 // src/server/lib/oauth/state.ts
-import * as jose2 from "jose";
-import { env as env4 } from "@spfn/auth/config";
+import * as jose3 from "jose";
+import { env as env6 } from "@spfn/auth/config";
 async function getStateKey() {
-  const secret = env4.SPFN_AUTH_SESSION_SECRET;
+  const secret = env6.SPFN_AUTH_SESSION_SECRET;
   const encoder = new TextEncoder();
   const data = encoder.encode(`oauth-state:${secret}`);
   const hashBuffer = await crypto.subtle.digest("SHA-256", data);
@@ -847,7 +1161,7 @@ async function createOAuthState(params) {
     algorithm: params.algorithm,
     metadata: params.metadata
   };
-  const jwe = await new jose2.EncryptJWT({ state }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime("10m").encrypt(key);
+  const jwe = await new jose3.EncryptJWT({ state }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime("10m").encrypt(key);
   return encodeURIComponent(jwe);
 }
 
@@ -866,31 +1180,6 @@ function isSafeReturnPath(returnPath) {
   return !/^\/[^/?#]*:/.test(returnPath);
 }
 
-// src/nextjs/session-helpers.ts
-import * as jose3 from "jose";
-import { cookies } from "next/headers.js";
-import { env as env5 } from "@spfn/auth/config";
-import { logger } from "@spfn/core/logger";
-async function getPendingSessionKey() {
-  const secret = env5.SPFN_AUTH_SESSION_SECRET;
-  const encoder = new TextEncoder();
-  const data = encoder.encode(`oauth-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 jose3.EncryptJWT({ data }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime(`${ttl}s`).setIssuer("spfn-auth").setAudience("spfn-oauth").encrypt(key);
-}
-async function unsealPendingSession(jwt2) {
-  const key = await getPendingSessionKey();
-  const { payload } = await jose3.jwtDecrypt(jwt2, key, {
-    issuer: "spfn-auth",
-    audience: "spfn-oauth"
-  });
-  return payload.data;
-}
-
 // src/nextjs/interceptors/oauth.ts
 var UNSAFE_RETURN_URL_MESSAGE = "returnUrl must be a relative path within the app";
 function refuseUnsafeReturnUrl() {
@@ -1010,7 +1299,7 @@ var oauthFinalizeInterceptor = {
   pathPattern: /^\/_auth\/oauth\/finalize$/,
   method: "POST",
   response: async (ctx, next) => {
-    if (!ctx.response.ok) {
+    if (!ctx.response.ok || ctx.response.status === 202) {
       await next();
       return;
     }
@@ -1044,7 +1333,8 @@ var oauthFinalizeInterceptor = {
         userId,
         privateKey: pendingSession.privateKey,
         keyId: pendingSession.keyId,
-        algorithm: pendingSession.algorithm
+        algorithm: pendingSession.algorithm,
+        ...bindingSessionFields(ctx.response.body, ctx.request.headers["user-agent"])
       }, ttl);
       ctx.setCookies.push({
         name: COOKIE_NAMES.SESSION,
@@ -1202,10 +1492,12 @@ var authInterceptors = [
   signupLinkInterceptor,
   passwordResetInterceptor,
   loginRegisterInterceptor,
+  mfaVerifyInterceptor,
   keyRotationInterceptor,
   oauthUrlInterceptor,
   oauthFinalizeInterceptor,
-  generalAuthInterceptor
+  generalAuthInterceptor,
+  sessionBindingInterceptor
 ];
 
 // src/nextjs/api.ts