/** * The one OAuth client every provider integration speaks through: the * authorization URL, the code exchange, the refresh, and (Strava) the * deauthorization, with the token endpoint's answer classified the same way * for every provider. * * A provider declares what differs (`OAuthClientConfig`): its endpoints and * scope, how its client authenticates (credentials in the form, or HTTP Basic * with or without the client id beside it), the fields its grants add, how * it classifies an answer and names the upstream refusal, the error type it * throws, and where the token sits in the body. Everything else is here once: * the form post, the external-call line on the wide event, the refusal * becoming the provider's own classified error, and a 2xx without a token * object (a captive portal, a gateway 200, a 204) becoming a transient * `empty_token_body` failure instead of a null the caller dereferences. * * The token lifecycle (when to refresh, under which lock, writing the grant * back) is `token.ts`; this module is the wire. * * `__tests__/oauth-wire-parity.test.ts` pins what every provider puts on the * wire and makes of each answer against the hand-written clients this * replaced. */ import { getEvent } from "@/lib/logging/context"; import { safeFetch } from "@/lib/safe-fetch"; import { classifyHttpStatus, type IntegrationClassification, } from "@/lib/integrations/http-status-classifier"; export interface OAuthClientCredentials { clientId: string; clientSecret: string; } /** A provider's verdict on one token-endpoint answer. */ export interface TokenVerdict { classification: IntegrationClassification; /** The status that drove it: HTTP, or a provider's in-body status. */ status: number | undefined; reason: string; } /** What the provider's error type is built from. */ export interface TokenFailure extends TokenVerdict { verb: string; upstreamError: string | undefined; } type FormFields = Readonly>; export interface OAuthClientConfig { /** The service name on the wide event's external-call line. */ service: string; authorizeUrl: string; tokenUrl: string; /** * A second token endpoint asked after the first refused (Oura's legacy * one). Never asked first: an authorization code works once. */ legacyTokenUrl?: { url: string; /** HTTP statuses of the first answer that send the request on. */ retryOn: ReadonlySet; }; redirectUri: () => string; /** Query parameters of the authorization URL after the client and redirect. */ authorizeParams: () => FormFields; /** S256 PKCE: the authorization URL carries the challenge, the exchange the verifier. */ pkce?: boolean; /** * How the client authenticates at the token endpoint: its id and secret in * the form, or HTTP Basic, with the id also in the form for the grants * named. */ clientAuth: | { kind: "form" } | { kind: "basic"; idInForm: { exchange: boolean; refresh: boolean } }; /** Send `Accept: application/json` with the token request. */ acceptJson?: boolean; /** Whether the exchange repeats the redirect URI (RFC 6749 4.1.3). Default true. */ exchangeRedirectUri?: boolean; /** Fields a grant adds to the form (Withings' `action`, WHOOP's `scope`). */ extraFields?: { exchange?: FormFields; refresh?: FormFields }; /** Whether the provider issues refresh tokens at all. */ refresh: boolean; /** Classify one answer. Default: the HTTP status alone. */ classify?: (httpStatus: number, body: unknown) => TokenVerdict; /** The provider's own name for a refusal, read from the body. */ upstreamError?: (body: unknown) => string | undefined; /** The verb a failure is filed under, when it differs from the call's. */ failureVerb?: { exchange?: string; refresh?: string }; /** Build the provider's error type. */ error: (failure: TokenFailure) => Error; /** The token object inside the answer. Default: the body itself. */ tokenOf?: (body: unknown) => unknown; /** Best-effort deauthorization at the provider (Strava). */ deauthorizeUrl?: string; } export interface OAuthClient { readonly redirectUri: () => string; /** The browser redirect to the consent screen; `state` is the CSRF nonce. */ authorizationUrl( state: string, credentials: OAuthClientCredentials, codeChallenge?: string, ): string; /** * Exchange an authorization code. `codeVerifier` is the PKCE verifier; * `useLegacyEndpoint` is false when the code is known to come from the * current authorization server, so a refusal is final. */ exchange( code: string, credentials: OAuthClientCredentials, options?: { codeVerifier?: string; useLegacyEndpoint?: boolean }, ): Promise; /** Refresh an access token. Throws for a provider without refresh tokens. */ refresh( refreshToken: string, credentials: OAuthClientCredentials, ): Promise; /** Tell the provider the grant is gone. Never throws on a refusal. */ deauthorize(accessToken: string): Promise; } const EXCHANGE_VERB = "exchangeCode"; const REFRESH_VERB = "refreshAccessToken"; /** HTTP Basic credentials for the confidential client (RFC 6749 2.3.1). */ export function basicAuthorization( credentials: OAuthClientCredentials, ): string { const raw = `${credentials.clientId}:${credentials.clientSecret}`; return `Basic ${Buffer.from(raw, "utf8").toString("base64")}`; } /** The RFC 6749 `error` code of a refusal body, when it has one. */ export function oauthErrorCode(body: unknown): string | undefined { if (body === null || typeof body !== "object") return undefined; const error = (body as { error?: unknown }).error; return typeof error === "string" ? error : undefined; } function defaultVerdict(httpStatus: number): TokenVerdict { const verdict = classifyHttpStatus(httpStatus); return { classification: verdict.classification, status: verdict.httpStatus, reason: verdict.reason, }; } interface Answer { httpStatus: number; body: unknown; verdict: TokenVerdict; } export function defineOAuthClient( config: OAuthClientConfig, ): OAuthClient { const classify = config.classify ?? ((httpStatus: number) => defaultVerdict(httpStatus)); const upstreamError = config.upstreamError ?? oauthErrorCode; const tokenOf = config.tokenOf ?? ((body: unknown) => body); async function post( url: string, form: Record, credentials: OAuthClientCredentials, eventMethod: string, ): Promise { const headers: Record = { "Content-Type": "application/x-www-form-urlencoded", }; if (config.acceptJson) headers.Accept = "application/json"; if (config.clientAuth.kind === "basic") { headers.Authorization = basicAuthorization(credentials); } const start = performance.now(); const res = await safeFetch(url, { method: "POST", headers, body: new URLSearchParams(form).toString(), }); const body: unknown = await res.json().catch(() => null); const verdict = classify(res.status, body); getEvent()?.addExternalCall({ service: config.service, method: eventMethod, duration_ms: Math.round(performance.now() - start), status: res.status, error: verdict.classification === "success" ? undefined : verdict.reason, }); return { httpStatus: res.status, body, verdict }; } function settle(answer: Answer, verb: string): Token { const { verdict, body } = answer; if (verdict.classification !== "success") { throw config.error({ ...verdict, verb, upstreamError: upstreamError(body), }); } const token = tokenOf(body); if (token === null || typeof token !== "object") { throw config.error({ classification: "transient", status: answer.httpStatus, reason: "empty_token_body", verb, upstreamError: undefined, }); } return token as Token; } async function request( grant: "exchange" | "refresh", form: Record, credentials: OAuthClientCredentials, mayUseLegacy: boolean, ): Promise { const eventMethod = grant === "exchange" ? EXCHANGE_VERB : REFRESH_VERB; const verb = config.failureVerb?.[grant] ?? eventMethod; const first = await post(config.tokenUrl, form, credentials, eventMethod); const legacy = config.legacyTokenUrl; if (legacy && mayUseLegacy && legacy.retryOn.has(first.httpStatus)) { const second = await post( legacy.url, form, credentials, `${eventMethod}.legacy`, ); if (second.httpStatus >= 200 && second.httpStatus < 300) { return settle(second, verb); } // Neither endpoint took it; the first answer describes the grant for // every current client, so that is the one reported. } return settle(first, verb); } function clientFields( grant: "exchange" | "refresh", credentials: OAuthClientCredentials, ): Record { if (config.clientAuth.kind === "form") { return { client_id: credentials.clientId, client_secret: credentials.clientSecret, }; } return config.clientAuth.idInForm[grant] ? { client_id: credentials.clientId } : {}; } return { redirectUri: config.redirectUri, authorizationUrl(state, credentials, codeChallenge) { if (config.pkce && !codeChallenge) { throw new Error( `${config.service}: the authorization needs a PKCE challenge`, ); } const params = new URLSearchParams({ response_type: "code", client_id: credentials.clientId, redirect_uri: config.redirectUri(), ...config.authorizeParams(), ...(config.pkce && codeChallenge ? { code_challenge: codeChallenge, code_challenge_method: "S256" } : {}), state, }); return `${config.authorizeUrl}?${params}`; }, exchange(code, credentials, options = {}) { if (config.pkce && !options.codeVerifier) { throw new Error( `${config.service}: the exchange needs the PKCE verifier`, ); } return request( "exchange", { ...config.extraFields?.exchange, grant_type: "authorization_code", code, ...clientFields("exchange", credentials), ...(config.exchangeRedirectUri === false ? {} : { redirect_uri: config.redirectUri() }), ...(options.codeVerifier ? { code_verifier: options.codeVerifier } : {}), }, credentials, options.useLegacyEndpoint ?? true, ); }, refresh(refreshToken, credentials) { if (!config.refresh) { return Promise.reject( new Error(`${config.service} issues no refresh tokens`), ); } return request( "refresh", { ...config.extraFields?.refresh, grant_type: "refresh_token", refresh_token: refreshToken, ...clientFields("refresh", credentials), }, credentials, true, ); }, async deauthorize(accessToken) { if (!config.deauthorizeUrl) return; const start = performance.now(); const res = await safeFetch(config.deauthorizeUrl, { method: "POST", headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json", }, }); getEvent()?.addExternalCall({ service: config.service, method: "deauthorize", duration_ms: Math.round(performance.now() - start), status: res.status, error: res.ok ? undefined : `http_${res.status}`, }); }, }; }