@calimero-network/mero-js 22.7.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 {
@@ -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;

package/dist/request-proof/authorizer.js

@@ -0,0 +1,65 @@
+/**
+ * A device cert, as something every transport can authenticate a request with.
+ *
+ * {@link signRequestProof} signs one request. This wraps it in the shape the
+ * rest of the SDK can consume without knowing what a proof is: a function from
+ * `(method, path, body)` to the headers that request should carry. The HTTP
+ * client, the SSE client and the admin client each take that function, so a
+ * keyholder is authenticated the same way on all three and none of them holds a
+ * second copy of the encoding.
+ *
+ * ## Why the authorizer, and not a token
+ *
+ * A bearer token is one value reused across requests, so `getAuthToken` can be
+ * called once and its result cached. A proof commits to the method, the path and
+ * the body, so it cannot be: every request needs its own, and the signature has
+ * to be taken where those three are known. That is the whole reason this is a
+ * per-request callback rather than another token provider.
+ *
+ * Measured against a node built from core `aecba573b`: reads answer `200` to a
+ * proof with no session, `/sse` answers `200` and `/ws` upgrades `101`, and the
+ * listings are caller-scoped — an account in one of the node's two namespaces is
+ * shown one, and a WS subscribe naming a context it is not a member of is
+ * refused while the one it is a member of is granted.
+ */
+import { REQUEST_PROOF_HEADER, signRequestProof } from './request-proof.js';
+/**
+ * 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 function createProofAuthorizer(credential) {
+    if (!credential.credential) {
+        throw new Error('a proof authorizer needs the `credential` from signDeviceCert');
+    }
+    if (!credential.deviceSecret && !credential.signer) {
+        throw new Error('a proof authorizer needs either `deviceSecret` or `signer`');
+    }
+    return async ({ method, path, body }) => {
+        const proof = await signRequestProof({
+            method,
+            path,
+            body,
+            credential: credential.credential,
+            deviceSecret: credential.deviceSecret,
+            signer: credential.signer,
+            validForSeconds: credential.validForSeconds,
+        });
+        return { [REQUEST_PROOF_HEADER]: proof };
+    };
+}
+/**
+ * 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 function signedPath(url) {
+    return new URL(url).pathname;
+}

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

@@ -0,0 +1,4 @@
+export { signRequestProof, REQUEST_PROOF_HEADER } from './request-proof.js';
+export type { RequestProofInput } from './request-proof.js';
+export { createProofAuthorizer, signedPath } from './authorizer.js';
+export type { ProofCredential, RequestAuthorizer, RequestToAuthorize } from './authorizer.js';

package/dist/request-proof/index.js

@@ -0,0 +1,2 @@
+export { signRequestProof, REQUEST_PROOF_HEADER } from './request-proof.js';
+export { createProofAuthorizer, signedPath } from './authorizer.js';

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

@@ -0,0 +1,56 @@
+import type { Signer } from '../signer/index.js';
+/** The header a signed request carries. */
+export declare const REQUEST_PROOF_HEADER = "X-Calimero-Proof";
+export interface RequestProofInput {
+    /**
+     * The HTTP method, exactly as it will be sent.
+     *
+     * Not folded. `HEAD` and `GET` are the same *permission* and the node's
+     * permission table treats them so, but they are different *requests*: folding
+     * them here would let a proof minted for one be presented as the other.
+     */
+    method: string;
+    /**
+     * The path, **without** the query string.
+     *
+     * Excluded because a proxy may legitimately rewrite a query, and a signature
+     * over bytes something else may change fails for reasons the caller cannot
+     * see. Anything that must be bound belongs in the body.
+     */
+    path: string;
+    /**
+     * The body, exactly as it will be sent. Omit when there is none.
+     *
+     * There is no "absent body" case: an omitted body commits to the hash of no
+     * bytes, so a signer and a verifier cannot disagree about which encoding a
+     * bodyless request used.
+     */
+    body?: string | Uint8Array;
+    /** 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 the signature stays valid. Defaults to 300. */
+    validForSeconds?: number;
+    /** Override the clock, for tests. Unix seconds. */
+    now?: number;
+}
+/**
+ * Sign one request and return the `X-Calimero-Proof` value, hex.
+ *
+ * The encoding is borsh, and it is assembled rather than re-derived: the
+ * account proof is the **first** field of `CallerProof`, so the credential hex
+ * a caller already holds is exactly its own prefix. Concatenating avoids a
+ * second implementation of a structure the node deserializes — the class of bug
+ * that surfaces far away, as a node refusing a credential nothing can explain.
+ *
+ *   CallerProof = <account_proof bytes> || 0x00 (no session) || RequestSig
+ *   RequestSig  = u32le(len method) || method
+ *               || u32le(len path)  || path
+ *               || body_hash[32]
+ *               || u64le(issued_at) || u64le(expires_at)
+ *               || signature[64]
+ */
+export declare function signRequestProof(input: RequestProofInput): Promise<string>;