cartethyia 2.7.9 → 2.8.1

package/src/providers/authentication/oauth-client.ts

@@ -12,18 +12,20 @@ import {
   record,
 } from "./oauth-flow-store";
 import type {
+  OAuthAccountIdentity,
   OAuthAuthorizeRequest,
   OAuthCodeExchangeContext,
   OAuthExchangeResult,
   OAuthLoginClient,
 } from "./oauth-flow-store";
+import { oauthAccountIdentity } from "./oauth-flow-store";
 import type { OAuthTokenRefreshResult, OAuthTokenRefresher } from "./oauth-refresh-service";
 
 /** Minimal fetch surface accepted by the generic OAuth client. */
 export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 /** Normalized token shape returned by provider token endpoints. */
-interface NormalizedTokenResponse {
+export interface NormalizedTokenResponse extends OAuthAccountIdentity {
   readonly access: string;
   readonly refresh: string;
   readonly expiresAt: Date;
@@ -83,12 +85,32 @@ export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresh
    */
   readonly browserRedirectUri?: string;
 
+  /**
+   * Custom state generator; `undefined` keeps the shared base64url state.
+   * A provider whose authorization server validates the format (e.g. DeepAI
+   * requires 32 hex chars) overrides this.
+   */
+  generateState(): string | undefined {
+    return undefined;
+  }
+
   protected readonly fetchFn: FetchLike;
 
   constructor(fetchFn: FetchLike = globalThis.fetch) {
     this.fetchFn = fetchFn;
   }
 
+  /**
+   * Resolves the transport a flow should use. When the console injects a
+   * `fetchFn` in the flow context (device-code OAuth routed through a network
+   * pool, see `device_flow_proxy`), that override wins; otherwise the
+   * client's own fetch is used. Every start/poll/exchange request that talks
+   * to the provider MUST route through this so the override is honored.
+   */
+  protected fetchFor(context?: { readonly fetchFn?: FetchLike | undefined }): FetchLike {
+    return context?.fetchFn ?? this.fetchFn;
+  }
+
   // ---------------------------------------------------------------------------
   // Public OAuthLoginClient surface
   // ---------------------------------------------------------------------------
@@ -135,8 +157,9 @@ export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresh
   }
 
   /** Extracts an account label from a token exchange/refresh response. */
-  protected extractAccountLabel(_data: unknown): string | undefined {
-    return undefined;
+  protected extractAccountLabel(data: unknown): string | undefined {
+    const identity = oauthAccountIdentity(data);
+    return identity.accountEmail ?? identity.accountName;
   }
 
   /** Calculates an expiry Date from an `expires_in` value. */
@@ -172,7 +195,14 @@ export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresh
     const refresh = nonEmptyString(body.refresh_token) ?? fallbackRefresh ?? "";
     const expiresAt = this.calculateExpiry(body.expires_in);
     const accountLabel = this.extractAccountLabel(data);
-    return { access, refresh, expiresAt, ...(accountLabel ? { accountLabel } : {}) };
+    const identity = oauthAccountIdentity(data);
+    return {
+      access,
+      refresh,
+      expiresAt,
+      ...identity,
+      ...(accountLabel ? { accountLabel } : {}),
+    };
   }
 
   /** Builds a PKCE authorization URL using the shared helper. */
@@ -231,22 +261,26 @@ export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresh
   // ---------------------------------------------------------------------------
 
   protected toExchangeResult(normalized: NormalizedTokenResponse): OAuthExchangeResult {
-    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
+    const { access, refresh, expiresAt, accountLabel, accountEmail, accountName, auth_state } = normalized;
     return {
       access,
       refresh,
       expiresAt,
+      ...(accountEmail === undefined ? {} : { accountEmail }),
+      ...(accountName === undefined ? {} : { accountName }),
       ...(accountLabel ? { accountLabel } : {}),
       ...(auth_state === undefined ? {} : { auth_state }),
     };
   }
 
   protected toRefreshResult(normalized: NormalizedTokenResponse): OAuthTokenRefreshResult {
-    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
+    const { access, refresh, expiresAt, accountLabel, accountEmail, accountName, auth_state } = normalized;
     return {
       access,
       ...(refresh ? { refresh } : {}),
       expiresAt,
+      ...(accountEmail === undefined ? {} : { accountEmail }),
+      ...(accountName === undefined ? {} : { accountName }),
       ...(accountLabel ? { accountLabel } : {}),
       ...(auth_state === undefined ? {} : { auth_state }),
     };

package/src/providers/authentication/oauth-device-flow.ts

@@ -8,8 +8,9 @@ import type {
   OAuthDeviceFlowContext,
   OAuthDevicePollResult,
   OAuthDeviceStartResult,
+  OAuthExchangeResult,
 } from "./oauth-flow-store";
-import { OAuthClient } from "./oauth-client";
+import { OAuthClient, type NormalizedTokenResponse } from "./oauth-client";
 
 /** Configuration for standard device-code start and poll requests. */
 export interface DeviceFlowConfig {
@@ -36,9 +37,12 @@ export abstract class OAuthDeviceFlow extends OAuthClient {
   }
 
   /** Standard device-authorization start. Override the body builder for custom providers. */
-  protected async startGenericDeviceAuth(config: DeviceFlowConfig): Promise<OAuthDeviceStartResult> {
+  protected async startGenericDeviceAuth(
+    config: DeviceFlowConfig,
+    context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDeviceStartResult> {
     const body = this.buildDeviceStartBody(config);
-    const response = await this.fetchFn(config.deviceAuthUrl, {
+    const response = await this.fetchFor(context)(config.deviceAuthUrl, {
       method: "POST",
       ...(config.formHeaders === undefined ? {} : { headers: config.formHeaders }),
       body,
@@ -67,12 +71,65 @@ export abstract class OAuthDeviceFlow extends OAuthClient {
     return new URLSearchParams(params);
   }
 
+  /**
+   * Optional verdict computed from the parsed token body before the status
+   * code is considered. Defaults to undefined (continue with standard
+   * handling). A provider whose authoritative endpoint states the poll state
+   * in the body on any status can return a backoff verdict here — e.g. Grok,
+   * which votes on `error` before the HTTP status.
+   */
+  protected preVerdict?(_payload: unknown): OAuthDevicePollResult | undefined;
+
+  /**
+   * Post-success hook for the standard device-token poll.
+   *
+   * Receives the raw token response payload and the normalized parsed token.
+   * Returns the exchange result to complete with, or a verdict (typically
+   * `failed`) instead. The default reproduces the generic behavior exactly.
+   * Errors thrown by a hook are converted to a `failed` verdict by
+   * `pollGenericDeviceAuth`, keeping the poll contract (verdicts, never
+   * throws).
+   */
+  protected afterDeviceTokenExchange?(
+    _payload: unknown,
+    _normalized: NormalizedTokenResponse,
+  ): OAuthExchangeResult | OAuthDevicePollResult | Promise<OAuthExchangeResult | OAuthDevicePollResult>;
+
+  /**
+   * Failure reason for a non-JSON token body. Defaults to the generic
+   * phrasing; providers whose wire carries a distinct message override it.
+   */
+  protected unparsablePollReason(status: number): string {
+    return `device polling failed (${status})`;
+  }
+
+  /**
+   * Failure reason for a non-OK token response. The default preserves the
+   * generic behavior: the response's `error` field names the reason on the
+   * RFC 8628 400/428 statuses, and every other non-OK status gets the generic
+   * phrasing (the body is not trusted there).
+   */
+  protected pollFailureReason(
+    status: number,
+    errorKey: string | undefined,
+    _errorDescription: string | undefined,
+  ): string {
+    if (status === 400 || status === 428) return errorKey || `device polling failed (${status})`;
+    return `device polling failed (${status})`;
+  }
+
+  /** Failure reason when a token response omits `access_token`. */
+  protected missingTokenReason(_errorKey: string | undefined, _errorDescription: string | undefined): string {
+    return `${this.providerLabel} token response omitted access_token`;
+  }
+
   /** Standard device-token poll. Returns pending while authorization is incomplete. */
   protected async pollGenericDeviceAuth(
     deviceAuthId: string,
     config: DeviceFlowConfig,
+    context?: OAuthDeviceFlowContext,
   ): Promise<OAuthDevicePollResult> {
-    const response = await this.fetchFn(config.tokenUrl, {
+    const response = await this.fetchFor(context)(config.tokenUrl, {
       method: "POST",
       ...(config.formHeaders === undefined ? {} : { headers: config.formHeaders }),
       body: new URLSearchParams({
@@ -88,20 +145,57 @@ export abstract class OAuthDeviceFlow extends OAuthClient {
     } catch {
       payload = undefined;
     }
+    // A body that is not JSON is a failed poll regardless of status: verdicts
+    // must never throw, and the reason below lets providers keep their own
+    // phrasing (e.g. Grok's "returned invalid JSON").
+    if (payload === undefined) {
+      return { status: "failed", reason: this.unparsablePollReason(response.status) };
+    }
     const root = record(payload) ?? {};
+    if (this.preVerdict) {
+      const verdict = this.preVerdict(payload);
+      if (verdict !== undefined) return verdict;
+    }
+    const errorKey = typeof root.error === "string" ? root.error : undefined;
+    const errorDescription = typeof root.error_description === "string" ? root.error_description : undefined;
     if (response.status === 400 || response.status === 428) {
-      const err = typeof root.error === "string" ? root.error : "";
-      const verdict = devicePollBackoff(err, root.interval);
+      const verdict = devicePollBackoff(errorKey, root.interval);
       if (verdict !== undefined) return verdict;
-      return { status: "failed", reason: err || `device polling failed (${response.status})` };
+      return {
+        status: "failed",
+        reason: this.pollFailureReason(response.status, errorKey, errorDescription),
+      };
     }
-    if (!response.ok || payload === undefined) {
-      return { status: "failed", reason: `device polling failed (${response.status})` };
+    if (!response.ok) {
+      return { status: "failed", reason: this.pollFailureReason(response.status, errorKey, errorDescription) };
     }
     if (typeof root.access_token !== "string" || !root.access_token) {
-      return { status: "failed", reason: `${this.providerLabel} token response omitted access_token` };
+      return {
+        status: "failed",
+        reason: this.missingTokenReason(errorKey, errorDescription),
+      };
+    }
+    let normalized: NormalizedTokenResponse;
+    try {
+      normalized = this.parseTokenResponse(payload);
+    } catch (error) {
+      return {
+        status: "failed",
+        reason: error instanceof Error ? error.message : `${this.providerLabel} token response omitted access_token`,
+      };
+    }
+    if (this.afterDeviceTokenExchange) {
+      try {
+        const hooked = await this.afterDeviceTokenExchange(payload, normalized);
+        if ("status" in hooked) return hooked;
+        return { status: "complete", result: hooked };
+      } catch (error) {
+        return {
+          status: "failed",
+          reason: error instanceof Error ? error.message : `${this.providerLabel} authentication failed`,
+        };
+      }
     }
-    const normalized = this.parseTokenResponse(payload);
     return { status: "complete", result: this.toExchangeResult(normalized) };
   }
 }

package/src/providers/authentication/oauth-flow-store.ts

@@ -29,7 +29,15 @@ export interface OAuthCodeExchangeContext {
   readonly providerState?: string;
 }
 
-export interface OAuthExchangeResult {
+/** Structured identity an OAuth token response exposed at login or polling time. */
+export interface OAuthAccountIdentity {
+  /** Human-readable name or username, when the provider exposes one. */
+  readonly accountName?: string;
+  /** Primary email, when the provider exposes one. */
+  readonly accountEmail?: string;
+}
+
+export interface OAuthExchangeResult extends OAuthAccountIdentity {
   readonly access: string;
   readonly refresh: string;
   readonly expiresAt: Date;
@@ -75,8 +83,20 @@ export interface OAuthDeviceFlowContext {
    * needs none ignores it.
    */
   readonly parameters?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Transport override for the device-authorization and token-poll requests.
+   * When supplied, the client MUST use it instead of its default fetch — the
+   * console injects a pool-routed or direct validated fetch here (see the
+   * `device_flow_proxy` routing setting). Providers that ignore it keep
+   * dialing from the gateway's own egress, which is what made multiple device
+   * codes appear to arrive from one IP.
+   */
+  readonly fetchFn?: FetchLike | undefined;
 }
 
+/** Minimal fetch surface accepted by the OAuth flow contracts. */
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
 export type OAuthDevicePollResult =
   /**
    * Still waiting on the user. `retryAfterSeconds` carries the server's
@@ -112,6 +132,12 @@ export interface OAuthLoginClient {
    * compares it against the one the authorize step sent.
    */
   readonly browserRedirectUri?: string;
+  /**
+   * Custom OAuth state generator for providers whose authorization server
+   * validates the `state` format (e.g. DeepAI accepts only 32 hex chars).
+   * Defaults to the shared base64url state when omitted.
+   */
+  generateState?(): string | undefined;
   prepareAuthorize?(request: OAuthAuthorizeRequest): Promise<OAuthAuthorizeRequest>;
   /** Browser-code clients only; device-only clients omit both. */
   buildAuthorizeUrl?(request: OAuthAuthorizeRequest): string;
@@ -425,6 +451,61 @@ export function decodeJwtPayload(token: string): Record<string, unknown> | undef
   }
 }
 
+/** Trim a text value from an untrusted token response without accepting other types. */
+function identityText(value: unknown): string | undefined {
+  const trimmed = nonEmptyTrimmedString(value);
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+function firstIdentityText(
+  source: Record<string, unknown> | undefined,
+  fields: readonly string[],
+): string | undefined {
+  if (source === undefined) return undefined;
+  for (const field of fields) {
+    const value = identityText(source[field]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Reads identity from the token response shapes shared by WorkOS and the donor
+ * OAuth integrations. A provider that exposes only an id gets a display name,
+ * never an invented email; a response with neither leaves every field absent.
+ */
+export function oauthAccountIdentity(payload: unknown): OAuthAccountIdentity {
+  const root = record(payload);
+  if (root === undefined) return {};
+  const sources = [
+    root,
+    record(root.data),
+    record(root.user),
+    record(root.userInfo),
+    record(record(root.data)?.user),
+    record(record(root.data)?.userInfo),
+    decodeJwtPayload(identityText(root.access_token) ?? identityText(root.accessToken) ?? ""),
+  ].filter((value): value is Record<string, unknown> => value !== undefined);
+  const email = sources
+    .map((source) => firstIdentityText(source, ["email", "userEmail", "preferred_username", "upn"]))
+    .find((value): value is string => value !== undefined);
+  const name = sources
+    .map((source) => firstIdentityText(source, ["name", "displayName", "nickname", "username", "login"]))
+    .find((value): value is string => value !== undefined);
+  const firstName = sources
+    .map((source) => firstIdentityText(source, ["firstName", "first_name", "given_name"]))
+    .find((value): value is string => value !== undefined);
+  const lastName = sources
+    .map((source) => firstIdentityText(source, ["lastName", "last_name", "family_name"]))
+    .find((value): value is string => value !== undefined);
+  const fullName = [firstName, lastName].filter((part): part is string => part !== undefined).join(" ").trim();
+  const accountName = name ?? (fullName.length > 0 ? fullName : undefined);
+  return {
+    ...(email === undefined ? {} : { accountEmail: email }),
+    ...(accountName === undefined ? {} : { accountName }),
+  };
+}
+
 /**
  * Builds a PKCE authorization URL with the canonical parameter order
  * (`client_id`, `response_type`, `redirect_uri`, `scope`, `state`,