Enhance OAuth and OTP handling with request context serialization

- Updated the OAuth authorization route to support a union response schema, allowing for both JSON and text responses with appropriate status codes.
- Improved the OTP sign-in code route by incorporating request context serialization for new users, ensuring accurate tracking of sign-up details.
- Refactored the verification code handler to deserialize stored sign-up request context, enhancing user experience during sign-in.
- Added new utility functions for serializing and deserializing sign-up request context, improving data handling across authentication flows.
- Enhanced tests to validate the new request context handling in OTP sign-in scenarios.

Author: mantrakp04

apps/backend/src/app/api/latest/auth/oauth/authorize/[provider_id]/route.tsx

@@ -5,14 +5,15 @@ import { getRequestContextAndBotChallengeAssessment, botChallengeFlowRequestSche
 import { getProjectBranchFromClientId, getProvider } from "@/oauth";
 import { globalPrismaClient } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import type { SmartResponse } from "@/route-handlers/smart-response";
 import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
-import { urlSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { urlSchema, yupArray, yupNumber, yupObject, yupString, yupUnion } from "@stackframe/stack-shared/dist/schema-fields";
 import { getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { cookies } from "next/headers";
 import { redirect } from "next/navigation";
 import { generators } from "openid-client";
-import * as yup from "yup";
+import type { InferType, Schema } from "yup";
 
 const outerOAuthFlowExpirationInMinutes = 10;
 
@@ -52,15 +53,25 @@ export const GET = createSmartRouteHandler({
       response_type: yupString().defined(),
     }).noUnknown(/* Allow unknown query params such as ttclid, other stuff that's being injected by browsers */ false).defined(),
   }),
-  response: yupObject({
-    // The SDK uses stack_response_mode=json so it can intercept bot challenges before navigating.
-    // The redirect path (default) is the legacy browser-direct flow.
-    statusCode: yupNumber().oneOf([200]).defined(),
-    bodyType: yupString().oneOf(["json"]).defined(),
-    body: yupObject({
-      location: yupString().defined(),
+  response: yupUnion(
+    yupObject({
+      // The SDK uses stack_response_mode=json so it can intercept bot challenges before navigating.
+      // The redirect path (default) is the legacy browser-direct flow.
+      statusCode: yupNumber().oneOf([200]).defined(),
+      bodyType: yupString().oneOf(["json"]).defined(),
+      body: yupObject({
+        location: yupString().defined(),
+      }).defined(),
     }).defined(),
-  }),
+    yupObject({
+      statusCode: yupNumber().oneOf([307]).defined(),
+      headers: yupObject({
+        location: yupArray(yupString().defined()).defined(),
+      }).defined(),
+      bodyType: yupString().oneOf(["text"]).defined(),
+      body: yupString().defined(),
+    }).defined(),
+  ) as unknown as Schema<SmartResponse>,
   async handler({ params, query }, fullReq) {
     const tenancy = await getSoleTenancyFromProjectBranch(...getProjectBranchFromClientId(query.client_id), true);
     if (!tenancy) {
@@ -138,7 +149,7 @@ export const GET = createSmartRouteHandler({
           turnstileResult: turnstileAssessment.status,
           turnstileVisibleChallengeResult: turnstileAssessment.visibleChallengeResult,
           responseMode: query.stack_response_mode,
-        } satisfies yup.InferType<typeof oauthCookieSchema>,
+        } satisfies InferType<typeof oauthCookieSchema>,
         expiresAt: new Date(Date.now() + 1000 * 60 * outerOAuthFlowExpirationInMinutes),
       },
     });

apps/backend/src/app/api/latest/auth/otp/send-sign-in-code/route.tsx

@@ -1,4 +1,5 @@
 import { getRequestContextAndBotChallengeAssessment, botChallengeFlowRequestSchemaFields } from "@/lib/turnstile";
+import { serializeStoredSignUpRequestContext } from "@/lib/sign-up-context";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { adaptSchema, clientOrHigherAuthTypeSchema, emailOtpSignInCallbackUrlSchema, signInEmailSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
@@ -39,7 +40,7 @@ export const POST = createSmartRouteHandler({
 
     await ensureUserForEmailAllowsOtp(tenancy, email);
 
-    const { turnstileAssessment } = await getRequestContextAndBotChallengeAssessment(botChallenge, "send_magic_link_email", tenancy);
+    const { requestContext, turnstileAssessment } = await getRequestContextAndBotChallengeAssessment(botChallenge, "send_magic_link_email", tenancy);
 
     const { nonce } = await signInVerificationCodeHandler.sendCode(
       {
@@ -49,6 +50,7 @@ export const POST = createSmartRouteHandler({
         data: {
           turnstile_result: turnstileAssessment.status,
           turnstile_visible_challenge_result: turnstileAssessment.visibleChallengeResult,
+          ...serializeStoredSignUpRequestContext(requestContext),
         },
       },
       { email }

apps/backend/src/app/api/latest/auth/otp/sign-in/verification-code-handler.tsx

@@ -3,7 +3,7 @@ import { getAuthContactChannelWithEmailNormalization } from "@/lib/contact-chann
 import { sendEmailFromDefaultTemplate } from "@/lib/emails";
 import { getSoleTenancyFromProjectBranch, Tenancy } from "@/lib/tenancies";
 import { createAuthTokens } from "@/lib/tokens";
-import { buildSignUpRuleOptions, reconstructTurnstileAssessment } from "@/lib/sign-up-context";
+import { buildSignUpRuleOptions, deserializeStoredSignUpRequestContext, reconstructTurnstileAssessment, storedSignUpRequestContextSchemaFields } from "@/lib/sign-up-context";
 import { createOrUpgradeAnonymousUserWithRules } from "@/lib/users";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createVerificationCodeHandler } from "@/route-handlers/verification-code-handler";
@@ -78,6 +78,7 @@ export const signInVerificationCodeHandler = createVerificationCodeHandler({
   data: yupObject({
     turnstile_result: yupString().oneOf(turnstileResultValues).defined(),
     turnstile_visible_challenge_result: yupString().oneOf(turnstileResultValues).optional(),
+    ...storedSignUpRequestContextSchemaFields,
   }),
   method: yupObject({
     email: emailSchema.defined(),
@@ -125,13 +126,11 @@ export const signInVerificationCodeHandler = createVerificationCodeHandler({
         buildSignUpRuleOptions({
           authMethod: 'otp',
           oauthProvider: null,
-          requestContext: null,
+          requestContext: deserializeStoredSignUpRequestContext(data),
           turnstileAssessment: reconstructTurnstileAssessment(
             data.turnstile_result,
             data.turnstile_visible_challenge_result,
           ),
-          // Request context is not available in the verification code handler because the
-          // sign-in code is verified in a separate request from where it was sent
         })
       );
       isNewUser = true;

apps/backend/src/lib/openapi.tsx

@@ -117,6 +117,36 @@ function isMaybeRequestSchemaForAudience(requestDescribe: yup.SchemaObjectDescri
   return true;
 }
 
+function getResponseDescriptions(responseSchema: yup.AnySchema): yup.SchemaObjectDescription[] {
+  const schemaInfo = responseSchema.meta()?.stackSchemaInfo;
+  const responseSchemas = schemaInfo?.type === "union" ? schemaInfo.items : [responseSchema];
+
+  return responseSchemas.map((schema) => {
+    const responseDescribe = schema.describe();
+    if (!isSchemaObjectDescription(responseDescribe)) {
+      throw new Error('Response schema must be a yup.ObjectSchema');
+    }
+    return responseDescribe;
+  });
+}
+
+function mergeParsedResponses(parsedResponses: any[]) {
+  const [firstResponse, ...remainingResponses] = parsedResponses;
+  if (!firstResponse) {
+    throw new StackAssertionError("Expected at least one parsed response");
+  }
+
+  return remainingResponses.reduce((acc, response) => {
+    return {
+      ...acc,
+      responses: {
+        ...acc.responses,
+        ...response.responses,
+      },
+    };
+  }, firstResponse);
+}
+
 
 function parseRouteHandler(options: {
   handler: SmartRouteHandler,
@@ -130,9 +160,8 @@ function parseRouteHandler(options: {
     if (overload.metadata?.hidden) continue;
 
     const requestDescribe = overload.request.describe();
-    const responseDescribe = overload.response.describe();
     if (!isSchemaObjectDescription(requestDescribe)) throw new Error('Request schema must be a yup.ObjectSchema');
-    if (!isSchemaObjectDescription(responseDescribe)) throw new Error('Response schema must be a yup.ObjectSchema');
+    const responseDescribes = getResponseDescriptions(overload.response);
 
     // estimate whether this overload is the right one based on a heuristic
     if (!isMaybeRequestSchemaForAudience(requestDescribe, options.audience)) {
@@ -150,18 +179,20 @@ function parseRouteHandler(options: {
       `);
     }
 
-    result = parseOverload({
-      metadata: overload.metadata,
-      method: options.method,
-      path: options.path,
-      pathDesc: undefinedIfMixed(requestDescribe.fields.params),
-      parameterDesc: undefinedIfMixed(requestDescribe.fields.query),
-      headerDesc: undefinedIfMixed(requestDescribe.fields.headers),
-      requestBodyDesc: undefinedIfMixed(requestDescribe.fields.body),
-      responseDesc: undefinedIfMixed(responseDescribe.fields.body),
-      responseTypeDesc: undefinedIfMixed(responseDescribe.fields.bodyType) ?? throwErr('Response type must be defined and not mixed', { options, bodyTypeField: responseDescribe.fields.bodyType }),
-      statusCodeDesc: undefinedIfMixed(responseDescribe.fields.statusCode) ?? throwErr('Status code must be defined and not mixed', { options, statusCodeField: responseDescribe.fields.statusCode }),
-    });
+    result = mergeParsedResponses(responseDescribes.map((responseDescribe) => {
+      return parseOverload({
+        metadata: overload.metadata,
+        method: options.method,
+        path: options.path,
+        pathDesc: undefinedIfMixed(requestDescribe.fields.params),
+        parameterDesc: undefinedIfMixed(requestDescribe.fields.query),
+        headerDesc: undefinedIfMixed(requestDescribe.fields.headers),
+        requestBodyDesc: undefinedIfMixed(requestDescribe.fields.body),
+        responseDesc: undefinedIfMixed(responseDescribe.fields.body),
+        responseTypeDesc: undefinedIfMixed(responseDescribe.fields.bodyType) ?? throwErr('Response type must be defined and not mixed', { options, bodyTypeField: responseDescribe.fields.bodyType }),
+        statusCodeDesc: undefinedIfMixed(responseDescribe.fields.statusCode) ?? throwErr('Status code must be defined and not mixed', { options, statusCodeField: responseDescribe.fields.statusCode }),
+      });
+    }));
   }
 
   return result;

apps/backend/src/lib/sign-up-context.ts

@@ -1,8 +1,43 @@
+import { yupBoolean, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { SignUpAuthMethod } from "@stackframe/stack-shared/dist/utils/auth-methods";
 import { BestEffortEndUserRequestContext } from "./end-users";
 import { SignUpTurnstileAssessment } from "./turnstile";
 import { SignUpRuleOptions } from "./users";
 
+export const storedSignUpRequestContextSchemaFields = {
+  sign_up_ip_address: yupString().nullable().defined(),
+  sign_up_ip_trusted: yupBoolean().nullable().defined(),
+  sign_up_country_code: yupString().nullable().defined(),
+} as const;
+
+export type StoredSignUpRequestContext = {
+  sign_up_ip_address: string | null,
+  sign_up_ip_trusted: boolean | null,
+  sign_up_country_code: string | null,
+};
+
+export function serializeStoredSignUpRequestContext(requestContext: BestEffortEndUserRequestContext): StoredSignUpRequestContext {
+  return {
+    sign_up_ip_address: requestContext.ipAddress,
+    sign_up_ip_trusted: requestContext.ipTrusted,
+    sign_up_country_code: requestContext.location?.countryCode ?? null,
+  };
+}
+
+export function deserializeStoredSignUpRequestContext(data: StoredSignUpRequestContext): BestEffortEndUserRequestContext | null {
+  if (data.sign_up_ip_address == null && data.sign_up_ip_trusted == null && data.sign_up_country_code == null) {
+    return null;
+  }
+
+  return {
+    ipAddress: data.sign_up_ip_address,
+    ipTrusted: data.sign_up_ip_trusted,
+    location: data.sign_up_country_code == null ? null : {
+      countryCode: data.sign_up_country_code,
+    },
+  };
+}
+
 /**
  * Builds a `SignUpRuleOptions` from a request context and auth details.
  * Centralises the boilerplate that every auth route previously duplicated.
@@ -19,6 +54,7 @@ export function buildSignUpRuleOptions(params: {
     ipAddress: params.requestContext?.ipAddress ?? null,
     ipTrusted: params.requestContext?.ipTrusted ?? null,
     countryCode: params.requestContext?.location?.countryCode ?? null,
+    requestContext: params.requestContext,
     turnstileAssessment: params.turnstileAssessment,
   };
 }

apps/backend/src/lib/turnstile.tsx

@@ -113,6 +113,7 @@ export async function verifyTurnstileToken(params: {
   expectedAction: TurnstileAction,
   isAllowedHostname?: (hostname: string) => boolean,
   secretKey?: string,
+  captureRejectedAsError?: boolean,
 }): Promise<SignUpTurnstileAssessment> {
   const token = params.token?.trim() ?? "";
   if (!token) {
@@ -134,12 +135,14 @@ export async function verifyTurnstileToken(params: {
   const data = result.data;
 
   if (!data.success) {
-    captureError("turnstile-siteverify-rejected", new StackAssertionError("Turnstile siteverify returned success=false", {
-      errorCodes: data["error-codes"],
-      expectedAction: params.expectedAction,
-      receivedAction: data.action,
-      hostname: data.hostname,
-    }));
+    if (params.captureRejectedAsError ?? true) {
+      captureError("turnstile-siteverify-rejected", new StackAssertionError("Turnstile siteverify returned success=false", {
+        errorCodes: data["error-codes"],
+        expectedAction: params.expectedAction,
+        receivedAction: data.action,
+        hostname: data.hostname,
+      }));
+    }
     return { status: "invalid" };
   }
 
@@ -165,7 +168,10 @@ export async function verifyTurnstileTokenWithOptionalVisibleChallenge(params: {
   phase?: "invisible" | "visible",
   secretKey?: string,
 }): Promise<SignUpTurnstileAssessment> {
-  const assessment = await verifyTurnstileToken(params);
+  const assessment = await verifyTurnstileToken({
+    ...params,
+    captureRejectedAsError: params.phase !== "invisible",
+  });
 
   switch (params.phase) {
     case undefined: {
@@ -263,6 +269,21 @@ import.meta.vitest?.describe("verifyTurnstileToken(...)", () => {
       .resolves.toEqual({ status: "error" });
   });
 
+  test("can suppress captureError for expected siteverify rejections", async ({ expect }) => {
+    const errorsModule = await import("@stackframe/stack-shared/dist/utils/errors");
+    const captureErrorSpy = vi.spyOn(errorsModule, "captureError").mockImplementation(() => {});
+    stubFetch({ success: false, action: "sign_up_with_credential" });
+
+    await expect(verifyTurnstileToken({
+      ...baseParams,
+      token: "real-token",
+      remoteIp: "127.0.0.1",
+      captureRejectedAsError: false,
+    })).resolves.toEqual({ status: "invalid" });
+
+    expect(captureErrorSpy).not.toHaveBeenCalled();
+  });
+
   const allowMyapp = (h: string) => h === "myapp.com" || matchHostnamePattern("*.myapp.com", h);
 
   test("returns invalid when hostname does not match allowed hostnames", async ({ expect }) => {

apps/backend/src/lib/users.tsx

@@ -6,7 +6,7 @@ import { normalizeCountryCode, validCountryCodeSet } from "@stackframe/stack-sha
 import { SignUpAuthMethod } from "@stackframe/stack-shared/dist/utils/auth-methods";
 import { KeyIntersect } from "@stackframe/stack-shared/dist/utils/types";
 import { createSignUpRuleContext } from "./cel-evaluator";
-import { getBestEffortEndUserRequestContext } from "./end-users";
+import { BestEffortEndUserRequestContext, getBestEffortEndUserRequestContext } from "./end-users";
 import { calculateSignUpRiskAssessment } from "./risk-scores";
 import { evaluateSignUpRules } from "./sign-up-rules";
 import { Tenancy } from "./tenancies";
@@ -23,6 +23,7 @@ export type SignUpRuleOptions = {
   ipAddress: string | null,
   ipTrusted: boolean | null,
   countryCode: string | null,
+  requestContext?: BestEffortEndUserRequestContext | null,
   turnstileAssessment: SignUpTurnstileAssessment,
 };
 
@@ -122,9 +123,11 @@ export async function createOrUpgradeAnonymousUserWithRules(
 ): Promise<UsersCrud["Admin"]["Read"]> {
   const email = createOrUpdate.primary_email ?? currentUser?.primary_email ?? null;
   const primaryEmailVerified = createOrUpdate.primary_email_verified ?? currentUser?.primary_email_verified ?? false;
-  const endUserRequestContext = signUpRuleOptions.ipAddress !== null && signUpRuleOptions.ipTrusted !== null && signUpRuleOptions.countryCode !== null
-    ? null
-    : await getBestEffortEndUserRequestContext();
+  const endUserRequestContext = signUpRuleOptions.requestContext !== undefined
+    ? signUpRuleOptions.requestContext
+    : signUpRuleOptions.ipAddress !== null && signUpRuleOptions.ipTrusted !== null
+      ? null
+      : await getBestEffortEndUserRequestContext();
   const requestIpAddress = signUpRuleOptions.ipAddress ?? endUserRequestContext?.ipAddress ?? null;
   const requestIpTrusted = signUpRuleOptions.ipTrusted ?? endUserRequestContext?.ipTrusted ?? null;
   // EndUserLocation.countryCode is string | undefined; coerce to string | null for downstream consumers

apps/e2e/tests/backend/endpoints/api/v1/auth/otp/sign-in.test.ts

@@ -344,6 +344,44 @@ it("should sign in with both codes when requesting two sign in codes before usin
   `);
 });
 
+it("should use the send-sign-in-code request context when creating a new OTP user", async ({ expect }) => {
+  backendContext.set({
+    ipData: {
+      ipAddress: "127.0.0.70",
+      country: "CA",
+      city: "Toronto",
+      region: "ON",
+      latitude: 43.6532,
+      longitude: -79.3832,
+      tzIdentifier: "America/Toronto",
+    },
+  });
+
+  const { sendSignInCodeResponse } = await Auth.Otp.sendSignInCode();
+  const signInCode = await Auth.Otp.getSignInCodeFromMailbox(sendSignInCodeResponse.body.nonce);
+
+  backendContext.set({
+    ipData: {
+      ipAddress: "127.0.0.71",
+      country: "US",
+      city: "New York",
+      region: "NY",
+      latitude: 40.7128,
+      longitude: -74.006,
+      tzIdentifier: "America/New_York",
+    },
+  });
+
+  const { userId } = await Auth.Otp.signInWithCode(signInCode);
+  const userResponse = await niceBackendFetch(`/api/v1/users/${userId}`, {
+    method: "GET",
+    accessType: "server",
+  });
+
+  expect(userResponse.status).toBe(200);
+  expect(userResponse.body.country_code).toBe("CA");
+});
+
 it.todo("should not sign in if e-mail's usedForAuth status has changed since sign-in code was sent");
 
 it.todo("should not sign in if account's otpEnabled status has changed since sign-in code was sent");