@cleocode/core 2026.10.2 → 2026.10.4

package/dist/cloud/nexus-project-names.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 type { CloudWarning, NexusNamedProject } from '@cleocode/contracts';
+import { NexusAccountError } from './nexus-auth.js';
+import { type NexusCloudProjectsOptions } from './nexus-cloud.js';
+/** Warning code: some project names are encrypted and could not be opened on this device. */
+export declare 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 declare const W_NEXUS_PROJECT_ID_INVALID = "W_NEXUS_PROJECT_ID_INVALID";
+/** Opens one project's `encryptedName`; throws when it cannot. */
+export type NexusProjectNameOpener = (projectId: string, encryptedName: string) => Promise<string>;
+/** Options of {@link listNexusNamedProjects} and {@link resolveNexusProjectRef}. */
+export interface NexusNamedProjectsOptions extends NexusCloudProjectsOptions {
+    /** This machine's device id, to mark projects already here; `null`/absent marks none. */
+    deviceId?: string | null;
+    /**
+     * Opener of `encryptedName`. None by default: the format is not specified yet
+     * (cleo-nexus T098), so names show as their label or id until it is.
+     */
+    openName?: NexusProjectNameOpener;
+}
+/** The account's projects with display names. */
+export interface NexusNamedProjectsResult {
+    /** API origin asked. */
+    apiUrl: string;
+    /** Every visible project, newest first. */
+    projects: NexusNamedProject[];
+    /** The list stopped short (a server ceiling or the page budget): a project may be missing. */
+    incomplete: boolean;
+    /** Non-fatal problems. */
+    warnings: CloudWarning[];
+}
+/** What a project reference resolved to. */
+export interface NexusProjectRef {
+    /** The server's project id. */
+    projectId: string;
+    /** The display name it matched, or `null` when it was taken as an id. */
+    name: string | null;
+    /** `id`: the reference was the project id; `name`: a name or label. */
+    matchedBy: 'id' | 'name';
+}
+/** The candidates an ambiguous or missing reference reports (the envelope's `error.details`). */
+export interface NexusProjectRefDetails {
+    /** The reference given. */
+    ref: string;
+    /** The projects it matched, each with a by-id restore command. */
+    candidates: NexusNamedProject[];
+}
+/**
+ * A reference that matched several projects or none. `publicDetails` is
+ * secret-free and the CLI forwards it as the envelope's `error.details`.
+ */
+export declare class NexusProjectRefError extends NexusAccountError {
+    /** The reference and its candidates. */
+    readonly publicDetails: NexusProjectRefDetails;
+    /**
+     * @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: 'E_NEXUS_PROJECT_AMBIGUOUS' | 'E_NEXUS_PROJECT_NOT_FOUND', message: string, fix: string, publicDetails: NexusProjectRefDetails);
+}
+/**
+ * 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 declare function safeNexusProjectName(raw: string | null | undefined): string | null;
+/**
+ * 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 declare function shellQuoteWord(word: string): string;
+/**
+ * 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 declare function matchNexusProjects(projects: readonly NexusNamedProject[], ref: string): NexusNamedProject[];
+/**
+ * ` --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 declare function nexusApiUrlFlag(apiUrl: string): string;
+/**
+ * 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 declare function nexusRestoreCommand(project: NexusNamedProject, apiUrl: string): string;
+/**
+ * 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 declare function nexusRestoreByNameCommand(project: NexusNamedProject, all: readonly NexusNamedProject[], apiUrl: string): string | null;
+/**
+ * `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 declare function listNexusNamedProjects(opts?: NexusNamedProjectsOptions): Promise<NexusNamedProjectsResult>;
+/**
+ * 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 declare function resolveNexusProjectRef(ref: string, opts?: NexusNamedProjectsOptions): Promise<NexusProjectRef>;
+/**
+ * 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 declare function assertNexusRestoreTarget(into?: string): void;
+//# sourceMappingURL=nexus-project-names.d.ts.map

package/dist/cloud/nexus-project-names.d.ts.map

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

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;
@@ -101,11 +105,39 @@ export interface NexusAccountKey {
  *   `E_NEXUS_VAULT_EMPTY`.
  * @returns The key, its version and the trusted signers.
  * @throws {NexusAccountError} `E_NEXUS_VAULT_KEY_UNAVAILABLE` when the key
- *   cannot be obtained or verified; a mapped API error otherwise.
+ *   cannot be obtained or verified; `E_NEXUS_VAULT_UNSUPPORTED` when the server
+ *   has no key escrow route; a mapped API error otherwise.
  */
 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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"}