@calimero-network/mero-js 19.15.0 → 19.17.0

package/dist/mero-js.d.ts

@@ -1,6 +1,7 @@
 import type { AuthApiClient } from './auth-api/index.js';
 import type { AdminApiClient } from './admin-api/index.js';
 import type { TokenStore } from './token-store/index.js';
+import type { ProofRequest, ProofSignerOptions } from './request/index.js';
 import type { AuthCallbackResult, AuthLoginOptions } from './auth/index.js';
 import { RpcClient } from './rpc/index.js';
 import { SseClient } from './events/sse.js';
@@ -44,6 +45,40 @@ export interface MeroJsConfig {
      * instead — it returns a connection that can write without one.
      */
     cloud?: CloudClientConfig;
+    /**
+     * Sign every request with a device key, instead of or alongside a session.
+     *
+     * A session is a bearer token: obtained once, presented many times. A
+     * request-carried proof commits to one method, one path and one body, so it
+     * is minted per call and cannot be lifted onto another request. It is what
+     * lets a client talk to a relay it has no account on — nothing was ever
+     * issued to it.
+     *
+     * Pass the keys and let the SDK mint each proof:
+     *
+     * ```ts
+     * new MeroJs({
+     *   baseUrl,
+     *   requestProof: { credential, session, signerSecret },
+     * });
+     * ```
+     *
+     * …or pass your own signer, when the key must not reach the SDK at all — a
+     * hardware token, or a worker that holds it:
+     *
+     * ```ts
+     * new MeroJs({ baseUrl, requestProof: (req) => myWorker.sign(req) });
+     * ```
+     *
+     * The node only honours this when it runs with `--delegated-access`; a node
+     * that does not answers `403`, which is distinct from the `401` a bad proof
+     * gets.
+     *
+     * Applies to the request/response API. `events` (SSE) and `ws` are long-lived
+     * connections rather than requests, so a per-request signature does not
+     * describe them — they still use the session.
+     */
+    requestProof?: ProofSignerOptions | ((request: ProofRequest) => Promise<string | undefined>);
 }
 export interface TokenData {
     access_token: string;

package/dist/mero-js.js

@@ -2,11 +2,24 @@ import { createBrowserHttpClient } from './http-client/index.js';
 import { createAuthApiClientFromHttpClient } from './auth-api/index.js';
 import { createAdminApiClientFromHttpClient } from './admin-api/index.js';
 import { parseAuthCallback, buildAuthLoginUrl } from './auth/index.js';
+import { createProofSigner } from './request/index.js';
 import { RpcClient } from './rpc/index.js';
 import { SseClient } from './events/sse.js';
 import { WsClient } from './events/ws.js';
 import { EphemeralClient } from './ephemeral/index.js';
 import { CloudClient } from './cloud/cloud-client.js';
+/**
+ * Accept either the keys or a ready signer.
+ *
+ * Taking a callback as well as an options object is not a convenience: it is
+ * how a caller keeps the signing key out of the SDK entirely when it lives
+ * somewhere the SDK cannot reach.
+ */
+function resolveProofSigner(config) {
+    if (!config)
+        return undefined;
+    return typeof config === 'function' ? config : createProofSigner(config);
+}
 /** Name of the Web Lock that serializes token refresh across tabs / webviews. */
 const REFRESH_LOCK_NAME = 'mero-js:token-refresh';
 /** Returns `navigator.locks` when the runtime supports the Web Locks API. */
@@ -58,8 +71,13 @@ export class MeroJs {
         // Create HTTP client with token management
         // For Tauri, explicitly set credentials to 'omit' to avoid network errors
         const isTauri = typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window;
+        // One signer for the whole connection: `authClient` and `adminClient` are
+        // both built FROM this transport, so wiring it here covers every request
+        // either of them makes.
+        const getProof = resolveProofSigner(this.config.requestProof);
         this.httpClient = createBrowserHttpClient({
             baseUrl: this.config.baseUrl,
+            getProof,
             getAuthToken: async () => {
                 const token = await this.getValidToken();
                 return token?.access_token || '';

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

@@ -0,0 +1,43 @@
+/**
+ * Assemble the credential a node reads from `X-Calimero-Proof`.
+ *
+ * A request-carried proof is three links, and the node needs all of them in one
+ * header: the account root certified the device, the device (optionally)
+ * certified a short-lived session key, and that key signed THIS request. Each
+ * link is minted by its own function here — {@link signDeviceCert},
+ * {@link signLoginStatement}, {@link signRequest} — and each already returns
+ * the borsh encoding of the Rust type the node deserializes. Rust's
+ * `CallerProof` is a plain struct of those three fields, and borsh writes a
+ * struct as its fields back to back, so assembling the header is concatenation
+ * rather than a fourth encoder.
+ *
+ * That is worth stating because it is load-bearing and it is not obvious: if it
+ * were re-encoded here there would be a second spelling of a signed structure,
+ * able to disagree with the one that was signed. `caller-proof.test.ts` pins the
+ * concatenation against bytes produced by core itself.
+ */
+/** The three links, each already hex-encoded by the function that signed it. */
+export interface CallerProofInput {
+    /**
+     * `signDeviceCert(...)` — the account root's certificate over the device key,
+     * with the genesis that names the account.
+     */
+    credential: string;
+    /**
+     * `signLoginStatement(...)`, when signing with a session key.
+     *
+     * Omit it on the two-link chain, where the device key signs the request
+     * itself. Omitting is not the same as passing an empty string: borsh writes
+     * `Option` as a tag byte, so the two produce different bytes and only one of
+     * them parses.
+     */
+    session?: string;
+    /** `signRequest(...)` — the signature over this exact method, path and body. */
+    request: string;
+}
+/**
+ * Concatenate the three links into the header value.
+ *
+ * Returns hex, ready to present as `X-Calimero-Proof`.
+ */
+export declare function callerProof(input: CallerProofInput): string;

package/dist/request/caller-proof.js

@@ -0,0 +1,36 @@
+/**
+ * Assemble the credential a node reads from `X-Calimero-Proof`.
+ *
+ * A request-carried proof is three links, and the node needs all of them in one
+ * header: the account root certified the device, the device (optionally)
+ * certified a short-lived session key, and that key signed THIS request. Each
+ * link is minted by its own function here — {@link signDeviceCert},
+ * {@link signLoginStatement}, {@link signRequest} — and each already returns
+ * the borsh encoding of the Rust type the node deserializes. Rust's
+ * `CallerProof` is a plain struct of those three fields, and borsh writes a
+ * struct as its fields back to back, so assembling the header is concatenation
+ * rather than a fourth encoder.
+ *
+ * That is worth stating because it is load-bearing and it is not obvious: if it
+ * were re-encoded here there would be a second spelling of a signed structure,
+ * able to disagree with the one that was signed. `caller-proof.test.ts` pins the
+ * concatenation against bytes produced by core itself.
+ */
+import { fromHexUnsized, hex, concat } from "../crypto/internal.js";
+/**
+ * Concatenate the three links into the header value.
+ *
+ * Returns hex, ready to present as `X-Calimero-Proof`.
+ */
+export function callerProof(input) {
+    const credential = fromHexUnsized(input.credential, "credential");
+    const request = fromHexUnsized(input.request, "request signature");
+    // Borsh `Option<T>`: a single tag byte, then the value when present. A
+    // two-link chain is `None`, not an empty `Some` — the node reads the tag
+    // before anything else, so getting it backwards fails to parse rather than
+    // failing to verify, which at least is loud.
+    const session = input.session === undefined
+        ? new Uint8Array([0])
+        : concat(new Uint8Array([1]), fromHexUnsized(input.session, "session statement"));
+    return hex(concat(credential, session, request));
+}

package/dist/request/index.d.ts

@@ -1 +1,3 @@
 export { requestBodyHash, signRequest, type RequestSigInput, } from "./request-sig.js";
+export { callerProof, type CallerProofInput } from "./caller-proof.js";
+export { createProofSigner, type ProofRequest, type ProofSignerOptions, } from "./proof-signer.js";

package/dist/request/index.js

@@ -1 +1,3 @@
 export { requestBodyHash, signRequest, } from "./request-sig.js";
+export { callerProof } from "./caller-proof.js";
+export { createProofSigner, } from "./proof-signer.js";

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

@@ -0,0 +1,49 @@
+/**
+ * Turn a device key into something the HTTP client can call per request.
+ *
+ * A session is a bearer token: mint once, present many times. A request-carried
+ * proof is the opposite — it commits to one method, one path and one body, so
+ * it has to be produced at the moment of the call, by something holding the
+ * signing key. This is that something, shaped like `getAuthToken` so the key
+ * stays with the caller and never reaches the transport.
+ */
+/** What the transport knows about the call it is about to make. */
+export interface ProofRequest {
+    /** `GET`, `POST`, … exactly as it will be sent. */
+    method: string;
+    /** The URL path the node will see, **without** the query string. */
+    path: string;
+    /** The exact bytes that will be sent, if any. */
+    body?: unknown;
+}
+export interface ProofSignerOptions {
+    /** `signDeviceCert(...)`, hex. */
+    credential: string;
+    /**
+     * `signLoginStatement(...)`, hex — the three-link chain.
+     *
+     * Omit for the two-link chain, where `signerSecret` is the device key itself.
+     */
+    session?: string;
+    /**
+     * The ed25519 secret that signs each request, hex: the session key when
+     * `session` is set, otherwise the device key.
+     */
+    signerSecret: string;
+    /**
+     * How long each signature stays valid. Seconds, default 120.
+     *
+     * This is what bounds replay and nothing else does, so it is deliberately
+     * short and deliberately not configurable to "never". A clock skew allowance
+     * lives on the node; this only has to outlive the flight time.
+     */
+    ttlSeconds?: number;
+    /** Unix seconds. Injectable so a test does not depend on the wall clock. */
+    now?: () => number;
+}
+/**
+ * Build the `X-Calimero-Proof` value for one request.
+ *
+ * Pass the result to the HTTP client's `getProof`.
+ */
+export declare function createProofSigner(options: ProofSignerOptions): (request: ProofRequest) => Promise<string>;

package/dist/request/proof-signer.js

@@ -0,0 +1,59 @@
+/**
+ * Turn a device key into something the HTTP client can call per request.
+ *
+ * A session is a bearer token: mint once, present many times. A request-carried
+ * proof is the opposite — it commits to one method, one path and one body, so
+ * it has to be produced at the moment of the call, by something holding the
+ * signing key. This is that something, shaped like `getAuthToken` so the key
+ * stays with the caller and never reaches the transport.
+ */
+import { callerProof } from "./caller-proof.js";
+import { signRequest } from "./request-sig.js";
+/**
+ * The bytes a body will actually be sent as.
+ *
+ * Refuses what it cannot hash without consuming or re-encoding. A stream can be
+ * read once, and reading it here would send an empty body; `FormData` and
+ * `URLSearchParams` are serialized by `fetch` in ways this cannot reproduce
+ * byte for byte. Signing a guess would produce a signature over bytes that
+ * never travelled, and the node would reject it with a signature error that
+ * says nothing about the real cause — so this throws, naming the type.
+ */
+function bodyBytes(body) {
+    if (body === undefined || body === null)
+        return new Uint8Array(0);
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    throw new Error(`a request-carried proof cannot commit to a ${body?.constructor?.name ?? typeof body} body: pass a string or bytes, or use a session for this call`);
+}
+/**
+ * Build the `X-Calimero-Proof` value for one request.
+ *
+ * Pass the result to the HTTP client's `getProof`.
+ */
+export function createProofSigner(options) {
+    const ttl = options.ttlSeconds ?? 120;
+    const clock = options.now ?? (() => Math.floor(Date.now() / 1000));
+    return async (request) => {
+        const issuedAt = clock();
+        return callerProof({
+            credential: options.credential,
+            session: options.session,
+            request: await signRequest({
+                method: request.method,
+                path: request.path,
+                body: bodyBytes(request.body),
+                issuedAt,
+                expiresAt: issuedAt + ttl,
+                signerSecret: options.signerSecret,
+            }),
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "19.15.0",
+  "version": "19.17.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {