@calimero-network/mero-js 22.6.0 → 22.8.0

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

@@ -1026,6 +1026,21 @@ export interface AccountDeviceEntry {
     signingKey: string;
     /** Set only on the device this node itself presents. */
     isSelf: boolean;
+    /**
+     * Whether this device has been withdrawn from the account.
+     *
+     * A revoked device stays in the listing rather than vanishing from it, so a
+     * settings UI can render "revoked" as a state of a known device instead of
+     * silently losing the row. Never filter on this by default: a device that
+     * disappeared and a device that was withdrawn are different facts, and only
+     * the second one is a fact the account holder took an action to create.
+     *
+     * Revocation is **forward-only**. It withdraws the device's authority to
+     * write from here on; it does not retract, unsign or rewrite anything the
+     * device already authored, and ops it signed before the revocation stay valid
+     * and stay in the DAG. `revoked: true` therefore means "may not act any more",
+     * never "never acted" - do not build UI that implies the past was undone.
+     */
     revoked: boolean;
     /**
      * Applications this device may speak for, 64 hex each. **Empty means every
@@ -1082,7 +1097,15 @@ export interface AccountApplicationEntry {
     /** Ids of the namespaces targeting it, 64 hex characters each. */
     namespaces: string[];
 }
-/** Withdraw a device from an account, terminally. */
+/**
+ * Withdraw a device from an account, terminally.
+ *
+ * Terminal in one direction only: revocation is **forward-only**. It stops the
+ * device acting from here on and does not retract past authorship - every op it
+ * already signed keeps verifying and stays in the DAG, because the certificate
+ * that authorised it was valid when the signature was made. There is no
+ * "un-author" in this system, so no revocation UI should promise one.
+ */
 export interface RevokeAccountDeviceRequest {
     /** The device to withdraw, 64 hex. */
     deviceId: string;
@@ -1139,6 +1162,36 @@ export interface RevokeAccountDeviceResponseData {
      */
     revokedIn: RevocationOutcome[];
 }
+/** One device of one member account, as the group's live bindings record it. */
+export interface MemberDeviceEntry {
+    /** The device id, 64 hex - the form {@link RevokeAccountDeviceRequest.deviceId} takes. */
+    deviceId: string;
+    /**
+     * The key this device's signatures carry, 64 hex. This is the join column
+     * against the identities a context reports, which name bare signing keys and
+     * nothing else.
+     */
+    signingKey: string;
+}
+/** One member account of a group, with the devices currently bound for it. */
+export interface MemberDevicesEntry {
+    /** The member's account id, 64 hex - the same id a group member listing names. */
+    account: string;
+    /**
+     * Devices holding a live binding for this account. Only live ones: a revoked
+     * device is gone from here, unlike {@link AccountDeviceEntry} which keeps it
+     * with `revoked: true`. So this answers "who may act now", never "who ever
+     * did" - a past author may well be absent.
+     */
+    devices: MemberDeviceEntry[];
+}
+/** Paging for a member-device listing. Both are optional; the node defaults them. */
+export interface ListMemberDevicesOptions {
+    /** How many entries to skip. */
+    offset?: number;
+    /** How many entries to return. The node clamps this to its own maximum. */
+    limit?: number;
+}
 export interface CreateGroupRequest {
     applicationId: string;
     appKey?: string;
@@ -1305,10 +1358,6 @@ export interface MemberDevicesEntry {
     account: string;
     devices: MemberDevice[];
 }
-export interface ListMemberDevicesOptions {
-    offset?: number;
-    limit?: number;
-}
 export interface ListMemberDevicesResponseData {
     /**
      * Every account in the group if the calling node is an admin; only its own
@@ -1730,3 +1779,108 @@ export interface AdmitJoinResponseData {
      */
     readonly published: boolean;
 }
+/**
+ * Where one author device stands in its warrant-nonce sequence on one node.
+ *
+ * # Why `bigint` and not `number`
+ *
+ * A nonce is a `u64` on the node. `JSON.parse` turns every number into an IEEE
+ * double, so any value past 2^53 arrives already rounded - and it rounds
+ * silently, producing a nonce that looks ordinary and is refused forever. The
+ * exhaustion rule this endpoint exists to report (`u64::MAX` spent -> no next
+ * nonce) lives precisely in the range a `number` cannot hold, so representing it
+ * as one would lose the very case the type is meant to make visible.
+ *
+ * `bigint` over a decimal `string` because callers do arithmetic with these:
+ * the documented recovery rule is `max(ownNext, nextNonce)`, and
+ * {@link NonceSource} already emits `bigint`. A string would make every caller
+ * convert first, and the ones that forget would compare `"10" < "9"`.
+ *
+ * The digits are recovered from the raw response text rather than from a parsed
+ * `number`, so nothing is routed through a double on the way in.
+ *
+ * # Why a union on `kind`
+ *
+ * `nextNonce` is absent in exactly one case, and a client that reads it as
+ * `undefined` and falls back to a guess burns nonces for real. Splitting the two
+ * cases makes the compiler ask which one this is before `nextNonce` can be read
+ * at all.
+ *
+ * The discriminant is a string rather than an `exhausted: boolean` because this
+ * package compiles with `strictNullChecks` off, and TypeScript declines to
+ * narrow a union on a boolean-literal discriminant in that mode. A flag that
+ * silently fails to narrow would be worse than no flag: it would read as a
+ * guard and admit `nextNonce` on both arms.
+ */
+export type WarrantNonceState = WarrantNonceOpen | WarrantNonceExhausted;
+/** Fields both arms carry, whatever the sequence's state. */
+interface WarrantNonceCommon {
+    /** The context asked about, echoed - read it to reject a cached answer. */
+    readonly contextId: string;
+    /**
+     * The author device asked about, echoed. This is the device's SIGNING KEY,
+     * not its `deviceId` and not the account: two devices of one account hold two
+     * independent sequences, and a re-keyed device starts a fresh one.
+     *
+     * Echoed as the node spelled it, which is the spelling that was asked for -
+     * the route accepts base58 or hex and does not normalise between them.
+     */
+    readonly authorDeviceKey: string;
+    /**
+     * Whether this node has admitted any warrant from this device here.
+     *
+     * `false` is the ordinary state of a device that has not written yet - a fresh
+     * sequence, not an error and not a row worth retrying for.
+     */
+    readonly seen: boolean;
+    /**
+     * The highest nonce this node has accepted from this device here, absent when
+     * `seen` is `false`.
+     *
+     * Reported for auditability. Do NOT compute a nonce from it: the `+ 1` is the
+     * node's arithmetic, already done in {@link WarrantNonceOpen.nextNonce}, and
+     * doing it again here is how a client reintroduces the overflow this endpoint
+     * avoids.
+     */
+    readonly highWaterNonce?: bigint;
+    /**
+     * How far below `highWaterNonce` a late warrant may still be accepted.
+     *
+     * Constant (64 today), and useful for sizing an in-flight window: a warrant
+     * minted but not yet executed is refused once this many later ones have landed
+     * ahead of it. It is NOT an input to a nonce - which parts of the window below
+     * the mark are already spent is deliberately not reported.
+     */
+    readonly windowWidth: bigint;
+}
+/** The sequence has room: {@link nextNonce} is the number to mint at. */
+export interface WarrantNonceOpen extends WarrantNonceCommon {
+    readonly kind: 'open';
+    /**
+     * The smallest nonce this node is guaranteed to accept. **The only actionable
+     * value here.**
+     *
+     * `0` on a fresh sequence (`seen: false`), which is a real answer, not a
+     * missing one.
+     *
+     * A client that still holds its own counter must mint at
+     * `max(ownNext, nextNonce)`, never at `nextNonce` alone: nonce state folds per
+     * peer, so this node can be BEHIND a client whose warrants it has not applied
+     * yet, and never ahead of the truth. An author spread across relays asks each
+     * and takes the highest answer.
+     */
+    readonly nextNonce: bigint;
+}
+/**
+ * `u64::MAX` is spent here: there is no next nonce and this device cannot write
+ * to this context again. It must re-key - a new signing key starts a fresh
+ * sequence.
+ *
+ * The node reports this by omitting `nextNonce` rather than by wrapping to `0`,
+ * because a wrapped `0` would look like a valid answer and be refused forever.
+ */
+export interface WarrantNonceExhausted extends WarrantNonceCommon {
+    readonly kind: 'exhausted';
+    readonly seen: true;
+    readonly highWaterNonce: bigint;
+}

package/dist/capabilities.d.ts

@@ -30,6 +30,48 @@ export declare const CAPABILITIES: {
 };
 export type CapabilityName = keyof typeof CAPABILITIES;
 export type CapabilityBit = (typeof CAPABILITIES)[CapabilityName];
+/**
+ * Ready-made masks for `setDefaultCapabilities` / `setMemberCapabilities` and
+ * `RelayClient.foundNamespace({ defaultCapabilities })`, so an app can name the
+ * default it gives members instead of passing a bare number.
+ *
+ * Why this matters: a namespace's default mask is copied into a non-admin
+ * member's row when they join, and a namespace starts without
+ * `CAN_CREATE_CONTEXT` in it. An app that never sets a default leaves every
+ * invited member unable to create a context until an admin grants it by hand.
+ *
+ * None of these include `CAN_AUTHOR_ON_BEHALF`; grant that deliberately (see
+ * `AdminApiClient.grantAuthorship` / `openToDelegatedExecution`).
+ */
+export declare const CAPABILITY_PRESETS: {
+    /** No capabilities. */
+    readonly NONE: 0;
+    /** Join Open subgroups only: what a namespace starts with. */
+    readonly JOIN_ONLY: number;
+    /**
+     * Create contexts, invite members, join Open subgroups (= 7). A member who
+     * can work in the namespace but not reshape it.
+     */
+    readonly CONTRIBUTOR: number;
+    /**
+     * `CONTRIBUTOR` plus create and delete subgroups and manage their visibility
+     * (= 231). What mero-chat gives members, so they can start and close their
+     * own channels.
+     */
+    readonly COLLABORATOR: number;
+};
+export type CapabilityPreset = keyof typeof CAPABILITY_PRESETS;
+/**
+ * Builds a u32 mask from capability names and/or bit values:
+ * `capMask('CAN_CREATE_CONTEXT', 'CAN_INVITE_MEMBERS') === 3`.
+ * Throws on a name core does not assign, so a typo can't silently yield 0.
+ */
+export declare function capMask(...caps: Array<CapabilityName | number>): number;
+/**
+ * The names of the assigned capability bits set in `mask`, in bit order.
+ * Unassigned bits (10 and above) are not reported.
+ */
+export declare function capNames(mask: number): CapabilityName[];
 /**
  * Returns true if `mask` has every bit of `cap` set. Both operands are
  * coerced to unsigned 32-bit (`>>> 0`) before comparing so a high bit such

package/dist/capabilities.js

@@ -34,6 +34,70 @@ export const CAPABILITIES = {
      */
     CAN_AUTHOR_ON_BEHALF: 1 << 9,
 };
+/**
+ * Ready-made masks for `setDefaultCapabilities` / `setMemberCapabilities` and
+ * `RelayClient.foundNamespace({ defaultCapabilities })`, so an app can name the
+ * default it gives members instead of passing a bare number.
+ *
+ * Why this matters: a namespace's default mask is copied into a non-admin
+ * member's row when they join, and a namespace starts without
+ * `CAN_CREATE_CONTEXT` in it. An app that never sets a default leaves every
+ * invited member unable to create a context until an admin grants it by hand.
+ *
+ * None of these include `CAN_AUTHOR_ON_BEHALF`; grant that deliberately (see
+ * `AdminApiClient.grantAuthorship` / `openToDelegatedExecution`).
+ */
+export const CAPABILITY_PRESETS = {
+    /** No capabilities. */
+    NONE: 0,
+    /** Join Open subgroups only: what a namespace starts with. */
+    JOIN_ONLY: CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS,
+    /**
+     * Create contexts, invite members, join Open subgroups (= 7). A member who
+     * can work in the namespace but not reshape it.
+     */
+    CONTRIBUTOR: CAPABILITIES.CAN_CREATE_CONTEXT |
+        CAPABILITIES.CAN_INVITE_MEMBERS |
+        CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS,
+    /**
+     * `CONTRIBUTOR` plus create and delete subgroups and manage their visibility
+     * (= 231). What mero-chat gives members, so they can start and close their
+     * own channels.
+     */
+    COLLABORATOR: CAPABILITIES.CAN_CREATE_CONTEXT |
+        CAPABILITIES.CAN_INVITE_MEMBERS |
+        CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS |
+        CAPABILITIES.CAN_CREATE_SUBGROUP |
+        CAPABILITIES.CAN_DELETE_SUBGROUP |
+        CAPABILITIES.CAN_MANAGE_VISIBILITY,
+};
+/**
+ * Builds a u32 mask from capability names and/or bit values:
+ * `capMask('CAN_CREATE_CONTEXT', 'CAN_INVITE_MEMBERS') === 3`.
+ * Throws on a name core does not assign, so a typo can't silently yield 0.
+ */
+export function capMask(...caps) {
+    let mask = 0;
+    for (const cap of caps) {
+        if (typeof cap === 'number') {
+            mask |= cap;
+        }
+        else if (Object.prototype.hasOwnProperty.call(CAPABILITIES, cap)) {
+            mask |= CAPABILITIES[cap];
+        }
+        else {
+            throw new Error(`unknown capability: ${String(cap)}`);
+        }
+    }
+    return mask >>> 0;
+}
+/**
+ * The names of the assigned capability bits set in `mask`, in bit order.
+ * Unassigned bits (10 and above) are not reported.
+ */
+export function capNames(mask) {
+    return Object.keys(CAPABILITIES).filter((name) => hasCap(mask, CAPABILITIES[name]));
+}
 /**
  * Returns true if `mask` has every bit of `cap` set. Both operands are
  * coerced to unsigned 32-bit (`>>> 0`) before comparing so a high bit such

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

@@ -24,6 +24,8 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
+import { type RootSource } from '../account/index.js';
+import type { Signer } from '../signer/signer.js';
 import { type DiscoveryChallenge, type RoutingChallenge, type RoutingCredential } from './routing-proof.js';
 /**
  * The first relay a warrant can be spent at, or `null`.
@@ -111,6 +113,26 @@ export interface CloudRelay {
     relayUrl: string | null;
     /** The account a warrant for this relay must name as its `executor`, hex. */
     executorAccount: string | null;
+    /**
+     * The relay node's ed25519 **device signing key**, hex — or `null`, which is
+     * what it is today.
+     *
+     * A relay is an ordinary node, so it can be logged in to and subscribed to;
+     * the login statement has to be signed against this key, supplied separately
+     * rather than read from the node being authenticated. The cloud does not
+     * publish it yet (mdma #312), so this is `null` on every row and the hosted
+     * path reports `canSubscribe === false`.
+     *
+     * It is parsed rather than omitted so the hosted path needs no API change
+     * when the field lands: `connectCloud` already passes it through, and the
+     * same call site starts observing. `peerId` is **not** a fallback — it is a
+     * libp2p identity, a different key, and signing a statement about it would
+     * authenticate nothing.
+     *
+     * Both plausible spellings are accepted because mdma #312 has not fixed one;
+     * if it lands under a third name, this mapping is the single line to change.
+     */
+    nodeKey: string | null;
     /** `'assigned'` (admitted pending confirm) or `'active'`. */
     status: string;
     /** Whether this relay holds `CAN_AUTHOR_ON_BEHALF` on the namespace. */
@@ -378,8 +400,10 @@ export declare class CloudClient {
      * account behind those reads was claimed by its owner. The claim is recorded
      * even when the session is refused.
      *
-     * @param rootSecret the account root's signing secret, 64 hex. It never
-     *   leaves this process — only a signature over the cloud's nonce travels.
+     * @param root the account root: its 64-hex secret, or a `Signer` over a root
+     *   this process may use and cannot read — the form a phrase-held root in a
+     *   browser takes. Either way nothing but a signature over the cloud's nonce
+     *   travels.
      *
      * A `403` means either the signature did not verify, or the account is not
      * linked to a cloud login: ownership alone says who you are, and the link
@@ -387,7 +411,7 @@ export declare class CloudClient {
      * on the proof alone would authenticate perfectly and authorize nothing. The
      * ownership claim is recorded either way, so linking later needs no re-proof.
      */
-    signInWithAccount(rootSecret: string): Promise<CloudSession>;
+    signInWithAccount(root: RootSource): Promise<CloudSession>;
     /**
      * Mint a challenge for an account root to sign.
      *
@@ -612,15 +636,16 @@ export declare class CloudClient {
      * an intent; the cloud needs it to know whose plan a hosted node is spending,
      * and to sign that account back in later.
      *
-     * @param rootSecret the account root's signing secret, 64 hex — from
-     *   {@link generateAccountRoot}, from a restored recovery phrase, or from a
-     *   desktop app or hardware key that already holds one.
+     * @param root the account root: its 64-hex secret — from
+     *   {@link generateAccountRoot}, a restored recovery phrase, or a desktop app
+     *   or hardware key that already holds one — or a `Signer` over a root this
+     *   process cannot read, which is what a phrase-held browser root is.
      *
      * Idempotent for the same login. An account already linked to a *different*
      * cloud login is a `409`; a replayed or expired challenge is a `403`; and
      * exceeding the plan's account limit is a `402`.
      */
-    linkAccount(rootSecret: string): Promise<CloudAccountLink>;
+    linkAccount(root: RootSource): Promise<CloudAccountLink>;
     /**
      * Mint a single-use challenge for an account root to sign.
      *
@@ -701,7 +726,12 @@ export declare class CloudClient {
     linkAccountWithGrant(options: {
         grant: string;
         /** The root of the account the grant names, 64 hex. */
-        rootSecret: string;
+        rootSecret?: string;
+        /**
+         * The root's signer — use instead of `rootSecret` when the root is a key
+         * this process may use and cannot read.
+         */
+        signer?: Signer;
     }): Promise<CloudAccountLink>;
     /** The accounts linked to this login, and how many the plan allows. */
     getMyAccounts(): Promise<CloudLinkedAccounts>;

package/dist/cloud/cloud-client.js

@@ -24,11 +24,22 @@
  * ever sent, and would be a throughput bottleneck on a path that has no reason
  * to involve it.
  */
-import { accountRootFromSecret, signAccountLink, signAccountLogin, } from '../account/index.js';
+import { resolveRoot, resolveRootPair, signAccountLink, signAccountLogin, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.js';
 import { routingProofHeaders, } from './routing-proof.js';
-/** Where the hosted cloud lives when a caller names no other. */
-const DEFAULT_CLOUD_BASE_URL = 'https://cloud.calimero.network';
+/**
+ * The hosted cloud's **API** when a caller names no other.
+ *
+ * `manager.cloud.calimero.network`, not `cloud.calimero.network`: the latter
+ * serves the React app, which answers an API call with 405 and an HTML body.
+ * Every method on this client is an API call, so the bare `new CloudClient()`
+ * used to fail at the first request with a parse error rather than at
+ * construction — and the URL it was talking to looked right in the message.
+ *
+ * The web origin still exists in this package: the consent screen in
+ * `link-redirect.ts` is a page a person visits, and that one is the app.
+ */
+const DEFAULT_CLOUD_BASE_URL = 'https://manager.cloud.calimero.network';
 /**
  * The cloud's own `can_execute` where it sends one, else `legacy`.
  *
@@ -117,8 +128,10 @@ export class CloudClient {
      * account behind those reads was claimed by its owner. The claim is recorded
      * even when the session is refused.
      *
-     * @param rootSecret the account root's signing secret, 64 hex. It never
-     *   leaves this process — only a signature over the cloud's nonce travels.
+     * @param root the account root: its 64-hex secret, or a `Signer` over a root
+     *   this process may use and cannot read — the form a phrase-held root in a
+     *   browser takes. Either way nothing but a signature over the cloud's nonce
+     *   travels.
      *
      * A `403` means either the signature did not verify, or the account is not
      * linked to a cloud login: ownership alone says who you are, and the link
@@ -126,13 +139,13 @@ export class CloudClient {
      * on the proof alone would authenticate perfectly and authorize nothing. The
      * ownership claim is recorded either way, so linking later needs no re-proof.
      */
-    async signInWithAccount(rootSecret) {
-        const root = await accountRootFromSecret(rootSecret);
+    async signInWithAccount(root) {
+        const { signer, publicKey } = await resolveRoot(root);
         const { nonce } = await this.getAccountLoginChallenge();
         return this.submitAccountLogin({
-            rootPublicKey: root.publicKey,
+            rootPublicKey: publicKey,
             nonce,
-            signature: await signAccountLogin({ rootSecret, nonce }),
+            signature: await signAccountLogin({ signer, nonce }),
         });
     }
     /**
@@ -221,6 +234,9 @@ export class CloudClient {
                 peerId: String(row.peer_id ?? ''),
                 relayUrl,
                 executorAccount,
+                nodeKey: row.node_key ??
+                    row.node_public_key ??
+                    null,
                 status: String(row.status ?? ''),
                 authorshipReady,
                 teeRole: teeRoleOf(row),
@@ -541,22 +557,23 @@ export class CloudClient {
      * an intent; the cloud needs it to know whose plan a hosted node is spending,
      * and to sign that account back in later.
      *
-     * @param rootSecret the account root's signing secret, 64 hex — from
-     *   {@link generateAccountRoot}, from a restored recovery phrase, or from a
-     *   desktop app or hardware key that already holds one.
+     * @param root the account root: its 64-hex secret — from
+     *   {@link generateAccountRoot}, a restored recovery phrase, or a desktop app
+     *   or hardware key that already holds one — or a `Signer` over a root this
+     *   process cannot read, which is what a phrase-held browser root is.
      *
      * Idempotent for the same login. An account already linked to a *different*
      * cloud login is a `409`; a replayed or expired challenge is a `403`; and
      * exceeding the plan's account limit is a `402`.
      */
-    async linkAccount(rootSecret) {
-        const root = await accountRootFromSecret(rootSecret);
+    async linkAccount(root) {
+        const { signer, publicKey, accountId } = await resolveRoot(root);
         const { nonce } = await this.getAccountLinkChallenge();
         return this.submitAccountLink({
-            accountId: root.accountId,
-            rootPublicKey: root.publicKey,
+            accountId,
+            rootPublicKey: publicKey,
             nonce,
-            signature: await signAccountLink({ rootSecret, nonce }),
+            signature: await signAccountLink({ signer, nonce }),
         });
     }
     /**
@@ -677,20 +694,20 @@ export class CloudClient {
      * login; `402` that the plan is full.
      */
     async linkAccountWithGrant(options) {
-        const root = await accountRootFromSecret(options.rootSecret);
+        const { signer, publicKey, accountId } = await resolveRootPair(options.rootSecret, options.signer);
         const body = await this.request('POST', '/api/cloud/accounts/link', {
             body: {
                 grant: options.grant,
-                root_public_key: root.publicKey,
+                root_public_key: publicKey,
                 signature: await signAccountLink({
-                    rootSecret: options.rootSecret,
+                    signer,
                     nonce: options.grant,
                 }),
             },
             anonymous: true,
         });
         return {
-            accountId: String(body.account_id ?? root.accountId),
+            accountId: String(body.account_id ?? accountId),
             linkedAt: body.linked_at ?? null,
             alreadyLinked: body.already_linked === true,
         };

package/dist/cloud/connect.d.ts

@@ -19,6 +19,12 @@
  * function is that missing answer, which is why the login step it replaces is
  * the *node URL prompt* rather than the authentication.
  *
+ * `connectCloudWithAccount(...)` is the same connection reached by the other
+ * door: the caller holds an account root and signs in as the account itself,
+ * with no Google login anywhere in it. Identical from there on, deliberately —
+ * which login proved who you are changes nothing about how a relay is found or
+ * how a write is authorised.
+ *
  * # What it does not do
  *
  * # Sealing the relay
@@ -38,6 +44,10 @@ import { CloudClient } from './cloud-client.js';
 import type { CloudClientConfig, CloudNamespace, CloudRelay } from './cloud-client.js';
 import { RelayClient } from '../relay/relay-client.js';
 import type { IntentResult, NonceSource } from '../relay/index.js';
+import { type Signer } from '../signer/signer.js';
+import { type RootSource } from '../account/account.js';
+import { MeroClient } from '../transport/mero-client.js';
+import type { Audience } from '../login/index.js';
 import type { VerifyTransportQuote } from '../sealed/sealed.js';
 export interface ConnectCloudOptions {
     /** Defaults to the hosted cloud. */
@@ -52,8 +62,24 @@ export interface ConnectCloudOptions {
     authorAccount: string;
     /** The author's `AccountProof<DeviceCert>`, hex-encoded borsh. */
     authorProof: string;
-    /** The author device's ed25519 signing secret, hex. Never transmitted. */
-    deviceSecret: string;
+    /**
+     * The author device's ed25519 signing secret, hex. Never transmitted.
+     *
+     * Mutually exclusive with {@link ConnectCloudOptions.signer}, and the weaker
+     * of the two in a browser — a secret that exists as a string can be read by
+     * anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer — use instead of
+     * {@link ConnectCloudOptions.deviceSecret}.
+     *
+     * A browser wallet holds its device key as a non-extractable `CryptoKey`,
+     * which has no hex form to pass. Without this, that wallet — the case this
+     * whole path was built for — had to hand-assemble the `RelayClient` the
+     * one-call path exists to build.
+     */
+    signer?: Signer;
     /**
      * Which namespace to write in.
      *
@@ -86,6 +112,25 @@ export interface ConnectCloudOptions {
     seal?: VerifyTransportQuote;
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /**
+     * The chosen relay node's device signing key, hex — if you know it.
+     *
+     * Supplying it makes `connection.client` able to *observe* as well as write:
+     * a relay is an ordinary node, and a keyholder with an account proof can log
+     * in to it and subscribe. The key has to come from somewhere the caller
+     * already trusts, which today means out of band, because the cloud does not
+     * publish it (mdma #312).
+     *
+     * Left unset, the key the cloud reported is used — `null` for now, which
+     * means `connection.client.canSubscribe === false` and nothing is guessed.
+     * When #312 lands, unchanged callers start observing.
+     */
+    relayNodeKey?: string;
+    /**
+     * The audience the observing session is bound to. Defaults to this runtime's
+     * own origin (or `cli`). See {@link RelayObserveConfig.audience}.
+     */
+    observeAudience?: Audience;
 }
 /** A signed-in cloud session with a relay ready to write through. */
 export interface CloudConnection {
@@ -100,6 +145,23 @@ export interface CloudConnection {
     relayInfo: CloudRelay;
     /** Run one method in one context, on the author's behalf. */
     execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
+    /**
+     * The same connection behind the transport-neutral surface.
+     *
+     * `client.rpc.execute({ contextId, method, argsJson })` is the call a
+     * node-backed app already writes, so an app reaching the cloud this way keeps
+     * every call site it has — signing in *is* the transport decision, and it
+     * happens here, once. `relay` and `execute` above are unchanged and remain
+     * the direct path for a caller that wants `IntentResult` in hand.
+     *
+     * Whether it can also *observe* depends on one input: the relay node's
+     * device signing key. A relay is an ordinary node and serves `/sse` and
+     * `/ws`, but a login statement must be signed against a key learned out of
+     * band. Pass {@link ConnectCloudOptions.relayNodeKey} if you have it; the
+     * cloud does not publish it yet (mdma #312), so by default
+     * `client.canSubscribe === false` and `client.events` throws saying so.
+     */
+    client: MeroClient;
 }
 /**
  * Sign in to the cloud and return a connection that can write.
@@ -112,3 +174,40 @@ export interface CloudConnection {
  * cannot tell them what.
  */
 export declare function connectCloud(options: ConnectCloudOptions): Promise<CloudConnection>;
+/** What {@link connectCloudWithAccount} needs on top of a root. */
+export interface ConnectCloudWithAccountOptions extends Omit<ConnectCloudOptions, 'sessionToken' | 'googleIdToken' | 'authorAccount'> {
+    /**
+     * The account root — a 64-hex secret, or a `Signer` over a key that cannot be
+     * exported. The whole credential: no Google login is involved.
+     */
+    root: RootSource;
+    /**
+     * Whose writes these are, hex. Defaults to the account the root derives,
+     * which is the only account it can open a session as.
+     *
+     * Worth passing only when the device certificate was issued by a *different*
+     * root than the one signing in — which core accepts and nothing here needs to
+     * forbid, but which is rare enough that defaulting to the signing root is the
+     * safer shape.
+     */
+    authorAccount?: string;
+}
+/**
+ * The same connection, opened with an account root instead of a cloud session.
+ *
+ * The two sign-in paths end in the same place, and until now only one of them
+ * ended in a usable client: a caller signing in with a root had to open the
+ * session, read the relays and assemble a {@link RelayClient} by hand, which is
+ * three chances to pair the wrong author with the wrong executor.
+ *
+ * It is one call rather than one function: the session is minted here and
+ * everything after it is {@link connectCloud}, unchanged. Duplicating the
+ * namespace choice and the three no-relay diagnostics would mean two copies of
+ * the messages that tell a user what to go and do.
+ *
+ * The author defaults to the account the root derives. That is not a
+ * convenience — passing an account the root does not own is the mistake this
+ * shape removes, since the cloud would answer with that root's namespaces while
+ * every warrant claimed somebody else's authorship.
+ */
+export declare function connectCloudWithAccount(options: ConnectCloudWithAccountOptions): Promise<CloudConnection>;