codai-sdk 0.5.0 → 0.7.0

package/README.md

@@ -198,6 +198,52 @@ with `balance`, `required`, `currency: 'micro_eur'` and `topupUrl`. `submit` and
 `accept` are never retried. `waitFor` stops at `resolved | failed | declined | error`
 (or `until`), and throws `ResolveError` with `status: 0` on timeout.
 
+### Webhooks instead of polling
+
+Pass `callback_url` (https, public host) on `submit`; the response carries
+`callback_secret` **once** — store it. Resolve then POSTs `job.quoted`,
+`job.declined`, `job.resolved`, `job.failed` and `job.error` events signed with
+`x-codai-signature: t=<unix>,v1=<hex HMAC-SHA256>`. Verify against the raw body
+with `verifyResolveWebhook` (server-side, uses `node:crypto`; 300 s tolerance by
+default). Up to 3 attempts on `5xx`/`429`/network errors; deduplicate on
+`x-codai-delivery`; delivery never changes job state — `get(id)` stays the truth.
+
+```ts
+import { verifyResolveWebhook, type ResolveWebhookEvent } from 'codai-sdk';
+
+const q = await codai.resolve.submit({
+  repo_url: 'https://github.com/psf/requests',
+  issue_url: 'https://github.com/psf/requests/issues/6000',
+  callback_url: 'https://ci.example.com/hooks/codai-resolve',
+});
+await saveSecret(q.id, q.callback_secret!); // shown once
+
+// in your webhook handler (Hono / Next route / express.raw):
+const raw = await req.text();
+if (!verifyResolveWebhook(secret, raw, req.headers.get('x-codai-signature'))) {
+  return new Response('bad signature', { status: 401 });
+}
+const evt = JSON.parse(raw) as ResolveWebhookEvent; // evt.event, evt.job.attestation_url
+```
+
+### Verifying a signed attestation
+
+Attestations created from 2026-09-27 carry `signature`: a DSSE envelope
+(ECDSA P-256/SHA-256) over a canonical statement of sha256 hashes of the patch,
+repro test and test outputs, plus the commands, base commit, runner digest and
+timestamps. `verifyAttestation` checks the signature against
+`GET /v1/resolve/keys` **and** that the statement matches the fields you were
+served. Older attestations have `signature: null` → `{ ok: false, reason: 'UNSIGNED' }`.
+
+```ts
+const proof = await codai.resolve.attestation(job.attestation_url!);
+const r = await codai.resolve.verifyAttestation(proof); // or { keys: pinnedKeys }
+if (!r.ok) throw new Error(`attestation not verified: ${r.reason}`);
+// r.keyid — the signing key; reasons: UNSIGNED | BAD_SIGNATURE | STATEMENT_MISMATCH | BAD_PAYLOAD_TYPE
+```
+
+Offline (no network): `verifyAttestationWithKeys(proof, keys)`. Server-side only (`node:crypto`).
+
 ## Shared sessions, devices and hosts
 
 Shared-sessions and hosts calls need a device UUID (`x-codai-device`). Set it once

package/dist/index.d.ts

@@ -11024,6 +11024,30 @@ type paths = {
         readonly patch?: never;
         readonly trace?: never;
     };
+    readonly '/v1/resolve/keys': {
+        readonly parameters: {
+            readonly query?: never;
+            readonly header?: never;
+            readonly path?: never;
+            readonly cookie?: never;
+        };
+        /**
+         * Public keys that sign attestations
+         * @description Returns the public key(s) used to sign attestation envelopes (`signature` on
+         *     `GET /v1/resolve/attestations/{id}`). ECDSA P-256 / SHA-256 over the DSSE v1 PAE of the
+         *     payload; the signature is DER, base64. **Unauthenticated**, CORS-open and cacheable for
+         *     1 hour. Verify with `codaid resolve verify`, `resolve.verifyAttestation` (TypeScript) or
+         *     `resolve.verify_attestation` (Python). `503` when signing is not configured.
+         */
+        readonly get: operations['getResolveKeys'];
+        readonly put?: never;
+        readonly post?: never;
+        readonly delete?: never;
+        readonly options?: never;
+        readonly head?: never;
+        readonly patch?: never;
+        readonly trace?: never;
+    };
 };
 type components = {
     schemas: {
@@ -11059,6 +11083,13 @@ type components = {
             readonly repro_test: components['schemas']['ResolveReproTest'] | null;
             /** @description Container image digest of the verification runner (`unknown` when not recorded). */
             readonly runner_image_digest: string;
+            /**
+             * @description DSSE envelope signing the canonical statement of this attestation (sha256 of the patch,
+             *     repro test, test outputs; commands, commit, runner digest, timestamps). `null` for
+             *     attestations created before signing was enabled (2026-09-27). Verify against
+             *     `GET /v1/resolve/keys`.
+             */
+            readonly signature: components['schemas']['ResolveAttestationEnvelope'] | null;
             /** Format: date-time */
             readonly started_at: string;
             /** @description FAIL_TO_PASS command that was executed. */
@@ -11070,11 +11101,39 @@ type components = {
             /** Format: date-time */
             readonly verified_at: string;
         };
+        /**
+         * Attestation envelope
+         * @description DSSE v1 envelope. `payload` is base64 of the RFC 8785 (JCS) canonical statement JSON
+         *     `{kind: "codai.resolve.attestation.v1", attestation_id, repo_url, base_commit, patch_sha256,
+         *     repro_test: {path, sha256} | null, test_command, regression_command,
+         *     test_output_before_sha256, test_output_after_sha256, regression_output_sha256,
+         *     runner_image_digest, started_at, verified_at}`. Each `sig` is an ECDSA P-256/SHA-256 DER
+         *     signature (base64) over `PAE(payloadType, payload bytes)` =
+         *     `"DSSEv1 " + len(type) + " " + type + " " + len(body) + " " + body`.
+         */
+        readonly ResolveAttestationEnvelope: {
+            /** @description Base64 of the canonical statement JSON. */
+            readonly payload: string;
+            /** @constant */
+            readonly payloadType: 'application/vnd.codai.resolve.attestation+json;v=1';
+            readonly signatures: readonly {
+                /** @description Identifier of the signing key; matches `keyid` in `GET /v1/resolve/keys`. */
+                readonly keyid?: string;
+                /** @description DER-encoded ECDSA signature, base64. */
+                readonly sig: string;
+            }[];
+        };
         /**
          * Declined
          * @description `200` body — triage declined the issue. The job is persisted with `status: declined` and is never billed.
          */
         readonly ResolveDeclined: {
+            /**
+             * @description Present only when the intake carried `callback_url` (a `job.declined` event is sent
+             *     too). HMAC-SHA256 key for webhook signatures. **Returned once** — store it now.
+             * @example whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
+             */
+            readonly callback_secret?: string;
             /**
              * @example feature request, no testable behavior
              * @example triage unavailable, please retry
@@ -11132,6 +11191,15 @@ type components = {
          * @description Body of `POST /v1/resolve/jobs`. Provide `issue_url` or `issue_text` (at least one).
          */
         readonly ResolveIntake: {
+            /**
+             * Format: uri
+             * @description Optional webhook target. Must be `https`, carry no credentials and point at a public
+             *     host (no localhost, private, link-local or metadata addresses; every DNS answer is
+             *     re-checked at delivery). Events are signed with the per-job `callback_secret`
+             *     returned in the intake response. Redirects are not followed.
+             * @example https://ci.example.com/hooks/codai-resolve
+             */
+            readonly callback_url?: string;
             /** @description Inline issue description. Takes precedence over `issue_url`. Only the first 20 000 characters reach triage. */
             readonly issue_text?: string;
             /**
@@ -11198,11 +11266,37 @@ type components = {
          * @enum {string}
          */
         readonly ResolveJobStatus: 'triage' | 'quoted' | 'declined' | 'accepted' | 'running' | 'resolved' | 'failed' | 'error';
+        /** Verification key */
+        readonly ResolveKey: {
+            /** @constant */
+            readonly algorithm: 'ECDSA_P256_SHA256';
+            /**
+             * @description Envelope and signature encoding.
+             * @example DSSE v1; signature DER, base64
+             */
+            readonly encoding: string;
+            /** @description Key identifier (the Cloud KMS key version name). */
+            readonly keyid: string;
+            /** @constant */
+            readonly payload_type: 'application/vnd.codai.resolve.attestation+json;v=1';
+            /** @description SPKI public key, PEM. */
+            readonly public_key_pem: string;
+        };
+        /** Verification keys */
+        readonly ResolveKeys: {
+            readonly keys: readonly components['schemas']['ResolveKey'][];
+        };
         /**
          * Quote
          * @description `201` body — the job was quoted (`quoted`) or auto-accepted on the free tier (`accepted`).
          */
         readonly ResolveQuote: {
+            /**
+             * @description Present only when the intake carried `callback_url`. HMAC-SHA256 key for verifying
+             *     webhook signatures. **Returned once** — it is never shown again, store it now.
+             * @example whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
+             */
+            readonly callback_secret?: string;
             /** @description Free resolves left for this user after this submission. */
             readonly free_tier_remaining: number;
             /** Format: uuid */
@@ -11252,6 +11346,53 @@ type components = {
             /** @description Errors on the whole object, e.g. `one of issue_url or issue_text is required`. */
             readonly formErrors: readonly string[];
         };
+        /**
+         * Webhook event payload
+         * @description JSON body POSTed to `callback_url`. Verify `x-codai-signature` over the raw bytes before trusting it.
+         */
+        readonly ResolveWebhookEvent: {
+            readonly event: components['schemas']['ResolveWebhookEventName'];
+            readonly job: components['schemas']['ResolveWebhookJob'];
+            /**
+             * Format: date-time
+             * @description When this delivery attempt was built (UTC).
+             */
+            readonly sent_at: string;
+        };
+        /**
+         * Webhook event
+         * @description `job.quoted` (paid quote ready), `job.declined` (triage refused), `job.resolved` (verified fix + attestation), `job.failed` (no verified fix, hold refunded), `job.error` (infrastructure failure, hold refunded).
+         * @enum {string}
+         */
+        readonly ResolveWebhookEventName: 'job.quoted' | 'job.declined' | 'job.resolved' | 'job.failed' | 'job.error';
+        /**
+         * Webhook job snapshot
+         * @description Snapshot of the job at send time. Nullable fields are `null` until the corresponding stage has run.
+         */
+        readonly ResolveWebhookJob: {
+            /** Format: uuid */
+            readonly attestation_id: string | null;
+            /**
+             * Format: uri
+             * @description Absolute URL of the public attestation (unlike the relative path on `GET /v1/resolve/jobs/{id}`).
+             * @example https://resolve.codai.ro/v1/resolve/attestations/1f2c1a3e-8d4b-4f8e-9a1b-0c2d3e4f5a6b
+             */
+            readonly attestation_url: string | null;
+            /** Format: date-time */
+            readonly completed_at: string | null;
+            /** @description Upstream inference spend attributed to this job, USD micros (informational). */
+            readonly cost_micro_usd: number;
+            readonly decline_reason: string | null;
+            readonly fail_reason: string | null;
+            /** Format: uuid */
+            readonly id: string;
+            /** @description Quoted price in USD micros; `0` on the free tier. */
+            readonly quote_micro_usd: number | null;
+            /** Format: uri */
+            readonly repo_url: string;
+            readonly status: components['schemas']['ResolveJobStatus'];
+            readonly tier: components['schemas']['ResolveTier'] | null;
+        };
     };
     responses: {
         /**
@@ -11473,6 +11614,64 @@ interface operations {
             readonly 409: components['responses']['ResolveConflict'];
         };
     };
+    readonly getResolveKeys: {
+        readonly parameters: {
+            readonly query?: never;
+            readonly header?: never;
+            readonly path?: never;
+            readonly cookie?: never;
+        };
+        readonly requestBody?: never;
+        readonly responses: {
+            /** @description Current verification keys. */
+            readonly 200: {
+                headers: {
+                    readonly [name: string]: unknown;
+                };
+                content: {
+                    readonly 'application/json': components['schemas']['ResolveKeys'];
+                };
+            };
+            /** @description Attestation signing is not configured (`attestation signing not configured`). */
+            readonly 503: {
+                headers: {
+                    readonly [name: string]: unknown;
+                };
+                content: {
+                    readonly 'application/json': components['schemas']['ResolveError'];
+                };
+            };
+        };
+    };
+    readonly resolveJobWebhook: {
+        readonly parameters: {
+            readonly query?: never;
+            readonly header: {
+                /** @description Idempotency key `<jobId>:<event>`, identical on every retry. */
+                readonly 'x-codai-delivery': string;
+                /** @description Event name, same as `event` in the body. */
+                readonly 'x-codai-event': components['schemas']['ResolveWebhookEventName'];
+                /** @description `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. */
+                readonly 'x-codai-signature': string;
+            };
+            readonly path?: never;
+            readonly cookie?: never;
+        };
+        readonly requestBody: {
+            readonly content: {
+                readonly 'application/json': components['schemas']['ResolveWebhookEvent'];
+            };
+        };
+        readonly responses: {
+            /** @description Any 2xx acknowledges the delivery; the body is ignored. */
+            readonly 200: {
+                headers: {
+                    readonly [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
 }
 
 /**
@@ -11495,10 +11694,54 @@ type ResolveJob = ResolveSchemas['ResolveJob'];
 type ResolveJobStatus = ResolveSchemas['ResolveJobStatus'];
 type ResolveTier = ResolveSchemas['ResolveTier'];
 type ResolveAttestation = ResolveSchemas['ResolveAttestation'];
+/** DSSE v1 envelope in `ResolveAttestation.signature` (`null` = unsigned, pre-2026-09-27). */
+type ResolveAttestationEnvelope = ResolveSchemas['ResolveAttestationEnvelope'];
+type ResolveKeys = ResolveSchemas['ResolveKeys'];
+type ResolveKey = ResolveSchemas['ResolveKey'];
 type ResolveReproTest = ResolveSchemas['ResolveReproTest'];
 type ResolveHealth = ResolveSchemas['ResolveHealth'];
 type ResolveValidationDetails = ResolveSchemas['ResolveValidationDetails'];
 type ResolveInsufficientFunds = ResolveSchemas['ResolveInsufficientFunds'];
+/** Body POSTed to `callback_url` (verify with `verifyResolveWebhook` first). */
+type ResolveWebhookEvent = ResolveSchemas['ResolveWebhookEvent'];
+type ResolveWebhookEventName = ResolveSchemas['ResolveWebhookEventName'];
+type ResolveWebhookJob = ResolveSchemas['ResolveWebhookJob'];
+interface VerifyResolveWebhookOptions {
+    /** Maximum age (and future skew) of `t`, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** Current unix time in seconds (tests). Default `Date.now() / 1000`. */
+    nowSeconds?: number;
+}
+/**
+ * Verify a Resolve webhook delivery: `x-codai-signature: t=<unix>,v1=<hex>`
+ * with `v1 = HMAC-SHA256(callback_secret, "<t>.<rawBody>")`. Pass the RAW
+ * request body (before JSON parsing). Constant-time compare; rejects a
+ * timestamp outside `toleranceSeconds`. Returns `false` for any bad input.
+ *
+ * Server-side only: uses `node:crypto` (Node 20.16+/22.3+, Bun, Deno), loaded
+ * lazily so the rest of the SDK still bundles for browsers and edge runtimes.
+ * Throws only when `node:crypto` is unavailable in the current runtime.
+ */
+declare function verifyResolveWebhook(secret: string, rawBody: string | Uint8Array, signatureHeader: string | null | undefined, opts?: VerifyResolveWebhookOptions): boolean;
+/** `payloadType` of Resolve attestation envelopes. */
+declare const RESOLVE_ATTESTATION_PAYLOAD_TYPE = "application/vnd.codai.resolve.attestation+json;v=1";
+type ResolveAttestationVerifyResult = {
+    ok: true;
+    keyid: string;
+} | {
+    ok: false;
+    reason: 'UNSIGNED' | 'BAD_SIGNATURE' | 'STATEMENT_MISMATCH' | 'BAD_PAYLOAD_TYPE';
+};
+/** The statement the Resolve service signs, recomputed from the attestation JSON. */
+declare function resolveAttestationStatement(att: ResolveAttestation): Record<string, unknown>;
+/**
+ * Verify a Resolve attestation offline against published keys: the DSSE
+ * signature (ECDSA P-256/SHA-256, DER) over `PAE(payloadType, payload)` must
+ * match one key, AND the signed statement must equal the one recomputed from
+ * the attestation's own fields (so a valid signature over other content fails).
+ * Server-side only (`node:crypto`, loaded lazily).
+ */
+declare function verifyAttestationWithKeys(att: ResolveAttestation, keys: ResolveKeys): ResolveAttestationVerifyResult;
 /** Statuses after which a job never changes again. */
 declare const RESOLVE_TERMINAL_STATUSES: ReadonlySet<ResolveJobStatus>;
 /** Any non-2xx answer from the Resolve service (flat `{ error }` body). */
@@ -11562,6 +11805,18 @@ declare class Resolve {
     attestation(idOrUrl: string, opts?: CallOpts$4): Promise<ResolveAttestation>;
     /** `GET /health` — liveness of the Resolve service. */
     health(opts?: CallOpts$4): Promise<ResolveHealth>;
+    /** `GET /v1/resolve/keys` — public keys that sign attestations (no auth needed server-side). */
+    keys(opts?: CallOpts$4): Promise<ResolveKeys>;
+    /**
+     * Verify an attestation's signature and that the signed statement matches
+     * its fields. Fetches `keys()` unless `opts.keys` is given (pin them to
+     * avoid trusting the network). `{ ok: false, reason: 'UNSIGNED' }` for
+     * attestations created before signing (2026-09-27). Server-side only.
+     */
+    verifyAttestation(att: ResolveAttestation, opts?: {
+        keys?: ResolveKeys;
+        signal?: AbortSignal;
+    }): Promise<ResolveAttestationVerifyResult>;
     /**
      * Poll `get(id)` until the job reaches a terminal status (`resolved`,
      * `failed`, `declined`, `error`) or one of `opts.until`. A `quoted` job
@@ -12068,4 +12323,4 @@ declare class Codai {
     private legacyExt;
 }
 
-export { Account, type AccountPatchRequest, type AccountPatchResponse, type AccountView, type AgentRun, type AgentRunAccepted, type AgentRunCreateRequest, type AgentRunRequest, type AgentRunResult, type AgentRunStats, type AgentRunStatus, type AgentRunStep, type AgentRunStreamEvent, AgentRuns, type AgentSyncResult, Agents, Audio, Chat, type ChatCallOptions, type ChatCompletionChunk, type ChatCompletionInput, type ChatCompletionRequest, type ChatCompletionResponse, ChatCompletions, type ChatMessage, type ChatOptions, type ChatResult, type ChatStream, type ChatStreamResult, type ChatTool, type ChatToolCall, type ChatUsage, Codai, type CodaiClientOptions, CodaiError, type CodaiRequestExtensions, type Device, type DevicePatch, type DevicePatched, Devices, type DispatchInbox, Embeddings, type EmbeddingsOptions, type EmbeddingsRequest, type EmbeddingsResponse, type EmbeddingsResult, type Environment, type EnvironmentAddMemberBody, type EnvironmentCreateBody, type EnvironmentDetail, type EnvironmentEnrollBody, type EnvironmentEnrollToken, type EnvironmentEnrolled, type EnvironmentMember, type EnvironmentMemberCreated, EnvironmentMembers, type EnvironmentPatchBody, type EnvironmentPort, type EnvironmentPortBody, EnvironmentPorts, type EnvironmentProvider, type EnvironmentRole, type EnvironmentSecret, type EnvironmentSecretSet, EnvironmentSecrets, type EnvironmentSshCa, type EnvironmentSshCert, type EnvironmentSshCertBody, type EnvironmentState, type EnvironmentTaskCreateBody, type EnvironmentTaskCreated, type EnvironmentTaskDetail, type EnvironmentTaskList, EnvironmentTasks, type EnvironmentTransition, Environments, type EphemeralScope, type EphemeralToken, type EphemeralTokenResponse, type ErrorCode, Feedback, type FeedbackRequest, type FeedbackResponse, Health, type HealthReadyResponse, type HealthResponse, type HostExecBody, type HostExecRequest, type HostExecResponse, type HostExecResultBody, type HostOp, type HostPresence, type HostStreamEvent, Hosts, HttpClient, type ListEnvironmentsQuery, type MessageCallOptions, type MessageInput, type MessageRequest, type MessageResponse, type MessageResult, type MessageStream, type MessageStreamEvent, type MessageStreamResult, Messages, type Model, type ModelList, Models, type NotificationList, Notifications, type NotificationsDeleted, type NotificationsRead, OPERATION_METHODS, type Org, type OrgAddMemberBody, type OrgMember, OrgMembers, type OrgRole, Orgs, type PhoneModel, PhoneModels, type Project, type ProjectCreateBody, type ProjectDetail, type ProjectIsolation, type ProjectPatchBody, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, type Receipt, Receipts, type RequestOptions, Resolve, type ResolveAccepted, type ResolveAttestation, type components as ResolveComponents, type ResolveDeclined, ResolveError, type ResolveHealth, type ResolveInsufficientFunds, ResolveInsufficientFundsError, type ResolveIntake, type ResolveJob, type ResolveJobStatus, type operations as ResolveOperations, type paths as ResolvePaths, type ResolveQuote, type ResolveReproTest, type ResolveSubmitResult, type ResolveTier, type ResolveValidationDetails, type ResolveWaitOptions, Responses, type ResponsesCallOptions, type ResponsesInput, type ResponsesRequest, type ResponsesResponse, type ResponsesResult, type ResponsesStream, type ResponsesStreamEvent, type ResponsesStreamResult, STREAMING_OPERATIONS, type Session, type SessionControl, type SessionControlAccepted, type SessionControlRequest, SessionControls, type SessionCreateRequest, type SessionDetail, type SessionDispatchRequest, type SessionDispatchResponse, type SessionEvent, SessionEvents, type SessionEventsAppendRequest, type SessionEventsAppendResponse, type SessionEventsPage, type SessionIncomingEvent, SessionLease, type SessionLeaseClaimRequest, type SessionLeaseResponse, type SessionListItem, type SessionPatchRequest, type SessionShare, type SessionShareCreateRequest, type SessionShareCreated, SessionShares, type SessionStreamEvent, Sessions, type SharedSession, type SpeechRequest, type SpeechResult, type SseFrame, type StatusResponse, type Task, type TaskConfirmRequest, type TaskConfirmResponse, type TaskListPage, type TaskListQuery, type TaskOutcome, type TaskStats, Tasks, type TokenUsage, Tokens, type ToolFetchRequest, type ToolFetchResponse, type ToolSearchRequest, type ToolSearchResponse, Tools, type TranscriptionOptions, type TranscriptionResponse, type TranscriptionResult, type TriggerCreateRequest, type TriggerCreated, type TriggerEvents, type TriggerList, type TriggerPatch, type TriggerTestRequest, type TriggerTestResult, type TriggerUpdated, Triggers, type components$1 as components, Codai as default, extensionHeaders, frameJson, mergeToolCall, type operations$1 as operations, type paths$1 as paths, readSse };
+export { Account, type AccountPatchRequest, type AccountPatchResponse, type AccountView, type AgentRun, type AgentRunAccepted, type AgentRunCreateRequest, type AgentRunRequest, type AgentRunResult, type AgentRunStats, type AgentRunStatus, type AgentRunStep, type AgentRunStreamEvent, AgentRuns, type AgentSyncResult, Agents, Audio, Chat, type ChatCallOptions, type ChatCompletionChunk, type ChatCompletionInput, type ChatCompletionRequest, type ChatCompletionResponse, ChatCompletions, type ChatMessage, type ChatOptions, type ChatResult, type ChatStream, type ChatStreamResult, type ChatTool, type ChatToolCall, type ChatUsage, Codai, type CodaiClientOptions, CodaiError, type CodaiRequestExtensions, type Device, type DevicePatch, type DevicePatched, Devices, type DispatchInbox, Embeddings, type EmbeddingsOptions, type EmbeddingsRequest, type EmbeddingsResponse, type EmbeddingsResult, type Environment, type EnvironmentAddMemberBody, type EnvironmentCreateBody, type EnvironmentDetail, type EnvironmentEnrollBody, type EnvironmentEnrollToken, type EnvironmentEnrolled, type EnvironmentMember, type EnvironmentMemberCreated, EnvironmentMembers, type EnvironmentPatchBody, type EnvironmentPort, type EnvironmentPortBody, EnvironmentPorts, type EnvironmentProvider, type EnvironmentRole, type EnvironmentSecret, type EnvironmentSecretSet, EnvironmentSecrets, type EnvironmentSshCa, type EnvironmentSshCert, type EnvironmentSshCertBody, type EnvironmentState, type EnvironmentTaskCreateBody, type EnvironmentTaskCreated, type EnvironmentTaskDetail, type EnvironmentTaskList, EnvironmentTasks, type EnvironmentTransition, Environments, type EphemeralScope, type EphemeralToken, type EphemeralTokenResponse, type ErrorCode, Feedback, type FeedbackRequest, type FeedbackResponse, Health, type HealthReadyResponse, type HealthResponse, type HostExecBody, type HostExecRequest, type HostExecResponse, type HostExecResultBody, type HostOp, type HostPresence, type HostStreamEvent, Hosts, HttpClient, type ListEnvironmentsQuery, type MessageCallOptions, type MessageInput, type MessageRequest, type MessageResponse, type MessageResult, type MessageStream, type MessageStreamEvent, type MessageStreamResult, Messages, type Model, type ModelList, Models, type NotificationList, Notifications, type NotificationsDeleted, type NotificationsRead, OPERATION_METHODS, type Org, type OrgAddMemberBody, type OrgMember, OrgMembers, type OrgRole, Orgs, type PhoneModel, PhoneModels, type Project, type ProjectCreateBody, type ProjectDetail, type ProjectIsolation, type ProjectPatchBody, Projects, RESOLVE_ATTESTATION_PAYLOAD_TYPE, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, type Receipt, Receipts, type RequestOptions, Resolve, type ResolveAccepted, type ResolveAttestation, type ResolveAttestationEnvelope, type ResolveAttestationVerifyResult, type components as ResolveComponents, type ResolveDeclined, ResolveError, type ResolveHealth, type ResolveInsufficientFunds, ResolveInsufficientFundsError, type ResolveIntake, type ResolveJob, type ResolveJobStatus, type ResolveKey, type ResolveKeys, type operations as ResolveOperations, type paths as ResolvePaths, type ResolveQuote, type ResolveReproTest, type ResolveSubmitResult, type ResolveTier, type ResolveValidationDetails, type ResolveWaitOptions, type ResolveWebhookEvent, type ResolveWebhookEventName, type ResolveWebhookJob, Responses, type ResponsesCallOptions, type ResponsesInput, type ResponsesRequest, type ResponsesResponse, type ResponsesResult, type ResponsesStream, type ResponsesStreamEvent, type ResponsesStreamResult, STREAMING_OPERATIONS, type Session, type SessionControl, type SessionControlAccepted, type SessionControlRequest, SessionControls, type SessionCreateRequest, type SessionDetail, type SessionDispatchRequest, type SessionDispatchResponse, type SessionEvent, SessionEvents, type SessionEventsAppendRequest, type SessionEventsAppendResponse, type SessionEventsPage, type SessionIncomingEvent, SessionLease, type SessionLeaseClaimRequest, type SessionLeaseResponse, type SessionListItem, type SessionPatchRequest, type SessionShare, type SessionShareCreateRequest, type SessionShareCreated, SessionShares, type SessionStreamEvent, Sessions, type SharedSession, type SpeechRequest, type SpeechResult, type SseFrame, type StatusResponse, type Task, type TaskConfirmRequest, type TaskConfirmResponse, type TaskListPage, type TaskListQuery, type TaskOutcome, type TaskStats, Tasks, type TokenUsage, Tokens, type ToolFetchRequest, type ToolFetchResponse, type ToolSearchRequest, type ToolSearchResponse, Tools, type TranscriptionOptions, type TranscriptionResponse, type TranscriptionResult, type TriggerCreateRequest, type TriggerCreated, type TriggerEvents, type TriggerList, type TriggerPatch, type TriggerTestRequest, type TriggerTestResult, type TriggerUpdated, Triggers, type VerifyResolveWebhookOptions, type components$1 as components, Codai as default, extensionHeaders, frameJson, mergeToolCall, type operations$1 as operations, type paths$1 as paths, readSse, resolveAttestationStatement, verifyAttestationWithKeys, verifyResolveWebhook };

package/dist/index.js

@@ -1220,6 +1220,145 @@ var Projects = class {
 };
 
 // src/resources/resolve.ts
+function verifyResolveWebhook(secret, rawBody, signatureHeader, opts = {}) {
+  if (!secret || !signatureHeader) return false;
+  let t;
+  const v1s = [];
+  for (const part of signatureHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    if (k === "t") t = v;
+    else if (k === "v1") v1s.push(v.toLowerCase());
+  }
+  if (!t || !/^\d+$/.test(t) || v1s.length === 0) return false;
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - Number(t)) > tolerance) return false;
+  const { createHmac, timingSafeEqual } = nodeCrypto();
+  const enc2 = new TextEncoder();
+  const body = typeof rawBody === "string" ? enc2.encode(rawBody) : rawBody;
+  const expected = createHmac("sha256", secret).update(enc2.encode(`${t}.`)).update(body).digest();
+  return v1s.some((v1) => {
+    if (!/^[0-9a-f]{64}$/.test(v1)) return false;
+    return timingSafeEqual(hexToBytes(v1), expected);
+  });
+}
+function nodeCrypto() {
+  const proc = globalThis.process;
+  const mod = proc?.getBuiltinModule?.("node:crypto");
+  if (!mod) {
+    throw new Error(
+      "verifyResolveWebhook needs node:crypto (Node 20.16+/22.3+, Bun or Deno); run it server-side"
+    );
+  }
+  return mod;
+}
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+var RESOLVE_ATTESTATION_PAYLOAD_TYPE = "application/vnd.codai.resolve.attestation+json;v=1";
+function verifyCrypto() {
+  const proc = globalThis.process;
+  const mod = proc?.getBuiltinModule?.("node:crypto");
+  if (!mod) {
+    throw new Error(
+      "verifyAttestation needs node:crypto (Node 20.16+/22.3+, Bun or Deno); run it server-side"
+    );
+  }
+  return mod;
+}
+function canonicalJson(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+  const o = v;
+  return `{${Object.keys(o).filter((k) => o[k] !== void 0).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+}
+function base64ToBytes(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function pae(payloadType, body) {
+  const enc2 = new TextEncoder();
+  const typeBytes = enc2.encode(payloadType);
+  const head = enc2.encode(`DSSEv1 ${typeBytes.length} ${payloadType} ${body.length} `);
+  const out = new Uint8Array(head.length + body.length);
+  out.set(head, 0);
+  out.set(body, head.length);
+  return out;
+}
+function resolveAttestationStatement(att) {
+  const { createHash } = verifyCrypto();
+  const enc2 = new TextEncoder();
+  const sha = (s) => s == null ? null : createHash("sha256").update(enc2.encode(s)).digest("hex");
+  return {
+    kind: "codai.resolve.attestation.v1",
+    attestation_id: att.id,
+    repo_url: att.repo_url,
+    base_commit: att.base_commit,
+    patch_sha256: sha(att.patch),
+    repro_test: att.repro_test?.path ? { path: att.repro_test.path, sha256: sha(att.repro_test.content) } : null,
+    test_command: att.test_command,
+    regression_command: att.regression_command,
+    test_output_before_sha256: sha(att.test_output_before),
+    test_output_after_sha256: sha(att.test_output_after),
+    regression_output_sha256: sha(att.regression_output),
+    runner_image_digest: att.runner_image_digest,
+    started_at: att.started_at,
+    verified_at: att.verified_at
+  };
+}
+function verifyAttestationWithKeys(att, keys) {
+  const env = att.signature;
+  if (!env || !Array.isArray(env.signatures) || env.signatures.length === 0)
+    return { ok: false, reason: "UNSIGNED" };
+  if (env.payloadType !== RESOLVE_ATTESTATION_PAYLOAD_TYPE)
+    return { ok: false, reason: "BAD_PAYLOAD_TYPE" };
+  const { createVerify } = verifyCrypto();
+  let body;
+  try {
+    body = base64ToBytes(env.payload);
+  } catch {
+    return { ok: false, reason: "BAD_SIGNATURE" };
+  }
+  const msg = pae(env.payloadType, body);
+  let keyid = null;
+  outer: for (const s of env.signatures) {
+    let sig;
+    try {
+      sig = base64ToBytes(s.sig);
+    } catch {
+      continue;
+    }
+    for (const k of keys.keys) {
+      if (k.payload_type && k.payload_type !== env.payloadType) continue;
+      try {
+        const v = createVerify("SHA256");
+        v.update(msg);
+        if (v.verify({ key: k.public_key_pem, dsaEncoding: "der" }, sig)) {
+          keyid = k.keyid;
+          break outer;
+        }
+      } catch {
+      }
+    }
+  }
+  if (keyid === null) return { ok: false, reason: "BAD_SIGNATURE" };
+  let signed;
+  try {
+    signed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+  } catch {
+    return { ok: false, reason: "STATEMENT_MISMATCH" };
+  }
+  if (canonicalJson(signed) !== canonicalJson(resolveAttestationStatement(att)))
+    return { ok: false, reason: "STATEMENT_MISMATCH" };
+  return { ok: true, keyid };
+}
 var RESOLVE_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "resolved",
   "failed",
@@ -1307,6 +1446,21 @@ var Resolve = class {
   health(opts = {}) {
     return this.call("/health", { signal: opts.signal });
   }
+  /** `GET /v1/resolve/keys` — public keys that sign attestations (no auth needed server-side). */
+  keys(opts = {}) {
+    return this.call("/v1/resolve/keys", { signal: opts.signal });
+  }
+  /**
+   * Verify an attestation's signature and that the signed statement matches
+   * its fields. Fetches `keys()` unless `opts.keys` is given (pin them to
+   * avoid trusting the network). `{ ok: false, reason: 'UNSIGNED' }` for
+   * attestations created before signing (2026-09-27). Server-side only.
+   */
+  async verifyAttestation(att, opts = {}) {
+    if (!att.signature) return { ok: false, reason: "UNSIGNED" };
+    const keys = opts.keys ?? await this.keys({ signal: opts.signal });
+    return verifyAttestationWithKeys(att, keys);
+  }
   /**
    * Poll `get(id)` until the job reaches a terminal status (`resolved`,
    * `failed`, `declined`, `error`) or one of `opts.until`. A `quoted` job
@@ -2019,7 +2173,8 @@ var RESOLVE_OPERATION_METHODS = {
   createResolveJob: "resolve.submit",
   getResolveJob: "resolve.get",
   acceptResolveJob: "resolve.accept",
-  getResolveAttestation: "resolve.attestation"
+  getResolveAttestation: "resolve.attestation",
+  getResolveKeys: "resolve.keys"
 };
 
 // src/index.ts
@@ -2187,6 +2342,6 @@ function allKeys(obj) {
 }
 var index_default = Codai;
 
-export { Account, AgentRuns, Agents, Audio, Chat, ChatCompletions, Codai, CodaiError, Devices, Embeddings, EnvironmentMembers, EnvironmentPorts, EnvironmentSecrets, EnvironmentTasks, Environments, Feedback, Health, Hosts, HttpClient, Messages, Models, Notifications, OPERATION_METHODS, OrgMembers, Orgs, PhoneModels, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, Receipts, Resolve, ResolveError, ResolveInsufficientFundsError, Responses, STREAMING_OPERATIONS, SessionControls, SessionEvents, SessionLease, SessionShares, Sessions, Tasks, Tokens, Tools, Triggers, index_default as default, extensionHeaders, frameJson, mergeToolCall, readSse };
+export { Account, AgentRuns, Agents, Audio, Chat, ChatCompletions, Codai, CodaiError, Devices, Embeddings, EnvironmentMembers, EnvironmentPorts, EnvironmentSecrets, EnvironmentTasks, Environments, Feedback, Health, Hosts, HttpClient, Messages, Models, Notifications, OPERATION_METHODS, OrgMembers, Orgs, PhoneModels, Projects, RESOLVE_ATTESTATION_PAYLOAD_TYPE, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, Receipts, Resolve, ResolveError, ResolveInsufficientFundsError, Responses, STREAMING_OPERATIONS, SessionControls, SessionEvents, SessionLease, SessionShares, Sessions, Tasks, Tokens, Tools, Triggers, index_default as default, extensionHeaders, frameJson, mergeToolCall, readSse, resolveAttestationStatement, verifyAttestationWithKeys, verifyResolveWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map