@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/generated-application/custom-surface.d.ts

@@ -0,0 +1,26 @@
+import type { DerivedRegistry } from '../../registry-derivation.js';
+import type { SurfaceSourceFile } from '../../surfaces/contract.js';
+import type { OwnershipManifest } from '../../surfaces/ownership.js';
+import { type CustomSurfaceReceipt } from '../../surfaces/render.js';
+import { type CustomSourceIdentity, type GeneratedEnvironmentCommandAdapters, type PreparedEnvironment } from './shared.js';
+export declare function executeCustomCapability(prepared: PreparedEnvironment, adapters: GeneratedEnvironmentCommandAdapters, harness: string, capability: Extract<DerivedRegistry['config']['surfaces']['harnesses'][number]['capabilities'][number], {
+    state: 'enforced' | 'instructed';
+}>, sources: readonly SurfaceSourceFile[]): Promise<{
+    receipt: CustomSurfaceReceipt;
+    sources: readonly CustomSourceIdentity[];
+    evidence?: Readonly<{
+        reference: string;
+        sha256: string;
+    }>;
+} | undefined>;
+export declare function projectExplicitNativeHooks(prepared: PreparedEnvironment, manifest: OwnershipManifest | undefined, adapters: GeneratedEnvironmentCommandAdapters, policyDeclaration: Readonly<{
+    path: string;
+    sha256: string;
+}>, harnesses: readonly string[]): Promise<{
+    projection: import("../../testing/hooks.js").NativeHookProjection;
+    source: {
+        path: string;
+        sha256: string;
+        identity: import("../../generated-environment/transaction.js").FileIdentity;
+    };
+} | undefined>;

package/dist/environment/generated-application/custom-surface.js

@@ -0,0 +1,289 @@
+import { chmod, lstat, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { authenticatedExecutionOutcome } from '../../environment-exec/execute.js';
+import { surfaceModelSha256 } from '../../surfaces/render.js';
+import { readAnchoredFile, readAnchoredBatches } from '../../generated-environment/transaction.js';
+import { snapshotExecutionStep, snapshotGeneratedJson, RefusalError, hasErrorCode } from '../contract.js';
+import { resolveExecutablePath, resolveGitExecutable } from '../executable.js';
+import { cockpitId } from '../identity.js';
+import { NATIVE_HOOK_COST_SCRIPT, projectNativeHooks } from '../../testing/hooks.js';
+import { exactKeys } from '../../exact-keys.js';
+import { HELPER_TIMEOUT_MS, MAX_EXECUTABLE_BYTES, MAX_GENERATED_BYTES, MAX_HELPER_FRAME_BYTES, MAX_SURFACE_FILE_BYTES, NATIVE_HOOK_COST_TIMEOUT_MS, SHA256, confined, ownRecord, sha256, } from './shared.js';
+// The worker runs in its own process and cannot import modules; `safe` mirrors safeSurfacePath in
+// surfaces/contract.ts, including its case-folded reserved segments.
+const CUSTOM_SURFACE_WORKER = String.raw `
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const path = require('node:path');
+const request = JSON.parse(process.argv[1]);
+const digest = value => crypto.createHash('sha256').update(value).digest('hex');
+const own = value => value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+const safe = value => typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) && !value.includes('\\') && !value.includes('\0') && value.split('/').every(part => part && part !== '.' && part !== '..' && !['.GIT','NODE_MODULES'].includes(part.normalize('NFC').toUpperCase()));
+(async () => {
+  const source = fs.readFileSync(process.argv[2]);
+  if (digest(source) !== request.sourceSha256) throw new RefusalError('module changed');
+  const imported = await import('data:text/javascript;base64,' + source.toString('base64'));
+  const fn = imported[request.export]; if (typeof fn !== 'function') throw new RefusalError('export');
+  const result = await fn(request.input);
+  if (!own(result) || Object.keys(result).sort().join(',') !== 'files,kind' || result.kind !== 'complete' || !Array.isArray(result.files) || result.files.length === 0 || result.files.length > 256) throw new RefusalError('result');
+  let total = 0; let spelling = false; const files = [];
+  for (const [index, file] of result.files.entries()) {
+    if (!own(file) || Object.keys(file).sort().join(',') !== 'bytes,path,scope,sha256' || !safe(file.path) || typeof file.bytes !== 'string' || Buffer.byteLength(file.bytes) > 65536 || digest(file.bytes) !== file.sha256 || !['always','scoped'].includes(file.scope)) throw new RefusalError('file');
+    spelling = spelling || file.path === request.spelling || file.bytes.includes(request.spelling);
+    total += Buffer.byteLength(file.bytes); if (total > 4194304) throw new RefusalError('limit');
+    const output = path.join(request.output, String(index)); fs.writeFileSync(output, file.bytes, { flag: 'wx', mode: 0o600 });
+    files.push({ path: file.path, sha256: file.sha256, scope: file.scope, output: String(index) });
+  }
+  if (!spelling) throw new RefusalError('spelling');
+  process.stdout.write(JSON.stringify({ version: 1, files }) + '\n');
+})().catch(() => { process.stdout.write(JSON.stringify({ version: 1, refusal: true }) + '\n'); });
+`;
+export async function executeCustomCapability(prepared, adapters, harness, capability, sources) {
+    let evidenceSource;
+    if (capability.state === 'enforced') {
+        const evidenceRead = await readAnchoredFile(prepared.root, capability.evidence.reference, MAX_SURFACE_FILE_BYTES, prepared.node, adapters);
+        if (evidenceRead.kind !== 'complete' || evidenceRead.sha256 !== capability.evidence.sha256)
+            return undefined;
+        evidenceSource = { harness, feature: capability.feature, path: capability.evidence.reference,
+            sha256: evidenceRead.sha256, identity: evidenceRead.identity, maxBytes: MAX_SURFACE_FILE_BYTES };
+    }
+    const moduleRead = await readAnchoredFile(prepared.root, capability.mechanism.module, MAX_GENERATED_BYTES, prepared.node, adapters);
+    if (moduleRead.kind !== 'complete')
+        return undefined;
+    const permissionFlag = process.allowedNodeEnvironmentFlags.has('--permission') ? '--permission'
+        : process.allowedNodeEnvironmentFlags.has('--experimental-permission') ? '--experimental-permission' : undefined;
+    if (!permissionFlag || !process.allowedNodeEnvironmentFlags.has('--allow-fs-read')
+        || !process.allowedNodeEnvironmentFlags.has('--allow-fs-write'))
+        return undefined;
+    let scratch;
+    let scratchIdentity;
+    try {
+        scratch = await realpath(await mkdtemp(join(tmpdir(), 'cockpit-custom-surface-')));
+        const scratchStatus = await lstat(scratch);
+        if (!scratchStatus.isDirectory() || scratchStatus.isSymbolicLink())
+            return undefined;
+        scratchIdentity = { dev: scratchStatus.dev, ino: scratchStatus.ino };
+        const input = snapshotGeneratedJson({ harness, feature: capability.feature, sources });
+        if (!input)
+            return undefined;
+        const absoluteModule = confined(prepared.root, capability.mechanism.module);
+        if (!absoluteModule || [scratch, absoluteModule].some(path => path.includes('*')))
+            return undefined;
+        const request = { export: capability.mechanism.export, input, output: scratch,
+            sourceSha256: moduleRead.sha256, spelling: capability.spelling };
+        const raw = JSON.stringify(request);
+        if (Buffer.byteLength(raw) > MAX_HELPER_FRAME_BYTES)
+            return undefined;
+        const step = snapshotExecutionStep({
+            id: `custom-surface-${harness}-${capability.feature}`, argv: [prepared.node.canonicalPath, permissionFlag,
+                '--allow-fs-read', absoluteModule, `--allow-fs-read=${scratch}`, `--allow-fs-write=${scratch}`,
+                '-e', CUSTOM_SURFACE_WORKER, raw, absoluteModule],
+            argv0: prepared.node.invocationPath, cwd: scratch, env: {}, timeoutMs: HELPER_TIMEOUT_MS,
+            spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(), stdoutLimitBytes: MAX_HELPER_FRAME_BYTES,
+            stderrLimitBytes: 16_384, paths: [prepared.root, scratch], ports: [], labels: { harness, feature: capability.feature }, expected: [],
+            consumedFiles: [
+                { path: prepared.node.canonicalPath, sha256: prepared.node.sha256, maxBytes: MAX_EXECUTABLE_BYTES, argvIndexes: [0], executable: true, executionMode: prepared.node.executionMode },
+                { path: absoluteModule, sha256: moduleRead.sha256, maxBytes: MAX_GENERATED_BYTES, argvIndexes: [3, 9], executable: false },
+            ], filesystemChecks: [{ path: scratch, expected: 'directory' }], compensation: [],
+        });
+        if (!step)
+            return undefined;
+        const outcome = authenticatedExecutionOutcome(await adapters.execute(step), step);
+        if (!outcome || outcome.kind !== 'complete' || outcome.stderr.byteLength !== 0)
+            return undefined;
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(outcome.stdout);
+        const record = ownRecord(JSON.parse(text));
+        if (!record || !exactKeys(record, ['version', 'files']) || record.version !== 1 || !Array.isArray(record.files))
+            return undefined;
+        const descriptors = [];
+        for (const [index, value] of record.files.entries()) {
+            const row = ownRecord(value);
+            if (!row || !exactKeys(row, ['path', 'sha256', 'scope', 'output']) || row.output !== String(index)
+                || typeof row.path !== 'string' || typeof row.sha256 !== 'string' || !SHA256.test(row.sha256)
+                || row.scope !== 'always' && row.scope !== 'scoped')
+                return undefined;
+            descriptors.push({ path: row.path, sha256: row.sha256, scope: row.scope, output: row.output });
+        }
+        const reads = await readAnchoredBatches(scratch, descriptors.map(row => ({
+            path: row.output, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-file',
+        })), prepared.node, adapters);
+        if (!reads || reads.kind !== 'complete' || reads.results.length !== descriptors.length)
+            return undefined;
+        const files = [];
+        for (const [index, row] of descriptors.entries()) {
+            const read = reads.results[index];
+            if (read.kind !== 'complete' || read.sha256 !== row.sha256
+                || read.identity.root.dev !== scratchIdentity.dev || read.identity.root.ino !== scratchIdentity.ino)
+                return undefined;
+            const bytes = new TextDecoder('utf-8', { fatal: true }).decode(read.bytes);
+            files.push({ path: row.path, bytes, sha256: row.sha256, scope: row.scope });
+        }
+        if (files.length === 0 || !files.some(file => file.path === capability.spelling || file.bytes.includes(capability.spelling)))
+            return undefined;
+        const resultSha256 = surfaceModelSha256(files);
+        if (!resultSha256)
+            return undefined;
+        return {
+            receipt: { harness, feature: capability.feature, state: capability.state, measuredOn: capability.measured_on,
+                module: capability.mechanism.module, export: capability.mechanism.export, sourceSha256: moduleRead.sha256,
+                resultSha256, files },
+            sources: [
+                { harness, feature: capability.feature, path: capability.mechanism.module,
+                    sha256: moduleRead.sha256, identity: moduleRead.identity, maxBytes: MAX_GENERATED_BYTES },
+                ...(evidenceSource ? [evidenceSource] : []),
+            ],
+            ...(capability.state === 'enforced' ? { evidence: { ...capability.evidence } } : {}),
+        };
+    }
+    catch { /* an unavailable authority is refused by the caller. */
+        return undefined;
+    }
+    finally {
+        if (scratch && scratchIdentity) {
+            try {
+                const current = await lstat(scratch);
+                if (current.isDirectory() && !current.isSymbolicLink()
+                    && current.dev === scratchIdentity.dev && current.ino === scratchIdentity.ino) {
+                    await rm(scratch, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+    }
+}
+export async function projectExplicitNativeHooks(prepared, manifest, adapters, policyDeclaration, harnesses) {
+    if (!manifest)
+        return undefined;
+    const policyRead = await readAnchoredFile(prepared.root, policyDeclaration.path, MAX_SURFACE_FILE_BYTES, prepared.node, adapters);
+    if (policyRead.kind !== 'complete' || policyRead.sha256 !== policyDeclaration.sha256)
+        return undefined;
+    let policyBytes;
+    try {
+        policyBytes = new TextDecoder('utf-8', { fatal: true }).decode(policyRead.bytes);
+    }
+    catch { /* undecodable bytes are malformed input the caller refuses. */
+        return undefined;
+    }
+    const policy = {
+        manifest,
+        authority: { root: prepared.root, cockpitId: prepared.cockpitId, configPath: prepared.configPath },
+        declarations: [],
+        path: policyDeclaration.path,
+        exists: true,
+        bytes: policyBytes,
+    };
+    const source = { path: policyDeclaration.path, sha256: policyRead.sha256, identity: policyRead.identity };
+    const git = await resolveGitExecutable(process.env);
+    if (git.state !== 'available')
+        return {
+            projection: { kind: 'refusal', reason: git.reason },
+            source,
+        };
+    const revisionStep = snapshotExecutionStep({
+        id: 'native-hook-revisions',
+        argv: [git.value.invocationPath, 'rev-list', '--max-count=2', 'HEAD'],
+        argv0: git.value.invocationPath,
+        cwd: prepared.root,
+        env: {},
+        timeoutMs: HELPER_TIMEOUT_MS,
+        spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(),
+        stdoutLimitBytes: 256,
+        stderrLimitBytes: 4_096,
+        paths: [prepared.root],
+        ports: [],
+        labels: { action: 'native-hook-revisions' },
+        expected: [],
+        consumedFiles: [{ path: git.value.canonicalPath, sha256: git.value.sha256, maxBytes: MAX_EXECUTABLE_BYTES,
+                argvIndexes: [0], executable: true, executionMode: git.value.executionMode }],
+        filesystemChecks: [{ path: prepared.root, expected: 'directory' }],
+        compensation: [],
+    });
+    if (!revisionStep)
+        return undefined;
+    const revisionOutcome = authenticatedExecutionOutcome(await adapters.execute(revisionStep), revisionStep);
+    if (!revisionOutcome || revisionOutcome.kind !== 'complete' || revisionOutcome.stderr.byteLength !== 0)
+        return undefined;
+    let revisions;
+    try {
+        revisions = new TextDecoder('utf-8', { fatal: true }).decode(revisionOutcome.stdout).trim().split('\n');
+    }
+    catch { /* undecodable bytes are malformed input the caller refuses. */
+        return undefined;
+    }
+    if (revisions.length !== 2 || revisions[0] === revisions[1]
+        || revisions.some(value => !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value) || !/[1-9a-f]/.test(value)))
+        return undefined;
+    let scratch;
+    let scratchIdentity;
+    try {
+        scratch = await realpath(await mkdtemp(join(tmpdir(), 'cockpit-native-hook-cost-')));
+        const status = await lstat(scratch);
+        if (!status.isDirectory() || status.isSymbolicLink())
+            return undefined;
+        scratchIdentity = { dev: status.dev, ino: status.ino };
+        const shell = await resolveExecutablePath('/bin/sh');
+        if (shell.state !== 'available')
+            return undefined;
+        const projection = await projectNativeHooks({
+            cockpitId: prepared.cockpitId,
+            harnesses,
+            install: 'explicit-native',
+            budget: {
+                policy,
+                prepareMeasurement: async (entry) => {
+                    const path = join(scratch, 'pre-push');
+                    await writeFile(path, entry.bytes, { flag: 'wx', mode: 0o700 });
+                    await chmod(path, 0o700);
+                    const step = snapshotExecutionStep({
+                        id: 'native-hook-cost',
+                        argv: [shell.value.canonicalPath, '-c', NATIVE_HOOK_COST_SCRIPT, 'native-hook-cost', path, revisions[0], revisions[1]],
+                        argv0: shell.value.canonicalPath,
+                        cwd: prepared.root,
+                        env: { PATH: dirname(git.value.canonicalPath) },
+                        timeoutMs: NATIVE_HOOK_COST_TIMEOUT_MS,
+                        spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(),
+                        stdoutLimitBytes: 4_096,
+                        stderrLimitBytes: 4_096,
+                        paths: [prepared.root, scratch],
+                        ports: [],
+                        labels: { action: 'native-hook-cost' },
+                        expected: [],
+                        consumedFiles: [
+                            { path: shell.value.canonicalPath, sha256: shell.value.sha256, maxBytes: MAX_EXECUTABLE_BYTES,
+                                argvIndexes: [0], executable: true, executionMode: shell.value.executionMode },
+                            { path, sha256: entry.sha256, maxBytes: Buffer.byteLength(entry.bytes), argvIndexes: [4], executable: false },
+                        ],
+                        filesystemChecks: [{ path: prepared.root, expected: 'directory' }, { path: scratch, expected: 'directory' }],
+                        compensation: [],
+                    });
+                    if (!step)
+                        throw new RefusalError('native hook cost measurement could not be admitted');
+                    return step;
+                },
+            },
+        });
+        return {
+            projection,
+            source,
+        };
+    }
+    finally {
+        if (scratch && scratchIdentity) {
+            try {
+                const current = await lstat(scratch);
+                if (current.isDirectory() && !current.isSymbolicLink()
+                    && current.dev === scratchIdentity.dev && current.ino === scratchIdentity.ino) {
+                    await rm(scratch, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+    }
+}

package/dist/environment/generated-application/prepare.d.ts

@@ -0,0 +1,29 @@
+import { type OwnershipManifest } from '../../surfaces/ownership.js';
+import { type FileIdentity } from '../../generated-environment/transaction.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentCommandInput, type GeneratedEnvironmentSyncInput, type PreparedEnvironment, type RefusalOutcome } from './shared.js';
+export declare function commandInput(input: unknown): GeneratedEnvironmentCommandInput | undefined;
+export declare function syncCommandInput(input: unknown): GeneratedEnvironmentSyncInput | undefined;
+export declare function safePath(root: string, path: string, allowMissing: boolean): Promise<string | undefined>;
+export type OwnershipState = {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'invalid';
+} | {
+    readonly kind: 'unsupported';
+    readonly format: string;
+} | {
+    readonly kind: 'complete';
+    readonly manifest: OwnershipManifest;
+    readonly bytes: string;
+    readonly sha256: string;
+    readonly identity: FileIdentity;
+};
+export declare function readOwnership(prepared: PreparedEnvironment, adapters: GeneratedEnvironmentCommandAdapters): Promise<OwnershipState>;
+export declare function expectedOutputExists(prepared: PreparedEnvironment): Promise<boolean>;
+export declare function renamedStackRefusal(prepared: PreparedEnvironment): Promise<RefusalOutcome | undefined>;
+/** Why no single Compose service publishes the endpoint's port on loopback, or undefined when exactly one does. */
+export declare function browserEndpointUnpublished(endpoint: string, sources: readonly Readonly<{
+    reference: string;
+    source: string;
+}>[], bases: Readonly<Record<string, number>>): string | undefined;
+export declare function prepare(input: unknown, adapters: GeneratedEnvironmentCommandAdapters): Promise<PreparedEnvironment | RefusalOutcome>;

package/dist/environment/generated-application/prepare.js

@@ -0,0 +1,276 @@
+import { lstat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { isProxy } from 'node:util/types';
+import { parseDocument } from 'yaml';
+import { consumeWorkEnvironmentConfigProjection, loadCockpitConfig, projectWorkEnvironmentConfig } from '../../config/load.js';
+import { deriveRegistry } from '../../registry-derivation.js';
+import { SURFACE_TARGETS } from '../../surfaces/contract.js';
+import { parseOwnershipManifest } from '../../surfaces/ownership.js';
+import { nodeAuthority, readAnchoredFile, readAnchoredConfigSource } from '../../generated-environment/transaction.js';
+import { ENVIRONMENT_CODES, hasErrorCode } from '../contract.js';
+import { checkoutId, cockpitId, publicationCockpitId, stackId } from '../identity.js';
+import { composePublishedPorts, variableName } from '../compose-topology.js';
+import { COMPOSE_OWNERSHIP_FILE, renderComposeOwnership } from '../compose-ownership.js';
+import { earlierNameRefusalMessage, findStackUnderEarlierName } from '../lifecycle-stage.js';
+import { selectStateRoot } from '../state.js';
+import { observeGeneratedCheckoutIdentity } from '../setup-observation.js';
+import { exactKeys } from '../../exact-keys.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+import { COMPOSE_SOURCE_BYTES, MAX_OWNERSHIP_BYTES, OWNERSHIP_PATH, authenticateSiblingRoots, compareCodeUnits, confined, ownRecord, sha256, } from './shared.js';
+export function commandInput(input) {
+    try {
+        if (input === null || typeof input !== 'object' || Array.isArray(input) || isProxy(input))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        const keys = Reflect.ownKeys(descriptors);
+        if (keys.some((key) => typeof key !== 'string' || key !== 'configPath')
+            || !Object.hasOwn(descriptors, 'configPath') || !('value' in descriptors.configPath))
+            return undefined;
+        const configPath = descriptors.configPath.value;
+        if (typeof configPath !== 'string' || configPath.length === 0 || configPath.includes('\0'))
+            return undefined;
+        return { configPath };
+    }
+    catch {
+        // a guard over caller-supplied values; a throwing accessor or proxy trap is malformed input the caller refuses.
+        return undefined;
+    }
+}
+export function syncCommandInput(input) {
+    try {
+        if (input === null || typeof input !== 'object' || Array.isArray(input) || isProxy(input))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        const keys = Reflect.ownKeys(descriptors);
+        if (keys.some((key) => typeof key !== 'string' || key !== 'configPath' && key !== 'dryRun' && key !== 'bootstrapState')
+            || !Object.hasOwn(descriptors, 'configPath') || !('value' in descriptors.configPath))
+            return undefined;
+        const configPath = descriptors.configPath.value;
+        const dryRun = Object.hasOwn(descriptors, 'dryRun') && 'value' in descriptors.dryRun ? descriptors.dryRun.value : false;
+        if (typeof configPath !== 'string' || configPath.length === 0 || configPath.includes('\0') || typeof dryRun !== 'boolean')
+            return undefined;
+        const bootstrapState = Object.hasOwn(descriptors, 'bootstrapState') && 'value' in descriptors.bootstrapState
+            ? descriptors.bootstrapState.value : undefined;
+        if (bootstrapState !== undefined) {
+            const state = ownRecord(bootstrapState);
+            if (!state || !exactKeys(state, ['publication', 'address']))
+                return undefined;
+        }
+        return { configPath, dryRun, ...(bootstrapState === undefined ? {} : { bootstrapState }) };
+    }
+    catch {
+        // a guard over caller-supplied values; a throwing accessor or proxy trap is malformed input the caller refuses.
+        return undefined;
+    }
+}
+export async function safePath(root, path, allowMissing) {
+    const target = confined(root, path);
+    if (!target)
+        return undefined;
+    const parts = relative(root, target).split(sep);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        current = resolve(current, part);
+        try {
+            const entry = await lstat(current);
+            if (entry.isSymbolicLink() || index < parts.length - 1 && !entry.isDirectory()
+                || index === parts.length - 1 && !entry.isFile())
+                return undefined;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            if (!allowMissing && index === parts.length - 1)
+                return undefined;
+        }
+    }
+    return target;
+}
+export async function readOwnership(prepared, adapters) {
+    const read = await readAnchoredFile(prepared.root, OWNERSHIP_PATH, MAX_OWNERSHIP_BYTES, prepared.node, adapters);
+    if (read.kind === 'missing')
+        return { kind: 'missing' };
+    if (read.kind !== 'complete')
+        return { kind: 'invalid' };
+    try {
+        const bytes = new TextDecoder('utf-8', { fatal: true }).decode(read.bytes);
+        const parsed = parseOwnershipManifest(bytes, { root: prepared.root, cockpitId: prepared.cockpitId, configPath: prepared.configPath });
+        return parsed.kind === 'complete' ? { kind: 'complete', manifest: parsed.manifest, bytes, sha256: read.sha256, identity: read.identity } : parsed;
+    }
+    catch {
+        // invalid ownership bytes are reported as invalid.
+        return { kind: 'invalid' };
+    }
+}
+export async function expectedOutputExists(prepared) {
+    for (const file of prepared.owned) {
+        if (await safePath(prepared.root, file.path, false))
+            return true;
+    }
+    return false;
+}
+// A ledger recorded under another name means `cockpit.name` was renamed. Publishing under the new
+// name is safe for the files, but a stack still recorded under the old one would be left where
+// down cannot reach it, so the rename waits until that stack is down.
+export async function renamedStackRefusal(prepared) {
+    const checkout = prepared.runtimeCheckout;
+    if (!checkout || process.platform !== 'darwin' && process.platform !== 'linux')
+        return undefined;
+    const namespace = await selectStateRoot({ platform: process.platform, home: process.env.HOME,
+        xdgStateHome: process.env.XDG_STATE_HOME,
+        checkoutRoots: [checkout.currentCheckoutPath, checkout.mainCheckoutPath], cockpitId: checkout.cockpitId });
+    if (namespace.kind !== 'complete')
+        return refuse(ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE, `cannot tell whether a stack started before cockpit.name was renamed is still recorded: ${'message' in namespace ? namespace.message : 'the state root is missing'}; nothing was written`, prepared.configPath);
+    const earlier = await findStackUnderEarlierName({ namespace: namespace.value, cockpitId: checkout.cockpitId, checkoutId: checkout.checkoutId });
+    if (earlier.kind === 'refusal')
+        return refuse(earlier.code, `${earlier.message}; nothing was written`, earlier.target);
+    return earlier.name === undefined ? undefined
+        : refuse(ENVIRONMENT_CODES.STACK_RECORDED_UNDER_EARLIER_NAME, earlierNameRefusalMessage(prepared.configPath, earlier.name), prepared.configPath);
+}
+const LOOPBACK_HOST_IPS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+/** Why no single Compose service publishes the endpoint's port on loopback, or undefined when exactly one does. */
+export function browserEndpointUnpublished(endpoint, sources, bases) {
+    const port = Number(new URL(endpoint).port || 80);
+    const publishers = [];
+    for (const { reference, source } of sources) {
+        const document = parseDocument(source);
+        const services = document.errors.length === 0 ? document.toJS()?.services : undefined;
+        for (const [id, service] of Object.entries(services ?? {})) {
+            const ports = composePublishedPorts(service?.ports);
+            if (!ports)
+                return `${reference} service ${id} has a ports entry cockpit cannot read, so it cannot tell whether it publishes browser.endpoint`;
+            if (ports.some(published => {
+                if (published.hostIp === null || !LOOPBACK_HOST_IPS.has(published.hostIp) || published.published === null)
+                    return false;
+                const name = variableName(published.published);
+                return (name === undefined ? Number(published.published) : bases[name]) === port;
+            }))
+                publishers.push(`${reference}:${id}`);
+        }
+    }
+    return publishers.length === 1 ? undefined
+        : publishers.length === 0 ? `browser.endpoint port ${port} is not published on loopback by any service in environment.compose_files`
+            : `browser.endpoint port ${port} is published on loopback by more than one service (${publishers.join(', ')})`;
+}
+export async function prepare(input, adapters) {
+    const request = commandInput(input);
+    if (!request)
+        return refuse('GENERATED_INPUT_INVALID', 'generated environment command input is invalid', 'generated-environment');
+    const loaded = await loadCockpitConfig(request.configPath);
+    if (loaded.kind !== 'complete')
+        return {
+            kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+            diagnostics: [...loaded.diagnostics],
+        };
+    const workProjection = projectWorkEnvironmentConfig(loaded.result);
+    const workEnvironment = workProjection && consumeWorkEnvironmentConfigProjection(workProjection);
+    if (!workEnvironment || workEnvironment.source.path !== loaded.result.source.path
+        || workEnvironment.source.sha256 !== loaded.result.source.sha256) {
+        return refuse('GENERATED_RENDER_UNAUTHENTICATED', 'the work environment configuration could not be consumed', loaded.result.source.path);
+    }
+    const derived = deriveRegistry(loaded.result.config);
+    if (derived.kind !== 'complete')
+        return refuse(derived.code, derived.message, loaded.result.source.path);
+    const config = derived.result.config;
+    const root = dirname(loaded.result.source.path);
+    const authenticatedSiblings = await authenticateSiblingRoots(root, derived.result.config, loaded.result.source.path);
+    if (authenticatedSiblings.kind === 'refusal')
+        return refuse(authenticatedSiblings.code ?? 'GENERATED_SIBLING_ROOT_INVALID', authenticatedSiblings.reason, authenticatedSiblings.target ?? 'sibling', authenticatedSiblings.fix);
+    const siblingRoots = authenticatedSiblings.roots;
+    const runtimeCheckout = workEnvironment.browser || config.environment.compose_files.length > 0
+        ? await observeGeneratedCheckoutIdentity({ source: loaded.result.source, cockpitName: config.cockpit.name,
+            env: process.env }) : undefined;
+    if (runtimeCheckout?.state === 'failed')
+        return refuse('GENERATED_INPUT_INVALID', `generated checkout identity is unavailable: ${runtimeCheckout.reason}`, loaded.result.source.path, 'restore the configuration checkout and Git installation, then run npx --no cockpit sync --config <your cockpit.toml>');
+    const currentCockpit = runtimeCheckout?.cockpitId ?? cockpitId({ name: config.cockpit.name, mainCheckoutPath: root });
+    const publishedCockpit = publicationCockpitId({ name: config.cockpit.name });
+    const currentCheckout = runtimeCheckout?.checkoutId ?? checkoutId({ checkoutPath: root });
+    const currentStack = stackId({ cockpitId: currentCockpit, checkoutId: currentCheckout, variant: { kind: 'shared' } });
+    // Derived from the runtime declarations, not the file bytes, so rewording a purpose or a guard
+    // keeps the running stack's identity.
+    const generation = sha256(`generated-environment\0${loaded.result.runtimeSha256}`);
+    const node = await nodeAuthority();
+    if (!node)
+        return refuse('GENERATED_EXECUTABLE_UNAVAILABLE', 'the current Node executable could not be authenticated', process.execPath);
+    let composeOwnership;
+    const composeSources = [];
+    const sources = [];
+    if (config.environment.compose_files.length > 0) {
+        for (const reference of config.environment.compose_files) {
+            const read = await readAnchoredFile(root, reference, COMPOSE_SOURCE_BYTES, node, adapters);
+            if (read.kind !== 'complete')
+                return refuse('GENERATED_PATH_UNSAFE', 'a declared Compose file is missing, unreadable, or crosses a symbolic-link boundary', reference);
+            sources.push({ reference, source: read.bytes.toString('utf8') });
+            composeSources.push({ path: reference, sha256: read.sha256, identity: read.identity });
+        }
+        const ownership = renderComposeOwnership({ sources, stackId: currentStack, cockpitId: currentCockpit,
+            configSha256: loaded.result.runtimeSha256, resettableVolumes: config.environment.resettable_volumes });
+        if (ownership.kind !== 'complete')
+            return refuse('GENERATED_DECLARATION_INVALID', `the ownership override cannot be rendered from environment.compose_files: ${ownership.reason}`, ownership.target);
+        composeOwnership = { path: COMPOSE_OWNERSHIP_FILE, bytes: ownership.bytes, sha256: sha256(ownership.bytes) };
+    }
+    // A browser endpoint is a server the project's own Compose files run, so it must be reachable
+    // only from this machine, by exactly the service that publishes its port.
+    const endpoint = workEnvironment.browser?.endpoint;
+    const unpublished = endpoint === undefined ? undefined : browserEndpointUnpublished(endpoint, sources, config.ports.bases);
+    if (unpublished)
+        return refuse('GENERATED_BROWSER_ENDPOINT_UNPUBLISHED', unpublished, 'browser', 'publish the endpoint port from exactly one service in environment.compose_files as "127.0.0.1:${VAR}:<container port>" with VAR under [ports.bases] set to the endpoint port, or remove browser.endpoint to drive a local browser, then run npx --no cockpit sync --config <your cockpit.toml>');
+    const generated = composeOwnership ? [composeOwnership] : [];
+    // The anchored read of the configuration file pins the publication root's identity for the whole sync.
+    const sourcePath = relative(root, loaded.result.source.path);
+    const sourceTarget = await safePath(root, sourcePath, false);
+    if (!sourceTarget)
+        return refuse('GENERATED_CONFIG_SOURCE_UNAVAILABLE', 'the cockpit configuration file is missing or crosses a symbolic-link boundary', sourcePath);
+    const source = await readAnchoredConfigSource(root, sourcePath, node, adapters);
+    if (!source) {
+        return refuse('GENERATED_CONFIG_SOURCE_UNAVAILABLE', 'the cockpit configuration file is unreadable', sourcePath);
+    }
+    const owned = [...generated].sort((left, right) => compareCodeUnits(left.path, right.path));
+    if (new Set(owned.map(({ path }) => path)).size !== owned.length
+        || owned.some(({ path }) => path === OWNERSHIP_PATH)
+        || owned.some(({ path }) => [loaded.result.source.path, sourceTarget].includes(resolve(root, path)))) {
+        return refuse('GENERATED_PATH_DUPLICATE', 'generated ownership contains a duplicate or input path', 'generated-environment');
+    }
+    for (const file of owned) {
+        if (!await safePath(root, file.path, true)) {
+            return refuse('GENERATED_PATH_UNSAFE', 'generated destination crosses an existing symbolic-link or non-directory boundary', file.path);
+        }
+    }
+    const producedAt = (adapters.now ?? (() => new Date().toISOString()))();
+    const now = producedAt.slice(0, 10);
+    return {
+        root,
+        cockpitId: publishedCockpit,
+        stackId: currentStack,
+        ...(runtimeCheckout ? { runtimeCheckout } : {}),
+        configPath: loaded.result.source.path,
+        sourceSha256: loaded.result.source.sha256,
+        runtimeSha256: loaded.result.runtimeSha256,
+        configSource: { path: sourcePath, sha256: source.sha256 },
+        configSourceIdentity: source.identity,
+        generation,
+        generated,
+        owned,
+        surfaces: [],
+        compactSurfacePaths: new Set(),
+        configuredHarnesses: [...SURFACE_TARGETS],
+        activeSurfaceOverrides: [],
+        changedOverrideOriginals: [],
+        composeSources,
+        guideSources: { requests: [], observations: [], missing: [] },
+        openCodeGrantRoots: [],
+        sourceEvidence: [],
+        sourceRoots: [],
+        customSources: [],
+        adoptedSources: [],
+        surfaceAssets: [],
+        warnings: [],
+        unapprovedMcpServers: [],
+        registry: derived.result,
+        siblingRoots,
+        workEnvironment,
+        node,
+        now,
+        producedAt,
+    };
+}

package/dist/environment/generated-application/publication.d.ts

@@ -0,0 +1,33 @@
+import { type GeneratedPathClassificationResult, type OwnershipManifest, type SurfaceDiagnostic, type SurfacePriorOwnedEntry } from '../../surfaces/ownership.js';
+import { type SurfaceObservedEntry, type SurfaceChangePlanResult } from '../../surfaces/sync.js';
+import { type AnchoredEntry, type AnchoredBatchReadResult, type PublicationPlan } from '../../generated-environment/transaction.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentSyncInput, type PreparedEnvironment, type RefusalOutcome } from './shared.js';
+import { type OwnershipState } from './prepare.js';
+import { type UnfinishedInit } from './bootstrap-skill.js';
+export declare function inputSourcesCurrent(prepared: PreparedEnvironment, adapters: GeneratedEnvironmentCommandAdapters, deadline?: number): Promise<boolean>;
+export declare function ownedInputOverlap(prepared: PreparedEnvironment, prior: readonly Readonly<{
+    path: string;
+}>[]): Promise<Readonly<{
+    kind: 'complete';
+    path?: string;
+}> | Readonly<{
+    kind: 'invalid';
+}>>;
+export declare function observeSurfaceState(prepared: PreparedEnvironment, prior: readonly SurfacePriorOwnedEntry[], adapters: GeneratedEnvironmentCommandAdapters): Promise<{
+    observed: readonly SurfaceObservedEntry[];
+    raw: ReadonlyMap<string, AnchoredEntry>;
+    opaque: ReadonlySet<string>;
+} | undefined>;
+export declare function classifyOwnedState(prepared: PreparedEnvironment, manifest: OwnershipManifest | undefined, raw: ReadonlyMap<string, AnchoredBatchReadResult>): Promise<GeneratedPathClassificationResult>;
+export declare function planObservedSurfaces(prepared: PreparedEnvironment, priorOwned: readonly SurfacePriorOwnedEntry[], state: NonNullable<Awaited<ReturnType<typeof observeSurfaceState>>>): SurfaceChangePlanResult;
+/** A hand edit to a merged adopted file belongs in its adopted copy; say so where the conflict is reported. */
+export declare function surfacePlanRefusal(prepared: PreparedEnvironment, diagnostic: SurfaceDiagnostic, unfinishedInit?: UnfinishedInit): RefusalOutcome;
+export declare function preparePublication(input: GeneratedEnvironmentSyncInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>, seed?: PreparedEnvironment, knownOwnership?: OwnershipState): Promise<RefusalOutcome | Readonly<{
+    prepared: PreparedEnvironment;
+    ownership: OwnershipState;
+    plan: PublicationPlan;
+}> | Readonly<{
+    prepared: PreparedEnvironment;
+    ownership: OwnershipState;
+    refusal: RefusalOutcome;
+}>>;