@zksecurity/zkao-sdk 0.13.0-next.8 → 0.15.0-next.10

package/dist/index.d.ts

@@ -216,6 +216,92 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/projects/{projectId}/reports": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List incoming reports
+         * @description Requires scope: `read`. Vulnerability reports the programme has received, newest first. Optionally filter by `status`.
+         *
+         *     `publicId` is what `investigateReport` takes. `intakeState` says whether the report has been read and split into claims yet: an investigation waits for `COMPLETE`, so a `PENDING` or `RUNNING` report is one to come back to rather than one to retry.
+         */
+        get: operations["listReports"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/reports/{publicId}/investigate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Investigate an incoming report against the code
+         * @description Requires scope: `scans:launch`. Runs the triage flow over the report's claims: each is checked against the repository, deduplicated against the findings already confirmed there, and given a proof of concept where one can be written. Returns immediately with the scan doing the work; poll `/projects/{projectId}/scans/{scanId}` and then read its findings.
+         *
+         *     Idempotent. A report already under investigation returns the existing scan with `claimsQueued: null`, so a retry costs nothing.
+         */
+        post: operations["investigateReport"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/advisories": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List advisories
+         * @description Requires scope: `read`. The project's coordinated-disclosure advisories, newest first. Optionally filter by `status`.
+         */
+        get: operations["listAdvisories"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/advisories/{publicId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get an advisory
+         * @description Requires scope: `read`. The advisory, the versions it affects, and the notices planned for it.
+         *
+         *     A notice the plan is holding back carries `blockedReason`. The commonest one is that no affected range names a fixed version, which only the people who shipped the release can supply; record it in the app and the notice becomes schedulable.
+         */
+        get: operations["getAdvisory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/projects/{projectId}/findings": {
         parameters: {
             query?: never;
@@ -596,6 +682,18 @@ interface components {
             /** @description Null for a scan launched without a budget. */
             budget?: components["schemas"]["ScanBudget"] | null;
         };
+        /** @description Where a launch came from. References only: no URL is accepted, and the link the scan page shows is built from the scanned repository, so a token can never point that page somewhere of its own choosing. */
+        ScanTrigger: {
+            /**
+             * @description What asked for the scan.
+             * @enum {string}
+             */
+            kind: "github_action" | "pr_comment" | "agent" | "api";
+            /** @description Pull request number in the scanned repository. Its existence is not checked: a wrong number only yields a dead link in your own repository. */
+            pullRequest?: number | null;
+            /** @description The comment that asked for the scan, so the link lands on it. Requires pullRequest. */
+            commentId?: string | null;
+        };
         /** @description What a scan was allowed to spend, what it was charged, and whether the next scan of its type and scope should get more. Check the last scan of a type before choosing the next one's budget. */
         ScanBudget: {
             /** @description The most the scan could spend, in credits. */
@@ -680,6 +778,105 @@ interface components {
             limit: number;
             total: number;
         };
+        Report: {
+            /** @description The identifier `investigateReport` takes. */
+            publicId: string;
+            title: string;
+            /** @description How it arrived. Today always GitHub private vulnerability reporting. */
+            source: string;
+            /** @description What the reporter claimed, which is not an assessment. */
+            claimedSeverity?: components["schemas"]["Severity"] | null;
+            /** @enum {string} */
+            status: "NEW" | "TRIAGING" | "NEEDS_INFO" | "ACCEPTED" | "DUPLICATE" | "REJECTED";
+            /**
+             * @description Whether the report has been read and split into claims. An investigation waits for COMPLETE.
+             * @enum {string}
+             */
+            intakeState: "PENDING" | "RUNNING" | "REVIEW" | "COMPLETE" | "FAILED";
+            /**
+             * @description How the investigation is going, or null if none has run.
+             * @enum {string|null}
+             */
+            evaluationState?: "QUEUED" | "RUNNING" | "COMPLETE" | "FAILED" | null;
+            reporterName?: string | null;
+            reporterGithubLogin?: string | null;
+            /** @description The GitHub advisory it arrived as. */
+            githubUrl?: string | null;
+            /** Format: date-time */
+            acknowledgedAt?: string | null;
+            /** Format: date-time */
+            createdAt: string;
+        };
+        PaginatedReports: {
+            items: components["schemas"]["Report"][];
+            page: number;
+            limit: number;
+            total: number;
+        };
+        Advisory: {
+            /** @description Readable identifier, e.g. `ADVISORY-ADV-2026-0045`. */
+            publicId: string;
+            title: string;
+            /** @enum {string} */
+            severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+            /** @enum {string} */
+            status: "DRAFT" | "SCHEDULED" | "UNDER_EMBARGO" | "PUBLISHED" | "WITHDRAWN";
+            /**
+             * Format: date-time
+             * @description When the embargo lifts. Null until a date is set.
+             */
+            disclosureAt?: string | null;
+            /** Format: date-time */
+            publishedAt?: string | null;
+            cveId?: string | null;
+            /** @description The GitHub advisory, once one has been filed. */
+            ghsaId?: string | null;
+            ghsaUrl?: string | null;
+            /** @description What GitHub reports. A created entry is a DRAFT, which is private and reaches no scanner; only a published one is public. */
+            ghsaState: string;
+            /** Format: date-time */
+            createdAt: string;
+        };
+        AdvisoryAffected: {
+            id: string;
+            repository: {
+                owner: string;
+                name: string;
+            };
+            /** @description First version carrying the defect. */
+            introducedIn: string;
+            /** @description Version that closes the range. Null while no patch exists, which is what holds a patch notice back. */
+            fixedIn: string | null;
+        };
+        AdvisoryNotice: {
+            label: string;
+            /** @description Days relative to disclosure. Negative is before it, 0 is the day itself. */
+            offsetDays: number;
+            /** Format: date-time */
+            scheduledFor: string;
+            /** @enum {string} */
+            status: "DRAFT" | "SCHEDULED" | "BLOCKED" | "SENDING" | "SENT" | "CANCELLED";
+            /** @description Why the plan is holding this notice back, if it is. */
+            blockedReason: string | null;
+            /** Format: date-time */
+            sentAt: string | null;
+            /** @description Contacts written to, as recorded when it went. */
+            recipientCount: number;
+        };
+        AdvisoryDetail: components["schemas"]["Advisory"] & {
+            summary: string;
+            description: string;
+            impact: string;
+            cwe?: string | null;
+            affected: components["schemas"]["AdvisoryAffected"][];
+            notices: components["schemas"]["AdvisoryNotice"][];
+        };
+        PaginatedAdvisories: {
+            items: components["schemas"]["Advisory"][];
+            page: number;
+            limit: number;
+            total: number;
+        };
         PaginatedFindings: {
             items: components["schemas"]["Finding"][];
             page: number;
@@ -716,6 +913,8 @@ interface components {
             commitMessage?: string | null;
             /** @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 Where this launch came from, shown on the scan page. Optional, and display only: nothing in the pipeline reads it. */
+            trigger?: components["schemas"]["ScanTrigger"] | 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. */
@@ -795,6 +994,13 @@ interface components {
             /** @description Number of in-flight jobs signalled to stop. */
             cancelledJobs: number;
         };
+        InvestigateReportResult: {
+            publicId: string;
+            /** @description The scan triaging this report's claims. */
+            scanId: string;
+            /** @description Claims queued for triage, or null when an investigation was already running and this call started nothing. */
+            claimsQueued: number | null;
+        };
         /** @description Optionally attach or reuse a note alongside a resolution change. */
         ChangeNote: {
             /** @description Create a new note with this body. */
@@ -1262,6 +1468,127 @@ interface operations {
             429: components["responses"]["RateLimited"];
         };
     };
+    listReports: {
+        parameters: {
+            query?: {
+                page?: components["parameters"]["Page"];
+                limit?: components["parameters"]["Limit"];
+                /** @description Only reports in this triage status. */
+                status?: "NEW" | "TRIAGING" | "NEEDS_INFO" | "ACCEPTED" | "DUPLICATE" | "REJECTED";
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedReports"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    investigateReport: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                /** @description The report's public identifier. */
+                publicId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InvestigateReportResult"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            402: components["responses"]["InsufficientCredits"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    listAdvisories: {
+        parameters: {
+            query?: {
+                page?: components["parameters"]["Page"];
+                limit?: components["parameters"]["Limit"];
+                /** @description Only advisories in this status. */
+                status?: "DRAFT" | "SCHEDULED" | "UNDER_EMBARGO" | "PUBLISHED" | "WITHDRAWN";
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedAdvisories"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getAdvisory: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                /** @description The advisory's readable identifier. */
+                publicId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        advisory: components["schemas"]["AdvisoryDetail"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
     listFindings: {
         parameters: {
             query?: {
@@ -1706,6 +2033,14 @@ type BillingUsage = Schemas["BillingUsage"];
 type UsageEvent = Schemas["UsageEvent"];
 type UsageEventType = Schemas["UsageEventType"];
 type BillingSummary = Schemas["BillingSummary"];
+type InvestigateReportResult = Schemas["InvestigateReportResult"];
+type Report = Schemas["Report"];
+/** The triage statuses a report moves through. */
+type ReportStatus = "NEW" | "TRIAGING" | "NEEDS_INFO" | "ACCEPTED" | "DUPLICATE" | "REJECTED";
+type Advisory = Schemas["Advisory"];
+type AdvisoryDetail = Schemas["AdvisoryDetail"];
+/** The statuses an advisory moves through. */
+type AdvisoryStatus = "DRAFT" | "SCHEDULED" | "UNDER_EMBARGO" | "PUBLISHED" | "WITHDRAWN";
 type UsageMonthSummary = Schemas["UsageMonthSummary"];
 type Paginated<T> = {
     items: T[];
@@ -1878,6 +2213,47 @@ declare class ZkaoClient {
      * scope, which only a zkao site admin can grant; any other token gets 404.
      */
     createManualAudit(body: ManualAuditRequest): Promise<ManualAuditResult>;
+    /**
+     * The project's coordinated-disclosure advisories, newest first.
+     */
+    listAdvisories(opts?: {
+        page?: number;
+        limit?: number;
+        status?: AdvisoryStatus;
+    }): Promise<Paginated<Advisory>>;
+    /**
+     * One advisory, the versions it affects, and the notices planned for it.
+     *
+     * A notice the plan is holding back carries `blockedReason`. The commonest
+     * one is that no affected range names a fixed version, which only the people
+     * who shipped the release can supply.
+     */
+    getAdvisory(publicId: string): Promise<AdvisoryDetail>;
+    /**
+     * Reports the programme has received, newest first.
+     *
+     * `publicId` is what {@link investigateReport} takes. `intakeState` says
+     * whether a report has been read and split into claims yet: an
+     * investigation waits for `COMPLETE`.
+     */
+    listReports(opts?: {
+        page?: number;
+        limit?: number;
+        status?: ReportStatus;
+    }): Promise<Paginated<Report>>;
+    /**
+     * Check an incoming vulnerability report against the code.
+     *
+     * Requires the `scans:launch` scope. The report's claims are each checked
+     * against the repository, deduplicated against the findings already
+     * confirmed there, and given a proof of concept where one can be written.
+     * Returns at once with the scan doing the work: poll {@link getScan} and
+     * then read its findings.
+     *
+     * Idempotent. A report already under investigation comes back with the
+     * existing scan and `claimsQueued: null`, so a retry costs nothing.
+     */
+    investigateReport(publicId: string): Promise<InvestigateReportResult>;
     listFindings(opts?: {
         page?: number;
         limit?: number;

package/dist/index.js

@@ -376,6 +376,69 @@ var ZkaoClient = class {
   async createManualAudit(body) {
     return this.postUntyped("/manual-audits", body);
   }
+  // --- Advisories ---------------------------------------------------------
+  /**
+   * The project's coordinated-disclosure advisories, newest first.
+   */
+  async listAdvisories(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/advisories", {
+      params: {
+        path: this.path,
+        query: { page: opts.page, limit: opts.limit, status: opts.status }
+      }
+    });
+    return unwrap(res);
+  }
+  /**
+   * One advisory, the versions it affects, and the notices planned for it.
+   *
+   * A notice the plan is holding back carries `blockedReason`. The commonest
+   * one is that no affected range names a fixed version, which only the people
+   * who shipped the release can supply.
+   */
+  async getAdvisory(publicId) {
+    const res = await this.http.GET(
+      "/projects/{projectId}/advisories/{publicId}",
+      { params: { path: { ...this.path, publicId } } }
+    );
+    return unwrap(res).advisory;
+  }
+  // --- Incoming reports ---------------------------------------------------
+  /**
+   * Reports the programme has received, newest first.
+   *
+   * `publicId` is what {@link investigateReport} takes. `intakeState` says
+   * whether a report has been read and split into claims yet: an
+   * investigation waits for `COMPLETE`.
+   */
+  async listReports(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/reports", {
+      params: {
+        path: this.path,
+        query: { page: opts.page, limit: opts.limit, status: opts.status }
+      }
+    });
+    return unwrap(res);
+  }
+  /**
+   * Check an incoming vulnerability report against the code.
+   *
+   * Requires the `scans:launch` scope. The report's claims are each checked
+   * against the repository, deduplicated against the findings already
+   * confirmed there, and given a proof of concept where one can be written.
+   * Returns at once with the scan doing the work: poll {@link getScan} and
+   * then read its findings.
+   *
+   * Idempotent. A report already under investigation comes back with the
+   * existing scan and `claimsQueued: null`, so a retry costs nothing.
+   */
+  async investigateReport(publicId) {
+    const res = await this.http.POST(
+      "/projects/{projectId}/reports/{publicId}/investigate",
+      { params: { path: { ...this.path, publicId } } }
+    );
+    return unwrap(res);
+  }
   // --- Findings -----------------------------------------------------------
   async listFindings(opts = {}) {
     const res = await this.http.GET("/projects/{projectId}/findings", {

package/package.json

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