@envolvr/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,65 @@
+# @envolvr/sdk
+
+Private inference your agent can prove. The envolvr gateway runs in an attested
+Intel TDX enclave and speaks the OpenAI API; every response comes with a signed
+receipt that records the model, the attested provider session, commitments to
+the request and response, and what was billed. Receipt hashes are anchored on
+Robinhood Chain every 10 minutes. This package signs in with a wallet, funds
+the account with USDG, runs inference, keeps every receipt, and verifies it.
+
+```bash
+npm install @envolvr/sdk        # Node 20+
+```
+
+## From zero to a verified receipt (testnet)
+
+```bash
+export ENVOLVR_PRIVATE_KEY=0x…   # a wallet with a little Robinhood testnet ETH for gas
+npx envolvr signin --save        # sign a message, get an API key
+npx envolvr testnet-mint 20      # test USDG (testnet only)
+npx envolvr deposit 10           # credited net of the deposit fee, within seconds
+npx envolvr chat "Reply with the single word: sealed"
+npx envolvr verify --last        # signature, billing, payer, on-chain anchor
+```
+
+`verify` prints what the receipt proves: the gateway's TDX attestation and the
+receipt signature (checked by `private-ai-proxy`), what was billed and that it
+was billed to your key, and the batch and transaction that anchor it. A receipt
+is anchored at the end of its 10-minute slot (UTC).
+
+## In code
+
+```ts
+import { Envolvr, privateKeySigner, signIn, depositUsdg, TESTNET, toMicros } from '@envolvr/sdk';
+
+const wallet = privateKeySigner(process.env.KEY!, { rpcUrl: TESTNET.rpcUrl, chainId: TESTNET.chainId });
+const { apiKey } = await signIn(wallet);                          // keep it: shown once
+await depositUsdg({ signer: wallet, amountMicros: toMicros('10') });
+
+const envolvr = new Envolvr({ apiKey, receiptDir: './receipts' });
+const { response, saved } = await envolvr.chat({
+  model: 'z-ai/glm-5.3',
+  messages: [{ role: 'user', content: 'hello' }],
+  provider: { only: ['redpill'] },                                // optional: pin providers
+});
+const proof = await envolvr.verify(saved!.dir!);                  // after the slot closes
+```
+
+Using the OpenAI SDK instead: `new OpenAI(envolvr.openai)`. Then fetch each
+receipt yourself with `envolvr.receipt(id)` within an hour: the gateway keeps
+receipts for an hour. For an OpenAI client that verifies the service before
+sending and checks every receipt, run the local verifying proxy
+`npx private-ai-proxy serve https://api.envolvr.xyz` and point the client at
+`http://127.0.0.1:4180/v1`.
+
+Any wallet works for sign-in and deposits: implement `Signer` (`address`,
+`signMessage`, and `sendTransaction` for deposits) around viem, ethers or a
+hardware wallet.
+
+## Pricing
+
+Per-token prices are the providers' own list prices (`envolvr models`). A fee
+is kept from each USDG deposit (`envolvr pricing`). Every receipt records the
+token counts, the rates and the amount billed, so any charge can be recomputed.
+If a request allows several providers, it is priced at the highest of their
+list prices.

package/dist/api.d.ts

@@ -0,0 +1,76 @@
+import { type Network } from './network.ts';
+import type { Signer } from './wallet.ts';
+/** The message the sign-in signs; the SDK signs nothing else. */
+export declare function signInMessage(wallet: string, nonce: string, issuedAt: string): string;
+/**
+ * Sign in with a wallet and get an API key. The key is shown once; keep it.
+ * Each sign-in issues a new key; earlier keys keep working.
+ */
+export declare function signIn(signer: Signer, network?: Network): Promise<{
+    apiKey: string;
+    wallet: string;
+}>;
+/** The message that closes an account; the SDK signs nothing else for it. */
+export declare function closeAccountMessage(wallet: string, refundTo: string, nonce: string, issuedAt: string): string;
+/**
+ * Close the account of `signer`'s wallet: every API key stops working, and the
+ * balance (net of deposit fees; the staking allowance is not money) is refunded
+ * to `refundTo`, by default the wallet itself. The refund is paid from the
+ * credit vault shortly after.
+ */
+export declare function closeAccount(signer: Signer, opts?: {
+    refundTo?: string;
+    network?: Network;
+}): Promise<{
+    closed: boolean;
+    revokedKeys: number;
+    refund?: {
+        id: number;
+        amountMicros: string;
+        status: 'pending' | 'held';
+        refundTo: string;
+    };
+}>;
+export interface Account {
+    wallet: string;
+    /** USDG balance, micro-USD (6 decimals), as a decimal string. */
+    balanceMicros: string;
+    /** Today's staking allowance and what is left of it, micro-USD. */
+    allowanceTodayMicros: string;
+    allowanceLeftMicros: string;
+}
+export declare function getAccount(apiKey: string, network?: Network): Promise<Account>;
+export interface Pricing {
+    /** Kept from each USDG deposit, in basis points (500 = 5%). */
+    depositFeeBps: number;
+    tokenPricing: string;
+}
+export declare function getPricing(network?: Network): Promise<Pricing>;
+/** What a deposit of `amountMicros` credits at `feeBps` (the fee rounds down). */
+export declare function netCredit(amountMicros: bigint, feeBps: number): bigint;
+/**
+ * Deposit USDG into the credit vault for `account` (default: the signer's own
+ * wallet, the one that signs in). Approves the vault first when needed. The
+ * balance is credited, net of the deposit fee, within seconds of the deposit
+ * being mined. Deposit from a wallet you control; a plain USDG transfer to the
+ * vault is not credited.
+ */
+export declare function depositUsdg(opts: {
+    signer: Signer;
+    amountMicros: bigint;
+    account?: string;
+    network?: Network;
+}): Promise<{
+    approveTx: string | undefined;
+    depositTx: string;
+    account: string;
+    amountMicros: bigint;
+    depositFeeBps: number;
+    expectedCreditMicros: bigint;
+}>;
+/** Testnet only: mint test USDG to the signer (the test token has an open mint). */
+export declare function mintTestUsdg(opts: {
+    signer: Signer;
+    amountMicros: bigint;
+    network?: Network;
+}): Promise<string>;

package/dist/api.js

@@ -0,0 +1,112 @@
+// envolvr's HTTP surface for an agent: sign in with a wallet, read the account
+// and the pricing, and move USDG into the credit vault.
+import { decodeWords, encodeCall, Rpc } from "./evm.js";
+import { TESTNET } from "./network.js";
+async function json(res) {
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(`${new URL(res.url).pathname}: ${res.status} ${body.error ?? ''}`.trim());
+    return body;
+}
+/** The message the sign-in signs; the SDK signs nothing else. */
+export function signInMessage(wallet, nonce, issuedAt) {
+    return ['envolvr: sign in to get an API key.', '', `Wallet: ${wallet.toLowerCase()}`, `Nonce: ${nonce}`, `Issued At: ${issuedAt}`]
+        .join('\n');
+}
+/**
+ * Sign in with a wallet and get an API key. The key is shown once; keep it.
+ * Each sign-in issues a new key; earlier keys keep working.
+ */
+export async function signIn(signer, network = TESTNET) {
+    const n = await json(await fetch(`${network.control}/auth/nonce?wallet=${signer.address}`));
+    const expected = signInMessage(signer.address, n.nonce, n.issuedAt);
+    if (n.message !== expected)
+        throw new Error('the sign-in message is not the one envolvr defines; refusing to sign it');
+    const signature = await signer.signMessage(expected);
+    return json(await fetch(`${network.control}/auth/key`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ wallet: signer.address, nonce: n.nonce, issuedAt: n.issuedAt, signature }),
+    }));
+}
+/** The message that closes an account; the SDK signs nothing else for it. */
+export function closeAccountMessage(wallet, refundTo, nonce, issuedAt) {
+    return ['envolvr: close this account and refund its balance.', '', `Wallet: ${wallet.toLowerCase()}`,
+        `Refund to: ${refundTo.toLowerCase()}`, `Nonce: ${nonce}`, `Issued At: ${issuedAt}`].join('\n');
+}
+/**
+ * Close the account of `signer`'s wallet: every API key stops working, and the
+ * balance (net of deposit fees; the staking allowance is not money) is refunded
+ * to `refundTo`, by default the wallet itself. The refund is paid from the
+ * credit vault shortly after.
+ */
+export async function closeAccount(signer, opts = {}) {
+    const network = opts.network ?? TESTNET;
+    const refundTo = opts.refundTo ?? signer.address;
+    const n = await json(await fetch(`${network.control}/account/close/nonce?wallet=${signer.address}&refundTo=${refundTo}`));
+    const expected = closeAccountMessage(signer.address, refundTo, n.nonce, n.issuedAt);
+    if (n.message !== expected)
+        throw new Error('the close message is not the one envolvr defines; refusing to sign it');
+    const signature = await signer.signMessage(expected);
+    return json(await fetch(`${network.control}/account/close`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ wallet: signer.address, refundTo, nonce: n.nonce, issuedAt: n.issuedAt, signature }),
+    }));
+}
+export async function getAccount(apiKey, network = TESTNET) {
+    return json(await fetch(`${network.control}/account`, { headers: { authorization: `Bearer ${apiKey}` } }));
+}
+export async function getPricing(network = TESTNET) {
+    return json(await fetch(`${network.control}/pricing`));
+}
+/** What a deposit of `amountMicros` credits at `feeBps` (the fee rounds down). */
+export function netCredit(amountMicros, feeBps) {
+    return amountMicros - (amountMicros * BigInt(feeBps)) / 10000n;
+}
+/**
+ * Deposit USDG into the credit vault for `account` (default: the signer's own
+ * wallet, the one that signs in). Approves the vault first when needed. The
+ * balance is credited, net of the deposit fee, within seconds of the deposit
+ * being mined. Deposit from a wallet you control; a plain USDG transfer to the
+ * vault is not credited.
+ */
+export async function depositUsdg(opts) {
+    const network = opts.network ?? TESTNET;
+    const { signer, amountMicros } = opts;
+    if (!signer.sendTransaction)
+        throw new Error('this signer cannot send transactions');
+    if (amountMicros <= 0n)
+        throw new Error('the amount must be positive');
+    const rpc = new Rpc(network.rpcUrl);
+    const view = async (to, sig, args) => BigInt(decodeWords(await rpc.call('eth_call', [{ to, data: encodeCall(sig, args) }, 'latest']))[0]);
+    const balance = await view(network.usdg, 'balanceOf(address)', [signer.address]);
+    if (balance < amountMicros)
+        throw new Error(`the wallet holds ${balance} micro-USDG, less than ${amountMicros}`);
+    const { depositFeeBps } = await getPricing(network);
+    let approveTx;
+    if ((await view(network.usdg, 'allowance(address,address)', [signer.address, network.creditVault])) < amountMicros) {
+        approveTx = await signer.sendTransaction({
+            to: network.usdg, data: encodeCall('approve(address,uint256)', [network.creditVault, amountMicros]),
+        });
+    }
+    const account = opts.account ?? signer.address;
+    const depositTx = await signer.sendTransaction({
+        to: network.creditVault,
+        data: account.toLowerCase() === signer.address.toLowerCase()
+            ? encodeCall('deposit(uint256)', [amountMicros])
+            : encodeCall('depositFor(address,uint256)', [account, amountMicros]),
+    });
+    return { approveTx, depositTx, account, amountMicros, depositFeeBps, expectedCreditMicros: netCredit(amountMicros, depositFeeBps) };
+}
+/** Testnet only: mint test USDG to the signer (the test token has an open mint). */
+export async function mintTestUsdg(opts) {
+    const network = opts.network ?? TESTNET;
+    if (network.chainId !== TESTNET.chainId)
+        throw new Error('mintTestUsdg is for the testnet only');
+    if (!opts.signer.sendTransaction)
+        throw new Error('this signer cannot send transactions');
+    return opts.signer.sendTransaction({
+        to: network.usdg, data: encodeCall('mint(address,uint256)', [opts.signer.address, opts.amountMicros]),
+    });
+}

package/dist/attest.d.ts

@@ -0,0 +1,58 @@
+import type { Network } from './network.ts';
+export declare const PAP_PACKAGE = "private-ai-proxy@0.1.6";
+export interface PapResult {
+    /** True only when pap's verdict is VERIFIED (exit 0). */
+    verified: boolean;
+    /** pap's --json transcript, or its text output when that is not JSON. */
+    transcript: unknown;
+    stderr: string;
+}
+export declare function runPap(args: string[], opts?: {
+    timeoutMs?: number;
+}): Promise<PapResult>;
+/**
+ * Verify the live gateway: a fresh nonce, the TDX quote, the measured compose
+ * and source, and the TLS key being served. `acceptCompose` pins the compose
+ * hashes you accept; without it pap verifies and reports the measurement and
+ * you appraise it yourself.
+ */
+export declare function verifyGateway(network: Network, opts?: {
+    acceptCompose?: string[];
+}): Promise<PapResult>;
+/** A fresh 32-byte attestation nonce (64 lowercase hex). */
+export declare const newNonce: () => string;
+/** Fetch the gateway's attestation report for a nonce (to keep beside receipts). */
+export declare function fetchAttestationReport(network: Network, nonce?: string): Promise<{
+    nonce: string;
+    report: Record<string, unknown>;
+}>;
+/**
+ * Check a saved receipt offline against the attestation report of the keyset
+ * that signed it: the report itself (quote, binding, provenance), the receipt
+ * signature, and, when given, the exact request and response bytes against the
+ * receipt's commitments.
+ */
+export declare function auditReceipt(opts: {
+    reportPath: string;
+    nonce?: string;
+    receiptPath: string;
+    requestBodyPath?: string;
+    responseBodyPath?: string;
+    sessionPath?: string;
+    acceptCompose?: string[];
+}): Promise<PapResult>;
+export interface AuditCheck {
+    id: string;
+    title: string;
+    status: 'pass' | 'fail' | 'skip';
+    detail: string;
+}
+/** What an offline audit establishes, by name. */
+export interface AuditSummary {
+    /** The receipt's signature, keyset, commitments and cited session all check out, and nothing failed. */
+    signed: boolean;
+    checks: Record<string, AuditCheck | undefined>;
+    failed: AuditCheck[];
+}
+export declare const AUDIT_CHECKS: Record<string, string>;
+export declare function summarizeAudit(result: PapResult): AuditSummary;

package/dist/attest.js

@@ -0,0 +1,85 @@
+// Attestation: is this really envolvr's measured gateway, and did it sign this
+// receipt? The checks are done by private-ai-proxy (pap), the open verifier for
+// the ACI protocol the gateway speaks (TDX quote to Intel's root, keyset and
+// nonce binding, source provenance, TLS channel binding, receipt signature,
+// request and response commitments). This module runs it and reads its verdict.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+export const PAP_PACKAGE = 'private-ai-proxy@0.1.6';
+export function runPap(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npx', ['-y', PAP_PACKAGE, ...args, '--json', '--non-interactive'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => child.kill('SIGTERM'), opts.timeoutMs ?? 300_000);
+        child.stdout.on('data', (d) => { stdout += d; });
+        child.stderr.on('data', (d) => { stderr += d; });
+        child.on('error', (err) => { clearTimeout(timer); reject(new Error(`could not run ${PAP_PACKAGE} (needs npx): ${err.message}`)); });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            let transcript = stdout.trim();
+            try {
+                transcript = JSON.parse(stdout);
+            }
+            catch { /* keep the text */ }
+            resolve({ verified: code === 0, transcript, stderr: stderr.trim() });
+        });
+    });
+}
+/**
+ * Verify the live gateway: a fresh nonce, the TDX quote, the measured compose
+ * and source, and the TLS key being served. `acceptCompose` pins the compose
+ * hashes you accept; without it pap verifies and reports the measurement and
+ * you appraise it yourself.
+ */
+export function verifyGateway(network, opts = {}) {
+    return runPap(['verify', '--require-production-os',
+        ...(opts.acceptCompose ?? []).flatMap((h) => ['--accept-compose', h]), network.gateway]);
+}
+/** A fresh 32-byte attestation nonce (64 lowercase hex). */
+export const newNonce = () => randomBytes(32).toString('hex');
+/** Fetch the gateway's attestation report for a nonce (to keep beside receipts). */
+export async function fetchAttestationReport(network, nonce = newNonce()) {
+    const res = await fetch(`${network.gateway}/v1/aci/attestation?nonce=${nonce}`);
+    if (!res.ok)
+        throw new Error(`attestation report: HTTP ${res.status}`);
+    return { nonce, report: await res.json() };
+}
+/**
+ * Check a saved receipt offline against the attestation report of the keyset
+ * that signed it: the report itself (quote, binding, provenance), the receipt
+ * signature, and, when given, the exact request and response bytes against the
+ * receipt's commitments.
+ */
+export function auditReceipt(opts) {
+    return runPap([
+        'audit', '--report', opts.reportPath, '--receipt', opts.receiptPath, '--require-production-os', '--skip-expiry',
+        ...(opts.nonce ? ['--nonce', opts.nonce] : []),
+        ...(opts.requestBodyPath ? ['--request-body', opts.requestBodyPath] : []),
+        ...(opts.responseBodyPath ? ['--response-body', opts.responseBodyPath] : []),
+        ...(opts.sessionPath ? ['--session', opts.sessionPath] : []),
+        ...(opts.acceptCompose ?? []).flatMap((h) => ['--accept-compose', h]),
+    ]);
+}
+// pap's check ids (ACI spec sections): what each one tells an agent.
+export const AUDIT_CHECKS = {
+    'receipt-1': 'receipt signature by the attested key',
+    'receipt-2': 'receipt names the attested keyset',
+    'receipt-3': 'request commitment matches the bytes sent',
+    'receipt-4': 'response commitment matches the bytes received',
+    'upstream-1': 'provider enclave verified before forwarding',
+    'upstream-2': 'cited provider session checks out',
+    'id-2': 'keyset bound into the TDX quote',
+    'id-4': 'workload measured and linked to public source',
+    'policy-os': 'production dstack OS image',
+    'id-1': 'TDX quote chains to Intel (checked live by verify-gateway)',
+};
+export function summarizeAudit(result) {
+    const transcript = result.transcript;
+    const all = typeof transcript === 'object' && Array.isArray(transcript.checks) ? transcript.checks : [];
+    const checks = Object.fromEntries(Object.keys(AUDIT_CHECKS).map((id) => [id, all.find((c) => c.id === id)]));
+    const failed = all.filter((c) => c.status === 'fail');
+    const required = ['receipt-1', 'receipt-2', 'id-2', 'id-4', 'policy-os', 'upstream-1'];
+    const signed = failed.length === 0 && required.every((id) => checks[id]?.status === 'pass');
+    return { signed, checks, failed };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};