@calimero-network/mero-js 23.8.2 → 24.0.0

package/dist/account/application-id.js

@@ -0,0 +1,83 @@
+/**
+ * An application's id, computed the way merod computes it.
+ *
+ * core's `ApplicationId::for_bundle(package, signer_id)` is
+ * `sha256(borsh((package, signer_id)))`: the package name and the publisher's
+ * signing key together decide which app a bundle IS, and the version is not an
+ * input, so every version a publisher ships under one package installs as the
+ * same application. A node learns the id when it installs the bundle; an
+ * account installs nothing, so it has to derive the id from the same two
+ * inputs — both of which the registry's bundle listing carries.
+ */
+/** Borsh `String`: u32 little-endian byte length, then the UTF-8 bytes. */
+function borshString(s) {
+    const bytes = new TextEncoder().encode(s);
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+/**
+ * `sha256(borsh((pkg, signerId)))` as lowercase hex: core's
+ * `ApplicationId::for_bundle`. A borsh tuple is its fields concatenated.
+ */
+export async function applicationIdForBundle(pkg, signerId) {
+    const a = borshString(pkg);
+    const b = borshString(signerId);
+    const tuple = new Uint8Array(a.length + b.length);
+    tuple.set(a, 0);
+    tuple.set(b, a.length);
+    const digest = await crypto.subtle.digest('SHA-256', tuple);
+    return Array.from(new Uint8Array(digest), (x) => x.toString(16).padStart(2, '0')).join('');
+}
+/** Whether `a` is a newer version string than `b` (numeric, dot/dash split). */
+function newer(a, b) {
+    const [x, y] = [a, b].map((v) => v.split(/[.-]/).map((n) => Number.parseInt(n, 10) || 0));
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    }
+    return false;
+}
+/**
+ * The entry a package resolves to: its newest version that is not yanked. The
+ * one rule for "latest", shared by the version lookup and the id derivation so
+ * the two cannot disagree about which bundle an account is founding on.
+ */
+export function selectLatestBundle(bundles) {
+    return bundles
+        .filter((b) => !b.yanked && typeof b.appVersion === 'string' && b.appVersion.length > 0)
+        .reduce((best, b) => (!best || newer(b.appVersion, best.appVersion) ? b : best), undefined);
+}
+/** The registry's listing of `pkg`, every version. */
+export async function fetchRegistryBundles(registryUrl, pkg, fetchFn = globalThis.fetch) {
+    const url = `${registryUrl.replace(/\/+$/, '')}/api/v2/bundles?package=${encodeURIComponent(pkg)}`;
+    const response = await fetchFn(url, { headers: { Accept: 'application/json' } });
+    if (!response.ok)
+        throw new Error(`the registry has no ${pkg} (HTTP ${response.status})`);
+    const body = (await response.json());
+    return Array.isArray(body) ? body : [];
+}
+/**
+ * The application id an account founds `pkg` on, learned from the registry.
+ *
+ * Refused when the non-yanked versions of `pkg` name more than one publisher:
+ * that is two different applications under one package name (the id binds the
+ * signer), and picking either silently would commit the founder — who signs
+ * `TargetApplicationSet` naming the id — to an app it did not choose.
+ */
+export async function resolveApplicationIdFromRegistry(registryUrl, pkg, deps = {}) {
+    const bundles = await fetchRegistryBundles(registryUrl, pkg, deps.fetch);
+    const live = bundles.filter((b) => !b.yanked);
+    const signers = [...new Set(live.map((b) => b.signerId).filter((s) => typeof s === 'string' && s.length > 0))];
+    if (signers.length > 1) {
+        throw new Error(`the registry lists ${pkg} under more than one publisher (${signers.join(', ')}): refusing to guess which application it is`);
+    }
+    const latest = selectLatestBundle(live);
+    if (!latest)
+        throw new Error(`the registry lists no version of ${pkg}`);
+    const signerId = latest.signerId;
+    if (!signerId)
+        throw new Error(`the registry names no publisher for ${pkg} ${latest.appVersion}`);
+    return { applicationId: await applicationIdForBundle(pkg, signerId), signerId, version: latest.appVersion };
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Bootstrapping an account that is a member of nothing, from an invitation.
+ *
+ * # The one missing step
+ *
+ * A freshly enrolled account holds a certified device and belongs to no
+ * namespace, so `CloudClient.getAccountRelays` answers `[]` — correctly, because
+ * nothing serves an account that is a member of nothing. It is still signed in;
+ * what it has no way to do is write. An invitation is what changes that, and the
+ * chain is:
+ *
+ *     invitation → namespaceId → a node URL
+ *                → POST the signed join to that node  → the account is a member
+ *                → that same node is the relay, from this moment
+ *                → a fleet relay writes the recovery envelope asynchronously,
+ *                  and getAccountRelays() agrees from then on
+ *
+ * The session does not wait for the cloud to catch up. The node that carried the
+ * join is known to serve the namespace now; the lookup will agree later.
+ *
+ * # Where the node URL comes from, in preference order
+ *
+ * 1. one passed in — an operator's, or one a future invitation carries. Core
+ *    today emits only libp2p multiaddrs on an invitation (`resolve_admitter_addrs`)
+ *    because a node cannot know the URL its admin API is proxied on, so there is
+ *    nothing to read off the invitation yet and this is the seam for when there
+ *    is;
+ * 2. the cloud's `/api/cloud/namespaces/{ns}/admitters`, intersected with the
+ *    invitation's signed `admitters` — see `resolveRelayFromInvitation`;
+ * 3. an http(s) origin in the invitation's `admitter_addrs`, when the cloud
+ *    routes the namespace to no node: the relay of a founder who never linked
+ *    the account writes its own origin there when it mints.
+ *
+ * # Nothing here is minted, weakened or worked around
+ *
+ * The credential and the device secret come from the enrolment the wallet
+ * already performed. The op is signed by that device key, which is what stops an
+ * admitter substituting a different member. The admitters intersection is done in
+ * `resolveRelayFromInvitation` and is never relaxed.
+ */
+import type { SignedGroupOpenInvitation } from '../admin-api/index.js';
+import type { DelegatedCredential, DelegatedSession } from './session.js';
+import { joinWithNode, type JoinWithNodeStep } from './join-with-node.js';
+import { resolveRelayFromInvitation, type RelayResolutionStep, type ResolvedInvitationRelay } from './relay-from-invitation.js';
+/**
+ * Which step failed. One exhaustive list to branch on: the relay-resolution
+ * steps, the two `joinWithNode` reports, and the one only a hook can hit.
+ *
+ * - `no-credential` — this tab holds no enrolled account, so there is nothing to
+ *   admit. Only {@link useDelegatedBootstrap} can report it;
+ *   `bootstrapFromInvitation` is handed the credential as an argument.
+ */
+export type BootstrapStep = RelayResolutionStep | JoinWithNodeStep | 'no-credential';
+export interface BootstrapSuccess {
+    readonly ok: true;
+    /** The session to connect with — hand it straight to `connectWithAccount`. */
+    readonly session: DelegatedSession;
+    /**
+     * How the node was chosen, when the cloud chose it.
+     *
+     * `null` when the caller named the node itself, because then there was no
+     * routing read to report — not because anything was skipped.
+     */
+    readonly relay: ResolvedInvitationRelay | null;
+    /**
+     * 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. `false` with no error means the node
+     * took the call and did not publish — worth surfacing rather than treating as
+     * success.
+     */
+    readonly published: boolean;
+}
+export interface BootstrapFailure {
+    readonly ok: false;
+    readonly step: BootstrapStep;
+    readonly reason: string;
+    /** The HTTP status, when the failing step was an HTTP call. */
+    readonly status?: number;
+}
+export type BootstrapResult = BootstrapSuccess | BootstrapFailure;
+export interface BootstrapFromInvitationInput {
+    /** The namespace the invitation admits you to, 64 hex. */
+    readonly namespaceId: string;
+    /** The invitation, exactly as the inviter's node returned it. */
+    readonly invitation: SignedGroupOpenInvitation;
+    /** The enrolled account, its certificate, and the device secret. */
+    readonly credential: DelegatedCredential;
+    /**
+     * A node to present the join to, skipping the cloud lookup.
+     *
+     * Use it when something already knows the node — an operator, a local rig, or
+     * an invitation that carries a claim URL once core emits one. Without it the
+     * cloud's admitters lookup answers, and the invitation's signed list is what
+     * narrows the answer.
+     */
+    readonly nodeUrl?: string;
+    /** Point at a cloud other than the hosted manager. For local rigs. */
+    readonly cloudBaseUrl?: string;
+    /** Injected in tests. */
+    readonly deps?: {
+        readonly resolve?: typeof resolveRelayFromInvitation;
+        readonly join?: typeof joinWithNode;
+        readonly fetch?: typeof fetch;
+        readonly nonce?: () => Promise<bigint>;
+    };
+}
+/**
+ * Resolve a node from the invitation, present the signed join to it, and return
+ * the session to connect with.
+ *
+ * Never throws for an expected failure: every one of them is a different thing
+ * for the person to do, so they come back as `{ ok: false, step, reason }`. A
+ * generic "could not join" is exactly what this shape exists to prevent.
+ */
+export declare function bootstrapFromInvitation(input: BootstrapFromInvitationInput): Promise<BootstrapResult>;

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

@@ -0,0 +1,86 @@
+/**
+ * Bootstrapping an account that is a member of nothing, from an invitation.
+ *
+ * # The one missing step
+ *
+ * A freshly enrolled account holds a certified device and belongs to no
+ * namespace, so `CloudClient.getAccountRelays` answers `[]` — correctly, because
+ * nothing serves an account that is a member of nothing. It is still signed in;
+ * what it has no way to do is write. An invitation is what changes that, and the
+ * chain is:
+ *
+ *     invitation → namespaceId → a node URL
+ *                → POST the signed join to that node  → the account is a member
+ *                → that same node is the relay, from this moment
+ *                → a fleet relay writes the recovery envelope asynchronously,
+ *                  and getAccountRelays() agrees from then on
+ *
+ * The session does not wait for the cloud to catch up. The node that carried the
+ * join is known to serve the namespace now; the lookup will agree later.
+ *
+ * # Where the node URL comes from, in preference order
+ *
+ * 1. one passed in — an operator's, or one a future invitation carries. Core
+ *    today emits only libp2p multiaddrs on an invitation (`resolve_admitter_addrs`)
+ *    because a node cannot know the URL its admin API is proxied on, so there is
+ *    nothing to read off the invitation yet and this is the seam for when there
+ *    is;
+ * 2. the cloud's `/api/cloud/namespaces/{ns}/admitters`, intersected with the
+ *    invitation's signed `admitters` — see `resolveRelayFromInvitation`;
+ * 3. an http(s) origin in the invitation's `admitter_addrs`, when the cloud
+ *    routes the namespace to no node: the relay of a founder who never linked
+ *    the account writes its own origin there when it mints.
+ *
+ * # Nothing here is minted, weakened or worked around
+ *
+ * The credential and the device secret come from the enrolment the wallet
+ * already performed. The op is signed by that device key, which is what stops an
+ * admitter substituting a different member. The admitters intersection is done in
+ * `resolveRelayFromInvitation` and is never relaxed.
+ */
+import { joinWithNode } from './join-with-node.js';
+import { resolveRelayFromInvitation, } from './relay-from-invitation.js';
+/**
+ * Resolve a node from the invitation, present the signed join to it, and return
+ * the session to connect with.
+ *
+ * Never throws for an expected failure: every one of them is a different thing
+ * for the person to do, so they come back as `{ ok: false, step, reason }`. A
+ * generic "could not join" is exactly what this shape exists to prevent.
+ */
+export async function bootstrapFromInvitation(input) {
+    const resolve = input.deps?.resolve ?? resolveRelayFromInvitation;
+    const join = input.deps?.join ?? joinWithNode;
+    let relay = null;
+    let nodeUrl = input.nodeUrl;
+    let admitUrl;
+    if (!nodeUrl) {
+        const resolved = await resolve({
+            namespaceId: input.namespaceId,
+            // The signed list, read off the invitation itself rather than passed
+            // separately: two sources for one fact is how an intersection ends up
+            // being performed against the wrong list.
+            admitters: input.invitation.invitation.admitters,
+            admitterAddrs: input.invitation.admitter_addrs,
+            credential: input.credential.credential,
+            deviceSecret: input.credential.deviceSecret,
+            cloudBaseUrl: input.cloudBaseUrl,
+        });
+        if (resolved.ok === false)
+            return resolved;
+        relay = resolved;
+        nodeUrl = resolved.relayUrl;
+        admitUrl = resolved.admitUrl;
+    }
+    const joined = await join({
+        nodeUrl,
+        admitUrl,
+        namespaceId: input.namespaceId,
+        invitation: input.invitation,
+        credential: input.credential,
+        deps: { fetch: input.deps?.fetch, nonce: input.deps?.nonce },
+    });
+    if (joined.ok === false)
+        return joined;
+    return { ok: true, published: joined.published, relay, session: joined.session };
+}

package/dist/account/create-context.d.ts

@@ -0,0 +1,105 @@
+import { type GovernanceOp } from '../warrant/index.js';
+import { type DelegatedSession } from './session.js';
+/**
+ * What an account asks for when it creates a context: the fields of a node's
+ * `CreateContextRequest` that have a place in the creation warrant
+ * (mero-js `CreationWarrantInput`), plus which namespace to find the relay by.
+ *
+ * Intentionally NOT here, because the warrant has no field for it:
+ * `identitySecret` — a node's key for its new member identity; the account IS
+ * the member identity here (`init` runs as the author's account), so there is
+ * nothing to derive one from.
+ */
+export interface CreateDelegatedContextRequest {
+    readonly namespaceId: string;
+    /** The group to create it in; the namespace itself when omitted. */
+    readonly groupId?: string;
+    readonly applicationId: string;
+    /**
+     * Which service of a multi-service bundle the context is for; absent for
+     * the bundle's default service. Signed into the warrant: the relay runs THAT
+     * service's `init`, so a bundle like mero-docs (`registry`, `docs`) creates
+     * the right contract.
+     */
+    readonly serviceName?: string;
+    /** The seed the context id is derived from, hex (32 bytes); random when absent. */
+    readonly contextSeed?: string;
+    readonly initializationParams?: number[];
+    readonly name?: string;
+}
+export declare function createDelegatedContext(s: DelegatedSession, req: CreateDelegatedContextRequest, deps?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    contextId: string;
+}>;
+/** Publish one delegable governance op through the namespace's relay. */
+export declare function delegatedGovernance(s: DelegatedSession, req: {
+    namespaceId: string;
+    group: string;
+    op: GovernanceOp;
+}, deps?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    groupId: string;
+}>;
+/**
+ * A context only the author and `members` are in (a DM, a small room): a
+ * restricted subgroup of the namespace (a root op, posted to the namespace),
+ * each member added to it directly — they are in the namespace already, so
+ * nobody is invited — and the context created inside it. The relay that
+ * creates the subgroup is seated in it with CAN_AUTHOR_ON_BEHALF by core.
+ */
+export declare function createDelegatedPrivateContext(s: DelegatedSession, req: CreateDelegatedContextRequest & {
+    readonly members: readonly string[];
+}, deps?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    contextId: string;
+    groupId: string;
+}>;
+/**
+ * Found a namespace as the account, through a relay it already uses. The
+ * account becomes founder, owner and admin; the relay is seated in it (and a
+ * TEE relay admits itself as its first TEE), so contexts can be created in it
+ * through the same relay straight away.
+ *
+ * The relay's executor account cannot be asked about a namespace that does
+ * not exist yet, so it is the session's `executorAccount` when the app named
+ * one, else learned from a namespace the account already has on that relay. A
+ * brand-new account with neither is told how to get one.
+ */
+export declare function foundDelegatedNamespace(s: DelegatedSession, req?: {
+    readonly defaultCapabilities?: number;
+    /** The application the namespace runs; without one no context can be created in it. */
+    readonly application?: {
+        applicationId: string;
+        package: string;
+        version: string;
+    };
+}, deps?: {
+    fetch?: typeof fetch;
+    /** The cloud to enable HA on; mero-js's default when unset. */
+    cloudBaseUrl?: string;
+}): Promise<FoundedDelegatedNamespace>;
+/** What {@link foundDelegatedNamespace} returns. */
+export interface FoundedDelegatedNamespace {
+    namespaceId: string;
+    teeEnabled: boolean;
+    /** Whether the cloud agreed to host the namespace (HA) right after founding. */
+    haEnabled: boolean;
+    /** Why `haEnabled` is `false`, in words a person can act on. */
+    haError?: string;
+}
+/** What an app can tell a person whose account the cloud cannot place. */
+export declare const HA_ACCOUNT_NOT_LINKED_MESSAGE = "link this account to your cloud user in the wallet so invitees can find this namespace";
+/**
+ * What to tell a person for each refusal the cloud names, keyed by its code.
+ * Every one leaves the namespace founded; only hosting was refused.
+ */
+export declare const HA_REFUSAL_MESSAGES: Record<string, string>;
+/**
+ * The latest version of `pkg` the registry publishes. Used when the app names
+ * its package but not a version. Same selection as the id derivation
+ * ({@link selectLatestBundle}): the newest version that is not yanked.
+ */
+export declare function latestPublishedVersion(registryUrl: string, pkg: string, fetchFn?: typeof fetch): Promise<string>;

package/dist/account/create-context.js

@@ -0,0 +1,237 @@
+/**
+ * An account's governance through the relay that serves its namespace: create
+ * a context, and the group ops a private context (a DM) needs.
+ *
+ * A thin layer over mero-js's `RelayClient.createContext` / `govern` (core's
+ * `/admin-api/groups/{group}/context-intents` and `.../governance-intents`),
+ * adding what only this package knows: which relay serves the namespace (the
+ * relay map), and the nonce bookkeeping across page loads.
+ *
+ * Nodes check the AUTHOR's rights (CAN_CREATE_CONTEXT, CAN_CREATE_SUBGROUP,
+ * MANAGE_MEMBERS…), never the relay's; the relay only needs standing to act.
+ */
+import { AccountHaRefusedError, AccountNotLinkedError, CloudClient, } from '../cloud/index.js';
+import { memberAddedOp, subgroupCreation, } from '../warrant/index.js';
+import { RelayClient, } from '../relay/index.js';
+import { knownRelays, markContextNonceSpent, readRelayMap, rememberRelay } from './session.js';
+import { fetchRegistryBundles, selectLatestBundle } from './application-id.js';
+/**
+ * A governance warrant's nonce, for one (relay, group): spent in a sliding
+ * per-(group, device) window 64 wide, so it must never go backwards. A stored
+ * counter, floored at the clock so a cleared storage resumes above anything
+ * spent before rather than replaying it.
+ */
+function governanceNonce(relay, group) {
+    return { next: async () => nextGovernanceNonce(relay, group) };
+}
+function nextGovernanceNonce(relay, group) {
+    const key = `calimero.governance-nonce.${relay}.${group}`;
+    let last = 0n;
+    try {
+        last = BigInt(localStorage.getItem(key) ?? '0');
+    }
+    catch {
+        /* no storage: the clock floor alone */
+    }
+    const next = [last + 1n, BigInt(Date.now())].reduce((a, b) => (a > b ? a : b));
+    try {
+        localStorage.setItem(key, String(next));
+    }
+    catch {
+        /* unpersisted */
+    }
+    return next;
+}
+function relayFor(s, namespaceId) {
+    // The relay that serves this namespace: learned when the account joined it.
+    const url = readRelayMap(s.account).namespaces[namespaceId] ?? s.relayUrl;
+    if (!url)
+        throw new Error('no relay is known for this namespace, so there is nowhere to send this');
+    return url.replace(/\/+$/, '');
+}
+/** The `init` arguments as the JSON the route takes, from the bytes a caller may hold. */
+function initArgsOf(params) {
+    if (!params || params.length === 0)
+        return {};
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(params)));
+}
+/** A relay client for these calls: the author's credential, whatever nonces the call needs. */
+function client(s, relayUrl, nonces, fetch) {
+    return new RelayClient({
+        relayUrl,
+        authorAccount: s.account,
+        authorProof: s.credential,
+        deviceSecret: s.deviceSecret,
+        nonces,
+        fetch,
+    });
+}
+export async function createDelegatedContext(s, req, deps = {}) {
+    const relay = relayFor(s, req.namespaceId);
+    // The creation warrant's nonce is spent in the NEW context's per-device
+    // window — the one its writes draw from, empty until now — so the first
+    // number is free, and the context's writes then start above it.
+    const creationNonce = 0n;
+    const created = await client(s, relay, { next: async () => creationNonce }, deps.fetch).createContext({
+        groupId: req.groupId ?? req.namespaceId,
+        applicationId: req.applicationId,
+        serviceName: req.serviceName,
+        seed: req.contextSeed,
+        initArgs: initArgsOf(req.initializationParams),
+        name: req.name,
+    });
+    markContextNonceSpent(relay, created.contextId, creationNonce);
+    rememberRelay(s.account, relay, { namespaceId: req.namespaceId, contextId: created.contextId });
+    return { contextId: created.contextId };
+}
+/** Publish one delegable governance op through the namespace's relay. */
+export async function delegatedGovernance(s, req, deps = {}) {
+    const relay = relayFor(s, req.namespaceId);
+    return client(s, relay, governanceNonce(relay, req.group), deps.fetch).govern({ groupId: req.group, op: req.op });
+}
+/**
+ * A context only the author and `members` are in (a DM, a small room): a
+ * restricted subgroup of the namespace (a root op, posted to the namespace),
+ * each member added to it directly — they are in the namespace already, so
+ * nobody is invited — and the context created inside it. The relay that
+ * creates the subgroup is seated in it with CAN_AUTHOR_ON_BEHALF by core.
+ */
+export async function createDelegatedPrivateContext(s, req, deps = {}) {
+    const { groupId } = await delegatedGovernance(s, {
+        namespaceId: req.namespaceId,
+        group: req.namespaceId,
+        // The id is derived from a fresh salt (core#4244); a node refuses any other.
+        op: (await subgroupCreation({ parentId: req.namespaceId, restricted: true, admin: s.account })).op,
+    }, deps);
+    for (const member of req.members) {
+        await delegatedGovernance(s, { namespaceId: req.namespaceId, group: groupId, op: memberAddedOp(member, 'Member') }, deps);
+    }
+    const { contextId } = await createDelegatedContext(s, { ...req, groupId }, deps);
+    return { contextId, groupId };
+}
+/**
+ * Found a namespace as the account, through a relay it already uses. The
+ * account becomes founder, owner and admin; the relay is seated in it (and a
+ * TEE relay admits itself as its first TEE), so contexts can be created in it
+ * through the same relay straight away.
+ *
+ * The relay's executor account cannot be asked about a namespace that does
+ * not exist yet, so it is the session's `executorAccount` when the app named
+ * one, else learned from a namespace the account already has on that relay. A
+ * brand-new account with neither is told how to get one.
+ */
+export async function foundDelegatedNamespace(s, req = {}, deps = {}) {
+    const relays = knownRelays(s).map((u) => u.replace(/\/+$/, ''));
+    const relay = relays[0];
+    if (!relay)
+        throw new Error('no relay is known for this account, so there is nowhere to found a namespace');
+    const known = Object.entries(readRelayMap(s.account).namespaces).find(([, url]) => url.replace(/\/+$/, '') === relay)?.[0];
+    // The session's relay may come with its account (the cloud names it), which
+    // is all founding needs; otherwise it is learned from a namespace on it.
+    const named = s.executorAccount && s.relayUrl && s.relayUrl.replace(/\/+$/, '') === relay ? s.executorAccount : null;
+    if (!named && !known) {
+        throw new Error("the executor account of this relay is not known: join a namespace on it first, or connect with the relay's executor account (the cloud shows it beside the relay)");
+    }
+    const executorAccount = named ?? (await client(s, relay, governanceNonce(relay, known), deps.fetch).describeGovernance(known)).executorAccount;
+    // The founding warrant and, with a default mask, a second one are both spent
+    // in the NEW namespace's window, which is empty: any rising pair will do.
+    let next = BigInt(Date.now());
+    const founded = await client(s, relay, { next: async () => next++ }, deps.fetch).foundNamespace({
+        executorAccount,
+        ...(req.defaultCapabilities !== undefined ? { defaultCapabilities: req.defaultCapabilities } : {}),
+        ...(req.application ? { application: req.application } : {}),
+    });
+    try {
+        localStorage.setItem(`calimero.governance-nonce.${relay}.${founded.namespaceId}`, String(next));
+    }
+    catch {
+        /* unpersisted: the clock floor still keeps later warrants above these */
+    }
+    rememberRelay(s.account, relay, { namespaceId: founded.namespaceId });
+    if (req.application && founded.applicationSet !== true) {
+        // Founded, but no context can be created in it until it has its
+        // application; the same choice can be retried (it is still the first).
+        throw new Error(`founded ${founded.namespaceId} but could not give it its application: ${founded.applicationError ?? 'unknown reason'}`);
+    }
+    // HA's fleet node is admitted by the founding relay, which can vouch for it
+    // only once it attested itself as the namespace's first TEE (that also sets
+    // the admission policy). Without that no fleet node is ever admitted, and the
+    // request would hold the account's one pending slot in the cloud for good.
+    const ha = founded.teeEnabled
+        ? await enableHaBestEffort(s, founded.namespaceId, founded.salt, relay, deps)
+        : {
+            haEnabled: false,
+            haError: `the relay did not attest the founding, so no fleet node could be admitted for HA${founded.teeError ? `: ${founded.teeError}` : ''}`,
+        };
+    return { namespaceId: founded.namespaceId, teeEnabled: founded.teeEnabled, ...ha };
+}
+/** What an app can tell a person whose account the cloud cannot place. */
+export const HA_ACCOUNT_NOT_LINKED_MESSAGE = 'link this account to your cloud user in the wallet so invitees can find this namespace';
+/**
+ * What to tell a person for each refusal the cloud names, keyed by its code.
+ * Every one leaves the namespace founded; only hosting was refused.
+ */
+export const HA_REFUSAL_MESSAGES = {
+    account_not_linked: HA_ACCOUNT_NOT_LINKED_MESSAGE,
+    account_linked_to_several_users: 'this account is linked to more than one cloud user, so the cloud cannot tell whose plan hosts the namespace: unlink it from all but one in the wallet',
+    ha_request_pending: "another namespace of this account is still waiting to be hosted; the cloud hosts one new namespace at a time without a cloud sign-in. Sign in to the cloud and turn off hosting for the waiting namespace, or wait until it is hosted",
+    unknown_relay: 'the cloud does not run the relay this namespace was founded on, so it cannot host it',
+    relay_not_dialable: 'the relay this namespace was founded on has not reported its address to the cloud yet; try enabling hosting again shortly',
+};
+/** The namespace the cloud says is blocking, when it names one. */
+function blockingNamespace(e) {
+    try {
+        const body = JSON.parse(e.bodyText ?? '');
+        const id = body?.detail?.namespace_id ?? body?.namespace_id;
+        return typeof id === 'string' && /^[0-9a-f]{64}$/i.test(id) ? id.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask the cloud to host a namespace this account just founded, with no cloud
+ * session: the account proves it is the founder (its id and the salt reproduce
+ * the namespace id) and the cloud bills the user it is linked to.
+ *
+ * Best-effort: the namespace exists whatever the cloud answers, so a refusal is
+ * reported, never thrown. Without HA nothing in the cloud knows the namespace,
+ * so an invitee cannot find its relay; hence the not-linked case gets a
+ * sentence that says what to do.
+ */
+async function enableHaBestEffort(s, namespaceId, salt, relayUrl, deps) {
+    try {
+        await new CloudClient({ cloudBaseUrl: deps.cloudBaseUrl, fetch: deps.fetch }).enableHaAsAccount({
+            namespaceId,
+            salt,
+            accountId: s.account,
+            credential: s.credential,
+            deviceSecret: s.deviceSecret,
+            // The relay that founded it: the cloud hands it to the fleet node as its
+            // admitter, so the node does not have to find it by discovery.
+            relayUrl,
+        });
+        return { haEnabled: true };
+    }
+    catch (e) {
+        if (e instanceof AccountNotLinkedError)
+            return { haEnabled: false, haError: HA_ACCOUNT_NOT_LINKED_MESSAGE };
+        if (e instanceof AccountHaRefusedError && HA_REFUSAL_MESSAGES[e.code]) {
+            const blocking = e.code === 'ha_request_pending' ? blockingNamespace(e) : null;
+            const message = HA_REFUSAL_MESSAGES[e.code];
+            return { haEnabled: false, haError: blocking ? `${message} (waiting: ${blocking})` : message };
+        }
+        return { haEnabled: false, haError: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * The latest version of `pkg` the registry publishes. Used when the app names
+ * its package but not a version. Same selection as the id derivation
+ * ({@link selectLatestBundle}): the newest version that is not yanked.
+ */
+export async function latestPublishedVersion(registryUrl, pkg, fetchFn = globalThis.fetch) {
+    const latest = selectLatestBundle(await fetchRegistryBundles(registryUrl, pkg, fetchFn));
+    if (!latest)
+        throw new Error(`the registry lists no version of ${pkg}`);
+    return latest.appVersion;
+}

package/dist/account/govern.d.ts

@@ -0,0 +1,24 @@
+/**
+ * An account's group management through a relay: one delegated governance op
+ * per call (`RelayClient.govern`), posted to the relay that serves the group's
+ * namespace.
+ *
+ * A group op goes to the group it acts on; a root op (create, delete, move a
+ * subgroup; join an open one) goes to the NAMESPACE. The namespace of a
+ * subgroup is remembered here per account: when this account created it, and
+ * when the account admin asked the relay for it (`getGroupInfo`).
+ */
+import { type GovernanceOp } from '../warrant/index.js';
+import { type DelegatedSession } from './session.js';
+/** Record that `groupId` is a subgroup of `namespaceId`, for this account. */
+export declare function rememberGroupNamespace(account: string, groupId: string, namespaceId: string): void;
+/** The namespace a group belongs to: itself if it is a namespace this account is in, else what was remembered. */
+export declare function namespaceOfGroup(s: DelegatedSession, groupId: string): string | undefined;
+/** A group op (member, role, capabilities, metadata, visibility, detach) on `groupId`. */
+export declare function governGroup(s: DelegatedSession, groupId: string, op: GovernanceOp): Promise<{
+    groupId: string;
+}>;
+/** A root op, posted to the namespace `groupId` belongs to. */
+export declare function governRoot(s: DelegatedSession, groupId: string, op: GovernanceOp): Promise<{
+    groupId: string;
+}>;