cartethyia 2.7.4 → 2.7.5

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

@@ -1,253 +1,254 @@
-/**
- * Generic OAuth 2.0 base class for provider-specific OAuth clients.
- *
- * Encapsulates common PKCE, device-code, token-exchange and refresh logic
- * while exposing protected hooks for provider-specific customizations.
- */
-import {
-  buildPkceAuthorizeUrl as buildPkceAuthorizeUrlShared,
-  nonEmptyString,
-  postFormTokenRequest,
-  record,
-} from "./oauth-flow-store";
-import type {
-  OAuthAuthorizeRequest,
-  OAuthCodeExchangeContext,
-  OAuthExchangeResult,
-  OAuthLoginClient,
-} 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 {
-  readonly access: string;
-  readonly refresh: string;
-  readonly expiresAt: Date;
-  readonly accountLabel?: string | undefined;
-  /**
-   * Identity the flow learned beside the tokens — an upstream user id the
-   * token itself does not carry. Threaded through both converters so a
-   * provider that resolves it during login does not lose it on the way to
-   * storage, and can refresh it later without a second round trip.
-   */
-  readonly auth_state?: Readonly<Record<string, unknown>> | undefined;
-}
-
-/** Options for building a PKCE authorize URL. */
-interface PkceAuthorizeOptions {
-  readonly clientId: string;
-  readonly authorizeUrl: string;
-  readonly redirectUri: string;
-  readonly scope: string;
-  readonly state: string;
-  readonly codeChallenge: string;
-  readonly extra?: Record<string, string> | undefined;
-}
-
-/** Options for a form-encoded token exchange or refresh. */
-interface FormTokenOptions {
-  readonly url: string;
-  readonly params: Record<string, string>;
-  readonly headers?: Record<string, string>;
-  readonly signal?: AbortSignal;
-  readonly label: string;
-}
-
-
-/** Base class for provider OAuth clients. */
-export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresher {
-  /** Provider display label used in error messages. */
-  protected abstract readonly providerLabel: string;
-  /** OAuth client id. */
-  protected abstract readonly clientId: string;
-  /** Token endpoint URL. */
-  protected abstract readonly tokenUrl: string;
-  /** Authorization endpoint URL (omit for device-only providers). */
-  protected readonly authorizeUrl?: string;
-  /** Space-separated OAuth scopes. */
-  protected abstract readonly scopes: string;
-
-  /** Whether the provider supports the device-code flow. */
-  abstract readonly supportsDeviceCode: boolean;
-  /** Whether the provider supports browser PKCE authorization. */
-  abstract readonly supportsBrowserCode: boolean;
-  /**
-   * Loopback/native redirect URI this client's authorization server
-   * allowlists, when it differs from the gateway-wide default. Declared here so
-   * a client can state it without the console route reaching into provider
-   * specifics; see `OAuthLoginClient.browserRedirectUri`.
-   */
-  readonly browserRedirectUri?: string;
-
-  protected readonly fetchFn: FetchLike;
-
-  constructor(fetchFn: FetchLike = globalThis.fetch) {
-    this.fetchFn = fetchFn;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Public OAuthLoginClient surface
-  // ---------------------------------------------------------------------------
-
-  buildAuthorizeUrl(request: OAuthAuthorizeRequest): string {
-    if (!this.authorizeUrl) {
-      throw new Error(`${this.providerLabel} does not support browser authorization`);
-    }
-    return this.buildPkceAuthorizeUrl({
-      clientId: this.clientId,
-      authorizeUrl: this.authorizeUrl,
-      redirectUri: request.redirectUri,
-      scope: this.scopes,
-      state: request.state,
-      codeChallenge: request.codeChallenge,
-      extra: this.extraAuthorizeParams(),
-    });
-  }
-
-  async exchangeCode(
-    code: string,
-    codeVerifier: string,
-    redirectUri: string,
-    _state?: string,
-    _context?: OAuthCodeExchangeContext,
-  ): Promise<OAuthExchangeResult> {
-    if (!this.supportsBrowserCode) {
-      throw new Error(`${this.providerLabel} does not support browser code exchange`);
-    }
-    return this.exchangeCodeVia(code, codeVerifier, redirectUri);
-  }
-
-  refresh(_refreshToken: string, _signal?: AbortSignal): Promise<OAuthTokenRefreshResult> {
-    throw new Error(`${this.providerLabel} does not support token refresh`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Protected hooks
-  // ---------------------------------------------------------------------------
-
-  /** Extra query parameters appended to the PKCE authorize URL. */
-  protected extraAuthorizeParams(): Record<string, string> | undefined {
-    return undefined;
-  }
-
-  /** Extracts an account label from a token exchange/refresh response. */
-  protected extractAccountLabel(_data: unknown): string | undefined {
-    return undefined;
-  }
-
-  /** Calculates an expiry Date from an `expires_in` value. */
-  protected calculateExpiry(expiresIn: unknown, fallbackSeconds = 3600): Date {
-    const seconds =
-      typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn >= 0
-        ? expiresIn
-        : fallbackSeconds;
-    return new Date(Date.now() + Math.max(0, seconds) * 1000);
-  }
-
-  /**
-   * Parses a standard token response object into a normalized result.
-   *
-   * Fails when the response carries no `access_token`. Returning an empty
-   * access value instead let a poll report `complete` with an unusable
-   * credential: the account was persisted and the browser saw success, while
-   * the gateway then dispatched with an empty bearer. A token endpoint that
-   * answers 2xx without a token is a failure, whatever the status code says —
-   * an `error` field in a 200 body is exactly that case. An empty refresh
-   * token is still allowed, because several providers legitimately issue an
-   * access-only credential.
-   */
-  protected parseTokenResponse(data: unknown, fallbackRefresh?: string): NormalizedTokenResponse {
-    const body = record(data) ?? {};
-    const access = nonEmptyString(body.access_token);
-    if (access === undefined) {
-      const detail = nonEmptyString(body.error_description) ?? nonEmptyString(body.error);
-      throw new Error(
-        `${this.providerLabel} token response omitted access_token${detail === undefined ? "" : `: ${detail}`}`,
-      );
-    }
-    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 } : {}) };
-  }
-
-  /** Builds a PKCE authorization URL using the shared helper. */
-  protected buildPkceAuthorizeUrl(options: PkceAuthorizeOptions): string {
-    return buildPkceAuthorizeUrlShared({
-      clientId: options.clientId,
-      authorizeUrl: options.authorizeUrl,
-      redirectUri: options.redirectUri,
-      scope: options.scope,
-      state: options.state,
-      codeChallenge: options.codeChallenge,
-      ...(options.extra === undefined ? {} : { extra: options.extra }),
-    });
-  }
-
-  // ---------------------------------------------------------------------------
-  // Shared token request helpers
-  // ---------------------------------------------------------------------------
-
-  protected async postFormToken(options: FormTokenOptions): Promise<unknown> {
-    return postFormTokenRequest({
-      url: options.url,
-      fetchFn: this.fetchFn,
-      params: options.params,
-      ...(options.headers === undefined ? {} : { headers: options.headers }),
-      ...(options.signal === undefined ? {} : { signal: options.signal }),
-      label: options.label,
-    });
-  }
-
-  /** Exchanges a browser authorization code using an explicit callback redirect. */
-  protected async exchangeCodeVia(
-    code: string,
-    codeVerifier: string,
-    redirectUri: string,
-    extraParams: Record<string, string> = {},
-  ): Promise<OAuthExchangeResult> {
-    const response = await this.postFormToken({
-      url: this.tokenUrl,
-      params: {
-        client_id: this.clientId,
-        grant_type: "authorization_code",
-        code,
-        redirect_uri: redirectUri,
-        code_verifier: codeVerifier,
-        ...extraParams,
-      },
-      label: `${this.providerLabel} token exchange`,
-    });
-    return this.toExchangeResult(this.parseTokenResponse(response));
-  }
-
-
-  // ---------------------------------------------------------------------------
-  // Converters
-  // ---------------------------------------------------------------------------
-
-  protected toExchangeResult(normalized: NormalizedTokenResponse): OAuthExchangeResult {
-    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
-    return {
-      access,
-      refresh,
-      expiresAt,
-      ...(accountLabel ? { accountLabel } : {}),
-      ...(auth_state === undefined ? {} : { auth_state }),
-    };
-  }
-
-  protected toRefreshResult(normalized: NormalizedTokenResponse): OAuthTokenRefreshResult {
-    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
-    return {
-      access,
-      ...(refresh ? { refresh } : {}),
-      expiresAt,
-      ...(accountLabel ? { accountLabel } : {}),
-      ...(auth_state === undefined ? {} : { auth_state }),
-    };
-  }
-}
+/**
+ * Generic OAuth 2.0 base class for provider-specific OAuth clients.
+ *
+ * Encapsulates common PKCE, device-code, token-exchange and refresh logic
+ * while exposing protected hooks for provider-specific customizations.
+ */
+import {
+  buildPkceAuthorizeUrl as buildPkceAuthorizeUrlShared,
+  expiryFromSeconds,
+  nonEmptyString,
+  postFormTokenRequest,
+  record,
+} from "./oauth-flow-store";
+import type {
+  OAuthAuthorizeRequest,
+  OAuthCodeExchangeContext,
+  OAuthExchangeResult,
+  OAuthLoginClient,
+} 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 {
+  readonly access: string;
+  readonly refresh: string;
+  readonly expiresAt: Date;
+  readonly accountLabel?: string | undefined;
+  /**
+   * Identity the flow learned beside the tokens — an upstream user id the
+   * token itself does not carry. Threaded through both converters so a
+   * provider that resolves it during login does not lose it on the way to
+   * storage, and can refresh it later without a second round trip.
+   */
+  readonly auth_state?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** Options for building a PKCE authorize URL. */
+interface PkceAuthorizeOptions {
+  readonly clientId: string;
+  readonly authorizeUrl: string;
+  readonly redirectUri: string;
+  readonly scope: string;
+  readonly state: string;
+  readonly codeChallenge: string;
+  readonly extra?: Record<string, string> | undefined;
+}
+
+/** Options for a form-encoded token exchange or refresh. */
+interface FormTokenOptions {
+  readonly url: string;
+  readonly params: Record<string, string>;
+  readonly headers?: Record<string, string>;
+  readonly signal?: AbortSignal;
+  readonly label: string;
+}
+
+
+/** Base class for provider OAuth clients. */
+export abstract class OAuthClient implements OAuthLoginClient, OAuthTokenRefresher {
+  /** Provider display label used in error messages. */
+  protected abstract readonly providerLabel: string;
+  /** OAuth client id. */
+  protected abstract readonly clientId: string;
+  /** Token endpoint URL. */
+  protected abstract readonly tokenUrl: string;
+  /** Authorization endpoint URL (omit for device-only providers). */
+  protected readonly authorizeUrl?: string;
+  /** Space-separated OAuth scopes. */
+  protected abstract readonly scopes: string;
+
+  /** Whether the provider supports the device-code flow. */
+  abstract readonly supportsDeviceCode: boolean;
+  /** Whether the provider supports browser PKCE authorization. */
+  abstract readonly supportsBrowserCode: boolean;
+  /**
+   * Loopback/native redirect URI this client's authorization server
+   * allowlists, when it differs from the gateway-wide default. Declared here so
+   * a client can state it without the console route reaching into provider
+   * specifics; see `OAuthLoginClient.browserRedirectUri`.
+   */
+  readonly browserRedirectUri?: string;
+
+  protected readonly fetchFn: FetchLike;
+
+  constructor(fetchFn: FetchLike = globalThis.fetch) {
+    this.fetchFn = fetchFn;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public OAuthLoginClient surface
+  // ---------------------------------------------------------------------------
+
+  buildAuthorizeUrl(request: OAuthAuthorizeRequest): string {
+    if (!this.authorizeUrl) {
+      throw new Error(`${this.providerLabel} does not support browser authorization`);
+    }
+    return this.buildPkceAuthorizeUrl({
+      clientId: this.clientId,
+      authorizeUrl: this.authorizeUrl,
+      redirectUri: request.redirectUri,
+      scope: this.scopes,
+      state: request.state,
+      codeChallenge: request.codeChallenge,
+      extra: this.extraAuthorizeParams(),
+    });
+  }
+
+  async exchangeCode(
+    code: string,
+    codeVerifier: string,
+    redirectUri: string,
+    _state?: string,
+    _context?: OAuthCodeExchangeContext,
+  ): Promise<OAuthExchangeResult> {
+    if (!this.supportsBrowserCode) {
+      throw new Error(`${this.providerLabel} does not support browser code exchange`);
+    }
+    return this.exchangeCodeVia(code, codeVerifier, redirectUri);
+  }
+
+  refresh(_refreshToken: string, _signal?: AbortSignal): Promise<OAuthTokenRefreshResult> {
+    throw new Error(`${this.providerLabel} does not support token refresh`);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Protected hooks
+  // ---------------------------------------------------------------------------
+
+  /** Extra query parameters appended to the PKCE authorize URL. */
+  protected extraAuthorizeParams(): Record<string, string> | undefined {
+    return undefined;
+  }
+
+  /** Extracts an account label from a token exchange/refresh response. */
+  protected extractAccountLabel(_data: unknown): string | undefined {
+    return undefined;
+  }
+
+  /** Calculates an expiry Date from an `expires_in` value. */
+  protected calculateExpiry(expiresIn: unknown, fallbackSeconds = 3600): Date {
+    const seconds =
+      typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn >= 0
+        ? expiresIn
+        : fallbackSeconds;
+    return expiryFromSeconds(seconds);
+  }
+
+  /**
+   * Parses a standard token response object into a normalized result.
+   *
+   * Fails when the response carries no `access_token`. Returning an empty
+   * access value instead let a poll report `complete` with an unusable
+   * credential: the account was persisted and the browser saw success, while
+   * the gateway then dispatched with an empty bearer. A token endpoint that
+   * answers 2xx without a token is a failure, whatever the status code says —
+   * an `error` field in a 200 body is exactly that case. An empty refresh
+   * token is still allowed, because several providers legitimately issue an
+   * access-only credential.
+   */
+  protected parseTokenResponse(data: unknown, fallbackRefresh?: string): NormalizedTokenResponse {
+    const body = record(data) ?? {};
+    const access = nonEmptyString(body.access_token);
+    if (access === undefined) {
+      const detail = nonEmptyString(body.error_description) ?? nonEmptyString(body.error);
+      throw new Error(
+        `${this.providerLabel} token response omitted access_token${detail === undefined ? "" : `: ${detail}`}`,
+      );
+    }
+    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 } : {}) };
+  }
+
+  /** Builds a PKCE authorization URL using the shared helper. */
+  protected buildPkceAuthorizeUrl(options: PkceAuthorizeOptions): string {
+    return buildPkceAuthorizeUrlShared({
+      clientId: options.clientId,
+      authorizeUrl: options.authorizeUrl,
+      redirectUri: options.redirectUri,
+      scope: options.scope,
+      state: options.state,
+      codeChallenge: options.codeChallenge,
+      ...(options.extra === undefined ? {} : { extra: options.extra }),
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Shared token request helpers
+  // ---------------------------------------------------------------------------
+
+  protected async postFormToken(options: FormTokenOptions): Promise<unknown> {
+    return postFormTokenRequest({
+      url: options.url,
+      fetchFn: this.fetchFn,
+      params: options.params,
+      ...(options.headers === undefined ? {} : { headers: options.headers }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      label: options.label,
+    });
+  }
+
+  /** Exchanges a browser authorization code using an explicit callback redirect. */
+  protected async exchangeCodeVia(
+    code: string,
+    codeVerifier: string,
+    redirectUri: string,
+    extraParams: Record<string, string> = {},
+  ): Promise<OAuthExchangeResult> {
+    const response = await this.postFormToken({
+      url: this.tokenUrl,
+      params: {
+        client_id: this.clientId,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+        ...extraParams,
+      },
+      label: `${this.providerLabel} token exchange`,
+    });
+    return this.toExchangeResult(this.parseTokenResponse(response));
+  }
+
+
+  // ---------------------------------------------------------------------------
+  // Converters
+  // ---------------------------------------------------------------------------
+
+  protected toExchangeResult(normalized: NormalizedTokenResponse): OAuthExchangeResult {
+    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
+    return {
+      access,
+      refresh,
+      expiresAt,
+      ...(accountLabel ? { accountLabel } : {}),
+      ...(auth_state === undefined ? {} : { auth_state }),
+    };
+  }
+
+  protected toRefreshResult(normalized: NormalizedTokenResponse): OAuthTokenRefreshResult {
+    const { access, refresh, expiresAt, accountLabel, auth_state } = normalized;
+    return {
+      access,
+      ...(refresh ? { refresh } : {}),
+      expiresAt,
+      ...(accountLabel ? { accountLabel } : {}),
+      ...(auth_state === undefined ? {} : { auth_state }),
+    };
+  }
+}

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

@@ -25,6 +25,8 @@ export interface OAuthAuthorizeRequest {
 export interface OAuthCodeExchangeContext {
   readonly state?: string;
   readonly parameters?: Readonly<Record<string, string>>;
+  /** Server-side provider continuation state for a multi-step browser login. */
+  readonly providerState?: string;
 }
 
 export interface OAuthExchangeResult {
@@ -197,6 +199,8 @@ const DEFAULT_DEVICE_EXPIRY_SECONDS = 900;
  * so each caller keeps its own error text. Missing or non-positive
  * `interval`/`expires_in` fall back to the caller's defaults (or the shared
  * ones); present values are floored at one second.
+ * Both wire shapes are accepted: the RFC snake_case (`device_code`) and the
+ * AWS SSO OIDC camelCase (`deviceCode`), which Kiro's OIDC device flow speaks.
  */
 export function parseDeviceAuthStart(
   payload: unknown,
@@ -204,10 +208,17 @@ export function parseDeviceAuthStart(
 ): DeviceAuthStart | undefined {
   const root = record(payload);
   if (!root) return undefined;
-  const deviceCode = nonEmptyTrimmedString(root.device_code);
-  const userCode = nonEmptyTrimmedString(root.user_code);
-  const complete = nonEmptyTrimmedString(root.verification_uri_complete);
-  const verificationUri = nonEmptyTrimmedString(root.verification_uri) ?? complete;
+  const deviceCode =
+    nonEmptyTrimmedString(root.device_code) ?? nonEmptyTrimmedString(root.deviceCode);
+  const userCode =
+    nonEmptyTrimmedString(root.user_code) ?? nonEmptyTrimmedString(root.userCode);
+  const complete =
+    nonEmptyTrimmedString(root.verification_uri_complete) ??
+    nonEmptyTrimmedString(root.verificationUriComplete);
+  const verificationUri =
+    nonEmptyTrimmedString(root.verification_uri) ??
+    nonEmptyTrimmedString(root.verificationUri) ??
+    complete;
   if (!deviceCode || !userCode || !verificationUri) return undefined;
   return {
     deviceCode,
@@ -219,7 +230,7 @@ export function parseDeviceAuthStart(
       defaults?.intervalSeconds ?? DEFAULT_DEVICE_INTERVAL_SECONDS,
     ),
     expiresInSeconds: positiveSeconds(
-      root.expires_in,
+      root.expires_in ?? root.expiresIn,
       defaults?.expiresInSeconds ?? DEFAULT_DEVICE_EXPIRY_SECONDS,
     ),
   };
@@ -236,12 +247,12 @@ function positiveSeconds(value: unknown, fallbackSeconds: number): number {
  * True when a device-token poll error means "keep polling": the user has not
  * approved yet, or the client is polling faster than the server allows.
  */
-export function isDevicePollPending(error: string | undefined): boolean {
+function isDevicePollPending(error: string | undefined): boolean {
   return error === "authorization_pending";
 }
 
 /** RFC 8628 `slow_down`: the client must widen its polling interval. */
-export function isDevicePollSlowDown(error: string | undefined): boolean {
+function isDevicePollSlowDown(error: string | undefined): boolean {
   return error === "slow_down";
 }
 
@@ -498,6 +509,8 @@ export interface OAuthFlowStorage {
   savePending(state: string, flow: PendingOAuthFlow): Promise<void>;
   consumePendingByProvider(providerId: string): Promise<PendingOAuthFlow | undefined>;
   consumePending(state: string): Promise<PendingOAuthFlow | undefined>;
+  /** Reads a pending flow without consuming it (for a retry-safe callback path). */
+  peekPending(state: string): Promise<PendingOAuthFlow | undefined>;
   saveDevice(deviceAuthId: string, correlation: DeviceFlowCorrelation): Promise<void>;
   getDevice(deviceAuthId: string): Promise<DeviceFlowCorrelation | undefined>;
   deleteDevice(deviceAuthId: string): Promise<void>;
@@ -588,6 +601,17 @@ export class OAuthFlowStore implements OAuthFlowStorage {
     }
   }
 
+  /** Reads a pending flow without consuming it — used to replay a callback. */
+  async peekPending(state: string): Promise<PendingOAuthFlow | undefined> {
+    const raw = await this.#redis.get(PENDING_PREFIX + state);
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as PendingOAuthFlow;
+    } catch {
+      return undefined;
+    }
+  }
+
   // ---------------------------------------------------------- Device correlation
 
   async saveDevice(deviceAuthId: string, correlation: DeviceFlowCorrelation): Promise<void> {
@@ -691,6 +715,17 @@ export class InMemoryOAuthFlowStore implements OAuthFlowStorage {
     }
   }
 
+  /** Reads a pending flow without consuming it — used to replay a callback. */
+  async peekPending(state: string): Promise<PendingOAuthFlow | undefined> {
+    const raw = this.pending.get(PENDING_PREFIX + state);
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as PendingOAuthFlow;
+    } catch {
+      return undefined;
+    }
+  }
+
   async saveDevice(deviceAuthId: string, correlation: DeviceFlowCorrelation): Promise<void> {
     this.devices.set(DEVICE_PREFIX + deviceAuthId, JSON.stringify(correlation));
   }