:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { IAuthOAuthFlowService } from "@posthog/core/auth/identifiers";
import {
type CancelFlowOutput,
type OAuthErrorCode,
type OAuthTokenResponse,
oAuthTokenResponse,
type RefreshTokenOutput,
type StartFlowOutput,
} from "@posthog/core/auth/oauth.schemas";
import type { RootLogger } from "@posthog/di/logger";
import {
type CloudRegion,
getCloudUrlFromRegion,
getOauthClientIdFromRegion,
OAUTH_SCOPES,
} from "@posthog/shared";
// Browser implementation of the auth OAuth flow. Desktop's OAuthService drives
// PKCE through a posthog-code:// deep link (prod) or a loopback HTTP server
// (dev); neither exists in a browser. Here the authorize page opens in a
// popup, the OAuth server redirects it back to /oauth/callback on this origin,
// and the callback page relays code+state to this (still-running) tab over a
// BroadcastChannel. Token exchange and refresh are the same plain fetches
// desktop makes.
//
// CORS on /oauth/token and /api/* is open (verified against us.posthog.com),
// so the only external requirement is redirect URI registration on the Code
// ("Array") OAuth application. The path is /callback to match the portless
// localhost convention: PostHog's authorize view extends RFC 8252 §7.3 port
// flexibility to `localhost`, so a registered `http://localhost/callback`
// matches this app on any dev port. Production needs
// `https://<web-origin>/callback` registered once a web origin exists. Until
// registration, the flow fails at the authorize step with a visible error.
export const OAUTH_CALLBACK_PATH = "/callback";
const OAUTH_CALLBACK_CHANNEL = "posthog-code:oauth-callback";
const FLOW_TIMEOUT_MS = 5 * 60 * 1000;
const TOKEN_FETCH_TIMEOUT_MS = 30_000;
const POPUP_FEATURES = "popup,width=600,height=760";
interface OAuthCallbackMessage {
code: string | null;
state: string | null;
error: string | null;
}
class HttpError extends Error {
constructor(
readonly status: number,
message: string,
) {
super(message);
}
}
function getWebRedirectUri(): string {
return `${window.location.origin}${OAUTH_CALLBACK_PATH}`;
}
export class WebOAuthFlowService implements IAuthOAuthFlowService {
private pendingFlow: { cancel: (reason: string) => void } | null = null;
constructor(private readonly log: RootLogger) {}
startFlow(region: CloudRegion): Promise<StartFlowOutput> {
return this.runFlow(region, "login");
}
startSignupFlow(region: CloudRegion): Promise<StartFlowOutput> {
return this.runFlow(region, "signup");
}
async refreshToken(
refreshToken: string,
region: CloudRegion,
): Promise<RefreshTokenOutput> {
try {
const data = await this.postTokenEndpoint(region, {
grant_type: "refresh_token",
refresh_token: refreshToken,
client_id: getOauthClientIdFromRegion(region),
});
return { success: true, data };
} catch (error) {
return {
success: false,
error: messageOf(error),
errorCode: classifyError(error),
};
}
}
cancelFlow(): CancelFlowOutput {
if (!this.pendingFlow) {
return { success: false, error: "No pending flow" };
}
this.pendingFlow.cancel("Authentication canceled");
return { success: true };
}
private async runFlow(
region: CloudRegion,
kind: "login" | "signup",
): Promise<StartFlowOutput> {
this.pendingFlow?.cancel("Superseded by a new sign-in attempt");
try {
const codeVerifier = randomBase64Url(32);
const state = randomBase64Url(16);
const authUrl = await this.buildAuthorizeUrl(region, codeVerifier, state);
const target =
kind === "signup" ? buildSignupUrl(region, authUrl) : authUrl;
// Open before any network round-trip so the click's transient activation
// still permits the popup. The window name is unique per flow: a fixed
// name lets a concurrent sign-in in another tab reuse (and navigate away)
// this flow's popup, stranding it until the timeout — its own callback
// never fires and the shared channel only carries the other flow's state.
const popup = window.open(
target.toString(),
`posthog-code-oauth-${state}`,
POPUP_FEATURES,
);
if (!popup) {
return {
success: false,
error:
"The sign-in popup was blocked. Allow popups for this site and try again.",
};
}
this.log.info("Waiting for OAuth callback", { region, kind });
const code = await this.waitForCallback(state, popup);
const data = await this.postTokenEndpoint(region, {
grant_type: "authorization_code",
code,
redirect_uri: getWebRedirectUri(),
client_id: getOauthClientIdFromRegion(region),
code_verifier: codeVerifier,
});
return { success: true, data };
} catch (error) {
this.log.warn("Web OAuth flow failed", { error: messageOf(error) });
return {
success: false,
error: messageOf(error),
errorCode: classifyError(error),
};
}
}
private waitForCallback(
expectedState: string,
popup: Window,
): Promise<string> {
return new Promise<string>((resolve, reject) => {
const channel = new BroadcastChannel(OAUTH_CALLBACK_CHANNEL);
const closePoll = window.setInterval(() => {
if (popup.closed) {
fail(new Error("The sign-in window was closed before completing"));
}
}, 1_000);
const timeout = window.setTimeout(() => {
fail(new Error("Authorization timed out"));
}, FLOW_TIMEOUT_MS);
const cleanup = () => {
window.clearInterval(closePoll);
window.clearTimeout(timeout);
channel.close();
this.pendingFlow = null;
};
const fail = (error: Error) => {
cleanup();
if (!popup.closed) popup.close();
reject(error);
};
this.pendingFlow = { cancel: (reason) => fail(new Error(reason)) };
channel.onmessage = (event: MessageEvent<OAuthCallbackMessage>) => {
const { code, state, error } = event.data ?? {};
if (state !== expectedState) {
this.log.warn("Ignoring OAuth callback with mismatched state");
return;
}
if (error) {
fail(new Error(`Authorization failed: ${error}`));
return;
}
if (!code) {
fail(new Error("Authorization callback carried no code"));
return;
}
cleanup();
resolve(code);
};
});
}
private async buildAuthorizeUrl(
region: CloudRegion,
codeVerifier: string,
state: string,
): Promise<URL> {
const codeChallenge = await sha256Base64Url(codeVerifier);
const url = new URL(`${getCloudUrlFromRegion(region)}/oauth/authorize`);
url.searchParams.set("client_id", getOauthClientIdFromRegion(region));
url.searchParams.set("redirect_uri", getWebRedirectUri());
url.searchParams.set("response_type", "code");
url.searchParams.set("code_challenge", codeChallenge);
url.searchParams.set("code_challenge_method", "S256");
url.searchParams.set("scope", OAUTH_SCOPES.join(" "));
url.searchParams.set("required_access_level", "project");
url.searchParams.set("state", state);
return url;
}
private async postTokenEndpoint(
region: CloudRegion,
body: Record<string, string>,
): Promise<OAuthTokenResponse> {
const response = await fetch(
`${getCloudUrlFromRegion(region)}/oauth/token`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal: AbortSignal.timeout(TOKEN_FETCH_TIMEOUT_MS),
},
);
if (!response.ok) {
throw new HttpError(
response.status,
`Token request failed: ${response.status} ${response.statusText}`,
);
}
return oAuthTokenResponse.parse(await response.json());
}
}
/**
* Runs on the popup when the OAuth server redirects it to /oauth/callback:
* relays the result to the opener tab and closes itself. main.tsx routes here
* instead of rendering the app.
*/
export function completeOAuthCallbackPage(): void {
const params = new URL(window.location.href).searchParams;
const message: OAuthCallbackMessage = {
code: params.get("code"),
state: params.get("state"),
error: params.get("error"),
};
const channel = new BroadcastChannel(OAUTH_CALLBACK_CHANNEL);
channel.postMessage(message);
channel.close();
// Drop the one-time code from the URL/history before showing anything.
window.history.replaceState(null, "", OAUTH_CALLBACK_PATH);
const root = document.getElementById("root");
if (root) {
root.textContent = message.error
? `Sign-in failed: ${message.error}`
: "Signed in — you can close this window.";
}
window.close();
}
function buildSignupUrl(region: CloudRegion, authUrl: URL): URL {
const signupUrl = new URL(`${getCloudUrlFromRegion(region)}/signup`);
signupUrl.searchParams.set("next", `${authUrl.pathname}${authUrl.search}`);
return signupUrl;
}
function randomBase64Url(byteLength: number): string {
const bytes = crypto.getRandomValues(new Uint8Array(byteLength));
return base64UrlEncode(bytes);
}
async function sha256Base64Url(input: string): Promise<string> {
const digest = await crypto.subtle.digest(
"SHA-256",
new TextEncoder().encode(input),
);
return base64UrlEncode(new Uint8Array(digest));
}
function base64UrlEncode(bytes: Uint8Array): string {
let binary = "";
for (const byte of bytes) {
binary += String.fromCharCode(byte);
}
return btoa(binary)
.replaceAll("+", "-")
.replaceAll("/", "_")
.replace(/=+$/, "");
}
function messageOf(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
function classifyError(error: unknown): OAuthErrorCode {
if (error instanceof HttpError) {
if (error.status >= 500) return "server_error";
if (error.status === 401 || error.status === 403) return "auth_error";
return "unknown_error";
}
// fetch rejects with TypeError on network/CORS failure; AbortSignal.timeout
// rejects with a DOMException named TimeoutError.
if (error instanceof TypeError) return "network_error";
if (error instanceof DOMException && error.name === "TimeoutError") {
return "network_error";
}
return "unknown_error";
}