@aptos-labs/inference-verifier 0.1.0 → 0.1.1

package/README.md

@@ -1,4 +1,85 @@
-Offline attestation verifier for the Aptos inference router.
+# @aptos-labs/inference-verifier
 
-`verifyRouterDocument` checks one attestation document. It uses the Intel
-collateral carried in that document and does not contact Intel or Sigstore.
+`@aptos-labs/inference-verifier` verifies attestation documents from the Aptos confidential inference router. It validates Intel TDX evidence, signed release provenance, and hardware measurements using the collateral included in the document and the package's bundled trust roots. Verification runs locally without contacting Intel, GitHub, Sigstore, or the attestation collateral service (ATC).
+
+The package is implemented in TypeScript, is distributed as an ECMAScript module (ESM), and requires Node.js 22 or later. Browser runtimes are not supported.
+
+## Installation
+
+```sh
+npm install @aptos-labs/inference-verifier
+```
+
+[`@aptos-labs/inference-sdk`](https://www.npmjs.com/package/@aptos-labs/inference-sdk) integrates this verifier with attestation retrieval and TLS pinning. Use the verifier directly when implementing those parts of the client yourself.
+
+## Usage
+
+Call `verifyRouterDocument` with the received document bytes, the nonce used to request that document, the trusted source repository, and the current time:
+
+```ts
+import { verifyRouterDocument } from "@aptos-labs/inference-verifier";
+
+const evidence = verifyRouterDocument(
+  bytes,
+  nonce,
+  "aptos-labs/confidential-inference-router",
+  Math.floor(Date.now() / 1000),
+);
+```
+
+The function is synchronous and returns a `RouterEvidence` object after all checks pass.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `bytes` | `Uint8Array` | Complete UTF-8 JSON attestation document in the Tinfoil v3 format, including its collateral. The maximum size is 4 MiB. |
+| `nonce` | `Uint8Array` | The 32-byte nonce generated by the caller and sent in the attestation request. |
+| `repo` | `string` | Trusted GitHub repository in `owner/repo` format, without a URL prefix or `@tag` suffix. |
+| `nowSecs` | `number` | Current Unix time in seconds, used to check Intel certificate, revocation-list, and collateral validity. |
+
+Generate a fresh random nonce for each attestation request and retain it for verification. The repository and verification time come from the caller's configuration and clock; the document does not establish those trusted inputs.
+
+To require a specific release, compare `evidence.releaseTag` with the expected tag after verification. The SDK performs this comparison when its `configRepo` option includes an `@tag` suffix.
+
+## Verification policy
+
+The verifier accepts Intel TDX quote version 4 for the router's GPU-less `small_0d_v011` hardware profile. Verification covers:
+
+- The document structure and the quote's binding to the request nonce, TLS key fingerprint, and HPKE key.
+- Intel DCAP signatures, certificate chains, revocation lists, and collateral validity, with an `UpToDate` trusted computing base (TCB) status.
+- The required TDX module measurements, security versions, attributes, and zero-valued RTMR3.
+- Sigstore release provenance from a GitHub-hosted Actions workflow on a tag in the trusted repository, with RTMR1 and RTMR2 matching the quote.
+- A signed hardware catalog from `tinfoilsh/hardware-measurements`, with MRTD and RTMR0 matching the accepted profile.
+
+The policy does not require host-specific platform endorsements or release freshness witnesses. A nonce binds the evidence to a request, but does not establish that the attested release is the latest release or remains approved for deployment. Historical releases can pass verification when they satisfy the repository and measurement checks and the Intel collateral is valid.
+
+## Returned evidence
+
+The package exports the `RouterEvidence` type with the following fields:
+
+| Field | Description |
+| --- | --- |
+| `tlsPublicKey` | SHA-256 fingerprint of the TLS public key's DER-encoded SubjectPublicKeyInfo (SPKI), represented as lowercase hexadecimal. |
+| `hpkePublicKey` | The 32-byte X25519 HPKE public key, represented as lowercase hexadecimal. |
+| `mrtd` | The trust domain's initial measurement, represented as lowercase hexadecimal. |
+| `rtmrs` | A tuple containing RTMR0 through RTMR3, each represented as lowercase hexadecimal. |
+| `hardware` | Matched hardware profile and catalog digest in `profile@digest` format. |
+| `releaseDigest` | SHA-256 subject digest from the verified release provenance. |
+| `releaseTag` | Release tag established by the verified GitHub Actions identity. |
+| `codeMeasurement` | Measurement predicate type and register values from the signed code provenance, ordered as SNP, RTMR1, and RTMR2. |
+| `tcbStatus` | Verified Intel TCB status. Successful verification requires `UpToDate`. |
+| `collateralExpiresAt` | Earlier of the Intel TCB information and quoting enclave identity `nextUpdate` timestamps, in Unix seconds. |
+
+The caller is responsible for comparing `tlsPublicKey` with the SPKI fingerprint of the TLS connection that delivered the document, and for enforcing that pin on subsequent connections while retaining normal certificate and hostname validation. The verifier does not manage connections or cached sessions. Certificate and revocation-list expiry are checked during verification; they are not included in `collateralExpiresAt`.
+
+## Error handling
+
+Validation failures raise `VerificationError`, which the package exports alongside the `VerificationCategory` type. The error's `message` describes the failure, and its `category` identifies the failed check:
+
+| Category | Description |
+| --- | --- |
+| `envelope` | Invalid document structure, unsupported document format, or a nonce or report-data mismatch. |
+| `encoding` | Invalid JSON, UTF-8, or binary-field encoding. |
+| `dcap` | Invalid Intel quote, signature, certificate chain, revocation data, or collateral. |
+| `tdx` | TDX measurements, attributes, security versions, or TCB status fail the required policy. |
+| `provenance` | Missing or invalid Sigstore evidence, an unexpected publisher, or code measurements that do not match the quote. |
+| `policy` | Unsupported repository format, CPU or device evidence, missing required keys, or an unrecognized hardware profile. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aptos-labs/inference-verifier",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Offline attestation verifier for the Aptos inference router.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,7 +32,7 @@
   "devDependencies": {
     "@types/node": "24.10.1",
     "typescript": "5.9.3",
-    "vitest": "3.2.4"
+    "vitest": "5.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",