@calimero-network/mero-js 18.1.1 → 18.3.0

package/README.md

@@ -89,6 +89,53 @@ Every failure surfaces as a typed error:
 you only see a `401` if the refresh itself fails. Full details in the
 [error model reference](https://calimero-network.github.io/mero-js/reference/error-model/).
 
+## Writing without a node
+
+The quickstart above assumes you have a node and a credential on it. A browser
+tab, a phone, or an agent has neither — the runtime cannot compile the app's WASM
+against materialized state, and never received the scope key that seals the
+deltas. So there is a second connection shape: sign in to **Calimero Cloud**, and
+write through an attested TEE **relay** using
+[delegated execution](https://calimero-network.github.io/core/protocol/delegated-authorship/).
+
+You sign a *warrant* locally — your consent for one specific intent, once — the
+relay runs the method as **your** principal, and the resulting change is
+attributed to your account and device. Your signing key never leaves the
+process; only signatures do.
+
+```typescript
+import { connectCloud } from '@calimero-network/mero-js';
+
+const connection = await connectCloud({
+  googleIdToken,        // or a stored sessionToken
+  authorAccount,        // your account, hex
+  authorProof,          // your AccountProof<DeviceCert>, hex borsh
+  deviceSecret,         // your device's ed25519 seed, hex — never transmitted
+});
+
+const { rootHash, returns } = await connection.execute(contextId, 'set', {
+  key: 'greeting',
+  value: 'hello',
+});
+```
+
+`connectCloud` replaces the **node-URL prompt**, not the authentication: it asks
+the cloud which namespaces the account owns and which relay serves them, then
+builds the relay client. `sdk.cloud` exposes the same cloud API from an existing
+`MeroJs` instance for apps that have both a node and a cloud account, and
+`RelayClient` is available directly for a relay you were told about out of band.
+
+One precondition is not yours to satisfy: an admin of the namespace must grant
+the relay `CAN_AUTHOR_ON_BEHALF` (core implies it from nothing — not from
+membership, not from admin). Until then `connectCloud` throws naming the account
+that needs the grant, and `relay.describe(contextId)` reports
+`canAuthorOnBehalf: false` so a UI can say so rather than failing a write.
+
+See the [cloud client](https://calimero-network.github.io/mero-js/reference/cloud/),
+[relay client](https://calimero-network.github.io/mero-js/reference/relay/) and
+[connectCloud](https://calimero-network.github.io/mero-js/reference/connect-cloud/)
+references — including why a warrant nonce must never restart.
+
 ## Lower-level HTTP client
 
 If you need raw HTTP against a node (without the `MeroJs` facade), the SDK

package/dist/admin-api/admin-client.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from '../http-client/index.js';
-import type { HealthStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, IssueOwnershipProofRequest, IssueNamespaceOwnershipProofRequest, IssueOwnershipProofResponseData, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
+import type { HealthStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, IssueOwnershipProofRequest, IssueNamespaceOwnershipProofRequest, IssueOwnershipProofResponseData, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, IntentRelayInfo, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
 /**
  * Compare two version strings by SemVer 2.0 precedence, ascending: negative if
  * `a < b`, positive if `a > b`, `0` if equal. Build metadata (`+...`) is stripped
@@ -62,6 +62,7 @@ export declare class AdminApiClient {
     joinContext(contextId: string): Promise<JoinContextResponseData>;
     getContextGroup(contextId: string): Promise<ContextGroupResponseData>;
     getContextStorage(contextId: string): Promise<ContextStorageResponseData>;
+    /** Sync one context, or every context when `contextId` is omitted. */
     syncContext(contextId?: string): Promise<void>;
     /**
      * Kick off a full state re-pull for a context (operator recovery for a
@@ -153,6 +154,26 @@ export declare class AdminApiClient {
      * {@link PerformIntentRequest.warrant}.
      */
     performIntent(contextId: string, request: PerformIntentRequest): Promise<PerformIntentResponseData>;
+    /**
+     * Ask what this node can do for a member in `contextId`, before they sign
+     * anything.
+     *
+     * The two facts {@link performIntent} needs and a client cannot derive: whose
+     * account goes in the warrant's `executor`, and whether this node holds
+     * `CAN_AUTHOR_ON_BEHALF` on the owning group. `canAuthorOnBehalf: false` comes
+     * back as an answer rather than an error — it is the default state of every
+     * context — so a caller can say "an admin of `groupId` must grant it to
+     * `executorAccount`" instead of presenting a warrant that will be refused
+     * after the author has spent a nonce on it.
+     *
+     * `404` means the context belongs to no group, or this node holds no account
+     * yet; either way it can be named as no warrant's executor.
+     *
+     * For a caller with no credential on the node at all — a browser tab holding
+     * one signing key — use `RelayClient`, which reads this same route on a node
+     * run as a relay.
+     */
+    getIntentRelay(contextId: string): Promise<IntentRelayInfo>;
     listNamespacesForApplication(applicationId: string): Promise<ListNamespacesResponseData>;
     createNamespace(request: CreateNamespaceRequest): Promise<CreateNamespaceResponseData>;
     deleteNamespace(namespaceId: string): Promise<DeleteNamespaceResponseData>;

package/dist/admin-api/admin-client.js

@@ -217,8 +217,12 @@ export class AdminApiClient {
     async getContextStorage(contextId) {
         return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/storage`));
     }
+    /** Sync one context, or every context when `contextId` is omitted. */
     async syncContext(contextId) {
-        await this.httpClient.post(`/admin-api/contexts/sync/${contextId ?? ''}`, {});
+        // Sync-all is `/contexts/sync` with no trailing slash - core routes the two
+        // spellings separately and 404s the trailing one.
+        const path = contextId ? `/admin-api/contexts/sync/${contextId}` : '/admin-api/contexts/sync';
+        await this.httpClient.post(path, {});
     }
     /**
      * Kick off a full state re-pull for a context (operator recovery for a
@@ -406,6 +410,28 @@ export class AdminApiClient {
     async performIntent(contextId, request) {
         return unwrap(await this.httpClient.post(`/admin-api/contexts/${contextId}/intents`, request));
     }
+    /**
+     * Ask what this node can do for a member in `contextId`, before they sign
+     * anything.
+     *
+     * The two facts {@link performIntent} needs and a client cannot derive: whose
+     * account goes in the warrant's `executor`, and whether this node holds
+     * `CAN_AUTHOR_ON_BEHALF` on the owning group. `canAuthorOnBehalf: false` comes
+     * back as an answer rather than an error — it is the default state of every
+     * context — so a caller can say "an admin of `groupId` must grant it to
+     * `executorAccount`" instead of presenting a warrant that will be refused
+     * after the author has spent a nonce on it.
+     *
+     * `404` means the context belongs to no group, or this node holds no account
+     * yet; either way it can be named as no warrant's executor.
+     *
+     * For a caller with no credential on the node at all — a browser tab holding
+     * one signing key — use `RelayClient`, which reads this same route on a node
+     * run as a relay.
+     */
+    async getIntentRelay(contextId) {
+        return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/intents`));
+    }
     async listNamespacesForApplication(applicationId) {
         return unwrap(await this.httpClient.get(`/admin-api/namespaces/for-application/${applicationId}`));
     }

package/dist/admin-api/admin-types.d.ts

@@ -401,6 +401,40 @@ export interface PerformIntentResponseData {
     /** The method's own return value, if it had one. */
     returns: unknown | null;
 }
+/**
+ * What a node says about running intents in one context — read before minting a
+ * warrant, not after being refused one.
+ *
+ * Every input to a warrant is something the author already holds except two:
+ * whose name goes in `executor`, and whether that node may act here at all. Both
+ * belong to the node, so both are answered here, on the path the intent will be
+ * presented to.
+ *
+ * Reading it first is what lets a client fail before signing. A warrant spends a
+ * nonce from a monotonic per-device sequence, and one naming the wrong executor
+ * is unspendable — the number is gone and the write never happened.
+ */
+export interface IntentRelayInfo {
+    /**
+     * The account a warrant for this node must name as its `executor`, 64 hex.
+     *
+     * An account, not the node's signing key: one of its processes re-keying must
+     * not void warrants already issued to it.
+     */
+    executorAccount: string;
+    /**
+     * Whether this node holds `CAN_AUTHOR_ON_BEHALF` on the group owning the
+     * context.
+     *
+     * `false` is an answer, not an error, and it is the *default* state of every
+     * context — the capability is implied by neither membership nor admin, and is
+     * not propagated by the subgroup cascade. A client reads it to tell "ask an
+     * admin of `groupId`" from "retry later".
+     */
+    canAuthorOnBehalf: boolean;
+    /** The group whose admin must grant that capability, 64 hex. */
+    groupId: string;
+}
 export interface NodeIdentity {
     /**
      * The account this node writes as, 64 hex characters. This — not
@@ -908,9 +942,15 @@ export interface MemberMigrationReport {
     migrationFailed?: MigrationFailureReason;
 }
 export interface MemberMigrationStatusEntry {
+    /** The reporting device's signing KEY, bs58. One account with two devices
+     * appears as two rows: the cohort is replicas, not people. */
     peer: string;
-    /** Freshest reported facts, or `null` when the member's state is `unknown`. */
-    report: MemberMigrationReport | null;
+    /** The ACCOUNT `peer` speaks for, 64 hex - join it to `listGroupMembers` to
+     * name a person. Absent from nodes predating the field. */
+    account?: string;
+    /** Freshest reported facts. Omitted (not `null`) when the member's state is
+     * `unknown`, so test falsiness rather than `=== null`. */
+    report?: MemberMigrationReport | null;
     state: MemberMigrationState;
 }
 export interface MigrationStatusRollup {

package/dist/capabilities.d.ts

@@ -1,8 +1,8 @@
 /**
  * Capability bits as defined by core's `MemberCapabilities`.
  *
- * The per-member value is a u32 bitmask. Core currently assigns bits 0..=8
- * (the entries below); bits 9 and above are unassigned — do not repurpose
+ * The per-member value is a u32 bitmask. Core currently assigns bits 0..=9
+ * (the entries below); bits 10 and above are unassigned — do not repurpose
  * them for application data, as a future core release may claim them.
  */
 export declare const CAPABILITIES: {
@@ -15,6 +15,18 @@ export declare const CAPABILITIES: {
     readonly CAN_DELETE_SUBGROUP: number;
     readonly CAN_MANAGE_VISIBILITY: number;
     readonly CAN_MANAGE_METADATA: number;
+    /**
+     * Publish writes attributed to ANOTHER member, under a warrant that member
+     * signed — the grant delegated execution runs on.
+     *
+     * Implied by nothing: not by membership, not by admin, and not propagated by
+     * the subgroup-admit cascade. So every group is authorship-closed until an
+     * admin sets this bit, and a relay without it is refused at
+     * `performIntent` before anything executes. That is why it is worth naming
+     * here rather than leaving callers to write `1 << 9`: a client granting it
+     * has to be able to say what it is granting.
+     */
+    readonly CAN_AUTHOR_ON_BEHALF: number;
 };
 export type CapabilityName = keyof typeof CAPABILITIES;
 export type CapabilityBit = (typeof CAPABILITIES)[CapabilityName];

package/dist/capabilities.js

@@ -1,14 +1,14 @@
 // Member capability bitmask constants — mirrors core's `MemberCapabilities`
 // (crates/context/config/src/lib.rs). The value stored per-member is a u32
-// bitmask. Core currently assigns bits 0..=8; bits 9 and above are unassigned
+// bitmask. Core currently assigns bits 0..=9; bits 10 and above are unassigned
 // and may be claimed by future core versions, so an application MUST NOT
 // assume any particular bit is safe for its own use unless core documents it
 // as reserved for applications.
 /**
  * Capability bits as defined by core's `MemberCapabilities`.
  *
- * The per-member value is a u32 bitmask. Core currently assigns bits 0..=8
- * (the entries below); bits 9 and above are unassigned — do not repurpose
+ * The per-member value is a u32 bitmask. Core currently assigns bits 0..=9
+ * (the entries below); bits 10 and above are unassigned — do not repurpose
  * them for application data, as a future core release may claim them.
  */
 export const CAPABILITIES = {
@@ -21,6 +21,18 @@ export const CAPABILITIES = {
     CAN_DELETE_SUBGROUP: 1 << 6,
     CAN_MANAGE_VISIBILITY: 1 << 7,
     CAN_MANAGE_METADATA: 1 << 8,
+    /**
+     * Publish writes attributed to ANOTHER member, under a warrant that member
+     * signed — the grant delegated execution runs on.
+     *
+     * Implied by nothing: not by membership, not by admin, and not propagated by
+     * the subgroup-admit cascade. So every group is authorship-closed until an
+     * admin sets this bit, and a relay without it is refused at
+     * `performIntent` before anything executes. That is why it is worth naming
+     * here rather than leaving callers to write `1 << 9`: a client granting it
+     * has to be able to say what it is granting.
+     */
+    CAN_AUTHOR_ON_BEHALF: 1 << 9,
 };
 /**
  * Returns true if `mask` has every bit of `cap` set. Both operands are

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

@@ -1,5 +1,138 @@
+/**
+ * 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.
+ */
 export interface CloudClientConfig {
     cloudBaseUrl?: string;
+    /**
+     * An MDMA session token to start out authenticated with — from a previous
+     * {@link CloudClient.signInWithGoogle}, persisted by the app.
+     *
+     * Sessions are 7-day JWTs with a rolling refresh, so a stored one is usually
+     * still live and re-running the Google flow on every launch is avoidable.
+     */
+    sessionToken?: string;
+    /**
+     * Called whenever the session token changes — a sign-in, an explicit
+     * refresh, or a rolling refresh the server performed mid-request. Persist it
+     * here; errors thrown are swallowed so a storage failure cannot mask the
+     * response the caller is waiting for.
+     */
+    onSession?: (session: CloudSession | null) => void | Promise<void>;
+    /** Injected for tests and non-browser runtimes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Per-request timeout. Defaults to 10s, as the node clients do. */
+    timeoutMs?: number;
+}
+/** Who is signed in, and until when. */
+export interface CloudSession {
+    sessionToken: string;
+    /** Epoch **seconds**, as MDMA reports it — not milliseconds. */
+    expiresAt: number;
+    user: {
+        email: string;
+        name?: string;
+        picture?: string;
+    };
+}
+/** One namespace the signed-in user owns. */
+export interface CloudNamespace {
+    namespaceId: string;
+    /** Always equal to `namespaceId`; MDMA keeps it for wire compatibility. */
+    groupId: string;
+    /** `'enabled' | 'disabled' | 'none'` — `'none'` means HA was never enabled. */
+    haStatus: string;
+    haEnabledAt?: string | null;
+    contexts: string[];
+    fleetReplicas?: {
+        current?: number;
+        limit?: number;
+    } | unknown;
+}
+/**
+ * One attested node the cloud has assigned to a namespace, described as a
+ * relay.
+ *
+ * `authorshipReady` is the field that decides whether a write can happen, and
+ * it is reported rather than assumed because it is not the cloud's to grant:
+ * `CAN_AUTHOR_ON_BEHALF` is a governance capability, set by an admin of the
+ * namespace, and the cloud only relays what the node observed. A relay that is
+ * `active` with `authorshipReady: false` is a healthy node waiting for a grant.
+ */
+export interface CloudRelay {
+    peerId: string;
+    /** Base URL to present intents to, or `null` when the cloud knows none yet. */
+    relayUrl: string | null;
+    /** The account a warrant for this relay must name as its `executor`, hex. */
+    executorAccount: string | null;
+    /** `'assigned'` (admitted pending confirm) or `'active'`. */
+    status: string;
+    /** Whether this relay holds `CAN_AUTHOR_ON_BEHALF` on the namespace. */
+    authorshipReady: boolean;
+    lastSeenAt?: string | null;
+    confirmedAt?: string | null;
+}
+/** One namespace of the caller's that a machine is serving. */
+export interface CloudMachineNamespace {
+    namespaceId: string;
+    /** `'assigned'` (admitted pending confirm) or `'active'`. */
+    status: string;
+    /** Whether the machine holds `CAN_AUTHOR_ON_BEHALF` on this namespace. */
+    authorshipReady: boolean;
+    /**
+     * Whether the machine's heartbeat for this namespace is recent.
+     *
+     * The same freshness rule the per-plan fleet cap uses, so a replica that
+     * stopped polling reads as stale here rather than continuing to look
+     * healthy — otherwise "my writes stopped working" has no visible cause.
+     */
+    fresh: boolean;
+    confirmedAt?: string | null;
+    lastSeenAt?: string | null;
+}
+/**
+ * One attested machine serving this account.
+ *
+ * A narrow view on purpose: the zone, machine type, instance name, public IP
+ * and KMS ids are operator data with no client use, and a cloud user is not an
+ * operator.
+ */
+export interface CloudMachine {
+    peerId: string;
+    relayUrl: string | null;
+    executorAccount: string | null;
+    /**
+     * Whether this machine can write for the caller *somewhere* — a URL, an
+     * executor account, and the grant on at least one namespace.
+     *
+     * Folded here so a client does not re-derive the three-way precondition and
+     * get a refusal it cannot explain.
+     */
+    canExecute: boolean;
+    /** Only the caller's own namespaces, even on a machine shared with others. */
+    namespaces: CloudMachineNamespace[];
 }
 export interface EnableHAOptions {
     groupId: string;
@@ -13,7 +146,138 @@ export interface DisableHAOptions {
 }
 export declare class CloudClient {
     private baseUrl;
+    private session;
+    private readonly onSession?;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
     constructor(config?: CloudClientConfig);
+    /** The current session, or `null` when nobody is signed in. */
+    getSession(): CloudSession | null;
+    /** Whether a session token is held. Says nothing about the server agreeing. */
+    isSignedIn(): boolean;
+    /**
+     * 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.
+     */
+    signInWithGoogle(idToken: string): Promise<CloudSession>;
+    /**
+     * 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.
+     */
+    refreshSession(): Promise<CloudSession>;
+    /**
+     * 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.
+     */
+    signOut(): Promise<void>;
+    /** Namespaces the signed-in user owns. */
+    getMyNamespaces(): Promise<CloudNamespace[]>;
+    /**
+     * 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 `authorshipReady` before signing — a warrant presented to
+     * a relay with no grant is refused *after* the author has burned a nonce from
+     * its monotonic sequence on it.
+     */
+    getNamespaceRelays(namespaceId: string): Promise<CloudRelay[]>;
+    /**
+     * The first relay for `namespaceId` that can actually run an intent, or
+     * `null`.
+     *
+     * "Can actually run one" is three 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 grant
+     * must be in place.
+     */
+    findExecutingRelay(namespaceId: string): Promise<CloudRelay | 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.
+     */
+    getMyMachines(): Promise<CloudMachine[]>;
+    /**
+     * 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.
+     *
+     * Idempotent for the same account. A namespace already claimed by someone
+     * else is a `409`; a replayed proof nonce is a `403`.
+     */
+    claimNamespace(namespaceId: string, ownershipProof: unknown): Promise<void>;
+    /**
+     * Ask the fleet to host a claimed namespace — the step that gets a relay
+     * assigned.
+     *
+     * Takes no body: {@link claimNamespace} already established ownership, and
+     * this is the separate "now host it" half. Idempotent.
+     *
+     * 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.
+     */
+    enableNamespaceHa(namespaceId: string): Promise<unknown>;
+    /**
+     * 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.
+     */
+    disableNamespaceHa(namespaceId: string): Promise<unknown>;
+    /**
+     * 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".
+     */
+    getMyNode(): Promise<Record<string, unknown> | null>;
     enableHA(options: EnableHAOptions): void;
     disableHA(options: DisableHAOptions): void;
+    /** Record a freshly-issued session and tell the app to persist it. */
+    private adoptSession;
+    private notifySession;
+    private request;
+    /**
+     * 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.
+     */
+    private adoptRollingRefresh;
 }