@zksecurity/zkao-sdk 0.5.1 → 0.11.0-next.2

package/dist/index.d.ts

@@ -29,6 +29,26 @@ declare function resolveBaseUrlFromEnv(env?: Record<string, string | undefined>)
  * Do not make direct changes to the file.
  */
 interface paths {
+    "/token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The calling token and its project
+         * @description Any valid token may call this, whatever its scopes. Use it to learn which project (and organization) a token belongs to.
+         */
+        get: operations["getTokenInfo"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/projects/{projectId}/repositories": {
         parameters: {
             query?: never;
@@ -134,13 +154,21 @@ interface paths {
          * Launch a scan
          * @description Requires scope: `scans:launch`. Reserves `creditBudget` credits from the
          *     project balance. The repo must be in the token's allowlist (when set) and
-         *     ACTIVE. Discover valid `presetRef` / `optInFlowIds` via the discovery
-         *     endpoints. Per-token spend limits are enforced, and the project must have
-         *     enough prepaid credits to cover the budget (otherwise `402`).
+         *     ACTIVE. Discover valid `presetRef` values via `/scan-presets`. Each scan
+         *     type runs a fixed set of flows. Per-token spend limits are enforced, and
+         *     the project must have enough prepaid credits to cover the budget
+         *     (otherwise `402`).
          *
          *     A repository added moments ago may still be analyzing, in which case
          *     this returns `409 repository_initializing`. Wait for its `readiness` to
          *     be `ready` in `GET /repositories` and launch again.
+         *
+         *     A diff scan preset audits only the change from `baseCommit` to the
+         *     scanned commit, and requires `baseCommit`. Every other preset refuses
+         *     it. A malformed, unknown, or misplaced base is a `400` with code
+         *     `diff_base_required`, `diff_base_not_allowed`, or `diff_base_invalid`.
+         *     A diff scan also needs an earlier full scan of the branch, and a
+         *     change to audit (otherwise `422`).
          */
         post: operations["launchScan"];
         delete?: never;
@@ -369,26 +397,6 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/projects/{projectId}/optional-flows": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * List opt-in flows available at launch
-         * @description Requires scope: `read`. Pass the chosen ids as `optInFlowIds` when launching. A flow marked `rotating` may run without being asked for.
-         */
-        get: operations["listOptionalFlows"];
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/projects/{projectId}/billing/balance": {
         parameters: {
             query?: never;
@@ -397,8 +405,8 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Current prepaid credit balance
-         * @description Requires scope: `read`. All amounts are in credits.
+         * Credits available to this project
+         * @description Requires scope: `read`. The organization's shared prepaid balance, available to this project and to the organization's other projects. All amounts are in credits.
          */
         get: operations["getBillingBalance"];
         put?: never;
@@ -417,8 +425,8 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Credit usage events
-         * @description Requires scope: `read`. Signed credit delta per ledger event. Defaults to the last 30 days; newest first; max 1000 rows.
+         * Credit usage events attributed to this project
+         * @description Requires scope: `read`. Signed credit delta per ledger event attributed to this project; organization-wide movements such as a top-up made outside any project are not included. Defaults to the last 30 days; newest first; max 1000 rows.
          */
         get: operations["getBillingUsage"];
         put?: never;
@@ -437,8 +445,8 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Monthly spend and purchase summary
-         * @description Requires scope: `read`. Per-month net scan spend and net purchases, in credits, newest first.
+         * Monthly spend and purchase summary for this project
+         * @description Requires scope: `read`. Per-month net scan spend and net purchases attributed to this project, in credits, newest first. Purchases land in the organization's shared balance.
          */
         get: operations["getBillingSummary"];
         put?: never;
@@ -452,12 +460,38 @@ interface paths {
 }
 interface components {
     schemas: {
+        /** @description The organization a project belongs to. Credits are held and billed at this level and shared by every project in it. */
+        Organization: {
+            id: string;
+            /** @description URL segment of the organization (`/orgs/<slug>`), unique across zkao. */
+            slug: string;
+            name: string;
+        };
+        TokenInfo: {
+            id: string;
+            name: string;
+            scopes: string[];
+            /** @description Repositories the token is restricted to. Empty means every repository of the project. */
+            repositoryIds: string[];
+            /** Format: date-time */
+            expiresAt: string | null;
+            /** @description Credits this token may spend. Null means no limit. */
+            spendLimitCredits: number | null;
+            project: {
+                id: string;
+                slug: string;
+                name: string;
+                organization: components["schemas"]["Organization"];
+            };
+        };
         BillingBalance: {
-            /** @description Total prepaid credit balance. */
+            /** @description The organization whose shared balance this is. */
+            organization: components["schemas"]["Organization"];
+            /** @description The organization's total prepaid credit balance, shared by all of its projects. */
             balanceCredits: number;
-            /** @description Balance minus credits reserved by in-flight scans. */
+            /** @description Balance minus credits reserved by the organization's in-flight scans. */
             availableCredits: number;
-            /** @description Credits held by queued/running scans. */
+            /** @description Credits held by the organization's queued/running scans. */
             reservedCredits: number;
         };
         /** @enum {string} */
@@ -488,12 +522,14 @@ interface components {
             purchasedCredits: number;
         };
         BillingSummary: {
+            /** @description The organization whose shared balance the purchases were made into. */
+            organization: components["schemas"]["Organization"];
             months: components["schemas"]["UsageMonthSummary"][];
         };
         Error: {
             error: {
                 /** @enum {string} */
-                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "repository_initializing" | "rate_limited" | "internal";
+                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "repository_initializing" | "diff_base_required" | "diff_base_not_allowed" | "diff_base_invalid" | "diff_empty" | "diff_overview_missing" | "rate_limited" | "internal";
                 message: string;
             };
         };
@@ -507,6 +543,8 @@ interface components {
         ScanStatus: "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED";
         Repository: {
             id: string;
+            /** @description URL segment of the repository inside its project (`/orgs/<org>/projects/<project>/repos/<slug>`). Unique per project. */
+            slug: string;
             owner: string;
             name: string;
             url: string;
@@ -524,6 +562,8 @@ interface components {
             status: components["schemas"]["ScanStatus"];
             repositoryId: string;
             commitHash?: string | null;
+            /** @description A diff scan's base, as the merge base SHA its change is measured from. Null for other scans. */
+            baseCommit?: string | null;
             commitMessage?: string | null;
             presetName?: string | null;
             /** Format: date-time */
@@ -564,6 +604,11 @@ interface components {
             severity: components["schemas"]["Severity"];
             category: string;
             triageStatus: components["schemas"]["TriageStatus"];
+            /**
+             * @description What backs a CONFIRMED verdict. POC means a proof of concept ran and demonstrated the issue. ANALYSIS means it was confirmed by code analysis alone. Null for other statuses or when not recorded.
+             * @enum {string|null}
+             */
+            confirmationEvidence?: "POC" | "ANALYSIS" | null;
             resolutionStatus: components["schemas"]["ResolutionStatus"];
             notesCount: number;
         };
@@ -610,23 +655,14 @@ interface components {
             ref: string;
             name: string;
             description?: string | null;
-            /** @description Minimum budget for a launch that names no optInFlowIds. Adding a flow raises it. 0 = use the default floor. */
+            /** @description Minimum budget for a launch. 0 = use the default floor. */
             minCredits: number;
             modelTier: string;
         };
-        OptionalFlow: {
-            /** @description Pass in `optInFlowIds` when launching. */
-            id: string;
-            flowId: string;
-            title: string;
-            description: string;
-            /** @description True when this flow belongs to a group the preset rotates through. Some of the group runs on every scan without being asked for, and which members depends on the repository. Naming it in `optInFlowIds` adds it whether or not the rotation picked it, and raises the scan's minimum budget. */
-            rotating: boolean;
-        };
         LaunchScanRequest: {
             repositoryId: string;
-            /** @description Max budget for the scan, in credits. Reserved at launch. */
-            creditBudget: number;
+            /** @description Max budget for the scan, in credits. Reserved at launch. Omit it to launch at the budget zkao recommends for this scan type and scope on this repository: sized from what past scans of it spent, half again the last budget when that scan ran short of it, or the scan type's minimum on the first. */
+            creditBudget?: number;
             /** @description A preset ref from /scan-presets. Defaults to the first active preset. */
             presetRef?: string;
             /** @description Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set. */
@@ -634,8 +670,8 @@ interface components {
             /** @description Pin a specific commit SHA (7-40 hex chars). */
             commitHash?: string | null;
             commitMessage?: string | null;
-            /** @description Optional-flow ids from /optional-flows, added to the scan on top of whatever a rotating group already contributes. */
-            optInFlowIds?: string[];
+            /** @description What a diff scan's change is measured from: a commit SHA, branch, or tag. Required by a diff scan preset and refused by every other. The scan records the merge base of this and the scanned commit. */
+            baseCommit?: string | null;
             /** @description Area keys from /audit-areas to scope this scan to. Omit or send an empty array to scan the whole repository. A key the repository's current map no longer names fails the launch rather than being dropped, so a scan budgeted for one subsystem never silently runs against everything. */
             auditAreaKeys?: string[];
             /** @description Guidance for this scan only, replacing the repository's configured guidance layer (it is still layered over any committed zkao.md). Omit the field to inherit the repository's guidance; send null to scan with no guidance layer. */
@@ -644,6 +680,8 @@ interface components {
         LaunchScanResult: {
             scanId: string;
             queued: boolean;
+            /** @description The budget the scan was launched with, in credits. */
+            creditBudget: number;
         };
         RepositoryGuidance: {
             repositoryId: string;
@@ -800,6 +838,15 @@ interface components {
                 "application/json": components["schemas"]["Error"];
             };
         };
+        /** @description The diff scan cannot run on this repository yet. Code `diff_empty`: the base and the scanned commit have no change between them. Code `diff_overview_missing`: no earlier full scan of the branch (or the default branch) exists to compare against. Run a full scan first. */
+        DiffUnavailable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
         /** @description The token lacks the required scope */
         Forbidden: {
             headers: {
@@ -853,6 +900,27 @@ interface components {
     pathItems: never;
 }
 interface operations {
+    getTokenInfo: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenInfo"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
     listRepositories: {
         parameters: {
             query?: never;
@@ -1087,6 +1155,7 @@ interface operations {
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
             409: components["responses"]["RepositoryInitializing"];
+            422: components["responses"]["DiffUnavailable"];
             429: components["responses"]["RateLimited"];
         };
     };
@@ -1446,33 +1515,6 @@ interface operations {
             404: components["responses"]["NotFound"];
         };
     };
-    listOptionalFlows: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                projectId: components["parameters"]["ProjectId"];
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        optionalFlows: components["schemas"]["OptionalFlow"][];
-                    };
-                };
-            };
-            401: components["responses"]["Unauthorized"];
-            403: components["responses"]["Forbidden"];
-            404: components["responses"]["NotFound"];
-        };
-    };
     getBillingBalance: {
         parameters: {
             query?: never;
@@ -1565,7 +1607,6 @@ type Finding = Schemas["Finding"];
 type FindingDetail = Schemas["FindingDetail"];
 type FindingNote = Schemas["FindingNote"];
 type ScanPreset = Schemas["ScanPreset"];
-type OptionalFlow = Schemas["OptionalFlow"];
 type LaunchScanRequest = Schemas["LaunchScanRequest"];
 type LaunchScanResult = Schemas["LaunchScanResult"];
 type CancelScanResult = Schemas["CancelScanResult"];
@@ -1581,6 +1622,7 @@ type AuditArea = Schemas["AuditArea"];
 type AuditAreaList = Schemas["AuditAreaList"];
 type DeleteAuditAreaResult = Schemas["DeleteAuditAreaResult"];
 type SetGuidanceResult = Schemas["SetGuidanceResult"];
+type TokenInfo = Schemas["TokenInfo"];
 type BillingBalance = Schemas["BillingBalance"];
 type BillingUsage = Schemas["BillingUsage"];
 type UsageEvent = Schemas["UsageEvent"];
@@ -1593,6 +1635,25 @@ type Paginated<T> = {
     limit: number;
     total: number;
 };
+/**
+ * Body of `createManualAudit`. Not part of the published OpenAPI spec: the
+ * endpoint needs the `admin` scope, which only a zkao site admin can grant.
+ */
+type ManualAuditRequest = {
+    /** Repository the audit covers. */
+    repositoryId: string;
+    /** Commit the audit reviewed (7-64 hex characters). */
+    commitHash: string;
+    commitMessage?: string | null;
+    /** Findings YAML, as report-tool's `just export-findings <slug>` prints it. */
+    findingsYaml: string;
+    /** Report body markdown, shown on the scan page. */
+    reportMarkdown?: string | null;
+};
+type ManualAuditResult = {
+    scanId: string;
+    findingsCreated: number;
+};
 type ZkaoClientOptions = {
     /** A project API token: `zkao_proj_<keyId>_<secret>`. */
     token: string;
@@ -1642,11 +1703,27 @@ declare class ZkaoApiError extends Error {
  * Typed client for one zkao project. Every call is scoped to the project the
  * token belongs to; see https://zkao.io/openapi/v1.yaml for the full contract.
  */
+/**
+ * Which project (and organization) a token belongs to, plus its scopes and
+ * limits. Needs no project id, so it works with a token whose project is
+ * unknown. Any valid token may call it.
+ */
+declare function getTokenInfo(options: Omit<ZkaoClientOptions, "projectId">): Promise<TokenInfo>;
 declare class ZkaoClient {
     private readonly http;
     private readonly projectId;
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
     constructor(options: ZkaoClientOptions);
+    /**
+     * POST a JSON body to a project route that is not in the generated `paths`.
+     * Same error envelope handling as the typed calls.
+     */
+    private postUntyped;
     private get path();
+    /** The calling token, and the project and organization it belongs to. */
+    getTokenInfo(): Promise<TokenInfo>;
     listRepositories(): Promise<Repository[]>;
     /**
      * Block until a repository is ready to scan, then return it.
@@ -1717,6 +1794,12 @@ declare class ZkaoClient {
     publishScan(scanId: string, opts?: {
         withPassword?: boolean;
     }): Promise<PublishArtifactResult>;
+    /**
+     * Record a zkSecurity audit report on the project as a manual audit: a
+     * completed scan whose findings are pre-confirmed. Requires the `admin`
+     * scope, which only a zkao site admin can grant; any other token gets 404.
+     */
+    createManualAudit(body: ManualAuditRequest): Promise<ManualAuditResult>;
     listFindings(opts?: {
         page?: number;
         limit?: number;
@@ -1757,7 +1840,6 @@ declare class ZkaoClient {
         withPassword?: boolean;
     }): Promise<PublishArtifactResult>;
     listScanPresets(): Promise<ScanPreset[]>;
-    listOptionalFlows(): Promise<OptionalFlow[]>;
     /**
      * Get the project's prepaid credit balance (requires the `read` scope). zkao
      * is pay-as-you-go: `balanceCredits` is the total, `reservedCredits` is held
@@ -1785,4 +1867,4 @@ declare class ZkaoClient {
     }): Promise<UsageMonthSummary[]>;
 }
 
-export { type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type OptionalFlow, type Paginated, type PublishArtifactResult, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForRepositoryReadyOptions, type WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };
+export { type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type ManualAuditRequest, type ManualAuditResult, type Paginated, type PublishArtifactResult, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TokenInfo, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForRepositoryReadyOptions, type WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, getTokenInfo, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };

package/dist/index.js

@@ -99,20 +99,64 @@ function unwrap(result) {
     envelope?.error?.message ?? result.response.statusText
   );
 }
+async function getTokenInfo(options) {
+  const http = createClient({
+    baseUrl: options.baseUrl ?? resolveBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
+    headers: { Authorization: `Bearer ${options.token}` },
+    ...options.fetch ? { fetch: options.fetch } : {}
+  });
+  return unwrap(await http.GET("/token"));
+}
 var ZkaoClient = class {
   http;
   projectId;
+  baseUrl;
+  token;
+  fetchImpl;
   constructor(options) {
     this.projectId = options.projectId;
+    this.baseUrl = options.baseUrl ?? resolveBaseUrlFromEnv() ?? DEFAULT_BASE_URL;
+    this.token = options.token;
+    this.fetchImpl = options.fetch ?? fetch;
     this.http = createClient({
-      baseUrl: options.baseUrl ?? resolveBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
-      headers: { Authorization: `Bearer ${options.token}` },
+      baseUrl: this.baseUrl,
+      headers: { Authorization: `Bearer ${this.token}` },
       ...options.fetch ? { fetch: options.fetch } : {}
     });
   }
+  /**
+   * POST a JSON body to a project route that is not in the generated `paths`.
+   * Same error envelope handling as the typed calls.
+   */
+  async postUntyped(path, body) {
+    const url = `${this.baseUrl.replace(/\/+$/, "")}/projects/${encodeURIComponent(this.projectId)}${path}`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      payload = void 0;
+    }
+    if (response.ok && payload !== void 0) {
+      return payload;
+    }
+    return unwrap({ error: payload, response });
+  }
   get path() {
     return { projectId: this.projectId };
   }
+  // --- Token --------------------------------------------------------------
+  /** The calling token, and the project and organization it belongs to. */
+  async getTokenInfo() {
+    return unwrap(await this.http.GET("/token"));
+  }
   // --- Repositories -------------------------------------------------------
   async listRepositories() {
     const res = await this.http.GET("/projects/{projectId}/repositories", {
@@ -324,6 +368,14 @@ var ZkaoClient = class {
     });
     return unwrap(res);
   }
+  /**
+   * Record a zkSecurity audit report on the project as a manual audit: a
+   * completed scan whose findings are pre-confirmed. Requires the `admin`
+   * scope, which only a zkao site admin can grant; any other token gets 404.
+   */
+  async createManualAudit(body) {
+    return this.postUntyped("/manual-audits", body);
+  }
   // --- Findings -----------------------------------------------------------
   async listFindings(opts = {}) {
     const res = await this.http.GET("/projects/{projectId}/findings", {
@@ -391,12 +443,6 @@ var ZkaoClient = class {
     });
     return unwrap(res).presets;
   }
-  async listOptionalFlows() {
-    const res = await this.http.GET("/projects/{projectId}/optional-flows", {
-      params: { path: this.path }
-    });
-    return unwrap(res).optionalFlows;
-  }
   // --- Billing ------------------------------------------------------------
   /**
    * Get the project's prepaid credit balance (requires the `read` scope). zkao
@@ -474,6 +520,7 @@ export {
   TERMINAL_SCAN_STATUSES,
   ZkaoApiError,
   ZkaoClient,
+  getTokenInfo,
   isTerminalScanStatus,
   normalizeBaseUrl,
   resolveBaseUrlFromEnv

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/zkao-sdk",
-  "version": "0.5.1",
+  "version": "0.11.0-next.2",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",