@calimero-network/mero-js 19.12.0 → 19.13.0

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

@@ -24,7 +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';
+import { type DiscoveryChallenge, type RoutingChallenge, type RoutingCredential } from './routing-proof.js';
 export interface CloudClientConfig {
     cloudBaseUrl?: string;
     /**
@@ -116,6 +116,20 @@ export interface CloudRelay {
  * namespace id anyone holding an invitation already has, and answering both
  * things a keyholder needs from a node rather than one of them.
  */
+/**
+ * One relay that serves an account, as the bootstrap read reports it.
+ *
+ * `fresh` and a null `relayUrl` are reported rather than filtered, because
+ * "your relay is down", "we have no address for it" and "you have no relay"
+ * need different actions from a caller and an empty list erases the
+ * distinction. A caller looking for somewhere to talk to wants
+ * `fresh && relayUrl`; one diagnosing wants the rest.
+ */
+export interface CloudAccountRelay {
+    peerId: string;
+    relayUrl: string | null;
+    fresh: boolean;
+}
 export interface CloudNamespaceNode {
     peerId: string;
     /**
@@ -438,6 +452,36 @@ export declare class CloudClient {
      * for a class of expiry bug that only shows up on a slow client.
      */
     private routingProof;
+    /**
+     * Ask the cloud for a challenge bound to one ACCOUNT.
+     *
+     * Public and unauthenticated like {@link getRoutingChallenge}: an account id
+     * is `H(genesis(root_pk))` and travels in the clear in every device-link op,
+     * so naming one here reveals nothing and authorises nothing. MDMA re-derives
+     * the account from the certificate and refuses a mismatch.
+     */
+    getAccountRelaysChallenge(accountId: string): Promise<DiscoveryChallenge>;
+    /**
+     * Which relays serve this account — the bootstrap, and nothing more.
+     *
+     * A device holding a certificate can resolve a namespace it can *name*
+     * ({@link getNamespaceRouting}) and can ask a node it can *reach* what its
+     * account belongs to. It starts with neither. This closes that one gap.
+     *
+     * **It does not return namespaces, deliberately.** The node answers that from
+     * the governance DAG, scoped to the calling account: log in at one of these
+     * relays with an account proof and read its namespace listing. A cloud-side
+     * copy would be a second source of truth built from rows that linger for an
+     * account which left a namespace.
+     *
+     * So the sequence is: this → log in at a relay → ask it what you are in.
+     *
+     * Proven with the **device certificate**, not a cloud session, so it needs a
+     * `routingCredential` and throws without one rather than returning an empty
+     * list — "you configured no credential" and "you have no relays" are
+     * different answers and must not look alike.
+     */
+    getAccountRelays(accountId: string): Promise<CloudAccountRelay[]>;
     /**
      * The node to send a signed join to, chosen from those an invitation names.
      *

package/dist/cloud/cloud-client.js

@@ -288,6 +288,60 @@ export class CloudClient {
         const challenge = await this.getRoutingChallenge(namespaceId);
         return routingProofHeaders(challenge, this.routingCredential);
     }
+    /**
+     * Ask the cloud for a challenge bound to one ACCOUNT.
+     *
+     * Public and unauthenticated like {@link getRoutingChallenge}: an account id
+     * is `H(genesis(root_pk))` and travels in the clear in every device-link op,
+     * so naming one here reveals nothing and authorises nothing. MDMA re-derives
+     * the account from the certificate and refuses a mismatch.
+     */
+    async getAccountRelaysChallenge(accountId) {
+        const body = await this.request('GET', `/api/cloud/accounts/${encodeURIComponent(accountId)}/challenge`, {
+            anonymous: true,
+        });
+        return {
+            accountId: String(body.account_id ?? accountId),
+            nonce: String(body.nonce ?? ''),
+            expiresAtMs: Number(body.expires_at_ms ?? 0),
+        };
+    }
+    /**
+     * Which relays serve this account — the bootstrap, and nothing more.
+     *
+     * A device holding a certificate can resolve a namespace it can *name*
+     * ({@link getNamespaceRouting}) and can ask a node it can *reach* what its
+     * account belongs to. It starts with neither. This closes that one gap.
+     *
+     * **It does not return namespaces, deliberately.** The node answers that from
+     * the governance DAG, scoped to the calling account: log in at one of these
+     * relays with an account proof and read its namespace listing. A cloud-side
+     * copy would be a second source of truth built from rows that linger for an
+     * account which left a namespace.
+     *
+     * So the sequence is: this → log in at a relay → ask it what you are in.
+     *
+     * Proven with the **device certificate**, not a cloud session, so it needs a
+     * `routingCredential` and throws without one rather than returning an empty
+     * list — "you configured no credential" and "you have no relays" are
+     * different answers and must not look alike.
+     */
+    async getAccountRelays(accountId) {
+        if (!this.routingCredential) {
+            throw new Error('getAccountRelays needs a routingCredential: construct the client with the device ' +
+                'certificate and its signing secret, since this read is proven by the device, not by a session.');
+        }
+        const challenge = await this.getAccountRelaysChallenge(accountId);
+        const body = await this.request('GET', `/api/cloud/accounts/${encodeURIComponent(accountId)}/relays`, {
+            anonymous: true,
+            headers: await routingProofHeaders(challenge, this.routingCredential),
+        });
+        return (body.relays ?? []).map((row) => ({
+            peerId: String(row.peer_id ?? ''),
+            relayUrl: row.relay_url ?? null,
+            fresh: row.fresh === true,
+        }));
+    }
     /**
      * The node to send a signed join to, chosen from those an invitation names.
      *

package/dist/cloud/index.d.ts

@@ -1,6 +1,6 @@
 export { CloudClient } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
+export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudAccountRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, 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';
+export type { RoutingCredential, DiscoveryChallenge, RoutingChallenge, RoutingProofHeaders, } from './routing-proof.js';

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

@@ -61,6 +61,23 @@ export interface RoutingChallenge {
     /** Epoch **milliseconds**, as MDMA reports it. Nonces live about two minutes. */
     expiresAtMs: number;
 }
+/**
+ * A challenge bound to an ACCOUNT rather than a namespace, for asking which
+ * relays serve that account.
+ *
+ * Separate from {@link RoutingChallenge} because the binding is the security
+ * property, not a field name: MDMA seals the account into this one and the
+ * namespace into that one, and refuses each at the other's route. Keeping the
+ * TypeScript types distinct is what stops a caller passing the wrong one and
+ * learning about it as a 403.
+ */
+export interface DiscoveryChallenge {
+    accountId: 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.
  *
@@ -88,5 +105,9 @@ export declare function signRoutingChallenge(nonce: string, deviceSecret: string
  * 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.
+ *
+ * Takes either challenge kind: only the nonce is signed and both are signed
+ * over the same domain, so one encoder serves both. What separates them is what
+ * MDMA sealed inside, which is checked server-side.
  */
-export declare function routingProofHeaders(challenge: RoutingChallenge, credential: RoutingCredential): Promise<RoutingProofHeaders>;
+export declare function routingProofHeaders(challenge: RoutingChallenge | DiscoveryChallenge, credential: RoutingCredential): Promise<RoutingProofHeaders>;

package/dist/cloud/routing-proof.js

@@ -69,6 +69,10 @@ export async function signRoutingChallenge(nonce, deviceSecret) {
  * 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.
+ *
+ * Takes either challenge kind: only the nonce is signed and both are signed
+ * over the same domain, so one encoder serves both. What separates them is what
+ * MDMA sealed inside, which is checked server-side.
  */
 export async function routingProofHeaders(challenge, credential) {
     return {