@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/OAuthFlow.ts

@@ -0,0 +1,874 @@
+import type { Config } from "effect";
+import {
+  Array,
+  Clock,
+  ConfigProvider,
+  Context,
+  Effect,
+  HashSet,
+  Layer,
+  Predicate,
+  Random,
+  Redacted,
+  Record,
+  Schema,
+  String,
+  pipe,
+} from "effect";
+
+/**
+ * OAuth protocol runner used by ConnectionStore.
+ *
+ * OAuthFlow owns provider-facing protocol mechanics: resolving OAuth client
+ * configuration, optional discovery, authorization URL construction, token
+ * exchange, token refresh, and token response normalization. It does not persist
+ * OAuth sessions or create Connections; ConnectionStore owns those product
+ * lifecycle records and calls this service for the protocol steps.
+ */
+import { Base64, Base64Url } from "effect/encoding";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+
+import * as AuthMethod from "./AuthMethod.ts";
+import * as OAuth2TokenRefresher from "./OAuth2TokenRefresher.ts";
+
+export class OAuthConnectionValidationFailed extends Schema.TaggedError<OAuthConnectionValidationFailed>()(
+  "OAuthConnectionValidationFailed",
+  { cause: Schema.optionalKey(Schema.Redacted(Schema.Defect())), message: Schema.String },
+) {}
+export class OAuthProviderRejected extends Schema.TaggedError<OAuthProviderRejected>()(
+  "OAuthProviderRejected",
+  { error: Schema.String, errorDescription: Schema.optional(Schema.String) },
+) {}
+export class OAuthGrantRejected extends Schema.TaggedError<OAuthGrantRejected>()(
+  "OAuthGrantRejected",
+  { errorSubtype: Schema.optionalKey(Schema.String), message: Schema.String },
+) {}
+
+const DefaultFlowTtlMs = 10 * 60 * 1000;
+
+const OAuthEndpoints = Schema.Struct({
+  authorizationUrl: Schema.String,
+  expectedIssuer: Schema.optional(Schema.String),
+  tokenUrl: Schema.String,
+});
+type OAuthEndpoints = typeof OAuthEndpoints.Type;
+
+const ClientAuthentication = Schema.Union([
+  Schema.Literal("basic"),
+  Schema.Literal("post"),
+  Schema.Literal("none"),
+]);
+
+const ReservedTokenHeaders = HashSet.fromIterable([
+  "accept",
+  "accept-charset",
+  "accept-encoding",
+  "access-control-request-headers",
+  "access-control-request-method",
+  "authorization",
+  "connection",
+  "content-encoding",
+  "content-length",
+  "content-type",
+  "cookie",
+  "cookie2",
+  "date",
+  "dnt",
+  "expect",
+  "host",
+  "keep-alive",
+  "origin",
+  "permissions-policy",
+  "referer",
+  "set-cookie",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "user-agent",
+  "via",
+]);
+
+type TokenHeaders = typeof TokenHeaders.Type;
+const TokenHeaders = Schema.Record(
+  Schema.String,
+  Schema.String.check(Schema.isPattern(/^[\t\x20-\x7e\x80-\xff]*$/u)),
+).check(
+  Schema.makeFilter(
+    headers => {
+      const names = Array.map(Record.keys(headers), String.toLowerCase);
+      return (
+        HashSet.size(HashSet.fromIterable(names)) === names.length &&
+        Array.every(
+          names,
+          name =>
+            /^[!#$%&'*+.^_`|~0-9a-z-]+$/u.test(name) &&
+            !HashSet.has(ReservedTokenHeaders, name) &&
+            !String.startsWith("proxy-")(name) &&
+            !String.startsWith("sec-")(name),
+        )
+      );
+    },
+    { message: "Invalid provider token headers" },
+  ),
+);
+
+const ResolvedOAuth2Config = Schema.Struct({
+  authorizationParams: Schema.Record(Schema.String, Schema.String),
+  authorizationUrl: Schema.String,
+  clientAuthentication: ClientAuthentication,
+  clientId: Schema.String,
+  clientSecret: Schema.optional(Schema.String),
+  expectedIssuer: Schema.optional(Schema.String),
+  pkce: Schema.Boolean,
+  scopes: Schema.Array(Schema.String),
+  tokenHeaders: TokenHeaders,
+  tokenParams: Schema.Record(Schema.String, Schema.String),
+  tokenRequestEncoding: Schema.Literals(["form", "json"]),
+  tokenUrl: Schema.String,
+});
+type ResolvedOAuth2Config = typeof ResolvedOAuth2Config.Type;
+
+const ProviderDiscoveryDocument = Schema.Struct({
+  authorization_endpoint: Schema.String,
+  issuer: Schema.optional(Schema.String),
+  token_endpoint: Schema.String,
+});
+
+const decodeDiscoveryDocument = Schema.decodeUnknownSync(ProviderDiscoveryDocument);
+const encodeJsonTokenParams = Schema.encodeSync(
+  Schema.fromJsonString(Schema.Record(Schema.String, Schema.String)),
+);
+const decodeProviderTokenError = Schema.decodeSync(
+  Schema.fromJsonString(
+    Schema.Struct({
+      error: Schema.Literals([
+        "invalid_request",
+        "invalid_client",
+        "invalid_grant",
+        "unauthorized_client",
+        "unsupported_grant_type",
+        "invalid_scope",
+        "server_error",
+        "temporarily_unavailable",
+      ]),
+    }),
+  ),
+);
+// Only Google's documented reauthentication subtypes pass, so an echoed secret never reaches an error.
+const decodeProviderTokenErrorSubtype = Schema.decodeSync(
+  Schema.fromJsonString(
+    Schema.Struct({ error_subtype: Schema.Literals(["invalid_rapt", "rapt_required"]) }),
+  ),
+);
+
+const randomBase64Url = (bytes: number): string => {
+  const data = new Uint8Array(bytes);
+  crypto.getRandomValues(data);
+  return Base64Url.encode(data);
+};
+
+const sha256Base64Url = (value: string): Effect.Effect<string> =>
+  Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(value))).pipe(
+    Effect.map(digest => Base64Url.encode(new Uint8Array(digest))),
+  );
+
+const requiredString = (
+  value: unknown,
+  message: string,
+): Effect.Effect<string, OAuthConnectionValidationFailed> =>
+  typeof value === "string" && value.trim() !== ""
+    ? Effect.succeed(value)
+    : Effect.fail(new OAuthConnectionValidationFailed({ message }));
+
+const fetchDiscovery = Effect.fn("OAuthFlow.fetchDiscovery")(function* (
+  discoveryUrl: string,
+  client: HttpClient.HttpClient,
+): Effect.fn.Return<OAuthEndpoints, OAuthConnectionValidationFailed> {
+  const rawDocument = yield* pipe(
+    HttpClient.filterStatusOk(client).get(discoveryUrl, {
+      headers: { Accept: "application/json" },
+    }),
+    Effect.flatMap(response => response.json),
+    Effect.mapError(cause =>
+      OAuthConnectionValidationFailed.make({
+        cause: Redacted.make(cause),
+        message: "failed to load oauth discovery document",
+      }),
+    ),
+  );
+
+  const document = yield* Effect.try({
+    catch: () =>
+      new OAuthConnectionValidationFailed({ message: "invalid oauth discovery document" }),
+    try: () => decodeDiscoveryDocument(rawDocument),
+  });
+
+  const authorizationUrl = yield* requiredString(
+    document.authorization_endpoint,
+    "oauth discovery document missing authorization_endpoint",
+  );
+  const tokenUrl = yield* requiredString(
+    document.token_endpoint,
+    "oauth discovery document missing token_endpoint",
+  );
+  const expectedIssuer =
+    typeof document.issuer === "string" && document.issuer.trim() !== ""
+      ? document.issuer
+      : undefined;
+
+  return {
+    authorizationUrl,
+    tokenUrl,
+    ...(expectedIssuer === undefined ? {} : { expectedIssuer }),
+  };
+});
+
+const resolveEndpoint = (
+  value: AuthMethod.OAuth2Endpoint<unknown> | undefined,
+  setup: unknown,
+): string | undefined =>
+  value === undefined ? undefined : typeof value === "function" ? value({ setup }) : value;
+
+const resolveParams = (
+  value: AuthMethod.OAuth2Params<unknown> | undefined,
+  setup: unknown,
+): Readonly<Record<string, string>> =>
+  typeof value === "function" ? value({ setup }) : (value ?? {});
+
+function invalidTokenHeaders() {
+  return OAuthConnectionValidationFailed.make({ message: "invalid oauth token headers" });
+}
+
+const resolveTokenHeaders = Effect.fnUntraced(function* (input: {
+  value: AuthMethod.OAuth2Headers<unknown> | undefined;
+  setup: unknown;
+}): Effect.fn.Return<TokenHeaders, OAuthConnectionValidationFailed> {
+  const raw = yield* Effect.try({
+    catch: invalidTokenHeaders,
+    try: () => {
+      if (Predicate.isFunction(input.value)) {
+        return input.value({ setup: input.setup });
+      }
+      if (input.value === undefined) {
+        return {};
+      }
+      return input.value;
+    },
+  });
+  return yield* pipe(Schema.decodeEffect(TokenHeaders)(raw), Effect.mapError(invalidTokenHeaders));
+});
+
+const resolveClientValue = Effect.fn("OAuthFlow.resolveClientValue")(function* (input: {
+  readonly value: string | Config.Config<string> | undefined;
+  readonly field: string;
+  readonly configProvider: ConfigProvider.ConfigProvider;
+}): Effect.fn.Return<string | undefined, OAuthConnectionValidationFailed> {
+  if (input.value === undefined) {
+    return undefined;
+  }
+  if (typeof input.value === "string") {
+    return yield* requiredString(input.value, `${input.field} is empty`);
+  }
+
+  return yield* input.value
+    .parse(input.configProvider)
+    .pipe(
+      Effect.mapError(
+        cause =>
+          new OAuthConnectionValidationFailed({
+            message: `failed to resolve ${input.field}: ${cause.message}`,
+          }),
+      ),
+    );
+});
+
+const resolveOAuthConfig = Effect.fn("OAuthFlow.resolveOAuthConfig")(function* (input: {
+  readonly method: AuthMethod.Any;
+  readonly setup: unknown;
+  readonly configProvider: ConfigProvider.ConfigProvider;
+  readonly client: HttpClient.HttpClient;
+}): Effect.fn.Return<ResolvedOAuth2Config, OAuthConnectionValidationFailed> {
+  const oauth = input.method.oauth2;
+  if (oauth === undefined) {
+    return yield* new OAuthConnectionValidationFailed({ message: "auth method is not oauth2" });
+  }
+
+  const tokenHeaders = yield* resolveTokenHeaders({
+    setup: input.setup,
+    value: oauth.tokenHeaders,
+  });
+
+  const client =
+    typeof oauth.client === "function" ? oauth.client({ setup: input.setup }) : oauth.client;
+  const clientId = yield* resolveClientValue({
+    configProvider: input.configProvider,
+    field: "clientId",
+    value: client.clientId,
+  });
+  const clientSecret = yield* resolveClientValue({
+    configProvider: input.configProvider,
+    field: "clientSecret",
+    value: client.clientSecret,
+  });
+  if (clientId === undefined) {
+    return yield* new OAuthConnectionValidationFailed({ message: "missing oauth client id" });
+  }
+
+  const authorizationUrl = resolveEndpoint(oauth.authorizationUrl, input.setup);
+  const tokenUrl = resolveEndpoint(oauth.tokenUrl, input.setup);
+  const discoveryUrl = resolveEndpoint(oauth.discoveryUrl, input.setup);
+
+  const endpoints =
+    authorizationUrl !== undefined && tokenUrl !== undefined
+      ? { authorizationUrl, tokenUrl }
+      : discoveryUrl === undefined
+        ? yield* new OAuthConnectionValidationFailed({
+            message: "oauth method requires explicit endpoints or discoveryUrl",
+          })
+        : yield* fetchDiscovery(discoveryUrl, input.client);
+
+  return {
+    ...endpoints,
+    authorizationParams: resolveParams(oauth.authorizationParams, input.setup),
+    clientAuthentication: client.authentication ?? "basic",
+    clientId,
+    clientSecret,
+    pkce: oauth.pkce ?? true,
+    scopes: oauth.scopes,
+    tokenHeaders,
+    tokenParams: resolveParams(oauth.tokenParams, input.setup),
+    tokenRequestEncoding: oauth.tokenRequestEncoding ?? "form",
+  };
+});
+
+const buildAuthorizationUrl = (input: {
+  readonly config: ResolvedOAuth2Config;
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly pkceChallenge: string | undefined;
+}): string => {
+  const url = new URL(input.config.authorizationUrl);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", input.config.clientId);
+  url.searchParams.set("redirect_uri", input.redirectUri);
+  url.searchParams.set("state", input.state);
+  if (input.config.scopes.length > 0) {
+    url.searchParams.set("scope", input.config.scopes.join(" "));
+  }
+  if (input.pkceChallenge !== undefined) {
+    url.searchParams.set("code_challenge", input.pkceChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+  }
+  for (const [key, value] of Object.entries(input.config.authorizationParams)) {
+    url.searchParams.set(key, value);
+  }
+  return url.toString();
+};
+
+const httpStatusClass = (status: number): string => {
+  if (status >= 500) {
+    return "5xx";
+  }
+  if (status >= 400) {
+    return "4xx";
+  }
+  return "unexpected";
+};
+
+const oauthProtocolErrorCode = (body: string): string | undefined => {
+  try {
+    return decodeProviderTokenError(body).error;
+  } catch {
+    return undefined;
+  }
+};
+
+const oauthProtocolErrorSubtype = (body: string): string | undefined => {
+  try {
+    return decodeProviderTokenErrorSubtype(body).error_subtype;
+  } catch {
+    return undefined;
+  }
+};
+
+const tokenRequestHeaders = (
+  config: ResolvedOAuth2Config,
+): Effect.Effect<Record<string, string>, OAuthConnectionValidationFailed> => {
+  const headers: Record<string, string> = {
+    ...config.tokenHeaders,
+    Accept: "application/json",
+    "Content-Type":
+      config.tokenRequestEncoding === "json"
+        ? "application/json"
+        : "application/x-www-form-urlencoded",
+  };
+  if (config.clientAuthentication === "basic") {
+    if (config.clientSecret === undefined) {
+      return Effect.fail(
+        new OAuthConnectionValidationFailed({
+          message: "missing client secret for basic token auth",
+        }),
+      );
+    }
+    headers["Authorization"] =
+      `Basic ${Base64.encode(`${config.clientId}:${config.clientSecret}`)}`;
+  }
+  return Effect.succeed(headers);
+};
+
+const postTokenRequest = Effect.fn("OAuthFlow.postTokenRequest")(function* (input: {
+  readonly config: ResolvedOAuth2Config;
+  readonly params: URLSearchParams;
+  readonly failurePrefix: string;
+  readonly client: HttpClient.HttpClient;
+}): Effect.fn.Return<
+  Record<string, unknown>,
+  OAuthConnectionValidationFailed | OAuthGrantRejected
+> {
+  if (input.config.clientAuthentication === "post") {
+    input.params.set("client_id", input.config.clientId);
+    if (input.config.clientSecret !== undefined) {
+      input.params.set("client_secret", input.config.clientSecret);
+    }
+  } else if (input.config.clientAuthentication === "none") {
+    input.params.set("client_id", input.config.clientId);
+  }
+
+  for (const [key, value] of Object.entries(input.config.tokenParams)) {
+    input.params.set(key, value);
+  }
+
+  const headers = yield* tokenRequestHeaders(input.config);
+  const request = HttpClientRequest.post(input.config.tokenUrl, { headers }).pipe(
+    HttpClientRequest.bodyText(
+      input.config.tokenRequestEncoding === "json"
+        ? encodeJsonTokenParams(Record.fromEntries(input.params))
+        : input.params.toString(),
+      headers["Content-Type"],
+    ),
+  );
+  const response = yield* pipe(
+    input.client.execute(request),
+    Effect.provideService(
+      FetchHttpClient.RequestInit,
+      Record.isEmptyRecord(input.config.tokenHeaders) ? {} : { redirect: "error" },
+    ),
+    Effect.mapError(cause =>
+      OAuthConnectionValidationFailed.make({
+        cause: Redacted.make(cause),
+        message: `${input.failurePrefix} (network)`,
+      }),
+    ),
+  );
+  if (response.status < 200 || response.status >= 300) {
+    const body = yield* pipe(
+      response.text,
+      Effect.mapError(cause =>
+        OAuthConnectionValidationFailed.make({
+          cause: Redacted.make(cause),
+          message: `${input.failurePrefix} (unreadable response)`,
+        }),
+      ),
+    );
+    const statusClass = httpStatusClass(response.status);
+    const protocolError = oauthProtocolErrorCode(body);
+    const errorSubtype = oauthProtocolErrorSubtype(body);
+    const reason = Array.join(
+      Array.filter([protocolError, errorSubtype], Predicate.isNotUndefined),
+      ", ",
+    );
+    const message = `${input.failurePrefix} (${Array.join(Array.filter([statusClass, reason], String.isNonEmpty), ": ")})`;
+    if (protocolError === "invalid_grant") {
+      return yield* OAuthGrantRejected.make({
+        message,
+        ...(errorSubtype === undefined ? {} : { errorSubtype }),
+      });
+    }
+    return yield* OAuthConnectionValidationFailed.make({ message });
+  }
+  return yield* pipe(
+    response.json,
+    Effect.mapError(cause =>
+      OAuthConnectionValidationFailed.make({
+        cause: Redacted.make(cause),
+        message: `${input.failurePrefix} (network)`,
+      }),
+    ),
+    Effect.flatMap(raw =>
+      pipe(
+        Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown))(raw),
+        Effect.mapError(() =>
+          OAuthConnectionValidationFailed.make({ message: "invalid oauth token response" }),
+        ),
+      ),
+    ),
+  );
+});
+
+const numberFromToken = (value: unknown): number | undefined => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+};
+
+const normalizeTokenResponse = Effect.fn("OAuthFlow.normalizeTokenResponse")(function* (input: {
+  readonly raw: Record<string, unknown>;
+  readonly method: AuthMethod.Any;
+  readonly previousRefreshToken?: string | undefined;
+}): Effect.fn.Return<AuthMethod.OAuth2TokenResponse, OAuthConnectionValidationFailed> {
+  const response = yield* pipe(
+    Schema.decodeUnknownEffect(
+      input.method.oauth2?.tokenResponse ?? AuthMethod.OAuth2ProviderTokenResponse,
+    )(input.raw),
+    Effect.mapError(() =>
+      OAuthConnectionValidationFailed.make({ message: "invalid oauth token response" }),
+    ),
+  );
+  const accessToken = yield* requiredString(
+    response.access_token,
+    "oauth token response missing access_token",
+  );
+  if (response.refresh_token?.trim() === "") {
+    return yield* OAuthConnectionValidationFailed.make({ message: "invalid oauth token response" });
+  }
+  const refreshToken = response.refresh_token ?? input.previousRefreshToken;
+  const expiresIn = numberFromToken(response.expires_in);
+  if (response.expires_in !== undefined && (expiresIn === undefined || expiresIn < 0)) {
+    return yield* OAuthConnectionValidationFailed.make({ message: "invalid oauth token response" });
+  }
+  const now = yield* Clock.currentTimeMillis;
+  const absoluteExpiry =
+    response.expires_at === undefined ? undefined : Date.parse(response.expires_at);
+  if (absoluteExpiry !== undefined && !Number.isFinite(absoluteExpiry)) {
+    return yield* OAuthConnectionValidationFailed.make({ message: "invalid oauth token response" });
+  }
+
+  return {
+    accessToken,
+    ...(refreshToken === undefined ? {} : { refreshToken }),
+    ...(response.token_type === undefined ? {} : { tokenType: response.token_type }),
+    ...(expiresIn === undefined ? {} : { expiresAt: now + expiresIn * 1000, expiresIn }),
+    ...(absoluteExpiry === undefined ? {} : { expiresAt: absoluteExpiry }),
+    ...(response.scope === undefined ? {} : { scope: response.scope }),
+    raw: input.raw,
+  };
+});
+
+export type OAuthFlowError = OAuthConnectionValidationFailed | OAuthProviderRejected;
+
+export interface OAuthFlowContinuation {
+  readonly state: string;
+  readonly redirectUri: string;
+  readonly pkceVerifier: string | null;
+  readonly expiresAt: Date;
+}
+
+export interface OAuthFlowStarted {
+  readonly authorizationUrl: string;
+  readonly continuation: OAuthFlowContinuation;
+}
+
+export interface OAuthFlowCompleted<Material> {
+  readonly tokens: AuthMethod.OAuth2TokenResponse;
+  readonly material: Material;
+}
+
+export class Service extends Context.Service<
+  Service,
+  {
+    readonly start: <Method extends AuthMethod.Any>(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly redirectUri: string;
+      readonly ttlMs?: number;
+    }) => Effect.Effect<OAuthFlowStarted, OAuthFlowError>;
+    readonly complete: <Method extends AuthMethod.Any>(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly continuation: OAuthFlowContinuation;
+      readonly query: Readonly<Record<string, string | undefined>>;
+    }) => Effect.Effect<OAuthFlowCompleted<AuthMethod.OAuth2TokenResponse>, OAuthFlowError>;
+    readonly refresh: <Method extends AuthMethod.Any>(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly refreshToken: string;
+    }) => Effect.Effect<
+      OAuthFlowCompleted<AuthMethod.OAuth2TokenResponse>,
+      OAuthFlowError | OAuthGrantRejected
+    >;
+  }
+>()("@dual-os/sdk/OAuthFlow") {}
+
+/** Deterministic OAuthFlow test layer that avoids external provider traffic. */
+export const testing = (
+  options: {
+    readonly accessToken?: string;
+    readonly refreshToken?: string;
+    readonly refreshedAccessToken?: string;
+    readonly tokenType?: string;
+    readonly expiresIn?: number;
+  } = {},
+) =>
+  Layer.succeed(
+    Service,
+    Service.of({
+      complete: Effect.fn("OAuthFlow.testing.complete")(function* <
+        Method extends AuthMethod.Any,
+      >(input: {
+        readonly method: Method;
+        readonly setup: AuthMethod.Setup<Method>;
+        readonly continuation: OAuthFlowContinuation;
+        readonly query: Readonly<Record<string, string | undefined>>;
+      }) {
+        if (input.query["state"] !== input.continuation.state) {
+          return yield* new OAuthConnectionValidationFailed({ message: "oauth state mismatch" });
+        }
+        if (input.query["error"] !== undefined) {
+          return yield* new OAuthProviderRejected({
+            error: input.query["error"],
+            errorDescription: input.query["error_description"],
+          });
+        }
+        if (input.query["code"] === undefined || input.query["code"].trim() === "") {
+          return yield* new OAuthConnectionValidationFailed({
+            message: "missing oauth authorization code",
+          });
+        }
+
+        const tokens: AuthMethod.OAuth2TokenResponse = {
+          accessToken: options.accessToken ?? `test_access_${input.query["code"]}`,
+          expiresIn: options.expiresIn ?? 3600,
+          raw: { code: input.query["code"], grantType: "authorization_code", testing: true },
+          refreshToken: options.refreshToken ?? `test_refresh_${input.query["code"]}`,
+          tokenType: options.tokenType ?? "Bearer",
+        };
+        return { material: tokens, tokens };
+      }),
+      refresh: Effect.fn("OAuthFlow.testing.refresh")(function* <
+        Method extends AuthMethod.Any,
+      >(input: {
+        readonly method: Method;
+        readonly setup: AuthMethod.Setup<Method>;
+        readonly refreshToken: string;
+      }) {
+        const tokens: AuthMethod.OAuth2TokenResponse = {
+          accessToken: options.refreshedAccessToken ?? `test_refreshed_${input.refreshToken}`,
+          expiresIn: options.expiresIn ?? 3600,
+          raw: { grantType: "refresh_token", testing: true },
+          refreshToken: input.refreshToken,
+          tokenType: options.tokenType ?? "Bearer",
+        };
+        yield* Effect.void;
+        return { material: tokens, tokens };
+      }),
+      start: Effect.fn("OAuthFlow.testing.start")(function* <Method extends AuthMethod.Any>(input: {
+        readonly method: Method;
+        readonly setup: AuthMethod.Setup<Method>;
+        readonly redirectUri: string;
+        readonly ttlMs?: number;
+      }) {
+        const oauth = input.method.oauth2;
+        if (oauth === undefined) {
+          return yield* new OAuthConnectionValidationFailed({
+            message: "auth method is not oauth2",
+          });
+        }
+        const client =
+          typeof oauth.client === "function" ? oauth.client({ setup: input.setup }) : oauth.client;
+        const state = `test_state_${yield* Random.nextInt}`;
+        const pkceVerifier = oauth.pkce === false ? null : `test_pkce_${yield* Random.nextInt}`;
+        const authorizationUrl = new URL(
+          resolveEndpoint(oauth.authorizationUrl, input.setup) ??
+            "https://oauth.testing.local/authorize",
+        );
+        authorizationUrl.searchParams.set("response_type", "code");
+        authorizationUrl.searchParams.set("client_id", globalThis.String(client.clientId));
+        authorizationUrl.searchParams.set("redirect_uri", input.redirectUri);
+        authorizationUrl.searchParams.set("state", state);
+        if (oauth.scopes.length > 0) {
+          authorizationUrl.searchParams.set("scope", oauth.scopes.join(" "));
+        }
+        if (pkceVerifier !== null) {
+          authorizationUrl.searchParams.set("code_challenge", "testing-code-challenge");
+          authorizationUrl.searchParams.set("code_challenge_method", "S256");
+        }
+        for (const [key, value] of Object.entries(
+          resolveParams(oauth.authorizationParams, input.setup),
+        )) {
+          authorizationUrl.searchParams.set(key, value);
+        }
+
+        return {
+          authorizationUrl: authorizationUrl.toString(),
+          continuation: {
+            expiresAt: new Date(
+              (yield* Clock.currentTimeMillis) + (input.ttlMs ?? DefaultFlowTtlMs),
+            ),
+            pkceVerifier,
+            redirectUri: input.redirectUri,
+            state,
+          },
+        };
+      }),
+    }),
+  );
+
+/** Live protocol layer that reads OAuth client config from Effect ConfigProvider. */
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const configProvider = yield* ConfigProvider.ConfigProvider;
+    const client = yield* HttpClient.HttpClient;
+
+    const start = Effect.fn("OAuthFlow.start")(function* <Method extends AuthMethod.Any>(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly redirectUri: string;
+      readonly ttlMs?: number;
+    }) {
+      const config = yield* resolveOAuthConfig({
+        client,
+        configProvider,
+        method: input.method,
+        setup: input.setup,
+      });
+      const expiresAt = new Date(
+        (yield* Clock.currentTimeMillis) + (input.ttlMs ?? DefaultFlowTtlMs),
+      );
+      const state = randomBase64Url(32);
+      const pkceVerifier = config.pkce ? randomBase64Url(32) : undefined;
+      const pkceChallenge =
+        pkceVerifier === undefined ? undefined : yield* sha256Base64Url(pkceVerifier);
+
+      return {
+        authorizationUrl: buildAuthorizationUrl({
+          config,
+          pkceChallenge,
+          redirectUri: input.redirectUri,
+          state,
+        }),
+        continuation: {
+          expiresAt,
+          pkceVerifier: pkceVerifier ?? null,
+          redirectUri: input.redirectUri,
+          state,
+        },
+      };
+    });
+
+    const complete = Effect.fn("OAuthFlow.complete")(function* <
+      Method extends AuthMethod.Any,
+    >(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly continuation: OAuthFlowContinuation;
+      readonly query: Readonly<Record<string, string | undefined>>;
+    }) {
+      if (input.query["state"] !== input.continuation.state) {
+        return yield* new OAuthConnectionValidationFailed({ message: "oauth state mismatch" });
+      }
+      if (input.query["error"] !== undefined) {
+        return yield* new OAuthProviderRejected({
+          error: input.query["error"],
+          errorDescription: input.query["error_description"],
+        });
+      }
+      const code = input.query["code"];
+      if (code === undefined || code.trim() === "") {
+        return yield* new OAuthConnectionValidationFailed({
+          message: "missing oauth authorization code",
+        });
+      }
+
+      const config = yield* resolveOAuthConfig({
+        client,
+        configProvider,
+        method: input.method,
+        setup: input.setup,
+      });
+      if (
+        config.expectedIssuer !== undefined &&
+        input.query["iss"] !== undefined &&
+        input.query["iss"] !== config.expectedIssuer
+      ) {
+        return yield* new OAuthConnectionValidationFailed({ message: "oauth issuer mismatch" });
+      }
+
+      const tokenParams = new URLSearchParams({
+        code,
+        grant_type: "authorization_code",
+        redirect_uri: input.continuation.redirectUri,
+      });
+      if (input.continuation.pkceVerifier !== null) {
+        tokenParams.set("code_verifier", input.continuation.pkceVerifier);
+      }
+
+      const rawTokens = yield* pipe(
+        postTokenRequest({
+          client,
+          config,
+          failurePrefix: "oauth token exchange failed",
+          params: tokenParams,
+        }),
+        Effect.catchTag("OAuthGrantRejected", error =>
+          Effect.fail(OAuthConnectionValidationFailed.make({ message: error.message })),
+        ),
+      );
+      const tokens = yield* normalizeTokenResponse({ method: input.method, raw: rawTokens });
+      return { material: tokens, tokens };
+    });
+
+    const refresh = Effect.fn("OAuthFlow.refresh")(function* <
+      Method extends AuthMethod.Any,
+    >(input: {
+      readonly method: Method;
+      readonly setup: AuthMethod.Setup<Method>;
+      readonly refreshToken: string;
+    }) {
+      const config = yield* resolveOAuthConfig({
+        client,
+        configProvider,
+        method: input.method,
+        setup: input.setup,
+      });
+      const rawTokens = yield* postTokenRequest({
+        client,
+        config,
+        failurePrefix: "oauth token refresh failed",
+        params: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: input.refreshToken,
+        }),
+      });
+      const tokens = yield* normalizeTokenResponse({
+        method: input.method,
+        previousRefreshToken: input.refreshToken,
+        raw: rawTokens,
+      });
+      return { material: tokens, tokens };
+    });
+
+    return Service.of({ complete, refresh, start });
+  }),
+).pipe(Layer.provide(FetchHttpClient.layer));
+
+export const oauth2TokenRefresherLayer = Layer.effect(
+  OAuth2TokenRefresher.Service,
+  Effect.gen(function* () {
+    const flow = yield* Service;
+    return OAuth2TokenRefresher.Service.of({
+      refresh: input =>
+        flow
+          .refresh({ method: input.method, refreshToken: input.refreshToken, setup: input.setup })
+          .pipe(Effect.map(refreshed => refreshed.tokens)),
+    });
+  }),
+);
+
+export * as OAuthFlow from "./OAuthFlow.ts";