@premai/reticle 0.3.0

package/README.md

@@ -0,0 +1,113 @@
+# reticle
+
+Hardware attestation SDK for JavaScript and TypeScript. Cryptographically verifies AMD SEV-SNP, Intel TDX, and NVIDIA GPU attestations from an [attestation server](https://github.com/prem-research/reticle) — runs in Node.js, Bun, Deno and the browser via WASM.
+
+## Install
+
+```bash
+npm install @premai/reticle
+```
+
+## Quick start
+
+```typescript
+import { ClientBuilder } from "@premai/reticle";
+
+const client = new ClientBuilder("https://attestation.example.com")
+  .build();
+
+// End-to-end attestation: discovers modules, generates nonces,
+// verifies cryptographic signatures and certificate chains
+const result = await client.attest();
+
+console.log("CPU:", result.modules().cpu());   // CpuModule.Sev or CpuModule.Tdx
+console.log("GPU:", result.modules().gpu());   // GpuModule.Nvidia or undefined
+```
+
+## API
+
+### `ClientBuilder`
+
+Creates and configures a `Client` instance.
+
+```typescript
+const client = new ClientBuilder(url)
+  .with_authorization("Bearer <token>")  // optional: set Authorization header
+  .with_kds(new Kds(kdsUrl))             // optional: custom AMD KDS cache
+  .with_pcs(new Pcs(pcsUrl))             // optional: custom Intel PCS cache
+  .build();
+```
+
+### `Client`
+
+#### High-level (recommended)
+
+These methods handle nonce generation, request, and full cryptographic verification in a single call:
+
+| Method | Description |
+|---|---|
+| `client.attest(query?)` | Full attestation of all available modules (CPU + GPU) |
+| `client.attest_sev(query?)` | AMD SEV-SNP attestation only |
+| `client.attest_tdx(query?)` | Intel TDX attestation only |
+| `client.attest_nvidia(query?)` | NVIDIA GPU attestation only |
+
+#### Low-level
+
+These methods fetch and parse attestation evidence (**discouraged**) — useful when you need to inspect raw data or implement custom validation:
+
+| Method | Description |
+|---|---|
+| `client.request_modules(query?)` | List available attestation modules on the server |
+| `client.request_sev(nonce, query)` | Fetch raw SEV-SNP attestation report |
+| `client.request_tdx(nonce, query)` | Fetch raw TDX quote |
+| `client.request_nvidia(nonce, query)` | Fetch raw NVIDIA EAT/JWT token |
+
+### `QueryParams`
+
+Pass custom query parameters to the attestation server. The `nonce` key is reserved and will throw if used.
+
+```typescript
+const query = new QueryParams()
+  .with("model", "my-model")
+  .with("version", "1.0");
+
+await client.attest(query);
+```
+
+### Sub-module access
+
+Lower-level types from the attestation modules are available under namespaces:
+
+```typescript
+import { nvidia, sev } from "@premai/reticle";
+
+// NVIDIA: manual token parsing and verification
+const keychain = await nvidia.fetch_keychain();
+const token = nvidia.EATToken.parse(rawJwt);
+const claims = token.verify(keychain);
+claims.validate(nonce);
+
+// AMD SEV-SNP: manual certificate chain verification
+const kds = new sev.Kds("https://kcds.prem.io");
+const chain = await kds.fetch_certificates(attestation);
+attestation.verify(chain, nonce);
+```
+
+## Memory management
+
+WASM objects are not garbage-collected automatically. Call `.free()` when done, or use `using` (TypeScript 5.2+) for automatic disposal:
+
+```typescript
+using client = new ClientBuilder(url).build();
+using result = await client.attest();
+// automatically freed at end of scope
+```
+
+## Examples
+
+- **[Bun](../examples/bun)** — minimal CLI attestation
+- **[Vite](../examples/vite)** — browser UI with attestation status
+
+## License
+
+See [LICENSE](../LICENSE).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@premai/reticle",
+  "type": "module",
+  "version": "0.3.0",
+  "files": [
+    "prem_rs_bg.wasm",
+    "prem_rs.js",
+    "prem_rs_bg.js",
+    "prem_rs.d.ts",
+    "prem_rs_bg.js"
+  ],
+  "main": "prem_rs_main.js",
+  "types": "prem_rs.d.ts",
+  "sideEffects": [
+    "./prem_rs.js",
+    "./snippets/*"
+  ],
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./prem_rs.d.ts",
+        "default": "./prem_rs.js"
+      },
+      "default": {
+        "types": "./prem_rs.d.ts",
+        "default": "./prem_rs_main.js"
+      }
+    }
+  }
+}

package/prem_rs.d.ts

@@ -0,0 +1,327 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class AttestHeaders {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cpu(): ResponseHeaders | undefined;
+    gpu(): ResponseHeaders | undefined;
+}
+
+export class AttestResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    headers(): AttestHeaders;
+    modules(): Modules;
+}
+
+export class Client {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Steps:
+     * - Gathers modules to attest from attestation server
+     * - Iterates through each module and performs end-to-end attestation
+     * - Returns the list of attested modules
+     */
+    attest(query?: QueryParams | null): Promise<AttestResult>;
+    /**
+     * Completes end-to-end nvidia attestation. Generates nonce and validates claims all in one
+     */
+    attest_nvidia(query?: QueryParams | null): Promise<ResponseHeaders>;
+    /**
+     * Performs end-to-end sev-snp attestation. Generates nonce and validates claims all in one
+     */
+    attest_sev(query?: QueryParams | null): Promise<void>;
+    /**
+     * Performs end-to-end tdx attestation. Generates nonce and validates claims all in one
+     */
+    attest_tdx(query?: QueryParams | null): Promise<void>;
+    /**
+     * Gather available attestable modules from remote attestation endpoint
+     */
+    request_modules(query?: QueryParams | null): Promise<Modules>;
+    /**
+     * Requests and parses an Nvidia EATToken attestation from the attestation server
+     *
+     * ### Warning
+     * This method exposes core functionality and does not perform cryptographic
+     * or measurement checks on the attestation. If you want to perform end-to-end attestation
+     * please refer to [`Self::attest_nvidia`]
+     */
+    request_nvidia(nonce: NvidiaNonce, query: QueryParams): Promise<NvidiaAttestResult>;
+    /**
+     * Requests and parses a SEV-SNP attestation from the attestation server.
+     *
+     * ### Warning
+     * This method exposes core functionality and does not perform cryptographic
+     * or measurement checks on the attestation. If you want to perform end-to-end attestation
+     * please refer to [`Self::attest_sev`]
+     */
+    request_sev(nonce: SevNonce, query: QueryParams): Promise<ParsedAttestation>;
+    /**
+     * Requests and parses a TDX quote
+     *
+     * ### Warning
+     * This method exposes core functionality and does not perform cryptographic
+     * or measurement checks on the attestation. If you want to perform end-to-end attestation
+     * please refer to [`Self::attest_tdx`]
+     */
+    request_tdx(nonce: TdxNonce, query: QueryParams): Promise<TdxQuote>;
+}
+
+export class ClientBuilder {
+    free(): void;
+    [Symbol.dispose](): void;
+    build(): Promise<Client>;
+    constructor(url: string);
+    /**
+     * Sets `Authorization` header
+     */
+    with_authorization(token: string): ClientBuilder;
+    /**
+     * Sets custom KDS for AMD collateral server
+     */
+    with_kds(kds: Kds): ClientBuilder;
+    /**
+     * Sets custom PCS for Intel collateral server
+     */
+    with_pcs(pcs: Pcs): ClientBuilder;
+    /**
+     * sets custom url for OPA policies index
+     */
+    with_policies_url(url: string): ClientBuilder;
+}
+
+export class Collateral {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+export enum CpuModule {
+    Sev = 0,
+    Tdx = 1,
+}
+
+export class GatewayError {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    message: string;
+}
+
+export enum GpuModule {
+    Nvidia = 0,
+}
+
+export class Modules {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cpu(): CpuModule;
+    gpu(): GpuModule | undefined;
+    has_gpu(): boolean;
+}
+
+export class NvidiaAttestResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+export class Pcs {
+    free(): void;
+    [Symbol.dispose](): void;
+    fetch_collateral(quote: TdxQuote): Promise<Collateral>;
+    constructor(base_url: string);
+}
+
+/**
+ * Generic per-request query parameters.
+ *
+ * The `nonce` key is reserved and will be rejected.
+ */
+export class QueryParams {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor();
+    /**
+     * Appends a query parameter.
+     *
+     * Reserved keywords for specific queries will get overwritten
+     */
+    with(key: string, value: string): QueryParams;
+}
+
+export class QuoteVerifier {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor(collateral: Collateral, quote: TdxQuote);
+    verify(nonce: TdxNonce): void;
+}
+
+export class ResponseHeaders {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    get(name: string): string | undefined;
+    keys(): string[];
+}
+
+export class TcbLevels {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+export class TdxNonce {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor();
+    to_hex(): string;
+}
+
+export class TdxQuote {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Attempts to parse a quote from DCAP bytes.
+     */
+    static from_bytes(quote: Uint8Array): TdxQuote;
+}
+
+declare class DecodedClaims {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+declare class EATToken {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    static parse(from: string): EATToken;
+    verify(keys: KeyChain, nonce: NvidiaNonce): DecodedClaims;
+}
+
+declare class KeyChain {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+declare class NvidiaNonce {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    static generate(): NvidiaNonce;
+    to_hex(): string;
+}
+
+/**
+ * Same as [`KeyChain:fetch_keychain`], put in for better wasm compatibility
+ */
+declare function fetch_keychain(): Promise<KeyChain>;
+
+export let nvidia: {
+    DecodedClaims: typeof DecodedClaims,
+    EATToken: typeof EATToken,
+    KeyChain: typeof KeyChain,
+    NvidiaNonce: typeof NvidiaNonce,
+    fetch_keychain: typeof fetch_keychain,
+};
+
+/**
+ * A parsed certificate revocation list
+ */
+declare class CRL {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Passes if the certificates are not in the certificate revocation list
+     * Throws `AttestationError` on fail
+     */
+    check_chain(chain: VerifiedChain): void;
+    /**
+     * Parses a certificate revocation list from DER format binary data
+     */
+    static from_der(list: Uint8Array): CRL;
+}
+
+declare class ExportPem {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    ark: Uint8Array;
+    ask: Uint8Array;
+    vek: Uint8Array;
+}
+
+declare class Kds {
+    free(): void;
+    [Symbol.dispose](): void;
+    fetch_certificates(attestation: ParsedAttestation): Promise<VerifiedChain>;
+    /**
+     * Fetches the certificate revocation list from AMD's KDS
+     */
+    fetch_crl(attestation: ParsedAttestation): Promise<CRL>;
+    constructor(cache_url: string);
+}
+
+/**
+ * Represents a parsed attestation report with some already
+ * parsed commonly accessed fields
+ */
+declare class ParsedAttestation {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cpu_fam_id(): number;
+    cpu_mod_id(): number;
+    /**
+     * Parses and constructs a new attestation report from a stream of binary data
+     */
+    static new(bytes: Uint8Array): ParsedAttestation;
+    /**
+     * Verifies the attestation report against a certificate chain
+     */
+    verify(chain: VerifiedChain, nonce: SevNonce): void;
+}
+
+declare class SevNonce {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    static generate(): SevNonce;
+    to_hex(): string;
+}
+
+/**
+ * A chain which has been cryptographically verified
+ */
+declare class VerifiedChain {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * parses a triad of ark, ask and vek certificates in the PEM format,
+     * cryptographically verifies the chain is valid, returns a `VerifiedChain` object
+     */
+    static parse_verify(ark_pem: string, ask_pem: string, vek_pem: string): VerifiedChain;
+    to_pem(): ExportPem;
+}
+
+export let sev: {
+    CRL: typeof CRL,
+    ExportPem: typeof ExportPem,
+    Kds: typeof Kds,
+    ParsedAttestation: typeof ParsedAttestation,
+    SevNonce: typeof SevNonce,
+    VerifiedChain: typeof VerifiedChain,
+};

package/prem_rs.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./prem_rs.d.ts" */
+
+import * as wasm from "./prem_rs_bg.wasm";
+import { __wbg_set_wasm } from "./prem_rs_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    AttestHeaders, AttestResult, Client, ClientBuilder, Collateral, CpuModule, GatewayError, GpuModule, Modules, NvidiaAttestResult, Pcs, QueryParams, QuoteVerifier, ResponseHeaders, TcbLevels, TdxNonce, TdxQuote
+} from "./prem_rs_bg.js";