@calimero-network/mero-js 24.0.0 → 24.1.1

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

@@ -155,6 +155,54 @@ export interface CloudRelay {
     canExecute: boolean;
     lastSeenAt?: string | null;
     confirmedAt?: string | null;
+    /**
+     * How far along this relay's admission is, as the cloud judges it:
+     * `'confirmed'` (in), `'pending'` (trying), `'refused'` (alive and turned
+     * away), `'absent'` (stopped talking before getting in). `null` from a cloud
+     * that predates the field. A string, not a closed union, so a verdict the
+     * cloud adds later is passed through rather than dropped.
+     */
+    admission: string | null;
+    /** The cloud's one-line explanation of `admission`, for a person; `null` when none. */
+    admissionHint: string | null;
+    /**
+     * What the relay itself reported about its latest attempt to join, reasons
+     * included — or `null` when it has reported nothing (an older fleet node or
+     * cloud, or a relay assigned since its last report).
+     */
+    join: CloudRelayJoin | null;
+}
+/**
+ * A fleet node's own account of its latest attempt to join a namespace.
+ *
+ * A refusal happens peer to peer, between the node and the namespace's
+ * admitters, so this is the only place a client learns WHY a relay is stuck:
+ * the node forwards what each admitter it asked directly answered.
+ */
+export interface CloudRelayJoin {
+    /**
+     * `'admitted'` (in, or an admitter said yes and the key is on its way),
+     * `'refused'` (every admitter asked declined; see `refusals`), `'waiting'`
+     * (nobody answered directly yet), or `'error'` (the attempt itself failed;
+     * see `error`). Passed through as sent.
+     */
+    state: string;
+    /** Consecutive attempts without admission, as the node counts them. */
+    attempts: number;
+    /**
+     * Each directly-asked admitter that declined: its libp2p peer id and its
+     * reason, verbatim. Text to show a person, never to parse — the most useful
+     * one is "was removed from group … and cannot rejoin; an admin must re-add
+     * them", which the namespace owner can fix by re-adding the node.
+     */
+    refusals: Array<{
+        peer: string;
+        reason: string;
+    }>;
+    /** Why the attempt itself failed, when `state` is `'error'`. */
+    error: string | null;
+    /** When the node reported this, ISO 8601 (UTC, no offset), or `null`. */
+    reportedAt: string | null;
 }
 /**
  * One node serving a namespace, as a caller with no cloud account sees it.

package/dist/cloud/cloud-client.js

@@ -66,6 +66,27 @@ function teeRoleOf(row) {
 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,
+    };
+}
 const ACCOUNT_HEX = /^[0-9a-f]{64}$/;
 function accountHexOrNull(value) {
     return typeof value === 'string' && ACCOUNT_HEX.test(value) ? value : null;
@@ -349,6 +370,9 @@ export class CloudClient {
                 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),
             };
         });
     }

package/dist/cloud/index.d.ts

@@ -1,5 +1,5 @@
 export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } 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, EnableHaAsAccountOptions, } from './cloud-client.js';
+export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudRelayJoin, CloudAccountRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, EnableHaAsAccountOptions, } from './cloud-client.js';
 export { connectCloud, connectCloudWithAccount } from './connect.js';
 export type { ConnectCloudOptions, ConnectCloudWithAccountOptions, CloudConnection, } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';

package/dist/device-cert/device-cert.d.ts

@@ -46,11 +46,12 @@ export interface DeviceCertInput {
     deviceEpoch: number;
 }
 /**
- * Mint a device id: `H(DEVICE_ID_DOMAIN, account ‖ nonce)`.
+ * Mint a device id: `nonce ‖ H(DEVICE_ID_DOMAIN, account ‖ nonce)[..16]`.
  *
  * Derived from the account and a fresh nonce rather than from the device's keys,
- * so rotating a keypair keeps the replica identity — and with it the counter
- * slots and HLC lineage — intact.
+ * so rotating a keypair keeps the replica identity - and with it the counter
+ * slots and HLC lineage - intact. The hash half binds the id to its account:
+ * core refuses a certificate naming an id minted for another account.
  */
 export declare function mintDeviceId(account: string, nonce: Uint8Array): Promise<string>;
 /**

package/dist/device-cert/device-cert.js

@@ -34,18 +34,20 @@ export const ACCOUNT_GENESIS_VERSION = 2;
 /** Byte length of an `AccountProof<DeviceCert>` with an empty handoff chain. */
 const ACCOUNT_PROOF_BYTES = 237;
 /**
- * Mint a device id: `H(DEVICE_ID_DOMAIN, account ‖ nonce)`.
+ * Mint a device id: `nonce ‖ H(DEVICE_ID_DOMAIN, account ‖ nonce)[..16]`.
  *
  * Derived from the account and a fresh nonce rather than from the device's keys,
- * so rotating a keypair keeps the replica identity — and with it the counter
- * slots and HLC lineage — intact.
+ * so rotating a keypair keeps the replica identity - and with it the counter
+ * slots and HLC lineage - intact. The hash half binds the id to its account:
+ * core refuses a certificate naming an id minted for another account.
  */
 export async function mintDeviceId(account, nonce) {
     if (nonce.length !== 16) {
         throw new Error(`nonce must be 16 bytes, got ${nonce.length}`);
     }
     const accountBytes = fromHex(account, 'account', 32);
-    return hex(await domainHash(DEVICE_ID_DOMAIN, [accountBytes, nonce]));
+    const binding = await domainHash(DEVICE_ID_DOMAIN, [accountBytes, nonce]);
+    return hex(concat(nonce, binding.subarray(0, 16)));
 }
 /**
  * The 32 bytes a root signs to certify a device.

package/dist/events/sse.d.ts

@@ -1,4 +1,6 @@
 import type { GroupMembershipEventData, GroupMigrationEventData } from './group.js';
+/** How long a subscription POST may take before it counts as failed. */
+export declare const SUBSCRIPTION_TIMEOUT_MS = 10000;
 export type { GroupMembershipEventData, GroupMigrationEventData };
 export interface SseEventData {
     contextId: string;
@@ -109,6 +111,8 @@ export declare class SseClient {
         groupIds?: string[];
     }): Promise<void>;
     private sendSubscription;
+    /** Sends one subscription change and returns why it failed, or `null`. */
+    private postSubscription;
     private forceReconnect;
     private scheduleReconnect;
     close(): void;

package/dist/events/sse.js

@@ -17,6 +17,8 @@ const TERMINAL_AUTH_ERRORS = new Set(['token_reuse', 'token_revoked']);
  * `HTTPError(403)` and reconnected on a timer forever.
  */
 const TERMINAL_AUTH_STATUSES = new Set([401, 403]);
+/** How long a subscription POST may take before it counts as failed. */
+export const SUBSCRIPTION_TIMEOUT_MS = 10000;
 /**
  * Whether a failed response means the whole token family is gone, so the caller
  * must re-authenticate and the client must stop reconnecting.
@@ -233,18 +235,27 @@ export class SseClient {
             const msg = JSON.parse(jsonStr);
             // Connection message
             if (msg.type === 'connect' && msg.session_id) {
-                this.sessionId = msg.session_id;
-                this.emit('connect', msg.session_id);
+                const sessionId = msg.session_id;
+                this.sessionId = sessionId;
                 // A new connection gets a new replay when it re-subscribes; what the
                 // old one said may name authors who have since gone.
                 this.presence.clear();
-                // Re-subscribe after reconnect
-                if (this.subscribedContextIds.size > 0 || this.subscribedGroupIds.size > 0) {
-                    this.sendSubscription('subscribe', {
-                        contextIds: [...this.subscribedContextIds],
-                        groupIds: [...this.subscribedGroupIds],
-                    });
+                if (this.subscribedContextIds.size === 0 && this.subscribedGroupIds.size === 0) {
+                    this.emit('connect', sessionId);
+                    return;
                 }
+                // A new session starts subscribed to nothing, so announce it once the re-subscribe
+                // lands; a failed one still announces, then reports the error, as consumers saw before.
+                void this.postSubscription('subscribe', {
+                    contextIds: [...this.subscribedContextIds],
+                    groupIds: [...this.subscribedGroupIds],
+                }).then((failure) => {
+                    if (this.closed || this.sessionId !== sessionId)
+                        return;
+                    this.emit('connect', sessionId);
+                    if (failure)
+                        this.emit('error', failure);
+                });
                 return;
             }
             if (!msg.result)
@@ -348,6 +359,14 @@ export class SseClient {
         }
     }
     async sendSubscription(method, ids) {
+        const failure = await this.postSubscription(method, ids);
+        if (failure)
+            this.emit('error', failure);
+    }
+    /** Sends one subscription change and returns why it failed, or `null`. */
+    async postSubscription(method, ids) {
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(new DOMException(`SSE ${method} timed out`, 'TimeoutError')), SUBSCRIPTION_TIMEOUT_MS);
         try {
             const params = {};
             if (ids.contextIds && ids.contextIds.length > 0)
@@ -367,6 +386,7 @@ export class SseClient {
                     'Content-Type': 'application/json',
                 },
                 body,
+                signal: timeout.signal,
             });
             if (!response.ok) {
                 // The subscribe path used to report only the status. On the one failure
@@ -377,13 +397,17 @@ export class SseClient {
                 // does carry a body.
                 const terminal = isTerminalAuthFailure(response);
                 const bodyText = await response.text().catch(() => undefined);
-                this.emit('error', terminal
+                return terminal
                     ? new AuthRevokedError(terminal, response.status, response.statusText, `${this.baseUrl}/sse/subscription`, response.headers, bodyText)
-                    : new HTTPError(response.status, response.statusText, `${this.baseUrl}/sse/subscription`, response.headers, bodyText));
+                    : new HTTPError(response.status, response.statusText, `${this.baseUrl}/sse/subscription`, response.headers, bodyText);
             }
+            return null;
         }
         catch (err) {
-            this.emit('error', err instanceof Error ? err : new Error(`SSE ${method} failed`));
+            return err instanceof Error ? err : new Error(`SSE ${method} failed`);
+        }
+        finally {
+            clearTimeout(timer);
         }
     }
     forceReconnect() {