libfx 0.0.13 → 0.0.14-dev.1561.g1a070af32cdf

package/grok-sign-in.js

@@ -0,0 +1,145 @@
+// `libfx/grok`: sign in with a Grok plan for a Grok agent. Two flows, both
+// plain data between steps so a website can start in one request and finish in
+// another:
+//
+// - Device code: the user enters a short code on xAI's page.
+// - Paste the address: the user signs in on xAI, lands on a page at
+//   127.0.0.1 that does not load, and pastes its address back.
+import { grokAccountId, grokClientId, grokIssuer, normalizeGrokCredentials, refreshGrokCredentials } from "./grok.js";
+import { hostFetch, pkceChallenge, randomSecret, readSignInAddress, signInError, wait } from "./oauth.js";
+
+const scope = "openid profile email offline_access grok-cli:access api:access";
+const deviceGrant = "urn:ietf:params:oauth:grant-type:device_code";
+const slowDownMs = 5000;
+
+const form = (fields) => ({
+  method: "POST",
+  headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+  body: new URLSearchParams(fields).toString(),
+});
+
+/** Credentials for a token response, with the account it belongs to. */
+async function credentialsFor(tokens, { fetch, signal }) {
+  const accountId = await grokAccountId(tokens.access_token, { fetch, signal });
+  return normalizeGrokCredentials({
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    accountId,
+    ...(Number.isFinite(tokens.expires_in) ? { expiresAt: Date.now() + tokens.expires_in * 1000 } : {}),
+  });
+}
+
+/** Starts a sign-in. Keep the result on the server: `verifier` is secret. */
+export async function startSignIn() {
+  const verifier = randomSecret();
+  const state = randomSecret();
+  // xAI accepts any loopback port. Nothing listens there: the user copies the address.
+  const port = 1024 + (crypto.getRandomValues(new Uint16Array(1))[0] % (65536 - 1024));
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const url = new URL(`${grokIssuer}/oauth2/authorize`);
+  for (const [key, value] of Object.entries({
+    response_type: "code",
+    client_id: grokClientId,
+    redirect_uri: redirectUri,
+    scope,
+    code_challenge: await pkceChallenge(verifier),
+    code_challenge_method: "S256",
+    state,
+    referrer: "fx",
+  })) url.searchParams.set(key, value);
+  return { url: url.href, state, verifier, redirectUri };
+}
+
+/** Finishes a sign-in from the address the user pasted. */
+export async function finishSignIn(signIn, address, { fetch, signal } = {}) {
+  if (!signIn || typeof signIn.state !== "string" || typeof signIn.verifier !== "string" || typeof signIn.redirectUri !== "string") {
+    throw new TypeError("finishSignIn() needs the object startSignIn() returned");
+  }
+  const { code, state } = readSignInAddress(address, { prefix: "LIBFX_GROK", issuer: "xAI", redirectUri: signIn.redirectUri });
+  if (state !== signIn.state) {
+    throw signInError("LIBFX_GROK_SIGN_IN_STATE_MISMATCH", "That address is from a different sign-in. Start again and paste the address from this one.");
+  }
+  const response = await hostFetch(fetch)(`${grokIssuer}/oauth2/token`, {
+    ...form({ grant_type: "authorization_code", client_id: grokClientId, code, code_verifier: signIn.verifier, redirect_uri: signIn.redirectUri }),
+    signal,
+  });
+  if (response.status === 400 || response.status === 401) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_GROK_SIGN_IN_EXPIRED", "This sign-in expired or was already used. Start again.", { status: response.status });
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_GROK_SIGN_IN_FAILED", `xAI could not finish the sign-in (HTTP ${response.status}).`, { status: response.status });
+  }
+  return credentialsFor(await response.json(), { fetch, signal });
+}
+
+/** Starts a device code sign-in. Show `userCode` and `verificationUrl`. */
+export async function startDeviceSignIn({ fetch, signal } = {}) {
+  const response = await hostFetch(fetch)(`${grokIssuer}/oauth2/device/code`, { ...form({ client_id: grokClientId, scope }), signal });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw signInError("LIBFX_GROK_DEVICE_CODE_UNAVAILABLE", `xAI did not issue a device code (HTTP ${response.status}).`, { status: response.status });
+  }
+  const body = await response.json();
+  const expiresIn = Number(body.expires_in);
+  if (typeof body.user_code !== "string" || typeof body.device_code !== "string" || typeof body.verification_uri !== "string" || !Number.isFinite(expiresIn)) {
+    throw signInError("LIBFX_GROK_DEVICE_CODE_UNAVAILABLE", "xAI returned a device code response libfx does not understand.");
+  }
+  const interval = Number(body.interval);
+  return {
+    verificationUrl: typeof body.verification_uri_complete === "string" ? body.verification_uri_complete : body.verification_uri,
+    userCode: body.user_code,
+    deviceCode: body.device_code,
+    intervalMs: Math.max(Number.isFinite(interval) ? interval : 5, 1) * 1000,
+    expiresAt: Date.now() + expiresIn * 1000,
+  };
+}
+
+/** One poll: `{ credentials }`, or `{ pending: true, slowDown }` until the user enters the code. */
+async function poll(device, { fetch, signal }) {
+  if (!device || typeof device.deviceCode !== "string" || typeof device.userCode !== "string") {
+    throw new TypeError("pollDeviceSignIn() needs the object startDeviceSignIn() returned");
+  }
+  if (Date.now() > device.expiresAt) {
+    throw signInError("LIBFX_GROK_DEVICE_CODE_EXPIRED", "The code expired before it was entered. Start again.");
+  }
+  const response = await hostFetch(fetch)(`${grokIssuer}/oauth2/token`, {
+    ...form({ grant_type: deviceGrant, device_code: device.deviceCode, client_id: grokClientId }),
+    signal,
+  });
+  if (response.ok) return { credentials: await credentialsFor(await response.json(), { fetch, signal }) };
+  const body = await response.json().catch(() => null);
+  switch (body?.error) {
+    case "authorization_pending": return { pending: true, slowDown: false };
+    case "slow_down": return { pending: true, slowDown: true };
+    case "expired_token":
+      throw signInError("LIBFX_GROK_DEVICE_CODE_EXPIRED", "The code expired before it was entered. Start again.");
+    case "access_denied":
+      throw signInError("LIBFX_GROK_SIGN_IN_DENIED", "The sign-in was declined on xAI's page.", { reason: body.error });
+    default:
+      throw signInError("LIBFX_GROK_SIGN_IN_FAILED", `xAI could not finish the sign-in (HTTP ${response.status}).`, { status: response.status });
+  }
+}
+
+/** Checks a device sign-in once: credentials when the user has entered the code, otherwise null. */
+export async function pollDeviceSignIn(device, { fetch, signal } = {}) {
+  const result = await poll(device, { fetch, signal });
+  return result.credentials ?? null;
+}
+
+/** Waits until the user enters the code, polling at xAI's interval and slowing down when asked. */
+export async function completeDeviceSignIn(device, { fetch, signal } = {}) {
+  let intervalMs = device?.intervalMs;
+  for (;;) {
+    const result = await poll(device, { fetch, signal });
+    if (result.credentials) return result.credentials;
+    if (result.slowDown) intervalMs += slowDownMs;
+    await wait(intervalMs, signal);
+  }
+}
+
+/** Refreshes credentials. Grok agents refresh on their own; this is for hosts. */
+export function refreshCredentials(credentials, { fetch, signal } = {}) {
+  return refreshGrokCredentials(normalizeGrokCredentials(credentials), { fetch, signal });
+}

package/grok.js

@@ -0,0 +1,108 @@
+// Grok (xAI subscription) credentials for libfx agents: the Grok endpoints,
+// how a Grok plan's credentials are checked and refreshed, and the headers
+// that carry them. `subscription.js` adds them at the fetch edge.
+import { normalizeCredentials } from "./subscription.js";
+
+export const grokIssuer = "https://auth.x.ai";
+export const grokClientId = "b1a00492-073a-47ea-816f-4c329264a828";
+
+const proxyOrigin = "https://cli-chat-proxy.grok.com";
+const responsesPath = "/v1/responses";
+const modelsPath = "/v1/models";
+const languageModelsEndpoint = "https://api.x.ai/v1/language-models";
+
+function endpointOf(url) {
+  try {
+    const parsed = new URL(String(url));
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return null;
+  }
+}
+
+/** True only for the exact Grok endpoints the engine calls. */
+export function isGrokRequest(url) {
+  const endpoint = endpointOf(url);
+  return endpoint === `${proxyOrigin}${responsesPath}` ||
+    endpoint === `${proxyOrigin}${modelsPath}` ||
+    endpoint === languageModelsEndpoint;
+}
+
+/**
+ * Validates credentials from the host. The account id defaults to the access
+ * token's `sub` claim when the token carries one; sign-in from `libfx/grok`
+ * always returns it. Returns a new object.
+ */
+export function normalizeGrokCredentials(value) {
+  return normalizeCredentials(value, { label: "Grok", accountClaim: (claims) => claims?.sub });
+}
+
+function grokError(code, message, status) {
+  const error = new Error(message);
+  error.code = code;
+  if (status !== undefined) error.status = status;
+  return error;
+}
+
+/** The xAI account an access token belongs to: the `sub` of its userinfo. */
+export async function grokAccountId(accessToken, { fetch, signal } = {}) {
+  const doFetch = fetch ?? globalThis.fetch?.bind(globalThis);
+  const response = await doFetch(`${grokIssuer}/oauth2/userinfo`, {
+    headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw grokError("LIBFX_GROK_ACCOUNT_UNAVAILABLE", `xAI did not identify the account (HTTP ${response.status})`, response.status);
+  }
+  const info = await response.json().catch(() => null);
+  if (typeof info?.sub !== "string" || info.sub.length === 0) {
+    throw grokError("LIBFX_GROK_ACCOUNT_UNAVAILABLE", "xAI's account response had no account id");
+  }
+  return info.sub;
+}
+
+/**
+ * Exchanges a refresh token at xAI, keeping the old refresh token when the
+ * response does not rotate it, and confirms the new token is for the same
+ * account.
+ */
+export async function refreshGrokCredentials(credentials, { fetch, signal } = {}) {
+  if (credentials.refreshToken === undefined) throw new TypeError("Grok credentials have no refreshToken");
+  const doFetch = fetch ?? globalThis.fetch?.bind(globalThis);
+  const response = await doFetch(`${grokIssuer}/oauth2/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: new URLSearchParams({ grant_type: "refresh_token", client_id: grokClientId, refresh_token: credentials.refreshToken }).toString(),
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw grokError("LIBFX_GROK_REFRESH_FAILED", `Grok token refresh failed with HTTP ${response.status}`, response.status);
+  }
+  const tokens = await response.json();
+  const next = normalizeGrokCredentials({
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? credentials.refreshToken,
+    accountId: credentials.accountId,
+    ...(Number.isFinite(tokens.expires_in) ? { expiresAt: Date.now() + tokens.expires_in * 1000 } : {}),
+  });
+  if (await grokAccountId(next.accessToken, { fetch, signal }) !== credentials.accountId) {
+    throw grokError("LIBFX_GROK_ACCOUNT_CHANGED", "The refreshed Grok token belongs to a different account");
+  }
+  return next;
+}
+
+/** Grok on a Grok plan, for `createSubscriptionAuthorizer()`. */
+export const grokSubscription = {
+  provider: "grok",
+  matches: isGrokRequest,
+  sessionId: (headers) => headers.get("x-grok-conv-id"),
+  normalize: normalizeGrokCredentials,
+  refresh: refreshGrokCredentials,
+  authorize(headers, endpoint, credentials) {
+    headers.set("authorization", `Bearer ${credentials.accessToken}`);
+    if (endpoint === `${proxyOrigin}${responsesPath}`) headers.set("x-grok-user-id", credentials.accountId);
+    if (endpoint === `${proxyOrigin}${modelsPath}`) headers.set("x-userid", credentials.accountId);
+  },
+};

package/mcp.js

@@ -33,6 +33,11 @@ export async function createMcpAdapter(client, options = {}) {
     throw new TypeError("MCP client must provide listTools() and callTool()");
   }
   const prefix = options.prefix ?? "";
+  if (options.propagateCorrelation !== undefined && typeof options.propagateCorrelation !== "boolean") throw new TypeError("MCP propagateCorrelation must be a boolean");
+  if (options.serverName !== undefined && (typeof options.serverName !== "string" || options.serverName.length === 0 || options.serverName.length > 256)) throw new TypeError("MCP serverName must be a bounded name");
+  let reportedName;
+  try { reportedName = client.getServerVersion?.()?.name; } catch {}
+  const serverName = options.serverName ?? (typeof reportedName === "string" && reportedName.length > 0 && reportedName.length <= 256 ? reportedName : null);
   if (typeof prefix !== "string" || !/^[A-Za-z0-9_-]*$/.test(prefix)) {
     throw new TypeError("MCP prefix must contain only letters, digits, underscore, or hyphen");
   }
@@ -67,8 +72,15 @@ export async function createMcpAdapter(client, options = {}) {
       name,
       description: tool.description || "MCP tool",
       inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
-      async execute(input, { signal }) {
-        const result = await client.callTool({ name: tool.name, arguments: input }, undefined, { signal });
+      // The server's hints are not trusted: a call is never run twice on its
+      // own. A host that knows a tool is safe to repeat can set this to true.
+      idempotent: false,
+      async execute(input, { signal, observation }) {
+        const correlationId = options.propagateCorrelation === true ? crypto.randomUUID() : undefined;
+        // Correlation is not progress reporting: progressToken requests remote
+        // notifications and some clients replace it with their JSON-RPC ID.
+        const send = () => client.callTool({ name: tool.name, arguments: input, ...(correlationId === undefined ? {} : { _meta: { "libfx/correlationId": correlationId } }) }, undefined, { signal });
+        const result = observation ? await observation.mcp({ server: serverName, tool: tool.name, correlationId }, send) : await send();
         const text = resultText(result);
         const images = (Array.isArray(result?.content) ? result.content : []).flatMap((item) => item?.type === "image" ? [item] : item?.type === "resource" && item.resource?.mimeType?.startsWith("image/") && typeof item.resource?.blob === "string" ? [{ type: "image", mimeType: item.resource.mimeType, data: item.resource.blob }] : []).map((item) => ({
           type: "image", mimeType: item.mimeType, data: item.data,