Fix core OAuth typed boundaries

Rhys Sullivan committed 6 months ago

Commit 70d01de1 parent b039b6e2 files · +388 −542Browse files

Unified · Split

2 files

packages/core/sdk/src/oauth-discovery.ts +120 −152
packages/core/sdk/src/oauth-service.ts +268 −390

packages/core/sdk/src/oauth-discovery.ts+120−152

 // callers actually need.
 // ---------------------------------------------------------------------------
-import { Data, Effect, Result, Schema } from "effect";
+import { Data, Effect, Option, Predicate, Result, Schema } from "effect";
 import * as oauth from "oauth4webapi";
 import {
  *  token-endpoint failures. A plugin's refresh path should never have
  *  to inspect error messages to tell "metadata drifted, re-discover"
  *  apart from "refresh token is no longer honoured". */
-export class OAuthDiscoveryError extends Data.TaggedError(
+export class OAuthDiscoveryError extends Data.TaggedError("OAuthDiscoveryError")<{
-  "OAuthDiscoveryError",
-)<{
   readonly message: string;
   readonly status?: number;
   readonly cause?: unknown;
 }> {}
-const discoveryError = (
-  message: string,
-  options: { status?: number; cause?: unknown } = {},
-): OAuthDiscoveryError =>
-  new OAuthDiscoveryError({
-    message,
-    status: options.status,
-    cause: options.cause,
-  });
 // ---------------------------------------------------------------------------
 // Schemas (narrow structural parsing — the RFCs leave many fields
 // optional; we validate only the subset consumers read)
 // ---------------------------------------------------------------------------
 const StringArray = Schema.Array(Schema.String);
+const JsonValueSchema = Schema.fromJsonString(Schema.Unknown);
+const DcrErrorBodySchema = Schema.Struct({
+  error: Schema.NonEmptyString,
+  error_description: Schema.optional(Schema.String),
+});
 export const OAuthProtectedResourceMetadataSchema = Schema.Struct({
   resource: Schema.optional(Schema.String),
   bearer_methods_supported: Schema.optional(StringArray),
   resource_documentation: Schema.optional(Schema.String),
 }).annotate({ identifier: "OAuthProtectedResourceMetadata" });
-export type OAuthProtectedResourceMetadata =
+export type OAuthProtectedResourceMetadata = typeof OAuthProtectedResourceMetadataSchema.Type;
-  typeof OAuthProtectedResourceMetadataSchema.Type;
 export const OAuthAuthorizationServerMetadataSchema = Schema.Struct({
   issuer: Schema.String,
   userinfo_endpoint: Schema.optional(Schema.String),
   id_token_signing_alg_values_supported: Schema.optional(StringArray),
 }).annotate({ identifier: "OAuthAuthorizationServerMetadata" });
-export type OAuthAuthorizationServerMetadata =
+export type OAuthAuthorizationServerMetadata = typeof OAuthAuthorizationServerMetadataSchema.Type;
-  typeof OAuthAuthorizationServerMetadataSchema.Type;
 export type DynamicClientMetadata = {
   readonly client_name?: string;
 }).annotate({ identifier: "OAuthClientInformation" });
 export type OAuthClientInformation = typeof OAuthClientInformationSchema.Type;
-const decodeResourceMetadata = Schema.decodeUnknownEffect(
+const decodeResourceMetadata = Schema.decodeUnknownEffect(OAuthProtectedResourceMetadataSchema);
-  OAuthProtectedResourceMetadataSchema,
+const decodeAuthServerMetadata = Schema.decodeUnknownEffect(OAuthAuthorizationServerMetadataSchema);
-);
+const decodeClientInformation = Schema.decodeUnknownEffect(OAuthClientInformationSchema);
-const decodeAuthServerMetadata = Schema.decodeUnknownEffect(
-  OAuthAuthorizationServerMetadataSchema,
-);
-const decodeClientInformation = Schema.decodeUnknownEffect(
-  OAuthClientInformationSchema,
-);
 export interface DiscoveryRequestOptions {
   /** Injected for tests. Defaults to the global `fetch`. */
 const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
-const isLoopbackHttpUrl = (value: string): boolean => {
+const parseUrlOption = (value: string): URL | null => {
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: URL constructor is the platform URL parser
   try {
-    const url = new URL(value);
+    return new URL(value);
-    if (url.protocol !== "http:") return false;
-    const hostname = url.hostname.toLowerCase();
-    return (
-      hostname === "localhost" ||
-      hostname === "0.0.0.0" ||
-      hostname === "::1" ||
-      hostname === "[::1]" ||
-      hostname.startsWith("127.")
-    );
   } catch {
-    return false;
+    return null;
   }
 };
+const isLoopbackHttpUrl = (value: string): boolean => {
+  const parsed = parseUrlOption(value);
+  if (!parsed || parsed.protocol !== "http:") return false;
+  const hostname = parsed.hostname.toLowerCase();
+  return (
+    hostname === "localhost" ||
+    hostname === "0.0.0.0" ||
+    hostname === "::1" ||
+    hostname === "[::1]" ||
+    hostname.startsWith("127.")
+  );
+};
 const oauth4webapiOptions = (
   options: DiscoveryRequestOptions,
   targetUrl?: string,
   const out: Record<string, unknown> = {};
   if (options.fetch) (out as { [customFetch]?: typeof fetch })[customFetch] = options.fetch;
   if (targetUrl && isLoopbackHttpUrl(targetUrl)) {
-    (out as { [oauth.allowInsecureRequests]?: boolean })[
+    (out as { [oauth.allowInsecureRequests]?: boolean })[oauth.allowInsecureRequests] = true;
-      oauth.allowInsecureRequests
-    ] = true;
   }
   const signal = AbortSignal.timeout(options.timeoutMs ?? OAUTH2_DEFAULT_TIMEOUT_MS);
   out.signal = signal;
   resourceUrl: string,
   options: DiscoveryRequestOptions = {},
 ): Effect.Effect<
-  | { readonly metadataUrl: string; readonly metadata: OAuthProtectedResourceMetadata }
+  { readonly metadataUrl: string; readonly metadata: OAuthProtectedResourceMetadata } | null,
-  | null,
   OAuthDiscoveryError
 > =>
   Effect.gen(function* () {
           }
           const text = await response.text();
           if (text.length === 0) return "skip" as const;
-          return { status: response.status, body: JSON.parse(text) } as const;
+          return { status: response.status, body: text } as const;
         },
         catch: (cause) =>
-          discoveryError(
+          new OAuthDiscoveryError({
-            `Failed to fetch ${url}: ${cause instanceof Error ? cause.message : String(cause)}`,
+            message: `Failed to fetch ${url}`,
-            { cause },
+            cause,
-          ),
+          }),
       });
       if (result === "skip") continue;
       if (!("body" in result)) {
-        return yield* Effect.fail(
+        return yield* new OAuthDiscoveryError({
-          discoveryError(
+          message: `Protected resource metadata returned status ${result.status}`,
-            `Protected resource metadata returned status ${result.status}`,
+          status: result.status,
-            { status: result.status },
+        });
-          ),
-        );
       }
-      const metadata = yield* decodeResourceMetadata(result.body).pipe(
+      const parsedBody = yield* Schema.decodeUnknownEffect(JsonValueSchema)(result.body).pipe(
         Effect.mapError(
           (err) =>
             new OAuthDiscoveryError({
-              message: `Protected resource metadata is malformed: ${
+              message: "Protected resource metadata is malformed: invalid JSON",
-                Schema.isSchemaError(err) ? err.message : String(err)
+              cause: err,
-              }`,
+            }),
+        ),
+      );
+      const metadata = yield* decodeResourceMetadata(parsedBody).pipe(
+        Effect.mapError(
+          (err) =>
+            new OAuthDiscoveryError({
+              message: "Protected resource metadata is malformed: invalid shape",
               cause: err,
             }),
         ),
 ): string => {
   // Mirrors the library's own well-known composition so the URL we
   // surface matches what was actually fetched.
-  const suffix = algorithm === "oauth2"
+  const suffix = algorithm === "oauth2" ? "oauth-authorization-server" : "openid-configuration";
-    ? "oauth-authorization-server"
-    : "openid-configuration";
   return issuerPath && issuerPath !== "/"
     ? `${issuerOrigin}/.well-known/${suffix}${issuerPath}`
     : `${issuerOrigin}/.well-known/${suffix}`;
   issuer: string,
   options: DiscoveryRequestOptions = {},
 ): Effect.Effect<
-  | {
+  {
-      readonly metadataUrl: string;
+    readonly metadataUrl: string;
-      readonly metadata: OAuthAuthorizationServerMetadata;
+    readonly metadata: OAuthAuthorizationServerMetadata;
-    }
+  } | null,
-  | null,
   OAuthDiscoveryError
 > =>
   Effect.gen(function* () {
           };
         },
         catch: (cause) => {
-          if (cause instanceof OAuthDiscoveryError) return cause;
+          if (Predicate.isTagged("OAuthDiscoveryError")(cause)) return cause;
-          return discoveryError(
+          return new OAuthDiscoveryError({
-            `Discovery (${algorithm}) failed for ${issuer}: ${
+            message: `Discovery (${algorithm}) failed for ${issuer}`,
-              cause instanceof Error ? cause.message : String(cause)
+            cause,
-            }`,
+          });
-            { cause },
-          );
         },
       }).pipe(
         // If one algorithm fails mid-roundtrip (network, parse, issuer
         Effect.mapError(
           (err) =>
             new OAuthDiscoveryError({
-              message: `Authorization server metadata is malformed: ${
+              message: "Authorization server metadata is malformed: invalid shape",
-                Schema.isSchemaError(err) ? err.message : String(err)
-              }`,
               cause: err,
             }),
         ),
   return body;
 };
-const interpretDcrFailure = (
+const interpretDcrFailure = (status: number, text: string): DcrErrorBody | DcrTransport => {
-  status: number,
-  text: string,
-): DcrErrorBody | DcrTransport => {
   // RFC 6749 error envelope: `{error, error_description?}` with 4xx.
   if (status >= 400 && status < 500) {
-    const parsed = Result.try({
+    const parsedJson = Schema.decodeUnknownOption(JsonValueSchema)(text);
-      try: () => (text ? (JSON.parse(text) as unknown) : null),
+    const parsed = Option.isSome(parsedJson)
-      catch: () => null,
+      ? Schema.decodeUnknownOption(DcrErrorBodySchema)(parsedJson.value)
-    });
+      : Option.none();
-    const body = Result.isSuccess(parsed) ? parsed.success : null;
+    if (Option.isSome(parsed)) {
-    if (
+      return new DcrErrorBody({
-      body &&
+        status,
-      typeof body === "object" &&
+        error: parsed.value.error,
-      "error" in body &&
+        error_description: parsed.value.error_description,
-      typeof body.error === "string" &&
+      });
-      body.error.length > 0
-    ) {
-      const desc =
-        "error_description" in body && typeof body.error_description === "string"
-          ? body.error_description
-          : undefined;
-      return new DcrErrorBody({ status, error: body.error, error_description: desc });
     }
   }
   return new DcrTransport({
 ): Effect.Effect<OAuthClientInformation, OAuthDiscoveryError> =>
   Effect.gen(function* () {
     const url = new URL(input.registrationEndpoint);
-    if (
+    if (url.protocol !== "https:" && !isLoopbackHttpUrl(input.registrationEndpoint)) {
-      url.protocol !== "https:" &&
-      !isLoopbackHttpUrl(input.registrationEndpoint)
-    ) {
       return yield* new DcrTransport({
         message: `registration_endpoint must be HTTPS or a loopback HTTP URL (got ${url.protocol}//${url.host})`,
       });
         }),
       catch: (cause) =>
         new DcrTransport({
-          message: `Dynamic Client Registration request failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+          message: "Dynamic Client Registration request failed",
           cause,
         }),
     });
     // Accept both 200 and 201 as success — RFC 7591 mandates 201, but
     // Todoist (and others) return 200 OK with the client information body.
     if (response.status !== 200 && response.status !== 201) {
-      const text = yield* Effect.promise(() =>
+      const text = yield* Effect.tryPromise({
-        response.text().catch(() => ""),
+        try: () => response.text(),
-      );
+        catch: (cause) =>
+          new DcrTransport({
+            message: "Dynamic Client Registration error response could not be read",
+            status: response.status,
+            cause,
+          }),
+      }).pipe(Effect.catchTag("DcrTransport", () => Effect.succeed("")));
       return yield* interpretDcrFailure(response.status, text);
     }
           cause,
         }),
     });
-    const json = yield* Effect.try({
+    const json = yield* Schema.decodeUnknownEffect(JsonValueSchema)(text).pipe(
-      try: () => JSON.parse(text) as unknown,
+      Effect.mapError(
-      catch: (cause) =>
+        (cause) =>
-        new DcrTransport({
+          new DcrTransport({
-          message: "Dynamic Client Registration response was not valid JSON",
+            message: "Dynamic Client Registration response was not valid JSON",
-          status: response.status,
+            status: response.status,
-          cause,
+            cause,
-        }),
+          }),
-    });
+      ),
+    );
     return yield* decodeClientInformation(json).pipe(
       Effect.mapError(
         (err) =>
           new OAuthDiscoveryError({
-            message: `Dynamic Client Registration response is malformed: ${
+            message: "Dynamic Client Registration response is malformed: invalid shape",
-              Schema.isSchemaError(err) ? err.message : String(err)
-            }`,
             cause: err,
           }),
       ),
     Effect.catchTags({
       DcrErrorBody: (err) =>
         Effect.fail(
-          discoveryError(
+          new OAuthDiscoveryError({
-            `Dynamic Client Registration failed: ${err.error}${
+            message: `Dynamic Client Registration failed: ${err.error}${
               err.error_description ? ` — ${err.error_description}` : ""
             }`,
-            { status: err.status, cause: err },
+            status: err.status,
-          ),
+            cause: err,
+          }),
         ),
       DcrTransport: (err) =>
         Effect.fail(
-          discoveryError(`Dynamic Client Registration failed: ${err.message}`, {
+          new OAuthDiscoveryError({
+            message: "Dynamic Client Registration failed",
             status: err.status,
             cause: err.cause ?? err,
           }),
     const authorizationServerUrl = (() => {
       if (prior.authorizationServerUrl) return prior.authorizationServerUrl;
-      const fromResource =
+      const fromResource = resource && resource.metadata.authorization_servers?.[0];
-        resource && resource.metadata.authorization_servers?.[0];
       if (fromResource) return fromResource;
-      const u = new URL(input.endpoint);
+      const u = parseUrlOption(input.endpoint);
-      return `${u.protocol}//${u.host}`;
+      return u ? `${u.protocol}//${u.host}` : input.endpoint;
     })();
     const authServer =
             metadata: prior.authorizationServerMetadata,
             metadataUrl: prior.authorizationServerMetadataUrl,
           }
-        : yield* discoverAuthorizationServerMetadata(
+        : yield* discoverAuthorizationServerMetadata(authorizationServerUrl, options);
-            authorizationServerUrl,
-            options,
-          );
     if (!authServer) {
-      return yield* Effect.fail(
+      return yield* new OAuthDiscoveryError({
-        discoveryError(
+        message: `No OAuth authorization server metadata at ${authorizationServerUrl}`,
-          `No OAuth authorization server metadata at ${authorizationServerUrl}`,
+      });
-        ),
-      );
     }
     const pkceMethods = authServer.metadata.code_challenge_methods_supported ?? [];
     if (pkceMethods.length > 0 && !pkceMethods.includes("S256")) {
-      return yield* Effect.fail(
+      return yield* new OAuthDiscoveryError({
-        discoveryError(
+        message: `Authorization server does not support PKCE S256 (advertised: ${pkceMethods.join(", ")})`,
-          `Authorization server does not support PKCE S256 (advertised: ${pkceMethods.join(", ")})`,
+      });
-        ),
-      );
     }
     const responseTypes = authServer.metadata.response_types_supported ?? [];
     if (responseTypes.length > 0 && !responseTypes.includes("code")) {
-      return yield* Effect.fail(
+      return yield* new OAuthDiscoveryError({
-        discoveryError(
+        message: `Authorization server does not support response_type=code (advertised: ${responseTypes.join(", ")})`,
-          `Authorization server does not support response_type=code (advertised: ${responseTypes.join(", ")})`,
+      });
-        ),
-      );
     }
     const baseClientMetadata: DynamicClientMetadata = {
         const reg = authServer.metadata.registration_endpoint;
         if (!reg) {
           return Effect.fail(
-            discoveryError(
+            new OAuthDiscoveryError({
-              "Authorization server does not advertise registration_endpoint — cannot auto-register a client",
+              message:
-            ),
+                "Authorization server does not advertise registration_endpoint — cannot auto-register a client",
+            }),
           );
         }
         return registerDynamicClient(
       })());
     const codeVerifier = createPkceCodeVerifier();
-    const codeChallenge = yield* Effect.promise(() =>
+    const codeChallenge = yield* Effect.promise(() => createPkceCodeChallenge(codeVerifier));
-      createPkceCodeChallenge(codeVerifier),
-    );
     const scopes = input.scopes ?? authServer.metadata.scopes_supported ?? [];
     const authorizationUrl = buildAuthorizationUrl({

packages/core/sdk/src/oauth-service.ts+268−390

 // every strategy because refresh semantics are strategy-independent.
 // ---------------------------------------------------------------------------
-import { Effect, Schema } from "effect";
+import { Effect, Option, Predicate, Schema } from "effect";
-import type {
+import type { DBAdapter, StorageFailure, TypedAdapter } from "@executor-js/storage-core";
-  DBAdapter,
-  StorageFailure,
-  TypedAdapter,
-} from "@executor-js/storage-core";
 import {
   ConnectionRefreshError,
   type ConnectionRefreshResult,
   type ConnectionRef,
 } from "./connections";
-import type {
+import type { ConnectionProviderNotRegisteredError } from "./errors";
-  ConnectionProviderNotRegisteredError,
-} from "./errors";
 import type { CoreSchema } from "./core-schema";
 import { ConnectionId, ScopeId, SecretId } from "./ids";
 import { SetSecretInput, type SecretRef } from "./secrets";
 const OAuthAuthorizationServerMetadataJson = Schema.Record(Schema.String, Schema.Unknown);
 const OAuthClientInformationJson = Schema.Record(Schema.String, Schema.Unknown);
+const UnknownRecord = Schema.Record(Schema.String, Schema.Unknown);
+const JsonValueSchema = Schema.fromJsonString(Schema.Unknown);
 const DynamicDcrSessionPayload = Schema.Struct({
   kind: Schema.Literal("dynamic-dcr"),
   authorizationServerMetadata: OAuthAuthorizationServerMetadataJson,
   clientInformation: OAuthClientInformationJson,
   resourceMetadataUrl: Schema.NullOr(Schema.String),
-  resourceMetadata: Schema.NullOr(
+  resourceMetadata: Schema.NullOr(Schema.Record(Schema.String, Schema.Unknown)),
-    Schema.Record(Schema.String, Schema.Unknown),
-  ),
   scopes: Schema.Array(Schema.String),
 });
   codeVerifier: Schema.String,
   authorizationEndpoint: Schema.String,
   tokenEndpoint: Schema.String,
-  issuerUrl: Schema.NullOr(Schema.String).pipe(Schema.withDecodingDefaultType(Effect.succeed(null))),
+  issuerUrl: Schema.NullOr(Schema.String).pipe(
+    Schema.withDecodingDefaultType(Effect.succeed(null)),
+  ),
   clientIdSecretId: Schema.String,
   clientSecretSecretId: Schema.NullOr(Schema.String),
   scopes: Schema.Array(Schema.String),
 const coerceJson = (value: unknown): unknown => {
   if (typeof value !== "string") return value;
-  try {
+  const parsed = Schema.decodeUnknownOption(JsonValueSchema)(value);
-    return JSON.parse(value);
+  return Option.isSome(parsed) ? parsed.value : value;
-  } catch {
-    return value;
-  }
 };
 const stringArray = (value: unknown): readonly string[] =>
-  Array.isArray(value)
+  Array.isArray(value) ? value.filter((scope): scope is string => typeof scope === "string") : [];
-    ? value.filter((scope): scope is string => typeof scope === "string")
-    : [];
 const originOrNull = (value: unknown): string | null => {
   if (typeof value !== "string") return null;
+  return parseUrlOption(value)?.origin ?? null;
+};
+const parseUrlOption = (value: string): URL | null => {
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: URL constructor is the platform URL parser
   try {
-    return new URL(value).origin;
+    return new URL(value);
   } catch {
     return null;
   }
 const decodeProviderState = (value: unknown): OAuthProviderState => {
   const raw = coerceJson(value);
-  const record =
+  const decodedRecord = Schema.decodeUnknownOption(UnknownRecord)(raw);
-    raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
+  const record = Option.isSome(decodedRecord) ? decodedRecord.value : null;
   if (record && !("kind" in record) && "flow" in record && "tokenUrl" in record) {
     const flow = record.flow;
     }
   }
-  if (
+  if (record && !("kind" in record) && "clientIdSecretId" in record && "scopes" in record) {
-    record &&
-    !("kind" in record) &&
-    "clientIdSecretId" in record &&
-    "scopes" in record
-  ) {
     const scopes = stringArray(record.scopes);
     return Schema.decodeUnknownSync(OAuthProviderStateSchema)({
       kind: "authorization-code",
     });
   }
-  if (
+  if (record && !("kind" in record) && "clientInformation" in record && "endpoint" in record) {
-    record &&
+    const decodedClientInformation = Schema.decodeUnknownOption(UnknownRecord)(
-    !("kind" in record) &&
+      record.clientInformation,
-    "clientInformation" in record &&
+    );
-    "endpoint" in record
+    const clientInformation = Option.isSome(decodedClientInformation)
-  ) {
+      ? decodedClientInformation.value
-    const clientInformation =
+      : null;
-      record.clientInformation && typeof record.clientInformation === "object"
+    const decodedAuthorizationServerMetadata = Schema.decodeUnknownOption(UnknownRecord)(
-        ? (record.clientInformation as Record<string, unknown>)
+      record.authorizationServerMetadata,
-        : null;
+    );
+    const authorizationServerMetadata = Option.isSome(decodedAuthorizationServerMetadata)
+      ? decodedAuthorizationServerMetadata.value
+      : null;
     return Schema.decodeUnknownSync(OAuthProviderStateSchema)({
       kind: "dynamic-dcr",
       tokenEndpoint:
         typeof record.tokenEndpoint === "string"
           ? record.tokenEndpoint
-          : record.authorizationServerMetadata &&
+          : typeof authorizationServerMetadata?.token_endpoint === "string"
-              typeof record.authorizationServerMetadata === "object" &&
+            ? authorizationServerMetadata.token_endpoint
-              typeof (record.authorizationServerMetadata as Record<string, unknown>)
-                .token_endpoint === "string"
-            ? ((record.authorizationServerMetadata as Record<string, unknown>)
-                .token_endpoint as string)
             : "",
       issuerUrl:
-        record.authorizationServerMetadata &&
+        typeof authorizationServerMetadata?.issuer === "string"
-        typeof record.authorizationServerMetadata === "object" &&
+          ? authorizationServerMetadata.issuer
-        typeof (record.authorizationServerMetadata as Record<string, unknown>).issuer ===
-          "string"
-          ? ((record.authorizationServerMetadata as Record<string, unknown>)
-              .issuer as string)
           : null,
       authorizationServerUrl:
-        typeof record.authorizationServerUrl === "string"
+        typeof record.authorizationServerUrl === "string" ? record.authorizationServerUrl : null,
-          ? record.authorizationServerUrl
-          : null,
       authorizationServerMetadataUrl:
         typeof record.authorizationServerMetadataUrl === "string"
           ? record.authorizationServerMetadataUrl
           : null,
-      clientId:
+      clientId: typeof clientInformation?.client_id === "string" ? clientInformation.client_id : "",
-        typeof clientInformation?.client_id === "string"
-          ? clientInformation.client_id
-          : "",
       clientSecretSecretId: null,
       clientAuth: "body",
       scope: null,
    *  `complete` (and from `start` for `client-credentials`). */
   readonly connectionsCreate: (
     input: CreateConnectionInput,
-  ) => Effect.Effect<
+  ) => Effect.Effect<ConnectionRef, ConnectionProviderNotRegisteredError | StorageFailure>;
-    ConnectionRef,
-    ConnectionProviderNotRegisteredError | StorageFailure
-  >;
   /** Random session id generator. Tests override to make outputs
    *  deterministic. */
   readonly newSessionId?: () => string;
   if (crypto?.randomUUID) return `oauth2_session_${crypto.randomUUID()}`;
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
-  return `oauth2_session_${Array.from(bytes, (byte) =>
+  return `oauth2_session_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
-    byte.toString(16).padStart(2, "0"),
+    "",
-  ).join("")}`;
+  )}`;
 };
 const secretIdPart = (value: string): string =>
 const scopedSessionId = (scopeId: string, sessionId: string): string =>
   `${sessionId}_${secretIdPart(scopeId).slice(0, 24)}`;
-const terminalRefreshErrors = new Set([
+const terminalRefreshErrors = new Set(["invalid_grant", "invalid_client", "unauthorized_client"]);
-  "invalid_grant",
-  "invalid_client",
-  "unauthorized_client",
-]);
 // ---------------------------------------------------------------------------
 // Service factory
   // -------------------------------------------------------------------
   // probe
   // -------------------------------------------------------------------
-  const probe = (
+  const probe = (input: OAuthProbeInput): Effect.Effect<OAuthProbeResult, OAuthProbeError> =>
-    input: OAuthProbeInput,
-  ): Effect.Effect<OAuthProbeResult, OAuthProbeError> =>
     Effect.gen(function* () {
-      const resource = yield* discoverProtectedResourceMetadata(
+      const resource = yield* discoverProtectedResourceMetadata(input.endpoint, {
-        input.endpoint,
+        resourceHeaders: input.headers,
-        { resourceHeaders: input.headers, resourceQueryParams: input.queryParams },
+        resourceQueryParams: input.queryParams,
-      ).pipe(
+      }).pipe(
-        Effect.catchTag("OAuthDiscoveryError", (err) =>
+        Effect.catchTag("OAuthDiscoveryError", () =>
           Effect.fail(
             new OAuthProbeError({
-              message: `Protected resource metadata probe failed: ${err.message}`,
+              message: "Protected resource metadata probe failed",
             }),
           ),
         ),
       const authorizationServerUrl = (() => {
         const fromResource = resource?.metadata.authorization_servers?.[0];
         if (fromResource) return fromResource;
-        try {
+        const u = parseUrlOption(input.endpoint);
-          const u = new URL(input.endpoint);
+        return u ? `${u.protocol}//${u.host}` : null;
-          return `${u.protocol}//${u.host}`;
-        } catch {
-          return null;
-        }
       })();
       const authServer = authorizationServerUrl
-        ? yield* discoverAuthorizationServerMetadata(
+        ? yield* discoverAuthorizationServerMetadata(authorizationServerUrl).pipe(
-            authorizationServerUrl,
+            Effect.catchTag("OAuthDiscoveryError", () => Effect.succeed(null)),
-          ).pipe(
-            Effect.catchTag("OAuthDiscoveryError", () =>
-              Effect.succeed(null),
-            ),
           )
         : null;
       const supportsDynamicRegistration = !!(
         authServer?.metadata.registration_endpoint &&
-        (authServer.metadata.token_endpoint_auth_methods_supported ?? []).includes(
+        (authServer.metadata.token_endpoint_auth_methods_supported ?? []).includes("none")
-          "none",
-        )
       );
       // Bearer challenge probe — POST the endpoint unauth, look for
       // challenge").
       const isBearerChallengeEndpoint = yield* Effect.tryPromise({
         try: async (): Promise<boolean> => {
-          const controller = new AbortController();
+          const probeUrl = parseUrlOption(input.endpoint);
-          const timer = setTimeout(() => controller.abort(), 6_000);
+          if (!probeUrl) return false;
-          try {
+          for (const [key, value] of Object.entries(input.queryParams ?? {})) {
-            const probeUrl = new URL(input.endpoint);
+            probeUrl.searchParams.set(key, value);
-            for (const [key, value] of Object.entries(input.queryParams ?? {})) {
-              probeUrl.searchParams.set(key, value);
-            }
-            const response = await fetch(probeUrl.toString(), {
-              method: "POST",
-              headers: {
-                ...(input.headers ?? {}),
-                "content-type": "application/json",
-                accept: "application/json, text/event-stream",
-              },
-              body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: 1,
-                method: "initialize",
-                params: {
-                  protocolVersion: "2025-06-18",
-                  capabilities: {},
-                  clientInfo: { name: "executor-probe", version: "0" },
-                },
-              }),
-              signal: controller.signal,
-            });
-            if (response.status !== 401) return false;
-            const wwwAuth =
-              response.headers.get("www-authenticate") ??
-              response.headers.get("WWW-Authenticate");
-            return !!wwwAuth && /^\s*bearer\b/i.test(wwwAuth);
-          } finally {
-            clearTimeout(timer);
           }
+          const response = await fetch(probeUrl.toString(), {
+            method: "POST",
+            headers: {
+              ...(input.headers ?? {}),
+              "content-type": "application/json",
+              accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify({
+              jsonrpc: "2.0",
+              id: 1,
+              method: "initialize",
+              params: {
+                protocolVersion: "2025-06-18",
+                capabilities: {},
+                clientInfo: { name: "executor-probe", version: "0" },
+              },
+            }),
+            signal: AbortSignal.timeout(6_000),
+          });
+          if (response.status !== 401) return false;
+          const wwwAuth =
+            response.headers.get("www-authenticate") ?? response.headers.get("WWW-Authenticate");
+          return !!wwwAuth && /^\s*bearer\b/i.test(wwwAuth);
         },
         catch: () => null,
       }).pipe(Effect.catch(() => Effect.succeed(false)));
       return {
-        resourceMetadata:
+        resourceMetadata: (resource?.metadata as Record<string, unknown> | undefined) ?? null,
-          (resource?.metadata as Record<string, unknown> | undefined) ?? null,
         resourceMetadataUrl: resource?.metadataUrl ?? null,
         authorizationServerMetadata:
           (authServer?.metadata as Record<string, unknown> | undefined) ?? null,
     strategy: OAuthDynamicDcrStrategy,
   ): Effect.Effect<OAuthStartResult, OAuthStartError | StorageFailure> =>
     Effect.gen(function* () {
-      const started = yield* beginDynamicAuthorization({
+      const started = yield* beginDynamicAuthorization(
-        endpoint: input.endpoint,
+        {
-        redirectUrl: input.redirectUrl,
+          endpoint: input.endpoint,
-        state: "",
+          redirectUrl: input.redirectUrl,
-        scopes: strategy.scopes,
+          state: "",
-      }, {
+          scopes: strategy.scopes,
-        resourceHeaders: input.headers,
+        },
-        resourceQueryParams: input.queryParams,
+        {
-      }).pipe(
+          resourceHeaders: input.headers,
-        Effect.catchTag("OAuthDiscoveryError", (err) =>
+          resourceQueryParams: input.queryParams,
+        },
+      ).pipe(
+        Effect.catchTag("OAuthDiscoveryError", () =>
           Effect.fail(
             new OAuthStartError({
-              message: `Dynamic authorization setup failed: ${err.message}`,
+              message: "Dynamic authorization setup failed",
             }),
           ),
         ),
         authorizationUrl: started.state.authorizationServerMetadata.authorization_endpoint,
         clientId: started.state.clientInformation.client_id,
         redirectUrl: input.redirectUrl,
-        scopes:
+        scopes: strategy.scopes ?? started.state.authorizationServerMetadata.scopes_supported ?? [],
-          strategy.scopes ??
-          started.state.authorizationServerMetadata.scopes_supported ??
-          [],
         state: sessionId,
         codeChallenge,
       });
         identityLabel: input.identityLabel ?? null,
         codeVerifier: started.codeVerifier,
         authorizationServerUrl: started.state.authorizationServerUrl,
-        authorizationServerMetadataUrl:
+        authorizationServerMetadataUrl: started.state.authorizationServerMetadataUrl,
-          started.state.authorizationServerMetadataUrl,
+        authorizationServerMetadata: started.state.authorizationServerMetadata as Record<
-        authorizationServerMetadata:
+          string,
-          started.state.authorizationServerMetadata as Record<string, unknown>,
+          unknown
+        >,
         clientInformation: (() => {
           const value: unknown = started.state.clientInformation;
           return value as Record<string, unknown>;
         })(),
         resourceMetadataUrl: started.state.resourceMetadataUrl,
         resourceMetadata:
-          (started.state.resourceMetadata as Record<string, unknown> | null) ??
+          (started.state.resourceMetadata as Record<string, unknown> | null) ?? null,
-          null,
         scopes: [
-          ...(strategy.scopes ??
+          ...(strategy.scopes ?? started.state.authorizationServerMetadata.scopes_supported ?? []),
-            started.state.authorizationServerMetadata.scopes_supported ??
-            []),
         ],
       };
   ): Effect.Effect<OAuthStartResult, OAuthStartError | StorageFailure> =>
     Effect.gen(function* () {
       const clientId = yield* deps.secretsGet(strategy.clientIdSecretId).pipe(
-        Effect.mapError((err) =>
+        Effect.mapError(
-          // Storage failure propagates; null returns aren't errors — the
+          (err) =>
-          // branch below handles them.
+            // Storage failure propagates; null returns aren't errors — the
-          err,
+            // branch below handles them.
+            err,
         ),
       );
       if (clientId === null) {
-        return yield* Effect.fail(
+        return yield* new OAuthStartError({
-          new OAuthStartError({
+          message: `client_id secret "${strategy.clientIdSecretId}" not found`,
-            message: `client_id secret "${strategy.clientIdSecretId}" not found`,
+        });
-          }),
-        );
       }
       const sessionId = scopedSessionId(input.tokenScope, newSessionId());
       const codeVerifier = createPkceCodeVerifier();
-      const codeChallenge = yield* Effect.promise(() =>
+      const codeChallenge = yield* Effect.promise(() => createPkceCodeChallenge(codeVerifier));
-        createPkceCodeChallenge(codeVerifier),
-      );
       const authorizationUrl = buildAuthorizationUrl({
         authorizationUrl: strategy.authorizationEndpoint,
       const clientId = yield* deps.secretsGet(strategy.clientIdSecretId);
       const clientSecret = yield* deps.secretsGet(strategy.clientSecretSecretId);
       if (clientId === null || clientSecret === null) {
-        return yield* Effect.fail(
+        return yield* new OAuthStartError({
-          new OAuthStartError({
+          message: "client_id / client_secret secret not found",
-            message: "client_id / client_secret secret not found",
+        });
-          }),
-        );
       }
       const tokens = yield* exchangeClientCredentials({
         clientAuth: strategy.clientAuth ?? "body",
       }).pipe(
         Effect.mapError(
-          (err) =>
+          () =>
             new OAuthStartError({
-              message: `Client credentials exchange failed: ${err.message}`,
+              message: "Client credentials exchange failed",
             }),
         ),
       );
       const expiresAt =
-        typeof tokens.expires_in === "number"
+        typeof tokens.expires_in === "number" ? now() + tokens.expires_in * 1000 : null;
-          ? now() + tokens.expires_in * 1000
-          : null;
       const providerState: OAuthProviderState = {
         kind: "client-credentials",
             refreshToken: null,
             expiresAt,
             oauthScope: tokens.scope ?? null,
-            providerState: Schema.encodeSync(OAuthProviderStateSchema)(
+            providerState: Schema.encodeSync(OAuthProviderStateSchema)(providerState) as Record<
-              providerState,
+              string,
-            ) as Record<string, unknown>,
+              unknown
+            >,
           }),
         )
         .pipe(
           Effect.mapError(
-            (err) =>
+            () =>
               new OAuthStartError({
-                message: `Failed to mint connection: ${
+                message: "Failed to mint connection",
-                  err instanceof Error ? err.message : String(err)
-                }`,
               }),
           ),
         );
     payload: OAuthSessionPayload;
     strategyKind: string;
   }): Effect.Effect<void, StorageFailure> =>
-    deps.adapter.create({
+    deps.adapter
-      model: "oauth2_session",
+      .create({
-      data: {
+        model: "oauth2_session",
-        id: args.sessionId,
+        data: {
-        scope_id: args.input.tokenScope,
+          id: args.sessionId,
-        plugin_id: args.input.pluginId,
+          scope_id: args.input.tokenScope,
-        strategy: args.strategyKind,
+          plugin_id: args.input.pluginId,
-        connection_id: args.input.connectionId,
+          strategy: args.strategyKind,
-        token_scope: args.input.tokenScope,
+          connection_id: args.input.connectionId,
-        redirect_url: args.input.redirectUrl,
+          token_scope: args.input.tokenScope,
-        payload: encodeSessionPayload(args.payload) as Record<string, unknown>,
+          redirect_url: args.input.redirectUrl,
-        expires_at: now() + OAUTH2_SESSION_TTL_MS,
+          payload: encodeSessionPayload(args.payload) as Record<string, unknown>,
-        created_at: new Date(),
+          expires_at: now() + OAUTH2_SESSION_TTL_MS,
-      },
+          created_at: new Date(),
-      forceAllowId: true,
+        },
-    }).pipe(Effect.asVoid);
+        forceAllowId: true,
+      })
+      .pipe(Effect.asVoid);
   // -------------------------------------------------------------------
   // complete — exchange the code, mint the Connection, delete the session
         where: [{ field: "id", value: input.state }],
       });
       if (!row) {
-        return yield* Effect.fail(
+        return yield* new OAuthSessionNotFoundError({ sessionId: input.state });
-          new OAuthSessionNotFoundError({ sessionId: input.state }),
-        );
       }
       const deleteSession = deps.adapter.delete({
         model: "oauth2_session",
         where: [
           { field: "id", value: input.state },
-          { field: "scope_id", value: row.scope_id as string },
+          { field: "scope_id", value: row.scope_id },
         ],
       });
       if (input.error) {
         yield* deleteSession;
-        return yield* Effect.fail(
+        return yield* new OAuthCompleteError({
-          new OAuthCompleteError({
+          message: `Authorization server returned error: ${input.error}`,
-            message: `Authorization server returned error: ${input.error}`,
+          code: input.error,
-            code: input.error,
+        });
-          }),
-        );
       }
       if (!input.code) {
         yield* deleteSession;
-        return yield* Effect.fail(
+        return yield* new OAuthCompleteError({
-          new OAuthCompleteError({
+          message: "Missing authorization code",
-            message: "Missing authorization code",
+        });
-          }),
-        );
       }
       const expiresAt = Number(row.expires_at as number | bigint);
       if (expiresAt <= now()) {
         yield* deleteSession;
-        return yield* Effect.fail(
+        return yield* new OAuthCompleteError({
-          new OAuthCompleteError({
+          message: "OAuth session expired",
-            message: "OAuth session expired",
+        });
-          }),
-        );
       }
       const payload = decodeSessionPayload(coerceJson(row.payload));
       const endpoint = ""; // not stored on the row — the payload's own
-                          // endpoint fields drive exchange; we just need
+      // endpoint fields drive exchange; we just need
-                          // a display string for the identity label.
+      // a display string for the identity label.
-      const connectionId = row.connection_id as string;
+      const connectionId = row.connection_id;
-      const tokenScope = row.token_scope as string;
+      const tokenScope = row.token_scope;
-      const redirectUrl = row.redirect_url as string;
+      const redirectUrl = row.redirect_url;
       // Dispatch to the strategy-specific exchange.
       const exchangeResult = yield* (() => {
           case "dynamic-dcr":
             return exchangeDynamicDcr(payload, input.code, redirectUrl);
           case "authorization-code":
-            return exchangeAuthorizationCodeStrategy(
+            return exchangeAuthorizationCodeStrategy(payload, input.code, redirectUrl);
-              payload,
-              input.code,
-              redirectUrl,
-            );
         }
       })().pipe(Effect.tapError(() => deleteSession));
           .pipe(
             Effect.as(secretId),
             Effect.mapError(
-              (err) =>
+              () =>
                 new OAuthCompleteError({
-                  message: `Failed to persist DCR client_secret: ${
+                  message: "Failed to persist DCR client_secret",
-                    err instanceof Error ? err.message : String(err)
-                  }`,
                 }),
             ),
           );
         payload.kind === "dynamic-dcr"
           ? {
               kind: "dynamic-dcr",
-              tokenEndpoint: (payload.authorizationServerMetadata as {
+              tokenEndpoint: (
-                token_endpoint: string;
+                payload.authorizationServerMetadata as {
-              }).token_endpoint,
+                  token_endpoint: string;
+                }
+              ).token_endpoint,
               issuerUrl:
-                (payload.authorizationServerMetadata as { issuer?: string }).issuer ??
+                (payload.authorizationServerMetadata as { issuer?: string }).issuer ?? null,
-                null,
               authorizationServerUrl: payload.authorizationServerUrl,
-              authorizationServerMetadataUrl:
+              authorizationServerMetadataUrl: payload.authorizationServerMetadataUrl,
-                payload.authorizationServerMetadataUrl,
+              idTokenSigningAlgValuesSupported: (
-              idTokenSigningAlgValuesSupported:
+                payload.authorizationServerMetadata as {
-                (payload.authorizationServerMetadata as {
                   id_token_signing_alg_values_supported?: string[];
-                }).id_token_signing_alg_values_supported,
+                }
-              clientId: (payload.clientInformation as { client_id: string })
+              ).id_token_signing_alg_values_supported,
-                .client_id,
+              clientId: (payload.clientInformation as { client_id: string }).client_id,
               clientSecretSecretId: dynamicClientSecretSecretId,
               clientAuth:
                 (payload.clientInformation as { token_endpoint_auth_method?: string })
               : null,
             expiresAt: connectionExpiresAt,
             oauthScope: exchangeResult.tokens.scope ?? null,
-            providerState: Schema.encodeSync(OAuthProviderStateSchema)(
+            providerState: Schema.encodeSync(OAuthProviderStateSchema)(providerState) as Record<
-              providerState,
+              string,
-            ) as Record<string, unknown>,
+              unknown
+            >,
           }),
         )
         .pipe(
           Effect.mapError(
-            (err) =>
+            () =>
               new OAuthCompleteError({
-                message: `Failed to mint connection: ${
+                message: "Failed to mint connection",
-                  err instanceof Error ? err.message : String(err)
-                }`,
               }),
           ),
         );
         redirectUrl,
         codeVerifier: payload.codeVerifier,
         code,
-        idTokenSigningAlgValuesSupported:
+        idTokenSigningAlgValuesSupported: md.id_token_signing_alg_values_supported,
-          md.id_token_signing_alg_values_supported,
+        clientAuth: ci.token_endpoint_auth_method === "client_secret_basic" ? "basic" : "body",
-        clientAuth:
-          ci.token_endpoint_auth_method === "client_secret_basic"
-            ? "basic"
-            : "body",
       }).pipe(
         Effect.mapError(
           (err) =>
             new OAuthCompleteError({
-              message: `Token exchange failed: ${err.message}`,
+              message: "Token exchange failed",
               code: err.error,
             }),
         ),
       );
     payload: Extract<OAuthSessionPayload, { kind: "authorization-code" }>,
     code: string,
     redirectUrl: string,
-  ): Effect.Effect<
+  ): Effect.Effect<ExchangeResult, OAuthCompleteError | StorageFailure> =>
-    ExchangeResult,
-    OAuthCompleteError | StorageFailure
-  > =>
     Effect.gen(function* () {
       const clientId = yield* deps.secretsGet(payload.clientIdSecretId);
       if (clientId === null) {
-        return yield* Effect.fail(
+        return yield* new OAuthCompleteError({
-          new OAuthCompleteError({
+          message: `client_id secret "${payload.clientIdSecretId}" not found`,
-            message: `client_id secret "${payload.clientIdSecretId}" not found`,
+        });
-          }),
-        );
       }
       const clientSecret = payload.clientSecretSecretId
         ? yield* deps.secretsGet(payload.clientSecretSecretId)
         : null;
       if (payload.clientSecretSecretId && clientSecret === null) {
-        return yield* Effect.fail(
+        return yield* new OAuthCompleteError({
-          new OAuthCompleteError({
+          message: `client_secret secret "${payload.clientSecretSecretId}" not found`,
-            message: `client_secret secret "${payload.clientSecretSecretId}" not found`,
+        });
-          }),
-        );
       }
       const tokens = yield* exchangeAuthorizationCode({
         Effect.mapError(
           (err) =>
             new OAuthCompleteError({
-              message: `Token exchange failed: ${err.message}`,
+              message: "Token exchange failed",
               code: err.error,
             }),
         ),
       );
         model: "oauth2_session",
         where: [
           { field: "id", value: sessionId },
-          { field: "scope_id", value: row.scope_id as string },
+          { field: "scope_id", value: row.scope_id },
         ],
       });
     });
           catch: (cause) =>
             new ConnectionRefreshError({
               connectionId: input.connectionId,
-              message: `oauth2 providerState is malformed: ${
+              message: "oauth2 providerState is malformed",
-                cause instanceof Error ? cause.message : String(cause)
-              }`,
               cause,
             }),
         });
             case "dynamic-dcr":
               return Effect.gen(function* () {
                 const csec = state.clientSecretSecretId
-                  ? yield* deps
+                  ? yield* deps.secretsGet(state.clientSecretSecretId).pipe(
-                      .secretsGet(state.clientSecretSecretId)
+                      Effect.mapError(
-                      .pipe(
+                        (cause) =>
-                        Effect.mapError(
+                          new ConnectionRefreshError({
-                          (cause) =>
+                            connectionId: input.connectionId,
-                            new ConnectionRefreshError({
+                            message: "Failed to resolve DCR client_secret",
-                              connectionId: input.connectionId,
+                            cause,
-                              message: `Failed to resolve DCR client_secret: ${
+                          }),
-                                cause instanceof Error
+                      ),
-                                  ? cause.message
+                    )
-                                  : String(cause)
-                              }`,
-                              cause,
-                            }),
-                        ),
-                      )
                   : null;
                 if (state.clientSecretSecretId && csec === null) {
                   return yield* new ConnectionRefreshError({
             case "authorization-code":
             case "client-credentials":
               return Effect.gen(function* () {
-                const cid = yield* deps
+                const cid = yield* deps.secretsGet(state.clientIdSecretId).pipe(
-                  .secretsGet(state.clientIdSecretId)
+                  Effect.mapError(
-                  .pipe(
+                    (cause) =>
-                    Effect.mapError(
+                      new ConnectionRefreshError({
-                      (cause) =>
+                        connectionId: input.connectionId,
-                        new ConnectionRefreshError({
+                        message: "Failed to resolve client_id secret",
-                          connectionId: input.connectionId,
+                        cause,
-                          message: `Failed to resolve client_id secret: ${
+                      }),
-                            cause instanceof Error
+                  ),
-                              ? cause.message
+                );
-                              : String(cause)
-                          }`,
-                          cause,
-                        }),
-                    ),
-                  );
                 if (cid === null) {
                   return yield* new ConnectionRefreshError({
                     connectionId: input.connectionId,
                   });
                 }
                 const csec = state.clientSecretSecretId
-                  ? yield* deps
+                  ? yield* deps.secretsGet(state.clientSecretSecretId).pipe(
-                      .secretsGet(state.clientSecretSecretId)
+                      Effect.mapError(
-                      .pipe(
+                        (cause) =>
-                        Effect.mapError(
+                          new ConnectionRefreshError({
-                          (cause) =>
+                            connectionId: input.connectionId,
-                            new ConnectionRefreshError({
+                            message: "Failed to resolve client_secret",
-                              connectionId: input.connectionId,
+                            cause,
-                              message: `Failed to resolve client_secret: ${
+                          }),
-                                cause instanceof Error
+                      ),
-                                  ? cause.message
+                    )
-                                  : String(cause)
-                              }`,
-                              cause,
-                            }),
-                        ),
-                      )
                   : null;
                 if (state.clientSecretSecretId && csec === null) {
                   return yield* new ConnectionRefreshError({
         const tokenEndpoint = yield* (() => {
           if (state.tokenEndpoint) return Effect.succeed(state.tokenEndpoint);
-          if (
+          if (state.kind === "dynamic-dcr" && state.authorizationServerUrl) {
-            state.kind === "dynamic-dcr" &&
+            return discoverAuthorizationServerMetadata(state.authorizationServerUrl).pipe(
-            state.authorizationServerUrl
-          ) {
-            return discoverAuthorizationServerMetadata(
-              state.authorizationServerUrl,
-            ).pipe(
               Effect.flatMap((metadata) =>
                 metadata?.metadata.token_endpoint
                   ? Effect.succeed(metadata.metadata.token_endpoint)
                   : Effect.fail(
                       new ConnectionRefreshError({
                         connectionId: input.connectionId,
-                        message:
+                        message: "oauth2 legacy MCP providerState is missing token endpoint",
-                          "oauth2 legacy MCP providerState is missing token endpoint",
                         reauthRequired: true,
                       }),
                     ),
               ),
               Effect.mapError((cause) =>
-                cause instanceof ConnectionRefreshError
+                Predicate.isTagged("ConnectionRefreshError")(cause)
                   ? cause
                   : new ConnectionRefreshError({
                       connectionId: input.connectionId,
-                      message:
+                      message: "Failed to discover token endpoint for legacy MCP OAuth connection",
-                        "Failed to discover token endpoint for legacy MCP OAuth connection",
                       reauthRequired: true,
                       cause,
                     }),
           );
         })();
-        const tokens = yield* (state.kind === "client-credentials"
+        const tokens = yield* (
-          ? exchangeClientCredentials({
+          state.kind === "client-credentials"
-              tokenUrl: tokenEndpoint,
+            ? exchangeClientCredentials({
-              clientId,
+                tokenUrl: tokenEndpoint,
-              clientSecret: clientSecret ?? "",
+                clientId,
-              scopes: state.scopes,
+                clientSecret: clientSecret ?? "",
-              scopeSeparator: state.scopeSeparator,
+                scopes: state.scopes,
-              clientAuth: state.clientAuth,
+                scopeSeparator: state.scopeSeparator,
-            })
+                clientAuth: state.clientAuth,
-          : refreshAccessToken({
+              })
-              tokenUrl: tokenEndpoint,
+            : refreshAccessToken({
-              issuerUrl:
+                tokenUrl: tokenEndpoint,
-                state.kind === "dynamic-dcr" || state.kind === "authorization-code"
+                issuerUrl:
-                  ? (state.issuerUrl ?? undefined)
+                  state.kind === "dynamic-dcr" || state.kind === "authorization-code"
-                  : undefined,
+                    ? (state.issuerUrl ?? undefined)
-              clientId,
+                    : undefined,
-              clientSecret: clientSecret ?? undefined,
+                clientId,
-              refreshToken: input.refreshToken!,
+                clientSecret: clientSecret ?? undefined,
-              scopes:
+                refreshToken: input.refreshToken!,
-                state.kind === "dynamic-dcr" || state.kind === "authorization-code"
+                scopes:
-                  ? state.scopes
+                  state.kind === "dynamic-dcr" || state.kind === "authorization-code"
-                  : undefined,
+                    ? state.scopes
-              scopeSeparator:
+                    : undefined,
-                state.kind === "dynamic-dcr" || state.kind === "authorization-code"
+                scopeSeparator:
-                  ? state.scopeSeparator
+                  state.kind === "dynamic-dcr" || state.kind === "authorization-code"
-                  : undefined,
+                    ? state.scopeSeparator
-              clientAuth: state.clientAuth,
+                    : undefined,
-              idTokenSigningAlgValuesSupported:
+                clientAuth: state.clientAuth,
-                state.kind === "dynamic-dcr"
+                idTokenSigningAlgValuesSupported:
-                  ? state.idTokenSigningAlgValuesSupported
+                  state.kind === "dynamic-dcr" ? state.idTokenSigningAlgValuesSupported : undefined,
-                  : undefined,
+              })
-            })).pipe(
+        ).pipe(
           Effect.mapError(
             (err) =>
               new ConnectionRefreshError({
                 connectionId: input.connectionId,
-                message: `OAuth refresh failed: ${err.message}`,
+                message: "OAuth refresh failed",
                 // Terminal RFC 6749 §5.2 errors mean retrying won't heal it.
-                reauthRequired: err.error
+                reauthRequired: err.error ? terminalRefreshErrors.has(err.error) : false,
-                  ? terminalRefreshErrors.has(err.error)
-                  : false,
               }),
           ),
         );
         const expiresAt =
-          typeof tokens.expires_in === "number"
+          typeof tokens.expires_in === "number" ? now() + tokens.expires_in * 1000 : null;
-            ? now() + tokens.expires_in * 1000
-            : null;
         const result: ConnectionRefreshResult = {
           accessToken: tokens.access_token,
 const safeHostname = (value: string | null): string | null => {
   if (!value) return null;
-  try {
+  return parseUrlOption(value)?.host ?? value;
-    return new URL(value).host;
-  } catch {
-    return value;
-  }
 };