agent-comms 8.15.8 → 8.15.10

package/src/core/account-bundle.ts

@@ -0,0 +1,264 @@
+/**
+ * The account key in transit (agent-comms#344): the one deliberate way a user principal's private key leaves the machine it lives on, so a second machine can hold the same account and, through the replicated grant ledger, see and revoke everything the first minted. The key only ever travels sealed: under a passphrase for an export the person carries themselves, or under a key derived from a one-time account invite for a join, never as plaintext.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+  scryptSync,
+} from "node:crypto";
+import { z } from "zod";
+import { parseDisplayName } from "./display-name.js";
+import { CommsError } from "./store.js";
+
+/** The text an exported bundle starts with, so a file can be recognised for what it is before any decryption is attempted. */
+export const ACCOUNT_BUNDLE_PREFIX = "agent-comms-account:v1:";
+
+/** scrypt's cost as OWASP's password storage guidance recommends it (N = 2^17, r = 8, p = 1): slow enough that guessing a passphrase against a stolen bundle is expensive, fast enough for a once-per-machine export or import. */
+const SCRYPT_COST_LOG2 = 17;
+const SCRYPT_COST = 2 ** SCRYPT_COST_LOG2;
+const SCRYPT_BLOCK_SIZE = 8;
+const SCRYPT_PARALLELISM = 1;
+/** scrypt needs 128 * N * r bytes of memory; Node refuses by default above 32 MiB, so the limit is raised to exactly twice what these parameters need. */
+const SCRYPT_BYTES_PER_UNIT = 128;
+const SCRYPT_MAX_MEMORY =
+  2 * SCRYPT_BYTES_PER_UNIT * SCRYPT_COST * SCRYPT_BLOCK_SIZE;
+/** A 128-bit salt, the size NIST SP 800-132 sets as the minimum. */
+const SALT_BYTES = 16;
+const KEY_BYTES = 32;
+/** GCM's specified IV length. */
+const IV_BYTES = 12;
+/** The shortest passphrase an export accepts. Twelve characters is the length NCSC and NIST guidance treat as the floor for a passphrase protecting something offline-attackable; the scrypt cost above does the rest. */
+export const MIN_ACCOUNT_PASSPHRASE_LENGTH = 12;
+
+const INVITE_KEY_INFO = "agent-comms/account-invite/v1";
+const BUNDLE_AAD = Buffer.from(ACCOUNT_BUNDLE_PREFIX);
+
+const base64url = z.string().regex(/^[A-Za-z0-9_-]*$/);
+
+/** What an account export or a join carries: the PEM private key and the name the account asserts for itself, if it has one. */
+export interface AccountContents {
+  privateKey: string;
+  displayName?: string;
+}
+
+const accountContentsSchema = z
+  .object({ privateKey: z.string(), displayName: z.string().optional() })
+  .strict();
+
+/** The contents as the plaintext a bundle or a join seals. */
+function contentsText(contents: Readonly<AccountContents>): string {
+  return JSON.stringify(contents);
+}
+
+/** The contents a sealed plaintext holds. Throws INVALID_BUNDLE for a plaintext that is not account contents or whose name breaks the display-name rules, since a name from outside is shown to people. */
+function parseContents(plaintext: string, damaged: string): AccountContents {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(plaintext);
+  } catch {
+    throw new CommsError(damaged, "INVALID_BUNDLE");
+  }
+  const contents = accountContentsSchema.safeParse(decoded);
+  if (
+    !contents.success ||
+    (contents.data.displayName !== undefined &&
+      parseDisplayName(contents.data.displayName) !== contents.data.displayName)
+  ) {
+    throw new CommsError(damaged, "INVALID_BUNDLE");
+  }
+  return {
+    privateKey: contents.data.privateKey,
+    ...(contents.data.displayName === undefined
+      ? {}
+      : { displayName: contents.data.displayName }),
+  };
+}
+
+const passphraseEnvelopeSchema = z
+  .object({
+    kdf: z.literal("scrypt"),
+    n: z.number().int().positive(),
+    r: z.number().int().positive(),
+    p: z.number().int().positive(),
+    salt: base64url,
+    iv: base64url,
+    tag: base64url,
+    ct: base64url,
+  })
+  .strict();
+
+const inviteEnvelopeSchema = z
+  .object({ iv: base64url, tag: base64url, ct: base64url })
+  .strict();
+
+function seal(
+  key: Buffer,
+  plaintext: string,
+): { iv: string; tag: string; ct: string } {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(BUNDLE_AAD);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf-8"), cipher.final()]);
+  return {
+    iv: iv.toString("base64url"),
+    tag: cipher.getAuthTag().toString("base64url"),
+    ct: ct.toString("base64url"),
+  };
+}
+
+/** The plaintext of a sealed envelope, or undefined if the key is wrong or the envelope was altered. */
+function open(
+  key: Buffer,
+  envelope: Readonly<{ iv: string; tag: string; ct: string }>,
+): string | undefined {
+  const decipher = createDecipheriv(
+    "aes-256-gcm",
+    key,
+    Buffer.from(envelope.iv, "base64url"),
+  );
+  decipher.setAAD(BUNDLE_AAD);
+  decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+  try {
+    return Buffer.concat([
+      decipher.update(Buffer.from(envelope.ct, "base64url")),
+      decipher.final(),
+    ]).toString("utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+function passphraseKey(
+  passphrase: string,
+  salt: Buffer,
+  cost: Readonly<{ n: number; r: number; p: number }>,
+): Buffer {
+  return scryptSync(passphrase, salt, KEY_BYTES, {
+    N: cost.n,
+    r: cost.r,
+    p: cost.p,
+    maxmem: SCRYPT_MAX_MEMORY,
+  });
+}
+
+/** Seals the account's contents under a passphrase, as one line of text. Throws WEAK_PASSPHRASE for a passphrase shorter than MIN_ACCOUNT_PASSPHRASE_LENGTH. */
+export function sealAccountBundle(
+  contents: Readonly<AccountContents>,
+  passphrase: string,
+): string {
+  if (passphrase.length < MIN_ACCOUNT_PASSPHRASE_LENGTH) {
+    throw new CommsError(
+      `An account export passphrase must be at least ${String(MIN_ACCOUNT_PASSPHRASE_LENGTH)} characters`,
+      "WEAK_PASSPHRASE",
+    );
+  }
+  const salt = randomBytes(SALT_BYTES);
+  const cost = { n: SCRYPT_COST, r: SCRYPT_BLOCK_SIZE, p: SCRYPT_PARALLELISM };
+  const envelope = {
+    kdf: "scrypt",
+    ...cost,
+    salt: salt.toString("base64url"),
+    ...seal(passphraseKey(passphrase, salt, cost), contentsText(contents)),
+  };
+  return `${ACCOUNT_BUNDLE_PREFIX}${Buffer.from(JSON.stringify(envelope)).toString("base64url")}`;
+}
+
+/** The account contents a bundle holds. Throws INVALID_BUNDLE for text that is not a bundle this build can read, and WRONG_PASSPHRASE when the passphrase does not open it. The cost parameters are read from the bundle but capped at this build's own, so a crafted bundle cannot make an import run for hours. */
+export function openAccountBundle(
+  bundle: string,
+  passphrase: string,
+): AccountContents {
+  const text = bundle.trim();
+  if (!text.startsWith(ACCOUNT_BUNDLE_PREFIX)) {
+    throw new CommsError("Not an agent-comms account bundle", "INVALID_BUNDLE");
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(
+      Buffer.from(
+        text.slice(ACCOUNT_BUNDLE_PREFIX.length),
+        "base64url",
+      ).toString("utf-8"),
+    );
+  } catch {
+    throw new CommsError("The account bundle is damaged", "INVALID_BUNDLE");
+  }
+  const envelope = passphraseEnvelopeSchema.safeParse(decoded);
+  if (
+    !envelope.success ||
+    envelope.data.n > SCRYPT_COST ||
+    envelope.data.r > SCRYPT_BLOCK_SIZE ||
+    envelope.data.p > SCRYPT_PARALLELISM
+  ) {
+    throw new CommsError("The account bundle is damaged", "INVALID_BUNDLE");
+  }
+  const key = passphraseKey(
+    passphrase,
+    Buffer.from(envelope.data.salt, "base64url"),
+    envelope.data,
+  );
+  const plaintext = open(key, envelope.data);
+  if (plaintext === undefined) {
+    throw new CommsError(
+      "The passphrase does not open this account bundle",
+      "WRONG_PASSPHRASE",
+    );
+  }
+  return parseContents(plaintext, "The account bundle is damaged");
+}
+
+/** The fields of an account invite both ends know: the invite's own single-use nonce is the secret, and the expiry and issuing device are bound in so a sealed key cannot be replayed under a different invite. */
+export interface AccountInviteSecret {
+  code: string;
+  expiresAt: string;
+  deviceId: string;
+}
+
+function inviteKey(invite: Readonly<AccountInviteSecret>): Buffer {
+  return Buffer.from(
+    hkdfSync(
+      "sha256",
+      Buffer.from(invite.code),
+      Buffer.from(`${invite.expiresAt}:${invite.deviceId}`),
+      INVITE_KEY_INFO,
+      KEY_BYTES,
+    ),
+  );
+}
+
+/** Seals the account's contents for the machine redeeming `invite`. The invite's nonce carries enough entropy to key it directly, with no passphrase stretching needed. */
+export function sealAccountKeyForInvite(
+  contents: Readonly<AccountContents>,
+  invite: Readonly<AccountInviteSecret>,
+): string {
+  return Buffer.from(
+    JSON.stringify(seal(inviteKey(invite), contentsText(contents))),
+  ).toString("base64url");
+}
+
+/** The account contents sealed for `invite`. Throws INVALID_BUNDLE when the text does not open under that invite. */
+export function openAccountKeyFromInvite(
+  sealed: string,
+  invite: Readonly<AccountInviteSecret>,
+): AccountContents {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(sealed, "base64url").toString("utf-8"));
+  } catch {
+    throw new CommsError("The sealed account key is damaged", "INVALID_BUNDLE");
+  }
+  const envelope = inviteEnvelopeSchema.safeParse(decoded);
+  const plaintext = envelope.success
+    ? open(inviteKey(invite), envelope.data)
+    : undefined;
+  if (plaintext === undefined) {
+    throw new CommsError(
+      "The sealed account key does not open under this invite",
+      "INVALID_BUNDLE",
+    );
+  }
+  return parseContents(plaintext, "The sealed account key is damaged");
+}

package/src/core/account-join.ts

@@ -0,0 +1,289 @@
+/**
+ * Joining a machine to an account (agent-comms#344): one deliberate act per new machine. A machine holding the account issues an account invite, an ordinary connection code (connection-code.ts) it also remembers as an invite; the person carries it to the new machine, which redeems it. Redeeming trusts the issuing device exactly as any connection code does, then asks that device, over the mesh's end-to-end authenticated request path (directly or relayed by the hub), for the account key, which comes back sealed under a key only the invite's holder can derive. The new machine then holds the account: its devices mint membership proofs as the account, so every machine already trusting the account's principal covers them with no per-pair step, and it replicates and can revoke from the account's grant ledger.
+ *
+ * The issuing device enforces the invite for real, not only the redeemer: it answers each invite once and never after its expiry, so a copied invite is worth nothing once used or stale, and it refuses to issue one that would stay valid for longer than an ordinary connection code (DEFAULT_CONNECTION_CODE_TTL_MS), which is already sized for a person relaying it by hand, since an invite is the account key to whoever redeems it first. Invites live only in the issuing store's memory, so a restart of that store before the invite is used cancels it.
+ *
+ * A join can carry a label for the joining machine. The issuing device validates it and keeps it as its own petname for the joiner's machine (naming.ts), so the machine the person just admitted is listed by the name they typed without a second step. The label and the machine id it names are the joiner's own assertion, which is acceptable only because whoever redeems an invite already receives the whole account; the petname is nothing but the issuing person's own view and is never gossiped.
+ *
+ * Neither half is an agent_comms tool action: an invite hands over the account key and a join replaces the machine's account, so both are `agent-comms account invite` and `agent-comms account join`, run by the person at the terminal (account-cli.ts), where nothing an agent is told can trigger them and the invite is never written into an agent's transcript.
+ */
+
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { IncomingManageRequest } from "wire-mesh-core/domain/mesh-session";
+import type { ManageOutcome } from "wire-mesh-core/domain/mesh-session";
+import {
+  openAccountKeyFromInvite,
+  sealAccountKeyForInvite,
+  type AccountInviteSecret,
+} from "./account-bundle.js";
+import { openAccountLedger } from "./account-ledger-store.js";
+import {
+  DEFAULT_CONNECTION_CODE_TTL_MS,
+  type ConnectionCodeLedger,
+  type GenerateConnectionCodeOptions,
+  type RedeemConnectionCodeOptions,
+} from "./connection-code.js";
+import type { GatewayTrust } from "./gateway-trust.js";
+import type { MeshStoreIdentity } from "./mesh-store-shared.js";
+import { parseDisplayName } from "./display-name.js";
+import { isDeviceIdHex } from "./room-path.js";
+import { CommsError, requireDisplayName } from "./store.js";
+import type { MeshTransport } from "./transport.js";
+import type { ConnectionCode } from "./types.js";
+import { importAccountKey, readAccountContents } from "./user-identity.js";
+import { toIdentityPort } from "./wire-mesh-identity.js";
+
+/** The request verb an invite's redeemer sends its issuer (params.verb), and the capability verb the manage-command carries only to satisfy manage-command.verb's grammar: the handler checks the invite itself, never a token. */
+export const ACCOUNT_JOIN_VERB = "account.join";
+const ACCOUNT_JOIN_CAPABILITY_VERB = "account:join";
+
+/** The outcomes sendRoomRequest gives when this side has no route to the device yet, as opposed to an answer from the device. */
+export const NO_ROUTE_CODES: ReadonlySet<string> = new Set([
+  "no_route",
+  "not_connected",
+]);
+const MS_PER_SECOND = 1000;
+/** How long a join waits for a route to the issuing device to come up: a hub dial and its first directory exchange take seconds, so this is generous without leaving a person waiting on an unreachable issuer for long. */
+const JOIN_ROUTE_WAIT_SECONDS = 30;
+export const JOIN_ROUTE_WAIT_MS = JOIN_ROUTE_WAIT_SECONDS * MS_PER_SECOND;
+/** Between attempts to reach the issuing device: short against the wait, long enough not to spin. */
+export const JOIN_ROUTE_RETRY_MS = 250;
+
+/** What became of an invite: answered with the account key, or expired unanswered. */
+export type AccountInviteOutcome = "redeemed" | "expired";
+
+export interface AccountInvite {
+  code: ConnectionCode;
+  /** Settles once the invite has been answered or has expired, whichever comes first. */
+  settled: Promise<AccountInviteOutcome>;
+}
+
+interface PendingInvite {
+  secret: AccountInviteSecret;
+  settle: (outcome: AccountInviteOutcome) => void;
+}
+
+export interface AccountJoinDeps {
+  requireIdentity: () => MeshStoreIdentity;
+  requireTransport: () => MeshTransport;
+  getPeerId: () => string;
+  connectionCodes: ConnectionCodeLedger;
+  gatewayTrust: GatewayTrust;
+  /** Re-evaluates whether the store should hold a hub session, after trust changes. */
+  reconsiderHub: () => void;
+  /** Redeems a connection code the ordinary way (freshness, single use, optional signature) and trusts the device it vouches for. */
+  redeemConnectionCode: (
+    candidate: Readonly<ConnectionCode>,
+    options: Readonly<RedeemConnectionCodeOptions>,
+  ) => Promise<unknown>;
+  /** Labels deviceHex as name in the viewer's own petnames (Naming.setPetname). */
+  setPetname: (deviceHex: string, name: string) => string;
+  /** Re-attaches the store to the account it now holds, so its own proofs and ledger switch at once. */
+  setIdentity: (identity: MeshStoreIdentity) => void;
+}
+
+export interface AccountJoinOptions extends RedeemConnectionCodeOptions {
+  /** What the issuing person calls this machine: kept by the issuing device as its petname for it. Must satisfy the display-name rules. */
+  label?: string;
+}
+
+export interface AccountJoinResult {
+  /** The account's principal id (hex) this machine now holds. */
+  principal: string;
+  /** Where the account this machine held before was set aside, when it held a different one. */
+  replacedFile?: string;
+}
+
+/** The label a join request asks the issuer to keep for the joiner's machine: undefined when it asks for none, "invalid" when it asks for one that is not a usable label for a full machine id (a label with no machine id included). */
+function joinerPetname(
+  params: Readonly<Record<string, unknown>>,
+): { machine: string; label: string } | undefined | "invalid" {
+  const label: unknown = "label" in params ? params.label : undefined;
+  const machine: unknown = "machine" in params ? params.machine : undefined;
+  if (label === undefined && machine === undefined) return undefined;
+  if (
+    typeof label !== "string" ||
+    typeof machine !== "string" ||
+    !isDeviceIdHex(machine.toLowerCase()) ||
+    parseDisplayName(label) !== label
+  ) {
+    return "invalid";
+  }
+  return { machine, label };
+}
+
+export class AccountJoin {
+  /** Invites this store issued that are neither answered nor known to have expired, keyed by their nonce. */
+  private readonly invites = new Map<string, PendingInvite>();
+
+  constructor(private readonly deps: Readonly<AccountJoinDeps>) {}
+
+  /** Issues an account invite vouching for this store's own device, valid for options.ttlMs (at most DEFAULT_CONNECTION_CODE_TTL_MS, the default). Throws INVITE_TTL_TOO_LONG for a longer one. Also trusts the account's own principal, so this machine holds a hub session the joining machine can reach it through, and admits the joined machine's devices once their proofs name the account. */
+  async invite(
+    options: Readonly<Omit<GenerateConnectionCodeOptions, "now">> = {},
+  ): Promise<AccountInvite> {
+    const ttlMs = options.ttlMs ?? DEFAULT_CONNECTION_CODE_TTL_MS;
+    if (ttlMs > DEFAULT_CONNECTION_CODE_TTL_MS) {
+      throw new CommsError(
+        `An account invite can stay valid for at most ${String(DEFAULT_CONNECTION_CODE_TTL_MS)} ms, since whoever redeems it first takes the account key`,
+        "INVITE_TTL_TOO_LONG",
+      );
+    }
+    const { clock } = this.deps.requireIdentity();
+    this.pruneExpired();
+    const code = await this.deps.connectionCodes.generate(
+      this.deps.getPeerId(),
+      { ...options, ttlMs, now: clock.now() },
+    );
+    const settled = new Promise<AccountInviteOutcome>((resolve) => {
+      this.invites.set(code.code, {
+        secret: {
+          code: code.code,
+          expiresAt: code.expiresAt,
+          deviceId: code.deviceId,
+        },
+        settle: resolve,
+      });
+    });
+    // Settles `settled` on expiry even when nothing else calls in to prune; unref'd so a pending invite never keeps a process alive by itself.
+    setTimeout(() => {
+      this.pruneExpired();
+    }, ttlMs).unref();
+    this.trustOwnAccount();
+    return { code, settled };
+  }
+
+  /** Answers an account.join request: the account key and name sealed for the named invite, once, and only before the invite expires. Every other request, including a second use of the same invite, is refused without saying whether the invite ever existed. */
+  readonly handleJoinRequest = async (
+    request: Readonly<IncomingManageRequest>,
+  ): Promise<ManageOutcome> => {
+    this.pruneExpired();
+    const { params } = request.command;
+    const code: unknown = "code" in params ? params.code : undefined;
+    const invite =
+      typeof code === "string" ? this.invites.get(code) : undefined;
+    if (invite === undefined) {
+      return Promise.resolve({ result: "error", code: "invalid_invite" });
+    }
+    const petname = joinerPetname(params);
+    if (petname === "invalid") {
+      return Promise.resolve({ result: "error", code: "invalid_label" });
+    }
+    // Before the invite is spent, so a petname file that cannot be written fails the request with the invite still usable rather than losing the invite and the label together.
+    if (petname !== undefined) {
+      this.deps.setPetname(petname.machine, petname.label);
+    }
+    this.invites.delete(invite.secret.code);
+    const { userIdentityOptions } = this.deps.requireIdentity();
+    const sealed = sealAccountKeyForInvite(
+      readAccountContents(userIdentityOptions),
+      invite.secret,
+    );
+    invite.settle("redeemed");
+    return Promise.resolve({ result: "ok", sealed });
+  };
+
+  /** Drops every invite whose expiry has passed by this store's clock, settling each as expired. */
+  private pruneExpired(): void {
+    const now = this.deps.requireIdentity().clock.now();
+    for (const [nonce, invite] of this.invites) {
+      if (Date.parse(invite.secret.expiresAt) > now) continue;
+      this.invites.delete(nonce);
+      invite.settle("expired");
+    }
+  }
+
+  /** Redeems an account invite and makes this machine hold the account it names. Throws INVALID_NAME for an unusable options.label before anything is redeemed, INVITE_REFUSED when the issuing device will not answer it (used, expired, cancelled by a restart, unreachable, or unwilling to take the label), and whatever redeeming the connection code itself throws before that. Redeeming trusts the issuing device so the key request can reach it; when the join then fails, that trust is withdrawn again unless the device was already trusted before, so a refused or unanswered invite leaves this machine trusting no one new. */
+  async join(
+    candidate: Readonly<ConnectionCode>,
+    options: Readonly<AccountJoinOptions> = {},
+  ): Promise<AccountJoinResult> {
+    const { label, ...redeemOptions } = options;
+    const named =
+      label === undefined
+        ? undefined
+        : requireDisplayName(label, "A machine label");
+    const trustedBefore = this.deps.gatewayTrust.isTrusted(candidate.deviceId);
+    await this.deps.redeemConnectionCode(candidate, redeemOptions);
+    try {
+      return await this.takeAccount(candidate, named);
+    } catch (error) {
+      if (!trustedBefore) {
+        this.deps.gatewayTrust.remove(candidate.deviceId);
+        this.deps.reconsiderHub();
+      }
+      throw error;
+    }
+  }
+
+  /** The half of join after the invite's issuer is trusted: fetch the account key from it and switch this machine to that account. */
+  private async takeAccount(
+    candidate: Readonly<ConnectionCode>,
+    label: string | undefined,
+  ): Promise<AccountJoinResult> {
+    const outcome = await this.requestAccountKey(candidate, label);
+    const sealed: unknown =
+      outcome.result === "ok" ? outcome.sealed : undefined;
+    if (typeof sealed !== "string") {
+      throw new CommsError(
+        `The issuing device refused the account invite (${outcome.result === "error" ? (outcome.message ?? outcome.code) : "no key in its answer"})`,
+        "INVITE_REFUSED",
+      );
+    }
+    const contents = openAccountKeyFromInvite(sealed, candidate);
+    const current = this.deps.requireIdentity();
+    const { identity, replacedFile } = importAccountKey(
+      current.userIdentityOptions,
+      contents,
+    );
+    this.deps.setIdentity({
+      ...current,
+      userIdentity: await toIdentityPort(identity),
+      accountLedger: await openAccountLedger({
+        userIdentityOptions: current.userIdentityOptions,
+        userIdentity: identity,
+        clock: current.clock,
+      }),
+    });
+    this.trustOwnAccount();
+    const principal = deviceIdToHex(Uint8Array.from(identity.deviceId));
+    return replacedFile === undefined
+      ? { principal }
+      : { principal, replacedFile };
+  }
+
+  /** Asks the invite's issuing device for the account key. Redeeming the invite has only just trusted that device, so the route to it (a hub session this store opens because it now trusts someone) may still be coming up: a request that found no route yet is retried until JOIN_ROUTE_WAIT_MS has passed, and any answer from the device itself is returned as it is. */
+  private async requestAccountKey(
+    invite: Readonly<ConnectionCode>,
+    label: string | undefined,
+  ): Promise<ManageOutcome> {
+    const { clock, machineIdentity } = this.deps.requireIdentity();
+    const labelling =
+      label === undefined
+        ? {}
+        : { label, machine: deviceIdToHex(machineIdentity.deviceId) };
+    const deadline = clock.now() + JOIN_ROUTE_WAIT_MS;
+    for (;;) {
+      const outcome = await this.deps.requireTransport().sendRoomRequest(
+        invite.deviceId,
+        {
+          verb: ACCOUNT_JOIN_CAPABILITY_VERB,
+          params: { verb: ACCOUNT_JOIN_VERB, code: invite.code, ...labelling },
+        },
+        { kind: "node" },
+      );
+      const noRouteYet =
+        outcome.result === "error" && NO_ROUTE_CODES.has(outcome.code);
+      if (!noRouteYet || clock.now() >= deadline) return outcome;
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, JOIN_ROUTE_RETRY_MS);
+      });
+    }
+  }
+
+  private trustOwnAccount(): void {
+    const { userIdentity } = this.deps.requireIdentity();
+    this.deps.gatewayTrust.addPrincipal(deviceIdToHex(userIdentity.deviceId));
+    this.deps.reconsiderHub();
+  }
+}