/** * Single-use OAuth callbacks for every provider connect flow. * * A browser can deliver the same callback twice, a few hundred milliseconds * apart, with the same `code` and `state`. An authorization code works once * (RFC 6749 4.1.2), so the second exchange is refused, and the same section * tells the authorization server to revoke what the first exchange issued. * Oura does: the connection then fails its first sync with 401 everywhere and * asks for a reconnect. * * The callback therefore claims its `state` before it touches the code. The * claim is an insert that skips on conflict, so of any number of concurrent * requests exactly one wins and exchanges the code. Every other request is a * duplicate: it waits briefly for the winner to finish and sends the browser to * the same place, success page or error page, without reading or writing any * token. When the winner has not finished in time, the duplicate lands on the * integrations page, which shows the connection's real state. * * Where the claim sits differs by flow: * - signed-state flows (Oura, Polar, Strava) claim right after the signature * check, so only a state this server minted can create a row; * - ledger flows (WHOOP, Withings, Fitbit, Google Health) already consume * their state row with an atomic delete. The claim rides the same * transaction (`consumeLedgerState`), so a duplicate's delete waits on the * row lock, finds the row gone, and then sees the committed claim. * * A failed exchange settles the claim with its error page. Trying again means * starting a new connect, which mints a new state and so a new claim. */ import { createHash } from "node:crypto"; import { NextResponse } from "next/server"; import { prisma } from "@/lib/db"; import type { Prisma } from "@/generated/prisma/client"; import { annotate, getEvent } from "@/lib/logging/context"; import { cleanupExpiredOAuthCallbackClaims } from "@/lib/jobs/oauth-callback-claim-cleanup"; /** Providers whose callbacks claim their state here. */ export type OAuthCallbackProvider = | "oura" | "polar" | "strava" | "whoop" | "withings" | "fitbit" | "google-health"; /** * How long a claim is kept. Longer than any state lives (10 minutes), so a * state that still verifies can never find its claim already swept. */ const OAUTH_CALLBACK_CLAIM_TTL_MS = 15 * 60 * 1000; /** How long a duplicate waits for the winning request to finish. */ const DUPLICATE_WAIT_MS = 10_000; const DUPLICATE_POLL_MS = 150; /** Result URLs are short app paths; anything longer is not stored. */ const MAX_LOCATION_LENGTH = 2048; type ClaimDb = Pick; function claimKey(provider: OAuthCallbackProvider, state: string): string { return createHash("sha256").update(`${provider}\0${state}`).digest("hex"); } /** * Claim one callback. True for the one request that may exchange the code, * false for every duplicate. `db` lets a ledger flow claim inside the * transaction that consumes its state row. */ export async function claimOAuthCallback( provider: OAuthCallbackProvider, state: string, db: ClaimDb = prisma, ): Promise { const { count } = await db.oAuthCallbackClaim.createMany({ data: [ { key: claimKey(provider, state), provider, expiresAt: new Date(Date.now() + OAUTH_CALLBACK_CLAIM_TTL_MS), }, ], skipDuplicates: true, }); return count === 1; } /** * Consume a ledger flow's state row and claim the callback in one * transaction. `consume` is the flow's own atomic delete; it throws P2025 for * a row already consumed, which aborts the claim with it. */ export async function consumeLedgerState( provider: OAuthCallbackProvider, state: string, consume: (tx: Prisma.TransactionClient) => Promise, ): Promise { return prisma.$transaction(async (tx) => { const row = await consume(tx); await claimOAuthCallback(provider, state, tx); return row; }); } /** * Run the claimed callback and record where it sent the browser, so a * duplicate can follow. A throw is recorded as settled without a result, and * re-thrown for the route's own error handling. */ export async function settleOAuthCallback( provider: OAuthCallbackProvider, state: string, run: () => Promise, ): Promise { let location: string | null = null; try { const response = await run(); location = response.headers.get("location"); return response; } finally { const now = new Date(); try { await prisma.oAuthCallbackClaim.updateMany({ where: { key: claimKey(provider, state) }, data: { settledAt: now, location: location && location.length <= MAX_LOCATION_LENGTH ? location : null, }, }); await cleanupExpiredOAuthCallbackClaims(prisma, now); } catch (err) { getEvent()?.addWarning(`oauth callback claim settle failed: ${err}`); } } } /** * Answer a duplicate callback: wait for the claiming request to finish and * redirect to the same place, or to `fallbackUrl` when it does not finish in * time or finished without a result. Returns null when no claim exists for * this state at all, which a ledger flow reads as a genuine replay. * * Never touches tokens. Clears the state cookie like the winning request does, * since the browser may render this response instead of that one. */ export async function duplicateOAuthCallback( provider: OAuthCallbackProvider, state: string, opts: { fallbackUrl: string; stateCookie: string; waitMs?: number; }, ): Promise { const key = claimKey(provider, state); const deadline = Date.now() + (opts.waitMs ?? DUPLICATE_WAIT_MS); let row = await prisma.oAuthCallbackClaim.findUnique({ where: { key }, select: { settledAt: true, location: true }, }); if (!row) return null; while (!row?.settledAt && Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, DUPLICATE_POLL_MS)); row = await prisma.oAuthCallbackClaim.findUnique({ where: { key }, select: { settledAt: true, location: true }, }); } const settled = Boolean(row?.settledAt); annotate({ meta: { reason: "duplicate_callback", duplicate_callback_settled: settled, }, }); const response = NextResponse.redirect( settled && row?.location ? row.location : opts.fallbackUrl, ); response.cookies.delete(opts.stateCookie); return response; } /** * The whole single-use step for a flow whose state carries no ledger row: * claim, then either run the callback and record its result, or answer as the * duplicate. */ export async function runOAuthCallbackOnce( provider: OAuthCallbackProvider, state: string, opts: { fallbackUrl: string; stateCookie: string }, run: () => Promise, ): Promise { if (await claimOAuthCallback(provider, state)) { return settleOAuthCallback(provider, state, run); } const duplicate = await duplicateOAuthCallback(provider, state, opts); if (duplicate) return duplicate; const response = NextResponse.redirect(opts.fallbackUrl); response.cookies.delete(opts.stateCookie); return response; }