@calimero-network/mero-js 26.11.0 → 27.0.0

package/dist/cloud/cloud-client.js

@@ -1,1068 +0,0 @@
-/**
- * Calimero Cloud (MDMA) client.
- *
- * # Why the SDK knows about the cloud at all
- *
- * Delegated execution lets an account that holds one signing key write into a
- * context without running a node — but only through a *relay*, and a relay is
- * something the client has to be told about. A warrant names an executor
- * account, so a client that cannot discover which relay serves its namespace,
- * and which account that relay writes as, cannot mint a usable warrant at all.
- *
- * For a self-hosted namespace the operator hands those two facts over out of
- * band. For the hosted tier the cloud is the directory: the user signs in, the
- * cloud knows which namespaces they own and which attested TEE nodes are
- * assigned to each, and it answers with the relay's URL and executor account.
- * That is what this client is for — it is the discovery half of
- * {@link RelayClient}, not a second way to talk to a node.
- *
- * # What it deliberately is not
- *
- * It never sees a warrant, a device secret, or an intent. Discovery goes
- * through the cloud; the write goes straight from the client to the relay. A
- * cloud that proxied intents would read every method and argument its users
- * ever sent, and would be a throughput bottleneck on a path that has no reason
- * to involve it.
- */
-import { signAccountHaClaim } from './account-ownership.js';
-import { resolveRoot, resolveRootPair, signAccountLink, signAccountLogin, } from '../account/index.js';
-import { HTTPError } from '../http-client/web-client.js';
-import { pathSegment } from '../http-client/path-segment.js';
-import { ACCOUNT_HEX, VERIFIER_HEX, beginLinkState, linkChallenge, linkGrantClaims, takeLinkVerifier, } from './link-state.js';
-import { routingProofHeaders, } from './routing-proof.js';
-/**
- * The hosted cloud's **API** when a caller names no other.
- *
- * `manager.cloud.calimero.network`, not `cloud.calimero.network`: the latter
- * serves the React app, which answers an API call with 405 and an HTML body.
- * Every method on this client is an API call, so the bare `new CloudClient()`
- * used to fail at the first request with a parse error rather than at
- * construction — and the URL it was talking to looked right in the message.
- *
- * The web origin still exists in this package: the consent screen in
- * `link-redirect.ts` is a page a person visits, and that one is the app.
- */
-const DEFAULT_CLOUD_BASE_URL = 'https://manager.cloud.calimero.network';
-/**
- * The cloud's own `can_execute` where it sends one, else `legacy`.
- *
- * The cloud decides relaying by role (`RelayTee` relays, `ReadOnlyTee` never
- * does) and only falls back to the `CAN_AUTHOR_ON_BEHALF` grant for a node
- * that reports none, so re-deriving it here from `authorship_ready` would call
- * a grant-holding `ReadOnlyTee` writable. `legacy` is the grant-based answer,
- * for a cloud older than the field — the only rule such a cloud knew.
- */
-function canExecuteOf(row, legacy) {
-    return typeof row.can_execute === 'boolean' ? row.can_execute : legacy;
-}
-/** The reported `tee_role`, or `null` when absent (older cloud or sidecar). */
-function teeRoleOf(row) {
-    return typeof row.tee_role === 'string' && row.tee_role !== '' ? row.tee_role : null;
-}
-/**
- * The first relay a warrant can be spent at, or `null`.
- *
- * Shared by {@link CloudClient.findExecutingRelay} and `connectCloud`, which
- * already holds the list and must not fetch it twice.
- */
-export function pickExecutingRelay(relays) {
-    return (relays.find((r) => r.canExecute && r.relayUrl !== null && r.executorAccount !== null) ?? null);
-}
-/** `join` from a relay row, or `null` when absent or not an object. */
-function joinOf(row) {
-    const raw = row.join;
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return null;
-    const join = raw;
-    if (typeof join.state !== 'string')
-        return null;
-    const refusals = Array.isArray(join.refusals)
-        ? join.refusals
-            .filter((r) => !!r && typeof r === 'object')
-            .map((r) => ({ peer: String(r.peer ?? ''), reason: String(r.reason ?? '') }))
-        : [];
-    return {
-        state: join.state,
-        attempts: typeof join.attempts === 'number' ? join.attempts : 0,
-        refusals,
-        error: typeof join.error === 'string' ? join.error : null,
-        reportedAt: typeof join.reported_at === 'string' ? join.reported_at : null,
-    };
-}
-function accountHexOrNull(value) {
-    return typeof value === 'string' && ACCOUNT_HEX.test(value) ? value : null;
-}
-/**
- * The cloud's refusals of {@link CloudClient.enableHaAsAccount} that a
- * person can do something about. Both are `409`s with `{"error": code}`.
- *
- * Extends {@link HTTPError}, so `instanceof HTTPError` handling still catches it.
- */
-export class AccountHaRefusedError extends HTTPError {
-    constructor(
-    /** The cloud's `error` code, verbatim. */
-    code, status, statusText, url, headers, bodyText) {
-        super(status, statusText, url, headers, bodyText);
-        this.code = code;
-        this.name = 'AccountHaRefusedError';
-    }
-}
-/**
- * `account_not_linked`: the account was never linked to a cloud user through
- * the wallet, so the cloud has nobody to host the namespace for. Linking it
- * fixes this; retrying does not.
- */
-export class AccountNotLinkedError extends AccountHaRefusedError {
-    constructor() {
-        super(...arguments);
-        this.name = 'AccountNotLinkedError';
-    }
-}
-AccountNotLinkedError.CODE = 'account_not_linked';
-/**
- * `account_linked_to_several_users`: more than one cloud user linked this
- * account, so the cloud cannot tell whose quota hosts the namespace. Unlink it
- * from all but one.
- */
-export class AccountLinkedToSeveralUsersError extends AccountHaRefusedError {
-    constructor() {
-        super(...arguments);
-        this.name = 'AccountLinkedToSeveralUsersError';
-    }
-}
-AccountLinkedToSeveralUsersError.CODE = 'account_linked_to_several_users';
-/**
- * `ha_request_pending` (409): another namespace of this account is waiting for
- * its first fleet node to be admitted. The route allows one at a time; it
- * clears once that node is admitted, or by disabling HA on it from a cloud
- * session. The claim was not spent.
- */
-export class HaRequestPendingError extends AccountHaRefusedError {
-    constructor() {
-        super(...arguments);
-        this.name = 'HaRequestPendingError';
-    }
-}
-HaRequestPendingError.CODE = 'ha_request_pending';
-/**
- * `unknown_relay` (422): the cloud runs no relay at `relayUrl`. The claim was
- * not spent.
- */
-export class UnknownRelayError extends AccountHaRefusedError {
-    constructor() {
-        super(...arguments);
-        this.name = 'UnknownRelayError';
-    }
-}
-UnknownRelayError.CODE = 'unknown_relay';
-/**
- * `relay_not_dialable` (422): the relay is the cloud's but has not reported
- * its addresses yet. The claim was not spent; retrying later can succeed.
- */
-export class RelayNotDialableError extends AccountHaRefusedError {
-    constructor() {
-        super(...arguments);
-        this.name = 'RelayNotDialableError';
-    }
-}
-RelayNotDialableError.CODE = 'relay_not_dialable';
-const ACCOUNT_HA_REFUSALS = {
-    409: [AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError],
-    422: [UnknownRelayError, RelayNotDialableError],
-};
-/**
- * The `error` code of a 409 body. Accepts `{"error": code}` (the contract) and
- * FastAPI's `{"detail": code}` / `{"detail": {"error": code}}`, so how the
- * route raises it does not change what a caller catches.
- */
-function conflictCode(bodyText) {
-    if (!bodyText)
-        return undefined;
-    try {
-        const body = JSON.parse(bodyText);
-        if (typeof body?.error === 'string')
-            return body.error;
-        if (typeof body?.detail === 'string')
-            return body.detail;
-        const nested = body?.detail?.error;
-        if (typeof nested === 'string')
-            return nested;
-    }
-    catch {
-        // Not JSON: not one of ours.
-    }
-    return undefined;
-}
-/** Response headers MDMA uses to hand back a rolling-refreshed session. */
-const REFRESH_HEADER = 'x-mdma-session-refresh';
-const REFRESH_EXPIRES_HEADER = 'x-mdma-session-expires';
-export class CloudClient {
-    constructor(config = {}) {
-        this.session = null;
-        this.baseUrl = (config.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL).replace(/\/+$/, '');
-        this.onSession = config.onSession;
-        // Bound through an arrow function: an unbound `globalThis.fetch` throws
-        // "Illegal invocation" in a browser, the same reason the node HTTP clients
-        // wrap it.
-        const injected = config.fetch;
-        this.fetchImpl = injected
-            ? (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
-            // answers 401 when it disagrees.
-            this.session = {
-                sessionToken: config.sessionToken,
-                expiresAt: 0,
-                user: { email: '' },
-            };
-        }
-    }
-    /** The current session, or `null` when nobody is signed in. */
-    getSession() {
-        return this.session;
-    }
-    /** Whether a session token is held. Says nothing about the server agreeing. */
-    isSignedIn() {
-        return this.session !== null;
-    }
-    /**
-     * Exchange a Google OAuth2 ID token for an MDMA session.
-     *
-     * The app owns the Google flow (One Tap, an auth-code popup, a native
-     * browser) and hands the resulting ID token here once. Everything after this
-     * uses the returned session token, so the Google credential does not have to
-     * be kept or re-minted per call.
-     */
-    async signInWithGoogle(idToken) {
-        const body = await this.request('POST', '/api/auth/google', { body: { id_token: idToken }, anonymous: true });
-        return this.adoptSession(body);
-    }
-    /**
-     * Sign in as a Calimero account, proving it with its root key.
-     *
-     * The password-free counterpart to {@link signInWithGoogle}: no Google, no
-     * password, no server-held secret — the cloud mints a challenge, the account
-     * root signs it, and the session that comes back is the same MDMA session
-     * token every other cloud route already accepts.
-     *
-     * Doing this **once** is what makes an account's later device proofs mean
-     * something. A routing read shows that the caller holds a device the root
-     * certified, but certificates are public, so it can never show that anyone
-     * held the root; the cloud records this claim and from then on knows the
-     * account behind those reads was claimed by its owner. The claim is recorded
-     * even when the session is refused.
-     *
-     * @param root the account root: its 64-hex secret, or a `Signer` over a root
-     *   this process may use and cannot read — the form a phrase-held root in a
-     *   browser takes. Either way nothing but a signature over the cloud's nonce
-     *   travels.
-     *
-     * A `403` means either the signature did not verify, or the account is not
-     * linked to a cloud login: ownership alone says who you are, and the link
-     * says what you are entitled to. Anyone can mint a root offline, so a session
-     * on the proof alone would authenticate perfectly and authorize nothing. The
-     * ownership claim is recorded either way, so linking later needs no re-proof.
-     */
-    async signInWithAccount(root) {
-        const { signer, publicKey } = await resolveRoot(root);
-        const { nonce } = await this.getAccountLoginChallenge();
-        return this.submitAccountLogin({
-            rootPublicKey: publicKey,
-            nonce,
-            signature: await signAccountLogin({ signer, nonce }),
-        });
-    }
-    /**
-     * Mint a challenge for an account root to sign.
-     *
-     * Public, and deliberately so: the caller has no session — obtaining one is
-     * what this exchange does. The nonce is not a capability, it is the thing a
-     * capability gets demonstrated against, and demonstrating it needs the root.
-     *
-     * Split out of {@link signInWithAccount} for the case that call cannot serve:
-     * a root held by a hardware key, a desktop app or an air-gapped machine,
-     * which signs without the secret ever reaching this process.
-     */
-    async getAccountLoginChallenge() {
-        const body = await this.request('GET', '/api/auth/account/challenge', { anonymous: true });
-        return { nonce: body.nonce, expiresAtMs: body.expires_at_ms };
-    }
-    /** Post a proof assembled elsewhere. The other half of {@link getAccountLoginChallenge}. */
-    async submitAccountLogin(proof) {
-        const body = await this.request('POST', '/api/auth/account', {
-            body: {
-                root_public_key: proof.rootPublicKey,
-                nonce: proof.nonce,
-                signature: proof.signature,
-            },
-            anonymous: true,
-        });
-        return this.adoptSession(body);
-    }
-    /**
-     * Refresh the session token explicitly.
-     *
-     * Rarely needed: MDMA rolling-refreshes on ordinary authenticated calls and
-     * this client adopts the replacement automatically. Use it when an app wants
-     * a fresh token before going idle rather than on the next request.
-     */
-    async refreshSession() {
-        const body = await this.request('POST', '/api/auth/refresh');
-        return this.adoptSession(body);
-    }
-    /**
-     * Revoke this session server-side and forget it locally.
-     *
-     * Local state is cleared even if the server call fails: the caller asked to
-     * be signed out, and keeping a token they believe is gone is the worse of the
-     * two failures.
-     */
-    async signOut() {
-        try {
-            if (this.session)
-                await this.request('POST', '/api/auth/logout', { parse: 'none' });
-        }
-        finally {
-            this.session = null;
-            void this.notifySession(null);
-        }
-    }
-    /** Namespaces the signed-in user owns. */
-    async getMyNamespaces() {
-        const rows = await this.request('GET', '/api/cloud/me/namespaces');
-        return rows.map((row) => ({
-            namespaceId: String(row.namespace_id ?? row.group_id ?? ''),
-            groupId: String(row.group_id ?? row.namespace_id ?? ''),
-            haStatus: String(row.ha_status ?? 'none'),
-            haEnabledAt: row.ha_enabled_at ?? null,
-            contexts: Array.isArray(row.contexts) ? row.contexts : [],
-            fleetReplicas: row.fleet_replicas,
-        }));
-    }
-    /**
-     * The relays serving one namespace: where to present an intent, and as whom.
-     *
-     * Everything a client needs in order to mint a warrant it can actually
-     * spend. Filter on `canExecute` before signing — a warrant presented to a
-     * relay that does not relay (a `ReadOnlyTee` replica, or a node with no role
-     * and no grant) is refused *after* the author has burned a nonce from its
-     * monotonic sequence on it.
-     */
-    async getNamespaceRelays(namespaceId) {
-        const body = await this.request('GET', `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/relays`);
-        return (body.relays ?? []).map((row) => {
-            const relayUrl = row.relay_url ?? null;
-            const executorAccount = row.executor_account ?? null;
-            const authorshipReady = row.authorship_ready === true;
-            return {
-                peerId: String(row.peer_id ?? ''),
-                relayUrl,
-                executorAccount,
-                nodeKey: row.node_key ??
-                    row.node_public_key ??
-                    null,
-                status: String(row.status ?? ''),
-                authorshipReady,
-                teeRole: teeRoleOf(row),
-                canExecute: canExecuteOf(row, authorshipReady && relayUrl !== null && executorAccount !== null),
-                lastSeenAt: row.last_seen_at ?? null,
-                confirmedAt: row.confirmed_at ?? null,
-                admission: typeof row.admission === 'string' ? row.admission : null,
-                admissionHint: typeof row.admission_hint === 'string' ? row.admission_hint : null,
-                join: joinOf(row),
-            };
-        });
-    }
-    /**
-     * The first relay for `namespaceId` that can actually run an intent, or
-     * `null`.
-     *
-     * "Can actually run one" is several conditions, and a client that checks
-     * fewer gets a refusal it cannot explain: the cloud must know a URL, the
-     * relay must have reported the executor account a warrant has to name, and
-     * the node must relay — which the cloud folds into `canExecute`.
-     */
-    async findExecutingRelay(namespaceId) {
-        const relays = await this.getNamespaceRelays(namespaceId);
-        return pickExecutingRelay(relays);
-    }
-    /**
-     * 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: the cloud has no record of
-     * a node holding the namespace, so there is no hosted admitter.
-     */
-    async getNamespaceRouting(namespaceId) {
-        const body = await this.request('GET', `/api/cloud/namespaces/${pathSegment(namespaceId)}/admitters`, {
-            anonymous: true,
-            headers: await this.routingProof(namespaceId),
-        });
-        return {
-            namespaceId: String(body.namespace_id ?? namespaceId),
-            nodes: (body.admitters ?? []).map((row) => {
-                const account = row.account ?? null;
-                const relayUrl = row.relay_url ?? null;
-                const fresh = row.fresh === true;
-                const authorshipReady = row.authorship_ready === true;
-                return {
-                    peerId: String(row.peer_id ?? ''),
-                    account,
-                    relayUrl,
-                    admitUrl: row.admit_url ?? null,
-                    status: String(row.status ?? ''),
-                    fresh,
-                    canAdmit: row.can_admit === true,
-                    authorshipReady,
-                    teeRole: teeRoleOf(row),
-                    canExecute: canExecuteOf(row, authorshipReady && relayUrl !== null && account !== null && fresh),
-                };
-            }),
-            servable: body.servable === true,
-            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/${pathSegment(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);
-    }
-    /**
-     * 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/${pathSegment(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/${pathSegment(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,
-            executorAccount: accountHexOrNull(row.executor_account),
-            assigned: row.assigned === 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.
-     *
-     * The account-wide view of the same rows {@link getNamespaceRelays} returns
-     * per namespace, keyed by machine — so a UI can answer "what is running for
-     * me?" in one call. `canExecute` folds the three-way precondition, so a
-     * caller does not re-derive it.
-     *
-     * Only the caller's own namespaces appear on each machine. A plan's
-     * `usersPerMachine` is greater than one, so a fleet node routinely serves
-     * several accounts at once.
-     */
-    async getMyMachines() {
-        const body = await this.request('GET', '/api/cloud/me/machines');
-        return (body.machines ?? []).map((row) => {
-            const relayUrl = row.relay_url ?? null;
-            const executorAccount = row.executor_account ?? null;
-            const namespaces = (Array.isArray(row.namespaces) ? row.namespaces : []).map((n) => {
-                const ns = n;
-                return {
-                    namespaceId: String(ns.namespace_id ?? ''),
-                    status: String(ns.status ?? ''),
-                    authorshipReady: ns.authorship_ready === true,
-                    teeRole: teeRoleOf(ns),
-                    fresh: ns.fresh === true,
-                    confirmedAt: ns.confirmed_at ?? null,
-                    lastSeenAt: ns.last_seen_at ?? null,
-                };
-            });
-            return {
-                peerId: String(row.peer_id ?? ''),
-                relayUrl,
-                executorAccount,
-                canExecute: canExecuteOf(row, relayUrl !== null && executorAccount !== null && namespaces.some((n) => n.authorshipReady)),
-                namespaces,
-            };
-        });
-    }
-    /**
-     * Claim a namespace under this account, proving ownership.
-     *
-     * The cloud has no other way to learn a namespace exists — namespaces are
-     * created on a node, and there is deliberately no "create namespace" in the
-     * cloud. `ownershipProof` comes from
-     * `admin.issueNamespaceOwnershipProof(namespaceId, …)` on a node that is a
-     * **direct admin** of that namespace; merod refuses to issue one otherwise.
-     *
-     * Pass merod's response object straight through. The cloud accepts core's
-     * `signerPublicKey`/`signedPayload` casing as well as snake_case, so there is
-     * no re-keying step — and getting that wrong used to surface as a `422`
-     * naming three missing fields. Passing it whole also carries the `founding`
-     * and `credential` merod attaches: the cloud accepts a namespace proof only
-     * from a node of the account that founded the namespace, checked with those
-     * two, and only when that account is linked to this login. A node that
-     * predates them, or an admin that did not found the namespace, gets a `422`.
-     *
-     * Idempotent for the same account. A namespace already claimed by someone
-     * else is a `409`; a replayed proof nonce is a `403`.
-     */
-    async claimNamespace(namespaceId, ownershipProof) {
-        await this.request('POST', '/api/cloud/namespaces/claim', {
-            body: { namespace_id: namespaceId, ownership_proof: ownershipProof },
-        });
-    }
-    /**
-     * Ask the fleet to host a claimed namespace — the step that gets a relay
-     * assigned.
-     *
-     * Carries no proof: {@link claimNamespace} already established ownership,
-     * and this is the separate "now host it" half. Idempotent.
-     *
-     * `admitterAddrs` is where the owner's own node can be dialed — take it from
-     * that node's network status with {@link admitterAddrsFromNetworkStatus}.
-     * The first fleet node placed on a namespace has nobody but the owner to ask
-     * for admission, and without these it can only broadcast and hope the
-     * owner's node — often a laptop behind a relay — hears it. They are a dial
-     * hint, not a grant: the owner's node admits by its own policy. Omit them to
-     * leave whatever the cloud already holds; pass them again when the node's
-     * relay address changes, and they replace the stored ones.
-     *
-     * Not to be confused with {@link enableHA}, which opens the cloud's web flow
-     * in a browser tab for a user to complete by hand. This is the API call.
-     */
-    async enableNamespaceHa(namespaceId, options = {}) {
-        const body = options.admitterAddrs === undefined
-            ? {}
-            : { admitter_addrs: [...options.admitterAddrs] };
-        return this.request('POST', `/api/cloud/namespaces/${pathSegment(namespaceId)}/enable-ha`, { body });
-    }
-    /**
-     * Enable HA for a namespace this ACCOUNT founded through a relay, with the
-     * founder's claim (`signAccountOwnershipClaim`) instead of a node's
-     * ownership proof: a nodeless account holds no node that could issue one.
-     * The login must be linked to that account.
-     */
-    async enableFoundedNamespaceHa(namespaceId, ownershipProof) {
-        return this.request('POST', `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/enable-ha`, { body: { groups: [], ownership_proof: ownershipProof } });
-    }
-    /**
-     * Enable HA for a namespace this account founded, with **no cloud session**.
-     *
-     * The anonymous sibling of {@link enableFoundedNamespaceHa}: it signs the
-     * founder's claim itself ({@link signAccountHaClaim} — no `subject`, its own
-     * audience) and posts it to
-     * `/api/cloud/accounts/{accountId}/namespaces/{namespaceId}/enable-ha`. The
-     * cloud bills the user the account is linked to through the wallet, so the
-     * account must be linked to exactly one:
-     *
-     * - not linked at all → {@link AccountNotLinkedError};
-     * - linked to several → {@link AccountLinkedToSeveralUsersError}.
-     *
-     * A claim that does not verify is a `403` `HTTPError`; quota and the rest
-     * answer as the session route does. Returns the cloud's response body, the
-     * same shape the session route's enable-ha returns.
-     */
-    async enableHaAsAccount(options) {
-        const proof = await signAccountHaClaim({
-            namespaceId: options.namespaceId,
-            accountId: options.accountId,
-            salt: options.salt,
-            credential: options.credential,
-            deviceSecret: options.deviceSecret,
-            signer: options.signer,
-            ttlMs: options.ttlMs,
-            relayUrl: options.relayUrl,
-        });
-        // The path carries the ids as the claim does — lowercase hex — so a caller
-        // that kept them uppercase does not address a different resource.
-        const account = options.accountId.toLowerCase();
-        const namespace = options.namespaceId.toLowerCase();
-        try {
-            return await this.request('POST', `/api/cloud/accounts/${pathSegment(account)}/namespaces/${pathSegment(namespace)}/enable-ha`, { body: { ownership_proof: proof }, anonymous: true });
-        }
-        catch (err) {
-            if (err instanceof HTTPError && ACCOUNT_HA_REFUSALS[err.status]) {
-                const code = conflictCode(err.bodyText);
-                const Typed = ACCOUNT_HA_REFUSALS[err.status].find((t) => t.CODE === code);
-                if (Typed && code) {
-                    throw new Typed(code, err.status, err.statusText, err.url, err.headers, err.bodyText);
-                }
-            }
-            throw err;
-        }
-    }
-    /**
-     * Stop hosting a claimed namespace.
-     *
-     * The fleet's own reconcile loop does the rest: each assigned node notices
-     * the namespace is no longer assigned to it and **self-leaves**, which makes
-     * core evict it and purge its local data and keys. So this is not just a
-     * billing flip.
-     */
-    async disableNamespaceHa(namespaceId) {
-        return this.request('POST', `/api/cloud/namespaces/${pathSegment(namespaceId)}/disable-ha`, { body: {} });
-    }
-    /**
-     * The node assigned to the signed-in user, or `null`.
-     *
-     * @deprecated Use {@link getMyMachines}. This reads the cloud's retired
-     * `NodeAssignment` ledger, which nothing has written since the v1
-     * retirement, so it answers `null` for every namespace-native account —
-     * which reads as "you have no machine" when the truth is "that is no longer
-     * how a machine is assigned".
-     */
-    async getMyNode() {
-        const body = await this.request('GET', '/api/cloud/me/node');
-        return body.node ?? null;
-    }
-    enableHA(options) {
-        const params = new URLSearchParams({
-            group_id: options.groupId,
-            context_id: options.contextId,
-        });
-        if (options.redirectUrl) {
-            params.set('redirect_url', options.redirectUrl);
-        }
-        window.open(`${this.baseUrl}/enable-ha?${params.toString()}`);
-    }
-    disableHA(options) {
-        const params = new URLSearchParams({
-            group_id: options.groupId,
-            context_id: options.contextId,
-        });
-        if (options.redirectUrl) {
-            params.set('redirect_url', options.redirectUrl);
-        }
-        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 root the account root: its 64-hex secret — from
-     *   {@link generateAccountRoot}, a restored recovery phrase, or a desktop app
-     *   or hardware key that already holds one — or a `Signer` over a root this
-     *   process cannot read, which is what a phrase-held browser root is.
-     *
-     * 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(root) {
-        const { signer, publicKey, accountId } = await resolveRoot(root);
-        const { nonce } = await this.getAccountLinkChallenge();
-        return this.submitAccountLink({
-            accountId,
-            rootPublicKey: publicKey,
-            nonce,
-            signature: await signAccountLink({ signer, 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,
-        };
-    }
-    /**
-     * Where to send someone to authorise linking this account, and what to expect
-     * back. Pairs with {@link readAccountLinkCallback} and
-     * {@link linkAccountWithGrant}.
-     *
-     * This exists because a browser app is in a bind: it holds an account root and
-     * can never hold a *first* cloud session, since only Google issues one. So the
-     * person goes to the cloud, where they are signed in, and consents there. What
-     * comes back is a grant — consent to link this one account, spendable only by
-     * whoever can sign with its root.
-     *
-     * @param callbackUrl where the portal sends the person back. Must be an origin
-     *   the cloud allows; unlisted ones are refused when the grant is minted, not
-     *   here. The grant arrives in the URL **fragment**, which browsers do not
-     *   send to servers.
-     *
-     * Static, so it needs no client and no session: there is nothing to
-     * authenticate as yet.
-     */
-    static async accountLinkHandoff(options) {
-        const portal = options.portalUrl.replace(/\/+$/, '');
-        const { callbackUrl, challenge } = await beginLinkState(options.accountId, options.callbackUrl);
-        const query = new URLSearchParams({
-            'link-account': options.accountId,
-            challenge,
-            'callback-url': callbackUrl,
-        });
-        return { url: `${portal}/?${query.toString()}`, accountId: options.accountId };
-    }
-    /**
-     * Read the portal's answer out of a callback URL's fragment.
-     *
-     * Returns `{}` when there is nothing to read, so it is safe to call on every
-     * load — which is how a redirected app finds out it has been sent back.
-     *
-     * A grant is only returned when it answers a handoff this browser began, for the
-     * account that handoff named; anything else comes back as
-     * `error: 'unexpected_callback'`, because the redirect URL can be forwarded.
-     *
-     * @param href defaults to the current location, when there is one.
-     */
-    static readAccountLinkCallback(href) {
-        const source = href ?? (typeof window === 'undefined' ? '' : window.location.href);
-        if (!source)
-            return {};
-        let hash;
-        let search;
-        try {
-            ({ hash, search } = new URL(source));
-        }
-        catch {
-            return {};
-        }
-        const params = new URLSearchParams(hash.replace(/^#/, ''));
-        const grant = params.get('grant');
-        const accountId = params.get('account');
-        const error = params.get('error');
-        const out = {};
-        if (error)
-            takeLinkVerifier(search, null);
-        if (grant) {
-            const verifier = takeLinkVerifier(search, accountId);
-            const claims = linkGrantClaims(grant);
-            if (!verifier || claims?.account !== accountId)
-                return { error: 'unexpected_callback' };
-            out.grant = grant;
-            out.login = claims.login;
-            out.verifier = verifier;
-        }
-        if (accountId)
-            out.accountId = accountId;
-        if (error)
-            out.error = error;
-        return out;
-    }
-    /**
-     * Spend a link grant: sign it with the account root and post the pair.
-     *
-     * Anonymous, and it has to be — the app doing this holds no cloud session,
-     * which is the whole reason the grant exists. The grant carries the consenting
-     * login sealed inside it, so nothing here names one; a caller-supplied email
-     * would be a field to lie in.
-     *
-     * The signature is an ordinary account-link signature with the grant as the
-     * nonce, so the same {@link signAccountLink} every other link path uses signs
-     * this one. The grant is bound to the verifier of the browser that asked for
-     * it, and is refused here, before the root signs, unless it carries that
-     * verifier's challenge and names this root's account.
-     *
-     * A `403` means the grant was bad, expired, already spent, or signed by a key
-     * that names a different account; `409` that the account belongs to another
-     * login; `402` that the plan is full.
-     */
-    async linkAccountWithGrant(options) {
-        if (typeof options.verifier !== 'string' || !VERIFIER_HEX.test(options.verifier)) {
-            throw new Error('no verifier for this grant - start the link again from this browser');
-        }
-        const claims = linkGrantClaims(options.grant);
-        if (claims?.challenge !== (await linkChallenge(options.verifier))) {
-            throw new Error('this grant was not issued to this link request - start the link again from this browser');
-        }
-        const { signer, publicKey, accountId } = await resolveRootPair(options.rootSecret, options.signer);
-        if (claims.account !== accountId) {
-            throw new Error(`this grant is for account ${claims.account}, but the root here derives ` +
-                `${accountId} - it was minted for a different account`);
-        }
-        const body = await this.request('POST', '/api/cloud/accounts/link', {
-            body: {
-                grant: options.grant,
-                verifier: options.verifier,
-                root_public_key: publicKey,
-                signature: await signAccountLink({
-                    signer,
-                    nonce: options.grant,
-                }),
-            },
-            anonymous: true,
-        });
-        return {
-            accountId: String(body.account_id ?? 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,
-            expiresAt: body.expires_at,
-            user: body.user,
-        };
-        void this.notifySession(this.session);
-        return this.session;
-    }
-    async notifySession(session) {
-        try {
-            await this.onSession?.(session);
-        }
-        catch {
-            // A failing persistence callback must not mask the call's own result.
-        }
-    }
-    async request(method, path, options = {}) {
-        if (!options.anonymous && !this.session) {
-            throw new Error('Not signed in to Calimero Cloud: call signInWithGoogle() or construct the client with a sessionToken');
-        }
-        // 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) {
-            headers.Authorization = `Bearer ${this.session.sessionToken}`;
-        }
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-        let response;
-        try {
-            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-                method,
-                headers,
-                body: options.body === undefined ? undefined : JSON.stringify(options.body),
-                signal: controller.signal,
-            });
-        }
-        catch (err) {
-            // Same shape the node clients use for a transport failure: an `HTTPError`
-            // with `status: 0`, so a caller has one error type to handle rather than
-            // one per layer.
-            throw new HTTPError(0, err instanceof Error ? err.name : 'NetworkError', `${this.baseUrl}${path}`, new Headers(), err instanceof Error ? err.message : String(err));
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        this.adoptRollingRefresh(response);
-        if (!response.ok) {
-            const bodyText = await response.text().catch(() => undefined);
-            throw new HTTPError(response.status, response.statusText, `${this.baseUrl}${path}`, response.headers, bodyText);
-        }
-        if (options.parse === 'none' || response.status === 204)
-            return undefined;
-        return (await response.json());
-    }
-    /**
-     * Adopt a session token the server refreshed mid-request.
-     *
-     * MDMA rotates the token on activity and returns the replacement in a
-     * response header rather than making the client ask. Ignoring it costs
-     * nothing immediately and then logs the user out a week later, which is the
-     * kind of bug that is impossible to reproduce in a short session.
-     *
-     * The user identity is carried over: the header holds only a token, and the
-     * refresh is the same logical session as the sign-in that named the user.
-     */
-    adoptRollingRefresh(response) {
-        const token = response.headers.get(REFRESH_HEADER);
-        if (!token || !this.session)
-            return;
-        const expiresRaw = response.headers.get(REFRESH_EXPIRES_HEADER);
-        const expiresAt = Number(expiresRaw);
-        this.session = {
-            sessionToken: token,
-            expiresAt: Number.isFinite(expiresAt) && expiresAt > 0 ? expiresAt : this.session.expiresAt,
-            user: this.session.user,
-        };
-        void this.notifySession(this.session);
-    }
-}
-/**
- * The addresses a fleet node can dial to ask this node for admission, from the
- * node's `GET /admin-api/network/status` (see `AdminApiClient`).
- *
- * Its `externalAddrs`, each made to end in `/p2p/<localPeerId>`: that is the
- * shape core dials, and an external address is usually reported without it. A
- * relay-circuit address already contains `/p2p/` — the relay's — so the test is
- * whether it ends in this node's own id, not whether it names a peer at all.
- * Anything that is not a multiaddr is dropped. Empty when the status names no
- * peer id or no external address, which is an honest "not dialable yet".
- */
-export function admitterAddrsFromNetworkStatus(status) {
-    const record = status && typeof status === 'object'
-        ? (status.data ?? status)
-        : undefined;
-    if (!record || typeof record !== 'object')
-        return [];
-    const peerId = record.localPeerId;
-    const external = record.externalAddrs;
-    if (typeof peerId !== 'string' || !peerId || !Array.isArray(external))
-        return [];
-    const suffix = `/p2p/${peerId}`;
-    const out = [];
-    for (const entry of external) {
-        if (typeof entry !== 'string')
-            continue;
-        const addr = entry.trim();
-        if (!addr.startsWith('/'))
-            continue;
-        const dialable = addr.endsWith(suffix) ? addr : `${addr}${suffix}`;
-        if (!out.includes(dialable))
-            out.push(dialable);
-    }
-    return out;
-}