@cjhyy/code-shell-server 0.9.36 → 0.9.37

package/dist/bin/code-shell-cloud-account.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/code-shell-cloud-account.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { adoptCloudAccount, inspectCloudAccountAdoption, } from "../project-runtime/account-adoption.js";
+const help = `Usage: code-shell-cloud-account --inspect --data-dir <canonical path>
+       code-shell-cloud-account --adopt --data-dir <canonical path>
+         --evidence-dir <new private directory outside data-dir>
+         --account-origin <exact Account HTTPS origin> --account-id <UUID>
+         --installation-id <reviewed UUID> --owner-id <reviewed UUID>
+         --legacy-username <reviewed sole operator>
+
+Stop the Cloud controller and all projects first. Adoption durably preserves
+original authority files and SHA receipts before retiring legacy login. Evidence
+contains private password hashes. Make a full installation/volume backup too.
+Retry a failed adoption with exactly the same source, evidence and identities.
+This tool never contacts Account, accepts a password/token, or runs Docker.
+The bound Account must authenticate through the configured Cloud at first use.`;
+try {
+    const args = process.argv.slice(2);
+    if (args.length === 1 && ["--help", "-h"].includes(args[0]))
+        console.log(help);
+    else {
+        const mode = args.shift();
+        if (mode !== "--inspect" && mode !== "--adopt")
+            throw new Error("Choose --inspect or --adopt.");
+        const names = {
+            "--data-dir": "dataDir",
+            "--evidence-dir": "evidenceDirectory",
+            "--account-origin": "accountOrigin",
+            "--account-id": "accountId",
+            "--installation-id": "installationId",
+            "--owner-id": "ownerId",
+            "--legacy-username": "legacyUsername",
+        };
+        const options = {};
+        while (args.length) {
+            const name = args.shift(), key = names[name], value = args.shift();
+            if (!key || !value || value.startsWith("--") || key in options)
+                throw new Error("Unknown, duplicate or incomplete option.");
+            options[key] = value;
+        }
+        if (!options.dataDir ||
+            (mode === "--inspect"
+                ? Object.keys(options).length !== 1
+                : Object.keys(options).length !== Object.keys(names).length))
+            throw new Error("Supply every reviewed identity; use --help for usage.");
+        console.log(JSON.stringify(mode === "--inspect"
+            ? inspectCloudAccountAdoption(options.dataDir)
+            : adoptCloudAccount(options), null, 2));
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : "Cloud account adoption failed.");
+    process.exitCode = 1;
+}

package/dist/index.serve.d.ts

@@ -1,6 +1,9 @@
 /** Ready-made headless HTTP/WebSocket host and CLI composition helpers. */
 export * from "./serve/headless-server.js";
 export { startProjectControlServer, type ProjectControlServerOptions, } from "./project-runtime/control-server.js";
+export { CLOUD_MANAGEMENT_AUTHORITY_VERSION } from "./project-runtime/cloud-account-auth.js";
+export { adoptCloudAccount, inspectCloudAccountAdoption, type CloudAccountAdoptionOptions, } from "./project-runtime/account-adoption.js";
+export type { CloudAccountAuthority, CloudAccountPrincipal, CloudManagementSession, } from "./project-runtime/control-authority.js";
 export { parseServeArgs, resolveWebAppRoot, resolveWorkerCapabilityModules, resolveWorkerEntry, runServeCli, } from "./serve/cli.js";
 export { backupProjectInstallation, restoreProjectInstallation, type ProjectBackupOptions, type ProjectRestoreOptions, } from "./project-runtime/backup.js";
 export { readProjectSeccompProfile, type ProjectSeccompProfile, } from "./project-runtime/seccomp.js";

package/dist/index.serve.js

@@ -1,6 +1,8 @@
 /** Ready-made headless HTTP/WebSocket host and CLI composition helpers. */
 export * from "./serve/headless-server.js";
 export { startProjectControlServer, } from "./project-runtime/control-server.js";
+export { CLOUD_MANAGEMENT_AUTHORITY_VERSION } from "./project-runtime/cloud-account-auth.js";
+export { adoptCloudAccount, inspectCloudAccountAdoption, } from "./project-runtime/account-adoption.js";
 export { parseServeArgs, resolveWebAppRoot, resolveWorkerCapabilityModules, resolveWorkerEntry, runServeCli, } from "./serve/cli.js";
 export { backupProjectInstallation, restoreProjectInstallation, } from "./project-runtime/backup.js";
 export { readProjectSeccompProfile, } from "./project-runtime/seccomp.js";

package/dist/panels/management.js

@@ -396,6 +396,12 @@ export function createPanelManagement(options) {
                 source,
                 expectedRevision: current?.revision ?? null,
                 compatibility: compatibility(preview),
+                ...(current
+                    ? {
+                        installedVersion: current.app.version,
+                        installedPermissions: [...current.app.permissions],
+                    }
+                    : {}),
             };
             reviews.set(reviewToken, {
                 owner: context.ownerId,
@@ -458,7 +464,12 @@ export function createPanelManagement(options) {
                 preview: publicPreview,
                 expectedRevision: currentRevision,
                 compatibility: compatibility(preview),
-                ...(current ? { installedVersion: current.app.version } : {}),
+                ...(current
+                    ? {
+                        installedVersion: current.app.version,
+                        installedPermissions: [...current.app.permissions],
+                    }
+                    : {}),
             };
             reviews.set(value.reviewToken, {
                 owner: context.ownerId,

package/dist/panels/types.d.ts

@@ -57,11 +57,13 @@ export interface PanelReview {
     source: PanelGitSource;
     expectedRevision: string | null;
     compatibility: PanelCompatibility;
-}
-/** Trusted native hosts may review local sources without exposing paths to Web routes. */
-export interface PanelProjectReview extends Omit<PanelReview, "source"> {
+    /** The installed package selected for this project, when its manifest is available. */
     installedVersion?: string;
+    /** Reviewed permissions of that same installed package; an empty array is a known baseline. */
+    installedPermissions?: PanelAppPreview["permissions"];
 }
+/** Trusted native hosts may review local sources without exposing paths to Web routes. */
+export type PanelProjectReview = Omit<PanelReview, "source">;
 export interface PanelOperationContext {
     ownerId: string;
     authorize: () => boolean | Promise<boolean>;

package/dist/project-runtime/account-adoption.d.ts

@@ -0,0 +1,34 @@
+import { fsyncSync } from "node:fs";
+import { type CloudAccountBinding } from "./account-binding.js";
+export interface CloudAccountAdoptionOptions {
+    dataDir: string;
+    /** A new private directory outside the source. Authority evidence contains password hashes. */
+    evidenceDirectory: string;
+    accountOrigin: string;
+    accountId: string;
+    /** Both identities must be explicitly reviewed from the existing offline installation. */
+    installationId: string;
+    ownerId: string;
+    legacyUsername: string;
+    /** Fault seam; no user request can configure these hooks. */
+    io?: {
+        fsync?: typeof fsyncSync;
+    };
+}
+/** Read-only operator review; private runtime passwords and Hub hashes are excluded. */
+export declare function inspectCloudAccountAdoption(dataDir: string): {
+    installationId: string;
+    owners: any;
+    accountBinding: CloudAccountBinding | null;
+    projects: {
+        id: string;
+        status: import("./registry.js").ProjectStatus;
+        generation: number;
+    }[];
+    pending: boolean;
+};
+/** Offline, explicit adoption. Never rolls back or guesses authority from a username. */
+export declare function adoptCloudAccount(options: CloudAccountAdoptionOptions): {
+    binding: CloudAccountBinding;
+    evidenceDirectory: string;
+};

package/dist/project-runtime/account-adoption.js

@@ -0,0 +1,280 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { HubAuthStore } from "../hub/auth-store.js";
+import { CLOUD_ADOPTION_PENDING, isCloudAccountBinding, isCloudAccountOrigin, } from "./account-binding.js";
+import { ProjectRegistry } from "./registry.js";
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const FORMAT = "codeshell.cloud-account-adoption";
+const SOURCES = [
+    "project-control/registry.json",
+    "project-control/initialized",
+    "hub/auth.json",
+];
+function privateBytes(file, maximum = 1024 * 1024) {
+    const before = lstatSync(file);
+    if (!before.isFile() ||
+        before.isSymbolicLink() ||
+        before.nlink !== 1 ||
+        before.mode & 0o077 ||
+        before.size > maximum)
+        throw new Error("Adoption evidence must be a bounded private regular file.");
+    const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const after = fstatSync(fd);
+        if (after.dev !== before.dev ||
+            after.ino !== before.ino ||
+            after.nlink !== 1 ||
+            after.size !== before.size)
+            throw new Error("Adoption source changed while opening.");
+        const bytes = readFileSync(fd);
+        if (bytes.length !== before.size || bytes.length > maximum)
+            throw new Error("Adoption source changed while reading.");
+        return bytes;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function ordinaryDirectory(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077)
+        throw new Error("Adoption requires private ordinary directories.");
+    return stat;
+}
+/** Read-only operator review; private runtime passwords and Hub hashes are excluded. */
+export function inspectCloudAccountAdoption(dataDir) {
+    const source = realpathSync(dataDir);
+    if (source !== resolve(dataDir))
+        throw new Error("Adoption source must be canonical.");
+    ordinaryDirectory(source);
+    for (const name of SOURCES)
+        privateBytes(join(source, name));
+    const registry = new ProjectRegistry(source, Date.now, { offlineAccountAdoption: true });
+    try {
+        const data = JSON.parse(privateBytes(join(source, SOURCES[0])).toString("utf8"));
+        return {
+            installationId: registry.installationId,
+            owners: data.owners,
+            accountBinding: registry.accountBinding ?? null,
+            projects: registry.all().map(({ id, status, generation }) => ({ id, status, generation })),
+            pending: existsSync(join(source, "project-control", CLOUD_ADOPTION_PENDING)),
+        };
+    }
+    finally {
+        registry.close();
+    }
+}
+/** Offline, explicit adoption. Never rolls back or guesses authority from a username. */
+export function adoptCloudAccount(options) {
+    if (!isCloudAccountOrigin(options.accountOrigin) ||
+        !UUID.test(options.accountId) ||
+        !UUID.test(options.ownerId) ||
+        !UUID.test(options.installationId))
+        throw new Error("Explicit Cloud/Account UUIDs and exact Account origin are required.");
+    const source = realpathSync(options.dataDir);
+    if (source !== resolve(options.dataDir))
+        throw new Error("Adoption source must be canonical.");
+    const sourceStat = ordinaryDirectory(source);
+    const control = join(source, "project-control");
+    const controlStat = ordinaryDirectory(control);
+    ordinaryDirectory(join(source, "hub"));
+    const destination = resolve(options.evidenceDirectory);
+    const parent = realpathSync(dirname(destination));
+    ordinaryDirectory(parent);
+    if (parent !== dirname(destination))
+        throw new Error("Evidence destination must have a canonical parent.");
+    const rel = relative(source, destination);
+    if (!rel || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`)))
+        throw new Error("Preserve evidence outside the installation.");
+    // Never initialize a missing/wrong installation while performing adoption.
+    for (const name of SOURCES)
+        privateBytes(join(source, name));
+    const flush = options.io?.fsync ?? fsyncSync;
+    const sync = (path) => {
+        const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            flush(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const save = (file, bytes) => {
+        if (existsSync(file)) {
+            if (!privateBytes(file).equals(bytes))
+                throw new Error("Adoption evidence changed; preserve it for diagnosis.");
+        }
+        else {
+            const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+            try {
+                writeFileSync(fd, bytes);
+                flush(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        sync(file);
+        sync(dirname(file));
+    };
+    const registry = new ProjectRegistry(source, Date.now, {
+        fsync: flush,
+        offlineAccountAdoption: true,
+    });
+    try {
+        if (registry.installationId !== options.installationId ||
+            registry.all().some((project) => project.status !== "stopped"))
+            throw new Error("Adoption requires the reviewed installation with all projects stopped.");
+        if (!existsSync(destination)) {
+            mkdirSync(destination, { mode: 0o700 });
+            sync(parent);
+        }
+        ordinaryDirectory(destination);
+        const receiptPath = join(destination, "receipt.json");
+        let receipt;
+        if (existsSync(receiptPath)) {
+            receipt = JSON.parse(privateBytes(receiptPath).toString("utf8"));
+            if (receipt.format !== FORMAT ||
+                receipt.version !== 1 ||
+                !isCloudAccountBinding(receipt.binding) ||
+                receipt.source !== source ||
+                receipt.sourceDev !== sourceStat.dev ||
+                receipt.sourceIno !== sourceStat.ino ||
+                receipt.controllerDev !== controlStat.dev ||
+                receipt.controllerIno !== controlStat.ino ||
+                receipt.installationId !== options.installationId ||
+                receipt.binding.accountOrigin !== options.accountOrigin ||
+                receipt.binding.accountId !== options.accountId ||
+                receipt.binding.ownerId !== options.ownerId)
+                throw new Error("Adoption receipt does not match this explicit source and destination.");
+        }
+        else {
+            if (registry.accountBinding)
+                throw new Error("Bound Cloud requires its original adoption receipt.");
+            const originalRegistry = privateBytes(join(source, SOURCES[0]));
+            const data = JSON.parse(originalRegistry.toString("utf8"));
+            const auth = privateBytes(join(source, SOURCES[2]));
+            const authData = JSON.parse(auth.toString("utf8"));
+            const hub = new HubAuthStore({ dataDir: source });
+            if (!hub.isInitialized() ||
+                data.version !== 1 ||
+                data.owners.length !== 1 ||
+                data.owners[0].id !== options.ownerId ||
+                data.owners[0].username !== options.legacyUsername ||
+                authData.account?.username !== options.legacyUsername)
+                throw new Error("Explicit legacy owner must match the sole initialized operator.");
+            const binding = {
+                version: 1,
+                accountOrigin: options.accountOrigin,
+                accountId: options.accountId,
+                ownerId: options.ownerId,
+                managementEpoch: randomUUID(),
+                createdAt: Date.now(),
+            };
+            const bound = { ...data, version: 2, accountBinding: binding };
+            const revoked = { ...authData, sessions: [] };
+            receipt = {
+                format: FORMAT,
+                version: 1,
+                source,
+                sourceDev: sourceStat.dev,
+                sourceIno: sourceStat.ino,
+                controllerDev: controlStat.dev,
+                controllerIno: controlStat.ino,
+                installationId: options.installationId,
+                binding,
+                originals: {},
+                registryAfter: sha(Buffer.from(JSON.stringify(bound, null, 2) + "\n")),
+                authAfter: sha(Buffer.from(JSON.stringify(revoked, null, 2))),
+            };
+            for (const name of SOURCES) {
+                const bytes = privateBytes(join(source, name));
+                receipt.originals[name] = sha(bytes);
+                save(join(destination, name.replaceAll("/", "--")), bytes);
+            }
+            // Original evidence is fully flushed before publishing any adoption barrier.
+            save(receiptPath, Buffer.from(JSON.stringify(receipt, null, 2) + "\n"));
+        }
+        for (const name of SOURCES) {
+            const original = privateBytes(join(destination, name.replaceAll("/", "--")));
+            if (sha(original) !== receipt.originals[name])
+                throw new Error("Adoption evidence checksum mismatch.");
+        }
+        const originalData = JSON.parse(privateBytes(join(destination, SOURCES[0].replaceAll("/", "--"))).toString("utf8"));
+        const originalAuth = JSON.parse(privateBytes(join(destination, SOURCES[2].replaceAll("/", "--"))).toString("utf8"));
+        if (originalData.version !== 1 ||
+            originalData.installationId !== options.installationId ||
+            originalData.owners?.length !== 1 ||
+            originalData.owners[0].id !== options.ownerId ||
+            originalData.owners[0].username !== options.legacyUsername ||
+            originalAuth.account?.username !== options.legacyUsername ||
+            receipt.registryAfter !==
+                sha(Buffer.from(JSON.stringify({ ...originalData, version: 2, accountBinding: receipt.binding }, null, 2) + "\n")) ||
+            receipt.authAfter !==
+                sha(Buffer.from(JSON.stringify({ ...originalAuth, sessions: [] }, null, 2))))
+            throw new Error("Adoption receipt does not preserve the explicitly reviewed legacy authority.");
+        sync(receiptPath);
+        sync(destination);
+        const assertSource = () => {
+            const current = ordinaryDirectory(source), controller = ordinaryDirectory(control);
+            if (current.dev !== receipt.sourceDev ||
+                current.ino !== receipt.sourceIno ||
+                controller.dev !== receipt.controllerDev ||
+                controller.ino !== receipt.controllerIno)
+                throw new Error("Adoption source directory changed.");
+            for (const name of SOURCES) {
+                const value = sha(privateBytes(join(source, name)));
+                const allowed = [
+                    receipt.originals[name],
+                    name === SOURCES[0]
+                        ? receipt.registryAfter
+                        : name === SOURCES[2]
+                            ? receipt.authAfter
+                            : undefined,
+                ];
+                if (!allowed.includes(value))
+                    throw new Error("Adoption source changed; preserve evidence and diagnose before retrying.");
+            }
+        };
+        assertSource();
+        const pending = join(control, CLOUD_ADOPTION_PENDING);
+        const marker = Buffer.from(JSON.stringify({
+            format: FORMAT,
+            version: 1,
+            evidenceDirectory: destination,
+            receipt: sha(privateBytes(receiptPath)),
+        }) + "\n");
+        save(pending, marker);
+        assertSource();
+        if (!registry.accountBinding)
+            registry.bindAccount(receipt.binding);
+        if (JSON.stringify(registry.accountBinding) !== JSON.stringify(receipt.binding) ||
+            sha(privateBytes(join(source, SOURCES[0]))) !== receipt.registryAfter)
+            throw new Error("Cloud adoption binding changed.");
+        sync(join(source, SOURCES[0]));
+        sync(control);
+        assertSource();
+        new HubAuthStore({ dataDir: source }).revokeAllSessions();
+        sync(join(source, SOURCES[2]));
+        sync(join(source, "hub"));
+        assertSource();
+        save(join(destination, "completed.json"), Buffer.from(JSON.stringify({
+            format: FORMAT,
+            receipt: sha(privateBytes(receiptPath)),
+            registry: receipt.registryAfter,
+            auth: receipt.authAfter,
+        }) + "\n"));
+        if (existsSync(pending)) {
+            if (!privateBytes(pending).equals(marker))
+                throw new Error("Adoption pending marker changed.");
+            unlinkSync(pending);
+            sync(control);
+        }
+        return { binding: { ...receipt.binding }, evidenceDirectory: destination };
+    }
+    finally {
+        registry.close();
+    }
+}

package/dist/project-runtime/account-binding.d.ts

@@ -0,0 +1,12 @@
+/** Explicit single-operator adoption; account display names never confer ownership. */
+export interface CloudAccountBinding {
+    version: 1;
+    accountOrigin: string;
+    accountId: string;
+    ownerId: string;
+    managementEpoch: string;
+    createdAt: number;
+}
+export declare const CLOUD_ADOPTION_PENDING = "account-adoption-pending.json";
+export declare function isCloudAccountOrigin(value: unknown): value is string;
+export declare function isCloudAccountBinding(value: unknown): value is CloudAccountBinding;

package/dist/project-runtime/account-binding.js

@@ -0,0 +1,33 @@
+export const CLOUD_ADOPTION_PENDING = "account-adoption-pending.json";
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+export function isCloudAccountOrigin(value) {
+    if (typeof value !== "string" || value.length > 2048)
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.origin === value &&
+            !url.username &&
+            !url.password &&
+            (url.protocol === "https:" ||
+                (url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))));
+    }
+    catch {
+        return false;
+    }
+}
+export function isCloudAccountBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const row = value;
+    return (Object.keys(row).sort().join() ===
+        ["version", "accountOrigin", "accountId", "ownerId", "managementEpoch", "createdAt"]
+            .sort()
+            .join() &&
+        row.version === 1 &&
+        isCloudAccountOrigin(row.accountOrigin) &&
+        UUID.test(row.accountId) &&
+        UUID.test(row.ownerId) &&
+        UUID.test(row.managementEpoch) &&
+        Number.isSafeInteger(row.createdAt) &&
+        row.createdAt >= 0);
+}

package/dist/project-runtime/backup.d.ts

@@ -1,3 +1,5 @@
+import { fsyncSync } from "node:fs";
+import { rm } from "node:fs/promises";
 export interface ProjectBackupOptions {
     dataDir: string;
     destination: string;
@@ -8,6 +10,11 @@ export interface ProjectRestoreOptions {
     source: string;
     destination: string;
     helperImage: string;
+    /** Fault injection for offline restore durability tests. */
+    io?: {
+        fsync?: typeof fsyncSync;
+        removeMarker?: typeof rm;
+    };
 }
 /** Offline, owner-only backup. It never stops projects or modifies their volumes. */
 export declare function backupProjectInstallation(options: ProjectBackupOptions): Promise<{

package/dist/project-runtime/backup.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
-import { constants, createWriteStream } from "node:fs";
+import { closeSync, constants, createWriteStream, fsyncSync, fstatSync, lstatSync, openSync, writeFileSync, } from "node:fs";
 import { lstat, mkdir, open, readdir, realpath, rm, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
@@ -381,6 +381,7 @@ function validateManifest(value) {
             path.split("/").some((part) => !part || part === "." || part === "..") ||
             /[\0\r\n]/.test(path) ||
             path === "restore-in-progress" ||
+            ["project-runtime-secrets", "administrator-setup.txt", "environment.json"].some((obsolete) => path.startsWith(obsolete + "/")) ||
             path.startsWith("project-control.lock/") ||
             path === "project-control.lock" ||
             !entry ||
@@ -425,21 +426,48 @@ export async function restoreProjectInstallation(options) {
         same(digest(await controlBytes(join(source, "control"), path)), expected);
     await docker(["image", "inspect", options.helperImage]);
     const destination = await exclusiveDestination(source, resolve(options.destination));
+    const marker = join(destination, "restore-in-progress");
+    const directories = new Set([destination]);
+    const sync = (path) => {
+        const before = lstatSync(path);
+        if (before.isSymbolicLink() || (!before.isFile() && !before.isDirectory()))
+            throw new Error("Restore durability requires ordinary files and directories.");
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const current = fstatSync(fd);
+            if (current.dev !== before.dev || current.ino !== before.ino)
+                throw new Error("Restore storage changed while opening.");
+            (options.io?.fsync ?? fsyncSync)(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const persistMarker = (rearm = false) => {
+        try {
+            writeFileSync(marker, "1\n", { mode: 0o600, flag: "wx" });
+        }
+        catch (error) {
+            if (!rearm || error.code !== "EEXIST")
+                throw error;
+        }
+        sync(marker);
+        sync(destination);
+        sync(dirname(destination));
+    };
     const created = [];
     let registry;
     try {
-        await writeFile(join(destination, "restore-in-progress"), "1\n", {
-            mode: 0o600,
-            flag: "wx",
-            flush: true,
-        });
+        persistMarker();
         for (const [path, expected] of Object.entries(manifest.control)) {
             const bytes = await controlBytes(join(source, "control"), path);
             same(digest(bytes), expected);
             await mkdir(dirname(join(destination, path)), { recursive: true, mode: 0o700 });
+            for (let parent = dirname(join(destination, path)); parent !== destination; parent = dirname(parent))
+                directories.add(parent);
             await writeFile(join(destination, path), bytes, { mode: 0o600, flag: "wx", flush: true });
         }
-        registry = new ProjectRegistry(destination);
+        registry = new ProjectRegistry(destination, Date.now, { fsync: options.io?.fsync });
         const rows = registry.all();
         if (registry.installationId !== manifest.installationId ||
             rows.some((p) => p.status !== "stopped") ||
@@ -450,6 +478,10 @@ export async function restoreProjectInstallation(options) {
         if (!auth.isInitialized())
             throw new Error("Backup administrator is not initialized.");
         auth.revokeAllSessions();
+        // HubAuthStore publishes by rename. Persist the replacement and its directory
+        // before a new namespace or removal of the restore barrier can become visible.
+        sync(join(destination, "hub/auth.json"));
+        sync(join(destination, "hub"));
         registry.renewInstallationForRestore();
         const installationId = registry.installationId;
         for (const volume of manifest.volumes) {
@@ -472,7 +504,12 @@ export async function restoreProjectInstallation(options) {
         for (const path of ["project-runtime-secrets", "administrator-setup.txt", "environment.json"])
             await rm(join(destination, path), { recursive: true, force: true });
         registry.all();
-        await rm(join(destination, "restore-in-progress"));
+        // Copied file bytes were flushed individually; their new directory entries
+        // must also survive a crash before the installation is advertised as usable.
+        for (const path of [...directories].sort((a, b) => b.length - a.length))
+            sync(path);
+        await (options.io?.removeMarker ?? rm)(marker);
+        sync(destination);
         return {
             destination,
             installationId,
@@ -482,6 +519,15 @@ export async function restoreProjectInstallation(options) {
         };
     }
     catch (error) {
+        let barrierError;
+        try {
+            // In particular, unlink may have succeeded before its directory fsync
+            // failed. Re-establish and persist the barrier before any cleanup awaits.
+            persistMarker(true);
+        }
+        catch (failure) {
+            barrierError = failure;
+        }
         // Only delete volumes created by this restore and still carrying its exact labels.
         for (const { name, expected } of created.reverse()) {
             try {
@@ -492,6 +538,8 @@ export async function restoreProjectInstallation(options) {
                 /* Preserve a busy/changed volume for operator inspection. */
             }
         }
+        if (barrierError)
+            throw new AggregateError([error, barrierError], `Restore failed and its durable barrier could not be confirmed; keep ${destination} offline.`, { cause: error });
         throw error; // Keep the marked offline directory as recovery evidence; never advertise success.
     }
     finally {

package/dist/project-runtime/cloud-account-auth.d.ts

@@ -0,0 +1,23 @@
+import { type CloudAccountBinding } from "./account-binding.js";
+import type { CloudAccountAuthority, CloudManagementSession, ProjectControlAuthority } from "./control-authority.js";
+export declare const CLOUD_MANAGEMENT_AUTHORITY_VERSION = 2;
+export declare const CLOUD_MANAGEMENT_COOKIE = "cs_cloud_management";
+export declare function cloudManagementSessionView(session: CloudManagementSession): {
+    id: string;
+    kind: "cloud-management";
+    audience: string;
+    installationId: string;
+    accountOrigin: string;
+    accountId: string;
+    managementEpoch: string;
+    expiresAt: number;
+};
+/** An explicitly bound Account controls one existing single-operator installation. */
+export declare function createCloudAccountAuth(options: {
+    binding: CloudAccountBinding;
+    installationId: string;
+    publicOrigin: string;
+    authority: CloudAccountAuthority;
+    onRevoke(sessionId: string): void;
+    now?: () => number;
+}): ProjectControlAuthority;