@theokit/sdk 4.10.1 → 4.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.11.0
+
+### Minor Changes
+
+- Auth subsystem (agent-builder M42): a new `@theokit/sdk/auth` sub-entry ships a credential store + OAuth engine, promoted DOWN from agent-builder's hardened M37 code, generalized to `provider: string` + a caller-supplied `CredentialStoreConfig` (no hardcoded client IDs). Public surface (`import { … } from "@theokit/sdk/auth"`): `resolveCredential(name)` returns a fresh (transparently-refreshed) `ResolvedCredential`; the credential store (`writeCredential`/`readAuthFile`/`readStoredOAuth`/`authFilePath`/`credentialHome`/`CredentialError`), the OAuth engine (`exchangeCode`/`refreshOAuthTokens`/`ensureFreshCredential`/`persistOAuthTokens`), the device flows (`deviceLogin`/`openaiDeviceLogin`/`requestDeviceCode`/`pollDeviceToken`/`requestOpenAIUsercode`/`parseJwtClaims`/`extractAccountId`), and the contract types (`CredentialStoreConfig`, `ResolvedCredential`, `StoredOAuthCredential`, `OAuthProviderConfig`, `OAuthTokens`, `HttpDeps`, `DeviceOAuthConfig`, `OpenAIDeviceConfig`, …). It sits at a dedicated sub-entry (DTS via tsc) — the same isolation as `@theokit/sdk/messages` / `/subscription` / `/sanitize` — because rollup-plugin-dts cannot bundle the modules into the main barrel. The credential store does an atomic O_EXCL + rename + fsync write at mode 0600 with 0700/0600 mode gates; the OAuth engine implements RFC 8628 device-grant + the OpenAI two-step headless flow + token exchange/refresh with in-flight-refresh coalescing (keyed by store path, rejected promise evicted — single-use refresh tokens are never double-spent) and a no-token-in-error discipline. The router's lazy-sentinel path now covers `oauth_device_code` / `oauth_external` so an oauth provider builds a client whose M41 `transform.fetch(ctx)` owns the fresh bearer at stream time — a mid-turn expiry refreshes without rebuilding the agent, and plain (api-key/env) profiles resolve byte-for-byte unchanged. Device-grant + JWT extraction + OpenAI two-step adapted from OpenCode (MIT); see NOTICE.
+
 ## 4.10.1
 
 ### Patch Changes

package/dist/auth/index.cjs

@@ -0,0 +1,552 @@
+'use strict';
+
+var crypto = require('crypto');
+var fs = require('fs');
+var path = require('path');
+var zod = require('zod');
+
+// src/internal/auth/credential-store.ts
+function credentialHome(config, env = {}) {
+  const override = config.homeEnvVar !== void 0 ? env[config.homeEnvVar]?.trim() : void 0;
+  return override !== void 0 && override.length > 0 ? override : path.join(config.home, config.dirName);
+}
+function authFilePath(config, env = {}) {
+  return path.join(credentialHome(config, env), config.fileName);
+}
+var CredentialError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CredentialError";
+  }
+};
+var apiFileSchema = zod.z.object({
+  type: zod.z.literal("api").optional(),
+  provider: zod.z.string().min(1).optional(),
+  api_key: zod.z.string()
+}).strict();
+var oauthFileSchema = zod.z.object({
+  type: zod.z.literal("oauth"),
+  provider: zod.z.string().min(1),
+  access: zod.z.string().min(1),
+  refresh: zod.z.string().min(1),
+  expires: zod.z.number(),
+  account_id: zod.z.string().optional()
+}).strict();
+var fileSchema = zod.z.union([oauthFileSchema, apiFileSchema]);
+function assertSecureModes(dirPath, path) {
+  const dirMode = fs.statSync(dirPath).mode & 511;
+  if ((dirMode & 18) !== 0) {
+    throw new CredentialError(
+      `${dirPath} is writable by other users (mode ${dirMode.toString(8)}), so the credential file inside it can be replaced. Fix it with:  chmod 700 ${dirPath}`
+    );
+  }
+  const mode = fs.statSync(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new CredentialError(
+      `${path} is readable by other users (mode ${mode.toString(8)}). A credential file must not be. Fix it with:  chmod 600 ${path}`
+    );
+  }
+}
+function describeUnionError(parsed, err, path) {
+  const looksOAuth = typeof parsed === "object" && parsed !== null && parsed.type === "oauth";
+  const specific = looksOAuth ? oauthFileSchema.safeParse(parsed) : apiFileSchema.safeParse(parsed);
+  let issue;
+  if (!specific.success) {
+    issue = specific.error.issues[0];
+  } else if (err instanceof zod.z.ZodError) {
+    issue = err.issues[0];
+  }
+  return new CredentialError(
+    `${path}: ${issue?.message ?? String(err)} [${issue?.path.join(".") || "root"}]`
+  );
+}
+function parseStoredFile(raw, path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CredentialError(
+      `${path} is not valid JSON. Expected:  {"provider": "<name>", "api_key": "..."}`
+    );
+  }
+  try {
+    return fileSchema.parse(parsed);
+  } catch (err) {
+    throw describeUnionError(parsed, err, path);
+  }
+}
+function readAuthFile(config, env = {}) {
+  const path = authFilePath(config, env);
+  let raw;
+  try {
+    raw = fs.readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw new CredentialError(`cannot read ${path}: ${err.message}`);
+  }
+  assertSecureModes(credentialHome(config, env), path);
+  return parseStoredFile(raw, path);
+}
+function readStoredOAuth(config, env = {}) {
+  const stored = readAuthFile(config, env);
+  return stored !== void 0 && stored.type === "oauth" ? stored : void 0;
+}
+function isOAuthWrite(c) {
+  return "type" in c && c.type === "oauth";
+}
+function buildStorePayload(cred) {
+  if (isOAuthWrite(cred)) {
+    if (cred.access.length === 0 || cred.refresh.length === 0) {
+      throw new CredentialError(
+        "refusing to write an oauth credential with an empty access/refresh token"
+      );
+    }
+    return {
+      type: "oauth",
+      provider: cred.provider,
+      access: cred.access,
+      refresh: cred.refresh,
+      expires: cred.expires,
+      ...cred.account_id !== void 0 ? { account_id: cred.account_id } : {}
+    };
+  }
+  if (typeof cred.apiKey !== "string" || cred.apiKey.length === 0) {
+    throw new CredentialError("refusing to write an empty API key");
+  }
+  return { provider: cred.provider, api_key: cred.apiKey };
+}
+function writeCredential(cred, config, env = {}) {
+  const payload = buildStorePayload(cred);
+  const dir = credentialHome(config, env);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs.chmodSync(dir, 448);
+  const path = authFilePath(config, env);
+  const tmp = `${path}.tmp-${crypto.randomBytes(8).toString("hex")}`;
+  try {
+    const fd = fs.openSync(tmp, "wx", 384);
+    try {
+      fs.writeFileSync(fd, `${JSON.stringify(payload, null, 2)}
+`);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.chmodSync(tmp, 384);
+    fs.renameSync(tmp, path);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+    }
+    throw new CredentialError(`cannot write ${path}: ${err.message}`);
+  }
+  return path;
+}
+
+// src/server/auth/errors.ts
+var AuthCallbackError = class extends Error {
+  name = "AuthCallbackError";
+  code;
+  constructor(code, message) {
+    super(message ?? `OAuth callback error: ${code}`);
+    this.code = code;
+  }
+};
+
+// src/internal/auth/oauth-engine.ts
+var REFRESH_SKEW_MS = 6e4;
+function parseTokenResponse(body, now) {
+  const b = body;
+  if (typeof b.access_token !== "string" || b.access_token.length === 0) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      "token response had no access_token"
+    );
+  }
+  if (typeof b.refresh_token !== "string" || b.refresh_token.length === 0) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      "token response had no refresh_token"
+    );
+  }
+  const expiresIn = typeof b.expires_in === "number" ? b.expires_in : 3600;
+  return {
+    access: b.access_token,
+    refresh: b.refresh_token,
+    expires: now + expiresIn * 1e3,
+    ...typeof b.account_id === "string" ? { accountId: b.account_id } : {}
+  };
+}
+async function postGrant(config, form, deps) {
+  let res;
+  try {
+    res = await deps.fetch(config.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams(form).toString()
+    });
+  } catch (err) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      `token endpoint request failed: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      `token endpoint returned HTTP ${res.status}`
+    );
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new AuthCallbackError("oauth_token_exchange_failed", "token response was not valid JSON");
+  }
+  return parseTokenResponse(json, deps.now());
+}
+function exchangeCode(config, input, deps) {
+  return postGrant(
+    config,
+    {
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: config.redirectUri,
+      client_id: config.clientId,
+      code_verifier: input.verifier
+    },
+    deps
+  );
+}
+function refreshOAuthTokens(config, refresh, deps) {
+  return postGrant(
+    config,
+    { grant_type: "refresh_token", refresh_token: refresh, client_id: config.clientId },
+    deps
+  );
+}
+function persistOAuthTokens(provider, tokens, store, env = {}) {
+  return writeCredential(
+    {
+      type: "oauth",
+      provider,
+      access: tokens.access,
+      refresh: tokens.refresh,
+      expires: tokens.expires,
+      ...tokens.accountId !== void 0 ? { account_id: tokens.accountId } : {}
+    },
+    store,
+    env
+  );
+}
+var inFlightRefresh = /* @__PURE__ */ new Map();
+async function ensureFreshCredential(resolved, opts, deps) {
+  if (resolved.kind !== "oauth") return resolved;
+  const now = deps.now();
+  if (resolved.expiresAt !== void 0 && resolved.expiresAt > now + REFRESH_SKEW_MS) {
+    return resolved;
+  }
+  const env = opts.env ?? {};
+  const path = authFilePath(opts.store, env);
+  let refresh = inFlightRefresh.get(path);
+  if (refresh === void 0) {
+    refresh = (async () => {
+      const stored = readStoredOAuth(opts.store, env);
+      if (stored === void 0) {
+        throw new AuthCallbackError(
+          "oauth_token_exchange_failed",
+          "no stored oauth credential to refresh"
+        );
+      }
+      const fresh2 = await refreshOAuthTokens(opts.config, stored.refresh, deps);
+      persistOAuthTokens(resolved.provider, fresh2, opts.store, env);
+      return fresh2;
+    })();
+    inFlightRefresh.set(path, refresh);
+    refresh.finally(() => inFlightRefresh.delete(path)).catch(() => {
+    });
+  }
+  const fresh = await refresh;
+  return {
+    kind: "oauth",
+    provider: resolved.provider,
+    apiKey: fresh.access,
+    source: resolved.source,
+    inferred: false,
+    expiresAt: fresh.expires
+  };
+}
+
+// src/internal/auth/oauth-device.ts
+var POLLING_SAFETY_MARGIN_MS = 3e3;
+async function requestDeviceCode(config, deps) {
+  let res;
+  try {
+    res = await deps.fetch(config.deviceCodeEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams({
+        client_id: config.clientId,
+        scope: config.scopes.join(" ")
+      }).toString()
+    });
+  } catch (err) {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      `device request failed: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      `device endpoint returned HTTP ${res.status}`
+    );
+  }
+  const data = await res.json();
+  if (typeof data.device_code !== "string" || typeof data.user_code !== "string") {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      "device response missing device_code/user_code"
+    );
+  }
+  const verification = typeof data.verification_uri === "string" ? data.verification_uri : typeof data.verification_uri_complete === "string" ? data.verification_uri_complete : "";
+  return {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: verification,
+    interval: typeof data.interval === "number" && data.interval > 0 ? data.interval : 5,
+    expiresIn: typeof data.expires_in === "number" && data.expires_in > 0 ? data.expires_in : 900
+  };
+}
+async function pollDeviceToken(config, grant, deps) {
+  const deadline = deps.now() + grant.expiresIn * 1e3;
+  let intervalMs = grant.interval * 1e3;
+  while (deps.now() < deadline) {
+    let res;
+    try {
+      res = await deps.fetch(config.tokenEndpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json"
+        },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          device_code: grant.deviceCode,
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+        }).toString()
+      });
+    } catch (err) {
+      throw new AuthCallbackError(
+        "oauth_token_exchange_failed",
+        `device token poll failed: ${err.message}`
+      );
+    }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok && typeof data.error !== "string") {
+      throw new AuthCallbackError(
+        "oauth_token_exchange_failed",
+        `device token endpoint returned HTTP ${res.status}`
+      );
+    }
+    if (typeof data.access_token === "string" && data.access_token.length > 0) {
+      const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 0;
+      const accountId = extractAccountId({
+        access_token: data.access_token,
+        id_token: data.id_token
+      });
+      return {
+        access: data.access_token,
+        // Some device-grant providers (e.g. GitHub) issue no separate refresh token — reuse the access
+        // token as the refresh handle, mirroring OpenCode's copilot flow.
+        refresh: data.refresh_token ?? data.access_token,
+        expires: deps.now() + expiresIn * 1e3,
+        ...accountId !== void 0 ? { accountId } : {}
+      };
+    }
+    if (data.error === "authorization_pending") {
+      await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
+      continue;
+    }
+    if (data.error === "slow_down") {
+      intervalMs = (typeof data.interval === "number" && data.interval > 0 ? data.interval : grant.interval + 5) * 1e3;
+      await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
+      continue;
+    }
+    if (typeof data.error === "string") {
+      throw new AuthCallbackError(
+        "oauth_token_exchange_failed",
+        `device authorization rejected: ${data.error}`
+      );
+    }
+    await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
+  }
+  throw new AuthCallbackError(
+    "oauth_device_code_expired",
+    "the device code expired before it was approved"
+  );
+}
+async function deviceLogin(config, deps, hooks) {
+  const grant = await requestDeviceCode(config, deps);
+  hooks.onPrompt({
+    userCode: grant.userCode,
+    verificationUri: grant.verificationUri,
+    expiresIn: grant.expiresIn
+  });
+  return pollDeviceToken(config, grant, deps);
+}
+async function requestOpenAIUsercode(config, deps) {
+  let res;
+  try {
+    res = await deps.fetch(config.deviceUsercodeEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ client_id: config.clientId })
+    });
+  } catch (err) {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      `usercode request failed: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      `usercode endpoint returned HTTP ${res.status}`
+    );
+  }
+  const data = await res.json();
+  if (typeof data.device_auth_id !== "string" || typeof data.user_code !== "string") {
+    throw new AuthCallbackError(
+      "oauth_device_authorization_failed",
+      "usercode response missing device_auth_id/user_code"
+    );
+  }
+  const interval = Math.max(
+    typeof data.interval === "string" ? parseInt(data.interval, 10) || 5 : 5,
+    1
+  );
+  return { deviceAuthId: data.device_auth_id, userCode: data.user_code, interval };
+}
+async function openaiDeviceLogin(config, deps, hooks) {
+  const { deviceAuthId, userCode, interval } = await requestOpenAIUsercode(config, deps);
+  hooks.onPrompt({ userCode, verificationUri: config.verificationUri });
+  const intervalMs = interval * 1e3;
+  const deadline = deps.now() + 15 * 60 * 1e3;
+  while (deps.now() < deadline) {
+    let res;
+    try {
+      res = await deps.fetch(config.devicePollEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ device_auth_id: deviceAuthId, user_code: userCode })
+      });
+    } catch (err) {
+      throw new AuthCallbackError(
+        "oauth_token_exchange_failed",
+        `device poll failed: ${err.message}`
+      );
+    }
+    if (res.ok) {
+      const data = await res.json();
+      if (typeof data.authorization_code !== "string" || typeof data.code_verifier !== "string") {
+        throw new AuthCallbackError(
+          "oauth_token_exchange_failed",
+          "device poll returned no authorization_code"
+        );
+      }
+      return exchangeCode(
+        config,
+        { code: data.authorization_code, verifier: data.code_verifier },
+        deps
+      );
+    }
+    if (res.status !== 403 && res.status !== 404) {
+      throw new AuthCallbackError(
+        "oauth_token_exchange_failed",
+        `device poll returned HTTP ${res.status}`
+      );
+    }
+    await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
+  }
+  throw new AuthCallbackError(
+    "oauth_device_code_expired",
+    "the device authorization expired before approval"
+  );
+}
+function parseJwtClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return void 0;
+  try {
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString());
+  } catch {
+    return void 0;
+  }
+}
+function extractAccountId(tokens) {
+  for (const token of [tokens.id_token, tokens.access_token]) {
+    if (token === void 0) continue;
+    const claims = parseJwtClaims(token);
+    const id = claims?.chatgpt_account_id ?? claims?.["https://api.openai.com/auth"]?.chatgpt_account_id ?? claims?.organizations?.[0]?.id;
+    if (id !== void 0) return id;
+  }
+  return void 0;
+}
+
+// src/internal/auth/resolve-credential.ts
+async function resolveOAuth(stored, path, opts, env) {
+  if (stored.provider !== opts.provider) return void 0;
+  const base = {
+    kind: "oauth",
+    provider: opts.provider,
+    apiKey: stored.access,
+    source: path,
+    inferred: false,
+    expiresAt: stored.expires
+  };
+  if (opts.oauth === void 0) return base;
+  const deps = {
+    fetch: opts.deps?.fetch ?? fetch,
+    now: opts.deps?.now ?? (() => Date.now())
+  };
+  return ensureFreshCredential(base, { config: opts.oauth, store: opts.store, env }, deps);
+}
+async function resolveCredential(opts) {
+  const env = opts.env ?? {};
+  const stored = readAuthFile(opts.store, env);
+  if (stored === void 0) return void 0;
+  const path = authFilePath(opts.store, env);
+  if (stored.type === "oauth") {
+    return resolveOAuth(stored, path, opts, env);
+  }
+  if (stored.api_key.length === 0) return void 0;
+  if (stored.provider !== void 0 && stored.provider !== opts.provider) return void 0;
+  return {
+    kind: "api",
+    provider: opts.provider,
+    apiKey: stored.api_key,
+    source: path,
+    inferred: stored.provider === void 0
+  };
+}
+
+exports.CredentialError = CredentialError;
+exports.authFilePath = authFilePath;
+exports.credentialHome = credentialHome;
+exports.deviceLogin = deviceLogin;
+exports.ensureFreshCredential = ensureFreshCredential;
+exports.exchangeCode = exchangeCode;
+exports.extractAccountId = extractAccountId;
+exports.openaiDeviceLogin = openaiDeviceLogin;
+exports.parseJwtClaims = parseJwtClaims;
+exports.persistOAuthTokens = persistOAuthTokens;
+exports.pollDeviceToken = pollDeviceToken;
+exports.readAuthFile = readAuthFile;
+exports.readStoredOAuth = readStoredOAuth;
+exports.refreshOAuthTokens = refreshOAuthTokens;
+exports.requestDeviceCode = requestDeviceCode;
+exports.requestOpenAIUsercode = requestOpenAIUsercode;
+exports.resolveCredential = resolveCredential;
+exports.writeCredential = writeCredential;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map