@codemation/host 0.6.0 → 0.7.0

package/src/credentials/CredentialOAuth2MaterialReader.ts

@@ -0,0 +1,136 @@
+import { inject, injectable } from "@codemation/core";
+import type { Clock, OAuthFlowExecutor, OAuthMaterial } from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import type { LoggerFactory } from "../application/logging/Logger";
+import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
+import type {
+  CredentialOAuth2MaterialRecord,
+  CredentialStore,
+} from "../domain/credentials/CredentialServices";
+
+/**
+ * Reads OAuth2 material for a credential instance and proactively refreshes it
+ * when the stored access token is past (or within `REFRESH_LEAD_MS` of) expiry.
+ *
+ * Why this exists: most OAuth2 consumers in the host pipe an access token to a
+ * raw HTTP call (MCP transport, webhook outbound, etc.) and have no SDK-level
+ * 401-and-refresh behaviour. Without proactive refresh, the stored token goes
+ * stale ~1h after the OAuth callback and every consumer fails with 401 until
+ * the user manually reconnects. The Gmail trigger doesn't hit this because
+ * `googleapis.OAuth2Client` refreshes internally — that's the exception, not
+ * the rule.
+ *
+ * Concurrency: a single in-flight refresh per instanceId. Concurrent reads
+ * during a refresh share the same promise so we don't invalidate the refresh
+ * token by exchanging it twice in parallel.
+ */
+@injectable()
+export class CredentialOAuth2MaterialReader {
+  private static readonly REFRESH_LEAD_MS = 60_000;
+
+  private readonly inFlightRefresh = new Map<string, Promise<OAuthMaterial>>();
+
+  constructor(
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly credentialSecretCipher: CredentialSecretCipher,
+    @inject(ApplicationTokens.OAuthFlowExecutor) private readonly oauthFlowExecutor: OAuthFlowExecutor,
+    @inject(ApplicationTokens.Clock) private readonly clock: Clock,
+    @inject(ApplicationTokens.LoggerFactory) private readonly loggers: LoggerFactory,
+  ) {}
+
+  async readMaterial(instanceId: string): Promise<OAuthMaterial> {
+    const encrypted = await this.credentialStore.getOAuth2Material(instanceId);
+    if (!encrypted) {
+      throw new Error(`CredentialOAuth2MaterialReader: instance "${instanceId}" has no OAuth2 material`);
+    }
+    const current = this.decrypt(encrypted);
+    if (!this.shouldRefresh(current)) {
+      return current;
+    }
+    return this.refreshSingleFlight(instanceId, current, encrypted);
+  }
+
+  private shouldRefresh(material: OAuthMaterial): boolean {
+    if (!material.expiresAt) return false;
+    if (!material.refreshToken) return false;
+    const expiryMs = Date.parse(material.expiresAt);
+    if (Number.isNaN(expiryMs)) return false;
+    return this.clock.now().getTime() + CredentialOAuth2MaterialReader.REFRESH_LEAD_MS >= expiryMs;
+  }
+
+  private refreshSingleFlight(
+    instanceId: string,
+    current: OAuthMaterial,
+    encrypted: CredentialOAuth2MaterialRecord,
+  ): Promise<OAuthMaterial> {
+    const inflight = this.inFlightRefresh.get(instanceId);
+    if (inflight) return inflight;
+    const next = this.doRefresh(instanceId, current, encrypted).finally(() => {
+      this.inFlightRefresh.delete(instanceId);
+    });
+    this.inFlightRefresh.set(instanceId, next);
+    return next;
+  }
+
+  private async doRefresh(
+    instanceId: string,
+    current: OAuthMaterial,
+    encrypted: CredentialOAuth2MaterialRecord,
+  ): Promise<OAuthMaterial> {
+    const logger = this.loggers.create("CredentialOAuth2MaterialReader");
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`CredentialOAuth2MaterialReader: credential instance "${instanceId}" not found`);
+    }
+    let refreshed: OAuthMaterial;
+    try {
+      refreshed = await this.oauthFlowExecutor.refresh({ typeId: instance.typeId, instanceId, material: current });
+    } catch (error) {
+      logger.warn(
+        `CredentialOAuth2MaterialReader: token refresh failed for instance "${instanceId}" — returning stale material`,
+        error instanceof Error ? error : undefined,
+      );
+      return current;
+    }
+    const reEncrypted = this.credentialSecretCipher.encrypt({
+      accessToken: refreshed.accessToken,
+      refreshToken: refreshed.refreshToken ?? null,
+      expiresAt: refreshed.expiresAt ?? null,
+      grantedScopes: refreshed.grantedScopes.join(" "),
+    });
+    await this.credentialStore.saveOAuth2Material({
+      instanceId,
+      encryptedJson: reEncrypted.encryptedJson,
+      encryptionKeyId: reEncrypted.encryptionKeyId,
+      schemaVersion: reEncrypted.schemaVersion,
+      metadata: {
+        providerId: encrypted.providerId,
+        connectedEmail: encrypted.connectedEmail,
+        connectedAt: encrypted.connectedAt,
+        scopes: [...refreshed.grantedScopes],
+        updatedAt: this.clock.now().toISOString(),
+      },
+    });
+    logger.info(`CredentialOAuth2MaterialReader: refreshed token for instance "${instanceId}"`);
+    return refreshed;
+  }
+
+  private decrypt(record: CredentialOAuth2MaterialRecord): OAuthMaterial {
+    const json = this.credentialSecretCipher.decrypt(record) as {
+      accessToken?: unknown;
+      refreshToken?: unknown;
+      expiresAt?: unknown;
+      grantedScopes?: unknown;
+    };
+    return {
+      accessToken: typeof json.accessToken === "string" ? json.accessToken : "",
+      refreshToken: typeof json.refreshToken === "string" ? json.refreshToken : undefined,
+      expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : undefined,
+      grantedScopes:
+        typeof json.grantedScopes === "string"
+          ? json.grantedScopes.split(/\s+/).filter((s) => s.length > 0)
+          : [],
+    };
+  }
+}

package/src/credentials/InternalCredentialsListRegistrar.ts

@@ -0,0 +1,48 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import { ApplicationTokens } from "../applicationTokens";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+
+/**
+ * Registers GET /internal/credentials — HMAC-verified endpoint that returns the status
+ * list of credential instances (no token material). Used by the concierge (Story 5) to
+ * inspect what credentials are connected.
+ */
+@injectable()
+export class InternalCredentialsListRegistrar implements InternalHonoApiRouteRegistrar {
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+  ) {}
+
+  register(app: Hono): void {
+    app.get("/internal/credentials", this.hmacMiddleware.handle(), async (c) => {
+      const instances = await this.credentialStore.listInstances();
+      const result = await Promise.all(
+        instances.map(async (instance) => {
+          const oauth2Material = await this.credentialStore.getOAuth2Material(instance.instanceId);
+          return {
+            instanceId: instance.instanceId,
+            typeId: instance.typeId,
+            displayName: instance.displayName,
+            setupStatus: instance.setupStatus,
+            createdAt: instance.createdAt,
+            updatedAt: instance.updatedAt,
+            oauth2: oauth2Material
+              ? {
+                  providerId: oauth2Material.providerId,
+                  connectedEmail: oauth2Material.connectedEmail,
+                  connectedAt: oauth2Material.connectedAt,
+                  scopes: oauth2Material.scopes,
+                  updatedAt: oauth2Material.updatedAt,
+                }
+              : null,
+          };
+        }),
+      );
+      return c.json(result);
+    });
+  }
+}

package/src/credentials/InternalCredentialsPushRegistrar.ts

@@ -0,0 +1,125 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import type { Logger, LoggerFactory } from "../application/logging/Logger";
+import { ApplicationTokens } from "../applicationTokens";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+import { CredentialInstanceService, CredentialTestService } from "../domain/credentials/CredentialServices";
+
+/**
+ * Body shape pushed from the control-plane OAuth broker after a successful
+ * authorization code exchange. Defined per docs/pairing-protocol.md § Token Push.
+ */
+type CredentialPushBody = Readonly<{
+  credentialInstanceId: string;
+  accessToken: string;
+  refreshToken?: string | null;
+  expiresAt: number;
+  scopesGranted: ReadonlyArray<string>;
+}>;
+
+/**
+ * Registers POST /internal/credentials/push — HMAC-verified endpoint that receives
+ * OAuth tokens from the control-plane broker and writes them to the local credential store.
+ *
+ * If `refreshToken` is null/undefined the existing one is preserved (per Story 3 open question 5).
+ */
+@injectable()
+export class InternalCredentialsPushRegistrar implements InternalHonoApiRouteRegistrar {
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly cipher: CredentialSecretCipher,
+    @inject(CredentialInstanceService) private readonly credentialInstanceService: CredentialInstanceService,
+    @inject(CredentialTestService) private readonly credentialTestService: CredentialTestService,
+    @inject(ApplicationTokens.LoggerFactory) loggerFactory: LoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("InternalCredentialsPushRegistrar");
+  }
+
+  register(app: Hono): void {
+    app.post("/internal/credentials/push", this.hmacMiddleware.handle(), async (c) => {
+      try {
+        const rawBody = c.get("body" as never) as string | undefined;
+        const body: CredentialPushBody = rawBody ? JSON.parse(rawBody) : await c.req.json();
+
+        if (!body.credentialInstanceId || typeof body.credentialInstanceId !== "string") {
+          return c.json({ error: "credentialInstanceId is required" }, 400);
+        }
+        if (!body.accessToken || typeof body.accessToken !== "string") {
+          return c.json({ error: "accessToken is required" }, 400);
+        }
+
+        const nowIso = new Date().toISOString();
+        const expiryIso =
+          typeof body.expiresAt === "number" ? new Date(body.expiresAt * 1000).toISOString() : undefined;
+
+        // Merge: if the push omits refreshToken, preserve the existing one.
+        const existingMaterial = await this.credentialStore.getOAuth2Material(body.credentialInstanceId);
+        const existingDecrypted = existingMaterial ? this.cipher.decrypt(existingMaterial) : undefined;
+        const refreshToken =
+          body.refreshToken !== undefined && body.refreshToken !== null
+            ? body.refreshToken
+            : (existingDecrypted?.refresh_token as string | undefined);
+
+        const tokenMaterial = Object.freeze({
+          access_token: body.accessToken,
+          refresh_token: refreshToken,
+          expiry: expiryIso,
+          scope: body.scopesGranted.join(" "),
+        });
+
+        const encrypted = this.cipher.encrypt(tokenMaterial);
+
+        await this.credentialStore.saveOAuth2Material({
+          instanceId: body.credentialInstanceId,
+          encryptedJson: encrypted.encryptedJson,
+          encryptionKeyId: encrypted.encryptionKeyId,
+          schemaVersion: encrypted.schemaVersion,
+          metadata: {
+            providerId: body.credentialInstanceId,
+            connectedAt: nowIso,
+            scopes: [...body.scopesGranted],
+            updatedAt: nowIso,
+          },
+        });
+
+        // Attempt to mark the credential instance as ready if it exists.
+        // Not a hard requirement — broker may push before the instance is created locally.
+        try {
+          await this.credentialInstanceService.markOAuth2Connected(body.credentialInstanceId, nowIso);
+        } catch (markError) {
+          this.logger.warn(
+            "markOAuth2Connected failed (instance may not exist locally yet)",
+            markError instanceof Error ? markError : undefined,
+          );
+        }
+
+        this.logger.info(`Credential push applied for instance ${body.credentialInstanceId}`);
+
+        // Auto-test the credential so the UI shows a real health badge
+        // (healthy / failing) instead of "untested". For the broker type
+        // this just validates the token material we just persisted, so it
+        // never makes an outbound call to the provider. Soft-fails — a bad
+        // test result shouldn't fail the push that already succeeded.
+        try {
+          await this.credentialTestService.test(body.credentialInstanceId);
+        } catch (testError) {
+          this.logger.warn(
+            `Credential auto-test failed for instance ${body.credentialInstanceId}`,
+            testError instanceof Error ? testError : undefined,
+          );
+        }
+
+        return c.json({ ok: true });
+      } catch (error) {
+        this.logger.error("Credential push handler error", error instanceof Error ? error : undefined);
+        return c.json({ error: "Internal server error" }, 500);
+      }
+    });
+  }
+}

package/src/credentials/LocalOAuthFlowExecutor.ts

@@ -0,0 +1,316 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import { inject, injectable } from "@codemation/core";
+import type {
+  Clock,
+  OAuthFlowCallbackArgs,
+  OAuthFlowExecutor,
+  OAuthFlowStartArgs,
+  OAuthFlowStartResult,
+  OAuthMaterial,
+} from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import { CredentialFieldEnvOverlayService } from "../domain/credentials/CredentialFieldEnvOverlayService";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+import { CredentialMaterialResolver } from "../domain/credentials/CredentialMaterialResolver";
+import { CredentialTypeRegistryImpl } from "../domain/credentials/CredentialTypeRegistryImpl";
+import { OAuth2ProviderRegistry } from "../domain/credentials/OAuth2ProviderRegistry";
+
+type PendingState = Readonly<{
+  stateToken: string;
+  codeVerifier: string;
+  instanceId: string;
+  typeId: string;
+  redirectUri: string;
+  expiresAt: number;
+}>;
+
+/**
+ * OAuthFlowExecutor for framework (OSS / standalone) mode.
+ *
+ * Reads clientId from the credential instance's publicConfig and clientSecret
+ * from the instance's secret material. Does NOT write tokens back — that is
+ * the responsibility of the callback route (a later story).
+ */
+@injectable()
+export class LocalOAuthFlowExecutor implements OAuthFlowExecutor {
+  private static readonly stateTtlMs = 10 * 60 * 1_000;
+
+  private readonly pendingStates = new Map<string, PendingState>();
+
+  constructor(
+    @inject(CredentialTypeRegistryImpl)
+    private readonly credentialTypeRegistry: CredentialTypeRegistryImpl,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialMaterialResolver)
+    private readonly credentialMaterialResolver: CredentialMaterialResolver,
+    @inject(OAuth2ProviderRegistry)
+    private readonly oauth2ProviderRegistry: OAuth2ProviderRegistry,
+    @inject(CredentialFieldEnvOverlayService)
+    private readonly credentialFieldEnvOverlayService: CredentialFieldEnvOverlayService,
+    @inject(ApplicationTokens.Clock)
+    private readonly clock: Clock,
+  ) {}
+
+  async start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult> {
+    const { instanceId } = args;
+    if (!instanceId) {
+      throw new Error("LocalOAuthFlowExecutor.start requires instanceId; create the credential instance first");
+    }
+
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(instance.typeId);
+    if (!credentialType) {
+      throw new Error(`LocalOAuthFlowExecutor: unknown credential type: ${instance.typeId}`);
+    }
+    if (credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${instance.typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: material } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+
+    const scopes = args.scopes.length > 0 ? [...args.scopes] : [...auth.scopes];
+
+    const stateToken = this.createOpaqueValue();
+    const codeVerifier = this.createOpaqueValue();
+    const codeChallenge = this.createPkceCodeChallenge(codeVerifier);
+
+    const nowMs = this.clock.now().getTime();
+
+    // Evict expired entries on each start call to keep the map bounded.
+    this.evictExpired(nowMs);
+
+    const expiresAt = nowMs + LocalOAuthFlowExecutor.stateTtlMs;
+    this.pendingStates.set(stateToken, {
+      stateToken,
+      codeVerifier,
+      instanceId,
+      typeId: instance.typeId,
+      redirectUri: args.redirectUri,
+      expiresAt,
+    });
+
+    // Suppress unused-variable lint for material — it's loaded to validate that the
+    // clientSecret field is present before starting the flow, but clientSecret itself is
+    // only needed at completeCallback / refresh time.
+    void material;
+
+    const url = new URL(provider.authorizeUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", clientId);
+    url.searchParams.set("redirect_uri", args.redirectUri);
+    url.searchParams.set("scope", scopes.join(" "));
+    url.searchParams.set("state", stateToken);
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("access_type", "offline");
+    url.searchParams.set("prompt", "consent");
+
+    return { consentUrl: url.toString(), stateToken };
+  }
+
+  lookupInstanceId(stateToken: string): string | undefined {
+    return this.pendingStates.get(stateToken)?.instanceId;
+  }
+
+  async completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial> {
+    const pending = this.pendingStates.get(args.stateToken);
+    if (!pending) {
+      throw new Error(`LocalOAuthFlowExecutor: state token not found or already used: ${args.stateToken}`);
+    }
+    if (this.clock.now().getTime() > pending.expiresAt) {
+      this.pendingStates.delete(args.stateToken);
+      throw new Error("LocalOAuthFlowExecutor: OAuth state token has expired");
+    }
+    this.pendingStates.delete(args.stateToken);
+
+    const instance = await this.credentialStore.getInstance(pending.instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${pending.instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(instance.typeId);
+    if (!credentialType || credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${instance.typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: material } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+    const clientSecretFieldKey = this.oauth2ProviderRegistry.resolveClientSecretFieldKey(auth);
+    const clientSecret = String(material[clientSecretFieldKey] ?? "");
+    if (!clientSecret) {
+      throw new Error(`LocalOAuthFlowExecutor: clientSecret missing from secret field "${clientSecretFieldKey}"`);
+    }
+
+    const body = this.buildFormBody({
+      grant_type: "authorization_code",
+      code: args.code,
+      code_verifier: pending.codeVerifier,
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: pending.redirectUri,
+    });
+
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const text = await response.text();
+    const json = this.parseJson(text);
+
+    if (!response.ok) {
+      const msg =
+        typeof json.error_description === "string"
+          ? json.error_description
+          : typeof json.error === "string"
+            ? json.error
+            : text || "OAuth2 token exchange failed";
+      throw new Error(`LocalOAuthFlowExecutor: token exchange failed: ${msg}`);
+    }
+
+    return this.toOAuthMaterial(json);
+  }
+
+  async refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial> {
+    const { typeId, instanceId, material } = args;
+
+    const instance = await this.credentialStore.getInstance(instanceId);
+    if (!instance) {
+      throw new Error(`LocalOAuthFlowExecutor: credential instance not found: ${instanceId}`);
+    }
+
+    const credentialType = this.credentialTypeRegistry.getCredentialType(typeId);
+    if (!credentialType || credentialType.definition.auth?.kind !== "oauth2") {
+      throw new Error(`LocalOAuthFlowExecutor: credential type ${typeId} is not an OAuth2 type`);
+    }
+
+    const auth = credentialType.definition.auth;
+    const rawMaterial = await this.credentialMaterialResolver.resolveMaterial(instance);
+    const { resolvedPublicConfig, resolvedMaterial: secretMaterial } = this.credentialFieldEnvOverlayService.apply({
+      definition: credentialType.definition,
+      publicConfig: instance.publicConfig,
+      material: rawMaterial,
+    });
+    const provider = this.oauth2ProviderRegistry.resolve(credentialType.definition, resolvedPublicConfig);
+    const clientId = this.oauth2ProviderRegistry.resolveClientId(auth, resolvedPublicConfig);
+    const clientSecretFieldKey = this.oauth2ProviderRegistry.resolveClientSecretFieldKey(auth);
+    const clientSecret = String(secretMaterial[clientSecretFieldKey] ?? "");
+    if (!clientSecret) {
+      throw new Error(`LocalOAuthFlowExecutor: clientSecret missing from secret field "${clientSecretFieldKey}"`);
+    }
+
+    if (!material.refreshToken) {
+      throw new Error("LocalOAuthFlowExecutor: no refresh token available");
+    }
+
+    const body = this.buildFormBody({
+      grant_type: "refresh_token",
+      refresh_token: material.refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret,
+    });
+
+    const response = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    const text = await response.text();
+    const json = this.parseJson(text);
+
+    if (!response.ok) {
+      const msg =
+        typeof json.error_description === "string"
+          ? json.error_description
+          : typeof json.error === "string"
+            ? json.error
+            : text || "OAuth2 refresh failed";
+      throw new Error(`LocalOAuthFlowExecutor: token refresh failed: ${msg}`);
+    }
+
+    const refreshed = this.toOAuthMaterial(json);
+    // Preserve the existing refresh token if the provider omits it from the response.
+    if (!refreshed.refreshToken) {
+      return { ...refreshed, refreshToken: material.refreshToken };
+    }
+    return refreshed;
+  }
+
+  private toOAuthMaterial(json: Record<string, unknown>): OAuthMaterial {
+    const accessToken = String(json.access_token ?? "");
+    if (!accessToken) {
+      throw new Error("LocalOAuthFlowExecutor: token response missing access_token");
+    }
+    const refreshToken =
+      typeof json.refresh_token === "string" && json.refresh_token.length > 0 ? json.refresh_token : undefined;
+    const expiresAt = this.resolveExpiresAt(json);
+    const grantedScopes =
+      typeof json.scope === "string" && json.scope.length > 0
+        ? json.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    return Object.freeze({ accessToken, refreshToken, expiresAt, grantedScopes });
+  }
+
+  private resolveExpiresAt(json: Record<string, unknown>): string | undefined {
+    const expiresIn = Number(json.expires_in);
+    if (Number.isFinite(expiresIn) && expiresIn > 0) {
+      return new Date(this.clock.now().getTime() + expiresIn * 1000).toISOString();
+    }
+    return undefined;
+  }
+
+  private parseJson(text: string): Record<string, unknown> {
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  private buildFormBody(fields: Readonly<Record<string, string>>): string {
+    return Object.entries(fields)
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join("&");
+  }
+
+  private createOpaqueValue(): string {
+    return randomBytes(32).toString("base64url");
+  }
+
+  private createPkceCodeChallenge(codeVerifier: string): string {
+    return createHash("sha256").update(codeVerifier).digest("base64url");
+  }
+
+  private evictExpired(nowMs: number): void {
+    for (const [key, entry] of this.pendingStates) {
+      if (nowMs > entry.expiresAt) {
+        this.pendingStates.delete(key);
+      }
+    }
+  }
+}