@cartanova/qgrid-cli 2.10.10 → 2.11.1

package/bundle/src/utils/providers/grok/grok-refresh.ts

@@ -0,0 +1,325 @@
+// Grok (xAI) token refresh: single-flight per token, early refresh with a stable per-account
+// jitter, refresh-token retention when the IdP does not rotate, persist-before-resolve.
+// Mechanism follows grok-build 1.0.45 xai-grok-login/src (oidc/protocol.rs:413-520,
+// oidc/refresh.rs:21-27,260-264, model.rs:9). grok-build retries transient failures in place
+// (3 attempts); qgrid does not, because the dispatcher owns the per-request attempt budget.
+import { createHash } from "node:crypto";
+
+import { getLogger } from "@logtape/logtape";
+
+import { grokShellUserAgent } from "./grok-headers";
+import {
+  type GrokFetch,
+  GrokTokenResponse,
+  getGrokOAuthEndpoints,
+  readGrokOAuthErrorCode,
+} from "./grok-oauth";
+import {
+  GrokCredentials,
+  type GrokRefreshResult,
+  type GrokRefresher,
+  type GrokTokenRef,
+  decodeGrokJwt,
+} from "./grok-types";
+
+const logger = getLogger(["qgrid", "grok-refresh"]);
+
+/** model.rs:9 DEFAULT_EARLY_INVALIDATION_SECS. */
+export const GROK_REFRESH_MARGIN_MS = 300_000;
+
+/** Upper bound of the per-account jitter added to the margin (inclusive). */
+export const GROK_REFRESH_JITTER_MAX_MS = 60_000;
+const REFRESH_TIMEOUT_MS = 15_000;
+
+/** oidc/refresh.rs:21-27: the only codes that end a refresh token's life. */
+const TERMINAL_ERROR_CODES = new Set(["invalid_grant", "invalid_client"]);
+
+/** The refresh token is dead; only a new login recovers. Never retry. */
+export class GrokReauthRequiredError extends Error {
+  override readonly name = "GrokReauthRequiredError";
+  constructor(
+    readonly oauthError: string,
+    readonly status: number,
+  ) {
+    super(`Grok refresh rejected: HTTP ${status} ${oauthError}`);
+  }
+}
+
+/** Network failure, timeout, 5xx, 429, or an unrecognized error; the refresh token still lives. */
+export class GrokRefreshTransientError extends Error {
+  override readonly name = "GrokRefreshTransientError";
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly oauthError?: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Stable jitter in [0, 60 s] derived from a per-account seed. */
+export function grokRefreshJitterMs(seed: string): number {
+  const digest = createHash("sha256").update(`grok-refresh:${seed}`).digest();
+
+  return digest.readUInt32BE(0) % (GROK_REFRESH_JITTER_MAX_MS + 1);
+}
+
+/** True once `expiresAt - 300 s - jitter(userId)` is at or before `now`. */
+export function grokNeedsRefresh(credentials: GrokCredentials, now: number = Date.now()): boolean {
+  const expiresAt = Date.parse(credentials.expiresAt);
+
+  if (!Number.isFinite(expiresAt)) return true;
+
+  return expiresAt - GROK_REFRESH_MARGIN_MS - grokRefreshJitterMs(credentials.userId) <= now;
+}
+
+function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) return promise;
+
+  if (signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (cause: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(cause);
+      },
+    );
+  });
+}
+
+export type GrokPersistCredentials = (next: GrokCredentials) => Promise<void>;
+
+export interface GrokRefreshCoordinatorOptions {
+  fetch?: GrokFetch;
+  now?: () => number;
+  /** Persistence used by the `GrokRefresher` port methods (`ensureFresh`, `refreshAfterUnauthorized`). */
+  persist?: (tokenId: number, next: GrokCredentials) => Promise<void>;
+}
+
+export class GrokRefreshCoordinator implements GrokRefresher {
+  private readonly fetchImpl: GrokFetch;
+  private readonly now: () => number;
+  private readonly persistPort: GrokRefreshCoordinatorOptions["persist"];
+  private readonly inflight = new Map<number, Promise<GrokCredentials>>();
+  // Last credentials this process persisted per token. A caller holding an older snapshot must not
+  // present a refresh token the IdP has already rotated away (that reads as invalid_grant).
+  private readonly latest = new Map<number, GrokCredentials>();
+
+  constructor(options: GrokRefreshCoordinatorOptions = {}) {
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.now = options.now ?? Date.now;
+    this.persistPort = options.persist;
+  }
+
+  needsRefresh(credentials: GrokCredentials, now: number = this.now()): boolean {
+    return grokNeedsRefresh(credentials, now);
+  }
+
+  /**
+   * Refreshes `tokenId`, coalescing concurrent calls into one HTTP request. Resolves only after
+   * `persist` has stored the new credentials.
+   */
+  refresh(
+    tokenId: number,
+    credentials: GrokCredentials,
+    persist: GrokPersistCredentials,
+  ): Promise<GrokCredentials> {
+    const existing = this.inflight.get(tokenId);
+
+    if (existing) return existing;
+
+    const promise = this.doRefresh(tokenId, this.newest(tokenId, credentials), persist).finally(
+      () => this.inflight.delete(tokenId),
+    );
+
+    this.inflight.set(tokenId, promise);
+
+    return promise;
+  }
+
+  async ensureFresh(token: GrokTokenRef, signal?: AbortSignal): Promise<GrokCredentials> {
+    const current = this.newest(token.tokenId, token.credentials);
+
+    if (!this.needsRefresh(current)) return current;
+
+    return abortable(this.refresh(token.tokenId, current, this.portPersist(token.tokenId)), signal);
+  }
+
+  async refreshAfterUnauthorized(
+    token: GrokTokenRef,
+    signal?: AbortSignal,
+  ): Promise<GrokRefreshResult> {
+    const inflight = this.inflight.get(token.tokenId);
+    const latest = this.latest.get(token.tokenId);
+
+    // Another caller already replaced the rejected access token: reuse it instead of refreshing.
+    if (
+      !inflight &&
+      latest &&
+      latest.accessToken !== token.credentials.accessToken &&
+      !this.needsRefresh(latest)
+    )
+      return { status: "refreshed", credentials: latest };
+
+    try {
+      const credentials = await abortable(
+        this.refresh(token.tokenId, token.credentials, this.portPersist(token.tokenId)),
+        signal,
+      );
+
+      return { status: "refreshed", credentials };
+    } catch (error) {
+      if (error instanceof GrokReauthRequiredError)
+        return { status: "reauth_required", reason: error.oauthError };
+      throw error;
+    }
+  }
+
+  private portPersist(tokenId: number): GrokPersistCredentials {
+    const persist = this.persistPort;
+
+    if (!persist)
+      return () =>
+        Promise.reject(new Error("GrokRefreshCoordinator was created without a persist port"));
+
+    return (next) => persist(tokenId, next);
+  }
+
+  private newest(tokenId: number, credentials: GrokCredentials): GrokCredentials {
+    const latest = this.latest.get(tokenId);
+
+    if (!latest || latest.userId !== credentials.userId) return credentials;
+
+    return Date.parse(latest.expiresAt) > Date.parse(credentials.expiresAt) ? latest : credentials;
+  }
+
+  private async doRefresh(
+    tokenId: number,
+    credentials: GrokCredentials,
+    persist: GrokPersistCredentials,
+  ): Promise<GrokCredentials> {
+    const { tokenEndpoint } = await getGrokOAuthEndpoints({
+      fetch: this.fetchImpl,
+      now: this.now,
+    });
+
+    let response: Response;
+
+    try {
+      response = await this.fetchImpl(tokenEndpoint, {
+        method: "POST",
+        // oidc/protocol.rs:493-512: form body only; the shared client contributes the UA.
+        headers: {
+          "user-agent": grokShellUserAgent(),
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+        },
+        body: new URLSearchParams([
+          ["grant_type", "refresh_token"],
+          ["refresh_token", credentials.refreshToken],
+          ["client_id", credentials.clientId],
+        ]),
+        signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.name : "unknown";
+      logger.warn(`grok refresh network failure token=${tokenId} reason=${reason}`);
+      throw new GrokRefreshTransientError(`Grok refresh request failed (${reason})`);
+    }
+
+    if (!response.ok) {
+      const oauthError = await readGrokOAuthErrorCode(response);
+      logger.warn(
+        `grok refresh failed token=${tokenId} status=${response.status} code=${oauthError ?? "unknown"}`,
+      );
+
+      // oidc/protocol.rs:413-430: 5xx and 429 are always transient; otherwise only a terminal code
+      // ends the token.
+      if (
+        response.status < 500 &&
+        response.status !== 429 &&
+        oauthError !== undefined &&
+        TERMINAL_ERROR_CODES.has(oauthError)
+      )
+        throw new GrokReauthRequiredError(oauthError, response.status);
+      throw new GrokRefreshTransientError(
+        `Grok refresh failed: HTTP ${response.status} ${oauthError ?? "unknown"}`,
+        response.status,
+        oauthError,
+      );
+    }
+
+    let body: unknown;
+
+    try {
+      body = await response.json();
+    } catch {
+      throw new GrokRefreshTransientError("Grok refresh response is not JSON", response.status);
+    }
+
+    const tokens = GrokTokenResponse.safeParse(body);
+
+    if (!tokens.success)
+      throw new GrokRefreshTransientError(
+        "Grok refresh response failed validation",
+        response.status,
+      );
+
+    const rotated = Boolean(tokens.data.refresh_token);
+    const exp = decodeGrokJwt(tokens.data.access_token)?.payload.exp;
+
+    const expiresIn = tokens.data.expires_in;
+
+    const expiresAtMs =
+      expiresIn !== undefined && expiresIn !== null
+        ? this.now() + expiresIn * 1000
+        : exp !== undefined
+          ? exp * 1000
+          : undefined;
+
+    if (expiresAtMs === undefined || !Number.isFinite(expiresAtMs))
+      throw new GrokRefreshTransientError("Grok refresh response has no expiry", response.status);
+
+    const next = GrokCredentials.safeParse({
+      ...credentials,
+      accessToken: tokens.data.access_token,
+      // oidc/refresh.rs:260-264: keep the old refresh token when the IdP did not rotate it.
+      refreshToken: tokens.data.refresh_token ?? credentials.refreshToken,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    });
+
+    if (!next.success) {
+      logger.error(
+        `grok refresh returned unusable credentials token=${tokenId} rotated=${rotated}`,
+      );
+      throw new GrokRefreshTransientError(
+        "Grok refresh returned an access token that is not an auth.x.ai at+jwt",
+        response.status,
+      );
+    }
+
+    try {
+      await persist(next.data);
+    } catch (error) {
+      // A rotated refresh token that is not persisted is lost: the next refresh with the old one
+      // fails with invalid_grant. Keep it in memory so this process can still use it.
+      if (rotated) this.latest.set(tokenId, next.data);
+      logger.error(
+        `grok refresh persist FAILED token=${tokenId} rotated=${rotated} err=${error instanceof Error ? error.name : "unknown"}`,
+      );
+      throw error;
+    }
+
+    this.latest.set(tokenId, next.data);
+    logger.info(`grok token ${tokenId} refreshed (rotated=${rotated})`);
+
+    return next.data;
+  }
+}

package/bundle/src/utils/providers/grok/grok-types.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+
+import { GROK_OAUTH_CLIENT_ID, GROK_OAUTH_SCOPES } from "./grok-constants";
+import {
+  GrokApiImageModelCatalog,
+  GrokApiLanguageModelCatalog,
+  GrokBillingConfig,
+  GrokCredentials,
+  GrokImageResponse,
+  GrokModelsResponse,
+  GrokSettings,
+  GrokSttResponse,
+  GrokTtsRequest,
+  GrokUserSubscription,
+  GrokVideoStatus,
+  decodeGrokJwt,
+  grokCatalogModels,
+  grokVideoUrl,
+  isGrokAccessToken,
+} from "./grok-types";
+
+function segment(value: unknown): string {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+function fakeJwt(header: Record<string, unknown>, payload: Record<string, unknown>): string {
+  return `${segment(header)}.${segment(payload)}.c2lnbmF0dXJl`;
+}
+
+const validJwt = fakeJwt(
+  { alg: "RS256", typ: "at+jwt" },
+  { iss: "https://auth.x.ai", sub: "user", exp: 2_000_000_000 },
+);
+
+const credentials = {
+  authMode: "oauth",
+  accessToken: validJwt,
+  refreshToken: "refresh",
+  expiresAt: "2026-10-16T09:00:00Z",
+  issuer: "https://auth.x.ai",
+  clientId: GROK_OAUTH_CLIENT_ID,
+  scopes: [...GROK_OAUTH_SCOPES],
+  userId: "19bfa1b2-a163-9e0c-8de1-832a73e2695e",
+  sessionId: "22222222-2222-4222-8222-222222222222",
+  agentId: "33333333-3333-4333-8333-333333333333",
+  subscriptionTier: "SuperGrokPlus",
+};
+
+describe("GrokCredentials", () => {
+  it("accepts a fabricated at+jwt from auth.x.ai", () => {
+    expect(GrokCredentials.parse(credentials)).toEqual(credentials);
+    expect(decodeGrokJwt(validJwt)?.payload.iss).toBe("https://auth.x.ai");
+  });
+
+  it("rejects an API key", () => {
+    expect(isGrokAccessToken("xai-0123456789abcdefghijklmnop")).toBe(false);
+    expect(GrokCredentials.safeParse({ ...credentials, accessToken: "xai-abc" }).success).toBe(
+      false,
+    );
+  });
+
+  it("rejects a JWT from another issuer or of another type", () => {
+    const foreign = fakeJwt({ alg: "RS256", typ: "at+jwt" }, { iss: "https://accounts.example" });
+    const idToken = fakeJwt({ alg: "RS256", typ: "JWT" }, { iss: "https://auth.x.ai" });
+    expect(GrokCredentials.safeParse({ ...credentials, accessToken: foreign }).success).toBe(false);
+    expect(GrokCredentials.safeParse({ ...credentials, accessToken: idToken }).success).toBe(false);
+  });
+
+  it("rejects malformed JWT segments", () => {
+    expect(isGrokAccessToken("a.b")).toBe(false);
+    expect(isGrokAccessToken("!!!.???.sig")).toBe(false);
+    expect(isGrokAccessToken(`${segment("x")}.${segment("y")}.sig`)).toBe(false);
+  });
+
+  it("requires userId, an RFC 3339 expiry and the auth.x.ai issuer", () => {
+    const { userId: _userId, ...withoutUser } = credentials;
+    expect(GrokCredentials.safeParse(withoutUser).success).toBe(false);
+    expect(GrokCredentials.safeParse({ ...credentials, expiresAt: "tomorrow" }).success).toBe(
+      false,
+    );
+    expect(GrokCredentials.safeParse({ ...credentials, expiresAt: 1_800_000_000 }).success).toBe(
+      false,
+    );
+    expect(
+      GrokCredentials.safeParse({ ...credentials, issuer: "https://auth.example" }).success,
+    ).toBe(false);
+    expect(GrokCredentials.safeParse({ ...credentials, authMode: "api_key" }).success).toBe(false);
+  });
+});
+
+describe("Grok proxy response schemas (U0 shapes, redacted)", () => {
+  it("parses /billing?format=credits", () => {
+    const billing = GrokBillingConfig.parse({
+      config: {
+        currentPeriod: {
+          type: "USAGE_PERIOD_TYPE_WEEKLY",
+          start: "2026-10-12T00:00:00Z",
+          end: "2026-10-19T00:00:00Z",
+        },
+        creditUsagePercent: 1,
+        productUsage: [{ product: "GrokBot", usagePercent: 1 }],
+        isUnifiedBillingUser: true,
+        prepaidBalance: { val: 0 },
+        topUpMethod: "TOP_UP_METHOD_UNSPECIFIED",
+        billingPeriodStart: "2026-10-12T00:00:00Z",
+        billingPeriodEnd: "2026-10-19T00:00:00Z",
+      },
+    });
+    expect(billing.config.creditUsagePercent).toBe(1);
+    expect(billing.config).not.toHaveProperty("onDemandEnabled");
+    expect(billing.config.topUpMethod).toBe("TOP_UP_METHOD_UNSPECIFIED");
+    expect(GrokBillingConfig.safeParse({ config: { credit_usage_percent: 1 } }).success).toBe(
+      false,
+    );
+  });
+
+  it("parses /settings with on_demand_enabled null", () => {
+    const settings = GrokSettings.parse({
+      min_client_version: "1.0.13",
+      force_update: true,
+      default_model: "grok-4.7",
+      subscription_tier_display: "SuperGrok Plus",
+      on_demand_enabled: null,
+      image_gen_enabled: true,
+      video_gen_enabled: true,
+      voice_mode_enabled: true,
+      accept_request_encodings: ["zstd"],
+      tips: ["passthrough"],
+    });
+    expect(settings.on_demand_enabled).toBeNull();
+    expect(settings.tips).toEqual(["passthrough"]);
+    expect(GrokSettings.safeParse({ on_demand_enabled: "yes" }).success).toBe(false);
+  });
+
+  it("parses /user?include=subscription", () => {
+    const user = GrokUserSubscription.parse({
+      userId: "19bfa1b2-a163-9e0c-8de1-832a73e2695e",
+      email: "user@example.com",
+      subscriptionTier: "SuperGrokPlus",
+      hasGrokCodeAccess: true,
+      teamId: null,
+    });
+    expect(user.subscriptionTier).toBe("SuperGrokPlus");
+    expect(user.codingDataRetentionOptOut).toBeUndefined();
+    expect(
+      GrokUserSubscription.parse({ userId: user.userId, codingDataRetentionOptOut: true })
+        .codingDataRetentionOptOut,
+    ).toBe(true);
+    expect(
+      GrokUserSubscription.safeParse({ userId: user.userId, codingDataRetentionOptOut: "yes" })
+        .success,
+    ).toBe(false);
+    expect(GrokUserSubscription.safeParse({ subscriptionTier: "x" }).success).toBe(false);
+  });
+
+  it("parses proxy /models", () => {
+    const efforts = ["xhigh", "high", "medium", "low"].map((id) => ({
+      id,
+      value: id,
+      label: id,
+      description: id,
+      default: id === "high",
+    }));
+    const models = GrokModelsResponse.parse({
+      object: "list",
+      data: ["grok-4.7", "grok-4.7-build-fast", "grok-4.6", "grok-4.5"].map((id) => ({
+        id,
+        object: "model",
+        context_window: 256000,
+        context_windows: [256000, 500000],
+        api_backend: "responses",
+        reasoning_effort: "high",
+        supports_reasoning_effort: true,
+        reasoning_efforts: efforts,
+      })),
+    });
+    expect(models.data.map((model) => model.id)).toEqual([
+      "grok-4.7",
+      "grok-4.7-build-fast",
+      "grok-4.6",
+      "grok-4.5",
+    ]);
+  });
+});
+
+describe("api.x.ai schemas", () => {
+  it("parses the language-model price catalog under either envelope", () => {
+    const model = {
+      id: "grok-4.7",
+      aliases: ["grok-4.7-latest"],
+      prompt_text_token_price: 20000,
+      cached_prompt_text_token_price: 5000,
+      completion_text_token_price: 60000,
+      prompt_image_token_price: 20000,
+      prompt_text_token_price_long_context: 40000,
+      long_context_threshold: 200000,
+    };
+    for (const envelope of [{ models: [model] }, { data: [model], object: "list" }]) {
+      const catalog = GrokApiLanguageModelCatalog.parse(envelope);
+      expect(grokCatalogModels(catalog)[0]?.prompt_text_token_price).toBe(20000);
+    }
+  });
+
+  it("parses the image-model price catalog", () => {
+    const catalog = GrokApiImageModelCatalog.parse({
+      models: [
+        {
+          id: "grok-imagine-image-quality",
+          image_price: 500000000,
+          pricing: [{ quality: "quality", resolution: "1k", price_per_image: 500000000 }],
+        },
+      ],
+    });
+    expect(grokCatalogModels(catalog)[0]?.pricing?.[0]?.price_per_image).toBe(500000000);
+  });
+
+  it("parses image, video, STT and TTS shapes", () => {
+    expect(
+      GrokImageResponse.parse({
+        data: [{ b64_json: "AAAA", mime_type: "image/jpeg" }],
+        usage: { cost_in_usd_ticks: 500000000 },
+      }).usage?.cost_in_usd_ticks,
+    ).toBe(500000000);
+    expect(GrokImageResponse.safeParse({ data: [] }).success).toBe(false);
+    expect(
+      grokVideoUrl(GrokVideoStatus.parse({ status: "done", video: { url: "https://v/1.mp4" } })),
+    ).toBe("https://v/1.mp4");
+    expect(
+      grokVideoUrl(
+        GrokVideoStatus.parse({
+          status: "done",
+          video: { url: null, file_output: { public_url: "https://v/2.mp4" } },
+        }),
+      ),
+    ).toBe("https://v/2.mp4");
+    // @ai-sdk/xai never reads a top-level file_output.
+    expect(
+      grokVideoUrl(
+        GrokVideoStatus.parse({ status: "done", file_output: { public_url: "https://v/3.mp4" } }),
+      ),
+    ).toBeUndefined();
+    expect(grokVideoUrl(GrokVideoStatus.parse({ status: "pending" }))).toBeUndefined();
+    expect(GrokSttResponse.parse({ text: "", language: "", duration: 1 }).duration).toBe(1);
+    expect(
+      GrokTtsRequest.safeParse({ text: "hi", voice: "ara", language: "en", format: "mp3" })
+        .success,
+    ).toBe(true);
+    expect(GrokTtsRequest.safeParse({ text: "hi", voice: "ara", format: "mp3" }).success).toBe(
+      false,
+    );
+  });
+});