@zksecurity/zkao-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,335 @@
+// src/base-url.ts
+var DEFAULT_BASE_URL = "https://zkao.io/api/v1";
+var LOCAL_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1",
+  "[::1]"
+]);
+function unquote(value) {
+  return value.trim().replace(/^['"]+|['"]+$/g, "").trim();
+}
+function isLocalHost(host) {
+  return LOCAL_HOSTS.has(host.toLowerCase());
+}
+function normalizeBaseUrl(value) {
+  const cleaned = unquote(value);
+  if (cleaned.length === 0) {
+    throw new Error("ZKAO_URL is empty");
+  }
+  let withScheme = cleaned;
+  if (!/^https?:\/\//i.test(withScheme)) {
+    const slash = withScheme.indexOf("/");
+    let authority = slash === -1 ? withScheme : withScheme.slice(0, slash);
+    const rest = slash === -1 ? "" : withScheme.slice(slash);
+    let bareHost;
+    if (authority.startsWith("[")) {
+      const end = authority.indexOf("]");
+      bareHost = end === -1 ? authority : authority.slice(0, end + 1);
+    } else if (authority.split(":").length > 2) {
+      bareHost = authority;
+      authority = `[${authority}]`;
+    } else {
+      bareHost = authority.split(":")[0] ?? "";
+    }
+    withScheme = `${isLocalHost(bareHost) ? "http" : "https"}://${authority}${rest}`;
+  }
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch (err) {
+    throw new Error(`Invalid ZKAO_URL: ${JSON.stringify(value)}`, {
+      cause: err
+    });
+  }
+  if (url.protocol === "http:" && !isLocalHost(url.hostname)) {
+    console.warn(
+      `zkao: ZKAO_URL points at plaintext http://${url.hostname}; the API token will be sent unencrypted.`
+    );
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  const apiPath = /\/api\/v\d+$/.test(path) ? path : `${path}/api/v1`;
+  return `${url.origin}${apiPath}`;
+}
+function readEnv(env) {
+  if (env) {
+    return env;
+  }
+  const proc = globalThis.process;
+  return proc?.env ?? {};
+}
+function resolveBaseUrlFromEnv(env) {
+  const source = readEnv(env);
+  const origin = source.ZKAO_URL ? unquote(source.ZKAO_URL) : "";
+  if (origin.length > 0) {
+    return normalizeBaseUrl(origin);
+  }
+  return void 0;
+}
+
+// src/client.ts
+import createClient from "openapi-fetch";
+var TERMINAL_SCAN_STATUSES = [
+  "COMPLETED",
+  "FAILED",
+  "CANCELLED"
+];
+function isTerminalScanStatus(status) {
+  return TERMINAL_SCAN_STATUSES.includes(status);
+}
+var ZkaoApiError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.name = "ZkaoApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
+function unwrap(result) {
+  if (result.response.ok && result.data !== void 0) {
+    return result.data;
+  }
+  const envelope = result.error;
+  throw new ZkaoApiError(
+    result.response.status,
+    envelope?.error?.code ?? "error",
+    envelope?.error?.message ?? result.response.statusText
+  );
+}
+var ZkaoClient = class {
+  http;
+  projectId;
+  constructor(options) {
+    this.projectId = options.projectId;
+    this.http = createClient({
+      baseUrl: options.baseUrl ?? resolveBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
+      headers: { Authorization: `Bearer ${options.token}` },
+      ...options.fetch ? { fetch: options.fetch } : {}
+    });
+  }
+  get path() {
+    return { projectId: this.projectId };
+  }
+  // --- Repositories -------------------------------------------------------
+  async listRepositories() {
+    const res = await this.http.GET("/projects/{projectId}/repositories", {
+      params: { path: this.path }
+    });
+    return unwrap(res).repositories;
+  }
+  /** Read a repository's configured guidance (requires the `read` scope). */
+  async getRepositoryGuidance(repositoryId) {
+    const res = await this.http.GET(
+      "/projects/{projectId}/repositories/{repositoryId}/guidance",
+      { params: { path: { ...this.path, repositoryId } } }
+    );
+    return unwrap(res);
+  }
+  /**
+   * Set (or clear, with `null`) a repository's guidance (requires the
+   * `guidance:write` scope). Pass `expectedContent` for an optimistic
+   * compare-and-set: send the content you last read (or `null` for "currently
+   * cleared") to get a `409` instead of clobbering a concurrent change. Writing
+   * the same content that is already stored is a no-op (`unchanged: true`).
+   */
+  async setRepositoryGuidance(repositoryId, content, opts = {}) {
+    const res = await this.http.PUT(
+      "/projects/{projectId}/repositories/{repositoryId}/guidance",
+      {
+        params: { path: { ...this.path, repositoryId } },
+        body: "expectedContent" in opts ? { content, expectedContent: opts.expectedContent } : { content }
+      }
+    );
+    return unwrap(res);
+  }
+  // --- Scans --------------------------------------------------------------
+  async listScans(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/scans", {
+      params: { path: this.path, query: { page: opts.page, limit: opts.limit } }
+    });
+    return unwrap(res);
+  }
+  async getScan(scanId) {
+    const res = await this.http.GET("/projects/{projectId}/scans/{scanId}", {
+      params: { path: { ...this.path, scanId } }
+    });
+    return unwrap(res).scan;
+  }
+  /**
+   * Poll a scan until it reaches a terminal status (COMPLETED / FAILED /
+   * CANCELLED) and return the final detail. Honors the server's `Retry-After`
+   * header when present; otherwise backs off exponentially with jitter between
+   * `intervalMs` and `maxIntervalMs`. A `429` is treated as "slow down", not an
+   * error. Prefer this over a hand-rolled `getScan` loop so the server is not
+   * hammered.
+   */
+  async waitForScan(scanId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 5e3;
+    const maxIntervalMs = opts.maxIntervalMs ?? 3e4;
+    const timeoutMs = opts.timeoutMs ?? 60 * 60 * 1e3;
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(opts.signal);
+      const res = await this.http.GET("/projects/{projectId}/scans/{scanId}", {
+        params: { path: { ...this.path, scanId } },
+        signal: opts.signal
+      });
+      const retryAfterMs = parseRetryAfterMs(
+        res.response.headers.get("retry-after")
+      );
+      if (res.response.status !== 429) {
+        const scan = unwrap(res).scan;
+        if (isTerminalScanStatus(scan.status)) {
+          return scan;
+        }
+        opts.onPoll?.(scan);
+      }
+      const backoffMs = Math.min(
+        maxIntervalMs,
+        Math.round(intervalMs * 1.5 ** attempt)
+      );
+      const baseMs = retryAfterMs ?? backoffMs;
+      const delayMs = baseMs + Math.round(Math.random() * baseMs * 0.2);
+      if (Date.now() + delayMs > deadline) {
+        throw new Error(
+          `Timed out waiting for scan ${scanId} to finish after ${timeoutMs}ms`
+        );
+      }
+      await sleep(delayMs, opts.signal);
+    }
+  }
+  async launchScan(body) {
+    const res = await this.http.POST("/projects/{projectId}/scans", {
+      params: { path: this.path },
+      body
+    });
+    return unwrap(res);
+  }
+  /**
+   * Cancel a running or queued scan. Signals in-flight jobs to stop, marks the
+   * scan CANCELLED, and releases its reserved credits. A scan already in a
+   * terminal COMPLETED/FAILED state cannot be cancelled.
+   */
+  async cancelScan(scanId) {
+    const res = await this.http.POST("/projects/{projectId}/scans/{scanId}/cancel", {
+      params: { path: { ...this.path, scanId } }
+    });
+    return unwrap(res);
+  }
+  async publishScan(scanId, opts = {}) {
+    const res = await this.http.POST("/projects/{projectId}/scans/{scanId}/publish", {
+      params: { path: { ...this.path, scanId } },
+      body: { withPassword: opts.withPassword }
+    });
+    return unwrap(res);
+  }
+  // --- Findings -----------------------------------------------------------
+  async listFindings(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/findings", {
+      params: {
+        path: this.path,
+        query: { page: opts.page, limit: opts.limit, scanId: opts.scanId }
+      }
+    });
+    return unwrap(res);
+  }
+  async getFinding(findingId) {
+    const res = await this.http.GET("/projects/{projectId}/findings/{findingId}", {
+      params: { path: { ...this.path, findingId } }
+    });
+    return unwrap(res).finding;
+  }
+  async addFindingNote(findingId, content) {
+    const res = await this.http.POST("/projects/{projectId}/findings/{findingId}/notes", {
+      params: { path: { ...this.path, findingId } },
+      body: { content }
+    });
+    return unwrap(res);
+  }
+  async pinFindingNote(findingId, noteId, kind = "resolution") {
+    const res = await this.http.POST(
+      "/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin",
+      { params: { path: { ...this.path, findingId, noteId } }, body: { kind } }
+    );
+    return unwrap(res);
+  }
+  async setFindingSeverity(findingId, severity) {
+    const res = await this.http.PATCH("/projects/{projectId}/findings/{findingId}/severity", {
+      params: { path: { ...this.path, findingId } },
+      body: { severity }
+    });
+    return unwrap(res);
+  }
+  async setFindingResolution(findingId, resolutionStatus, note) {
+    const res = await this.http.PATCH("/projects/{projectId}/findings/{findingId}/resolution", {
+      params: { path: { ...this.path, findingId } },
+      body: { resolutionStatus, note }
+    });
+    return unwrap(res);
+  }
+  async publishFinding(findingId, opts = {}) {
+    const res = await this.http.POST("/projects/{projectId}/findings/{findingId}/publish", {
+      params: { path: { ...this.path, findingId } },
+      body: { noteId: opts.noteId, withPassword: opts.withPassword }
+    });
+    return unwrap(res);
+  }
+  // --- Discovery ----------------------------------------------------------
+  async listScanPresets() {
+    const res = await this.http.GET("/projects/{projectId}/scan-presets", {
+      params: { path: this.path }
+    });
+    return unwrap(res).presets;
+  }
+  async listOptionalFlows() {
+    const res = await this.http.GET("/projects/{projectId}/optional-flows", {
+      params: { path: this.path }
+    });
+    return unwrap(res).optionalFlows;
+  }
+};
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+  }
+}
+function parseRetryAfterMs(value) {
+  if (!value) {
+    return null;
+  }
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return Math.max(0, seconds * 1e3);
+  }
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("Aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason instanceof Error ? signal.reason : new Error("Aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+export {
+  DEFAULT_BASE_URL,
+  TERMINAL_SCAN_STATUSES,
+  ZkaoApiError,
+  ZkaoClient,
+  isTerminalScanStatus,
+  normalizeBaseUrl,
+  resolveBaseUrlFromEnv
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zksecurity/zkao-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the zkao Project API",
+  "license": "MIT",
+  "author": "zkSecurity",
+  "homepage": "https://github.com/zksecurity/zkao-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zksecurity/zkao-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/zksecurity/zkao-sdk/issues",
+  "keywords": [
+    "zkao",
+    "security",
+    "audit",
+    "sdk",
+    "api",
+    "zero-knowledge"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "openapi-typescript ../../openapi/v1.yaml -o src/generated/types.ts",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.4.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  }
+}