@calimero-network/mero-js 19.7.1 → 19.8.0

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

@@ -24,6 +24,7 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
+import { type RoutingChallenge, type RoutingCredential } from './routing-proof.js';
 export interface CloudClientConfig {
     cloudBaseUrl?: string;
     /**
@@ -45,6 +46,20 @@ export interface CloudClientConfig {
     fetch?: typeof fetch;
     /** Per-request timeout. Defaults to 10s, as the node clients do. */
     timeoutMs?: number;
+    /**
+     * The device credential to prove an account with on the routing read.
+     *
+     * Nothing to do with {@link sessionToken}: a cloud session says who is signed
+     * in, this says which account holds the key. A joiner has the second and
+     * cannot have the first — see `routing-proof.ts` for why that is not an
+     * oversight.
+     *
+     * Omitting it leaves {@link CloudClient.getNamespaceRouting} anonymous, which
+     * the cloud still answers while `require_routing_proof` is off. Supply it and
+     * the read is attributed; the cloud verifies a supplied proof either way, so
+     * a wrong one surfaces immediately rather than on the day the flag flips.
+     */
+    routingCredential?: RoutingCredential;
 }
 /** Who is signed in, and until when. */
 export interface CloudSession {
@@ -252,6 +267,7 @@ export declare class CloudClient {
     private readonly onSession?;
     private readonly fetchImpl;
     private readonly timeoutMs;
+    private readonly routingCredential?;
     constructor(config?: CloudClientConfig);
     /** The current session, or `null` when nobody is signed in. */
     getSession(): CloudSession | null;
@@ -323,6 +339,28 @@ export declare class CloudClient {
      * invitation's other admitters — another admin's node, or a self-hosted peer.
      */
     getNamespaceRouting(namespaceId: string): Promise<CloudNamespaceRouting>;
+    /**
+     * Ask the cloud for a challenge to prove an account against.
+     *
+     * Public and unauthenticated on purpose, and safe to be: the nonce is sealed
+     * and bound to this one namespace, so it is not a capability — it is the
+     * thing a capability gets demonstrated against. A caller with no credential
+     * gains nothing by holding one.
+     *
+     * {@link getNamespaceRouting} calls this for you when the client was
+     * constructed with a `routingCredential`. Call it directly only to sign a
+     * challenge somewhere this client cannot reach the key.
+     */
+    getRoutingChallenge(namespaceId: string): Promise<RoutingChallenge>;
+    /**
+     * The proof headers for one routing read, or nothing when no credential was
+     * configured.
+     *
+     * A challenge per read rather than a cached one: they expire in about two
+     * minutes and are single-namespace, so caching would trade one cheap request
+     * for a class of expiry bug that only shows up on a slow client.
+     */
+    private routingProof;
     /**
      * The node to send a signed join to, chosen from those an invitation names.
      *

package/dist/cloud/cloud-client.js

@@ -26,6 +26,7 @@
  */
 import { accountRootFromSecret, signAccountLink, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.js';
+import { routingProofHeaders, } from './routing-proof.js';
 /** Where the hosted cloud lives when a caller names no other. */
 const DEFAULT_CLOUD_BASE_URL = 'https://cloud.calimero.network';
 /** Response headers MDMA uses to hand back a rolling-refreshed session. */
@@ -44,6 +45,7 @@ export class CloudClient {
             ? (input, init) => injected(input, init)
             : (input, init) => globalThis.fetch(input, init);
         this.timeoutMs = config.timeoutMs ?? 10000;
+        this.routingCredential = config.routingCredential;
         if (config.sessionToken) {
             // Expiry unknown until the server tells us; 0 means "do not reason about
             // it locally", never "expired" — the server is the only judge and it
@@ -171,6 +173,7 @@ export class CloudClient {
     async getNamespaceRouting(namespaceId) {
         const body = await this.request('GET', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/admitters`, {
             anonymous: true,
+            headers: await this.routingProof(namespaceId),
         });
         return {
             namespaceId: String(body.namespace_id ?? namespaceId),
@@ -189,6 +192,42 @@ export class CloudClient {
             writable: body.writable === true,
         };
     }
+    /**
+     * Ask the cloud for a challenge to prove an account against.
+     *
+     * Public and unauthenticated on purpose, and safe to be: the nonce is sealed
+     * and bound to this one namespace, so it is not a capability — it is the
+     * thing a capability gets demonstrated against. A caller with no credential
+     * gains nothing by holding one.
+     *
+     * {@link getNamespaceRouting} calls this for you when the client was
+     * constructed with a `routingCredential`. Call it directly only to sign a
+     * challenge somewhere this client cannot reach the key.
+     */
+    async getRoutingChallenge(namespaceId) {
+        const body = await this.request('GET', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/challenge`, {
+            anonymous: true,
+        });
+        return {
+            namespaceId: String(body.namespace_id ?? namespaceId),
+            nonce: String(body.nonce ?? ''),
+            expiresAtMs: Number(body.expires_at_ms ?? 0),
+        };
+    }
+    /**
+     * The proof headers for one routing read, or nothing when no credential was
+     * configured.
+     *
+     * A challenge per read rather than a cached one: they expire in about two
+     * minutes and are single-namespace, so caching would trade one cheap request
+     * for a class of expiry bug that only shows up on a slow client.
+     */
+    async routingProof(namespaceId) {
+        if (!this.routingCredential)
+            return undefined;
+        const challenge = await this.getRoutingChallenge(namespaceId);
+        return routingProofHeaders(challenge, this.routingCredential);
+    }
     /**
      * The node to send a signed join to, chosen from those an invitation names.
      *
@@ -423,7 +462,13 @@ export class CloudClient {
         if (!options.anonymous && !this.session) {
             throw new Error('Not signed in to Calimero Cloud: call signInWithGoogle() or construct the client with a sessionToken');
         }
-        const headers = { Accept: 'application/json' };
+        // Caller headers go in FIRST, so the lines below win on any collision: a
+        // per-call header must never be able to replace the session's
+        // `Authorization` or change how the body is parsed.
+        const headers = {
+            ...options.headers,
+            Accept: 'application/json',
+        };
         if (options.body !== undefined)
             headers['Content-Type'] = 'application/json';
         if (!options.anonymous && this.session) {

package/dist/cloud/index.d.ts

@@ -2,3 +2,5 @@ export { CloudClient } from './cloud-client.js';
 export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
 export { connectCloud } from './connect.js';
 export type { ConnectCloudOptions, CloudConnection } from './connect.js';
+export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
+export type { RoutingCredential, RoutingChallenge, RoutingProofHeaders, } from './routing-proof.js';

package/dist/cloud/index.js

@@ -1,2 +1,3 @@
 export { CloudClient } from './cloud-client.js';
 export { connectCloud } from './connect.js';
+export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';

package/dist/cloud/routing-proof.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Proving an account to the cloud for the one read a joiner cannot avoid.
+ *
+ * `GET /api/cloud/namespaces/{ns}/admitters` answers where to send a signed
+ * membership op. A joiner needs it and *cannot* hold a cloud login: it is by
+ * construction not the namespace owner, and not needing an account on the cloud
+ * is the entire point of the path — a keyholder mints a root, certifies a
+ * device and signs its own join offline, and this read is the only thing that
+ * tells it where to post the result.
+ *
+ * So the caller proves possession of the credential it already holds. The cloud
+ * mints a sealed, namespace-bound nonce; the device signs it; the read carries
+ * the certificate and that signature.
+ *
+ * ## What this establishes, and what it does not
+ *
+ * It establishes that the caller holds a device key certified by some account
+ * root, and *which* account that is. It does **not** establish that the account
+ * was invited to the namespace, nor that it is a member — the cloud cannot
+ * check either, because membership is governance state held by the nodes.
+ * Anyone can mint an account root offline, so this is not a wall. It buys
+ * attribution (every read names an account and can be rate-limited) and it ends
+ * anonymous bulk discovery. Authorization stays where it always was: at the
+ * node, on the signed op.
+ *
+ * ## Why the DEVICE signs, not the root
+ *
+ * The opposite choice from {@link signAccountLink}, deliberately. That one
+ * exists for the device-loss case, so only the root will do. This one runs on
+ * every routing read from a browser that discards the root immediately after
+ * certifying its device — requiring the root would mean re-entering a 24-word
+ * phrase to look up a URL.
+ *
+ * The certificate alone is not enough and the signature is not redundant with
+ * it: a certificate travels in the clear inside every device-link op, so anyone
+ * who has seen one can replay it. Only the nonce signature binds the presenter
+ * to the device.
+ */
+/**
+ * The credential a routing read presents: a certificate, and the key to sign
+ * the challenge with.
+ *
+ * `credential` is the 237-byte `AccountProof<DeviceCert>` as hex — exactly what
+ * {@link signDeviceCert} returns, and the same string a login statement and a
+ * warrant carry. It is public by construction.
+ *
+ * `deviceSecret` never leaves the process. It signs the challenge locally and
+ * only the signature travels.
+ */
+export interface RoutingCredential {
+    /** The `AccountProof<DeviceCert>`, hex borsh, as `signDeviceCert` returns it. */
+    credential: string;
+    /** The certified device's ed25519 signing secret, hex (32 bytes). */
+    deviceSecret: string;
+}
+/** A challenge to sign, as the cloud minted it. */
+export interface RoutingChallenge {
+    namespaceId: string;
+    /** Opaque and sealed — the client neither parses nor constructs this. */
+    nonce: string;
+    /** Epoch **milliseconds**, as MDMA reports it. Nonces live about two minutes. */
+    expiresAtMs: number;
+}
+/**
+ * The three header values a proven routing read carries.
+ *
+ * Intersected with `Record<string, string>` rather than declared as a plain
+ * interface so it drops straight into a headers bag: an interface has no index
+ * signature, so TypeScript refuses it where `Record<string, string>` is wanted
+ * even though every field is a string.
+ */
+export type RoutingProofHeaders = Record<string, string> & {
+    'X-Calimero-Credential': string;
+    'X-Calimero-Nonce': string;
+    'X-Calimero-Signature': string;
+};
+/**
+ * Sign a routing challenge with the device key.
+ *
+ * Returns base64, which is what the header carries and what MDMA's verifier
+ * decodes — the one place this SDK does not spell a signature as hex, because
+ * the wire format is not ours to choose.
+ */
+export declare function signRoutingChallenge(nonce: string, deviceSecret: string): Promise<string>;
+/**
+ * Build the headers for one routing read, from a challenge the cloud minted.
+ *
+ * Separated from the request so a caller that fetches its own challenge — a
+ * test, or a client batching several reads against one nonce — can use the same
+ * encoding rather than a second spelling of it.
+ */
+export declare function routingProofHeaders(challenge: RoutingChallenge, credential: RoutingCredential): Promise<RoutingProofHeaders>;

package/dist/cloud/routing-proof.js

@@ -0,0 +1,92 @@
+/**
+ * Proving an account to the cloud for the one read a joiner cannot avoid.
+ *
+ * `GET /api/cloud/namespaces/{ns}/admitters` answers where to send a signed
+ * membership op. A joiner needs it and *cannot* hold a cloud login: it is by
+ * construction not the namespace owner, and not needing an account on the cloud
+ * is the entire point of the path — a keyholder mints a root, certifies a
+ * device and signs its own join offline, and this read is the only thing that
+ * tells it where to post the result.
+ *
+ * So the caller proves possession of the credential it already holds. The cloud
+ * mints a sealed, namespace-bound nonce; the device signs it; the read carries
+ * the certificate and that signature.
+ *
+ * ## What this establishes, and what it does not
+ *
+ * It establishes that the caller holds a device key certified by some account
+ * root, and *which* account that is. It does **not** establish that the account
+ * was invited to the namespace, nor that it is a member — the cloud cannot
+ * check either, because membership is governance state held by the nodes.
+ * Anyone can mint an account root offline, so this is not a wall. It buys
+ * attribution (every read names an account and can be rate-limited) and it ends
+ * anonymous bulk discovery. Authorization stays where it always was: at the
+ * node, on the signed op.
+ *
+ * ## Why the DEVICE signs, not the root
+ *
+ * The opposite choice from {@link signAccountLink}, deliberately. That one
+ * exists for the device-loss case, so only the root will do. This one runs on
+ * every routing read from a browser that discards the root immediately after
+ * certifying its device — requiring the root would mean re-entering a 24-word
+ * phrase to look up a URL.
+ *
+ * The certificate alone is not enough and the signature is not redundant with
+ * it: a certificate travels in the clear inside every device-link op, so anyone
+ * who has seen one can replay it. Only the nonce signature binds the presenter
+ * to the device.
+ */
+import { concat, fromHex, importSigningKey } from '../crypto/internal.js';
+/**
+ * The signing domain, followed immediately by the nonce as UTF-8.
+ *
+ * A flat prefix rather than this SDK's usual length-prefixed `domainHash`,
+ * because the verifier is MDMA's `verify_routing_proof` and it checks
+ * `DOMAIN ‖ nonce` against the raw message. The trailing NUL is part of the
+ * domain string on both sides; it is what stops a domain that is a prefix of
+ * some future one from colliding with it.
+ */
+const ROUTING_PROOF_DOMAIN = new TextEncoder().encode('calimero.mdma.routing-read.v1\0');
+/**
+ * Sign a routing challenge with the device key.
+ *
+ * Returns base64, which is what the header carries and what MDMA's verifier
+ * decodes — the one place this SDK does not spell a signature as hex, because
+ * the wire format is not ours to choose.
+ */
+export async function signRoutingChallenge(nonce, deviceSecret) {
+    // Validate the secret the same way every other signing path does, so a
+    // truncated or mis-cased key fails here rather than as a 403 from the cloud.
+    fromHex(deviceSecret, 'deviceSecret', 32);
+    const key = await importSigningKey(deviceSecret);
+    const message = concat(ROUTING_PROOF_DOMAIN, new TextEncoder().encode(nonce));
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, message));
+    return base64(signature);
+}
+/**
+ * Build the headers for one routing read, from a challenge the cloud minted.
+ *
+ * Separated from the request so a caller that fetches its own challenge — a
+ * test, or a client batching several reads against one nonce — can use the same
+ * encoding rather than a second spelling of it.
+ */
+export async function routingProofHeaders(challenge, credential) {
+    return {
+        'X-Calimero-Credential': credential.credential,
+        'X-Calimero-Nonce': challenge.nonce,
+        'X-Calimero-Signature': await signRoutingChallenge(challenge.nonce, credential.deviceSecret),
+    };
+}
+/**
+ * base64, the encoding the header carries.
+ *
+ * `btoa` is global in every browser and in Node since 16, and this package
+ * requires Node 18 — so there is no runtime here that needs a `Buffer`
+ * fallback, and adding one would pull a Node-only global into browser code.
+ */
+function base64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}