@qed-proof/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Typed helpers for the five live actions plus `http.url.status`, matching the wire shape the
+ * node's verifiers expect (`oss/spec/profiles/*.md`, `oss/node/src/poaw_node/verifiers/*.py`).
+ * Validation here is cheap and local — it never calls the network — but it fails fast with a
+ * clear message before the claim is submitted, since params are copied into public receipts.
+ */
+interface ClaimAction {
+    action: string;
+    target: string;
+    params: Record<string, unknown>;
+}
+declare function githubCommitPush(input: {
+    target: string;
+    sha: string;
+    branch: string;
+}): ClaimAction;
+declare function githubPrOpen(input: {
+    target: string;
+    number: number;
+    base?: string;
+    headSha?: string;
+}): ClaimAction;
+declare function githubChecksPass(input: {
+    target: string;
+    sha: string;
+}): ClaimAction;
+declare function xPostPublish(input: {
+    target: string;
+    postId: string;
+    textSha256?: string;
+}): ClaimAction;
+declare function slackMessagePost(input: {
+    target: string;
+    ts: string;
+    textSha256?: string;
+}): ClaimAction;
+declare function httpUrlStatus(input: {
+    target: string;
+    status?: number;
+    contentFingerprint?: string;
+}): ClaimAction;
+
+type actions_ClaimAction = ClaimAction;
+declare const actions_githubChecksPass: typeof githubChecksPass;
+declare const actions_githubCommitPush: typeof githubCommitPush;
+declare const actions_githubPrOpen: typeof githubPrOpen;
+declare const actions_httpUrlStatus: typeof httpUrlStatus;
+declare const actions_slackMessagePost: typeof slackMessagePost;
+declare const actions_xPostPublish: typeof xPostPublish;
+declare namespace actions {
+  export { type actions_ClaimAction as ClaimAction, actions_githubChecksPass as githubChecksPass, actions_githubCommitPush as githubCommitPush, actions_githubPrOpen as githubPrOpen, actions_httpUrlStatus as httpUrlStatus, actions_slackMessagePost as slackMessagePost, actions_xPostPublish as xPostPublish };
+}
+
+interface Proof$1 {
+    log_id: string;
+    leaf_index: number;
+    tree_size: number;
+    root_hash: string;
+    inclusion: string[];
+    anchor?: {
+        chain: string;
+        scheme: string;
+        uid: string;
+        tx_hash: string;
+        tree_size: number;
+    };
+}
+interface Keyset {
+    keys?: Array<{
+        key_id: string;
+        public_key: string;
+        valid_from: string;
+        revoked_at: string | null;
+    }>;
+    anchor_addresses?: string[];
+    anchor_schemas?: string[];
+}
+interface AnchorResult {
+    ok: boolean;
+    reason: string;
+    proven_by: number | null;
+}
+
+interface VerifyChecks {
+    spec_version: boolean;
+    schema: boolean;
+    integers_only: boolean;
+    key: boolean;
+    signature: boolean;
+    claim_digest: boolean;
+    inclusion: boolean | "absent";
+    anchor: boolean | "absent" | "not_checked_offline" | string;
+}
+interface VerifyReport {
+    checks: VerifyChecks;
+    valid: boolean;
+    verdict: string | null;
+    achieved_trust_level: number;
+    proven_by?: number | null;
+}
+interface VerifyOptions {
+    keys: Keyset;
+    rpcUrl?: string;
+}
+declare function verifyReceipt(receipt: unknown | string, options: VerifyOptions): Promise<VerifyReport>;
+
+/**
+ * The HTTP client. Shapes follow `oss/node/src/poaw_node/app.py`, `models.py` (`ClaimIn`) and
+ * `store.py` (`claim_status`). Uses only `fetch` — no Node built-ins — so it runs on Node, Deno
+ * and in browsers.
+ */
+
+interface QedProofOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+interface SubmitClaimOptions {
+    agentId: string;
+    clientClaimId?: string;
+    claimedAt?: string | Date;
+}
+interface ClaimStatus {
+    claim_id: string;
+    created?: boolean;
+    state: "queued" | "decided";
+    attempts: number;
+    receipt_id: string | null;
+    verdict: string | null;
+}
+interface WaitOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+interface Receipt {
+    body: Record<string, unknown>;
+    signature: Record<string, unknown>;
+    proof?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ClaimSummary {
+    claim_id: string;
+    state: string;
+    attempts: number;
+    receipt_id: string | null;
+    verdict: string | null;
+}
+interface ListClaimsOptions {
+    limit?: number;
+    cursor?: string;
+    agentId?: string;
+    action?: string;
+    verdict?: string;
+    state?: string;
+}
+interface ClaimPage {
+    claims: ClaimSummary[];
+    nextCursor: string | null;
+}
+declare class QedProof {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: QedProofOptions);
+    private request;
+    submitClaim(claim: ClaimAction, options: SubmitClaimOptions): Promise<ClaimStatus>;
+    getClaim(claimId: string): Promise<ClaimStatus>;
+    waitForVerdict(claimId: string, options?: WaitOptions): Promise<ClaimStatus>;
+    /**
+     * `GET /v1/claims`, newest first. `options.limit` (1-200, default 50) is validated locally —
+     * out of range throws a `RangeError` before any request is made.
+     */
+    listClaims(options?: ListClaimsOptions): Promise<ClaimPage>;
+    /** Yields every claim matching the filters, following `nextCursor` until exhausted. */
+    iterClaims(options?: Omit<ListClaimsOptions, "cursor" | "limit"> & {
+        pageSize?: number;
+    }): AsyncGenerator<ClaimSummary>;
+    /** Receipts are designed to be shared and checked by anyone (SPEC §1): no Authorization header. */
+    getReceipt(receiptId: string): Promise<Receipt>;
+    /** Public by design: `/.well-known/poaw-keys.json` (SPEC §5.2, §8.4). */
+    getKeys(): Promise<Keyset>;
+    verify(receipt: unknown | string, options?: {
+        keys?: Keyset;
+        rpcUrl?: string;
+    }): Promise<VerifyReport>;
+}
+
+declare class QedProofError extends Error {
+    status: number;
+    detail: string;
+    constructor(status: number, detail: string);
+}
+declare class RateLimitError extends QedProofError {
+    retryAfter: number | undefined;
+    constructor(detail: string, retryAfter: number | undefined);
+}
+
+declare const SPEC_VERSION = "poaw/0.1";
+declare const SIG_DOMAIN: Uint8Array<ArrayBuffer>;
+declare function b64u(data: Uint8Array): string;
+declare function b64uDecode(text: string): Uint8Array;
+/** RFC 8785 JCS, as UTF-8 bytes (matches Python's `rfc8785.dumps`, which returns bytes). */
+declare function jcs(obj: unknown): Uint8Array;
+declare function sha256(data: Uint8Array): Uint8Array;
+/**
+ * §3: receipts carry integers only. JSON.parse collapses the int/float distinction Python's
+ * `json.loads` preserves (e.g. `1.0` parses to the same JS number as `1`), so this checks two
+ * ways:
+ *  - `hasFloatValue`: any value that is a non-integer finite number (catches every float that
+ *    actually matters, e.g. `0.5` in vector 014-float-in-body.json).
+ *  - `hasFloatText`: scans the raw JSON text (outside string literals) for a numeric token
+ *    containing `.`, `e` or `E` — the same signal Python's tokenizer used to decide `float` vs
+ *    `int`, for callers that still have the original text (files, HTTP bodies).
+ * `verifyReceipt` OR's both when raw text is available, so nothing is hidden by `JSON.parse`.
+ */
+declare function hasFloatValue(value: unknown): boolean;
+declare function hasFloatText(text: string): boolean;
+declare function keyId(pkRaw: Uint8Array): string;
+declare function verifySignature(pkRaw: Uint8Array, body: unknown, sigValue: string): boolean;
+declare function claimDigest(claim: Record<string, unknown>): string;
+declare function leafHash(receipt: {
+    body: unknown;
+    signature: unknown;
+}): Uint8Array;
+/**
+ * RFC 9162 §2.1.3.2 audit-path verification. Returns the computed root, or null if the path is
+ * malformed. Ported line for line from `poaw_core.root_from_inclusion`.
+ */
+declare function rootFromInclusion(index: number, size: number, leaf: Uint8Array, path: Uint8Array[]): Uint8Array | null;
+
+/**
+ * This file was automatically generated by `npm run gen:types` from
+ * ../../../src/receipt.schema.json (the vendored PoAW receipt schema). Do not edit by hand.
+ */
+type Timestamp = string;
+type KeyId = string;
+type Action = string;
+type B64Url = string;
+type Fingerprint = string;
+type VerdictValue = "verified" | "late" | "mismatch" | "failed" | "unverifiable";
+type ReasonCode = "not_found" | "content_mismatch" | "target_mismatch" | "observed_after_tolerance" | "no_connection" | "permission_denied" | "rate_limited" | "destination_unavailable" | "unsupported_action" | "claim_ambiguous" | "verifier_error";
+/**
+ * Structural schema for a Proof of Agent Work receipt. Signature, inclusion and anchor checks are defined in SPEC.md and are not expressible in JSON Schema.
+ */
+interface PoAWReceiptPoaw01 {
+    body: Body;
+    signature: Signature;
+    proof?: Proof;
+}
+interface Body {
+    spec_version: "poaw/0.1";
+    receipt_id: string;
+    issued_at: Timestamp;
+    issuer: {
+        key_id: KeyId;
+        name?: string;
+    };
+    agent: {
+        id: string;
+        erc8004?: {
+            chain: string;
+            registry: string;
+            agent_id: string;
+        };
+    };
+    operator?: string;
+    claim: {
+        action: Action;
+        target: string;
+        params: {};
+        claimed_at: Timestamp;
+        client_claim_id?: string;
+        claim_digest: B64Url;
+    };
+    observation: {
+        verifier: {
+            id: Action;
+            version: string;
+            code_hash?: Fingerprint;
+        };
+        observed_at: Timestamp;
+        deadline_at: Timestamp;
+        attempts: number;
+        facts: {};
+    };
+    verdict: {
+        value: VerdictValue;
+        reason_code?: ReasonCode;
+    };
+    trust_level: number;
+    attestation?: {
+        type: string;
+        document: B64Url;
+    };
+    supersedes?: string;
+}
+interface Signature {
+    alg: "Ed25519";
+    key_id: KeyId;
+    value: string;
+}
+interface Proof {
+    log_id: B64Url;
+    leaf_index: number;
+    tree_size: number;
+    root_hash: B64Url;
+    inclusion: B64Url[];
+    anchor?: {
+        chain: string;
+        scheme: "eas";
+        uid: string;
+        tx_hash: string;
+        tree_size: number;
+    };
+}
+
+export { type AnchorResult, type ClaimAction, type ClaimPage, type ClaimStatus, type ClaimSummary, type PoAWReceiptPoaw01 as GeneratedReceipt, type Keyset, type ListClaimsOptions, type Proof$1 as Proof, QedProof, QedProofError, type QedProofOptions, RateLimitError, type Receipt, SIG_DOMAIN, SPEC_VERSION, type SubmitClaimOptions, type VerifyChecks, type VerifyOptions, type VerifyReport, type WaitOptions, actions, b64u, b64uDecode, claimDigest, hasFloatText, hasFloatValue, jcs, keyId, leafHash, rootFromInclusion, sha256, verifyReceipt, verifySignature };