@calimero-network/mero-js 19.11.0 → 19.13.0

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, BlobReadOptions, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateDeviceAliasRequest, 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, RescopeDeviceRequest, RescopeDeviceResponseData, 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';
+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, BlobReadOptions, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateDeviceAliasRequest, 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, RescopeDeviceRequest, RescopeDeviceResponseData, LabelDeviceRequest, LabelDeviceResponseData, 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
@@ -280,6 +280,13 @@ export declare class AdminApiClient {
      * device need not be online.
      */
     rescopeAccountDevice(deviceId: string, request: RescopeDeviceRequest): Promise<RescopeDeviceResponseData>;
+    /**
+     * Name a device of this account, for a listing to render.
+     *
+     * Run on the node holding the account root to name any device; a paired
+     * node is accepted only for that device's own id.
+     */
+    labelAccountDevice(deviceId: string, request: LabelDeviceRequest): Promise<LabelDeviceResponseData>;
     /**
      * Every device of this account, as this node sees them - its own included.
      *

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

@@ -597,6 +597,15 @@ export class AdminApiClient {
     async rescopeAccountDevice(deviceId, request) {
         return unwrap(await this.httpClient.put(`/admin-api/account/devices/${encodeURIComponent(deviceId)}/scope`, request));
     }
+    /**
+     * Name a device of this account, for a listing to render.
+     *
+     * Run on the node holding the account root to name any device; a paired
+     * node is accepted only for that device's own id.
+     */
+    async labelAccountDevice(deviceId, request) {
+        return unwrap(await this.httpClient.put(`/admin-api/account/devices/${encodeURIComponent(deviceId)}/label`, request));
+    }
     /**
      * Every device of this account, as this node sees them - its own included.
      *

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

@@ -530,6 +530,18 @@ export interface NodeIdentity {
      * a root nor has paired with the id; absent on an old node.
      */
     accountNamespaceId?: string | null;
+    /**
+     * The account that withdrew this node's device, absent on a node no
+     * revocation has reached.
+     */
+    revokedFrom?: RevokedFromEntry;
+}
+/** Which account withdrew this node's device, and which device it was. */
+export interface RevokedFromEntry {
+    /** The account the device spoke for, 64 hex characters. */
+    accountId: string;
+    /** The device that was withdrawn, 64 hex characters. */
+    deviceId: string;
 }
 /**
  * @deprecated Use {@link AdminApiClient.getNodeIdentity} instead. Nothing here
@@ -923,6 +935,33 @@ export interface AccountDeviceEntry {
      * hex characters each. Empty for a certified device not yet bound anywhere.
      */
     namespaces: string[];
+    /**
+     * The replicated name the account gave this device, absent while it has
+     * none. Every device of the account reads the same one.
+     */
+    label?: string;
+}
+/**
+ * Name a device of this account, for a listing to render.
+ *
+ * Run on the node holding the account root to name any device; a paired node
+ * is accepted only for that device's own id.
+ */
+export interface LabelDeviceRequest {
+    /** Trimmed, non-empty, bounded and free of control characters. */
+    label: string;
+}
+/**
+ * The name that was published, and the epoch that orders it against a rename
+ * another device of the account made at the same time.
+ */
+export interface LabelDeviceResponseData {
+    /** The account the device speaks for, 64 hex characters. */
+    accountId: string;
+    /** The device that was named, 64 hex characters. */
+    deviceId: string;
+    label: string;
+    labelEpoch: number;
 }
 /**
  * One application this account speaks in, derived from the namespaces this node

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

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

package/dist/cloud/cloud-client.js

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

package/dist/cloud/index.d.ts

@@ -1,6 +1,6 @@
 export { CloudClient } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
+export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudAccountRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
 export { connectCloud } from './connect.js';
 export type { ConnectCloudOptions, CloudConnection } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
-export type { RoutingCredential, RoutingChallenge, RoutingProofHeaders, } from './routing-proof.js';
+export type { RoutingCredential, DiscoveryChallenge, RoutingChallenge, RoutingProofHeaders, } from './routing-proof.js';

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

@@ -61,6 +61,23 @@ export interface RoutingChallenge {
     /** Epoch **milliseconds**, as MDMA reports it. Nonces live about two minutes. */
     expiresAtMs: number;
 }
+/**
+ * A challenge bound to an ACCOUNT rather than a namespace, for asking which
+ * relays serve that account.
+ *
+ * Separate from {@link RoutingChallenge} because the binding is the security
+ * property, not a field name: MDMA seals the account into this one and the
+ * namespace into that one, and refuses each at the other's route. Keeping the
+ * TypeScript types distinct is what stops a caller passing the wrong one and
+ * learning about it as a 403.
+ */
+export interface DiscoveryChallenge {
+    accountId: string;
+    /** Opaque and sealed — the client neither parses nor constructs this. */
+    nonce: string;
+    /** Epoch **milliseconds**, as MDMA reports it. Nonces live about two minutes. */
+    expiresAtMs: number;
+}
 /**
  * The three header values a proven routing read carries.
  *
@@ -88,5 +105,9 @@ export declare function signRoutingChallenge(nonce: string, deviceSecret: string
  * Separated from the request so a caller that fetches its own challenge — a
  * test, or a client batching several reads against one nonce — can use the same
  * encoding rather than a second spelling of it.
+ *
+ * Takes either challenge kind: only the nonce is signed and both are signed
+ * over the same domain, so one encoder serves both. What separates them is what
+ * MDMA sealed inside, which is checked server-side.
  */
-export declare function routingProofHeaders(challenge: RoutingChallenge, credential: RoutingCredential): Promise<RoutingProofHeaders>;
+export declare function routingProofHeaders(challenge: RoutingChallenge | DiscoveryChallenge, credential: RoutingCredential): Promise<RoutingProofHeaders>;

package/dist/cloud/routing-proof.js

@@ -69,6 +69,10 @@ export async function signRoutingChallenge(nonce, deviceSecret) {
  * Separated from the request so a caller that fetches its own challenge — a
  * test, or a client batching several reads against one nonce — can use the same
  * encoding rather than a second spelling of it.
+ *
+ * Takes either challenge kind: only the nonce is signed and both are signed
+ * over the same domain, so one encoder serves both. What separates them is what
+ * MDMA sealed inside, which is checked server-side.
  */
 export async function routingProofHeaders(challenge, credential) {
     return {