@calimero-network/mero-js 23.8.2 → 24.0.0

package/dist/account/relay-from-invitation.js

@@ -0,0 +1,216 @@
+/**
+ * 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';
+/**
+ * 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 function normaliseAccount(account) {
+    if (!account)
+        return null;
+    const trimmed = account.trim().toLowerCase();
+    const bare = trimmed.startsWith('0x') ? trimmed.slice(2) : trimmed;
+    return bare.length > 0 ? bare : null;
+}
+/** The http(s) origins among an invitation's admitter addresses, trailing slash dropped. */
+function httpAdmitterOrigins(addrs) {
+    const out = [];
+    for (const addr of addrs ?? []) {
+        try {
+            const url = new URL(addr);
+            if (url.protocol === 'http:' || url.protocol === 'https:')
+                out.push(addr.replace(/\/+$/, ''));
+        }
+        catch {
+            // A multiaddr, or nothing a browser can dial.
+        }
+    }
+    return out;
+}
+/** Whether the invitation's signed list names this node. */
+function isInvited(node, invited) {
+    if (invited.size === 0)
+        return true;
+    const account = normaliseAccount(node.account);
+    return account !== null && invited.has(account);
+}
+/**
+ * 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 async function resolveRelayFromInvitation(input) {
+    const cloud = input.cloud ??
+        new CloudClient({
+            cloudBaseUrl: input.cloudBaseUrl,
+            routingCredential: { credential: input.credential, deviceSecret: input.deviceSecret },
+        });
+    let nodes;
+    let servable;
+    try {
+        const routing = await cloud.getNamespaceRouting(input.namespaceId);
+        nodes = routing.nodes;
+        servable = routing.servable;
+    }
+    catch (e) {
+        // Named as its own step: nothing has been learned about the namespace, so
+        // reporting this as "no nodes serve it" would be a claim the read never
+        // made — and would send the user to ask for a new invitation over what is
+        // usually a refused proof or a network blip.
+        return {
+            ok: false,
+            step: 'admitters-lookup',
+            reason: `The cloud could not be asked which nodes serve namespace ${input.namespaceId}: ` +
+                `${e instanceof Error ? e.message : String(e)}. Nothing is known about the ` +
+                'invitation yet — this is the lookup failing, not the invitation.',
+        };
+    }
+    if (nodes.length === 0) {
+        // The cloud routes nothing, but the invitation may say where an admitter
+        // is: an account's relay writes its origin into `admitter_addrs` when it
+        // mints for a namespace the cloud does not host. The relay's `admit_join`
+        // re-verifies the invitation and its admitters, so nothing is loosened by
+        // knocking there; the account is the invitation's, when it names one.
+        const [relayUrl] = httpAdmitterOrigins(input.admitterAddrs);
+        if (relayUrl) {
+            const admitters = (input.admitters ?? []).map(normaliseAccount).filter((a) => a !== null);
+            return {
+                ok: true,
+                relayUrl,
+                admitUrl: `${relayUrl}/admin-api/namespaces/${input.namespaceId}/admit`,
+                admitterAccount: admitters.length === 1 ? admitters[0] : null,
+                peerId: null,
+                // The relay a founder's session runs through executes that founder's
+                // warrants, so it authors on behalf; the node's answer to the first
+                // write is the authoritative one, as for a cloud-routed node.
+                writable: true,
+                stale: false,
+                via: 'invitation',
+            };
+        }
+        return {
+            ok: false,
+            step: 'no-nodes',
+            reason: 'The cloud lists no nodes serving this namespace, so there is no hosted node to be ' +
+                'admitted through. The namespace has no fleet assignment — whoever invited you is ' +
+                'running their own node, and admission has to go through a node the cloud routes to.',
+        };
+    }
+    const invited = new Set((input.admitters ?? [])
+        .map(normaliseAccount)
+        .filter((a) => a !== null));
+    const named = nodes.filter((n) => isInvited(n, invited));
+    if (named.length === 0) {
+        return {
+            ok: false,
+            step: 'not-invited',
+            reason: `${nodes.length} node${nodes.length === 1 ? '' : 's'} serve this namespace, but your ` +
+                'invitation names none of them. The signed admitter list is a snapshot from when the ' +
+                'invitation was minted, so a node assigned since is healthy and will still refuse the ' +
+                'claim. Ask for a fresh invitation.',
+        };
+    }
+    // `canAdmit` and `servable` are ADVISORY here, not gates.
+    //
+    // They 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. Refusing on those flags meant refusing to
+    // knock on a door that was open.
+    //
+    // So a node with an address is tried, and the node itself decides. Its answer
+    // is the authoritative one: `admit_join` re-verifies the invitation, the
+    // signature and the admitters list, so nothing is loosened by asking — the
+    // worst case is a 403 that names its own cause, which is strictly better than
+    // a client-side guess that names a heartbeat.
+    const usable = named.filter((n) => n.canAdmit);
+    const candidates = usable.length > 0 ? usable : named;
+    const advisory = usable.length === 0 || !servable;
+    const addressable = candidates.filter((n) => typeof n.relayUrl === 'string' && n.relayUrl.length > 0);
+    if (addressable.length === 0) {
+        return {
+            ok: false,
+            step: 'no-relay-url',
+            reason: 'A node your invitation names can admit you, but the cloud knows no address for it ' +
+                'yet, so there would be nothing to connect through afterwards. Try again shortly.',
+        };
+    }
+    // Prefer a node that can do both legs — admit now and author later — so the
+    // session lands on one node where possible. Preference only: admission is the
+    // step that cannot proceed without a node, and authorship is not on the
+    // invitation's list at all, so insisting would refuse a perfectly good
+    // admitter for a permission admission never needed.
+    const chosen = addressable.find((n) => n.canExecute) ?? addressable.find((n) => n.fresh) ?? addressable[0];
+    return {
+        ok: true,
+        relayUrl: chosen.relayUrl,
+        // The cloud's ready-made URL when it gave one, so the path is never rebuilt
+        // from a guess; the fallback is the documented route on the same origin.
+        admitUrl: chosen.admitUrl ??
+            `${chosen.relayUrl.replace(/\/+$/, '')}/admin-api/namespaces/${input.namespaceId}/admit`,
+        admitterAccount: chosen.account,
+        peerId: chosen.peerId,
+        writable: chosen.canExecute,
+        // Stale when the node's own heartbeat lapsed OR when the cloud's summary
+        // disagrees with trying it at all. Both mean the same thing to a caller:
+        // this was attempted on advisory data, so if the admit fails that is why.
+        stale: !chosen.fresh || advisory,
+        via: 'cloud',
+    };
+}

package/dist/account/session.d.ts

@@ -0,0 +1,214 @@
+import { type MeroClient } from '../transport/index.js';
+/**
+ * What a delegated connection needs to be rebuilt after a reload.
+ *
+ * `deviceSecret` is here because the device key is what signs warrants, and a
+ * reload that could not sign would be a dead session. It is a per-tab secret for
+ * a certificate the account can revoke — not the account root, which never
+ * leaves the wallet's origin.
+ */
+/**
+ * What the wallet certified: an account, a device it trusts, and the key that
+ * device signs with. Everything except somewhere to send the result.
+ *
+ * Split out of {@link DelegatedSession} because it is reachable one step
+ * earlier. An account that has just enrolled holds exactly this and no relay —
+ * it is a member of nothing, so the cloud has no relay to name — and this is the
+ * input that resolves one from an invitation instead.
+ */
+export interface DelegatedCredential {
+    /** The author's account id, hex. */
+    account: string;
+    /** The author's `AccountProof<DeviceCert>`, hex borsh. */
+    credential: string;
+    /** The certified device's ed25519 signing secret, hex. */
+    deviceSecret: string;
+}
+export interface DelegatedSession extends DelegatedCredential {
+    /**
+     * The relay to write through — a node origin, or `null` for none yet.
+     *
+     * **`null` is a logged-in state, not a broken one.** A brand-new account is a
+     * member of nothing, so the cloud names no relay for it — and that is the
+     * normal condition of an account that has just been created, because being
+     * signed in is how you come to be invited in the first place. Refusing to
+     * connect without a relay locked a new account out of the only path that
+     * would earn it one.
+     *
+     * What it does NOT mean is that writes quietly do nothing. There is no
+     * client at all without a URL ({@link buildDelegatedClient} returns `null`),
+     * so `mero` stays `null`, the session is authenticated, and anything reaching
+     * for `rpc.execute` is told the relay is missing. A placeholder URL would be
+     * the one unacceptable answer: it would look connected and refuse every
+     * warrant.
+     */
+    relayUrl: string | null;
+    /**
+     * The relay's executor account, hex, when the app knows it — the cloud's
+     * machine page names it beside the relay's address.
+     *
+     * Founding a namespace through a relay names the relay's account in the
+     * warrant, and a namespace that does not exist yet cannot be asked for it.
+     * Without this the account learns it from a namespace it is already in, so a
+     * brand-new account would have to join one first; with it, the account founds
+     * on `relayUrl` directly.
+     */
+    executorAccount?: string | null;
+}
+export declare function readDelegatedSession(): DelegatedSession | null;
+export declare function saveDelegatedSession(s: DelegatedSession): void;
+export declare function clearDelegatedSession(): void;
+/**
+ * The enrolled credential, whether or not a relay was ever found for it.
+ *
+ * A connected session is authoritative: it carries the same three fields and a
+ * relay, so it is read first and the standalone record is the fallback. Without
+ * that order a stale record from an earlier enrolment could out-rank the account
+ * actually connected.
+ */
+export declare function readDelegatedCredential(): DelegatedCredential | null;
+export declare function saveDelegatedCredential(c: DelegatedCredential): void;
+export declare function clearDelegatedCredential(): void;
+/**
+ * A warrant nonce is spent on the node, so the counter must outlive the page.
+ *
+ * In `localStorage`, not session: a reload that restarted from zero would
+ * replay a spent nonce and be refused. Keyed by relay and context because the
+ * ledger the node keeps is per `(context, author device)`.
+ *
+ * This is the client-side half of core #4018. The node can answer "where does
+ * my sequence stand" — `POST /contexts/{id}/warrant-nonce` with the caller's own
+ * `authorProof` — but that route is mounted on the protected router, so a
+ * delegated client on a relay cannot reach it. Until it moves, holding the
+ * counter locally is the only option, and losing storage means burning refusals
+ * until the counter catches up.
+ */
+export declare function persistedNonces(relayUrl: string): {
+    next: () => Promise<bigint>;
+};
+/**
+ * Record that `nonce` is spent for this device, so later intents start above
+ * it. A creation warrant's nonce is spent in the NEW context's own window; one
+ * sequence per relay covers that context like any other.
+ */
+export declare function markContextNonceSpent(relayUrl: string, _contextId: string, nonce: bigint): void;
+/**
+ * Pin a relay's device signing key, hex (32 bytes), learned out of band.
+ *
+ * `login()` binds the session to this key, and it must never be read from the
+ * relay being logged in to — the answering party would choose what the device
+ * signs about. Until the cloud publishes it (mdma#312), it comes from the
+ * relay's operator.
+ */
+export declare function pinRelayNodeKey(relayUrl: string, nodeKey: string): void;
+/** The pinned key for a relay, or `null` if none was pinned. */
+export declare function readPinnedRelayNodeKey(relayUrl: string): string | null;
+/**
+ * One attempt at a relay's node key, and what became of it:
+ *
+ * - `learned`: verified (or already pinned), and pinned now;
+ * - `unavailable`: something on the way did not answer — the relay, the release
+ *   mirror, the quote library's download. Nothing was decided; try again.
+ * - `refused`: the relay answered and its proof did not hold — a quote that is
+ *   not of a trusted image, not bound to this request, a mock from a hosted
+ *   relay. Trying again cannot change that answer into a yes, and must not.
+ */
+export type RelayNodeKeyAttempt = {
+    kind: 'learned';
+    nodeKey: string;
+} | {
+    kind: 'unavailable';
+    error: unknown;
+} | {
+    kind: 'refused';
+    error: unknown;
+};
+export declare function attemptRelayNodeKey(relayUrl: string): Promise<RelayNodeKeyAttempt>;
+/**
+ * The relay's node key: the pinned one, or else learned from the relay's TEE
+ * attestation in one attempt; `null` when that attempt did not learn it, for
+ * whatever reason. Callers that must end up with the key use
+ * {@link learnRelayNodeKey}.
+ */
+export declare function resolveRelayNodeKey(relayUrl: string): Promise<string | null>;
+/**
+ * How long to wait before each retry of an unavailable relay key: quickly at
+ * first, for a blip or a cold cache, then every 30 s for as long as it takes.
+ */
+export declare const RELAY_NODE_KEY_RETRY_MS: readonly number[];
+/**
+ * The relay's node key, however long the way to it is down.
+ *
+ * One failed fetch of the release used to cost the whole session: no key, so no
+ * relay session, so every admin read and every event stream unauthenticated
+ * until a reload. A transport failure here is now waited out with backoff
+ * ({@link RELAY_NODE_KEY_RETRY_MS}) until the key is learned or `signal` aborts.
+ *
+ * A refusal ends it at once with `null`. A quote that did not verify is an
+ * answer, and asking again is not how it becomes a different one.
+ */
+export declare function learnRelayNodeKey(relayUrl: string, options?: {
+    signal?: AbortSignal;
+}): Promise<string | null>;
+/** Forget what was learned about which methods read. For tests. */
+export declare function forgetMethodKinds(): void;
+/**
+ * Build the client a delegated session talks through.
+ *
+ * The result is a relay-transport `MeroClient`. Its `rpc.execute` takes the same
+ * named arguments a node client's does, which is what lets a generated ABI
+ * client — and every hook that only calls `execute` — work unchanged. What it
+ * also has is `admin` and `events`, pointed at the relay and authenticated as
+ * the account by the device certificate, so the caller-scoped reads answer this
+ * account's own contexts and namespaces rather than the node's.
+ */
+export declare function buildDelegatedClient(s: DelegatedSession, _contextId: string | null): MeroClient | null;
+export interface RelayMap {
+    namespaces: Record<string, string>;
+    contexts: Record<string, string>;
+}
+export declare function readRelayMap(account: string): RelayMap;
+/** Record the relay that admitted this account to a namespace (and, when known, the context it came for). */
+export declare function rememberRelay(account: string, relayUrl: string, at: {
+    namespaceId?: string;
+    contextId?: string;
+}): void;
+/** The relay that serves a context, if this account has learned it. */
+export declare function relayForContext(account: string, contextId: string): string | null;
+/**
+ * A session moving to `next`, keeping the relay's executor account the previous
+ * one knew when both are the same relay.
+ *
+ * A join hands back a session built from the admitting node alone, which has no
+ * executor on it. When that node is the relay the account was already on — the
+ * one the cloud assigned it, say — dropping the executor would cost nothing
+ * today (the joined namespace can answer for it) but leaves the session knowing
+ * less than it did. On a different relay the old executor is the wrong account,
+ * so it is left behind.
+ */
+export declare function carryExecutorAccount(prev: DelegatedSession | null, next: DelegatedSession): DelegatedSession;
+/** Every relay this account is known to use: the session's, and each in the map. */
+export declare function knownRelays(s: DelegatedSession): string[];
+type ListedContext = Awaited<ReturnType<MeroClient['admin']['getContexts']>>['contexts'][number];
+/**
+ * This account's contexts on every relay it knows, each tagged with the relay
+ * that listed it — and that relay recorded as the one serving it.
+ *
+ * Each relay answers only for itself and only for this caller, so the union is
+ * exactly the account's contexts across relays. A relay that cannot be reached
+ * or logged in to is skipped (its contexts simply do not appear), not fatal.
+ */
+export declare function listDelegatedContexts(s: DelegatedSession): Promise<Array<ListedContext & {
+    relayUrl: string;
+}>>;
+type ListedNamespace = Awaited<ReturnType<MeroClient['admin']['listNamespaces']>>[number];
+/**
+ * This account's namespaces on every relay it knows, each tagged with the relay
+ * that listed it and recorded as that namespace's relay. Same rules as
+ * {@link listDelegatedContexts}: each relay answers for itself and this caller
+ * only (`namespace:list-own`); an unreachable relay is skipped.
+ */
+export declare function listDelegatedNamespaces(s: DelegatedSession): Promise<Array<ListedNamespace & {
+    relayUrl: string;
+}>>;
+export {};