@calimero-network/mero-js 23.4.3 → 23.6.0

package/dist/cloud/account-ownership.d.ts

@@ -1,5 +1,8 @@
 import { type Signer } from '../signer/signer.js';
-/** The `ownership_proof` body for `POST /api/cloud/me/namespaces/{ns}/enable-ha`. */
+/**
+ * The `ownership_proof` body for `POST /api/cloud/me/namespaces/{ns}/enable-ha`
+ * and for `POST /api/cloud/accounts/{account}/namespaces/{ns}/enable-ha`.
+ */
 export interface AccountOwnershipProof {
     kind: 'account';
     /** hex `AccountProof<DeviceCert>`, the account's credential. */
@@ -9,15 +12,14 @@ export interface AccountOwnershipProof {
     /** base64 ed25519 by the certified device key. */
     signature: string;
 }
-export interface AccountOwnershipClaimInput {
+/** What every account claim needs; the audience and `subject` differ per route. */
+interface AccountClaimBase {
     /** The namespace, hex: the id `foundNamespace` returned. */
     namespaceId: string;
     /** The founding account, hex. */
     accountId: string;
     /** The salt `foundNamespace` returned, hex (32 bytes). */
     salt: string;
-    /** The cloud login's email: the claim is for this login only. */
-    subject: string;
     /** The account's credential, hex `AccountProof<DeviceCert>`. */
     credential: string;
     deviceSecret?: string;
@@ -27,4 +29,35 @@ export interface AccountOwnershipClaimInput {
     /** For tests. */
     now?: () => number;
 }
+export interface AccountOwnershipClaimInput extends AccountClaimBase {
+    /** The cloud login's email: the claim is for this login only. */
+    subject: string;
+}
+/**
+ * Input for {@link signAccountHaClaim}: the same as the session claim, minus
+ * `subject` — there is no login to bind it to.
+ */
+export interface AccountHaClaimInput extends AccountClaimBase {
+    /**
+     * The relay that founded the namespace (the delegated session's `relayUrl`).
+     * Signed into the claim so nobody forwarding it can swap it: the cloud
+     * resolves it to one of its own fleet relays and hands that relay's
+     * addresses to the fleet node as its admitter. Leave it out when unknown.
+     */
+    relayUrl?: string;
+}
+/** The audience of the session route's claim (`/api/cloud/me/...`). */
+export declare const ACCOUNT_OWNERSHIP_AUDIENCE = "mdma:enable-ha-namespace";
+/** The audience of the anonymous account route's claim (`/api/cloud/accounts/...`). */
+export declare const ACCOUNT_HA_AUDIENCE = "mdma:enable-ha-namespace-as-account";
+/** The founder's claim for the SESSION route, bound to one cloud login (`subject`). */
 export declare function signAccountOwnershipClaim(input: AccountOwnershipClaimInput): Promise<AccountOwnershipProof>;
+/**
+ * The founder's claim for the ANONYMOUS account route
+ * (`POST /api/cloud/accounts/{account}/namespaces/{ns}/enable-ha`): no cloud
+ * session, so no `subject`, and its own audience so a claim minted for one
+ * route can never be replayed on the other. The cloud finds the user to bill
+ * through the account's wallet link instead.
+ */
+export declare function signAccountHaClaim(input: AccountHaClaimInput): Promise<AccountOwnershipProof>;
+export {};

package/dist/cloud/account-ownership.js

@@ -19,6 +19,12 @@ const DOMAIN = new TextEncoder().encode('calimero.mdma.account-ownership-claim.v
 /** What the cloud accepts; it caps a claim's lifetime at five minutes. */
 const DEFAULT_TTL_MS = 60000;
 const MAX_TTL_MS = 5 * 60000;
+/** The cloud's limit on `relay_url`. */
+const MAX_RELAY_URL = 1024;
+/** The audience of the session route's claim (`/api/cloud/me/...`). */
+export const ACCOUNT_OWNERSHIP_AUDIENCE = 'mdma:enable-ha-namespace';
+/** The audience of the anonymous account route's claim (`/api/cloud/accounts/...`). */
+export const ACCOUNT_HA_AUDIENCE = 'mdma:enable-ha-namespace-as-account';
 function base64(bytes) {
     let binary = '';
     for (const b of bytes)
@@ -30,26 +36,52 @@ const hex32 = (value, what) => {
         throw new Error(`${what} must be 64 hex characters`);
     return value.toLowerCase();
 };
-export async function signAccountOwnershipClaim(input) {
+/**
+ * Sign one claim. `subject` is spliced in after `salt` only when given, so the
+ * session claim keeps its exact field order and the account claim has no
+ * `subject` key at all (not a null one: the cloud tells the two apart by it).
+ */
+async function signClaim(input, audience, subject, relayUrl) {
+    if (relayUrl !== undefined && !(relayUrl.length > 0 && relayUrl.length <= MAX_RELAY_URL)) {
+        throw new Error(`relayUrl must be a non-empty string of at most ${MAX_RELAY_URL} characters`);
+    }
     const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
     if (!(ttl > 0 && ttl <= MAX_TTL_MS))
         throw new Error(`ttlMs must be in (0, ${MAX_TTL_MS}]`);
-    if (!input.subject)
-        throw new Error('subject must be the cloud login email');
+    const groupId = hex32(input.namespaceId, 'namespaceId');
+    const accountId = hex32(input.accountId, 'accountId');
+    const salt = hex32(input.salt, 'salt');
     const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
     const issued = (input.now ?? Date.now)();
     const nonce = Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, '0')).join('');
     const payload = new TextEncoder().encode(JSON.stringify({
         v: 1,
-        audience: 'mdma:enable-ha-namespace',
-        group_id: hex32(input.namespaceId, 'namespaceId'),
-        account_id: hex32(input.accountId, 'accountId'),
-        salt: hex32(input.salt, 'salt'),
-        subject: input.subject,
+        audience,
+        group_id: groupId,
+        account_id: accountId,
+        salt,
+        ...(subject === undefined ? {} : { subject }),
         nonce,
         issued_at_ms: issued,
         expires_at_ms: issued + ttl,
+        ...(relayUrl === undefined ? {} : { relay_url: relayUrl }),
     }));
     const signature = await signer.sign(concat(DOMAIN, payload));
     return { kind: 'account', credential: input.credential, signed_payload: base64(payload), signature: base64(signature) };
 }
+/** The founder's claim for the SESSION route, bound to one cloud login (`subject`). */
+export async function signAccountOwnershipClaim(input) {
+    if (!input.subject)
+        throw new Error('subject must be the cloud login email');
+    return signClaim(input, ACCOUNT_OWNERSHIP_AUDIENCE, input.subject);
+}
+/**
+ * The founder's claim for the ANONYMOUS account route
+ * (`POST /api/cloud/accounts/{account}/namespaces/{ns}/enable-ha`): no cloud
+ * session, so no `subject`, and its own audience so a claim minted for one
+ * route can never be replayed on the other. The cloud finds the user to bill
+ * through the account's wallet link instead.
+ */
+export async function signAccountHaClaim(input) {
+    return signClaim(input, ACCOUNT_HA_AUDIENCE, undefined, input.relayUrl);
+}

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

@@ -24,8 +24,9 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
-import type { AccountOwnershipProof } from './account-ownership.js';
+import { type AccountOwnershipProof } from './account-ownership.js';
 import { type RootSource } from '../account/index.js';
+import { HTTPError } from '../http-client/web-client.js';
 import type { Signer } from '../signer/signer.js';
 import { type DiscoveryChallenge, type RoutingChallenge, type RoutingCredential } from './routing-proof.js';
 /**
@@ -365,6 +366,86 @@ export interface DisableHAOptions {
     contextId: string;
     redirectUrl?: string;
 }
+/** Options for {@link CloudClient.enableHaAsAccount}. */
+export interface EnableHaAsAccountOptions {
+    /** The namespace, hex: the id `foundNamespace` returned. */
+    namespaceId: string;
+    /** The salt `foundNamespace` returned, hex (32 bytes). */
+    salt: string;
+    /** The founding account, hex. */
+    accountId: string;
+    /** The account's credential, hex `AccountProof<DeviceCert>`. */
+    credential: string;
+    /** The certified device's secret, hex. Give this or `signer`. */
+    deviceSecret?: string;
+    signer?: Signer;
+    /** The claim's lifetime in ms; default one minute, at most five. */
+    ttlMs?: number;
+    /**
+     * The relay that founded the namespace (the delegated session's `relayUrl`).
+     * The cloud gives that relay to the fleet node as its admitter; without it
+     * the node has to find the relay by discovery.
+     */
+    relayUrl?: string;
+}
+/**
+ * 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 declare class AccountHaRefusedError extends HTTPError {
+    /** The cloud's `error` code, verbatim. */
+    readonly code: string;
+    name: string;
+    constructor(
+    /** The cloud's `error` code, verbatim. */
+    code: string, status: number, statusText: string, url: string, headers: Headers, bodyText?: string);
+}
+/**
+ * `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 declare class AccountNotLinkedError extends AccountHaRefusedError {
+    name: string;
+    static readonly 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 declare class AccountLinkedToSeveralUsersError extends AccountHaRefusedError {
+    name: string;
+    static readonly 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 declare class HaRequestPendingError extends AccountHaRefusedError {
+    name: string;
+    static readonly CODE = "ha_request_pending";
+}
+/**
+ * `unknown_relay` (422): the cloud runs no relay at `relayUrl`. The claim was
+ * not spent.
+ */
+export declare class UnknownRelayError extends AccountHaRefusedError {
+    name: string;
+    static readonly 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 declare class RelayNotDialableError extends AccountHaRefusedError {
+    name: string;
+    static readonly CODE = "relay_not_dialable";
+}
 export declare class CloudClient {
     private baseUrl;
     private session;
@@ -610,6 +691,24 @@ export declare class CloudClient {
      * The login must be linked to that account.
      */
     enableFoundedNamespaceHa(namespaceId: string, ownershipProof: AccountOwnershipProof): Promise<unknown>;
+    /**
+     * 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.
+     */
+    enableHaAsAccount(options: EnableHaAsAccountOptions): Promise<unknown>;
     /**
      * Stop hosting a claimed namespace.
      *

package/dist/cloud/cloud-client.js

@@ -24,6 +24,7 @@
  * 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 { routingProofHeaders, } from './routing-proof.js';
@@ -65,6 +66,107 @@ function teeRoleOf(row) {
 export function pickExecutingRelay(relays) {
     return (relays.find((r) => r.canExecute && r.relayUrl !== null && r.executorAccount !== null) ?? 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';
@@ -509,6 +611,52 @@ export class CloudClient {
     async enableFoundedNamespaceHa(namespaceId, ownershipProof) {
         return this.request('POST', `/api/cloud/me/namespaces/${encodeURIComponent(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/${encodeURIComponent(account)}/namespaces/${encodeURIComponent(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.
      *

package/dist/cloud/index.d.ts

@@ -1,5 +1,5 @@
-export { CloudClient, admitterAddrsFromNetworkStatus } 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 { 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 { connectCloud, connectCloudWithAccount } from './connect.js';
 export type { ConnectCloudOptions, ConnectCloudWithAccountOptions, CloudConnection, } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
@@ -8,5 +8,5 @@ export { cloudLinkUrl, beginCloudLink, readCloudLinkCallback, completeCloudLink,
 export type { BeginCloudLinkOptions, CloudLinkCallback, CompleteCloudLinkOptions, } from './link-redirect.js';
 export { deviceEnrolmentUrl, beginDeviceEnrolment, readEnrolmentCallback, completeDeviceEnrolment, callbackIsForeign, } from './enrol-redirect.js';
 export type { DeviceEnrolmentOptions, DeviceEnrolmentCallback, CompleteDeviceEnrolmentOptions, EnrolledDevice, } from './enrol-redirect.js';
-export { signAccountOwnershipClaim } from './account-ownership.js';
-export type { AccountOwnershipProof, AccountOwnershipClaimInput } from './account-ownership.js';
+export { signAccountOwnershipClaim, signAccountHaClaim, ACCOUNT_OWNERSHIP_AUDIENCE, ACCOUNT_HA_AUDIENCE, } from './account-ownership.js';
+export type { AccountOwnershipProof, AccountOwnershipClaimInput, AccountHaClaimInput, } from './account-ownership.js';

package/dist/cloud/index.js

@@ -1,4 +1,4 @@
-export { CloudClient, admitterAddrsFromNetworkStatus } from './cloud-client.js';
+export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } from './cloud-client.js';
 export { connectCloud, connectCloudWithAccount } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
 // Linking an account to a cloud login from a browser — the redirect half the
@@ -7,4 +7,4 @@ export { cloudLinkUrl, beginCloudLink, readCloudLinkCallback, completeCloudLink,
 // Getting this app's device key certified by a wallet on another origin — the
 // redirect that keeps the account root out of the app's reach.
 export { deviceEnrolmentUrl, beginDeviceEnrolment, readEnrolmentCallback, completeDeviceEnrolment, callbackIsForeign, } from './enrol-redirect.js';
-export { signAccountOwnershipClaim } from './account-ownership.js';
+export { signAccountOwnershipClaim, signAccountHaClaim, ACCOUNT_OWNERSHIP_AUDIENCE, ACCOUNT_HA_AUDIENCE, } from './account-ownership.js';