@calimero-network/mero-js 19.25.0 → 19.27.0

package/dist/sealed/index.d.ts

@@ -1,2 +1,4 @@
-export { HANDSHAKE_PATH, SEALED_CONTENT_TYPE, SEALED_PATH, SealedTransportError, StaleTransportKeyError, createSealedFetch, fetchAttestedTransportKey, transportKeyBinding, } from './sealed.js';
-export type { SealedFetchOptions, VerifyTransportQuote } from './sealed.js';
+export { HANDSHAKE_PATH, SEALED_CONTENT_TYPE, SEALED_PATH, SealedTransportError, StaleTransportKeyError, createAttestedSealedFetch, createSealedFetch, fetchAttestedTransportKey, transportKeyBinding, } from './sealed.js';
+export type { AttestedSealedFetchOptions, SealedFetchOptions, VerifyTransportQuote } from './sealed.js';
+export { createQuoteVerifier } from './verify.js';
+export type { DcapCollateral, DcapVerifiedReport, DcapVerify, QuoteVerifier, QuoteVerifierOptions, } from './verify.js';

package/dist/sealed/index.js

@@ -1 +1,2 @@
-export { HANDSHAKE_PATH, SEALED_CONTENT_TYPE, SEALED_PATH, SealedTransportError, StaleTransportKeyError, createSealedFetch, fetchAttestedTransportKey, transportKeyBinding, } from './sealed.js';
+export { HANDSHAKE_PATH, SEALED_CONTENT_TYPE, SEALED_PATH, SealedTransportError, StaleTransportKeyError, createAttestedSealedFetch, createSealedFetch, fetchAttestedTransportKey, transportKeyBinding, } from './sealed.js';
+export { createQuoteVerifier } from './verify.js';

package/dist/sealed/noise.js

@@ -94,9 +94,17 @@ export async function initiate(remoteStatic, prologue, fixedEphemeral) {
 }
 export async function x25519KeyPair(secret) {
     if (!secret) {
-        const pair = (await crypto.subtle.generateKey({ name: 'X25519' }, true, [
-            'deriveBits',
-        ]));
+        let pair;
+        try {
+            pair = (await crypto.subtle.generateKey({ name: 'X25519' }, true, [
+                'deriveBits',
+            ]));
+        }
+        catch (error) {
+            throw new Error('Sealed transport needs WebCrypto with X25519, which this runtime lacks ' +
+                `(${error?.name ?? 'no crypto.subtle'}). Current browsers and Node have ` +
+                'it; in React Native, install react-native-quick-crypto as the global crypto.');
+        }
         const publicKey = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
         return { privateKey: pair.privateKey, publicKey };
     }

package/dist/sealed/sealed.d.ts

@@ -37,6 +37,7 @@
  */
 import type { TeeAttestRequest, TeeAttestResponseData } from '../admin-api/admin-types.js';
 import { initiate } from './noise.js';
+import type { DcapCollateral } from './verify.js';
 /** Where a session is opened, relative to the node's base URL. */
 export declare const HANDSHAKE_PATH = "/sealed/v2/handshake";
 /** Where sealed requests are posted, relative to the node's base URL. */
@@ -68,18 +69,25 @@ export declare class SealedTransportError extends Error {
 export declare function transportKeyBinding(inner: Uint8Array, transportKey: Uint8Array): Promise<Uint8Array>;
 export interface VerifyTransportQuote {
     /**
-     * Verify `quoteB64` with a verifier you trust — never the node being
-     * attested — and check that its report data is `nonce || reportDataSuffix`
-     * (both hex). `AdminApiClient.teeVerifyQuote` on a node of your own does both
-     * when given `expectedApplicationHash: reportDataSuffix`. Resolve true only
-     * when the quote is genuine, its measurements are ones you accept, and the
-     * report data matches.
+     * Verify `quoteB64` — never by asking the node being attested — and check
+     * that its report data is `nonce || reportDataSuffix` (both hex). Resolve
+     * true only when the quote is genuine, its measurements are ones you accept,
+     * and the report data matches. {@link createQuoteVerifier} does all of this
+     * in the page. `collateral` is what the node sent with the quote, when the
+     * verifier asked for it.
      */
     (args: {
         quoteB64: string;
         nonce: string;
         reportDataSuffix: string;
+        collateral?: DcapCollateral;
     }): Promise<boolean>;
+    /**
+     * Ask the node for the collateral its quote verifies against, and pass it
+     * in as `collateral`. Off unless set, because a node that predates the field
+     * refuses the request.
+     */
+    readonly includeCollateral?: boolean;
 }
 /**
  * Ask a node for its transport key and accept it only if a quote you verified
@@ -95,6 +103,38 @@ export declare function fetchAttestedTransportKey(admin: {
     applicationId?: string;
     applicationHash?: string;
 }): Promise<Uint8Array>;
+export interface AttestedSealedFetchOptions {
+    /** The node's base URL. */
+    baseUrl: string;
+    /**
+     * Decides whether the node's quote is one you trust — typically
+     * {@link createQuoteVerifier}. Asked again whenever the node restarts.
+     */
+    verify: VerifyTransportQuote;
+    /** Also require the node to run this application with this bytecode hash. */
+    applicationId?: string;
+    applicationHash?: string;
+    /** Fetch that carries the attestation and the envelopes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * {@link createSealedFetch} for a node you know only by URL: it attests the
+ * node's transport key with `verify`, over `POST /admin-api/tee/attest` (the
+ * one call that needs no credential and is never sealed), and seals everything
+ * else to it. A restarted node is attested again, through the same verifier.
+ *
+ * This is what to hand a {@link RelayClient} for a TEE relay, so the warrant
+ * and the method's arguments reach only the attested TD:
+ *
+ * ```ts
+ * const relay = new RelayClient({
+ *   relayUrl,
+ *   fetch: createAttestedSealedFetch({ baseUrl: relayUrl, verify: createQuoteVerifier(...) }),
+ *   ...
+ * });
+ * ```
+ */
+export declare function createAttestedSealedFetch(options: AttestedSealedFetchOptions): typeof fetch;
 export interface SealedFetchOptions {
     /** The node's base URL, as given to `MeroJsConfig.baseUrl`. */
     baseUrl: string;

package/dist/sealed/sealed.js

@@ -109,6 +109,7 @@ export async function fetchAttestedTransportKey(admin, verify, options = {}) {
         nonce,
         applicationId: options.applicationId,
         bindTransportKey: true,
+        ...(verify.includeCollateral ? { includeCollateral: true } : {}),
     });
     if (!attested.transportPublicKey) {
         throw new Error('The node did not report a transport key; it predates sealed transport');
@@ -118,11 +119,62 @@ export async function fetchAttestedTransportKey(admin, verify, options = {}) {
         ? fromHex(options.applicationHash, 'applicationHash', 32)
         : new Uint8Array(32);
     const reportDataSuffix = hex(await transportKeyBinding(inner, transportKey));
-    if (!(await verify({ quoteB64: attested.quoteB64, nonce, reportDataSuffix }))) {
+    const verified = await verify({
+        quoteB64: attested.quoteB64,
+        nonce,
+        reportDataSuffix,
+        collateral: attested.collateral,
+    });
+    if (!verified) {
         throw new Error('The attestation did not verify, so its transport key is not trusted');
     }
     return transportKey;
 }
+/**
+ * {@link createSealedFetch} for a node you know only by URL: it attests the
+ * node's transport key with `verify`, over `POST /admin-api/tee/attest` (the
+ * one call that needs no credential and is never sealed), and seals everything
+ * else to it. A restarted node is attested again, through the same verifier.
+ *
+ * This is what to hand a {@link RelayClient} for a TEE relay, so the warrant
+ * and the method's arguments reach only the attested TD:
+ *
+ * ```ts
+ * const relay = new RelayClient({
+ *   relayUrl,
+ *   fetch: createAttestedSealedFetch({ baseUrl: relayUrl, verify: createQuoteVerifier(...) }),
+ *   ...
+ * });
+ * ```
+ */
+export function createAttestedSealedFetch(options) {
+    const baseFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const attestUrl = `${options.baseUrl.replace(/\/+$/, '')}/admin-api/tee/attest`;
+    const admin = {
+        async teeAttest(request) {
+            const response = await baseFetch(attestUrl, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                throw new Error(`The node refused to attest: HTTP ${response.status}`);
+            }
+            const body = (await response.json());
+            if (!body.data)
+                throw new Error('The attestation response is malformed');
+            return body.data;
+        },
+    };
+    return createSealedFetch({
+        baseUrl: options.baseUrl,
+        transportPublicKey: () => fetchAttestedTransportKey(admin, options.verify, {
+            applicationId: options.applicationId,
+            applicationHash: options.applicationHash,
+        }),
+        fetch: baseFetch,
+    });
+}
 /**
  * A `fetch` that seals every request to the node's attested transport key.
  * Pass it as `MeroJsConfig.fetch`.
@@ -139,6 +191,10 @@ export function createSealedFetch(options) {
     let transportKey = attest
         ? Promise.resolve().then(attest)
         : Promise.resolve(options.transportPublicKey);
+    // Attesting starts now, before any request awaits it. A node that fails to
+    // attest must surface on the request that needed the key, not earlier as an
+    // unhandled rejection; the failure is still thrown to every awaiter.
+    transportKey.catch(() => undefined);
     let session;
     const openSession = async () => {
         try {

package/dist/sealed/verify.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Verifying a TEE node's quote in the page, before trusting the key it binds.
+ *
+ * A quote proves what runs in a TD only once it has been checked: its
+ * signatures against Intel's root, the TCB status of the platform, the
+ * measurements of the image, and that its report data is the nonce and the
+ * binding this client asked for. {@link createQuoteVerifier} does all of that
+ * here, with nothing but the node: the node hands over the Intel-signed
+ * collateral with its quote (`includeCollateral`), and a node cannot forge
+ * collateral, only choose which valid collateral to serve.
+ *
+ * The DCAP verification itself — parsing the quote, checking its signature
+ * chain and appraising its TCB level against the collateral — comes from a
+ * library you pass in, normally `verify` from `@phala/dcap-qvl`, a pure
+ * JavaScript implementation that runs in browsers, Node and React Native. It
+ * is passed in rather than bundled so this SDK keeps no runtime dependencies,
+ * and applications that never talk to a TEE node pay nothing for it.
+ */
+import type { VerifyTransportQuote } from './sealed.js';
+/**
+ * The collateral a quote is verified against — TCB info, QE identity, CRLs and
+ * their chains — in dcap-qvl's form: byte fields are hex strings or byte
+ * arrays. What `/admin-api/tee/attest` returns with `includeCollateral`, and
+ * what `@phala/dcap-qvl`'s `getCollateral` fetches.
+ */
+export interface DcapCollateral {
+    pck_crl_issuer_chain: string;
+    root_ca_crl: number[] | string;
+    pck_crl: number[] | string;
+    tcb_info_issuer_chain: string;
+    tcb_info: string;
+    tcb_info_signature: number[] | string;
+    qe_identity_issuer_chain: string;
+    qe_identity: string;
+    qe_identity_signature: number[] | string;
+}
+/** What a DCAP verifier returns for a quote whose signature chain verified. */
+export interface DcapVerifiedReport {
+    status: string;
+    advisory_ids?: string[];
+    report: {
+        type: string;
+        data: unknown;
+    };
+}
+/**
+ * Verify a quote's signature chain against `collateral` as of `nowSecs`, and
+ * appraise its TCB level. Throws when it does not verify. `verify` from
+ * `@phala/dcap-qvl` has exactly this shape.
+ */
+export type DcapVerify = (quote: Uint8Array, collateral: DcapCollateral, nowSecs: number) => DcapVerifiedReport;
+export interface QuoteVerifierOptions {
+    /** DCAP verification: `verify` from `@phala/dcap-qvl`. */
+    dcapVerify: DcapVerify;
+    /**
+     * MRTDs (hex) of the images trusted. Required: the MRTD names the image a TD
+     * booted, and a quote that proves only "some genuine TD" proves nothing
+     * about which code reads the traffic.
+     */
+    allowedMrtd: string[];
+    /** RTMR allowlists (hex); a register is not checked when its list is left out. */
+    allowedRtmr0?: string[];
+    allowedRtmr1?: string[];
+    allowedRtmr2?: string[];
+    allowedRtmr3?: string[];
+    /**
+     * TCB statuses accepted. Defaults to `['UpToDate']`. `Revoked` is refused
+     * even when listed.
+     */
+    allowedTcbStatuses?: string[];
+    /**
+     * Where to get collateral when the node sends none (it predates
+     * `includeCollateral`): for example
+     * `(quote) => getCollateral(PHALA_PCCS_URL, quote)` from `@phala/dcap-qvl`.
+     * Without it, such a node's quote is refused.
+     */
+    fetchCollateral?: (quote: Uint8Array) => Promise<DcapCollateral>;
+    /** The current time in milliseconds; defaults to `Date.now`. For tests. */
+    now?: () => number;
+}
+/** A verifier for {@link fetchAttestedTransportKey}, which asks the node for collateral. */
+export type QuoteVerifier = VerifyTransportQuote & {
+    readonly includeCollateral: true;
+};
+/**
+ * A verifier that checks a TEE node's quote here, in the page, and accepts it
+ * only when every check passes:
+ *
+ * - its signatures verify against Intel's root, with collateral that is valid
+ *   now;
+ * - the platform's TCB status is one allowed (`UpToDate` by default), and
+ *   never `Revoked`;
+ * - the MRTD, and any RTMRs given, are ones allowed;
+ * - its report data is the nonce followed by the binding the client computed.
+ *
+ * Any failure rejects with the reason; nothing is trusted from a quote that
+ * does not pass. Mock quotes never pass: they carry no signature.
+ *
+ * ```ts
+ * import { verify as dcapVerify } from '@phala/dcap-qvl';
+ *
+ * const verifier = createQuoteVerifier({ dcapVerify, allowedMrtd: [trustedMrtd] });
+ * const fetch = createSealedFetch({
+ *   baseUrl,
+ *   transportPublicKey: () => fetchAttestedTransportKey(admin, verifier),
+ * });
+ * ```
+ */
+export declare function createQuoteVerifier(options: QuoteVerifierOptions): QuoteVerifier;

package/dist/sealed/verify.js

@@ -0,0 +1,116 @@
+/**
+ * Verifying a TEE node's quote in the page, before trusting the key it binds.
+ *
+ * A quote proves what runs in a TD only once it has been checked: its
+ * signatures against Intel's root, the TCB status of the platform, the
+ * measurements of the image, and that its report data is the nonce and the
+ * binding this client asked for. {@link createQuoteVerifier} does all of that
+ * here, with nothing but the node: the node hands over the Intel-signed
+ * collateral with its quote (`includeCollateral`), and a node cannot forge
+ * collateral, only choose which valid collateral to serve.
+ *
+ * The DCAP verification itself — parsing the quote, checking its signature
+ * chain and appraising its TCB level against the collateral — comes from a
+ * library you pass in, normally `verify` from `@phala/dcap-qvl`, a pure
+ * JavaScript implementation that runs in browsers, Node and React Native. It
+ * is passed in rather than bundled so this SDK keeps no runtime dependencies,
+ * and applications that never talk to a TEE node pay nothing for it.
+ */
+import { hex } from '../crypto/internal.js';
+const MEASUREMENT_HEX = /^[0-9a-f]{96}$/;
+/**
+ * A verifier that checks a TEE node's quote here, in the page, and accepts it
+ * only when every check passes:
+ *
+ * - its signatures verify against Intel's root, with collateral that is valid
+ *   now;
+ * - the platform's TCB status is one allowed (`UpToDate` by default), and
+ *   never `Revoked`;
+ * - the MRTD, and any RTMRs given, are ones allowed;
+ * - its report data is the nonce followed by the binding the client computed.
+ *
+ * Any failure rejects with the reason; nothing is trusted from a quote that
+ * does not pass. Mock quotes never pass: they carry no signature.
+ *
+ * ```ts
+ * import { verify as dcapVerify } from '@phala/dcap-qvl';
+ *
+ * const verifier = createQuoteVerifier({ dcapVerify, allowedMrtd: [trustedMrtd] });
+ * const fetch = createSealedFetch({
+ *   baseUrl,
+ *   transportPublicKey: () => fetchAttestedTransportKey(admin, verifier),
+ * });
+ * ```
+ */
+export function createQuoteVerifier(options) {
+    const allowedMrtd = measurements(options.allowedMrtd, 'allowedMrtd');
+    if (allowedMrtd.length === 0) {
+        throw new Error('allowedMrtd is empty, so no quote would ever be accepted');
+    }
+    const allowedRtmr = [
+        measurements(options.allowedRtmr0 ?? [], 'allowedRtmr0'),
+        measurements(options.allowedRtmr1 ?? [], 'allowedRtmr1'),
+        measurements(options.allowedRtmr2 ?? [], 'allowedRtmr2'),
+        measurements(options.allowedRtmr3 ?? [], 'allowedRtmr3'),
+    ];
+    const allowedStatuses = options.allowedTcbStatuses ?? ['UpToDate'];
+    const now = options.now ?? Date.now;
+    const verifier = async ({ quoteB64, nonce, reportDataSuffix, collateral, }) => {
+        const quote = fromBase64(quoteB64);
+        const against = collateral ?? (await options.fetchCollateral?.(quote));
+        if (!against) {
+            throw new Error('The node sent no collateral for its quote, and no fetchCollateral was given to get it');
+        }
+        let verified;
+        try {
+            verified = options.dcapVerify(quote, against, Math.floor(now() / 1000));
+        }
+        catch (error) {
+            throw new Error(`The quote did not verify: ${error?.message ?? String(error)}`);
+        }
+        if (verified.status === 'Revoked' || !allowedStatuses.includes(verified.status)) {
+            throw new Error(`The platform's TCB status is ${verified.status}, which is not accepted`);
+        }
+        const td = tdReport(verified.report);
+        if (!allowedMrtd.includes(hex(td.mrTd))) {
+            throw new Error(`MRTD ${hex(td.mrTd)} is not an image this verifier trusts`);
+        }
+        const registers = [td.rtMr0, td.rtMr1, td.rtMr2, td.rtMr3];
+        registers.forEach((register, index) => {
+            const allowed = allowedRtmr[index];
+            if (allowed.length > 0 && !allowed.includes(hex(register))) {
+                throw new Error(`RTMR${index} ${hex(register)} is not one this verifier trusts`);
+            }
+        });
+        if (hex(td.reportData) !== `${nonce}${reportDataSuffix}`.toLowerCase()) {
+            throw new Error('The quote does not commit to this nonce and binding');
+        }
+        return true;
+    };
+    return Object.assign(verifier, { includeCollateral: true });
+}
+function measurements(values, label) {
+    return values.map((value) => {
+        const normalized = value.trim().toLowerCase();
+        if (!MEASUREMENT_HEX.test(normalized)) {
+            throw new Error(`${label} holds ${JSON.stringify(value)}, which is not a 48-byte hex measurement`);
+        }
+        return normalized;
+    });
+}
+/** The TD report of a TDX quote (1.0 or 1.5); anything else is refused. */
+function tdReport(report) {
+    const data = report.data;
+    if (report.type === 'td10' && data)
+        return data;
+    if (report.type === 'td15' && data?.base)
+        return data.base;
+    throw new Error(`The quote is a ${report.type} quote, not a TDX one`);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "19.25.0",
+  "version": "19.27.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {
@@ -17,6 +17,7 @@
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "devDependencies": {
+    "@phala/dcap-qvl": "0.5.3",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.0",
     "@semantic-release/exec": "^7.0.0",