@calimero-network/mero-js 19.13.1 → 19.14.1

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, 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';
+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, AccountSignWithRootRequest, AccountSignWithRootResponseData, 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,36 @@ export declare class AdminApiClient {
      * device need not be online.
      */
     rescopeAccountDevice(deviceId: string, request: RescopeDeviceRequest): Promise<RescopeDeviceResponseData>;
+    /**
+     * Sign a payload an outside verifier specified, with this account's root.
+     *
+     * The counterpart to a verifier that issued a challenge and will check the
+     * signature against the account id it derives — the cloud's account link and
+     * login exchanges being the ones this exists for. The root never leaves the
+     * node, so this is the only way a client can produce that signature.
+     *
+     * `domain` is a NAME from a closed set the node knows, never the domain bytes.
+     * That is the security property rather than an encoding preference: signing
+     * caller-supplied bytes under a caller-supplied prefix would be an oracle over
+     * the one key that can certify a device. A node refuses a name it does not
+     * know, and refuses one whose bytes could be extended into a credential of its
+     * own.
+     *
+     * What comes back proves possession of the root and nothing else. Whether the
+     * payload is a challenge anyone issued, whether it is fresh, and whether the
+     * holder may link this account are the verifier's to decide — it issued the
+     * challenge and knows who to.
+     *
+     * ```ts
+     * const { nonce } = await cloud.getAccountLoginChallenge();
+     * const { rootPublicKey, signature } = await admin.signWithAccountRoot({
+     *   domain: 'mdma.account-login',
+     *   payload: hexEncodeUtf8(nonce),
+     * });
+     * await cloud.submitAccountLogin({ rootPublicKey, nonce, signature });
+     * ```
+     */
+    signWithAccountRoot(request: AccountSignWithRootRequest): Promise<AccountSignWithRootResponseData>;
     /**
      * Name a device of this account, for a listing to render.
      *

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

@@ -597,6 +597,38 @@ export class AdminApiClient {
     async rescopeAccountDevice(deviceId, request) {
         return unwrap(await this.httpClient.put(`/admin-api/account/devices/${encodeURIComponent(deviceId)}/scope`, request));
     }
+    /**
+     * Sign a payload an outside verifier specified, with this account's root.
+     *
+     * The counterpart to a verifier that issued a challenge and will check the
+     * signature against the account id it derives — the cloud's account link and
+     * login exchanges being the ones this exists for. The root never leaves the
+     * node, so this is the only way a client can produce that signature.
+     *
+     * `domain` is a NAME from a closed set the node knows, never the domain bytes.
+     * That is the security property rather than an encoding preference: signing
+     * caller-supplied bytes under a caller-supplied prefix would be an oracle over
+     * the one key that can certify a device. A node refuses a name it does not
+     * know, and refuses one whose bytes could be extended into a credential of its
+     * own.
+     *
+     * What comes back proves possession of the root and nothing else. Whether the
+     * payload is a challenge anyone issued, whether it is fresh, and whether the
+     * holder may link this account are the verifier's to decide — it issued the
+     * challenge and knows who to.
+     *
+     * ```ts
+     * const { nonce } = await cloud.getAccountLoginChallenge();
+     * const { rootPublicKey, signature } = await admin.signWithAccountRoot({
+     *   domain: 'mdma.account-login',
+     *   payload: hexEncodeUtf8(nonce),
+     * });
+     * await cloud.submitAccountLogin({ rootPublicKey, nonce, signature });
+     * ```
+     */
+    async signWithAccountRoot(request) {
+        return unwrap(await this.httpClient.post('/admin-api/account/sign-with-root', request));
+    }
     /**
      * Name a device of this account, for a listing to render.
      *

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

@@ -800,6 +800,61 @@ export interface AccountPairCompleteResponseData {
      */
     credential: string;
 }
+/**
+ * A domain an outside verifier defined, which the account root may sign under.
+ *
+ * A name from a closed set, never the domain bytes. The node prepends the bytes
+ * itself: "sign these bytes with the account root" would be a signing oracle
+ * over the one key that can certify a device, which is account takeover. A node
+ * refuses any name it does not know.
+ *
+ * Typed as a union plus `(string & {})` so a node newer than this SDK can be
+ * reached without a cast, while the known names still autocomplete.
+ */
+export type ExternalSigningDomain = 'mdma.account-link' | 'mdma.account-login' | 'mdma.account-recovery' | (string & {});
+/**
+ * Ask this node's account root to sign a payload an outside verifier specified.
+ *
+ * The verifier owns the format; the node supplies only the domain. For the cloud
+ * this is how a challenge it sealed and issued gets signed by a root that
+ * deliberately never leaves the node holding it.
+ */
+export interface AccountSignWithRootRequest {
+    /** Which verifier's domain to sign under. */
+    domain: ExternalSigningDomain;
+    /**
+     * The bytes to sign after the domain, hex-encoded.
+     *
+     * Hex rather than text because the field is bytes. For the cloud's challenge —
+     * an ASCII string — that is the UTF-8 of it, hex-encoded; {@link hexEncodeUtf8}
+     * does exactly that and exists so each caller does not re-derive it.
+     */
+    payload: string;
+}
+/**
+ * Hex-encode a string's UTF-8 bytes, for {@link AccountSignWithRootRequest.payload}.
+ *
+ * Exists so each caller does not write the same loop. Every verifier this is
+ * used with issues its challenge as text, and the node takes bytes — getting
+ * that conversion subtly wrong (UTF-16 code units, a stray newline from a shell)
+ * produces a signature over the wrong message, which fails at the verifier with
+ * nothing local to point at.
+ */
+export declare function hexEncodeUtf8(text: string): string;
+/** What the node signed, and the key to check it against. */
+export interface AccountSignWithRootResponseData {
+    /** The account root's public key, 64 hex characters. */
+    rootPublicKey: string;
+    /**
+     * The signature over `domain ‖ payload`, **base64**.
+     *
+     * Base64 rather than hex because that is what the consuming verifiers decode;
+     * re-encoding it on the way out is a step that fails silently at the far end.
+     */
+    signature: string;
+    /** The account the signing key belongs to, 64 hex characters. */
+    accountId: string;
+}
 /**
  * Repair or widen the reach of a device this account already certified.
  *

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

@@ -1,3 +1,14 @@
 // Admin API Types — aligned with core server routes
 // All types use camelCase to match core's #[serde(rename_all = "camelCase")]
-export {};
+/**
+ * Hex-encode a string's UTF-8 bytes, for {@link AccountSignWithRootRequest.payload}.
+ *
+ * Exists so each caller does not write the same loop. Every verifier this is
+ * used with issues its challenge as text, and the node takes bytes — getting
+ * that conversion subtly wrong (UTF-16 code units, a stray newline from a shell)
+ * produces a signature over the wrong message, which fails at the verifier with
+ * nothing local to point at.
+ */
+export function hexEncodeUtf8(text) {
+    return Array.from(new TextEncoder().encode(text), (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/events/sse.js

@@ -6,6 +6,32 @@ import { AuthRevokedError, HTTPError } from '../http-client/index.js';
  * all — is recoverable by refreshing and reconnecting.
  */
 const TERMINAL_AUTH_ERRORS = new Set(['token_reuse', 'token_revoked']);
+/**
+ * Statuses a terminal `x-auth-error` can arrive on.
+ *
+ * Measured against merod 0.11.0-rc.41: a revoked token family answers
+ * `GET /sse` and `POST /sse/subscription` with **403**, `x-auth-error:
+ * token_revoked` and `content-length: 0` — `token_expired` is the 401.
+ * Keying the check on 401 alone made the branch below unreachable for the one
+ * reason a stream actually sees, so a dead token family surfaced as a bare
+ * `HTTPError(403)` and reconnected on a timer forever.
+ */
+const TERMINAL_AUTH_STATUSES = new Set([401, 403]);
+/**
+ * Whether a failed response means the whole token family is gone, so the caller
+ * must re-authenticate and the client must stop reconnecting.
+ *
+ * The body carries nothing on this path (`content-length: 0`), so the header is
+ * the only evidence there is.
+ */
+function isTerminalAuthFailure(response) {
+    const authError = response.headers.get('x-auth-error');
+    if (!authError)
+        return null;
+    if (!TERMINAL_AUTH_STATUSES.has(response.status))
+        return null;
+    return TERMINAL_AUTH_ERRORS.has(authError) ? authError : null;
+}
 export class SseClient {
     constructor(opts) {
         this.sessionId = null;
@@ -110,12 +136,10 @@ export class SseClient {
                 // 401 as fatal — logs the user out on a routine reconnect after the
                 // access token ages out, discarding a refresh token that was still
                 // good. The distinction is in the header; surface it.
-                const authError = response.headers.get('x-auth-error');
+                const terminal = isTerminalAuthFailure(response);
                 const bodyText = await response.text().catch(() => undefined);
-                if (response.status === 401 &&
-                    authError &&
-                    TERMINAL_AUTH_ERRORS.has(authError)) {
-                    throw new AuthRevokedError(authError, response.status, response.statusText, url, response.headers, bodyText);
+                if (terminal) {
+                    throw new AuthRevokedError(terminal, response.status, response.statusText, url, response.headers, bodyText);
                 }
                 throw new HTTPError(response.status, response.statusText, url, response.headers, bodyText);
             }
@@ -135,6 +159,11 @@ export class SseClient {
                 return;
             const error = err instanceof Error ? err : new Error(String(err));
             this.emit('error', error);
+            // Reconnecting against a revoked token family is a timer that never
+            // succeeds: every attempt re-sends the same dead credential. The caller
+            // has to re-authenticate, and an AuthRevokedError is how it is told.
+            if (error instanceof AuthRevokedError)
+                return;
             this.scheduleReconnect();
         }
     }
@@ -284,7 +313,17 @@ export class SseClient {
                 }),
             });
             if (!response.ok) {
-                this.emit('error', new Error(`SSE ${method} failed: ${response.status}`));
+                // The subscribe path used to report only the status. On the one failure
+                // that matters it is the whole of what the caller got: a revoked family
+                // answers 403 with an empty body, so a bare `SSE subscribe failed: 403`
+                // discarded the only evidence of what went wrong — and a 403 here reads
+                // identically to the unrelated "not the session owner" refusal, which
+                // does carry a body.
+                const terminal = isTerminalAuthFailure(response);
+                const bodyText = await response.text().catch(() => undefined);
+                this.emit('error', 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));
             }
         }
         catch (err) {