import http from "node:http";
import * as Clock from "effect/Clock";
import * as Digest from "effect/crypto/Digest";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import { Base64Url } from "effect/encoding";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as Url from "effect/http/Url";
import * as Match from "effect/Match";
import * as Redacted from "effect/Redacted";
import * as Result from "effect/Result";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import { AUTH_ERROR_URL, AUTH_SUCCESS_URL } from "./AuthProvider.ts";
/**
* The authorization server rejected a request with an OAuth error code
* (RFC 6749 §5.2, RFC 8628 §3.5). `error` is the server's code verbatim.
*/
export class OAuthError extends Data.TaggedError("OAuthError")<{
error: string;
errorDescription: string;
}> {
override get message(): string {
return `${this.error}: ${this.errorDescription}`;
}
}
/** A request to the authorization server could not be sent or answered. */
export class OAuthNetworkError extends Data.TaggedError("OAuthNetworkError")<{
endpoint: string;
cause: unknown;
}> {
override get message(): string {
return `Request to ${this.endpoint} failed: ${this.cause instanceof Error ? this.cause.message : String(this.cause)}`;
}
}
/**
* The authorization server answered 429/5xx without an OAuth error body
* (typically an edge error page). Transient.
*/
export class OAuthServerUnavailable extends Data.TaggedError("OAuthServerUnavailable")<{
endpoint: string;
status: number;
}> {
override get message(): string {
return `${this.endpoint} is temporarily unavailable (HTTP ${this.status}).`;
}
}
/** The authorization server's response could not be interpreted. */
export class OAuthInvalidResponse extends Data.TaggedError("OAuthInvalidResponse")<{
endpoint: string;
status: number;
reason: string;
}> {
override get message(): string {
return `Unexpected response from ${this.endpoint} (HTTP ${this.status}): ${this.reason}`;
}
}
/** Every way a request to the authorization server can fail. */
export type OAuthRequestError =
| OAuthError
| OAuthNetworkError
| OAuthServerUnavailable
| OAuthInvalidResponse;
/** The client spec lacks the endpoints/URIs a flow needs. */
export class UnsupportedOAuthFlowError extends Data.TaggedError("UnsupportedOAuthFlowError")<{
flow: "browser" | "device";
}> {
override get message(): string {
return `This OAuth client is not configured for the ${this.flow} flow.`;
}
}
/** A callback redirect or pasted code lacks a code or carries the wrong state. */
export class OAuthCallbackError extends Data.TaggedError("OAuthCallbackError")<{
reason: "missing_code" | "state_mismatch";
}> {
override get message(): string {
return this.reason === "missing_code"
? "The authorization code is missing."
: "The authorization state does not match.";
}
}
/** No browser callback arrived within 5 minutes. */
export class OAuthCallbackTimeout extends Data.TaggedError("OAuthCallbackTimeout") {
override get message(): string {
return "The authorization process timed out.";
}
}
/**
* The device authorization endpoint pointed the user at a URL outside the
* authorization server's host (RFC 8628 §5.4, remote phishing).
*/
export class UntrustedVerificationUriError extends Data.TaggedError(
"UntrustedVerificationUriError",
)<{
url: string;
expectedHost: string;
}> {
override get message(): string {
return `Refusing verification URL outside ${this.expectedHost}: ${this.url}`;
}
}
/** The user denied the device authorization. */
export class DeviceAuthorizationDenied extends Data.TaggedError("DeviceAuthorizationDenied") {
override get message(): string {
return "The device authorization was denied.";
}
}
/** The device code expired (or the 5 minute cap passed) before approval. */
export class DeviceAuthorizationExpired extends Data.TaggedError("DeviceAuthorizationExpired") {
override get message(): string {
return "The device authorization expired before it was approved.";
}
}
/**
* The local loopback callback server could not start (typically the port is
* already taken). Distinct from {@link CallbackServerError} so callers can
* fall back to manual code entry instead of failing the whole flow.
*/
export class CallbackServerStartError extends Data.TaggedError("CallbackServerStartError")<{
message: string;
}> {}
/** The loopback callback server failed after it started listening. */
export class CallbackServerError extends Data.TaggedError("CallbackServerError")<{
message: string;
}> {}
/**
* On-disk shape of OAuth credentials persisted under
* `~/.alchemy/credentials/{profile}/<provider>-oauth.json`.
*
* `clientId` is optional because files written before the client id was
* recorded must still parse — {@link OAuthClient.usesCurrentClient} treats a
* missing id as "issued to a previous client", which triggers a clean
* re-login.
*/
export const OAuthCredentials = Schema.Struct({
type: Schema.Literal("oauth"),
clientId: Schema.optional(Schema.String),
access: Schema.RedactedFromValue(Schema.String),
refresh: Schema.RedactedFromValue(Schema.String),
expires: Schema.Number,
scopes: Schema.String.pipe(Schema.Array, Schema.mutable),
});
export type OAuthCredentials = typeof OAuthCredentials.Type;
/**
* A pending OAuth 2.0 Device Authorization Grant (RFC 8628): the user
* approves `userCode` at `verificationUri` while the CLI polls for tokens.
*/
export interface DeviceAuthorization {
deviceCode: string;
userCode: string;
verificationUri: string;
/** Verification URL with the user code pre-filled. */
verificationUriComplete: string;
/** Seconds until the device code expires. */
expiresIn: number;
/** Seconds between token polls. */
interval: number;
}
export interface Authorization {
url: string;
state: string;
/** PKCE verifier; present only for `auth: { kind: "pkce" }` clients. */
verifier?: string;
}
/**
* The provider-specific facts an OAuth flow needs. Everything else —
* state/PKCE generation, the loopback callback server, hosted-relay code
* extraction, device-code polling, token exchange, refresh, revoke — is
* shared.
*
* The browser (authorization-code) flow needs `endpoints.authorize`,
* `redirectUri` and `localCallbackUri`; the device flow needs
* `endpoints.deviceAuthorization`. A client that only refreshes and revokes
* existing grants needs neither.
*/
export interface OAuthClientSpec {
readonly clientId: string;
readonly endpoints: {
readonly authorize?: string;
/** RFC 8628 device authorization endpoint. */
readonly deviceAuthorization?: string;
readonly token: string;
/** Providers without a revocation endpoint omit it; `revoke` then no-ops. */
readonly revoke?: string;
};
/** Hosted relay redirect URI registered with the OAuth application. */
readonly redirectUri?: string;
/** Loopback URI the local callback server listens on. */
readonly localCallbackUri?: string;
/**
* Client authentication. `pkce` for public clients; `clientSecret` for
* providers whose token endpoint requires client authentication for every
* grant (the secret ships in the CLI — same exposure posture as a public
* client id, rotated by cutting a release).
*/
readonly auth:
| { readonly kind: "pkce" }
| { readonly kind: "clientSecret"; readonly clientSecret: Redacted.Redacted<string> };
/**
* How token-request parameters travel: URL-encoded POST body (the OAuth 2
* standard, default) or the query string (PlanetScale's documented form).
*/
readonly tokenTransport?: "body" | "query";
}
export interface OAuthClient {
readonly clientId: string;
/** Whether persisted credentials were issued to this client. */
readonly usesCurrentClient: (credentials: { readonly clientId?: unknown }) => boolean;
/**
* Generate an authorization URL. Pass `scopes` only for providers that
* take them per-authorization; omit for providers whose scopes are
* configured on the application.
*/
readonly authorize: (
scopes?: ReadonlyArray<string>,
) => Effect.Effect<
Authorization,
UnsupportedOAuthFlowError,
SecureRandom.SecureRandom | Digest.Digest
>;
/**
* Exchange an authorization code directly. `authorization` supplies the
* PKCE verifier; omit for non-PKCE clients (tests, relay-less flows).
*/
readonly exchange: (
code: string,
authorization?: Authorization,
) => Effect.Effect<OAuthCredentials, OAuthRequestError | UnsupportedOAuthFlowError, never>;
/**
* Exchange a code copied from the hosted relay page, or extract the code
* from either the hosted or loopback callback URL.
*/
readonly exchangeCallbackInput: (
input: string,
authorization: Authorization,
) => Effect.Effect<
OAuthCredentials,
OAuthRequestError | OAuthCallbackError | UnsupportedOAuthFlowError,
never
>;
/**
* Start a local HTTP server to listen for the OAuth callback, exchange
* the authorization code, and return the credentials. Times out after 5
* minutes.
*/
readonly callback: (
authorization: Authorization,
) => Effect.Effect<
OAuthCredentials,
| OAuthRequestError
| OAuthCallbackError
| OAuthCallbackTimeout
| CallbackServerStartError
| CallbackServerError
| UnsupportedOAuthFlowError,
never
>;
/** Start an RFC 8628 device authorization for `scopes`. */
readonly deviceAuthorize: (
scopes?: ReadonlyArray<string>,
) => Effect.Effect<
DeviceAuthorization,
OAuthRequestError | UnsupportedOAuthFlowError | UntrustedVerificationUriError,
never
>;
/**
* Poll the token endpoint until the user approves (or denies) the device
* authorization. Times out when the device code expires, capped at 5
* minutes.
*/
readonly deviceToken: (
authorization: DeviceAuthorization,
) => Effect.Effect<
OAuthCredentials,
OAuthRequestError | DeviceAuthorizationDenied | DeviceAuthorizationExpired,
never
>;
/** Refresh expired OAuth credentials with the stored refresh token. */
readonly refresh: (
credentials: OAuthCredentials,
) => Effect.Effect<OAuthCredentials, OAuthRequestError, never>;
/** Revoke the refresh token; no-op when the spec has no revoke endpoint. */
readonly revoke: (credentials: OAuthCredentials) => Effect.Effect<void, OAuthNetworkError>;
}
const randomText = Effect.fn(function* (length: number) {
const random = yield* SecureRandom.SecureRandom;
return Base64Url.encode(yield* random.randomBytes(length));
});
const generatePKCE = Effect.fn(function* (length = 96) {
const digest = yield* Digest.Digest;
const verifier = yield* randomText(length);
const challenge = yield* digest.digest(Digest.sha256, new TextEncoder().encode(verifier));
return { verifier, challenge: Base64Url.encode(challenge) };
});
const TokenResponse = Schema.Struct({
access_token: Schema.String,
refresh_token: Schema.optional(Schema.String),
expires_in: Schema.Number,
scope: Schema.optional(Schema.String),
});
const DeviceAuthorizationResponse = Schema.Struct({
device_code: Schema.String,
user_code: Schema.String,
verification_uri: Schema.String,
verification_uri_complete: Schema.optional(Schema.String),
expires_in: Schema.Number,
interval: Schema.optional(Schema.Number),
});
const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
const TokenErrorResponse = Schema.Struct({
error: Schema.String,
error_description: Schema.optional(Schema.String),
});
export const makeOAuthClient = (spec: OAuthClientSpec): OAuthClient => {
const provideHttp = <A, E>(effect: Effect.Effect<A, E, HttpClient.HttpClient>) =>
effect.pipe(Effect.provide(FetchHttpClient.layer));
const clientAuthParams = (): Record<string, string> =>
spec.auth.kind === "clientSecret"
? { client_secret: Redacted.value(spec.auth.clientSecret) }
: {};
/**
* POST form params to an authorization-server endpoint and decode the 2xx
* body with `success`. Non-2xx responses surface the server's OAuth error
* code as {@link OAuthError}.
*/
const postForm = Effect.fn(function* <A>(
endpoint: string,
params: Record<string, string>,
success: Schema.ConstraintDecoder<A, never>,
transport: "body" | "query" = "body",
) {
const client = yield* HttpClient.HttpClient;
const request = HttpClientRequest.post(endpoint).pipe(
HttpClientRequest.setHeader("Accept", "application/json"),
transport === "query"
? HttpClientRequest.setUrlParams(params)
: HttpClientRequest.bodyUrlParams(params),
);
const response = yield* client
.execute(request)
.pipe(Effect.mapError((cause) => new OAuthNetworkError({ endpoint, cause })));
const { status } = response;
if (status < 200 || status >= 300) {
const json = yield* HttpClientResponse.schemaBodyJson(TokenErrorResponse)(response).pipe(
Effect.mapError(() =>
status === 429 || status >= 500
? new OAuthServerUnavailable({ endpoint, status })
: new OAuthInvalidResponse({ endpoint, status, reason: "no OAuth error body" }),
),
);
return yield* new OAuthError({
error: json.error,
errorDescription: json.error_description ?? `HTTP ${status}`,
});
}
return yield* HttpClientResponse.schemaBodyJson(success)(response).pipe(
Effect.mapError(
() => new OAuthInvalidResponse({ endpoint, status, reason: "unexpected response body" }),
),
);
});
const tokenRequest = Effect.fn(function* (
params: Record<string, string>,
previous?: OAuthCredentials,
) {
const endpoint = spec.endpoints.token;
const json = yield* postForm(endpoint, params, TokenResponse, spec.tokenTransport);
const refresh =
json.refresh_token === undefined ? previous?.refresh : Redacted.make(json.refresh_token);
if (!refresh) {
return yield* new OAuthInvalidResponse({
endpoint,
status: 200,
reason: "no refresh token was returned for this authorization",
});
}
const now = yield* Clock.currentTimeMillis;
return {
type: "oauth" as const,
clientId: spec.clientId,
access: Redacted.make(json.access_token),
refresh,
expires: now + json.expires_in * 1000,
scopes: json.scope?.split(" ") ?? previous?.scopes ?? [],
} satisfies OAuthCredentials;
});
const browserSpec = Effect.suspend(() => {
const { redirectUri, localCallbackUri } = spec;
const authorizeEndpoint = spec.endpoints.authorize;
return redirectUri === undefined ||
localCallbackUri === undefined ||
authorizeEndpoint === undefined
? Effect.fail(new UnsupportedOAuthFlowError({ flow: "browser" }))
: Effect.succeed({ redirectUri, localCallbackUri, authorizeEndpoint });
});
const authorize = Effect.fn(function* (scopes?: ReadonlyArray<string>) {
const { authorizeEndpoint, redirectUri } = yield* browserSpec;
const state = yield* randomText(32);
const url = new URL(authorizeEndpoint);
url.searchParams.set("client_id", spec.clientId);
url.searchParams.set("redirect_uri", redirectUri);
url.searchParams.set("response_type", "code");
if (scopes !== undefined) {
url.searchParams.set("scope", scopes.join(" "));
}
url.searchParams.set("state", state);
if (spec.auth.kind === "pkce") {
const pkce = yield* generatePKCE();
url.searchParams.set("code_challenge", pkce.challenge);
url.searchParams.set("code_challenge_method", "S256");
return { url: url.toString(), state, verifier: pkce.verifier };
}
return { url: url.toString(), state };
});
const exchange = Effect.fn(function* (code: string, authorization?: Authorization) {
const { redirectUri } = yield* browserSpec;
return yield* tokenRequest({
grant_type: "authorization_code",
code,
client_id: spec.clientId,
redirect_uri: redirectUri,
...clientAuthParams(),
...(authorization?.verifier === undefined ? {} : { code_verifier: authorization.verifier }),
});
});
const deviceAuthorize = Effect.fn(function* (scopes?: ReadonlyArray<string>) {
const endpoint = spec.endpoints.deviceAuthorization;
if (endpoint === undefined) return yield* new UnsupportedOAuthFlowError({ flow: "device" });
const json = yield* postForm(
endpoint,
{
client_id: spec.clientId,
...(scopes === undefined ? {} : { scope: scopes.join(" ") }),
...clientAuthParams(),
},
DeviceAuthorizationResponse,
);
// The server picks where the user is sent to type their code; only
// trust https URLs on the authorization server's own host (RFC 8628
// §5.4, remote phishing).
const expectedHost = new URL(endpoint).host;
const trustedUrl = (value: string) => {
const untrusted = () => new UntrustedVerificationUriError({ url: value, expectedHost });
return Url.fromString(value).pipe(
Result.mapError(untrusted),
Result.filterOrFail(
(url) =>
url.protocol === "https:" &&
url.username === "" &&
url.password === "" &&
url.host === expectedHost,
untrusted,
),
Effect.fromResult,
);
};
const verificationUri = yield* trustedUrl(json.verification_uri);
const complete =
json.verification_uri_complete === undefined
? Url.mutate(verificationUri, (url) => url.searchParams.set("user_code", json.user_code))
: yield* trustedUrl(json.verification_uri_complete);
return {
deviceCode: json.device_code,
userCode: json.user_code,
verificationUri: json.verification_uri,
verificationUriComplete: complete.toString(),
expiresIn: json.expires_in,
interval: json.interval ?? 5,
} satisfies DeviceAuthorization;
});
const deviceToken = Effect.fn(function* (authorization: DeviceAuthorization) {
let interval = Math.max(authorization.interval, 1);
// The delay is read on every recurrence, so slow_down's bump applies to
// all later polls.
const schedule = Schedule.forever.pipe(
Schedule.modifyDelay(() => Effect.sync(() => Duration.seconds(interval))),
);
return yield* tokenRequest({
grant_type: DEVICE_CODE_GRANT,
device_code: authorization.deviceCode,
client_id: spec.clientId,
...clientAuthParams(),
}).pipe(
Effect.tapError((e) =>
Effect.sync(() => {
// RFC 8628 §3.5: slow_down adds 5 seconds to every later poll.
if (e._tag === "OAuthError" && e.error === "slow_down") interval += 5;
}),
),
Effect.retry({
schedule,
// Transient failures, or RFC 8628 §3.5 codes meaning the user has
// not decided yet.
while: (e) =>
["OAuthNetworkError", "OAuthServerUnavailable"].includes(e._tag) ||
(e._tag === "OAuthError" &&
["authorization_pending", "slow_down", "temporarily_unavailable"].includes(e.error)),
}),
Effect.catchTag("OAuthError", (e) =>
Effect.fail(
Match.value(e.error).pipe(
Match.when("access_denied", () => new DeviceAuthorizationDenied()),
Match.when("expired_token", () => new DeviceAuthorizationExpired()),
Match.orElse(() => e),
),
),
),
Effect.timeoutOrElse({
duration: Duration.seconds(Math.min(authorization.expiresIn, 300)),
orElse: () => Effect.fail(new DeviceAuthorizationExpired()),
}),
);
});
const refresh = Effect.fn(function (credentials: OAuthCredentials) {
return tokenRequest(
{
grant_type: "refresh_token",
refresh_token: Redacted.value(credentials.refresh),
client_id: spec.clientId,
...clientAuthParams(),
},
credentials,
);
});
const revoke = Effect.fn(function* (credentials: OAuthCredentials) {
const endpoint = spec.endpoints.revoke;
if (endpoint === undefined) return;
const client = yield* HttpClient.HttpClient;
const request = HttpClientRequest.post(endpoint).pipe(
HttpClientRequest.setHeader("Accept", "application/json"),
HttpClientRequest.bodyUrlParams({
token: Redacted.value(credentials.refresh),
token_type_hint: "refresh_token",
client_id: spec.clientId,
...clientAuthParams(),
}),
);
yield* client.execute(request).pipe(
Effect.mapError((cause) => new OAuthNetworkError({ endpoint, cause })),
Effect.asVoid,
);
});
const exchangeCallbackInput = Effect.fn(function* (input: string, authorization: Authorization) {
const value = input.trim();
// A full callback URL carries code + state; a code copied from the hosted
// relay page is `code#state`.
const { code, state } = Url.fromString(value).pipe(
Result.map((url) => ({
code: url.searchParams.get("code") ?? "",
state: url.searchParams.get("state"),
})),
Result.getOrElse(() => {
const separator = value.lastIndexOf("#");
return separator >= 0
? { code: value.slice(0, separator), state: value.slice(separator + 1) }
: { code: value, state: null };
}),
);
if (!code) {
return yield* new OAuthCallbackError({ reason: "missing_code" });
}
if (state !== null && state !== authorization.state) {
return yield* new OAuthCallbackError({ reason: "state_mismatch" });
}
return yield* exchange(code, authorization);
});
type CallbackFailure =
| OAuthRequestError
| OAuthCallbackError
| CallbackServerStartError
| CallbackServerError
| UnsupportedOAuthFlowError;
const callback = Effect.fn(function* (authorization: Authorization) {
const { localCallbackUri, redirectUri } = yield* browserSpec;
const { pathname, port, protocol } = new URL(localCallbackUri);
const listenPort = port === "" ? (protocol === "https:" ? 443 : 80) : Number(port);
const listen = Effect.callback<OAuthCredentials, CallbackFailure, HttpClient.HttpClient>(
(resume) => {
// The handler can run more than once (browser retries, extra tabs);
// resume exactly once and ignore everything after.
let settled = false;
const resolveOnce = (
effect: Effect.Effect<OAuthCredentials, CallbackFailure, HttpClient.HttpClient>,
) => {
if (settled) return;
settled = true;
resume(effect);
};
const server = http.createServer((req, res) => {
const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
if (url.pathname === "/auth/ping") {
res.writeHead(req.method === "OPTIONS" ? 204 : 200, {
"Access-Control-Allow-Origin": new URL(redirectUri).origin,
"Access-Control-Allow-Methods": "GET, OPTIONS",
"Access-Control-Allow-Private-Network": "true",
"Cache-Control": "no-store",
});
res.end();
return;
}
if (url.pathname !== pathname) {
res.statusCode = 404;
res.end("Not Found");
return;
}
const error = url.searchParams.get("error");
const errorDescription = url.searchParams.get("error_description");
if (error) {
res.writeHead(302, { Location: AUTH_ERROR_URL });
res.end();
new OAuthError({
error,
errorDescription: errorDescription ?? "An unknown error occurred.",
}).pipe(Effect.fail, resolveOnce);
return;
}
const code = url.searchParams.get("code");
const state = url.searchParams.get("state");
if (!code || !state) {
res.writeHead(302, { Location: AUTH_ERROR_URL });
res.end();
new OAuthCallbackError({ reason: "missing_code" }).pipe(Effect.fail, resolveOnce);
return;
}
if (state !== authorization.state) {
res.writeHead(302, { Location: AUTH_ERROR_URL });
res.end();
new OAuthCallbackError({ reason: "state_mismatch" }).pipe(Effect.fail, resolveOnce);
return;
}
resolveOnce(
exchange(code, authorization).pipe(
Effect.tap(() =>
Effect.sync(() => {
res.writeHead(302, { Location: AUTH_SUCCESS_URL });
res.end();
}),
),
Effect.tapError(() =>
Effect.sync(() => {
res.writeHead(302, { Location: AUTH_ERROR_URL });
res.end();
}),
),
),
);
});
server.on("error", (err) => {
(server.listening
? new CallbackServerError({ message: `Callback server failed: ${err.message}` })
: new CallbackServerStartError({
message: `Failed to start callback server: ${err.message}`,
})
).pipe(Effect.fail, resolveOnce);
});
server.listen(listenPort, "127.0.0.1");
return Effect.sync(() => {
server.close();
// `close` only stops new connections — a keep-alive browser
// connection would otherwise hold the process open until its
// socket timeout after login completes.
server.closeAllConnections();
});
},
);
return yield* listen.pipe(
Effect.timeoutOrElse({
duration: "5 minutes",
orElse: () => Effect.fail(new OAuthCallbackTimeout()),
}),
);
});
return {
clientId: spec.clientId,
usesCurrentClient: (credentials) => credentials.clientId === spec.clientId,
authorize,
exchange: (...args) => provideHttp(exchange(...args)),
exchangeCallbackInput: (...args) => provideHttp(exchangeCallbackInput(...args)),
callback: (authorization) => provideHttp(callback(authorization)),
deviceAuthorize: (scopes) => provideHttp(deviceAuthorize(scopes)),
deviceToken: (authorization) => provideHttp(deviceToken(authorization)),
refresh: (credentials) => provideHttp(refresh(credentials)),
revoke: (credentials) => provideHttp(revoke(credentials)),
};
};