@cleocode/core 2026.9.26 → 2026.10.2

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

@@ -0,0 +1,277 @@
+/**
+ * The vault's connection and keys: a read-write device connection, the
+ * account master key, this device's certificate, and the stream data keys.
+ *
+ * Owner decision (2026-10-01): adding a device needs only `cleo login` and
+ * the one-time browser approval; that approval also hands the device the
+ * encryption key. So the account master key (MK) is escrowed on Cleo Nexus:
+ *
+ * 1. `GET /v1/account/keys/escrow` returns MK sealed to this device's X25519
+ *    key (`sealTo`), released only to an approved, active device. The client
+ *    opens it with the device's private key and checks it against the
+ *    escrow's verifier.
+ * 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.
+ * 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`,
+ *    with the trust state persisted in {@link NexusVaultState}.
+ *
+ * Threat model (cleo-nexus T082): the escrow `PUT` sends MK to the server
+ * over TLS, and the server stores it encrypted under a server-held key
+ * (`KEY_ESCROW_SECRET`). Snapshots are therefore encrypted at rest with keys
+ * Cleo Nexus can recover: this is server-escrowed encryption, not
+ * zero-knowledge end-to-end encryption. What the escrow does guarantee is
+ * that MK is released only to an approved, active device of the account,
+ * sealed to that device's key.
+ *
+ * A project's data key (PDK) is minted by its first pusher and stored
+ * wrapped by MK (`PUT /v1/projects/:id/keys/:userId`); the home stream key
+ * is derived from MK.
+ *
+ * No function here logs a key, and no error carries one.
+ *
+ * @task T12336
+ * @epic T12322
+ */
+import { nexusProjectKeysSchema, nexusUserKeysSchema } from '@cleocode/contracts';
+import { DeviceTrust as DeviceTrustSchema, KeyEscrowGrant, PutKeyEscrowResult, } from '@cleocode/contracts/cloud';
+import { z } from 'zod';
+import { openSealed, randomKey } from './crypto.js';
+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 { ensureNexusDeviceCredential, nexusApiErrorToAccountError } from './nexus-enrol.js';
+import { NexusVaultState } from './nexus-vault-state.js';
+/** Timeout of a snapshot blob upload or download. */
+export const NEXUS_VAULT_BLOB_TIMEOUT_MS = 10 * 60_000;
+/** The sealed-box context of an escrow release (must match the server, cleo-nexus T082). */
+export const escrowContext = (userId, deviceId) => `cleo-nexus/escrow/v1:${userId}:${deviceId}`;
+const b64 = (s) => Buffer.from(s, 'base64');
+function keyPairOf(kp) {
+    return { publicKey: b64(kp.publicKey), privateKey: b64(kp.privateKey) };
+}
+/**
+ * Open a read-write vault connection with this machine's device credential.
+ *
+ * @param opts - API URL, account, stores and test overrides.
+ * @returns The connection.
+ * @throws {NexusAccountError} Not signed in, device mode off, or no device keys.
+ */
+export async function connectNexusVault(opts = {}) {
+    assertNexusCloudDeviceMode();
+    const apiUrl = resolveNexusApiUrl(opts.apiUrl);
+    const handle = await ensureNexusDeviceCredential({ ...opts, apiUrl });
+    const device = handle.device;
+    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`');
+    }
+    const entryKeys = device.unseal().keys;
+    if (entryKeys === null) {
+        throw new NexusAccountError('E_NEXUS_VAULT_KEY_UNAVAILABLE', 'this device has no key pair (it was enrolled before device keys existed)', 'run `cleo logout nexus --revoke` and then `cleo login nexus` to enrol it again');
+    }
+    const base = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const timeoutMs = opts.timeoutMs ?? NEXUS_CLOUD_TIMEOUT_MS;
+    const blobTimeoutMs = opts.blobTimeoutMs ?? NEXUS_VAULT_BLOB_TIMEOUT_MS;
+    const http = new Http({
+        baseUrl: apiUrl,
+        token: bearer,
+        deviceId: device.deviceId,
+        fetch: (input, init) => base(input, { ...init, signal: AbortSignal.timeout(timeoutMs) }),
+        maxAttempts: 2,
+    });
+    const raw = (method, path, schema, body) => http.request(method, path, schema, body);
+    return {
+        apiUrl,
+        userId: device.userId,
+        deviceId: device.deviceId,
+        device,
+        keys: { encryption: keyPairOf(entryKeys.encryption), signing: keyPairOf(entryKeys.signing) },
+        http,
+        blobFetch: (input, init) => base(input, { ...init, signal: AbortSignal.timeout(blobTimeoutMs) }),
+        state: opts.vaultState ?? new NexusVaultState(),
+        warnings: nexusCredentialWarnings(handle.warnings),
+        raw,
+        async call(method, path, schema, body) {
+            try {
+                return await raw(method, path, schema, body);
+            }
+            catch (err) {
+                throw nexusApiErrorToAccountError(err);
+            }
+        },
+        async find(path, schema) {
+            try {
+                return await raw('GET', path, schema);
+            }
+            catch (err) {
+                if (err instanceof NexusError && err.status === 404)
+                    return null;
+                throw nexusApiErrorToAccountError(err);
+            }
+        },
+    };
+}
+const isConflict = (err, reason) => err instanceof NexusError &&
+    err.status === 409 &&
+    (reason === undefined || err.details?.['reason'] === reason);
+function keyUnavailable(message, fix) {
+    return new NexusAccountError('E_NEXUS_VAULT_KEY_UNAVAILABLE', message, fix);
+}
+async function openEscrow(conn) {
+    const grant = await conn.find('/v1/account/keys/escrow', KeyEscrowGrant);
+    if (grant === null)
+        return null;
+    if (grant.deviceId !== conn.deviceId) {
+        throw keyUnavailable('the server released the account key to another device id');
+    }
+    let mk;
+    try {
+        mk = openSealed(conn.keys.encryption, b64(grant.sealedMasterKey), escrowContext(conn.userId, conn.deviceId));
+    }
+    catch {
+        throw keyUnavailable('the escrowed account key does not open with this device key', 'run `cleo logout nexus --revoke` and `cleo login nexus` to enrol this machine again');
+    }
+    if (mk.length !== 32 || masterKeyVerifier(mk) !== grant.masterKeyVerifier) {
+        throw keyUnavailable('the escrowed account key does not match its verifier');
+    }
+    return { mk, kv: grant.keyVersion };
+}
+async function mintEscrow(conn) {
+    const existing = await conn.find('/v1/account/keys', nexusUserKeysSchema);
+    if (existing !== null) {
+        throw keyUnavailable('this account has an encryption key that is not escrowed, so it cannot be handed to this device', 'run `cleo cloud push` once on a device that already holds the key, so it escrows it');
+    }
+    const mk = randomKey();
+    try {
+        await conn.raw('PUT', '/v1/account/keys/escrow', PutKeyEscrowResult, {
+            masterKey: mk.toString('base64url'),
+            keyVersion: 1,
+            masterKeyVerifier: masterKeyVerifier(mk),
+        });
+        return { mk, kv: 1 };
+    }
+    catch (err) {
+        if (!isConflict(err))
+            throw nexusApiErrorToAccountError(err);
+        // Another device escrowed first: use its key.
+        const won = await openEscrow(conn);
+        if (won === null)
+            throw keyUnavailable('the account key was escrowed concurrently but is not readable');
+        return won;
+    }
+}
+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;
+    const grant = createDeviceGrant({
+        masterKey: mk,
+        userId: conn.userId,
+        keyVersion: kv,
+        recipient: {
+            deviceId: conn.deviceId,
+            encryptionPublicKey: conn.keys.encryption.publicKey,
+            signingPublicKey: conn.keys.signing.publicKey,
+        },
+        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);
+}
+/**
+ * Get the account master key for this device, minting and escrowing it on
+ * the account's first vault use, and certify this device under it.
+ *
+ * @param conn - A vault connection.
+ * @param opts - `readOnly`: never mint, escrow or certify (GET only); a missing escrow is
+ *   `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.
+ */
+export async function unlockNexusAccountKey(conn, opts = {}) {
+    const escrowed = await openEscrow(conn);
+    if (escrowed === null && opts.readOnly === true) {
+        // 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);
+    // 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) => {
+        const e = certifiedSigners(new Map([[unlocked.kv, unlocked.mk]]), conn.userId, trust, current, unlocked.kv);
+        return { trust: e.keyRotated || e.serverError ? current : e.state, result: e };
+    });
+    if (evaluation.keyRotated || evaluation.serverError) {
+        throw keyUnavailable(evaluation.keyRotated
+            ? '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 };
+}
+/**
+ * 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).
+ *
+ * @param conn - A vault connection.
+ * @param mk - The unlocked master key.
+ * @param projectId - The server's project id.
+ * @param mint - Whether a missing key may be created (push: yes; restore: no).
+ * @returns The project data key, or `null` when none exists and `mint` is false.
+ */
+export async function nexusProjectDataKey(conn, mk, projectId, mint) {
+    const path = `/v1/projects/${encodeURIComponent(projectId)}/keys`;
+    const read = async () => {
+        const list = await conn.find(path, nexusProjectKeysSchema);
+        const newest = list?.keys[0];
+        if (!newest)
+            return null;
+        try {
+            return unwrapProjectKey(mk, newest.wrappedProjectKey, projectId, newest.keyVersion);
+        }
+        catch {
+            throw keyUnavailable(`the project key of ${projectId} does not open with this account's key`);
+        }
+    };
+    const have = await read();
+    if (have !== null || !mint)
+        return have;
+    const pdk = newProjectKey();
+    try {
+        await conn.raw('PUT', `${path}/${encodeURIComponent(conn.userId)}`, z.looseObject({}), {
+            wrappedProjectKey: wrapProjectKey(mk, pdk, projectId, 1),
+            keyVersion: 1,
+        });
+        return pdk;
+    }
+    catch (err) {
+        if (!isConflict(err))
+            throw nexusApiErrorToAccountError(err);
+        const won = await read();
+        if (won === null)
+            throw keyUnavailable(`the project key of ${projectId} is not readable`);
+        return won;
+    }
+}
+/**
+ * The data key of the account's `home:` stream (derived from MK, never stored).
+ *
+ * @param mk - The unlocked master key.
+ * @returns The home stream key.
+ */
+export function nexusHomeDataKey(mk) {
+    return homeStreamKey(mk);
+}
+/** Re-export for callers that only need the URL resolver. */
+export { resolveNexusApiUrl };
+//# sourceMappingURL=nexus-vault-keys.js.map

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

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

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

@@ -0,0 +1,121 @@
+/**
+ * This machine's cloud vault state (`<cleoHome>/nexus-vault.json`):
+ * secret-free, machine-local bookkeeping the vault needs between runs.
+ *
+ * - Per account: the signer {@link TrustState} learned from
+ *   `certifiedSigners` (trust only tightens, so it must survive restarts).
+ * - Per (stream, local store): the snapshot this store last pushed or
+ *   restored, which decides "behind" (another device pushed since) and
+ *   "pending changes" (this store changed since).
+ *
+ * Every read-modify-write runs under a lock file and writes atomically (temp
+ * file + rename). A file this version cannot read (truncated, invalid, or
+ * written by a newer CLEO) is moved aside with a warning, never reset in
+ * place, so a downgrade or a torn write cannot silently discard the signer
+ * pins. Nothing here is secret: keys and tokens stay in the sealed device
+ * store.
+ *
+ * @task T12336
+ * @epic T12322
+ */
+import type { CloudWarning } from '@cleocode/contracts';
+import { z } from 'zod';
+import { type TrustState } from './keys.js';
+declare const streamStateSchema: z.ZodObject<{
+    /** The snapshot this store last pushed or restored. */
+    lastCheckpointId: z.ZodNullable<z.ZodString>;
+    /** Its coversSeq: an older snapshot is never restored over it without `--checkpoint`. */
+    lastCoversSeq: z.ZodNumber;
+    updatedAt: z.ZodString;
+    /**
+     * A push from this store that had not recorded its snapshot yet: the parent it
+     * pushed over (T13007). Cleared when the snapshot is recorded.
+     */
+    pushInFlight: z.ZodOptional<z.ZodObject<{
+        parentCheckpointId: z.ZodNullable<z.ZodString>;
+        at: z.ZodString;
+        gitTracked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    /**
+     * Paths (relative to the section root) the last synced snapshot marks as
+     * git-tracked: git's job, so they are left out of every file comparison
+     * with it, and a machine without git carries the marks on (T13019).
+     */
+    gitTracked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /**
+     * The last synced snapshot's plain files, path to digest (a prefix of the
+     * vault file digest), so a later comparison judges each file on its own,
+     * whatever either side's git tracks (T13038).
+     */
+    files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$loose>;
+/** What a store last synced with on a stream. */
+export type VaultStreamState = z.infer<typeof streamStateSchema>;
+/** Key of one local store on one stream. */
+export declare const vaultStreamKey: (streamId: string, storeRoot: string) => string;
+/** Warning code: the state file was unreadable or newer, and was moved aside. */
+export declare const W_NEXUS_VAULT_STATE_MOVED = "W_NEXUS_VAULT_STATE_MOVED";
+/**
+ * Read/modify/write access to the vault state file.
+ */
+export declare class NexusVaultState {
+    /** Absolute path of the state file. */
+    readonly path: string;
+    private warnings;
+    /** @param filePath - Override for tests; defaults to {@link resolveNexusVaultStatePath}. */
+    constructor(filePath?: string);
+    /** Warnings raised since the last call (a moved-aside file), for the command's result. */
+    drainWarnings(): CloudWarning[];
+    /** Run `fn` holding the state file's lock. */
+    private locked;
+    /** Move an unusable file aside (never overwrite it) and start empty. */
+    private moveAside;
+    private read;
+    private write;
+    /** Read, let `fn` change the state, and write it back, all under the lock. */
+    private update;
+    /** Read under the lock (moving an unusable file aside). */
+    private snapshot;
+    private account;
+    /** The account's persisted signer trust state. */
+    trust(apiUrl: string, userId: string): TrustState;
+    /** Persist the trust state returned by `certifiedSigners`. */
+    saveTrust(apiUrl: string, userId: string, trust: TrustState): void;
+    /**
+     * Read the account's trust state, let `fn` evaluate it, and persist the
+     * trust it returns, all under one lock.
+     *
+     * @param apiUrl - Account API URL.
+     * @param userId - Account user id.
+     * @param fn - Receives the current trust; returns the trust to store and a result.
+     * @returns `fn`'s result.
+     */
+    updateTrust<T>(apiUrl: string, userId: string, fn: (current: TrustState) => {
+        trust: TrustState;
+        result: T;
+    }): T;
+    /** What `storeRoot` last synced with on `streamId`, or `null`. */
+    stream(apiUrl: string, userId: string, streamId: string, storeRoot: string): VaultStreamState | null;
+    /**
+     * Record that a push from `storeRoot` is about to create a snapshot over
+     * `parentCheckpointId` (T13007). {@link saveStream} clears the mark; when a
+     * crash loses that write, the mark tells the next command that the head
+     * this device and replica pushed over that parent is this store's own, and
+     * what that snapshot marks and holds (`pushed`), so recovering it loses no
+     * per-path digest.
+     */
+    markPushInFlight(apiUrl: string, userId: string, streamId: string, storeRoot: string, parentCheckpointId: string | null, pushed?: {
+        gitTracked?: readonly string[];
+        files?: Readonly<Record<string, string>>;
+    }): void;
+    /** Record that `storeRoot` now holds `checkpointId` on `streamId`. */
+    saveStream(apiUrl: string, userId: string, streamId: string, storeRoot: string, value: {
+        lastCheckpointId: string;
+        lastCoversSeq: number;
+        gitTracked?: readonly string[];
+        files?: Readonly<Record<string, string>>;
+    }): void;
+}
+export {};
+//# sourceMappingURL=nexus-vault-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-vault-state.d.ts","sourceRoot":"","sources":["../../src/cloud/nexus-vault-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAc/D,QAAA,MAAM,iBAAiB;IACrB,uDAAuD;;IAEvD,yFAAyF;;;IAGzF;;;OAGG;;;;;;;IAUH;;;;OAIG;;IAEH;;;;OAIG;;iBAEH,CAAC;AAcH,iDAAiD;AACjD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAKjE,4CAA4C;AAC5C,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,WAAW,MAAM,WACxB,CAAC;AAQ3C,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAMrE;;GAEG;AACH,qBAAa,eAAe;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAsB;IAEtC,4FAA4F;gBAChF,QAAQ,CAAC,EAAE,MAAM;IAI7B,0FAA0F;IAC1F,aAAa,IAAI,YAAY,EAAE;IAM/B,8CAA8C;IAC9C,OAAO,CAAC,MAAM;IAyBd,wEAAwE;IACxE,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,IAAI;IAqBZ,OAAO,CAAC,KAAK;IAYb,8EAA8E;IAC9E,OAAO,CAAC,MAAM;IASd,2DAA2D;IAC3D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAMf,kDAAkD;IAClD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAKjD,8DAA8D;IAC9D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAMlE;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,EACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,GAC5D,CAAC;IASJ,kEAAkE;IAClE,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI;IAK1B;;;;;;;OAOG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,MAAM,GAAG,IAAI,EACjC,MAAM,GAAE;QAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAO,GACxF,IAAI;IAuBP,sEAAsE;IACtE,UAAU,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QACL,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAC1C,GACA,IAAI;CAcR"}