@calimero-network/mero-js 22.7.0 → 22.9.0

package/dist/relay/nonce-source.js

@@ -41,6 +41,11 @@ export function createMemoryNonceSource(start = 1) {
             next += 1n;
             return Promise.resolve(value);
         },
+        advanceTo(floor) {
+            if (floor > next)
+                next = floor;
+            return Promise.resolve();
+        },
     };
 }
 /**
@@ -67,29 +72,192 @@ export function createLocalStorageNonceSource(key, storage) {
     if (!store) {
         throw new Error('no localStorage in this runtime: pass a storage implementation, or use createMemoryNonceSource for a process that owns its whole sequence');
     }
+    // A missing, empty, or corrupted value means "no sequence recorded", and the
+    // safe reading of that is not 1 — a cleared storage on a device that has
+    // already written would replay. But the client cannot know, and 1 is the only
+    // defensible start, so it is what a fresh key gets. This is why the doc above
+    // tells apps to key per device: a device whose storage was cleared should be
+    // re-paired rather than resumed — or handed a recovering source, which asks
+    // the node what it already spent instead of guessing.
+    const lastHandedOut = () => {
+        const raw = store.getItem(key);
+        if (raw === null || raw === '')
+            return 0n;
+        try {
+            const parsed = BigInt(raw);
+            return parsed > 0n ? parsed : 0n;
+        }
+        catch {
+            return 0n;
+        }
+    };
     return {
         next() {
-            const raw = store.getItem(key);
-            // A missing, empty, or corrupted value means "no sequence recorded", and
-            // the safe reading of that is not 1 — a cleared storage on a device that
-            // has already written would replay. But the client cannot know, and 1 is
-            // the only defensible start, so it is what a fresh key gets. This is why
-            // the doc above tells apps to key per device: a device whose storage was
-            // cleared should be re-paired rather than resumed.
-            let current = 0n;
-            if (raw !== null && raw !== '') {
-                try {
-                    const parsed = BigInt(raw);
-                    if (parsed > 0n)
-                        current = parsed;
-                }
-                catch {
-                    current = 0n;
-                }
-            }
-            const value = current + 1n;
+            const value = lastHandedOut() + 1n;
             store.setItem(key, value.toString());
             return Promise.resolve(value);
         },
+        advanceTo(floor) {
+            // Stored is the last number handed out, so the floor is recorded as the
+            // one below it — persisted rather than held in memory, which is the whole
+            // point: the next cold start resumes above the jump even if the node
+            // cannot be reached then.
+            const wanted = floor > 0n ? floor - 1n : 0n;
+            if (wanted > lastHandedOut())
+                store.setItem(key, wanted.toString());
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * A lookup a delegated client can actually use.
+ *
+ * {@link WarrantNonceLookup} names the device key because the admin route takes
+ * it in the path. The delegated route does not: it reads the key from the
+ * certificate it verifies, so the only way to ask is to present that
+ * certificate. This adapter bridges the two — it satisfies the interface, and
+ * ignores the device key argument because the credential already determines it.
+ *
+ * That the argument is ignored is not an oversight to tidy away. The whole
+ * point of the delegated route is that the device key is not caller-supplied:
+ * a key passed alongside the proof would be a second spelling of a fact the
+ * signature already fixes, and two spellings can differ. The adapter therefore
+ * has nothing to check it against, and pretending otherwise would invent a
+ * comparison the protocol deliberately does not make.
+ *
+ * Use with {@link createRecoveringNonceSource} exactly as an `AdminApiClient`
+ * would be used — on a relay, this is the form that works.
+ */
+export function authorNonceLookup(options) {
+    return {
+        getWarrantNonce: (contextId, _authorDeviceKey) => options.client.getWarrantNonceAsAuthor(contextId, options.authorProof),
+    };
+}
+/** Thrown when every node asked says this device has spent `u64::MAX` here. */
+export class WarrantNonceExhaustedError extends Error {
+    constructor(contextId, authorDeviceKey) {
+        super(`author device ${authorDeviceKey} has spent every nonce in context ${contextId}; it must re-key to write again`);
+        this.contextId = contextId;
+        this.authorDeviceKey = authorDeviceKey;
+        this.name = 'WarrantNonceExhaustedError';
+    }
+}
+/**
+ * A nonce source that asks the node where the sequence stands before its first
+ * mint, then carries on locally.
+ *
+ * # Why this is not the default
+ *
+ * It costs a round trip and an admin credential, and an author that never lost
+ * its counter gains nothing from it. It earns its place in exactly one
+ * situation, which is common rather than exotic: a client whose local state is
+ * gone. A browser keyholder lives in storage that is partitioned per top-level
+ * site and cleared on a schedule it does not control, so for it, losing the
+ * counter is the normal lifecycle. Without this, such a client either restarts
+ * at 1 — replaying every nonce it already spent, each write refused, which
+ * reads to the user as the app silently not saving — or guesses upward, one
+ * burnt round trip per wrong guess.
+ *
+ * # What it does
+ *
+ * The lookup happens once, lazily, on the first {@link NonceSource.next}: a
+ * source that is constructed and never used costs nothing, and an app that
+ * builds its relay client at startup does not pay a network call for it. The
+ * answer becomes a **floor**, and every nonce handed out afterwards is
+ * `max(localCounter, floor)`. It never goes backwards from either input, which
+ * is the one property a nonce source owes its caller.
+ *
+ * If the local counter is the one that is ahead, it wins — the node may simply
+ * not have applied this client's recent warrants yet.
+ *
+ * The floor is also pushed into the local source through
+ * {@link NonceSource.advanceTo} when it has one, so a persistent counter
+ * remembers the jump.
+ *
+ * # Exhaustion
+ *
+ * A node reporting no `nextNonce` means `u64::MAX` is spent and this device can
+ * never write here again. `next()` rejects with
+ * {@link WarrantNonceExhaustedError} rather than guessing, because every guess
+ * from there is refused forever.
+ *
+ * # On an older node
+ *
+ * The route is new and absent from core `master` builds, which answer 404 —
+ * {@link AdminApiClient.getWarrantNonce} surfaces that as
+ * `WarrantNonceRouteUnavailableError`. It reaches the caller as a lookup
+ * failure, so `onLookupFailure` decides: refuse to mint, or fall back to the
+ * local counter.
+ */
+export function createRecoveringNonceSource(options) {
+    const lookups = Array.isArray(options.lookups)
+        ? options.lookups
+        : [options.lookups];
+    if (lookups.length === 0) {
+        throw new Error('a recovering nonce source needs at least one node to ask');
+    }
+    const local = options.local ?? createMemoryNonceSource(1);
+    const onLookupFailure = options.onLookupFailure ?? 'throw';
+    let floor = null;
+    // Memoised so concurrent first calls ask once. Cleared on failure, since a
+    // node that was unreachable a moment ago may answer the next call — caching
+    // the failure would make one flaky request poison the whole session.
+    let pending = null;
+    const resolveFloor = async () => {
+        const answers = await Promise.allSettled(lookups.map((lookup) => lookup.getWarrantNonce(options.contextId, options.authorDeviceKey)));
+        let highest = null;
+        let exhausted = false;
+        for (const answer of answers) {
+            if (answer.status !== 'fulfilled')
+                continue;
+            const state = answer.value;
+            if (state.kind === 'exhausted') {
+                exhausted = true;
+                continue;
+            }
+            if (highest === null || state.nextNonce > highest)
+                highest = state.nextNonce;
+        }
+        // Exhaustion is only decisive when nothing usable came back. One node
+        // saturated while another still has room is not a thing the ledger can
+        // produce — the sequence is the device's, not the node's — but if it ever
+        // is, the usable answer is the actionable one.
+        if (highest === null && exhausted) {
+            throw new WarrantNonceExhaustedError(options.contextId, options.authorDeviceKey);
+        }
+        if (highest === null) {
+            const first = answers.find((a) => a.status === 'rejected');
+            const reason = first && first.status === 'rejected' ? first.reason : undefined;
+            if (onLookupFailure === 'local') {
+                floor = 0n;
+                return;
+            }
+            throw reason instanceof Error
+                ? reason
+                : new Error(`no node could answer where the warrant-nonce sequence stands: ${String(reason)}`);
+        }
+        floor = highest;
+        await local.advanceTo?.(highest);
+    };
+    return {
+        async next() {
+            if (floor === null) {
+                pending ?? (pending = resolveFloor().finally(() => {
+                    pending = null;
+                }));
+                await pending;
+            }
+            const mine = await local.next();
+            const value = floor !== null && floor > mine ? floor : mine;
+            // Advance the floor past what was just handed out, so a local source that
+            // is behind cannot re-offer this number on the next call.
+            floor = value + 1n;
+            return value;
+        },
+        async advanceTo(wanted) {
+            if (floor === null || wanted > floor)
+                floor = wanted;
+            await local.advanceTo?.(wanted);
+        },
     };
 }

package/dist/relay/relay-client.d.ts

@@ -27,8 +27,8 @@
  * monotonic per-device sequence, and one minted against the wrong executor is
  * unspendable: the number is gone and the write never happened.
  */
-import { type GovernanceOp } from '../warrant/governance-op.js';
 import { type Signer } from '../signer/signer.js';
+import { type GovernanceOp } from '../warrant/governance-op.js';
 import type { NonceSource } from './nonce-source.js';
 /** Where and as whom to write, plus the key that consents. */
 export interface RelayClientConfig {
@@ -73,7 +73,13 @@ export interface RelayClientConfig {
      * (a non-extractable WebCrypto key, a passkey, a hardware or remote signer).
      */
     signer?: Signer;
-    /** Where nonces come from. See {@link NonceSource} — a reset replays. */
+    /**
+     * Where nonces come from. See {@link NonceSource} — a reset replays.
+     *
+     * A client whose storage may be cleared between sessions should wrap its
+     * counter in `createRecoveringNonceSource`, which asks the node where the
+     * sequence actually stands before the first mint instead of restarting at 1.
+     */
     nonces: NonceSource;
     /**
      * Seconds a minted warrant stays valid. Defaults to 300.
@@ -86,6 +92,14 @@ export interface RelayClientConfig {
     /** Injected for tests and non-browser runtimes. Defaults to global `fetch`. */
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /**
+     * How many times a `429` is waited out before it reaches the caller.
+     * Defaults to 3; `0` surfaces rate limits immediately.
+     *
+     * Safe to retry because the relay's ingress limiter runs before the node sees
+     * the request, so a throttled warrant's nonce is not spent.
+     */
+    rateLimitRetries?: number;
 }
 /** What a relay says about its ability to run intents in one context. */
 export interface RelayDescription {
@@ -263,11 +277,35 @@ export declare class RelayClient {
     private readonly config;
     private readonly fetchImpl;
     private readonly timeoutMs;
+    /** How many times a 429 is waited out before it is raised. */
+    private readonly rateLimitRetries;
     constructor(config: RelayClientConfig);
     /**
-     * The author device's signer, built from `deviceSecret` when that is what was
-     * configured. A {@link Signer} and never the secret, so no caller of a
-     * `RelayClient` gains the ability to read key material.
+     * The relay's origin, trailing slash stripped.
+     *
+     * Exposed because a relay **is a node**: the same origin that answers the
+     * intents routes also answers `/auth/challenge`, `/auth/token`, `/sse` and
+     * `/ws`. Anything building an observing session over this relay needs the
+     * URL, and asking the caller to pass it a second time is how the two drift.
+     */
+    get relayUrl(): string;
+    /** The author's account, hex — whose consent every warrant here carries. */
+    get authorAccount(): string;
+    /**
+     * The author's `AccountProof<DeviceCert>`, hex.
+     *
+     * The same credential `login()` wants, which is why it is readable: a caller
+     * that already handed it to this client should not have to hand an identical
+     * copy to the login as well, where the two could disagree.
+     */
+    get authorProof(): string;
+    /**
+     * The author device's signer.
+     *
+     * A {@link Signer} and never the secret: this returns something that can
+     * *sign*, so no caller of a `RelayClient` gains the ability to read a key
+     * that was passed in as `deviceSecret`. That asymmetry is the point — the
+     * login needs a signature, not key material.
      */
     authorSigner(): Promise<Signer>;
     /**
@@ -377,5 +415,22 @@ export declare class RelayClient {
      * configured account must agree with. Remembered for later calls.
      */
     private checkedExecutor;
+    /**
+     * One request, waiting out a rate limit rather than failing the caller.
+     *
+     * The relay's ingress limits the delegated-execution routes to 20 requests a
+     * second per source IP, burst 40 — tighter than everything else it serves,
+     * because those two routes are the ones it answers to anonymous callers.
+     *
+     * Retrying a 429 is safe here in a way retrying most refusals is not: the
+     * limiter sits *first* in the middleware chain, so a throttled request never
+     * reached the node and its warrant nonce was never spent. The same bytes can
+     * go again. Contrast the spent-nonce 403 below, which needs a fresh warrant.
+     *
+     * `Retry-After` is honoured when the ingress sends one; otherwise the wait
+     * doubles from a little over the limiter's own window, which is the shortest
+     * delay that can actually clear.
+     */
     private json;
+    private jsonOnce;
 }

package/dist/relay/relay-client.js

@@ -28,12 +28,12 @@
  * unspendable: the number is gone and the write never happened.
  */
 import { signWarrant } from '../warrant/warrant.js';
+import { resolveSigner } from '../signer/signer.js';
 import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
 import { defaultCapabilitiesSetOp, foundedNamespaceId, namespaceCreatedOp, } from '../warrant/governance-op.js';
 import { HTTPError } from '../http-client/web-client.js';
 import { fromHex, hex } from '../crypto/internal.js';
-import { resolveSigner } from '../signer/signer.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
 /**
@@ -62,6 +62,25 @@ export class IntentRefusedError extends Error {
         this.name = 'IntentRefusedError';
     }
 }
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * `Retry-After`, as milliseconds — seconds or an HTTP date, per RFC 9110.
+ *
+ * Returns `null` when the header is absent or unusable, so the caller falls back
+ * to its own backoff rather than treating a malformed header as "retry now".
+ */
+function retryAfterMs(headers) {
+    const raw = headers?.get?.('Retry-After');
+    if (!raw)
+        return null;
+    const seconds = Number.parseInt(raw, 10);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const at = Date.parse(raw);
+    if (Number.isFinite(at))
+        return Math.max(0, at - Date.now());
+    return null;
+}
 export class RelayClient {
     constructor(config) {
         this.config = config;
@@ -72,11 +91,40 @@ export class RelayClient {
             ? (input, init) => injected(input, init)
             : (input, init) => globalThis.fetch(input, init);
         this.timeoutMs = config.timeoutMs ?? 10000;
+        this.rateLimitRetries = config.rateLimitRetries ?? 3;
     }
     /**
-     * The author device's signer, built from `deviceSecret` when that is what was
-     * configured. A {@link Signer} and never the secret, so no caller of a
-     * `RelayClient` gains the ability to read key material.
+     * The relay's origin, trailing slash stripped.
+     *
+     * Exposed because a relay **is a node**: the same origin that answers the
+     * intents routes also answers `/auth/challenge`, `/auth/token`, `/sse` and
+     * `/ws`. Anything building an observing session over this relay needs the
+     * URL, and asking the caller to pass it a second time is how the two drift.
+     */
+    get relayUrl() {
+        return this.baseUrl;
+    }
+    /** The author's account, hex — whose consent every warrant here carries. */
+    get authorAccount() {
+        return this.config.authorAccount;
+    }
+    /**
+     * The author's `AccountProof<DeviceCert>`, hex.
+     *
+     * The same credential `login()` wants, which is why it is readable: a caller
+     * that already handed it to this client should not have to hand an identical
+     * copy to the login as well, where the two could disagree.
+     */
+    get authorProof() {
+        return this.config.authorProof;
+    }
+    /**
+     * The author device's signer.
+     *
+     * A {@link Signer} and never the secret: this returns something that can
+     * *sign*, so no caller of a `RelayClient` gains the ability to read a key
+     * that was passed in as `deviceSecret`. That asymmetry is the point — the
+     * login needs a signature, not key material.
      */
     async authorSigner() {
         return resolveSigner(this.config.deviceSecret, this.config.signer, 'deviceSecret');
@@ -353,7 +401,39 @@ export class RelayClient {
         this.executorAccount = answered;
         return answered;
     }
+    /**
+     * One request, waiting out a rate limit rather than failing the caller.
+     *
+     * The relay's ingress limits the delegated-execution routes to 20 requests a
+     * second per source IP, burst 40 — tighter than everything else it serves,
+     * because those two routes are the ones it answers to anonymous callers.
+     *
+     * Retrying a 429 is safe here in a way retrying most refusals is not: the
+     * limiter sits *first* in the middleware chain, so a throttled request never
+     * reached the node and its warrant nonce was never spent. The same bytes can
+     * go again. Contrast the spent-nonce 403 below, which needs a fresh warrant.
+     *
+     * `Retry-After` is honoured when the ingress sends one; otherwise the wait
+     * doubles from a little over the limiter's own window, which is the shortest
+     * delay that can actually clear.
+     */
     async json(method, path, body) {
+        let wait = 250;
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await this.jsonOnce(method, path, body);
+            }
+            catch (err) {
+                const limited = err instanceof HTTPError && err.status === 429;
+                if (!limited || attempt >= this.rateLimitRetries)
+                    throw err;
+                const after = retryAfterMs(err.headers);
+                await sleep(after ?? wait);
+                wait *= 2;
+            }
+        }
+    }
+    async jsonOnce(method, path, body) {
         const headers = { Accept: 'application/json' };
         if (body !== undefined)
             headers['Content-Type'] = 'application/json';

package/dist/relay-attestation/attest-node-key.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Learn a relay's node signing key from its TEE attestation.
+ *
+ * `login()` binds a session to the node key the client names, and that key must
+ * never be taken from the node being logged in to on its word — the answering
+ * party would choose what the device signs about. A TEE quote is different: the
+ * node cannot put a key into it that the TEE did not bind. With `bindNodeKey`,
+ * core commits the node's signing key into the quote's report data:
+ *
+ *   report_data = nonce (32)  ‖  SHA-256("calimero.tee-attest.key-binding.v1" ‖ 0^32 ‖ key)
+ *
+ * (the 32 zero bytes stand for "no application", core's `attest_key_binding`).
+ * So the client sends a fresh nonce, reads the report data out of the RAW quote
+ * bytes — never the server's parsed rendering of them — and accepts the returned
+ * key only if both halves match.
+ *
+ * That proves the key came from whatever produced the quote. Whether that is a
+ * genuine TDX guest running a trusted image is the quote's signature and
+ * measurements, which this module does not judge: a real quote needs a
+ * `verifyQuote` supplied by the caller, and a mock quote (a dev-only format with
+ * no signature at all) is refused unless `allowMock` is set.
+ */
+import type { VerifyTransportQuote } from '../sealed/sealed.js';
+export interface AttestedNodeKey {
+    /** The relay's node signing key, hex (32 bytes), as the quote binds it. */
+    readonly nodeKey: string;
+    /** True when the quote was a mock — no TEE vouched for anything. */
+    readonly mock: boolean;
+}
+export interface AttestRelayNodeKeyOptions {
+    readonly relayUrl: string;
+    /**
+     * Accept a mock quote. DEV/TEST ONLY: a mock quote carries no signature, so it
+     * proves nothing about the hardware — only that the node bound this key into
+     * something it produced for our nonce.
+     */
+    readonly allowMock?: boolean;
+    /**
+     * Verify a real quote's signature chain and measurements; throw to refuse.
+     * Required for a non-mock quote: without it the binding would be checked
+     * against bytes nothing has authenticated.
+     */
+    readonly verifyQuote?: (quote: Uint8Array) => Promise<void>;
+    /**
+     * Verify a real quote the way a sealed transport does: a
+     * {@link VerifyTransportQuote}, such as `createSignedReleaseVerifier` (the
+     * relay's signed mero-tee release, Intel's chain, every register of its
+     * image). Called with our nonce and the node-key binding as the expected
+     * report data, and with the relay's collateral when it asks for it. Takes
+     * precedence over `verifyQuote`.
+     */
+    readonly verify?: VerifyTransportQuote;
+    readonly fetch?: typeof fetch;
+}
+/** Core's `attest_key_binding(None, key)`. */
+export declare function attestKeyBinding(nodeKey: Uint8Array): Promise<Uint8Array>;
+/** The 64 report-data bytes of a quote, read from the quote itself. */
+export declare function reportDataOf(quote: Uint8Array): {
+    reportData: Uint8Array;
+    mock: boolean;
+};
+/**
+ * Ask a relay for a quote binding its node key to a fresh nonce, check the
+ * binding, and return the key.
+ */
+export declare function attestRelayNodeKey(opts: AttestRelayNodeKeyOptions): Promise<AttestedNodeKey>;

package/dist/relay-attestation/attest-node-key.js

@@ -0,0 +1,110 @@
+import { hex } from '../crypto/internal.js';
+/** Core's `ATTEST_KEY_BINDING_DOMAIN`. */
+const KEY_BINDING_DOMAIN = new TextEncoder().encode('calimero.tee-attest.key-binding.v1');
+/** Core's `MOCK_QUOTE_HEADER`: a mock quote is this, then the 64-byte report data. */
+const MOCK_QUOTE_HEADER = new TextEncoder().encode('MOCK_TDX_QUOTE_V1');
+/** A TDX v4 quote: 48-byte header, then the TD report body; report data at body offset 520. */
+const TDX_REPORT_DATA_OFFSET = 48 + 520;
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+function fromBase64(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i += 1)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function fromHex32(value, label) {
+    if (typeof value !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value)) {
+        throw new Error(`${label} must be 64 hex characters`);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i += 1)
+        out[i] = Number.parseInt(value.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/** Core's `attest_key_binding(None, key)`. */
+export async function attestKeyBinding(nodeKey) {
+    const digest = await crypto.subtle.digest('SHA-256', concat(KEY_BINDING_DOMAIN, new Uint8Array(32), nodeKey));
+    return new Uint8Array(digest);
+}
+/** The 64 report-data bytes of a quote, read from the quote itself. */
+export function reportDataOf(quote) {
+    const mock = quote.length >= MOCK_QUOTE_HEADER.length &&
+        equal(quote.subarray(0, MOCK_QUOTE_HEADER.length), MOCK_QUOTE_HEADER);
+    const at = mock ? MOCK_QUOTE_HEADER.length : TDX_REPORT_DATA_OFFSET;
+    if (quote.length < at + 64) {
+        throw new Error(`the quote is too short to carry report data (${quote.length} bytes)`);
+    }
+    return { reportData: quote.slice(at, at + 64), mock };
+}
+/**
+ * Ask a relay for a quote binding its node key to a fresh nonce, check the
+ * binding, and return the key.
+ */
+export async function attestRelayNodeKey(opts) {
+    const nonce = crypto.getRandomValues(new Uint8Array(32));
+    const url = `${opts.relayUrl.replace(/\/+$/, '')}/admin-api/tee/attest`;
+    const body = JSON.stringify({
+        nonce: hex(nonce),
+        bindNodeKey: true,
+        ...(opts.verify?.includeCollateral ? { includeCollateral: true } : {}),
+    });
+    const init = { method: 'POST', headers: { 'Content-Type': 'application/json' }, body };
+    const response = opts.fetch ? await opts.fetch(url, init) : await globalThis.fetch(url, init);
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`the relay would not attest (HTTP ${response.status})${text ? `: ${text}` : ''}`);
+    }
+    const parsed = (await response.json());
+    const data = parsed.data ?? parsed;
+    if (typeof data.quoteB64 !== 'string')
+        throw new Error('the relay returned no quote');
+    const nodeKey = fromHex32(data.boundPublicKey, 'boundPublicKey');
+    const quote = fromBase64(data.quoteB64);
+    const { reportData, mock } = reportDataOf(quote);
+    if (mock) {
+        if (!opts.allowMock) {
+            throw new Error('the relay answered with a MOCK quote, which proves nothing about the hardware');
+        }
+    }
+    else if (opts.verify) {
+        const accepted = await opts.verify({
+            quoteB64: data.quoteB64,
+            nonce: hex(nonce),
+            reportDataSuffix: hex(await attestKeyBinding(nodeKey)),
+            ...(data.collateral ? { collateral: data.collateral } : {}),
+        });
+        if (!accepted) {
+            throw new Error("the relay's quote did not verify: not a trusted image, or not bound to this request");
+        }
+    }
+    else if (opts.verifyQuote) {
+        await opts.verifyQuote(quote);
+    }
+    else {
+        throw new Error('a real TDX quote needs a verify (or verifyQuote) to check its signature and measurements');
+    }
+    if (!equal(reportData.subarray(0, 32), nonce)) {
+        throw new Error('the quote does not carry our nonce: it was not made for this request');
+    }
+    if (!equal(reportData.subarray(32, 64), await attestKeyBinding(nodeKey))) {
+        throw new Error('the quote does not bind the key the relay named: refusing it');
+    }
+    return { nodeKey: hex(nodeKey), mock };
+}

package/dist/relay-attestation/index.d.ts

@@ -0,0 +1 @@
+export { attestRelayNodeKey, attestKeyBinding, reportDataOf, type AttestedNodeKey, type AttestRelayNodeKeyOptions, } from './attest-node-key.js';

package/dist/relay-attestation/index.js

@@ -0,0 +1 @@
+export { attestRelayNodeKey, attestKeyBinding, reportDataOf, } from './attest-node-key.js';

package/dist/request-proof/authorizer.d.ts

@@ -0,0 +1,48 @@
+import type { Signer } from '../signer/index.js';
+/** What a keyholder holds: a certificate, and the key it certifies. */
+export interface ProofCredential {
+    /** The `AccountProof<DeviceCert>` from `signDeviceCert`, hex. */
+    credential: string;
+    /** The certified device's ed25519 secret, hex. Or pass `signer`. */
+    deviceSecret?: string;
+    /** A signer, for a key that cannot be exported to hex. */
+    signer?: Signer;
+    /** Seconds each signature stays valid. Defaults to `signRequestProof`'s. */
+    validForSeconds?: number;
+}
+/** One request, as the proof has to see it. */
+export interface RequestToAuthorize {
+    method: string;
+    /** Path only — a query string is excluded from the signature by design. */
+    path: string;
+    /** The body exactly as it will be sent, if there is one. */
+    body?: string | Uint8Array;
+}
+/**
+ * A per-request authorizer. Returns the headers to merge into the request.
+ *
+ * Returning headers rather than setting them keeps the caller in charge of the
+ * request: a transport that already has an `Authorization` header can decide
+ * which wins, and core decides the same way — a request carrying a token is
+ * answered by that token, and the proof is only consulted when there is none.
+ */
+export type RequestAuthorizer = (request: RequestToAuthorize) => Promise<Record<string, string>>;
+/**
+ * Turn a device cert into a {@link RequestAuthorizer}.
+ *
+ * The credential is validated once, here, rather than on the first request:
+ * a malformed one otherwise surfaces as a 401 from whichever read happened to
+ * run first, which reads as "the node refused me" and sends the caller looking
+ * in the wrong place.
+ */
+export declare function createProofAuthorizer(credential: ProofCredential): RequestAuthorizer;
+/**
+ * The path a proof must be signed over, taken from a URL.
+ *
+ * Callers hold a base URL and a relative path; the proof commits to the path the
+ * node will see, which is their join with the query dropped. Deriving it from
+ * the assembled URL rather than concatenating strings is what keeps a base URL
+ * carrying its own prefix (`…/admin-api`) from signing a path the node never
+ * receives.
+ */
+export declare function signedPath(url: string): string;