@kleora-io/core 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,720 @@
+import { randomUUID } from 'crypto';
+import { readFileSync, mkdirSync, chmodSync, writeFileSync, renameSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// src/errors.ts
+var KleoraToolError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "KleoraToolError";
+    this.code = code;
+  }
+};
+var ApiError = class extends KleoraToolError {
+  type;
+  title;
+  status;
+  detail;
+  problem;
+  constructor(type, status, title, detail, problem) {
+    super("api_error", detail ?? title ?? type);
+    this.name = "ApiError";
+    this.type = type;
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.problem = problem;
+  }
+  /** The RFC 9457 document, verbatim plus its four standard fields. */
+  toProblemDocument() {
+    return {
+      type: this.type,
+      title: this.title,
+      status: this.status,
+      detail: this.detail,
+      ...this.problem.document
+    };
+  }
+};
+var ManagementApiUnreachable = class extends KleoraToolError {
+  constructor(message, options) {
+    super("management_api_unreachable", message, options);
+    this.name = "ManagementApiUnreachable";
+  }
+};
+var AuthorizationDenied = class extends KleoraToolError {
+  constructor() {
+    super("access_denied", "The device authorization was denied.");
+    this.name = "AuthorizationDenied";
+  }
+};
+function defaultConfigDir(name) {
+  return join(homedir(), `.${name}`);
+}
+async function createCredentialStore({
+  service,
+  configDir
+}) {
+  const fileStore = new FileCredentialStore(configDir);
+  const keyring = await loadKeyring();
+  if (keyring === null) return fileStore;
+  return new KeychainCredentialStore(service, keyring, fileStore);
+}
+async function loadKeyring() {
+  try {
+    return await import('@napi-rs/keyring');
+  } catch {
+    return null;
+  }
+}
+var KeychainCredentialStore = class {
+  backend = "keychain";
+  #service;
+  #keyring;
+  #fallback;
+  /** Set once any call fails, so a dead keychain is not retried per call. */
+  #broken = false;
+  constructor(service, keyring, fallback) {
+    this.#service = service;
+    this.#keyring = keyring;
+    this.#fallback = fallback;
+  }
+  async get(profile) {
+    if (this.#broken) return this.#fallback.get(profile);
+    try {
+      const entry = new this.#keyring.AsyncEntry(this.#service, profile);
+      const value = await entry.getPassword();
+      return value ?? null;
+    } catch {
+      this.#broken = true;
+      return this.#fallback.get(profile);
+    }
+  }
+  async set(profile, refreshToken) {
+    if (this.#broken) return this.#fallback.set(profile, refreshToken);
+    try {
+      const entry = new this.#keyring.AsyncEntry(this.#service, profile);
+      await entry.setPassword(refreshToken);
+    } catch {
+      this.#broken = true;
+      await this.#fallback.set(profile, refreshToken);
+    }
+  }
+  async delete(profile) {
+    if (this.#broken) return this.#fallback.delete(profile);
+    try {
+      const entry = new this.#keyring.AsyncEntry(this.#service, profile);
+      await entry.deleteCredential();
+    } catch {
+      this.#broken = true;
+      await this.#fallback.delete(profile);
+    }
+  }
+};
+var FileCredentialStore = class {
+  backend = "file";
+  #dir;
+  constructor(dir) {
+    this.#dir = dir;
+  }
+  // Every one of these is synchronous under the hood (`node:fs`'s sync API,
+  // deliberately — this runs at most once per tool call, never in a hot
+  // loop) but returns a `Promise` regardless, so `KeychainCredentialStore`
+  // can fall back to it without its callers caring which backend answered.
+  get(profile) {
+    try {
+      const raw = readFileSync(this.#path(profile), "utf8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "object" && parsed !== null && "refreshToken" in parsed) {
+        const refreshToken = parsed.refreshToken;
+        if (typeof refreshToken === "string") return Promise.resolve(refreshToken);
+      }
+      return Promise.resolve(null);
+    } catch (error) {
+      if (isNotFound(error)) return Promise.resolve(null);
+      return Promise.reject(asError(error));
+    }
+  }
+  set(profile, refreshToken) {
+    try {
+      mkdirSync(this.#dir, { recursive: true, mode: 448 });
+      chmodSync(this.#dir, 448);
+      const path = this.#path(profile);
+      const tmp = `${path}.${randomUUID()}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ refreshToken }), { mode: 384 });
+      chmodSync(tmp, 384);
+      renameSync(tmp, path);
+      return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(asError(error));
+    }
+  }
+  delete(profile) {
+    try {
+      rmSync(this.#path(profile));
+      return Promise.resolve();
+    } catch (error) {
+      if (isNotFound(error)) return Promise.resolve();
+      return Promise.reject(asError(error));
+    }
+  }
+  #path(profile) {
+    return join(this.#dir, `credentials-${encodeURIComponent(profile)}.json`);
+  }
+};
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function asError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+// src/credentials/device-grant.ts
+var OAuthError = class extends Error {
+  code;
+  constructor(code, description) {
+    super(description ?? code);
+    this.name = "OAuthError";
+    this.code = code;
+  }
+};
+async function postForm(url, body, fetchImpl, userAgent) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+        "User-Agent": userAgent
+      },
+      body: new URLSearchParams(body)
+    });
+  } catch (error) {
+    throw new ManagementApiUnreachable(`could not reach ${url}`, { cause: error });
+  }
+  let document = {};
+  try {
+    document = await response.json();
+  } catch {
+  }
+  if (!response.ok) {
+    const rawCode = typeof document["error"] === "string" ? document["error"] : "other";
+    const code = isKnownCode(rawCode) ? rawCode : "other";
+    const description = typeof document["error_description"] === "string" ? document["error_description"] : void 0;
+    throw new OAuthError(code, description);
+  }
+  return document;
+}
+function isKnownCode(value) {
+  return [
+    "authorization_pending",
+    "slow_down",
+    "access_denied",
+    "expired_token",
+    "invalid_grant",
+    "unauthorized_client"
+  ].includes(value);
+}
+async function startDeviceAuthorization({
+  issuer,
+  clientId,
+  userAgent,
+  fetch: fetchImpl
+}) {
+  const document = await postForm(
+    `${issuer}/oauth/device_authorization`,
+    { client_id: clientId },
+    fetchImpl,
+    userAgent
+  );
+  return {
+    deviceCode: requireString(document, "device_code"),
+    userCode: requireString(document, "user_code"),
+    verificationUri: requireString(document, "verification_uri"),
+    verificationUriComplete: typeof document["verification_uri_complete"] === "string" ? document["verification_uri_complete"] : requireString(document, "verification_uri"),
+    expiresIn: requireNumber(document, "expires_in"),
+    interval: typeof document["interval"] === "number" ? document["interval"] : 5
+  };
+}
+async function pollDeviceToken({
+  issuer,
+  clientId,
+  deviceCode,
+  userAgent,
+  fetch: fetchImpl
+}) {
+  const document = await postForm(
+    `${issuer}/oauth/token`,
+    {
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: deviceCode,
+      client_id: clientId
+    },
+    fetchImpl,
+    userAgent
+  );
+  return tokensOf(document);
+}
+async function refreshAccessToken({
+  issuer,
+  clientId,
+  refreshToken,
+  userAgent,
+  fetch: fetchImpl
+}) {
+  const document = await postForm(
+    `${issuer}/oauth/token`,
+    { grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId },
+    fetchImpl,
+    userAgent
+  );
+  return tokensOf(document);
+}
+async function revokeRefreshToken({
+  issuer,
+  clientId,
+  refreshToken,
+  userAgent,
+  fetch: fetchImpl
+}) {
+  await postForm(
+    `${issuer}/oauth/revoke`,
+    { token: refreshToken, token_type_hint: "refresh_token", client_id: clientId },
+    fetchImpl,
+    userAgent
+  );
+}
+function tokensOf(document) {
+  return {
+    accessToken: requireString(document, "access_token"),
+    refreshToken: typeof document["refresh_token"] === "string" ? document["refresh_token"] : void 0,
+    expiresIn: requireNumber(document, "expires_in")
+  };
+}
+function requireString(document, key) {
+  const value = document[key];
+  if (typeof value !== "string") throw new ManagementApiUnreachable(`the issuer's response has no '${key}'`);
+  return value;
+}
+function requireNumber(document, key) {
+  const value = document[key];
+  if (typeof value !== "number") throw new ManagementApiUnreachable(`the issuer's response has no '${key}'`);
+  return value;
+}
+
+// src/credentials/issuer.ts
+var PLATFORM_PATH = "/api/v1/platform";
+async function discoverIssuer({
+  baseUrl,
+  userAgent,
+  fetch: fetchImpl = globalThis.fetch
+}) {
+  const url = `${baseUrl}${PLATFORM_PATH}`;
+  const hint = "Check the API base URL, or pass the issuer explicitly.";
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { Accept: "application/json", "User-Agent": userAgent }
+    });
+  } catch (error) {
+    throw new ManagementApiUnreachable(`could not reach ${url} to find the issuer. ${hint}`, {
+      cause: error
+    });
+  }
+  if (!response.ok) {
+    throw new ManagementApiUnreachable(
+      `${url} answered ${String(response.status)}, so the issuer is unknown. ${hint}`
+    );
+  }
+  let document;
+  try {
+    document = await response.json();
+  } catch {
+    document = null;
+  }
+  const issuer = typeof document === "object" && document !== null ? document["issuer"] : void 0;
+  if (typeof issuer !== "string" || !isHttpUrl(issuer)) {
+    throw new ManagementApiUnreachable(`${url} did not name an issuer. ${hint}`);
+  }
+  return issuer.replace(/\/+$/, "");
+}
+function issuerResolver(explicit, options) {
+  if (explicit !== void 0) {
+    const value = explicit;
+    return () => Promise.resolve(value);
+  }
+  let pending = null;
+  return () => {
+    pending ??= discoverIssuer(options).catch((error) => {
+      pending = null;
+      throw error;
+    });
+    return pending;
+  };
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+// src/credentials/session.ts
+var SessionNotReady = class extends Error {
+  state;
+  constructor(state) {
+    super(`session not ready: ${state.status}`);
+    this.name = "SessionNotReady";
+    this.state = state;
+  }
+};
+var Session = class {
+  #issuer;
+  #clientId;
+  #profile;
+  #store;
+  #userAgent;
+  #fetch;
+  #skewMs;
+  #accessToken = null;
+  #accessTokenExpiresAt = 0;
+  #pending = null;
+  constructor(options) {
+    const issuer = options.issuer;
+    this.#issuer = typeof issuer === "string" ? () => Promise.resolve(issuer) : issuer;
+    this.#clientId = options.clientId;
+    this.#profile = options.profile;
+    this.#store = options.store;
+    this.#userAgent = options.userAgent;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#skewMs = (options.clockSkewSeconds ?? 30) * 1e3;
+  }
+  /**
+   * The access token to call the management API with, or the instructions to
+   * show the person instead of a result: "not an error — this is the
+   * sign-in."
+   */
+  async ensureAccessToken() {
+    if (this.#accessToken !== null && Date.now() < this.#accessTokenExpiresAt - this.#skewMs) {
+      return { status: "ready", accessToken: this.#accessToken };
+    }
+    const fromRefresh = await this.#tryStoredCredential();
+    if (fromRefresh !== null) return fromRefresh;
+    return this.#advanceDeviceFlow();
+  }
+  /**
+   * An access token from the **stored** credential only — never starting a
+   * device flow.
+   *
+   * This is the CLI's entry point rather than `ensureAccessToken` above, and
+   * the difference is a deliberate behavioural split rather than a
+   * convenience. With no credential for the profile, a CLI command says so
+   * and names `kleora login`, exiting `3`. **It does not start a device flow
+   * unbidden**: an interactive sign-in in the middle of a piped command is a
+   * hang.
+   *
+   * An MCP host, by contrast, has a place to show a verification URL and a
+   * turn to show it on, which is why `ensureAccessToken` may begin one there.
+   * `null` means "nothing stored, or what was stored is dead and has been
+   * deleted" — both of which the caller answers with the same sentence.
+   */
+  async accessTokenFromStoredCredential() {
+    if (this.#accessToken !== null && Date.now() < this.#accessTokenExpiresAt - this.#skewMs) {
+      return this.#accessToken;
+    }
+    const state = await this.#tryStoredCredential();
+    return state !== null && state.status === "ready" ? state.accessToken : null;
+  }
+  /** Forces the next call to re-authorise, even if a token is cached in memory. */
+  invalidate() {
+    this.#accessToken = null;
+    this.#accessTokenExpiresAt = 0;
+  }
+  /** `null` means "no usable stored credential — try the device flow instead". */
+  async #tryStoredCredential() {
+    const stored = await this.#store.get(this.#profile);
+    if (stored === null) return null;
+    let tokens;
+    try {
+      tokens = await refreshAccessToken({
+        issuer: await this.#issuer(),
+        clientId: this.#clientId,
+        refreshToken: stored,
+        userAgent: this.#userAgent,
+        fetch: this.#fetch
+      });
+    } catch (error) {
+      if (error instanceof OAuthError) {
+        await this.#store.delete(this.#profile);
+        return null;
+      }
+      throw error;
+    }
+    await this.#storeTokens(tokens);
+    return { status: "ready", accessToken: tokens.accessToken };
+  }
+  /** Starts a device flow if none is pending, or polls the one already running. */
+  async #advanceDeviceFlow() {
+    if (this.#pending === null || Date.now() >= this.#pending.expiresAt) {
+      const auth = await startDeviceAuthorization({
+        issuer: await this.#issuer(),
+        clientId: this.#clientId,
+        userAgent: this.#userAgent,
+        fetch: this.#fetch
+      });
+      this.#pending = {
+        deviceCode: auth.deviceCode,
+        interval: auth.interval,
+        expiresAt: Date.now() + auth.expiresIn * 1e3,
+        verificationUri: auth.verificationUri,
+        verificationUriComplete: auth.verificationUriComplete,
+        userCode: auth.userCode,
+        lastPollAt: 0
+      };
+      return this.#pendingState(
+        "No Kleora credential is authorised yet. Open the verification URL, enter the code, and approve. Then call this tool again."
+      );
+    }
+    const pending = this.#pending;
+    pending.lastPollAt = Date.now();
+    try {
+      const tokens = await pollDeviceToken({
+        issuer: await this.#issuer(),
+        clientId: this.#clientId,
+        deviceCode: pending.deviceCode,
+        userAgent: this.#userAgent,
+        fetch: this.#fetch
+      });
+      this.#pending = null;
+      await this.#storeTokens(tokens);
+      return { status: "ready", accessToken: tokens.accessToken };
+    } catch (error) {
+      if (!(error instanceof OAuthError)) throw error;
+      switch (error.code) {
+        case "authorization_pending":
+          return this.#pendingState("Still waiting for approval in the browser.");
+        case "slow_down":
+          pending.interval += 5;
+          return this.#pendingState(
+            `Polling too fast; the issuer asked for a wider interval. Wait a little longer before retrying.`
+          );
+        case "access_denied":
+          this.#pending = null;
+          return { status: "denied" };
+        case "expired_token":
+          this.#pending = null;
+          return this.#advanceDeviceFlow();
+        default:
+          throw new ManagementApiUnreachable(`the issuer refused the poll: ${error.code}`, {
+            cause: error
+          });
+      }
+    }
+  }
+  async #storeTokens(tokens) {
+    this.#accessToken = tokens.accessToken;
+    this.#accessTokenExpiresAt = Date.now() + tokens.expiresIn * 1e3;
+    if (tokens.refreshToken !== void 0) {
+      await this.#store.set(this.#profile, tokens.refreshToken);
+    }
+  }
+  #pendingState(message) {
+    const pending = this.#pending;
+    if (pending === null) throw new Error("invariant: #pendingState called with no pending flow");
+    return {
+      status: "authorization_required",
+      verificationUri: pending.verificationUri,
+      verificationUriComplete: pending.verificationUriComplete,
+      userCode: pending.userCode,
+      message
+    };
+  }
+};
+
+// src/management-client.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_CONCURRENT = 4;
+var MAX_RETRIES = 3;
+var ManagementClient = class {
+  baseUrl;
+  #getAccessToken;
+  #userAgent;
+  #fetch;
+  #timeoutMs;
+  #maxConcurrent;
+  #onTrace;
+  #inFlight = 0;
+  #queue = [];
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.#getAccessToken = options.getAccessToken;
+    this.#userAgent = options.userAgent;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    this.#onTrace = options.onTrace;
+  }
+  /**
+   * Calls one operation and parses the body. `args` is a flat argument
+   * object; this method is what splits it back into path, query and body using
+   * the operation's own metadata — never a lookup this package invents.
+   */
+  async call(operation, args, options = {}) {
+    const response = await this.request(operation, args, options);
+    if (response.status === 204 || response.text === "") return void 0;
+    return JSON.parse(response.text);
+  }
+  /** The same call, with the body left as the bytes that arrived. */
+  async request(operation, args, options = {}) {
+    await this.#acquire();
+    try {
+      return await this.#withRetry(operation, args, options, 0);
+    } finally {
+      this.#release();
+    }
+  }
+  async #withRetry(operation, args, options, attempt) {
+    const url = this.#urlFor(operation, args);
+    const body = this.#bodyFor(operation, args);
+    const token = await this.#getAccessToken();
+    const headers = {
+      Accept: "application/json, application/problem+json",
+      ...options.headers ?? {},
+      Authorization: `Bearer ${token}`,
+      "User-Agent": this.#userAgent
+    };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const method = operation.method.toUpperCase();
+    const startedAt = Date.now();
+    let response;
+    try {
+      response = await this.#fetch(url, {
+        method,
+        headers,
+        ...body === void 0 ? {} : { body: JSON.stringify(body) },
+        signal: AbortSignal.timeout(this.#timeoutMs)
+      });
+    } catch (error) {
+      this.#onTrace?.({
+        method,
+        path: url.pathname + url.search,
+        status: null,
+        durationMs: Date.now() - startedAt,
+        requestId: void 0,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw new ManagementApiUnreachable(`could not reach ${this.baseUrl}`, { cause: error });
+    }
+    this.#onTrace?.({
+      method,
+      path: url.pathname + url.search,
+      status: response.status,
+      durationMs: Date.now() - startedAt,
+      requestId: response.headers.get("x-request-id") ?? void 0
+    });
+    if (response.status === 429 && attempt < MAX_RETRIES && options.idempotent !== false) {
+      const retryAfter = retryAfterSeconds(response);
+      if (retryAfter !== null) {
+        await sleep(retryAfter * 1e3);
+        return this.#withRetry(operation, args, options, attempt + 1);
+      }
+    }
+    if (!response.ok) throw await toApiError(response);
+    return {
+      status: response.status,
+      text: response.status === 204 ? "" : await response.text(),
+      headers: response.headers
+    };
+  }
+  #urlFor(operation, args) {
+    const path = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
+      const value = args[name];
+      if (typeof value !== "string" || value === "") {
+        throw new Error(`operation '${operation.operationId}' needs a path parameter '${name}'`);
+      }
+      return encodeURIComponent(value);
+    });
+    const url = new URL(this.baseUrl + path);
+    for (const name of operation.queryParams) {
+      const value = args[name];
+      if (value === void 0 || value === null) continue;
+      for (const item of Array.isArray(value) ? value : [value]) {
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+          url.searchParams.append(name, String(item));
+        }
+      }
+    }
+    return url;
+  }
+  #bodyFor(operation, args) {
+    if (!operation.hasBody) return void 0;
+    const excluded = /* @__PURE__ */ new Set([...operation.pathParams, ...operation.queryParams]);
+    const body = {};
+    for (const [name, value] of Object.entries(args)) {
+      if (excluded.has(name)) continue;
+      if (value !== void 0) body[name] = value;
+    }
+    return body;
+  }
+  /** A tiny counting semaphore — no dependency for something this small. */
+  #acquire() {
+    if (this.#inFlight < this.#maxConcurrent) {
+      this.#inFlight++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.#queue.push(() => {
+        this.#inFlight++;
+        resolve();
+      });
+    });
+  }
+  #release() {
+    this.#inFlight--;
+    const next = this.#queue.shift();
+    if (next) next();
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retryAfterSeconds(response) {
+  const raw = response.headers.get("retry-after")?.trim();
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds, 60);
+  const at = Date.parse(raw);
+  if (Number.isFinite(at)) return Math.min(Math.max(0, Math.round((at - Date.now()) / 1e3)), 60);
+  return null;
+}
+async function toApiError(response) {
+  let document = {};
+  try {
+    const body = JSON.parse(await response.text());
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+      document = body;
+    }
+  } catch {
+  }
+  const problem = {
+    document,
+    retryAfter: retryAfterSeconds(response),
+    requestId: typeof document["request_id"] === "string" ? document["request_id"] : response.headers.get("x-request-id") ?? void 0
+  };
+  return new ApiError(
+    typeof document["type"] === "string" ? document["type"] : "about:blank",
+    response.status,
+    typeof document["title"] === "string" ? document["title"] : void 0,
+    typeof document["detail"] === "string" ? document["detail"] : void 0,
+    problem
+  );
+}
+
+export { ApiError, AuthorizationDenied, FileCredentialStore, KleoraToolError, ManagementApiUnreachable, ManagementClient, OAuthError, PLATFORM_PATH, Session, SessionNotReady, createCredentialStore, defaultConfigDir, discoverIssuer, issuerResolver, pollDeviceToken, refreshAccessToken, retryAfterSeconds, revokeRefreshToken, startDeviceAuthorization };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map