@addai/node 0.30.13 → 0.30.15

package/dist/entitybox-capacity-provisioner.js

@@ -0,0 +1,404 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxCapacityProvisioner = exports.entityboxCapacityLabels = void 0;
+exports.readEntityboxCapacity = readEntityboxCapacity;
+exports.observeEntityboxCapacity = observeEntityboxCapacity;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const child_process_1 = require("child_process");
+const perf_hooks_1 = require("perf_hooks");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_application_boundary_1 = require("./entitybox-application-boundary");
+const entitybox_display_binding_1 = require("./entitybox-display-binding");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const programs = __importStar(require("./entitybox-capacity-programs"));
+const uuid = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const fail = () => new entitybox_execution_lease_1.EntityboxExecutionError('Dedicated computer provisioning could not be verified');
+const sha = (s) => (0, crypto_1.createHash)('sha256').update(s).digest('hex');
+const programHash = sha((0, entitybox_recovery_store_1.entityboxCanonical)(programs));
+const labels = (plan, role) => ({
+    'ai.add.entitybox.provision.version': '1', 'ai.add.entitybox.provision.capacity': plan.capacityId,
+    'ai.add.entitybox.provision.desktop': plan.desktopId, 'ai.add.entitybox.provision.runtime': plan.runtimeId,
+    'ai.add.entitybox.provision.plan': sha((0, entitybox_recovery_store_1.entityboxCanonical)(plan)), 'ai.add.entitybox.provision.role': role,
+});
+exports.entityboxCapacityLabels = labels;
+const match = (actual, expected) => !!actual && Object.entries(expected).every(([k, v]) => actual[k] === v);
+/** Docker mutations have no observation timeout: a timed-out CLI is not proof
+ * that the daemon stopped creating/starting a resource. A hung operation keeps
+ * the durable reservation, rather than starting a replacement. */
+function nativeDocker(context) {
+    return (args, input) => new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('docker', ['--context', context, ...args], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+        let output = '', size = 0, invalid = false;
+        child.stdout.on('data', b => { size += b.length; if (size > 2 * 1024 * 1024)
+            invalid = true;
+        else
+            output += b.toString(); });
+        child.stderr.resume();
+        child.stdin.on('error', () => { invalid = true; });
+        child.once('error', () => reject(fail()));
+        child.once('close', code => code === 0 && !invalid ? resolve(output.trim()) : reject(fail()));
+        child.stdin.end(input);
+    });
+}
+function readJson(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 32768)
+            throw fail();
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw fail();
+    }
+}
+/** Publish an immutable complete file. A partial write cannot look like a
+ * reusable reservation or receipt. An existing name never grants ownership. */
+function publish(directory, name, value) {
+    const pending = path.join(directory, 'pending-' + (0, crypto_1.randomUUID)() + '.json');
+    let fd;
+    try {
+        fd = fs.openSync(pending, 'wx', 0o600);
+        fs.writeFileSync(fd, (0, entitybox_recovery_store_1.entityboxCanonical)(value));
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.linkSync(pending, path.join(directory, name));
+        if (process.platform !== 'win32') {
+            const handle = fs.openSync(directory, 'r');
+            try {
+                fs.fsyncSync(handle);
+            }
+            finally {
+                fs.closeSync(handle);
+            }
+        }
+    }
+    catch {
+        throw fail();
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        try {
+            fs.unlinkSync(pending);
+        }
+        catch { }
+    }
+}
+function directoryFor(value) {
+    if (typeof value !== 'string' || !path.isAbsolute(value) || value.startsWith('\\\\'))
+        throw fail();
+    fs.mkdirSync(value, { recursive: true, mode: 0o700 });
+    if (fs.lstatSync(value).isSymbolicLink())
+        throw fail();
+    return fs.realpathSync(value);
+}
+function parsePlan(value) {
+    if (!value || Object.keys(value).sort().join(',') !== 'capacityId,desktopId,dockerContext,imageId,programsSha256,runtimeId,version' || value.version !== 1
+        || ![value.capacityId, value.runtimeId, value.desktopId].every(v => uuid.test(v)) || !/^sha256:[a-f0-9]{64}$/.test(value.imageId)
+        || !/^[-a-zA-Z0-9_.]{1,80}$/.test(value.dockerContext) || value.programsSha256 !== programHash)
+        throw fail();
+    return value;
+}
+function portOf(c) {
+    const ports = c?.NetworkSettings?.Ports, bindings = c?.HostConfig?.PortBindings, entries = ports?.['5900/tcp'], requested = bindings?.['5900/tcp'];
+    if (!ports || Object.entries(ports).some(([key, value]) => key !== '5900/tcp' && value != null) || !Array.isArray(entries) || entries.length !== 1 || entries[0].HostIp !== '127.0.0.1'
+        || !bindings || Object.keys(bindings).length !== 1 || !Array.isArray(requested) || requested.length !== 1 || requested[0].HostIp !== '127.0.0.1')
+        throw fail();
+    const port = Number(entries[0].HostPort);
+    if (!Number.isSafeInteger(port) || port < 1024 || port > 65535)
+        throw fail();
+    return port;
+}
+/** NEW offline dedicated capacity only. This is deliberately unregistered in
+ * the shared desktop command runner/reconciler. The server must reserve a new
+ * native desktop identity before invoking it, then publish the verified VNC
+ * descriptor through its existing authorization path. */
+class EntityboxCapacityProvisioner {
+    docker;
+    plan;
+    directory;
+    result;
+    constructor(config, docker, reserved) {
+        this.docker = docker;
+        this.plan = Object.freeze(reserved ?? { version: 1, capacityId: (0, crypto_1.randomUUID)(), runtimeId: config.runtimeId, desktopId: config.desktopId, imageId: config.imageId, dockerContext: config.dockerContext ?? 'desktop-linux', programsSha256: programHash });
+        this.directory = directoryFor(config.directory);
+        this.password = config.vncPassword;
+    }
+    password;
+    static create(config, docker) {
+        if (config.enabled !== true)
+            return undefined;
+        if (!uuid.test(config.runtimeId) || !uuid.test(config.desktopId) || !/^sha256:[a-f0-9]{64}$/.test(config.imageId)
+            || !/^[-a-zA-Z0-9_.]{1,80}$/.test(config.dockerContext ?? 'desktop-linux') || typeof config.vncPassword !== 'string' || !/^[A-Za-z0-9_-]{8}$/.test(config.vncPassword))
+            throw fail();
+        return new EntityboxCapacityProvisioner(config, docker ?? nativeDocker(config.dockerContext ?? 'desktop-linux'));
+    }
+    /** Continue a server-claimed plan in its one physical helper. This is not
+     * resumption: run() still atomically reserves the desktop before ANY Docker
+     * operation and rejects an existing reservation, even for the same plan. */
+    static createReserved(config, plan, docker) {
+        if (config.enabled !== true)
+            return undefined;
+        const reserved = parsePlan(JSON.parse((0, entitybox_recovery_store_1.entityboxCanonical)(plan)));
+        if (reserved.runtimeId !== config.runtimeId || reserved.desktopId !== config.desktopId || reserved.imageId !== config.imageId || reserved.dockerContext !== (config.dockerContext ?? 'desktop-linux'))
+            throw fail();
+        // Reuse the normal configuration validation before constructing the helper.
+        if (!EntityboxCapacityProvisioner.create(config, docker))
+            throw fail();
+        return new EntityboxCapacityProvisioner(config, docker ?? nativeDocker(reserved.dockerContext), reserved);
+    }
+    /** Calls on this one owner join. A new object/process cannot repeat the
+     * operation: the desktop reservation remains, even after an ambiguous error. */
+    provision() {
+        this.result ??= this.run().catch(() => { throw fail(); }).finally(() => { this.password = ''; });
+        return this.result;
+    }
+    async inspect(id, role) {
+        const result = JSON.parse(await this.docker(['container', 'inspect', id]));
+        const c = result?.[0];
+        if (!Array.isArray(result) || result.length !== 1 || !/^[a-f0-9]{64}$/.test(id) || c?.Id !== id || c.Image !== this.plan.imageId || !match(c.Config?.Labels, labels(this.plan, role)))
+            throw fail();
+        return c;
+    }
+    async until(test, milliseconds = 30000) {
+        const end = Date.now() + milliseconds;
+        do {
+            if (await test())
+                return;
+            await new Promise(resolve => setTimeout(resolve, 150));
+        } while (Date.now() < end);
+        throw fail();
+    }
+    async run() {
+        const p = this.plan, planSha256 = sha((0, entitybox_recovery_store_1.entityboxCanonical)(p)), base = { capacityId: p.capacityId, desktopId: p.desktopId, runtimeId: p.runtimeId }, volumes = (0, entitybox_application_boundary_1.entityboxApplicationVolumes)(base);
+        // The reservation precedes every external operation, including discovery.
+        publish(this.directory, 'desktop-' + p.desktopId + '.json', p);
+        const file = (suffix) => 'capacity-' + p.capacityId + '-' + suffix + '.json';
+        const names = { init: 'entitybox-capacity-init-' + p.capacityId, display: 'entitybox-capacity-display-' + p.capacityId, application: 'entitybox-capacity-application-' + p.capacityId };
+        const knownContainers = (await this.docker(['container', 'ls', '--all', '--format', '{{.Names}}'])).split(/\r?\n/);
+        const knownVolumes = (await this.docker(['volume', 'ls', '--format', '{{.Name}}'])).split(/\r?\n/);
+        if (Object.values(names).some(n => knownContainers.includes(n)) || Object.values(volumes).some(n => knownVolumes.includes(n)))
+            throw fail();
+        const argsFor = (value) => Object.entries(value).flatMap(([k, v]) => ['--label', k + '=' + v]);
+        const mount = (src, dst, readonly = false) => ['--mount', `type=volume,src=${src},dst=${dst},volume-nocopy${readonly ? ',readonly' : ''}`];
+        const applicationLabels = (0, entitybox_application_boundary_1.entityboxApplicationLabels)(base), displayLabels = { 'ai.add.entitybox.display.version': '1', 'ai.add.entitybox.display.capacity': p.capacityId, 'ai.add.entitybox.display.desktop': p.desktopId, 'ai.add.entitybox.display.runtime': p.runtimeId };
+        for (const [kind, name] of Object.entries(volumes)) {
+            const expected = { ...labels(p, 'volume-' + kind), ...(kind === 'socket' ? displayLabels : applicationLabels) };
+            if (await this.docker(['volume', 'create', '--driver', 'local', ...argsFor(expected), name]) !== name)
+                throw fail();
+            const rows = JSON.parse(await this.docker(['volume', 'inspect', name]));
+            if (!Array.isArray(rows) || rows.length !== 1 || rows[0].Name !== name || rows[0].Driver !== 'local' || Object.keys(rows[0].Options ?? {}).length || !match(rows[0].Labels, expected))
+                throw fail();
+            publish(this.directory, file('volume-' + kind), { name, labels: expected });
+        }
+        const limits = ['--init', '--restart', 'no', '--ipc', 'private', '--memory', '1024m', '--memory-swap', '1024m', '--cpus', '1', '--pids-limit', '256', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--read-only'];
+        const temp = ['--tmpfs', '/tmp:rw,nosuid,nodev,size=128m,mode=1777', '--tmpfs', '/run:rw,nosuid,nodev,size=8m,mode=700,uid=10001,gid=10001'];
+        const create = async (role, extra, args, code) => {
+            const id = await this.docker(['create', '--name', names[role], ...argsFor({ ...labels(p, role), ...extra }), ...limits, ...args, '--entrypoint', 'node', p.imageId, '-e', code]);
+            const c = await this.inspect(id, role);
+            if (c.State?.Status !== 'created' || c.State.Running || c.State.Pid !== 0)
+                throw fail();
+            publish(this.directory, file(role), { id, name: names[role], imageId: p.imageId, labels: labels(p, role) });
+            return id;
+        };
+        const init = await create('init', {}, ['--network', 'none', '--user', '0:0', '--cap-add', 'CHOWN', '--cap-add', 'FOWNER', ...mount(volumes.socket, '/socket'), ...mount(volumes.profile, '/profile'), ...mount(volumes.work, '/work')], programs.entityboxCapacityInit);
+        await this.docker(['start', init]);
+        await this.until(async () => { const c = await this.inspect(init, 'init'); if (c.State.Running)
+            return false; if (c.State.Status !== 'exited' || c.State.Pid !== 0 || c.State.ExitCode !== 0)
+            throw fail(); return true; });
+        // Never use --force and never remove data. Only the proven stopped bootstrap
+        // helper created by this exact plan may be retired here.
+        await this.docker(['container', 'rm', init]);
+        const display = await create('display', displayLabels, ['--network', 'bridge', '--user', '10001:10001', ...temp, '--publish', '127.0.0.1::5900', ...mount(volumes.socket, '/tmp/.X11-unix')], programs.entityboxCapacityDisplay);
+        await this.docker(['start', display]);
+        await this.inspect(display, 'display');
+        await this.docker(['exec', '--interactive', '--user', '10001:10001', display, 'node', '-e', programs.entityboxCapacityPassword], this.password);
+        const application = await create('application', applicationLabels, ['--network', 'none', '--user', '10001:10001', ...temp, ...mount(volumes.socket, '/tmp/.X11-unix', true), ...mount(volumes.profile, '/home/entitybox'), ...mount(volumes.work, '/work')], programs.entityboxCapacityApplication);
+        // Xvfb must be listening before Chromium starts. The socket is exposed only
+        // to the new application, never a host desktop or an arbitrary bind mount.
+        await this.until(async () => { await this.inspect(display, 'display'); try {
+            return await this.docker(['exec', '--user', '10001:10001', '--env', 'DISPLAY=:1', display, 'xdpyinfo']) !== '';
+        }
+        catch {
+            return false;
+        } });
+        await this.docker(['start', application]);
+        await this.until(async () => { const a = await this.inspect(application, 'application'), d = await this.inspect(display, 'display'); if (!a.State.Running || !d.State.Running)
+            throw fail(); try {
+            return await this.docker(['exec', '--user', '10001:10001', display, 'node', '-e', programs.entityboxCapacityReady]) === 'ready';
+        }
+        catch {
+            return false;
+        } });
+        await this.docker(['container', 'pause', application]);
+        const a = await this.inspect(application, 'application'), d = await this.inspect(display, 'display');
+        const receipt = { version: 1, dockerContext: p.dockerContext, planSha256, vncPort: portOf(d), channels: ['screen'], applicationNetwork: 'none',
+            application: { ...base, containerId: application, imageId: p.imageId, startedAt: a.State.StartedAt }, display: { ...base, containerId: display, imageId: p.imageId, startedAt: d.State.StartedAt } };
+        await verifyEntityboxCapacityReceipt(p, receipt, this.docker);
+        publish(this.directory, file('ready'), receipt);
+        return Object.freeze({ ...receipt, application: Object.freeze(receipt.application), display: Object.freeze(receipt.display), channels: Object.freeze(receipt.channels) });
+    }
+}
+exports.EntityboxCapacityProvisioner = EntityboxCapacityProvisioner;
+async function verifyEntityboxCapacityReceipt(plan, r, docker, requirePaused = true) {
+    parsePlan(plan);
+    if (!r || r.version !== 1 || r.planSha256 !== sha((0, entitybox_recovery_store_1.entityboxCanonical)(plan)) || r.dockerContext !== plan.dockerContext || r.applicationNetwork !== 'none'
+        || JSON.stringify(r.channels) !== '["screen"]' || r.application?.containerId === r.display?.containerId)
+        throw fail();
+    const scope = { version: 1, runId: plan.capacityId, desktopId: plan.desktopId, runtimeId: plan.runtimeId };
+    for (const [role, b] of [['application', r.application], ['display', r.display]]) {
+        if (!b || b.capacityId !== plan.capacityId || b.desktopId !== plan.desktopId || b.runtimeId !== plan.runtimeId || b.imageId !== plan.imageId)
+            throw fail();
+        const rows = JSON.parse(await docker(['container', 'inspect', b.containerId]));
+        if (!Array.isArray(rows) || rows.length !== 1 || !match(rows[0]?.Config?.Labels, labels(plan, role)))
+            throw fail();
+        if (role === 'display' && (portOf(rows[0]) !== r.vncPort || rows[0].State?.Paused || rows[0].State?.Restarting || rows[0].HostConfig?.RestartPolicy?.Name !== 'no'))
+            throw fail();
+    }
+    const state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(r.application, scope, docker);
+    if (state === 'stopped' || requirePaused && state !== 'paused')
+        throw fail();
+    await (0, entitybox_display_binding_1.verifyEntityboxDisplay)(r.display, scope, docker);
+    return state;
+}
+/** Read-only reopening after a clean setup; never resumes, creates, repairs or
+ * deletes anything. Missing/ambiguous setup remains reserved for explicit
+ * recovery. A restarted container or changed published port is not adopted. */
+async function readEntityboxCapacity(directory, desktopId, runtimeId, docker) {
+    if (!uuid.test(desktopId) || !uuid.test(runtimeId) || !path.isAbsolute(directory) || directory.startsWith('\\\\'))
+        throw fail();
+    try {
+        if (fs.lstatSync(directory).isSymbolicLink())
+            throw fail();
+        const dir = fs.realpathSync(directory), p = parsePlan(readJson(path.join(dir, 'desktop-' + desktopId + '.json')));
+        if (p.desktopId !== desktopId || p.runtimeId !== runtimeId)
+            throw fail();
+        const r = readJson(path.join(dir, 'capacity-' + p.capacityId + '-ready.json'));
+        await verifyEntityboxCapacityReceipt(p, r, docker ?? nativeDocker(p.dockerContext));
+        return Object.freeze({ ...r, application: Object.freeze(r.application), display: Object.freeze(r.display), channels: Object.freeze(r.channels) });
+    }
+    catch {
+        throw fail();
+    }
+}
+/** A health observation is never execution, ownership, stop proof or permission
+ * to replace a computer. Every physical read is limited to this published
+ * receipt; unavailable includes missing evidence and inconclusive inspection.
+ * The existing task reader continues to require a paused application. */
+async function observeEntityboxCapacity(config, docker) {
+    if (config.enabled !== true)
+        return undefined;
+    try {
+        // Snapshot all input before the first await; late caller changes cannot
+        // redirect the remaining reads to another computer or Docker context.
+        const { directory, desktopId, runtimeId, dockerContext } = config;
+        if (!uuid.test(desktopId) || !uuid.test(runtimeId) || !path.isAbsolute(directory) || directory.startsWith('\\\\') || !/^[-a-zA-Z0-9_.]{1,80}$/.test(dockerContext))
+            throw fail();
+        const published = JSON.parse((0, entitybox_recovery_store_1.entityboxCanonical)(config.receipt));
+        if (fs.lstatSync(directory).isSymbolicLink())
+            throw fail();
+        const dir = fs.realpathSync(directory), plan = parsePlan(readJson(path.join(dir, 'desktop-' + desktopId + '.json')));
+        const receipt = readJson(path.join(dir, 'capacity-' + plan.capacityId + '-ready.json'));
+        if (plan.desktopId !== desktopId || plan.runtimeId !== runtimeId || plan.dockerContext !== dockerContext || published?.dockerContext !== dockerContext
+            || (0, entitybox_recovery_store_1.entityboxCanonical)(receipt) !== (0, entitybox_recovery_store_1.entityboxCanonical)(published))
+            throw fail();
+        // Structural validation precedes any command, including a custom fixture
+        // transport. No name lookup or ordinary desktop discovery is permitted.
+        if (Object.keys(receipt).sort().join(',') !== 'application,applicationNetwork,channels,display,dockerContext,planSha256,version,vncPort'
+            || !Number.isSafeInteger(receipt.vncPort) || receipt.vncPort < 1024 || receipt.vncPort > 65535)
+            throw fail();
+        for (const b of [receipt.application, receipt.display]) {
+            if (!b || Object.keys(b).sort().join(',') !== 'capacityId,containerId,desktopId,imageId,runtimeId,startedAt'
+                || b.capacityId !== plan.capacityId || b.desktopId !== desktopId || b.runtimeId !== runtimeId || b.imageId !== plan.imageId
+                || !/^[a-f0-9]{64}$/.test(b.containerId) || typeof b.startedAt !== 'string' || b.startedAt.length > 80 || !Number.isFinite(Date.parse(b.startedAt)))
+                throw fail();
+        }
+        const allowedContainers = new Set([receipt.application.containerId, receipt.display.containerId]);
+        const allowedVolumes = new Set(Object.values((0, entitybox_application_boundary_1.entityboxApplicationVolumes)(receipt.application)));
+        const deadline = perf_hooks_1.performance.now() + 20000;
+        const transport = docker ?? entityboxCapacityHealthDocker(dockerContext);
+        const read = async (args, input) => {
+            if (input !== undefined || perf_hooks_1.performance.now() >= deadline || args[1] !== 'inspect'
+                || !(args[0] === 'container' && args.length === 3 && allowedContainers.has(args[2])
+                    || args[0] === 'volume' && args.length >= 3 && args.length <= 5 && args.slice(2).every(v => allowedVolumes.has(v))))
+                throw fail();
+            const result = await transport([...args]);
+            if (perf_hooks_1.performance.now() >= deadline)
+                throw fail();
+            return result;
+        };
+        // Cache one complete observation: ownership, ports, labels and state must
+        // be assessed from the same container record, not different CLI responses.
+        const reads = new Map();
+        const snapshot = args => { const key = JSON.stringify(args); let value = reads.get(key); if (!value) {
+            value = read(args);
+            reads.set(key, value);
+        } return value; };
+        const state = await verifyEntityboxCapacityReceipt(plan, receipt, snapshot, false);
+        return Object.freeze({ state });
+    }
+    catch {
+        return Object.freeze({ state: 'unavailable' });
+    }
+}
+/** A deadline can cancel an inspect CLI because it has no mutation to join.
+ * Always await its actual exit. This transport is never used by provisioning,
+ * task execution or cleanup, whose mutation lifetimes retain their rules. */
+function entityboxCapacityHealthDocker(context) {
+    return args => new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('docker', ['--context', context, ...args], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '', size = 0, invalid = false;
+        const stop = () => { invalid = true; try {
+            child.kill();
+        }
+        catch { } };
+        const timer = setTimeout(stop, 5000);
+        timer.unref?.();
+        child.stdout.on('data', b => { size += b.length; if (size > 2 * 1024 * 1024)
+            stop();
+        else
+            output += b.toString(); });
+        child.stderr.resume();
+        child.once('error', () => { invalid = true; });
+        child.once('close', code => { clearTimeout(timer); if (code === 0 && !invalid)
+            resolve(output.trim());
+        else
+            reject(fail()); });
+    });
+}

package/dist/entitybox-capacity-publication.d.ts

@@ -0,0 +1,29 @@
+import { type EntityboxCapacityPlan, type EntityboxCapacityReceipt } from './entitybox-capacity-provisioner';
+import type { EntityboxCapacityAllocation, EntityboxCapacityRegistrationConfiguration, EntityboxCapacityRegistrationIO } from './entitybox-capacity-registration';
+interface Publication {
+    version: 1;
+    allocation: EntityboxCapacityAllocation;
+    plan: EntityboxCapacityPlan;
+    nonce: string;
+    password: string;
+}
+/** The original publication authority is encrypted under the existing pairing
+ * secret. It is not a public capacity receipt and is never an execution grant.
+ * No pairing token or plaintext VNC password is written into this directory. */
+export declare class EntityboxCapacityPublicationStore {
+    private readonly directory;
+    constructor(directory: string, create?: boolean);
+    private file;
+    private key;
+    private aad;
+    read(id: string, runtimeId: string, token: string): Publication;
+    write(value: Publication, token: string): void;
+}
+/** Complete only a physically finished setup. This never invokes a provisioner
+ * or mutates Docker. Concurrent fresh processes publish the SAME original
+ * nonce, plan, password and receipt through the existing idempotent SQL path.
+ * A missing ready receipt remains unresolved; it is not permission to recreate. */
+export declare function createEntityboxCapacityPublicationRecovery(config: EntityboxCapacityRegistrationConfiguration, io: EntityboxCapacityRegistrationIO): {
+    provision: () => Promise<Readonly<EntityboxCapacityReceipt>>;
+} | undefined;
+export {};

package/dist/entitybox-capacity-publication.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxCapacityPublicationStore = void 0;
+exports.createEntityboxCapacityPublicationRecovery = createEntityboxCapacityPublicationRecovery;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const entitybox_capacity_provisioner_1 = require("./entitybox-capacity-provisioner");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const uuid = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/, fail = () => new entitybox_execution_lease_1.EntityboxExecutionError('Computer setup publication could not be recovered');
+const sha = (s) => (0, crypto_1.createHash)('sha256').update(s).digest('hex');
+function validate(value) {
+    const a = value?.allocation, p = value?.plan;
+    if (!value || Object.keys(value).sort().join(',') !== 'allocation,nonce,password,plan,version' || value.version !== 1
+        || !a || Object.keys(a).sort().join(',') !== 'desktopId,id,runtimeId' || ![a.id, a.desktopId, a.runtimeId, value.nonce].every(v => typeof v === 'string' && uuid.test(v))
+        || !p || Object.keys(p).sort().join(',') !== 'capacityId,desktopId,dockerContext,imageId,programsSha256,runtimeId,version' || p.version !== 1 || !uuid.test(p.capacityId)
+        || p.runtimeId !== a.runtimeId || p.desktopId !== a.desktopId || !/^sha256:[a-f0-9]{64}$/.test(p.imageId) || !/^[-a-zA-Z0-9_.]{1,80}$/.test(p.dockerContext) || !/^[a-f0-9]{64}$/.test(p.programsSha256)
+        || typeof value.password !== 'string' || !/^[A-Za-z0-9_-]{8}$/.test(value.password))
+        throw fail();
+    return value;
+}
+/** The original publication authority is encrypted under the existing pairing
+ * secret. It is not a public capacity receipt and is never an execution grant.
+ * No pairing token or plaintext VNC password is written into this directory. */
+class EntityboxCapacityPublicationStore {
+    directory;
+    constructor(directory, create = false) {
+        if (!path.isAbsolute(directory) || directory.startsWith('\\\\'))
+            throw fail();
+        if (create)
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if (fs.lstatSync(directory).isSymbolicLink())
+            throw fail();
+        const root = fs.realpathSync(directory), target = path.join(root, 'publication-private');
+        if (create)
+            fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+        if (fs.lstatSync(target).isSymbolicLink() || !fs.lstatSync(target).isDirectory())
+            throw fail();
+        this.directory = fs.realpathSync(target);
+    }
+    file(id) { if (!uuid.test(id))
+        throw fail(); return path.join(this.directory, id + '.sealed'); }
+    key(token, runtimeId) { if (typeof token !== 'string' || !token || token.length > 16384 || !uuid.test(runtimeId))
+        throw fail(); return (0, crypto_1.createHmac)('sha256', token).update('entitybox-capacity-publication-v1\0' + runtimeId).digest(); }
+    aad(id, runtimeId) { return Buffer.from((0, entitybox_recovery_store_1.entityboxCanonical)({ version: 1, id, runtimeId })); }
+    read(id, runtimeId, token) {
+        try {
+            const file = this.file(id), stat = fs.lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384)
+                throw fail();
+            const envelope = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (!envelope || Object.keys(envelope).sort().join(',') !== 'body,iv,tag,version' || envelope.version !== 1)
+                throw fail();
+            const decode = (value) => { if (typeof value !== 'string' || !value)
+                throw fail(); const b = Buffer.from(value, 'base64'); if (b.toString('base64') !== value)
+                throw fail(); return b; };
+            const iv = decode(envelope.iv), tag = decode(envelope.tag), body = decode(envelope.body);
+            if (iv.length !== 12 || tag.length !== 16 || body.length > 8192)
+                throw fail();
+            const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', this.key(token, runtimeId), iv);
+            decipher.setAAD(this.aad(id, runtimeId));
+            decipher.setAuthTag(tag);
+            const value = validate(JSON.parse(Buffer.concat([decipher.update(body), decipher.final()]).toString('utf8')));
+            if (value.allocation.id !== id || value.allocation.runtimeId !== runtimeId)
+                throw fail();
+            return value;
+        }
+        catch {
+            throw fail();
+        }
+    }
+    write(value, token) {
+        validate(value);
+        const { id, runtimeId } = value.allocation, file = this.file(id), iv = (0, crypto_1.randomBytes)(12), cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', this.key(token, runtimeId), iv);
+        cipher.setAAD(this.aad(id, runtimeId));
+        const body = Buffer.concat([cipher.update((0, entitybox_recovery_store_1.entityboxCanonical)(value), 'utf8'), cipher.final()]);
+        const text = (0, entitybox_recovery_store_1.entityboxCanonical)({ version: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), body: body.toString('base64') }), pending = path.join(this.directory, 'pending-' + (0, crypto_1.randomUUID)() + '.sealed');
+        let fd;
+        try {
+            fd = fs.openSync(pending, 'wx', 0o600);
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+            try {
+                fs.linkSync(pending, file);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST' || (0, entitybox_recovery_store_1.entityboxCanonical)(this.read(id, runtimeId, token)) !== (0, entitybox_recovery_store_1.entityboxCanonical)(value))
+                    throw fail();
+            }
+            if (process.platform !== 'win32') {
+                const dir = fs.openSync(this.directory, 'r');
+                try {
+                    fs.fsyncSync(dir);
+                }
+                finally {
+                    fs.closeSync(dir);
+                }
+            }
+        }
+        catch {
+            throw fail();
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+            try {
+                fs.unlinkSync(pending);
+            }
+            catch { }
+        }
+    }
+}
+exports.EntityboxCapacityPublicationStore = EntityboxCapacityPublicationStore;
+/** Complete only a physically finished setup. This never invokes a provisioner
+ * or mutates Docker. Concurrent fresh processes publish the SAME original
+ * nonce, plan, password and receipt through the existing idempotent SQL path.
+ * A missing ready receipt remains unresolved; it is not permission to recreate. */
+function createEntityboxCapacityPublicationRecovery(config, io) {
+    if (config.enabled !== true || config.recoverPublication !== true)
+        return undefined;
+    const allocation = Object.freeze({ id: config.allocation?.id, runtimeId: config.allocation?.runtimeId, desktopId: config.allocation?.desktopId }), directory = config.directory, imageId = config.imageId, context = config.dockerContext ?? 'desktop-linux';
+    if (![allocation.id, allocation.runtimeId, allocation.desktopId].every(v => typeof v === 'string' && uuid.test(v)) || !/^sha256:[a-f0-9]{64}$/.test(imageId))
+        throw fail();
+    let flight;
+    async function run() {
+        const pairing = io.pairing();
+        if (!pairing || pairing.runtimeId !== allocation.runtimeId || !pairing.daemonToken)
+            throw fail();
+        const originalToken = pairing.daemonToken;
+        const token = () => { const p = io.pairing(); if (!p || p.runtimeId !== allocation.runtimeId || p.daemonToken !== originalToken)
+            throw fail(); return originalToken; };
+        const state = new EntityboxCapacityPublicationStore(directory).read(allocation.id, allocation.runtimeId, token());
+        if ((0, entitybox_recovery_store_1.entityboxCanonical)(state.allocation) !== (0, entitybox_recovery_store_1.entityboxCanonical)(allocation) || state.plan.imageId !== imageId || state.plan.dockerContext !== context)
+            throw fail();
+        const read = () => (io.read ?? entitybox_capacity_provisioner_1.readEntityboxCapacity)(directory, allocation.desktopId, allocation.runtimeId);
+        const receipt = await read();
+        token();
+        if (receipt.planSha256 !== sha((0, entitybox_recovery_store_1.entityboxCanonical)(state.plan)) || receipt.dockerContext !== context)
+            throw fail();
+        const validateReply = (r, phase) => {
+            if (!r || r.id !== allocation.id || r.runtimeId !== allocation.runtimeId || r.desktopId !== allocation.desktopId || r.phase !== phase || (0, entitybox_recovery_store_1.entityboxCanonical)(r.plan) !== (0, entitybox_recovery_store_1.entityboxCanonical)(state.plan)
+                || phase === 'ready' && (0, entitybox_recovery_store_1.entityboxCanonical)(r.receipt) !== (0, entitybox_recovery_store_1.entityboxCanonical)(receipt))
+                throw fail();
+        };
+        const claimed = await io.rpc('entitybox_native_capacity_claim', { p_token: token(), p_id: allocation.id, p_nonce: state.nonce, p_plan: state.plan });
+        token();
+        if (claimed?.phase === 'ready') {
+            validateReply(claimed, 'ready');
+            return receipt;
+        }
+        validateReply(claimed, 'provisioning');
+        const current = await read();
+        token();
+        if ((0, entitybox_recovery_store_1.entityboxCanonical)(current) !== (0, entitybox_recovery_store_1.entityboxCanonical)(receipt))
+            throw fail();
+        const published = await io.rpc('entitybox_native_capacity_publish', { p_token: token(), p_id: allocation.id, p_nonce: state.nonce, p_receipt: receipt, p_vnc_password: state.password });
+        token();
+        validateReply(published, 'ready');
+        return receipt;
+    }
+    return { provision: () => { if (!flight)
+            flight = run().catch(() => { throw fail(); }).finally(() => { flight = undefined; }); return flight; } };
+}