@calimero-network/mero-js 19.21.0 → 19.23.0

package/dist/sealed/index.d.ts

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

package/dist/sealed/index.js

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

package/dist/sealed/noise.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The Noise NK handshake (`Noise_NK_25519_AESGCM_SHA256`) that opens a sealed
+ * session, written against WebCrypto from the Noise specification
+ * (revision 34, http://www.noiseprotocol.org/noise.html). The node runs the
+ * other side with `snow`; core's published vectors check the two against each
+ * other.
+ *
+ * NK: the initiator knows the responder's static key in advance — here the
+ * transport key the node's quote commits to — and sends nothing but an
+ * ephemeral key before both ephemerals are mixed in, so everything after the
+ * handshake has forward secrecy.
+ */
+/** Noise's `SymmetricState`: the chaining key, the handshake hash and the cipher key. */
+export declare class SymmetricState {
+    private ck;
+    private h;
+    private k;
+    private n;
+    private constructor();
+    static initialize(): Promise<SymmetricState>;
+    mixHash(data: Uint8Array): Promise<void>;
+    mixKey(inputKeyMaterial: Uint8Array): Promise<void>;
+    encryptAndHash(plaintext: Uint8Array): Promise<Uint8Array>;
+    decryptAndHash(ciphertext: Uint8Array): Promise<Uint8Array>;
+    /** The initiator-to-responder key, then the responder-to-initiator key. */
+    split(): Promise<[Uint8Array, Uint8Array]>;
+}
+export interface X25519KeyPair {
+    privateKey: CryptoKey;
+    publicKey: Uint8Array;
+}
+/**
+ * Start an NK handshake to `remoteStatic`. `fixedEphemeral` pins the
+ * ephemeral secret, for the published test vectors only; leave it out.
+ */
+export declare function initiate(remoteStatic: Uint8Array, prologue: Uint8Array, fixedEphemeral?: Uint8Array): Promise<{
+    message1: Uint8Array;
+    finish(message2: Uint8Array): Promise<{
+        payload: Uint8Array;
+        split: [Uint8Array, Uint8Array];
+    }>;
+}>;
+export declare function x25519KeyPair(secret?: Uint8Array): Promise<X25519KeyPair>;
+export declare function dh(privateKey: CryptoKey, publicKey: Uint8Array): Promise<Uint8Array>;

package/dist/sealed/noise.js

@@ -0,0 +1,137 @@
+/**
+ * The Noise NK handshake (`Noise_NK_25519_AESGCM_SHA256`) that opens a sealed
+ * session, written against WebCrypto from the Noise specification
+ * (revision 34, http://www.noiseprotocol.org/noise.html). The node runs the
+ * other side with `snow`; core's published vectors check the two against each
+ * other.
+ *
+ * NK: the initiator knows the responder's static key in advance — here the
+ * transport key the node's quote commits to — and sends nothing but an
+ * ephemeral key before both ephemerals are mixed in, so everything after the
+ * handshake has forward secrecy.
+ */
+import { concat } from '../crypto/internal.js';
+const PROTOCOL_NAME = 'Noise_NK_25519_AESGCM_SHA256';
+const DH_LEN = 32;
+const TAG_LEN = 16;
+/** PKCS#8 wrapping of a raw X25519 private key (RFC 8410). */
+const PKCS8_X25519_PREFIX = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04,
+    0x22, 0x04, 0x20,
+]);
+/** Noise's `SymmetricState`: the chaining key, the handshake hash and the cipher key. */
+export class SymmetricState {
+    constructor(h) {
+        this.k = null;
+        this.n = 0;
+        this.ck = h;
+        this.h = h;
+    }
+    static async initialize() {
+        // A name of 32 bytes or fewer is used as the hash, zero-padded.
+        const name = new TextEncoder().encode(PROTOCOL_NAME);
+        const h = new Uint8Array(32);
+        h.set(name);
+        return new SymmetricState(h);
+    }
+    async mixHash(data) {
+        this.h = await sha256(concat(this.h, data));
+    }
+    async mixKey(inputKeyMaterial) {
+        const [ck, key] = await hkdf2(this.ck, inputKeyMaterial);
+        this.ck = ck;
+        this.k = await crypto.subtle.importKey('raw', key, 'AES-GCM', false, ['encrypt', 'decrypt']);
+        this.n = 0;
+    }
+    async encryptAndHash(plaintext) {
+        if (!this.k)
+            throw new Error('Noise: no cipher key yet');
+        const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv: noiseNonce(this.n), additionalData: this.h }, this.k, plaintext));
+        this.n += 1;
+        await this.mixHash(ciphertext);
+        return ciphertext;
+    }
+    async decryptAndHash(ciphertext) {
+        if (!this.k)
+            throw new Error('Noise: no cipher key yet');
+        const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: noiseNonce(this.n), additionalData: this.h }, this.k, ciphertext));
+        this.n += 1;
+        await this.mixHash(ciphertext);
+        return plaintext;
+    }
+    /** The initiator-to-responder key, then the responder-to-initiator key. */
+    split() {
+        return hkdf2(this.ck, new Uint8Array());
+    }
+}
+/**
+ * Start an NK handshake to `remoteStatic`. `fixedEphemeral` pins the
+ * ephemeral secret, for the published test vectors only; leave it out.
+ */
+export async function initiate(remoteStatic, prologue, fixedEphemeral) {
+    const state = await SymmetricState.initialize();
+    await state.mixHash(prologue);
+    // <- s (known in advance)
+    await state.mixHash(remoteStatic);
+    // -> e, es
+    const ephemeral = await x25519KeyPair(fixedEphemeral);
+    await state.mixHash(ephemeral.publicKey);
+    await state.mixKey(await dh(ephemeral.privateKey, remoteStatic));
+    const message1 = concat(ephemeral.publicKey, await state.encryptAndHash(new Uint8Array()));
+    return {
+        message1,
+        async finish(message2) {
+            if (message2.length < DH_LEN + TAG_LEN)
+                throw new Error('Noise: message 2 is too short');
+            // <- e, ee
+            const remoteEphemeral = message2.slice(0, DH_LEN);
+            await state.mixHash(remoteEphemeral);
+            await state.mixKey(await dh(ephemeral.privateKey, remoteEphemeral));
+            const payload = await state.decryptAndHash(message2.slice(DH_LEN));
+            return { payload, split: await state.split() };
+        },
+    };
+}
+export async function x25519KeyPair(secret) {
+    if (!secret) {
+        const pair = (await crypto.subtle.generateKey({ name: 'X25519' }, true, [
+            'deriveBits',
+        ]));
+        const publicKey = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
+        return { privateKey: pair.privateKey, publicKey };
+    }
+    const privateKey = await crypto.subtle.importKey('pkcs8', concat(PKCS8_X25519_PREFIX, secret), { name: 'X25519' }, true, ['deriveBits']);
+    const jwk = await crypto.subtle.exportKey('jwk', privateKey);
+    return { privateKey, publicKey: base64UrlDecode(jwk.x) };
+}
+export async function dh(privateKey, publicKey) {
+    const peer = await crypto.subtle.importKey('raw', publicKey, { name: 'X25519' }, false, []);
+    return new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: peer }, privateKey, 256));
+}
+/** Noise's AESGCM nonce: 32 zero bits, then the counter as a big-endian u64. */
+function noiseNonce(n) {
+    const nonce = new Uint8Array(12);
+    new DataView(nonce.buffer).setBigUint64(4, BigInt(n), false);
+    return nonce;
+}
+async function sha256(data) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', data));
+}
+async function hmacSha256(key, data) {
+    const hmacKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+    ]);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', hmacKey, data));
+}
+/** Noise's `HKDF` with two outputs. */
+async function hkdf2(chainingKey, inputKeyMaterial) {
+    const temp = await hmacSha256(chainingKey, inputKeyMaterial);
+    const first = await hmacSha256(temp, new Uint8Array([1]));
+    const second = await hmacSha256(temp, concat(first, new Uint8Array([2])));
+    return [first, second];
+}
+function base64UrlDecode(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}

package/dist/sealed/sealed.d.ts

@@ -1,39 +1,49 @@
 /**
- * Sealed transport: requests encrypted to a TEE node's attested key.
+ * Sealed transport: requests encrypted end to end to a TEE node's attested key.
  *
  * A node speaks plain HTTP and any TLS in front of it ends outside the enclave,
  * at whatever proxy or relay the operator runs, so everything crossing that hop
  * (the bearer token, JSON-RPC arguments, results) is readable there. Sealing
- * encrypts each request to an X25519 key the node's quote commits to, so only
- * the attested TD can read it, and only the TD can produce a response the
- * client accepts.
+ * encrypts it so that only the attested TD can read it, and only the TD can
+ * produce a response the client accepts.
+ *
+ * The client opens a session with a Noise NK handshake to the X25519 transport
+ * key the node's quote commits to ({@link fetchAttestedTransportKey}). The
+ * transport key only authenticates the node: the session keys come from both
+ * sides' ephemeral keys, so once a session is gone (an hour at most) what was
+ * sent in it cannot be opened, not even with the transport key. Each request
+ * is sealed under the session; each response streams back in sealed frames, so
+ * server-sent events are sealed too. WebSockets cannot be, and the node
+ * refuses one inside the envelope with a 501.
  *
  * The node's side, and the wire format this implements byte for byte, are in
  * core's `crates/server/src/sealed.rs`:
  *
  * ```text
- * shared    = X25519(secret, peer public)            all-zero result refused
- * prk       = HKDF-SHA256-Extract(salt = transport_pk || client_pk, ikm = shared)
- * req key   = HKDF-Expand(prk, "calimero/sealed-http/v1/request",  32)
- * resp key  = HKDF-Expand(prk, "calimero/sealed-http/v1/response", 32)
- * request   = 0x01 || transport_pk || client_pk || nonce(12)
- *             || AES-256-GCM(req key, nonce, aad = the 77 bytes before it, inner request)
- * response  = 0x01 || nonce(12)
- *             || AES-256-GCM(resp key, nonce, aad = 0x01 || transport_pk || client_pk, inner response)
- * inner     = u32 BE head length || head (JSON) || body
+ * handshake   Noise_NK_25519_AESGCM_SHA256, prologue "calimero/sealed-http/v2"
+ *   request   POST /sealed/v2/handshake   0x02 || transport_pk || Noise message 1
+ *   response  0x02 || Noise message 2 (payload = session_id(16) || lifetime secs, u32 BE)
+ *   keys      (req key, resp key) = Split()
+ * exchange    POST /sealed/v2
+ *   header    0x02 || session_id(16) || request_id (u64 BE; from 1, each used once)
+ *   request   header || AES-256-GCM(req key, nonce = request_id || 0u32, aad = header, inner)
+ *   response  frames, each u32 BE length || AES-256-GCM(resp key,
+ *             nonce = request_id || frame index (u32 BE, from 0), aad = header, kind || data)
+ *             kind 0 = head (JSON), 1 = body bytes, 2 = end; no end frame = cut short
+ *   inner     u32 BE head length || head (JSON) || body
  * ```
  *
- * Use it by attesting once ({@link fetchAttestedTransportKey}) and handing
- * {@link createSealedFetch} to `MeroJsConfig.fetch`. Server-sent events and
- * WebSockets are streams and cannot be sealed; the node refuses a sealed SSE
- * request with a 501 rather than hang.
+ * Use it by handing {@link createSealedFetch} to `MeroJsConfig.fetch`.
  */
 import type { TeeAttestRequest, TeeAttestResponseData } from '../admin-api/admin-types.js';
+import { initiate } from './noise.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. */
-export declare const SEALED_PATH = "/sealed/v1";
-/** Content type of both sealed bodies. */
+export declare const SEALED_PATH = "/sealed/v2";
+/** Content type of every sealed body. */
 export declare const SEALED_CONTENT_TYPE = "application/vnd.calimero.sealed";
-/** The node no longer holds the key this client sealed to (it restarted). */
+/** The node no longer holds the transport key this client attested (it restarted). */
 export declare class StaleTransportKeyError extends Error {
     name: string;
     constructor();
@@ -84,43 +94,53 @@ export declare function fetchAttestedTransportKey(admin: {
 export interface SealedFetchOptions {
     /** The node's base URL, as given to `MeroJsConfig.baseUrl`. */
     baseUrl: string;
-    /** The node's transport key, from {@link fetchAttestedTransportKey}. */
-    transportPublicKey: Uint8Array;
+    /**
+     * The node's attested transport key, or a function that attests and returns
+     * it — typically `() => fetchAttestedTransportKey(admin, verify)`. Given a
+     * function, a restarted node is handled: the key is attested again, through
+     * your verifier, and the request retried once. Given bytes, a restart
+     * surfaces as {@link StaleTransportKeyError}.
+     */
+    transportPublicKey: Uint8Array | (() => Promise<Uint8Array>);
     /** Fetch that carries the sealed envelope. Defaults to global `fetch`. */
     fetch?: typeof fetch;
 }
 /**
- * A `fetch` that seals every request to the node's transport key. Pass it as
- * `MeroJsConfig.fetch`.
+ * A `fetch` that seals every request to the node's attested transport key.
+ * Pass it as `MeroJsConfig.fetch`.
  *
  * A request for any URL outside `baseUrl` is refused rather than sent in the
  * clear: falling back to plaintext would silently undo the point of sealing.
  */
 export declare function createSealedFetch(options: SealedFetchOptions): typeof fetch;
+export interface Session {
+    requestKey: CryptoKey;
+    responseKey: CryptoKey;
+    nextRequestId: number;
+    renewAt: number;
+    header(requestId: number): Uint8Array;
+}
+/** Finish the handshake with the node's reply. Exported for the published vectors. */
+export declare function sessionFrom(noise: Awaited<ReturnType<typeof initiate>>, reply: Uint8Array): Promise<Session>;
+/** Seal one request under the session's next request id. */
+export declare function sealRequest(session: Session, head: RequestHead, body: Uint8Array): Promise<{
+    requestId: number;
+    header: Uint8Array;
+    envelope: Uint8Array;
+}>;
 export interface RequestHead {
     method: string;
     path: string;
     headers: Array<[string, string]>;
-    ts: number;
 }
 export interface ResponseHead {
     status: number;
     headers: Array<[string, string]>;
 }
-export interface SealedExchange {
-    envelope: Uint8Array;
-    open(sealed: Uint8Array): Promise<{
-        head: ResponseHead;
-        body: Uint8Array;
-    }>;
-}
 /**
- * Seal one request, keeping what is needed to open its response.
- *
- * `fixed` pins the client's one-time secret and the nonce, for the published
- * test vectors only; leave it out.
+ * Open a sealed response as it streams: wait for its head, then hand back a
+ * `Response` whose body opens each frame as it arrives. A frame that does not
+ * open, arrives out of order, or a stream that stops before its end frame
+ * errors the body rather than passing anything unauthenticated on.
  */
-export declare function sealRequest(transportKey: Uint8Array, head: RequestHead, body: Uint8Array, fixed?: {
-    clientSecret: Uint8Array;
-    nonce: Uint8Array;
-}): Promise<SealedExchange>;
+export declare function openResponse(response: Response, responseKey: CryptoKey, header: Uint8Array, requestId: number): Promise<Response>;