@calimero-network/mero-js 22.6.0 → 22.8.0

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 {
@@ -169,6 +183,61 @@ export interface GovernResult {
     /** The group the op acted on, hex: the new subgroup, for a creation. */
     groupId: string;
 }
+/** What {@link RelayClient.foundNamespace} founds with. */
+export interface FoundNamespaceInput {
+    /**
+     * The salt the namespace id is derived from, hex (32 bytes). Random when
+     * absent, which is what almost every caller wants: one account founds many
+     * namespaces by varying it.
+     */
+    salt?: string;
+    /**
+     * The relay's account, hex: the warrant's `executor`. The namespace does not
+     * exist yet, so there is nothing to ask `describeGovernance` about. Falls back
+     * to the client's configured or already-learned `executorAccount`.
+     */
+    executorAccount?: string;
+    /**
+     * The namespace root's default capability mask (`MemberCapabilities` bits),
+     * set right after founding. A namespace is founded with core's minimal
+     * default (`CAN_JOIN_OPEN_SUBGROUPS` only), so an app that wants members to
+     * create contexts or invite, for example, names its own mask here.
+     *
+     * Set through the relay with a delegated `DefaultCapabilitiesSet`, applied as
+     * the founder, who is the namespace's admin. It cannot include
+     * `CAN_AUTHOR_ON_BEHALF` (bit 9): which relays may write for members is never
+     * decided through a relay, and such a mask is refused before anything is
+     * signed.
+     */
+    defaultCapabilities?: number;
+}
+/** A namespace founded through a relay. */
+export interface FoundedNamespace {
+    /** The new namespace's id, hex: `foundedNamespaceId(author, salt)`. */
+    namespaceId: string;
+    /**
+     * The salt it was derived with, hex. Keep it if anyone will need to be shown
+     * who founded the namespace: `(founder, salt)` reproduces the id.
+     */
+    salt: string;
+    /**
+     * Whether the relay admitted itself as the namespace's first TEE, which also
+     * sets its default relay-mode admission policy. `false` from a relay that is
+     * not a TEE, or whose attestation failed (see `teeError`). The namespace is
+     * founded either way.
+     */
+    teeEnabled: boolean;
+    /** Why `teeEnabled` is `false`, when the relay tried and failed. */
+    teeError?: string;
+    /**
+     * Present only when `defaultCapabilities` was asked for: whether the mask was
+     * set. `false` leaves the namespace founded with core's default; retry with
+     * `govern({ groupId: namespaceId, op: defaultCapabilitiesSetOp(mask) })`.
+     */
+    defaultCapabilitiesSet?: boolean;
+    /** Why `defaultCapabilitiesSet` is `false`. */
+    defaultCapabilitiesError?: string;
+}
 /** Where an accepted intent landed. */
 export interface IntentResult<T = unknown> {
     /** The context's scope root after the run — did this change anything? */
@@ -208,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>;
     /**
@@ -284,10 +377,60 @@ export declare class RelayClient {
      * other warrant.
      */
     govern(input: GovernInput): Promise<GovernResult>;
+    /**
+     * Found a namespace through the relay, with the author as its founder, owner
+     * and admin. For an account with no node, this is how it gets a namespace at
+     * all.
+     *
+     * The author signs the exact genesis (`NamespaceCreatedV2`, carrying the
+     * author's own credential and the salt) under a root-plane governance
+     * warrant scoped to the new namespace's id, which is derived from the
+     * author's account and the salt, so the relay can neither choose another id
+     * nor found it for anyone else. The relay takes an identity in the new
+     * namespace, mints its key, publishes the genesis, and is seated as the
+     * founding relay (a `Member` holding `CAN_AUTHOR_ON_BEHALF`), so later
+     * `govern`, `createContext` and `execute` calls in the namespace work
+     * through it straight away. A TEE relay then admits itself as the
+     * namespace's first TEE; `teeEnabled` reports whether it did.
+     *
+     * The executor cannot be learned from the relay first: the namespace does not
+     * exist, so `describeGovernance` has nothing to answer about. It comes from
+     * `input.executorAccount`, the configured one, or one an earlier call learned
+     * (`describe`, `createContext`, `govern`), and without any of them this
+     * throws before taking a nonce.
+     * The nonce is spent in the new namespace's ledger.
+     *
+     * With `defaultCapabilities`, the founder then sets the namespace's default
+     * capability mask through the same relay (a second warrant, a second nonce)
+     * and `defaultCapabilitiesSet` reports whether it landed. A failure there
+     * does not throw, since the namespace is already founded.
+     *
+     * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
+     * that names an existing namespace is a `409`, an `HTTPError`.
+     */
+    foundNamespace(input?: FoundNamespaceInput): Promise<FoundedNamespace>;
+    private postGovernance;
     /**
      * The executor a warrant must name: the one the relay answered with, which a
      * 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,11 +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 { hex } from '../crypto/internal.js';
-import { resolveSigner } from '../signer/signer.js';
+import { fromHex, hex } from '../crypto/internal.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
 /**
@@ -61,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;
@@ -71,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 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 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 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');
@@ -237,8 +286,107 @@ export class RelayClient {
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
             signer,
         });
-        const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(input.groupId)}/governance-intents`, { warrant, authorProof: this.config.authorProof, op: hex(input.op.bytes) });
-        return { groupId: body.data.groupId };
+        const data = await this.postGovernance(input.groupId, input.op, warrant);
+        return { groupId: data.groupId };
+    }
+    /**
+     * Found a namespace through the relay, with the author as its founder, owner
+     * and admin. For an account with no node, this is how it gets a namespace at
+     * all.
+     *
+     * The author signs the exact genesis (`NamespaceCreatedV2`, carrying the
+     * author's own credential and the salt) under a root-plane governance
+     * warrant scoped to the new namespace's id, which is derived from the
+     * author's account and the salt, so the relay can neither choose another id
+     * nor found it for anyone else. The relay takes an identity in the new
+     * namespace, mints its key, publishes the genesis, and is seated as the
+     * founding relay (a `Member` holding `CAN_AUTHOR_ON_BEHALF`), so later
+     * `govern`, `createContext` and `execute` calls in the namespace work
+     * through it straight away. A TEE relay then admits itself as the
+     * namespace's first TEE; `teeEnabled` reports whether it did.
+     *
+     * The executor cannot be learned from the relay first: the namespace does not
+     * exist, so `describeGovernance` has nothing to answer about. It comes from
+     * `input.executorAccount`, the configured one, or one an earlier call learned
+     * (`describe`, `createContext`, `govern`), and without any of them this
+     * throws before taking a nonce.
+     * The nonce is spent in the new namespace's ledger.
+     *
+     * With `defaultCapabilities`, the founder then sets the namespace's default
+     * capability mask through the same relay (a second warrant, a second nonce)
+     * and `defaultCapabilitiesSet` reports whether it landed. A failure there
+     * does not throw, since the namespace is already founded.
+     *
+     * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
+     * that names an existing namespace is a `409`, an `HTTPError`.
+     */
+    async foundNamespace(input = {}) {
+        const executor = input.executorAccount
+            ? this.checkedExecutor(input.executorAccount)
+            : this.executorAccount;
+        if (!executor) {
+            throw new Error("foundNamespace needs the relay's account: pass executorAccount or configure it " +
+                '(checked before signing, no nonce was spent)');
+        }
+        const salt = input.salt
+            ? hex(fromHex(input.salt, 'salt', 32))
+            : hex(crypto.getRandomValues(new Uint8Array(32)));
+        const namespaceId = await foundedNamespaceId(this.config.authorAccount, salt);
+        const op = namespaceCreatedOp({
+            founder: this.config.authorAccount,
+            credential: this.config.authorProof,
+            salt,
+        });
+        // Encoded (and so validated) before anything is signed: a mask the relay
+        // would refuse must not cost the founding a nonce.
+        const capabilitiesOp = input.defaultCapabilities === undefined
+            ? undefined
+            : defaultCapabilitiesSetOp(input.defaultCapabilities);
+        // Resolved before the nonce, so a misconfigured key burns none.
+        const signer = await this.authorSigner();
+        const nonce = await this.config.nonces.next();
+        const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        const warrant = await signGovernanceWarrant({
+            scope: namespaceId,
+            op,
+            authorAccount: this.config.authorAccount,
+            executor,
+            nonce,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
+            signer,
+        });
+        const data = await this.postGovernance(namespaceId, op, warrant);
+        const founded = {
+            namespaceId: data.groupId,
+            salt,
+            teeEnabled: data.teeEnabled ?? false,
+            ...(data.teeError ? { teeError: data.teeError } : {}),
+        };
+        if (!capabilitiesOp)
+            return founded;
+        // A second op, under its own warrant, on the namespace root: the founder is
+        // its admin and the relay was seated to act for members, so it goes through
+        // the ordinary `govern` path. The namespace exists whatever happens here, so
+        // a failure is reported rather than thrown.
+        try {
+            await this.govern({ groupId: founded.namespaceId, op: capabilitiesOp });
+            return { ...founded, defaultCapabilitiesSet: true };
+        }
+        catch (err) {
+            return {
+                ...founded,
+                defaultCapabilitiesSet: false,
+                defaultCapabilitiesError: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async postGovernance(groupId, op, warrant) {
+        const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`, {
+            warrant,
+            authorProof: this.config.authorProof,
+            op: hex(op.bytes),
+        });
+        return body.data;
     }
     /**
      * The executor a warrant must name: the one the relay answered with, which a
@@ -253,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;