@cleocode/core 2026.10.3 → 2026.10.4

package/dist/cloud/nexus-project-names.js

@@ -0,0 +1,314 @@
+/**
+ * The account's Cleo Nexus projects by name (T13102): the list the guided
+ * first run of `cleo login nexus` shows on a machine with no linked project,
+ * and the name resolution behind `cleo cloud restore <name>`.
+ *
+ * - A project's display name is its plaintext label, else its id. Its
+ *   `encryptedName` is NOT opened by default: the format is not specified yet
+ *   (cleo-nexus T098: cipher, AAD with the key version, re-encryption on
+ *   rotation), and nothing in CLEO writes it. A caller may pass `openName`
+ *   (the seam the spec's reader will fill); a name that does not open falls
+ *   back to the label with one warning and never fails the list.
+ * - Names are matched exactly first, then case-insensitively, against the
+ *   display name, the label and the id. One match restores; several are
+ *   refused with the candidates listed (`E_NEXUS_PROJECT_AMBIGUOUS`); none is
+ *   `E_NEXUS_PROJECT_NOT_FOUND`. A UUID is taken as an id without listing.
+ * - Names and organization names from the server are shown with control,
+ *   zero-width, separator and bidi characters removed; a listed id that is
+ *   not a CLEO `ProjectId` is left out; commands quote every word for a POSIX
+ *   shell, and the machine-read restore command names the immutable id.
+ *
+ * Every request is a `GET`. No function here logs, and no result or error
+ * carries a key or a token.
+ *
+ * @task T13102
+ * @epic T12322
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { ProjectId } from '@cleocode/contracts/cloud';
+import { readDeclaredProjectIdentity } from '@cleocode/paths';
+import { NexusAccountError, resolveNexusApiUrl } from './nexus-auth.js';
+import { listNexusCloudProjects } from './nexus-cloud.js';
+/** Warning code: some project names are encrypted and could not be opened on this device. */
+export const W_NEXUS_PROJECT_NAME_LOCKED = 'W_NEXUS_PROJECT_NAME_LOCKED';
+/** Warning code: the server listed a project whose id is not a CLEO project id; it was left out. */
+export const W_NEXUS_PROJECT_ID_INVALID = 'W_NEXUS_PROJECT_ID_INVALID';
+/** A UUID project id: taken as an id without listing. */
+const UUID_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A legacy 12-hex project id (`ProjectId`): an id when no name matches it. */
+const LEGACY_ID = /^[0-9a-f]{12}$/;
+/**
+ * Never echoed from a server-held name: C0/C1 controls, the Arabic letter
+ * mark, zero-width characters, line/paragraph separators, bidirectional
+ * embeddings, overrides and isolates, and the byte-order mark.
+ */
+const UNSAFE_NAME_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g;
+/** A word a POSIX shell takes literally without quotes. */
+const SHELL_SAFE = /^[A-Za-z0-9._@%+=:,/-]+$/;
+/**
+ * A reference that matched several projects or none. `publicDetails` is
+ * secret-free and the CLI forwards it as the envelope's `error.details`.
+ */
+export class NexusProjectRefError extends NexusAccountError {
+    /** The reference and its candidates. */
+    publicDetails;
+    /**
+     * @param code - `E_NEXUS_PROJECT_AMBIGUOUS` or `E_NEXUS_PROJECT_NOT_FOUND`.
+     * @param message - Human message.
+     * @param fix - Remedy.
+     * @param publicDetails - The reference and its candidates.
+     */
+    constructor(code, message, fix, publicDetails) {
+        super(code, message, fix);
+        this.publicDetails = publicDetails;
+    }
+}
+/**
+ * A server-held name made safe to print: control and bidi-override characters removed.
+ *
+ * @param raw - Name as the server or the decryption gave it.
+ * @returns The cleaned name, or `null` when nothing printable is left.
+ */
+export function safeNexusProjectName(raw) {
+    const clean = (raw ?? '').replace(UNSAFE_NAME_CHARS, '').trim();
+    return clean === '' ? null : clean;
+}
+/**
+ * Quote a word for a POSIX shell (single quotes; `'` becomes `'\''`).
+ *
+ * @param word - The word.
+ * @returns It unchanged when it needs no quoting, else single-quoted.
+ */
+export function shellQuoteWord(word) {
+    return SHELL_SAFE.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/** Open every `encryptedName` with `opener`, if any; failures become one warning, never an error. */
+async function openNames(items, opener, warnings) {
+    const opened = new Map();
+    if (opener === undefined)
+        return opened;
+    let failed = 0;
+    let firstReason = '';
+    for (const item of items) {
+        if (!item.encryptedName)
+            continue;
+        try {
+            opened.set(item.projectId, await opener(item.projectId, item.encryptedName));
+        }
+        catch (err) {
+            failed += 1;
+            if (firstReason === '')
+                firstReason = err instanceof Error ? err.message : String(err);
+        }
+    }
+    if (failed > 0) {
+        warnings.push({
+            code: W_NEXUS_PROJECT_NAME_LOCKED,
+            message: `${failed} project name(s) are encrypted and could not be opened on this device (${firstReason}); showing the label or id instead`,
+        });
+    }
+    return opened;
+}
+/** One list item as a named project, without its restore command yet. */
+function namedProject(item, decrypted, deviceId) {
+    const fromName = safeNexusProjectName(decrypted);
+    const label = safeNexusProjectName(item.label);
+    const [name, nameSource] = fromName
+        ? [fromName, 'encrypted-name']
+        : label
+            ? [label, 'label']
+            : [item.projectId, 'id'];
+    return {
+        projectId: item.projectId,
+        name,
+        nameSource,
+        label,
+        organizationName: safeNexusProjectName(item.organizationName),
+        lastSyncAt: item.lastSyncAt ?? null,
+        hasBackup: item.headCheckpointId === undefined ? null : item.headCheckpointId !== null,
+        onThisDevice: deviceId !== null && item.replicas.some((r) => r.deviceId === deviceId),
+        restoreCommand: null,
+        restoreByNameCommand: null,
+    };
+}
+/**
+ * The projects a reference names: exact matches on the id, display name or
+ * label first; when there are none, case-insensitive matches on the names.
+ *
+ * @param projects - The account's projects.
+ * @param ref - A project name, label or id.
+ * @returns Every match (one: resolved; several: ambiguous; none: not found).
+ */
+export function matchNexusProjects(projects, ref) {
+    const want = ref.trim();
+    if (want === '')
+        return [];
+    const names = (p) => [p.name, p.label].filter((n) => n !== null);
+    const exact = projects.filter((p) => p.projectId === want || names(p).includes(want));
+    if (exact.length > 0)
+        return exact;
+    const folded = want.toLowerCase();
+    return projects.filter((p) => names(p).some((n) => n.toLowerCase() === folded));
+}
+/**
+ * ` --api-url <origin>` when the origin is not the one a bare `cleo` command
+ * would use (`$CLEO_NEXUS_API_URL`, else the default), so a printed command
+ * reaches the same server.
+ *
+ * @param apiUrl - API origin.
+ * @returns The flag with a leading space, or `''`.
+ */
+export function nexusApiUrlFlag(apiUrl) {
+    let fallback;
+    try {
+        fallback = resolveNexusApiUrl();
+    }
+    catch {
+        fallback = null;
+    }
+    return apiUrl === fallback ? '' : ` --api-url ${shellQuoteWord(apiUrl)}`;
+}
+/**
+ * The exact `cleo cloud restore` command for a project, by its id: the id
+ * never changes, while a name can be renamed or matched by a newer project
+ * between printing and running (review LOW-4). For agents and scripts.
+ *
+ * @param project - The project (its id is a validated `ProjectId`).
+ * @param apiUrl - API origin (added as `--api-url` when not the default).
+ * @returns The command.
+ */
+export function nexusRestoreCommand(project, apiUrl) {
+    return `cleo cloud restore ${shellQuoteWord(project.projectId)}${nexusApiUrlFlag(apiUrl)}`;
+}
+/**
+ * The same restore by name, for a person to type: only when the name resolves
+ * to this project alone and cannot be read as a flag or an id; else `null`.
+ *
+ * @param project - The project.
+ * @param all - Every project of the account, for the uniqueness check.
+ * @param apiUrl - API origin (added as `--api-url` when not the default).
+ * @returns The command, or `null`.
+ */
+export function nexusRestoreByNameCommand(project, all, apiUrl) {
+    const matches = matchNexusProjects(all, project.name);
+    const byName = project.nameSource !== 'id' &&
+        !project.name.startsWith('-') &&
+        !UUID_ID.test(project.name) &&
+        matches.length === 1 &&
+        matches[0]?.projectId === project.projectId;
+    return byName
+        ? `cleo cloud restore ${shellQuoteWord(project.name)}${nexusApiUrlFlag(apiUrl)}`
+        : null;
+}
+/**
+ * The list items whose id is a CLEO project id (a UUID or a legacy 12-hex
+ * id); any other id is left out with a warning, so a hostile or broken
+ * server cannot put arbitrary text into a printed command (review MED-1).
+ */
+function validItems(items, warnings) {
+    const valid = items.filter((item) => ProjectId.safeParse(item.projectId).success);
+    if (valid.length < items.length) {
+        warnings.push({
+            code: W_NEXUS_PROJECT_ID_INVALID,
+            message: `left out ${items.length - valid.length} project(s) whose id the server sent is not a CLEO project id`,
+        });
+    }
+    return valid;
+}
+/**
+ * `GET /v1/projects` (E13, every page) with display names and, for each
+ * project this machine can restore, the exact restore commands.
+ *
+ * @param opts - Device id, name opener, API URL, stores and test overrides.
+ * @returns The named projects, whether the list is complete, and warnings.
+ * @throws {NexusAccountError} When the list itself cannot be read.
+ */
+export async function listNexusNamedProjects(opts = {}) {
+    const { deviceId, openName, ...vault } = opts;
+    const list = await listNexusCloudProjects(vault);
+    const warnings = [...list.warnings];
+    const items = validItems(list.projects, warnings);
+    const opened = await openNames(items, openName, warnings);
+    const named = items.map((item) => namedProject(item, opened.get(item.projectId) ?? null, deviceId ?? null));
+    const projects = named.map((p) => {
+        const restorable = p.hasBackup !== false && !p.onThisDevice;
+        return {
+            ...p,
+            restoreCommand: restorable ? nexusRestoreCommand(p, list.apiUrl) : null,
+            restoreByNameCommand: restorable ? nexusRestoreByNameCommand(p, named, list.apiUrl) : null,
+        };
+    });
+    return {
+        apiUrl: list.apiUrl,
+        projects,
+        incomplete: list.paging.pageLimitReached || list.paging.projectsTruncated,
+        warnings,
+    };
+}
+/** One candidate line: name, id, organization and last sync. */
+function candidateLine(p) {
+    const org = p.organizationName ? `, ${p.organizationName}` : '';
+    const sync = p.lastSyncAt ? `, last sync ${p.lastSyncAt}` : '';
+    return `${p.name} (${p.projectId}${org}${sync})`;
+}
+/**
+ * Resolve a project name, label or id to the server's project id, for
+ * `cleo cloud restore <name>`. A UUID is taken as the id without a request.
+ *
+ * @param ref - What the user typed.
+ * @param opts - Name opener, API URL, stores and test overrides.
+ * @returns The project id and how it matched.
+ * @throws {NexusProjectRefError} `E_NEXUS_PROJECT_AMBIGUOUS` (the candidates
+ *   are listed) or `E_NEXUS_PROJECT_NOT_FOUND`.
+ * @throws {NexusAccountError} When the project list cannot be read.
+ */
+export async function resolveNexusProjectRef(ref, opts = {}) {
+    const want = ref.trim();
+    if (UUID_ID.test(want))
+        return { projectId: want.toLowerCase(), name: null, matchedBy: 'id' };
+    const listed = await listNexusNamedProjects({ ...opts, deviceId: null });
+    const matches = matchNexusProjects(listed.projects, want);
+    const only = matches.length === 1 ? matches[0] : undefined;
+    if (only) {
+        return only.projectId === want
+            ? { projectId: only.projectId, name: null, matchedBy: 'id' }
+            : { projectId: only.projectId, name: only.name, matchedBy: 'name' };
+    }
+    if (matches.length > 1) {
+        const candidates = matches.map((p) => ({
+            ...p,
+            restoreCommand: nexusRestoreCommand(p, listed.apiUrl),
+        }));
+        throw new NexusProjectRefError('E_NEXUS_PROJECT_AMBIGUOUS', `"${safeNexusProjectName(want) ?? want}" matches ${matches.length} projects: ${matches.map(candidateLine).join('; ')}`, `restore one by its id: ${candidates.map((c) => c.restoreCommand).join(' | ')}`, { ref: want, candidates });
+    }
+    if (LEGACY_ID.test(want))
+        return { projectId: want, name: null, matchedBy: 'id' };
+    throw new NexusProjectRefError('E_NEXUS_PROJECT_NOT_FOUND', `no project of this account at ${listed.apiUrl} is named "${safeNexusProjectName(want) ?? want}"${listed.incomplete ? ' (the project list was cut short, so it may exist; use its id)' : ''}`, 'run `cleo cloud projects` to list the projects, then pass a name or id from it', { ref: want, candidates: [] });
+}
+/**
+ * Refuse to restore a project into a directory nested inside another CLEO
+ * project (review LOW-5): `cleo cloud restore <name>` without `--into`
+ * restores into the current directory, and from a subdirectory of a project
+ * that would create a second project inside the first. The directory itself
+ * may be a project root (the restore checks it holds the same project); the
+ * home directory never counts as an enclosing project.
+ *
+ * @param into - The restore target; defaults to the current directory.
+ * @throws {NexusAccountError} `E_NEXUS_VAULT_TARGET_OCCUPIED` naming the enclosing project.
+ */
+export function assertNexusRestoreTarget(into) {
+    const target = path.resolve(into ?? process.cwd()); // CWD-OK: restore target directory, not a project root lookup
+    const home = path.resolve(os.homedir());
+    let dir = path.dirname(target);
+    for (;;) {
+        if (dir !== home && readDeclaredProjectIdentity(dir)) {
+            throw new NexusAccountError('E_NEXUS_VAULT_TARGET_OCCUPIED', `${target} is inside the CLEO project at ${dir}; restoring here would nest a second project in it`, `run it in ${dir} (or pass --into ${shellQuoteWord(dir)}) to restore that project there, or pass --into an empty directory outside it`);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}
+//# sourceMappingURL=nexus-project-names.js.map

package/dist/cloud/nexus-project-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-project-names.js","sourceRoot":"","sources":["../../src/cloud/nexus-project-names.ts"],"names":[],"mappings":"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"}

package/dist/cloud/nexus-vault-keys.d.ts

@@ -13,6 +13,9 @@
  * 2. No escrow and no account keys: this is the account's first vault use.
  *    The client mints MK and escrows it (`PUT`, insert-only). A concurrent
  *    first device loses the insert with 409 and reads the winner's key.
+ *    Since T13100 `cleo login nexus` runs steps 1 to 4 right after enrolment
+ *    ({@link provisionNexusAccount}); `cleo cloud push` still does them for a
+ *    device that logged in before that.
  * 3. The device certifies itself under MK (a self-grant, `PUT
  *    /v1/devices/:id/key`), so other devices can verify its snapshots.
  * 4. Signer trust comes from `certifiedSigners` over `GET /v1/devices/trust`,
@@ -33,15 +36,16 @@
  * No function here logs a key, and no error carries one.
  *
  * @task T12336
+ * @task T13100
  * @epic T12322
  */
-import type { CloudWarning } from '@cleocode/contracts';
+import type { CloudWarning, NexusAccountSetup } from '@cleocode/contracts';
 import { type KeyPair } from './crypto.js';
 import { type FetchLike, Http, type ResponseSchema } from './http.js';
 import { type TrustedSigners } from './keys.js';
 import { resolveNexusApiUrl } from './nexus-auth.js';
 import { type NexusCloudOptions } from './nexus-cloud.js';
-import type { SealedNexusDevice } from './nexus-device.js';
+import { type SealedNexusDevice } from './nexus-device.js';
 import { NexusVaultState } from './nexus-vault-state.js';
 /** Timeout of a snapshot blob upload or download. */
 export declare const NEXUS_VAULT_BLOB_TIMEOUT_MS: number;
@@ -107,6 +111,33 @@ export interface NexusAccountKey {
 export declare function unlockNexusAccountKey(conn: NexusVaultConnection, opts?: {
     readOnly?: boolean;
 }): Promise<NexusAccountKey>;
+/** Options of {@link provisionNexusAccount}. */
+export interface ProvisionNexusAccountOptions extends NexusVaultOptions {
+    /**
+     * The device entry to act as. `cleo login nexus` passes the entry it just
+     * stored, so the setup runs on that new device credential (the escrow routes
+     * accept only device credentials). Default: the stored credential, as
+     * {@link connectNexusVault} finds it.
+     */
+    device?: SealedNexusDevice;
+}
+/**
+ * Make the account ready for encrypted backups on this device (onboarding A,
+ * T13100): read the escrowed account master key, or mint and escrow it when
+ * the account has none (a 409 means another device won: its key is read,
+ * never re-minted), then certify this device under it and record the signer
+ * trust state in {@link NexusVaultState}. It is {@link unlockNexusAccountKey}
+ * with a report, so a later `cleo cloud push` finds everything in place and
+ * mints nothing; it is idempotent.
+ *
+ * It never throws: a server without key escrow answers `unsupported`, any
+ * other failure answers `failed` with the step and the remedy. No key is in
+ * the result, and a failure message is redacted of the device credential.
+ *
+ * @param opts - API URL, stores, the device to act as, and test overrides.
+ * @returns What the setup did.
+ */
+export declare function provisionNexusAccount(opts?: ProvisionNexusAccountOptions): Promise<NexusAccountSetup>;
 /**
  * The data key of a project stream: unwrap the newest wrapped key, or mint
  * and store one when the project has none yet (its first push).

package/dist/cloud/nexus-vault-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nexus-vault-keys.d.ts","sourceRoot":"","sources":["../../src/cloud/nexus-vault-keys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nexus-vault-keys.d.ts","sourceRoot":"","sources":["../../src/cloud/nexus-vault-keys.ts"],"names":[],"mappings":"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"}

package/dist/cloud/nexus-vault-keys.js

@@ -13,6 +13,9 @@
  * 2. No escrow and no account keys: this is the account's first vault use.
  *    The client mints MK and escrows it (`PUT`, insert-only). A concurrent
  *    first device loses the insert with 409 and reads the winner's key.
+ *    Since T13100 `cleo login nexus` runs steps 1 to 4 right after enrolment
+ *    ({@link provisionNexusAccount}); `cleo cloud push` still does them for a
+ *    device that logged in before that.
  * 3. The device certifies itself under MK (a self-grant, `PUT
  *    /v1/devices/:id/key`), so other devices can verify its snapshots.
  * 4. Signer trust comes from `certifiedSigners` over `GET /v1/devices/trust`,
@@ -33,6 +36,7 @@
  * No function here logs a key, and no error carries one.
  *
  * @task T12336
+ * @task T13100
  * @epic T12322
  */
 import { nexusProjectKeysSchema, nexusUserKeysSchema } from '@cleocode/contracts';
@@ -43,6 +47,7 @@ import { Http, NexusError } from './http.js';
 import { certifiedSigners, createDeviceGrant, homeStreamKey, masterKeyVerifier, newProjectKey, unwrapProjectKey, wrapProjectKey, } from './keys.js';
 import { NexusAccountError, resolveNexusApiUrl } from './nexus-auth.js';
 import { assertNexusCloudDeviceMode, NEXUS_CLOUD_TIMEOUT_MS, nexusCredentialWarnings, } from './nexus-cloud.js';
+import { redactNexusDeviceSecrets } from './nexus-device.js';
 import { ensureNexusDeviceCredential, nexusApiErrorToAccountError } from './nexus-enrol.js';
 import { NexusVaultState } from './nexus-vault-state.js';
 /** Timeout of a snapshot blob upload or download. */
@@ -64,7 +69,10 @@ export async function connectNexusVault(opts = {}) {
     assertNexusCloudDeviceMode();
     const apiUrl = resolveNexusApiUrl(opts.apiUrl);
     const handle = await ensureNexusDeviceCredential({ ...opts, apiUrl });
-    const device = handle.device;
+    return vaultConnectionOf(handle.device, apiUrl, opts, handle.warnings);
+}
+/** A vault connection acting as `device` (its current credential and keys). */
+function vaultConnectionOf(device, apiUrl, opts, credentialWarnings) {
     const bearer = device.currentBearer();
     if (bearer === null) {
         throw new NexusAccountError('E_NEXUS_NOT_SIGNED_IN', `not signed in to Cleo Nexus at ${apiUrl}`, 'run `cleo login nexus`');
@@ -93,7 +101,7 @@ export async function connectNexusVault(opts = {}) {
         http,
         blobFetch: (input, init) => base(input, { ...init, signal: AbortSignal.timeout(blobTimeoutMs) }),
         state: opts.vaultState ?? new NexusVaultState(),
-        warnings: nexusCredentialWarnings(handle.warnings),
+        warnings: nexusCredentialWarnings(credentialWarnings),
         raw,
         async call(method, path, schema, body) {
             try {
@@ -166,6 +174,10 @@ async function openEscrow(conn) {
     }
     return { mk, kv: grant.keyVersion };
 }
+/**
+ * Mint the account master key and escrow it (insert-only). `adopted` is `true` when another
+ * device escrowed first (409): its key is read and used, and this device never mints again.
+ */
 async function mintEscrow(conn) {
     const existing = await conn.find('/v1/account/keys', nexusUserKeysSchema);
     if (existing !== null) {
@@ -178,7 +190,7 @@ async function mintEscrow(conn) {
             keyVersion: 1,
             masterKeyVerifier: masterKeyVerifier(mk),
         });
-        return { mk, kv: 1 };
+        return { mk, kv: 1, adopted: false };
     }
     catch (err) {
         // Backstop: unreachable while GET and PUT escrow ship together (cleo-nexus #24), since
@@ -191,15 +203,16 @@ async function mintEscrow(conn) {
         const won = await openEscrow(conn);
         if (won === null)
             throw keyUnavailable('the account key was escrowed concurrently but is not readable');
-        return won;
+        return { ...won, adopted: true };
     }
 }
+/** Certify this device under MK unless it already is; `wrote` says whether this call did. */
 async function ensureCertified(conn, mk, kv) {
     const trust = await conn.call('GET', '/v1/devices/trust', DeviceTrustSchema);
     const mine = conn.keys.signing.publicKey.toString('base64');
     const certified = trust.certificates.some((c) => c.deviceId === conn.deviceId && c.keyVersion === kv && c.signingPublicKey === mine && c.live);
     if (certified)
-        return trust;
+        return { trust, wrote: false };
     const grant = createDeviceGrant({
         masterKey: mk,
         userId: conn.userId,
@@ -212,7 +225,7 @@ async function ensureCertified(conn, mk, kv) {
         signer: { deviceId: conn.deviceId, signing: conn.keys.signing },
     });
     await conn.call('PUT', `/v1/devices/${encodeURIComponent(conn.deviceId)}/key`, z.looseObject({}), grant);
-    return conn.call('GET', '/v1/devices/trust', DeviceTrustSchema);
+    return { trust: await conn.call('GET', '/v1/devices/trust', DeviceTrustSchema), wrote: true };
 }
 /**
  * Get the account master key for this device, minting and escrowing it on
@@ -227,16 +240,46 @@ async function ensureCertified(conn, mk, kv) {
  *   has no key escrow route; a mapped API error otherwise.
  */
 export async function unlockNexusAccountKey(conn, opts = {}) {
+    return (await unlockAccount(conn, opts.readOnly === true, { step: 'escrow-read' })).key;
+}
+/**
+ * {@link unlockNexusAccountKey}, reporting how the key was obtained. `progress.step` names the
+ * step running, so a caller that catches a failure can say where it happened.
+ */
+async function unlockAccount(conn, readOnly, progress) {
+    progress.step = 'escrow-read';
     const escrowed = await openEscrow(conn);
-    if (escrowed === null && opts.readOnly === true) {
+    if (escrowed === null && readOnly) {
         // Nothing was ever pushed from any device: a read has nothing to read, and
         // must not mint the account key as a side effect.
         throw new NexusAccountError('E_NEXUS_VAULT_EMPTY', 'the cloud vault is empty: no device has pushed a snapshot to this account yet', 'run `cleo cloud push` on a device that has the data');
     }
-    const unlocked = escrowed ?? (await mintEscrow(conn));
-    const trust = opts.readOnly === true
-        ? await conn.call('GET', '/v1/devices/trust', DeviceTrustSchema)
-        : await ensureCertified(conn, unlocked.mk, unlocked.kv);
+    let unlocked;
+    let escrow;
+    if (escrowed !== null) {
+        unlocked = escrowed;
+        escrow = 'fetched';
+    }
+    else {
+        // The account's first device. Since T13100 `cleo login nexus` does this right after
+        // enrolment; a push still gets here for a device that logged in before that.
+        progress.step = 'escrow-mint';
+        const minted = await mintEscrow(conn);
+        unlocked = minted;
+        escrow = minted.adopted ? 'adopted' : 'minted';
+    }
+    progress.step = 'certify';
+    let trust;
+    let certificate = null;
+    if (readOnly) {
+        trust = await conn.call('GET', '/v1/devices/trust', DeviceTrustSchema);
+    }
+    else {
+        const certified = await ensureCertified(conn, unlocked.mk, unlocked.kv);
+        trust = certified.trust;
+        certificate = certified.wrote ? 'new' : 'existing';
+    }
+    progress.step = 'trust';
     // Read, evaluate and persist the trust state under one lock, so two
     // concurrent commands cannot interleave and lose a narrowed pin.
     const evaluation = conn.state.updateTrust(conn.apiUrl, conn.userId, (current) => {
@@ -248,7 +291,84 @@ export async function unlockNexusAccountKey(conn, opts = {}) {
             ? 'the account key was rotated and this device does not hold the new one'
             : 'the server declared an account key version no rotation explains');
     }
-    return { masterKey: unlocked.mk, keyVersion: unlocked.kv, signers: evaluation.signers };
+    return {
+        key: { masterKey: unlocked.mk, keyVersion: unlocked.kv, signers: evaluation.signers },
+        escrow,
+        certificate,
+    };
+}
+/** What each setup step does, for a failure message. */
+const SETUP_STEP_LABELS = {
+    connect: 'opening the vault connection with the device credential',
+    'escrow-read': 'reading the escrowed account key',
+    'escrow-mint': 'creating and escrowing the account key',
+    certify: 'certifying this device under the account key',
+    trust: 'recording the device trust state',
+};
+/** The remedy of a failed setup step whose error carried none. */
+const SETUP_RETRY_FIX = 'run `cleo login nexus` again; `cleo cloud push` also finishes the setup on this device';
+/**
+ * Make the account ready for encrypted backups on this device (onboarding A,
+ * T13100): read the escrowed account master key, or mint and escrow it when
+ * the account has none (a 409 means another device won: its key is read,
+ * never re-minted), then certify this device under it and record the signer
+ * trust state in {@link NexusVaultState}. It is {@link unlockNexusAccountKey}
+ * with a report, so a later `cleo cloud push` finds everything in place and
+ * mints nothing; it is idempotent.
+ *
+ * It never throws: a server without key escrow answers `unsupported`, any
+ * other failure answers `failed` with the step and the remedy. No key is in
+ * the result, and a failure message is redacted of the device credential.
+ *
+ * @param opts - API URL, stores, the device to act as, and test overrides.
+ * @returns What the setup did.
+ */
+export async function provisionNexusAccount(opts = {}) {
+    const progress = { step: 'connect' };
+    // The bearer in use, so a failure message that quotes it (fetch quotes a malformed header
+    // value) is redacted even when it does not have the credential's shape.
+    let bearer = opts.device?.currentBearer() ?? null;
+    try {
+        const conn = opts.device !== undefined
+            ? vaultConnectionOf(opts.device, resolveNexusApiUrl(opts.apiUrl), opts, [])
+            : await connectNexusVault(opts);
+        bearer = conn.device.currentBearer();
+        const unlocked = await unlockAccount(conn, false, progress);
+        const how = unlocked.escrow === 'minted'
+            ? 'the account key was created and escrowed on Cleo Nexus'
+            : 'this device received the account key from Cleo Nexus escrow';
+        return {
+            status: 'ready',
+            escrow: unlocked.escrow,
+            certificate: unlocked.certificate ?? 'existing',
+            keyVersion: unlocked.key.keyVersion,
+            summary: `Your account is ready for encrypted backups: ${how}, and this device is certified to use it.`,
+        };
+    }
+    catch (err) {
+        if (err instanceof NexusAccountError && err.code === 'E_NEXUS_VAULT_UNSUPPORTED') {
+            const fix = err.fix ?? 'upgrade the Cleo Nexus server';
+            return {
+                status: 'unsupported',
+                code: err.code,
+                fix,
+                summary: `signed in, but encrypted backups are not available: ${err.message}. Fix: ${fix}`,
+            };
+        }
+        const code = err instanceof NexusAccountError ? err.code : 'E_NEXUS_REQUEST_FAILED';
+        const raw = err instanceof Error ? err.message : String(err);
+        const message = redactNexusDeviceSecrets(bearer !== null && bearer !== '' ? raw.split(bearer).join('[redacted]') : raw);
+        const fix = (err instanceof NexusAccountError ? err.fix : undefined) ?? SETUP_RETRY_FIX;
+        const step = progress.step;
+        return {
+            status: 'failed',
+            step,
+            code,
+            message,
+            fix,
+            summary: `signed in, but encrypted backups are not set up: step ${step} (${SETUP_STEP_LABELS[step]}) failed with ${code}: ${message}. Fix: ${fix}`,
+        };
+    }
 }
 /**
  * Why Cleo Nexus refused this device's first key for a project (403), as an