@calimero-network/mero-js 19.5.0 → 19.7.0

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

@@ -94,6 +94,62 @@ export interface CloudRelay {
     lastSeenAt?: string | null;
     confirmedAt?: string | null;
 }
+/**
+ * One node serving a namespace, as a caller with no cloud account sees it.
+ *
+ * The public counterpart to {@link CloudRelay}: same fleet rows, but keyed on a
+ * namespace id anyone holding an invitation already has, and answering both
+ * things a keyholder needs from a node rather than one of them.
+ */
+export interface CloudNamespaceNode {
+    peerId: string;
+    /**
+     * The node's own account id, hex.
+     *
+     * Intersect this against the invitation's signed `admitters` list before
+     * using the node. That list is a MINT-TIME SNAPSHOT, so a node assigned after
+     * an invitation was created is live, healthy, listed here, and still refused
+     * with 403 — the cloud cannot know which invitation you hold.
+     */
+    account: string | null;
+    /** Base URL, or `null` when the cloud knows none yet. */
+    relayUrl: string | null;
+    /** Ready-made admission URL, so a caller never rebuilds the path. */
+    admitUrl: string | null;
+    /** `'assigned'` (admitted pending confirm) or `'active'`. */
+    status: string;
+    /** Whether the node's heartbeat for this namespace is recent. */
+    fresh: boolean;
+    /**
+     * Whether a signed join can be presented here now.
+     *
+     * Deliberately independent of {@link CloudNamespaceNode.authorshipReady}:
+     * relaying a join the joiner already signed is not authoring on anyone's
+     * behalf, so a node with no grant admits perfectly well.
+     */
+    canAdmit: boolean;
+    /** Whether the node holds `CAN_AUTHOR_ON_BEHALF` on the namespace root group. */
+    authorshipReady: boolean;
+    /**
+     * Whether a delegated write can be posted here now — a URL, an account, a
+     * fresh heartbeat and the grant.
+     *
+     * Namespace-level. A context in a RESTRICTED SUBGROUP is governed by that
+     * subgroup, so per-context routing remains the exact answer if a write is
+     * refused despite this being true.
+     */
+    canExecute: boolean;
+}
+/** What {@link CloudClient.getNamespaceRouting} reports. */
+export interface CloudNamespaceRouting {
+    namespaceId: string;
+    /** Usable nodes first, then a stable order, so a polling caller sees no shuffle. */
+    nodes: CloudNamespaceNode[];
+    /** Whether any listed node can take a join now. */
+    servable: boolean;
+    /** Whether any listed node can take a delegated write now. */
+    writable: boolean;
+}
 /** One namespace of the caller's that a machine is serving. */
 export interface CloudMachineNamespace {
     namespaceId: string;
@@ -134,6 +190,52 @@ export interface CloudMachine {
     /** Only the caller's own namespaces, even on a machine shared with others. */
     namespaces: CloudMachineNamespace[];
 }
+/** A Calimero account linked to this cloud login. */
+export interface CloudLinkedAccount {
+    /** The account id, 64 hex. */
+    accountId: string;
+    linkedAt?: string | null;
+    /**
+     * Whether a recovery envelope has been stored for this account, so a UI can
+     * say "recoverable" without fetching the blob.
+     */
+    hasRecoveryEnvelope: boolean;
+}
+/** What {@link CloudClient.getMyAccounts} reports. */
+export interface CloudLinkedAccounts {
+    accounts: CloudLinkedAccount[];
+    /** How many the caller's plan allows. `null` means no limit. */
+    limit: number | null;
+}
+/** A single-use challenge to sign with an account root. */
+export interface AccountLinkChallenge {
+    /** Sign this verbatim — it is an opaque sealed string, not a decodable id. */
+    nonce: string;
+    /** When it stops being accepted, epoch milliseconds. */
+    expiresAtMs: number | null;
+}
+/** A proof assembled by whoever holds the root, for {@link CloudClient.submitAccountLink}. */
+export interface AccountLinkProof {
+    /** The account being claimed, 64 hex. */
+    accountId: string;
+    /** The root that names it, 64 hex. */
+    rootPublicKey: string;
+    /** The challenge that was signed. */
+    nonce: string;
+    /** `signAccountLink`'s output — standard base64. */
+    signature: string;
+}
+/** The outcome of {@link CloudClient.linkAccount}. */
+export interface CloudAccountLink {
+    accountId: string;
+    linkedAt?: string | null;
+    /**
+     * True when this account was already linked to this same login, which the
+     * cloud treats as a 200 no-op rather than an error. A caller re-running
+     * onboarding gets success, not a confusing failure.
+     */
+    alreadyLinked: boolean;
+}
 export interface EnableHAOptions {
     groupId: string;
     contextId: string;
@@ -201,6 +303,39 @@ export declare class CloudClient {
      * must be in place.
      */
     findExecutingRelay(namespaceId: string): Promise<CloudRelay | null>;
+    /**
+     * Where to reach a namespace without owning it: one read, both verbs.
+     *
+     * **Anonymous.** A joiner is by construction not the namespace owner and holds
+     * no cloud session — needing one is exactly what this path exists to avoid.
+     * Discovery is not authorization: merod refuses an `/admit` call unless the
+     * relaying node's account is on the invitation's signed `admitters` list, and
+     * refuses an intent unless the warrant is genuinely the member's, so naming a
+     * node grants the caller nothing it did not already have.
+     *
+     * A keyholder resolves a namespace to a node ONCE and then admits, reads and
+     * posts intents against that same node, which is why admission and writability
+     * are answered together rather than across two endpoints — the per-context
+     * read needs a context id a joiner does not yet have.
+     *
+     * An empty `nodes` list is a state, not an error: a namespace with no fleet
+     * assignment has no cloud node, and the joiner must use one of the
+     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     */
+    getNamespaceRouting(namespaceId: string): Promise<CloudNamespaceRouting>;
+    /**
+     * The node to send a signed join to, chosen from those an invitation names.
+     *
+     * Pass the invitation's `admitters` and the intersection is done here, because
+     * skipping it is the failure this method exists to prevent: the cloud lists
+     * every node assigned to the namespace, while `admitters` is a snapshot signed
+     * when the invitation was minted. A node added afterwards looks perfect in
+     * every field here and answers 403.
+     *
+     * Omit `admitters` only for an invitation that names none — an empty list on
+     * the wire authorises any node to admit.
+     */
+    findAdmitter(namespaceId: string, admitters?: readonly string[]): Promise<CloudNamespaceNode | null>;
     /**
      * Every attested machine currently serving something this account owns.
      *
@@ -265,6 +400,53 @@ export declare class CloudClient {
     enableHA(options: EnableHAOptions): void;
     disableHA(options: DisableHAOptions): void;
     /** Record a freshly-issued session and tell the app to persist it. */
+    /**
+     * Link a Calimero account to this cloud login, proving possession of its root.
+     *
+     * Two hops, folded into one call because they are useless apart: fetch a
+     * single-use challenge, then sign it with the account root and post the proof.
+     * The secret never leaves this process — only a signature over a nonce the
+     * cloud minted does.
+     *
+     * This is the binding the cloud bills against. A relay does not need it to run
+     * an intent; the cloud needs it to know whose plan a hosted node is spending,
+     * and to sign that account back in later.
+     *
+     * @param rootSecret the account root's signing secret, 64 hex — from
+     *   {@link generateAccountRoot}, from a restored recovery phrase, or from a
+     *   desktop app or hardware key that already holds one.
+     *
+     * Idempotent for the same login. An account already linked to a *different*
+     * cloud login is a `409`; a replayed or expired challenge is a `403`; and
+     * exceeding the plan's account limit is a `402`.
+     */
+    linkAccount(rootSecret: string): Promise<CloudAccountLink>;
+    /**
+     * Mint a single-use challenge for an account root to sign.
+     *
+     * The split half of {@link linkAccount}, for the case that call cannot serve:
+     * a root held by a desktop app, a hardware key or an air-gapped machine, which
+     * signs without the secret ever reaching this process. Fetch the challenge
+     * here, have the holder sign it, then hand the proof to
+     * {@link submitAccountLink}.
+     *
+     * Bound to the signed-in login and short-lived, so it is not a standing
+     * capability if it leaks — but it IS single-use, so a challenge fetched and
+     * abandoned is spent.
+     */
+    getAccountLinkChallenge(): Promise<AccountLinkChallenge>;
+    /**
+     * Post a proof assembled elsewhere. The other half of
+     * {@link getAccountLinkChallenge}.
+     *
+     * `accountId` must be the account `rootPublicKey` names — the cloud refuses a
+     * valid signature by a key that names a different account, or a caller could
+     * prove one root and link somebody else's account. Derive both from the same
+     * key rather than letting a user type either.
+     */
+    submitAccountLink(proof: AccountLinkProof): Promise<CloudAccountLink>;
+    /** The accounts linked to this login, and how many the plan allows. */
+    getMyAccounts(): Promise<CloudLinkedAccounts>;
     private adoptSession;
     private notifySession;
     private request;

package/dist/cloud/cloud-client.js

@@ -24,6 +24,7 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
+import { accountRootFromSecret, signAccountLink, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.js';
 /** Where the hosted cloud lives when a caller names no other. */
 const DEFAULT_CLOUD_BASE_URL = 'https://cloud.calimero.network';
@@ -148,6 +149,64 @@ export class CloudClient {
         return (relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ??
             null);
     }
+    /**
+     * Where to reach a namespace without owning it: one read, both verbs.
+     *
+     * **Anonymous.** A joiner is by construction not the namespace owner and holds
+     * no cloud session — needing one is exactly what this path exists to avoid.
+     * Discovery is not authorization: merod refuses an `/admit` call unless the
+     * relaying node's account is on the invitation's signed `admitters` list, and
+     * refuses an intent unless the warrant is genuinely the member's, so naming a
+     * node grants the caller nothing it did not already have.
+     *
+     * A keyholder resolves a namespace to a node ONCE and then admits, reads and
+     * posts intents against that same node, which is why admission and writability
+     * are answered together rather than across two endpoints — the per-context
+     * read needs a context id a joiner does not yet have.
+     *
+     * An empty `nodes` list is a state, not an error: a namespace with no fleet
+     * assignment has no cloud node, and the joiner must use one of the
+     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     */
+    async getNamespaceRouting(namespaceId) {
+        const body = await this.request('GET', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/admitters`, {
+            anonymous: true,
+        });
+        return {
+            namespaceId: String(body.namespace_id ?? namespaceId),
+            nodes: (body.admitters ?? []).map((row) => ({
+                peerId: String(row.peer_id ?? ''),
+                account: row.account ?? null,
+                relayUrl: row.relay_url ?? null,
+                admitUrl: row.admit_url ?? null,
+                status: String(row.status ?? ''),
+                fresh: row.fresh === true,
+                canAdmit: row.can_admit === true,
+                authorshipReady: row.authorship_ready === true,
+                canExecute: row.can_execute === true,
+            })),
+            servable: body.servable === true,
+            writable: body.writable === true,
+        };
+    }
+    /**
+     * The node to send a signed join to, chosen from those an invitation names.
+     *
+     * Pass the invitation's `admitters` and the intersection is done here, because
+     * skipping it is the failure this method exists to prevent: the cloud lists
+     * every node assigned to the namespace, while `admitters` is a snapshot signed
+     * when the invitation was minted. A node added afterwards looks perfect in
+     * every field here and answers 403.
+     *
+     * Omit `admitters` only for an invitation that names none — an empty list on
+     * the wire authorises any node to admit.
+     */
+    async findAdmitter(namespaceId, admitters) {
+        const { nodes } = await this.getNamespaceRouting(namespaceId);
+        const allowed = admitters && admitters.length > 0 ? new Set(admitters.map((a) => a.toLowerCase())) : null;
+        return (nodes.find((n) => n.canAdmit &&
+            (allowed === null || (n.account !== null && allowed.has(n.account.toLowerCase())))) ?? null);
+    }
     /**
      * Every attested machine currently serving something this account owns.
      *
@@ -260,6 +319,89 @@ export class CloudClient {
         window.open(`${this.baseUrl}/disable-ha?${params.toString()}`);
     }
     /** Record a freshly-issued session and tell the app to persist it. */
+    /**
+     * Link a Calimero account to this cloud login, proving possession of its root.
+     *
+     * Two hops, folded into one call because they are useless apart: fetch a
+     * single-use challenge, then sign it with the account root and post the proof.
+     * The secret never leaves this process — only a signature over a nonce the
+     * cloud minted does.
+     *
+     * This is the binding the cloud bills against. A relay does not need it to run
+     * an intent; the cloud needs it to know whose plan a hosted node is spending,
+     * and to sign that account back in later.
+     *
+     * @param rootSecret the account root's signing secret, 64 hex — from
+     *   {@link generateAccountRoot}, from a restored recovery phrase, or from a
+     *   desktop app or hardware key that already holds one.
+     *
+     * Idempotent for the same login. An account already linked to a *different*
+     * cloud login is a `409`; a replayed or expired challenge is a `403`; and
+     * exceeding the plan's account limit is a `402`.
+     */
+    async linkAccount(rootSecret) {
+        const root = await accountRootFromSecret(rootSecret);
+        const { nonce } = await this.getAccountLinkChallenge();
+        return this.submitAccountLink({
+            accountId: root.accountId,
+            rootPublicKey: root.publicKey,
+            nonce,
+            signature: await signAccountLink({ rootSecret, nonce }),
+        });
+    }
+    /**
+     * Mint a single-use challenge for an account root to sign.
+     *
+     * The split half of {@link linkAccount}, for the case that call cannot serve:
+     * a root held by a desktop app, a hardware key or an air-gapped machine, which
+     * signs without the secret ever reaching this process. Fetch the challenge
+     * here, have the holder sign it, then hand the proof to
+     * {@link submitAccountLink}.
+     *
+     * Bound to the signed-in login and short-lived, so it is not a standing
+     * capability if it leaks — but it IS single-use, so a challenge fetched and
+     * abandoned is spent.
+     */
+    async getAccountLinkChallenge() {
+        const body = await this.request('GET', '/api/cloud/me/accounts/challenge');
+        return { nonce: body.nonce, expiresAtMs: body.expires_at_ms ?? null };
+    }
+    /**
+     * Post a proof assembled elsewhere. The other half of
+     * {@link getAccountLinkChallenge}.
+     *
+     * `accountId` must be the account `rootPublicKey` names — the cloud refuses a
+     * valid signature by a key that names a different account, or a caller could
+     * prove one root and link somebody else's account. Derive both from the same
+     * key rather than letting a user type either.
+     */
+    async submitAccountLink(proof) {
+        const body = await this.request('POST', '/api/cloud/me/accounts', {
+            body: {
+                account_id: proof.accountId,
+                root_public_key: proof.rootPublicKey,
+                nonce: proof.nonce,
+                signature: proof.signature,
+            },
+        });
+        return {
+            accountId: String(body.account_id ?? proof.accountId),
+            linkedAt: body.linked_at ?? null,
+            alreadyLinked: body.already_linked === true,
+        };
+    }
+    /** The accounts linked to this login, and how many the plan allows. */
+    async getMyAccounts() {
+        const body = await this.request('GET', '/api/cloud/me/accounts');
+        return {
+            accounts: (body.accounts ?? []).map((row) => ({
+                accountId: String(row.account_id ?? ''),
+                linkedAt: row.linked_at ?? null,
+                hasRecoveryEnvelope: row.has_recovery_envelope === true,
+            })),
+            limit: body.limit ?? null,
+        };
+    }
     adoptSession(body) {
         this.session = {
             sessionToken: body.session_token,

package/dist/cloud/connect.js

@@ -123,8 +123,15 @@ function explainNoRelay(namespace, relays) {
     }
     const waitingOnGrant = relays.filter((r) => !r.authorshipReady);
     if (waitingOnGrant.length === relays.length) {
+        // Name the call, not just the capability. The grant is a governance op only
+        // a namespace admin can publish, so this message is read by someone who has
+        // to go ask for it — and "grant CAN_AUTHOR_ON_BEHALF" alone leaves them
+        // relaying a constant to an admin who then has to work out the command.
+        // `openToDelegatedExecution` is the durable half (every relay assigned from
+        // then on lands open), `grantAuthorship` the one for relays already here.
         return (`every relay on namespace ${namespace.namespaceId} is waiting for the authorship grant: ` +
-            `an admin of the namespace must grant CAN_AUTHOR_ON_BEHALF to ${waitingOnGrant.map((r) => r.executorAccount ?? r.peerId).join(', ') || 'the relay account'}`);
+            `an admin of the namespace must grant CAN_AUTHOR_ON_BEHALF to ${waitingOnGrant.map((r) => r.executorAccount ?? r.peerId).join(', ') || 'the relay account'} — with AdminClient.grantAuthorship(namespaceId, account) for these relays, and ` +
+            `AdminClient.openToDelegatedExecution(namespaceId) so relays assigned later need no further op`);
     }
     return `namespace ${namespace.namespaceId} has ${relays.length} relay(s), but none reported both a URL and an executor account yet — retry shortly`;
 }

package/dist/cloud/index.d.ts

@@ -1,4 +1,4 @@
 export { CloudClient } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudMachine, CloudMachineNamespace, EnableHAOptions, DisableHAOptions, } 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';