@calimero-network/mero-js 23.8.1 → 23.9.0

package/dist/account/govern.js

@@ -0,0 +1,50 @@
+import { delegatedGovernance } from './create-context.js';
+import { readRelayMap } from './session.js';
+const GROUP_NAMESPACE_PREFIX = 'calimero.delegated.group-namespace.';
+// What this page has learned, whether or not storage keeps it: a private window
+// or blocked site data must not turn a known subgroup back into an unknown one.
+const learned = new Map();
+function readGroupNamespaces(account) {
+    let stored = {};
+    try {
+        stored = JSON.parse(localStorage.getItem(GROUP_NAMESPACE_PREFIX + account) ?? '{}');
+    }
+    catch {
+        /* no storage: what this page learned still stands */
+    }
+    return { ...stored, ...learned.get(account) };
+}
+/** Record that `groupId` is a subgroup of `namespaceId`, for this account. */
+export function rememberGroupNamespace(account, groupId, namespaceId) {
+    learned.set(account, { ...learned.get(account), [groupId]: namespaceId });
+    try {
+        const all = readGroupNamespaces(account);
+        all[groupId] = namespaceId;
+        localStorage.setItem(GROUP_NAMESPACE_PREFIX + account, JSON.stringify(all));
+    }
+    catch {
+        /* unpersisted: root ops on this subgroup will ask for its namespace */
+    }
+}
+/** The namespace a group belongs to: itself if it is a namespace this account is in, else what was remembered. */
+export function namespaceOfGroup(s, groupId) {
+    if (readRelayMap(s.account).namespaces[groupId])
+        return groupId;
+    return readGroupNamespaces(s.account)[groupId];
+}
+function requireNamespace(s, groupId) {
+    const ns = namespaceOfGroup(s, groupId);
+    if (!ns) {
+        throw new Error(`the namespace of group ${groupId} is not known to this account: it can manage only groups in namespaces it joined or subgroups it created`);
+    }
+    return ns;
+}
+/** A group op (member, role, capabilities, metadata, visibility, detach) on `groupId`. */
+export async function governGroup(s, groupId, op) {
+    return delegatedGovernance(s, { namespaceId: requireNamespace(s, groupId), group: groupId, op });
+}
+/** A root op, posted to the namespace `groupId` belongs to. */
+export async function governRoot(s, groupId, op) {
+    const namespaceId = requireNamespace(s, groupId);
+    return delegatedGovernance(s, { namespaceId, group: namespaceId, op });
+}

package/dist/account/index.d.ts

@@ -4,3 +4,21 @@ export { resolveRoot } from './account.js';
 export type { RootSource } from './account.js';
 export { resolveRootPair } from './account.js';
 export type { ResolvedRoot } from './account.js';
+export type { DelegatedCredential, DelegatedSession as DelegatedAccountSession, RelayMap, RelayNodeKeyAttempt } from './session.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
+export type { RelayResolutionStep, RelayResolutionFailure, ResolvedInvitationRelay, ResolveRelayResult, ResolveRelayFromInvitationInput, } from './relay-from-invitation.js';
+export { joinWithNode } from './join-with-node.js';
+export type { JoinWithNodeInput, JoinWithNodeResult, JoinWithNodeSuccess, JoinWithNodeFailure, JoinWithNodeStep, } from './join-with-node.js';
+export { bootstrapFromInvitation } from './bootstrap-from-invitation.js';
+export type { BootstrapStep, BootstrapResult, BootstrapSuccess, BootstrapFailure, BootstrapFromInvitationInput, } from './bootstrap-from-invitation.js';
+export { joinAsAccount } from './join-as-account.js';
+export { createDelegatedContext, createDelegatedPrivateContext, foundDelegatedNamespace, delegatedGovernance, latestPublishedVersion, HA_ACCOUNT_NOT_LINKED_MESSAGE, HA_REFUSAL_MESSAGES, } from './create-context.js';
+export type { CreateDelegatedContextRequest, FoundedDelegatedNamespace } from './create-context.js';
+export { governGroup, governRoot, namespaceOfGroup, rememberGroupNamespace } from './govern.js';
+export { applicationIdForBundle, fetchRegistryBundles, resolveApplicationIdFromRegistry, selectLatestBundle, } from './application-id.js';
+export type { RegistryBundle, ResolvedApplication } from './application-id.js';
+export { createAccountAdmin, InvitationNotClaimableError, NoRelayError, NotForAccountError, } from './account-admin.js';
+export type { AccountAdminDeps } from './account-admin.js';
+export { createNodeAdmin } from './node-admin.js';
+export type { NodeAdminDeps } from './node-admin.js';

package/dist/account/index.js

@@ -2,3 +2,13 @@
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, createAccountRootSigner, accountRootSignerFromPhrase, signAccountLink, signAccountLogin, } from './account.js';
 export { resolveRoot } from './account.js';
 export { resolveRootPair } from './account.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
+export { joinWithNode } from './join-with-node.js';
+export { bootstrapFromInvitation } from './bootstrap-from-invitation.js';
+export { joinAsAccount } from './join-as-account.js';
+export { createDelegatedContext, createDelegatedPrivateContext, foundDelegatedNamespace, delegatedGovernance, latestPublishedVersion, HA_ACCOUNT_NOT_LINKED_MESSAGE, HA_REFUSAL_MESSAGES, } from './create-context.js';
+export { governGroup, governRoot, namespaceOfGroup, rememberGroupNamespace } from './govern.js';
+export { applicationIdForBundle, fetchRegistryBundles, resolveApplicationIdFromRegistry, selectLatestBundle, } from './application-id.js';
+export { createAccountAdmin, InvitationNotClaimableError, NoRelayError, NotForAccountError, } from './account-admin.js';
+export { createNodeAdmin } from './node-admin.js';

package/dist/account/join-as-account.d.ts

@@ -0,0 +1,23 @@
+import type { SignedGroupOpenInvitation } from '../admin-api/index.js';
+import { bootstrapFromInvitation } from './bootstrap-from-invitation.js';
+import { type DelegatedSession } from './session.js';
+/**
+ * Redeem an invitation for an account, the way `useDelegatedBootstrap` does:
+ * resolve the relay the invitation names, have it admit the account, add that
+ * relay to the account's map and hand the session over to `onJoined`.
+ *
+ * It is what an account's `admin.joinNamespace` runs, so an app that joins with
+ * the node call gets the account path with no code of its own. It works with no
+ * relay yet: the join is how an account gets its first one.
+ *
+ * Rejects on a refused join with the refusal's reason, its `step`, and its HTTP
+ * `status` when it has one, as the node call would; nothing is remembered or
+ * switched then.
+ */
+export declare function joinAsAccount(session: DelegatedSession, namespaceId: string, invitation: SignedGroupOpenInvitation, opts: {
+    cloudBaseUrl?: string;
+    onJoined: (session: DelegatedSession) => void;
+    bootstrap?: typeof bootstrapFromInvitation;
+}): Promise<{
+    namespaceId: string;
+}>;

package/dist/account/join-as-account.js

@@ -0,0 +1,34 @@
+import { bootstrapFromInvitation } from './bootstrap-from-invitation.js';
+import { carryExecutorAccount, rememberRelay } from './session.js';
+/**
+ * Redeem an invitation for an account, the way `useDelegatedBootstrap` does:
+ * resolve the relay the invitation names, have it admit the account, add that
+ * relay to the account's map and hand the session over to `onJoined`.
+ *
+ * It is what an account's `admin.joinNamespace` runs, so an app that joins with
+ * the node call gets the account path with no code of its own. It works with no
+ * relay yet: the join is how an account gets its first one.
+ *
+ * Rejects on a refused join with the refusal's reason, its `step`, and its HTTP
+ * `status` when it has one, as the node call would; nothing is remembered or
+ * switched then.
+ */
+export async function joinAsAccount(session, namespaceId, invitation, opts) {
+    const bootstrap = opts.bootstrap ?? bootstrapFromInvitation;
+    const outcome = await bootstrap({
+        namespaceId,
+        invitation,
+        credential: { account: session.account, credential: session.credential, deviceSecret: session.deviceSecret },
+        cloudBaseUrl: opts.cloudBaseUrl,
+    });
+    if (outcome.ok === false) {
+        throw Object.assign(new Error(outcome.reason), {
+            step: outcome.step,
+            ...(outcome.status !== undefined ? { status: outcome.status } : {}),
+        });
+    }
+    if (outcome.session.relayUrl)
+        rememberRelay(session.account, outcome.session.relayUrl, { namespaceId });
+    opts.onJoined(carryExecutorAccount(session, outcome.session));
+    return { namespaceId };
+}

package/dist/account/join-with-node.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Present a signed join to ONE named node.
+ *
+ * This is the whole of admission for a caller with no node of its own: sign the
+ * membership op with the device key the account certified, and POST it to a node
+ * the invitation named as an admitter.
+ *
+ *     POST /admin-api/namespaces/{namespaceId}/admit
+ *     { "invitation": SignedGroupOpenInvitation, "signedOp": "<hex borsh SignedNamespaceOp>" }
+ *
+ * Verified against core at rc.43 — `crates/server/src/admin/handlers/namespaces/
+ * admit_join.rs`, request type `AdmitJoinApiRequest` in
+ * `crates/server/primitives/src/admin/mod.rs`. The handler also refuses a
+ * mismatch between the invitation's `group_id` and the namespace in the path, so
+ * the two are never allowed to disagree here.
+ *
+ * ## Why it needs no token and no proof
+ *
+ * The joiner's signature IS the authorization. The op is signed by the device
+ * key named in the credential it carries, and every peer checks
+ * `signer == credential.statement.sign_pk` before applying a join — so an
+ * admitter can carry this and can never author it: it cannot admit a different
+ * account, change the group, or grant a role. It can refuse, and that is all.
+ * This is also why the fleet ingress leaves the route unauthenticated, and why
+ * this posts with `fetch` rather than through `AdminApiClient`, which is built
+ * around a node credential this caller does not have.
+ *
+ * ## Why it lives here and not in mero-js
+ *
+ * Two reasons. `mero-js` is read-only for this change by instruction, and the
+ * shape that is actually useful to a caller is the one that hands back a
+ * {@link DelegatedSession} — the node that admitted you is the node to connect
+ * through — which is `mero-react`'s concern. The pieces that are pure SDK, the
+ * borsh op layout and the request type, are used from `mero-js` unchanged and
+ * are not reimplemented here.
+ *
+ * ## Why the op has no parents
+ *
+ * A keyholder holds no node, so it has no view of the namespace DAG and cannot
+ * name its heads. Empty parents is the only thing it *can* sign, and the direct
+ * admission path exists precisely for callers in that position.
+ */
+import { type SignedGroupOpenInvitation } from '../admin-api/index.js';
+import type { DelegatedCredential, DelegatedSession } from './session.js';
+/** Which step failed, when one did. */
+export type JoinWithNodeStep = 
+/** The op could not be signed. Local, deterministic, and nothing was sent. */
+'sign'
+/** The node refused it, or could not be reached. */
+ | 'admit';
+export interface JoinWithNodeSuccess {
+    readonly ok: true;
+    /**
+     * Whether the admitter said it published the op.
+     *
+     * NOT "you are a member": membership lands when peers apply the op, which the
+     * admitter neither performs nor waits for.
+     */
+    readonly published: boolean;
+    /**
+     * The session to connect with — the admitting node, used immediately.
+     *
+     * Deliberately not waiting for `getAccountRelays` to answer: the fleet writes
+     * the account's recovery envelope asynchronously, so the cloud lookup lags the
+     * admission by an unpredictable amount. The node that just carried the join is
+     * known to serve this namespace right now, which is a better answer than a
+     * lookup that will agree later.
+     */
+    readonly session: DelegatedSession;
+}
+export interface JoinWithNodeFailure {
+    readonly ok: false;
+    readonly step: JoinWithNodeStep;
+    readonly reason: string;
+    /** The HTTP status, when the node answered with one. */
+    readonly status?: number;
+}
+export type JoinWithNodeResult = JoinWithNodeSuccess | JoinWithNodeFailure;
+export interface JoinWithNodeInput {
+    /**
+     * The node to present the join to — its admin API origin.
+     *
+     * The primary parameter, so all three sources of a node URL feed one method:
+     * one carried by the invitation (core emits only libp2p multiaddrs today —
+     * see `resolve_admitter_addrs`, a node cannot know the URL its admin API is
+     * proxied on — so this is the seam for when invitations carry a claim URL),
+     * one resolved from the cloud's `/admitters` lookup, and one an operator
+     * simply knows.
+     */
+    readonly nodeUrl: string;
+    /**
+     * The exact URL to POST to, when something already knows it.
+     *
+     * The cloud hands back a ready-made `admit_url` which need not be a path on
+     * `nodeUrl`'s origin, and rebuilding it from a guess is how a working
+     * admission becomes a 404. Omitted, the documented route on `nodeUrl` is used.
+     */
+    readonly admitUrl?: string;
+    /** The namespace being joined, 64 hex. Must match the invitation's group. */
+    readonly namespaceId: string;
+    /**
+     * The invitation, exactly as the inviter's node returned it.
+     *
+     * Passed through unchanged and never rebuilt field by field: the signature
+     * covers the body, and re-modelling it through a local type drops the unsigned
+     * bootstrap fields and invalidates the signature with them.
+     */
+    readonly invitation: SignedGroupOpenInvitation;
+    /** The enrolled account, its certificate, and the device secret that signs. */
+    readonly credential: DelegatedCredential;
+    /** Injected in tests. */
+    readonly deps?: {
+        readonly fetch?: typeof fetch;
+        readonly nonce?: () => Promise<bigint>;
+    };
+}
+/**
+ * Sign the membership op and present it to `nodeUrl`.
+ *
+ * Resolves rather than throws for every expected refusal, because they are
+ * different things for the person to do: a malformed op is final, an unreachable
+ * node is a retry, and a 409 means pick another admitter.
+ */
+export declare function joinWithNode(input: JoinWithNodeInput): Promise<JoinWithNodeResult>;

package/dist/account/join-with-node.js

@@ -0,0 +1,165 @@
+/**
+ * Present a signed join to ONE named node.
+ *
+ * This is the whole of admission for a caller with no node of its own: sign the
+ * membership op with the device key the account certified, and POST it to a node
+ * the invitation named as an admitter.
+ *
+ *     POST /admin-api/namespaces/{namespaceId}/admit
+ *     { "invitation": SignedGroupOpenInvitation, "signedOp": "<hex borsh SignedNamespaceOp>" }
+ *
+ * Verified against core at rc.43 — `crates/server/src/admin/handlers/namespaces/
+ * admit_join.rs`, request type `AdmitJoinApiRequest` in
+ * `crates/server/primitives/src/admin/mod.rs`. The handler also refuses a
+ * mismatch between the invitation's `group_id` and the namespace in the path, so
+ * the two are never allowed to disagree here.
+ *
+ * ## Why it needs no token and no proof
+ *
+ * The joiner's signature IS the authorization. The op is signed by the device
+ * key named in the credential it carries, and every peer checks
+ * `signer == credential.statement.sign_pk` before applying a join — so an
+ * admitter can carry this and can never author it: it cannot admit a different
+ * account, change the group, or grant a role. It can refuse, and that is all.
+ * This is also why the fleet ingress leaves the route unauthenticated, and why
+ * this posts with `fetch` rather than through `AdminApiClient`, which is built
+ * around a node credential this caller does not have.
+ *
+ * ## Why it lives here and not in mero-js
+ *
+ * Two reasons. `mero-js` is read-only for this change by instruction, and the
+ * shape that is actually useful to a caller is the one that hands back a
+ * {@link DelegatedSession} — the node that admitted you is the node to connect
+ * through — which is `mero-react`'s concern. The pieces that are pure SDK, the
+ * borsh op layout and the request type, are used from `mero-js` unchanged and
+ * are not reimplemented here.
+ *
+ * ## Why the op has no parents
+ *
+ * A keyholder holds no node, so it has no view of the namespace DAG and cannot
+ * name its heads. Empty parents is the only thing it *can* sign, and the direct
+ * admission path exists precisely for callers in that position.
+ */
+import { createLocalStorageNonceSource, } from '../relay/index.js';
+import { signMemberJoinOp, } from '../namespace-op/index.js';
+/**
+ * Turn an admit refusal into the thing to go and do about it.
+ *
+ * Each status has one dominant cause and they have nothing to do with each
+ * other, so a bare "HTTP 403" sends people to the wrong place — most often to
+ * the invitation, when the real answer is which node it was presented to.
+ */
+function explainAdmitFailure(status, body) {
+    const detail = body ? `: ${body}` : '';
+    switch (status) {
+        case 400:
+            return (`The node refused the join as malformed (400)${detail}. The signature covers the ` +
+                'invitation exactly as sent, so an edited or re-serialised invitation fails here — as ' +
+                "does a namespace id that is not the invitation's own group.");
+        case 403:
+            return (`The node refused to carry this join (403)${detail}. Either it is not in the ` +
+                "invitation's signed admitters list — being live and listed by the cloud is not the " +
+                'same thing — or the invitation itself was rejected as expired or not the inviter’s ' +
+                'to issue.');
+        case 409:
+            return (`That node holds no device of its own, so it cannot endorse anyone (409)${detail}. ` +
+                'Another admitter from the same invitation would work.');
+        default:
+            return `The join was not published (HTTP ${status})${detail}.`;
+    }
+}
+/**
+ * A join-nonce counter for this account, persisted so a reload does not replay.
+ *
+ * The device secret never appears in the key: storage keys are enumerable by
+ * anything running on the origin. One counter per account is right here — a
+ * bootstrap is once per account per device, and the node's receiving window
+ * accepts gaps, so a shared counter can only ever skip, never reuse.
+ */
+function joinNonce(account) {
+    const source = createLocalStorageNonceSource(`calimero.delegated.joinnonce.${account}`);
+    return () => source.next();
+}
+/** Strip a trailing slash so a pasted URL and a typed one address one node. */
+function origin(url) {
+    return url.replace(/\/+$/, '');
+}
+/**
+ * Sign the membership op and present it to `nodeUrl`.
+ *
+ * Resolves rather than throws for every expected refusal, because they are
+ * different things for the person to do: a malformed op is final, an unreachable
+ * node is a retry, and a 409 means pick another admitter.
+ */
+export async function joinWithNode(input) {
+    const { account, credential, deviceSecret } = input.credential;
+    let signedOp;
+    try {
+        signedOp = await signMemberJoinOp({
+            namespaceId: input.namespaceId,
+            member: account,
+            invitation: input.invitation,
+            credential,
+            deviceSecret,
+            nonce: await (input.deps?.nonce ?? joinNonce(account))(),
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            step: 'sign',
+            reason: 'The join op could not be signed, so nothing was sent: ' +
+                `${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    // `AdmitJoinRequest` names the shape, so a change to it in mero-js breaks this
+    // at the typecheck rather than as a 400 from a node.
+    const body = { invitation: input.invitation, signedOp };
+    const url = input.admitUrl ??
+        `${origin(input.nodeUrl)}/admin-api/namespaces/${input.namespaceId}/admit`;
+    const doFetch = input.deps?.fetch ?? fetch;
+    let response;
+    try {
+        response = await doFetch(url, {
+            method: 'POST',
+            // No Authorization header and no request proof, deliberately: the route is
+            // unauthenticated because the joiner's signature is the authorization.
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            step: 'admit',
+            reason: `The admitter at ${input.nodeUrl} could not be reached: ` +
+                `${e instanceof Error ? e.message : String(e)}. The invitation is untouched — this is ` +
+                'the node being unreachable, not a refusal.',
+        };
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        return {
+            ok: false,
+            step: 'admit',
+            status: response.status,
+            reason: explainAdmitFailure(response.status, text),
+        };
+    }
+    let published = false;
+    try {
+        const parsed = text ? JSON.parse(text) : {};
+        published = parsed.data?.published === true;
+    }
+    catch {
+        // A 2xx with a body this client cannot read is still a node that took the
+        // call. Reported as "not published" rather than as an error, because that is
+        // exactly what is not known.
+        published = false;
+    }
+    return {
+        ok: true,
+        published,
+        session: { relayUrl: origin(input.nodeUrl), account, credential, deviceSecret },
+    };
+}

package/dist/account/node-admin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A node's admin API, as an app writes against it: mero-js's `AdminApiClient`
+ * with `createNamespace` made whole. On a node a namespace can only be created
+ * for an application the node already holds, so this installs the provider's
+ * package from the registry first when it is missing — the step an account
+ * never sees, because founding through a relay names the package and the relay
+ * fetches it. Same call, same result, on both.
+ */
+import type { AdminApiClient } from '../admin-api/index.js';
+export interface NodeAdminDeps {
+    latestVersion?: (registryUrl: string, pkg: string) => Promise<string>;
+}
+export declare function createNodeAdmin(input: {
+    admin: AdminApiClient;
+    app: {
+        packageName?: string;
+        packageVersion?: string;
+        registryUrl?: string;
+    };
+}, deps?: NodeAdminDeps): AdminApiClient;

package/dist/account/node-admin.js

@@ -0,0 +1,33 @@
+import { latestPublishedVersion } from './create-context.js';
+export function createNodeAdmin(input, deps = {}) {
+    const { admin, app } = input;
+    const latestVersion = deps.latestVersion ?? latestPublishedVersion;
+    async function ensureInstalled(applicationId) {
+        const { apps } = await admin.listApplications();
+        if (apps.some((a) => a.id === applicationId))
+            return;
+        if (!app.packageName) {
+            throw new Error(`application ${applicationId} is not installed on this node, and no packageName is set to install it`);
+        }
+        const version = app.packageVersion ?? (await latestVersion(app.registryUrl ?? 'https://apps.calimero.network', app.packageName));
+        const { applicationId: installed } = await admin.installApplication({ package: app.packageName, version });
+        // A registry bundle signed by a different key is a different application:
+        // creating against it would found a workspace for some other app.
+        if (installed !== applicationId) {
+            throw new Error(`installed ${app.packageName}@${version} as ${installed}, not ${applicationId}`);
+        }
+    }
+    const overrides = {
+        async createNamespace(req) {
+            await ensureInstalled(req.applicationId);
+            return admin.createNamespace(req);
+        },
+    };
+    return new Proxy(admin, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && prop in overrides)
+                return overrides[prop];
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}

package/dist/account/relay-from-invitation.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Resolving a relay from an INVITATION rather than from an account.
+ *
+ * # The gap this closes
+ *
+ * `ConnectButtonAccount` finds a relay by asking the cloud what serves the
+ * *account* (`CloudClient.getAccountRelays`). A freshly enrolled account is a
+ * member of nothing, so that read correctly answers `[]` and the button
+ * correctly refuses to connect: there is nowhere to write, and a typed guess
+ * would be a node that refuses every warrant.
+ *
+ * But a newcomer is not stuck — they are holding an invitation, and an
+ * invitation names a namespace. `CloudClient.getNamespaceRouting` answers which
+ * nodes serve *that namespace*, and it is deliberately anonymous: a joiner has
+ * no cloud session, and needing one is exactly what this path exists to avoid.
+ * So the bootstrap order is namespace first, account second — admission is what
+ * makes `getAccountRelays` answer at all, not the other way round.
+ *
+ * # Two sources, one intersection, and why it must not be skipped
+ *
+ * The invitation's `admitters` list sits INSIDE the body the group admin
+ * signed, so it is authorization: merod answers `403` to an `/admit` from a node
+ * that list does not name, whatever else is true of it. The cloud's list is
+ * every node currently assigned to the namespace — it cannot know which
+ * invitation the caller holds, so it cannot filter by the signed list, and a
+ * node assigned *after* the invitation was minted looks perfect in every field
+ * the cloud reports and still refuses the claim.
+ *
+ * Intersecting here is therefore not belt-and-braces: it is the check that
+ * turns an unexplainable `403` into "your invitation names none of these nodes,
+ * ask for a fresh one". It is never relaxed to make a flow work.
+ *
+ * # `servable` and `canAdmit` are advisory; `writable` is information
+ *
+ * `servable` and `canAdmit` are derived from assignment heartbeats, and a lapsed
+ * heartbeat is not the same fact as a node that will refuse. Measured against
+ * prod: the cloud reported `servable: false, canAdmit: false, fresh: false` for a
+ * node whose `/admin-api/health` answered `{"status":"alive"}` and which had just
+ * minted the invitation being claimed. Gating on them meant refusing to knock on
+ * an open door, so a node with an address is tried and the NODE decides —
+ * `admit_join` re-verifies the invitation, the signature and the admitters list,
+ * so asking loosens nothing and a refusal names its own cause. `stale` on the
+ * result says the attempt rests on advisory data.
+ *
+ * `writable` — and its per-node form, `canExecute` — is about `CAN_AUTHOR_ON_BEHALF`,
+ * which admission does **not** require: relaying a join the joiner signed is not
+ * authoring on anyone's behalf. So a non-writable namespace is not a refusal
+ * here; it is reported on the result, because it is precisely why the writes
+ * would fail *after* connecting, and a caller that cannot tell the two apart
+ * sends the user to the wrong place.
+ */
+import { CloudClient } from '../cloud/index.js';
+/**
+ * Which step could not be completed. Each one needs a different action from the
+ * person, which is why this is an enum and not a message.
+ *
+ * - `admitters-lookup` — the cloud read itself failed (offline, 5xx, a refused
+ *   routing proof). Nothing has been learned about the namespace.
+ * - `no-nodes` — the read succeeded and the cloud lists nothing, and the
+ *   invitation carries no http(s) address of an admitter either. The namespace
+ *   has no fleet assignment, so there is no cloud node to admit through; the
+ *   invitation's admitters are somebody's self-hosted or desktop node, which the
+ *   cloud neither knows nor routes to.
+ * - `not-invited` — nodes serve the namespace, and the invitation names none of
+ *   them. Terminal for this invitation: ask for a fresh one.
+ * - `invited-unreachable` — a named node exists but cannot take a join now (no
+ *   fresh heartbeat, or the cloud reports the namespace as not servable). A
+ *   wait, not a wrong invitation.
+ * - `no-relay-url` — a named node can admit but the cloud knows no address for
+ *   it, so there is nothing to connect through afterwards. Also a wait: it is
+ *   the shape a node reports before its first heartbeat lands.
+ */
+export type RelayResolutionStep = 'admitters-lookup' | 'no-nodes' | 'not-invited' | 'invited-unreachable' | 'no-relay-url';
+/** A relay that can take this invitation's join, and connect afterwards. */
+export interface ResolvedInvitationRelay {
+    readonly ok: true;
+    /** The node origin to connect through. */
+    readonly relayUrl: string;
+    /** Where to POST the signed join — the cloud's own, never rebuilt when given. */
+    readonly admitUrl: string;
+    /**
+     * The admitter's account: as the cloud reported it, or — for a relay the
+     * invitation itself named — the one admitter it names, when it names one.
+     */
+    readonly admitterAccount: string | null;
+    /** The node's peer id as the cloud reported it; `null` for a relay the invitation named. */
+    readonly peerId: string | null;
+    /**
+     * Whether this node can also run delegated writes (`CAN_AUTHOR_ON_BEHALF`).
+     *
+     * `false` is not a failure of admission — see the module note. It means the
+     * connection that follows will read and receive events but have its intents
+     * refused, which an admin grants away, so it is worth saying out loud.
+     */
+    readonly writable: boolean;
+    /** Whether the chosen node's heartbeat for this namespace has lapsed. */
+    readonly stale: boolean;
+    /**
+     * Who named this relay: the cloud's routing, or the invitation's own
+     * `admitter_addrs` when the cloud routed the namespace to no node.
+     */
+    readonly via: 'cloud' | 'invitation';
+}
+export interface RelayResolutionFailure {
+    readonly ok: false;
+    readonly step: RelayResolutionStep;
+    /** What to go and do about it, in one sentence. */
+    readonly reason: string;
+}
+export type ResolveRelayResult = ResolvedInvitationRelay | RelayResolutionFailure;
+export interface ResolveRelayFromInvitationInput {
+    /** The namespace the invitation admits you to, 64 hex. */
+    readonly namespaceId: string;
+    /**
+     * The invitation's signed `admitters` — `invitation.invitation.admitters`.
+     *
+     * An EMPTY list is the legacy "admission by broadcast" shape, where any ready
+     * peer may admit, and is treated as such. Omitting the field and passing an
+     * empty array are therefore the same thing on purpose: there is no spelling
+     * here that means "nobody may admit", because an invitation cannot say that.
+     */
+    readonly admitters?: readonly string[];
+    /**
+     * The invitation's `admitter_addrs`: where its admitters are reached. Core
+     * emits libp2p multiaddrs here; an account minting through mero-react adds
+     * its relay's http(s) origin. Only the http(s) entries are of use to a
+     * browser, and only when the cloud routes the namespace to no node — the
+     * case of a namespace whose founder never linked the account, which the
+     * cloud does not route yet whose own relay admits.
+     */
+    readonly admitterAddrs?: readonly string[];
+    /** The delegated credential — an `AccountProof<DeviceCert>`, hex. */
+    readonly credential: string;
+    /** The certified device's ed25519 signing secret, hex. */
+    readonly deviceSecret: string;
+    /** Point at a cloud other than the hosted manager. For local rigs. */
+    readonly cloudBaseUrl?: string;
+    /** Injected in tests. Anything with the one method this needs. */
+    readonly cloud?: Pick<CloudClient, 'getNamespaceRouting'>;
+}
+/**
+ * Normalise a hex account for comparison: lower-cased, `0x` stripped.
+ *
+ * Both sides are hex for the same 32 bytes, and a spelling mismatch would
+ * present as "your invitation does not name this node" — a refusal that looks
+ * like policy and is really formatting.
+ */
+export declare function normaliseAccount(account: string | null | undefined): string | null;
+/**
+ * Resolve a relay to bootstrap through, from an invitation and nothing else.
+ *
+ * Reads the cloud's routing for the namespace, intersects it with the
+ * invitation's signed `admitters`, and returns the node to use — or which step
+ * stopped it and what that means. It performs no admission and mints no keys:
+ * the credential passed in is the one the wallet already certified.
+ */
+export declare function resolveRelayFromInvitation(input: ResolveRelayFromInvitationInput): Promise<ResolveRelayResult>;