@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/tee.d.ts

@@ -0,0 +1,253 @@
+import type { Address } from "../types.js";
+import { type CardPeriod, type CardPolicy, type CheckoutIntent, type Reservation } from "./accounts.js";
+export type SignMessageWallet = {
+    publicKey: Address;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+};
+/** Anything shaped like a Solana wallet adapter or wallet-standard account with signMessage. */
+export type WalletAdapterLike = {
+    publicKey: {
+        toBase58(): string;
+    } | string | null | undefined;
+    signMessage?: (message: Uint8Array) => Promise<Uint8Array | {
+        signature: Uint8Array;
+    } | Array<{
+        signature: Uint8Array;
+    }>>;
+};
+/** Signer for a server keypair (Axum authorizer, scripts). The secret stays in this closure. */
+export declare function keypairSigner(secretKey: Uint8Array): Promise<SignMessageWallet>;
+/** Signer for a browser wallet (Phantom via wallet adapter, or wallet-standard). */
+export declare function walletAdapterSigner(adapter: WalletAdapterLike): SignMessageWallet;
+export declare function base58Encode(bytes: Uint8Array): string;
+export type TeeSessionOptions = {
+    teeUrl?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+};
+export declare class TeeAuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * One wallet's authenticated connection to the private rollup. Refreshes the
+ * token when it is within 24 h of expiry or after any 401. The token is held
+ * in a private field and never leaves this object except through
+ * `endpoint()`, which exists only to build a Connection for sending
+ * owner-signed transactions.
+ */
+export declare class TeeSession {
+    #private;
+    readonly wallet: Address;
+    readonly teeUrl: string;
+    private constructor();
+    static open(signer: SignMessageWallet, options?: TeeSessionOptions): Promise<TeeSession>;
+    get expiresAt(): number;
+    needsRefresh(): boolean;
+    refresh(): Promise<void>;
+    ensureFresh(): Promise<void>;
+    /** SECRET: the tokenized RPC URL. Use only to construct a Connection; never log or display it. */
+    endpoint(): Promise<string>;
+    /** Raw JSON-RPC over the session. Retries once after a 401 with a fresh token. */
+    rpc(method: string, params: unknown[]): Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    toJSON(): {
+        wallet: string;
+        teeUrl: string;
+        expiresAt: number;
+        token: string;
+    };
+}
+/** Contract name (§10): open a TEE session for a keypair- or wallet-backed signer. */
+export declare function getTeeSession(wallet: SignMessageWallet, options?: TeeSessionOptions): Promise<TeeSession>;
+export type TeeRawAccount = {
+    owner: Address;
+    lamports: bigint;
+    data: Uint8Array;
+    executable: boolean;
+};
+/**
+ * `not_visible` is NOT "missing". The rollup answers a private account the
+ * caller may not read exactly like an account that doesn't exist.
+ */
+export type TeeRead<T> = {
+    state: "visible";
+    account: T;
+    slot: bigint;
+} | {
+    state: "not_visible";
+    slot: bigint | null;
+} | {
+    state: "rpc_error";
+    code: string;
+};
+export type TeeReadCommitment = "processed" | "confirmed" | "finalized";
+export declare function readTeeAccount(session: TeeSession, address: Address, commitment?: TeeReadCommitment): Promise<TeeRead<TeeRawAccount>>;
+/** Display shape of a policy: cent strings, hex hashes, no bigint. */
+export type CardPolicyView = {
+    policyVersion: number;
+    authorizer: Address;
+    budgetCents: string;
+    maxPurchaseCents: string;
+    maxPurchasesPerPeriod: number;
+    periodSeconds: number;
+    currency: string;
+    merchantIdHashes: string[];
+    mccs: number[];
+    expiresAt: string | null;
+    recurringAllowed: boolean;
+    feeBps: number;
+    maxObligationCents: string;
+    frozen: boolean;
+    freezeReason: CardPolicy["freezeReason"];
+    recoveryState: CardPolicy["recoveryState"];
+    statementOutstandingCents: string;
+    exceptionsOpen: number;
+    members: Array<{
+        pubkey: Address;
+        flags: number;
+    }>;
+    ledgerSeq: string;
+    commitSeq: string;
+};
+export declare function cardPolicyView(policy: CardPolicy): CardPolicyView;
+export declare function readCardPolicy(session: TeeSession, policyAddress: Address, programId?: Address): Promise<TeeRead<CardPolicyView>>;
+export declare function readCardPeriod(session: TeeSession, periodAddress: Address, programId?: Address): Promise<TeeRead<CardPeriod>>;
+export declare function readReservation(session: TeeSession, address: Address, programId?: Address): Promise<TeeRead<Reservation>>;
+export declare function readCheckoutIntent(session: TeeSession, address: Address, programId?: Address): Promise<TeeRead<CheckoutIntent>>;
+/** Budget left this period, only when both accounts are visible to this wallet. */
+export declare function readAvailableCents(session: TeeSession, accounts: {
+    policy: Address;
+    period: Address;
+}, programId?: Address): Promise<TeeRead<{
+    availableCents: string;
+    periodIndex: number;
+}>>;
+/** Plain-language status for any read. Never says "missing" for `not_visible`. */
+export declare function describeTeeRead(read: TeeRead<unknown>): string;
+/** Authorizer path (CD-4): anything but a visible read means stop. */
+export declare function requireVisible<T>(read: TeeRead<T>, what: string): T;
+export type TeeMeasurement = {
+    mrTd: string;
+    rtMr0: string;
+    rtMr1: string;
+    rtMr2: string;
+    /** Optional extra registers. When an allowlist entry pins one, the observed quote must match it too. */
+    rtMr3?: string;
+    mrOwner?: string;
+    label?: string;
+};
+/** What one fresh TDX quote showed. */
+export type TeeQuoteAttestation = {
+    /**
+     * `verified`: Intel's DCAP signature chain checked and the quote echoes our fresh challenge.
+     * `challenge_bound`: the quote echoes our fresh challenge, but its signature chain wasn't checked.
+     */
+    hardware: "verified" | "challenge_bound";
+    measurements: TeeMeasurement;
+};
+export type TeeIntegrityProvider = {
+    /** Fresh-challenge quote check (genuine TDX hardware). Throws on failure. */
+    verifyRpcIntegrity(teeUrl: string): Promise<void>;
+    verifyIntegrity?(teeUrl: string): Promise<void>;
+    /** Parse MRTD/RTMR0-2 from a fresh quote. Optional: only needed once an allowlist exists. */
+    readMeasurements?(teeUrl: string): Promise<TeeMeasurement>;
+    /**
+     * Preferred: one fresh quote gives both the hardware verdict and the measurements,
+     * so the build we compare is the one whose signature was checked. Throws on failure.
+     */
+    attestQuote?(teeUrl: string): Promise<TeeQuoteAttestation>;
+};
+export type AttestationMode = "report" | "enforce";
+export type AttestationResult = {
+    mode: AttestationMode;
+    hardware: "verified" | "challenge_bound" | "failed";
+    measurements: "matched" | "mismatch" | "pending" | "unavailable";
+    /** Whether an authorizer may keep approving purchases. */
+    ok: boolean;
+    label: string;
+    checkedAt: string;
+    /** Which pinned entry matched (`current` / `previous` label), when one did. */
+    matchedLabel?: string;
+};
+export type VerifyTeeOptions = {
+    mode: AttestationMode;
+    teeUrl?: string;
+    /**
+     * Allowed workload measurements (current + previous). Omitted: the pinned
+     * MagicBlock values for the Devnet TEE, nothing for any other URL. An empty
+     * list means "pending" (and fails closed in enforce mode).
+     */
+    allowlist?: readonly TeeMeasurement[];
+    provider?: TeeIntegrityProvider;
+    now?: () => number;
+};
+/**
+ * MagicBlock Devnet TEE validator measurements (gate G-MB).
+ *
+ * Observed by ChainPay in a fresh quote from devnet-tee.magicblock.app on
+ * 2026-10-03 (and again 2026-10-04), then confirmed by MagicBlock directly to
+ * Dre on 2026-10-04. That confirmation is not a signed or published source, so
+ * the provenance label says so.
+ *
+ * Rotation: when MagicBlock upgrades the validator, move `current` to
+ * `previous`, pin the new values as `current`, and drop `previous` once the
+ * old build is gone. Deployments can also pass an extra entry through
+ * `teeMeasurementAllowlist(extra)` (Axum: `CARDS_TEE_MEASUREMENTS`; frontend:
+ * `VITE_CHAINPAY_TEE_MEASUREMENTS_PREVIOUS`) without a release.
+ * Mirrored for Axum in shared/cards/tee-measurements.json (a test keeps them equal).
+ */
+export declare const MAGICBLOCK_DEVNET_TEE_MEASUREMENTS: {
+    readonly teeUrl: string;
+    readonly validator: Address;
+    readonly provenance: string;
+    readonly current: Required<Omit<TeeMeasurement, "label">> & {
+        label: string;
+    };
+    readonly previous: (TeeMeasurement & {
+        label: string;
+    }) | null;
+};
+/** The pinned Devnet allowlist: `current`, then `previous` if a rotation is in progress, then any `extra` entries. */
+export declare function teeMeasurementAllowlist(extra?: readonly TeeMeasurement[]): TeeMeasurement[];
+/**
+ * Parse an allowlist (JSON list). Accepts the SDK keys (`mrTd`, `rtMr0`…) and
+ * Axum's `CARDS_TEE_MEASUREMENTS` keys (`mrtd`, `rtmr0`…). Rejects anything
+ * that isn't 48-byte hex.
+ */
+export declare function parseMeasurementAllowlist(json: string | undefined): TeeMeasurement[];
+/**
+ * Read the TD 1.0 report of a TDX quote (v4 or v5 with a TD10 body): MRTD,
+ * MROWNER, RTMR0-3 and the 64-byte report data. Parsing only; it proves
+ * nothing about who signed the quote.
+ */
+export declare function parseTdxQuote(raw: Uint8Array): {
+    measurements: Required<Omit<TeeMeasurement, "label">>;
+    reportData: Uint8Array;
+};
+export type TdxQuoteProviderOptions = {
+    fetch?: typeof fetch;
+    /**
+     * Verifies Intel's DCAP signature chain over the raw quote (e.g.
+     * `@phala/dcap-qvl` getCollateral + verify). Throws when the quote isn't
+     * genuine. Without it the provider reports `challenge_bound` only.
+     */
+    verifyQuote?: (raw: Uint8Array) => Promise<void>;
+    /** Test hook for the 64-byte challenge. */
+    randomBytes?: (length: number) => Uint8Array;
+};
+/**
+ * Attestation from one fresh quote: GET `{tee}/quote?challenge=<base64 64 bytes>`
+ * (the endpoint MagicBlock's verifyTeeRpcIntegrity uses), require the report
+ * data to equal our challenge, optionally verify the DCAP chain, and return
+ * the measurements of that same quote.
+ */
+export declare function createTdxQuoteProvider(options?: TdxQuoteProviderOptions): TeeIntegrityProvider;
+/**
+ * Default provider: MagicBlock's own verifiers, loaded only when installed
+ * (`@magicblock-labs/ephemeral-rollups-sdk` is optional, not an SDK dependency).
+ */
+export declare function loadMagicBlockIntegrityProvider(): Promise<TeeIntegrityProvider>;
+export declare function verifyTee(options: VerifyTeeOptions): Promise<AttestationResult>;