@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/templates.js

@@ -0,0 +1,685 @@
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, linkSync, lstatSync, openSync, readSync, realpathSync, unlinkSync, writeSync, } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { EnvironmentFile, Sibling } from '../schema.js';
+import { ENVIRONMENT_CODES, OBSERVATION_REASON_BYTE_LIMIT, isCanonicalTimestamp, snapshotEnvironmentObservation, snapshotJson, RefusalError, hasErrorCode } from './contract.js';
+const OWNER = 'environment-template-seeding';
+export const observationDeclarations = Object.freeze([
+    { id: 'environment-key-freshness', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.ENVIRONMENT_KEYS_STALE, isIssued: isTemplateObservation, issuedAt: observationIssuedAt },
+    { id: 'secret-file-presence', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND, isIssued: isTemplateObservation, issuedAt: observationIssuedAt },
+    { id: 'sibling-presence', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.SIBLING_MISSING, isIssued: isTemplateObservation, issuedAt: observationIssuedAt },
+]);
+const issuedObservations = new WeakMap();
+function issueObservation(value) {
+    const snapshot = snapshotEnvironmentObservation(value);
+    if (!snapshot || snapshot.owner !== OWNER)
+        throw new RefusalError('template observation is malformed');
+    issuedObservations.set(snapshot, Date.now());
+    return snapshot;
+}
+function isTemplateObservation(value) {
+    return value !== null && typeof value === 'object' && issuedObservations.has(value);
+}
+function observationIssuedAt(value) {
+    return value !== null && typeof value === 'object' ? issuedObservations.get(value) : undefined;
+}
+export async function observeSiblingPresence(input) {
+    const snapshot = snapshotJson(input);
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot))
+        throw new RefusalError('sibling presence input is malformed');
+    const owned = snapshot;
+    const sibling = Sibling.safeParse(owned.sibling);
+    if (typeof owned.stackId !== 'string' || !/^stack:[a-f0-9]{64}$/.test(owned.stackId)
+        || typeof owned.observedAt !== 'string' || !isCanonicalTimestamp(owned.observedAt)
+        || typeof owned.siblingRoot !== 'string' || !isAbsolute(owned.siblingRoot)
+        || normalize(owned.siblingRoot) !== owned.siblingRoot || !sibling.success)
+        throw new RefusalError('sibling presence input is malformed');
+    const path = resolve(owned.siblingRoot, sibling.data.dir);
+    const confined = relative(owned.siblingRoot, path);
+    if (confined === '..' || confined.startsWith(`..${sep}`) || isAbsolute(confined))
+        throw new RefusalError('sibling presence input is malformed');
+    let present = false;
+    try {
+        const status = await lstat(path);
+        present = status.isDirectory() && !status.isSymbolicLink();
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw new RefusalError('sibling presence could not be observed');
+    }
+    return issueObservation({ code: ENVIRONMENT_CODES.SIBLING_MISSING, owner: OWNER, stackId: owned.stackId, source: path,
+        observed: { state: 'available', value: present, observedAt: owned.observedAt }, expectation: { kind: 'equal', value: true },
+        applicability: { state: 'required', posture: 'environment' }, freshness: { state: 'current' }, remedy: 'restore the declared sibling checkout' });
+}
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function projectAssignment(leftHandSide) {
+    let candidate = leftHandSide.trim();
+    if (candidate.startsWith('export '))
+        candidate = candidate.slice('export '.length).trim();
+    return ENVIRONMENT_KEY.test(candidate) ? candidate : null;
+}
+async function projectKeys(root, path, maxBytes) {
+    const keys = new Set();
+    let bytesRead = 0;
+    let line = 1;
+    let leftHandSide = '';
+    let assignment = false;
+    let ignoredLine = false;
+    function finishLine() {
+        const candidate = leftHandSide.endsWith('\r') ? leftHandSide.slice(0, -1) : leftHandSide;
+        const trimmed = candidate.trim();
+        if (!assignment && !ignoredLine && trimmed !== '' && !trimmed.startsWith('#')) {
+            return { kind: 'malformed', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_MALFORMED, line };
+        }
+        if (assignment) {
+            const key = projectAssignment(candidate);
+            if (key === null || keys.has(key)) {
+                return { kind: 'malformed', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_MALFORMED, line };
+            }
+            keys.add(key);
+        }
+        line += 1;
+        leftHandSide = '';
+        assignment = false;
+        ignoredLine = false;
+        return undefined;
+    }
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            kind: 'unreadable',
+            code: code === 'ENOENT'
+                ? ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND
+                : ENVIRONMENT_CODES.ENVIRONMENT_FILE_UNREADABLE,
+        };
+    }
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile())
+            return { kind: 'unreadable', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_UNREADABLE };
+        if (opened.size > BigInt(maxBytes)) {
+            return { kind: 'unreadable', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_TOO_LARGE };
+        }
+        const canonicalPath = await realpath(path);
+        const named = await lstat(path, { bigint: true });
+        if (named.isSymbolicLink() ||
+            named.dev !== opened.dev ||
+            named.ino !== opened.ino ||
+            !isContained(root, canonicalPath)) {
+            return { kind: 'unreadable', code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT };
+        }
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        while (true) {
+            const { bytesRead: count } = await handle.read(buffer, 0, buffer.byteLength, null);
+            if (count === 0)
+                break;
+            bytesRead += count;
+            if (bytesRead > maxBytes) {
+                return { kind: 'unreadable', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_TOO_LARGE };
+            }
+            for (let index = 0; index < count; index += 1) {
+                const byte = buffer[index];
+                if (byte === 0x0a) {
+                    const failure = finishLine();
+                    if (failure)
+                        return failure;
+                }
+                else if (!assignment && !ignoredLine && byte === 0x3d) {
+                    if (leftHandSide.trim().startsWith('#'))
+                        ignoredLine = true;
+                    else
+                        assignment = true;
+                }
+                else if (!assignment && !ignoredLine) {
+                    leftHandSide += String.fromCharCode(byte);
+                }
+            }
+        }
+    }
+    catch (error) {
+        // The unreadable result carries a code, not a cause, because read errors echo environment-file paths.
+        return { kind: 'unreadable', code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_UNREADABLE };
+    }
+    finally {
+        await handle.close();
+    }
+    if (leftHandSide !== '' || assignment || ignoredLine) {
+        const failure = finishLine();
+        if (failure)
+            return failure;
+    }
+    return { kind: 'keys', keys: [...keys].sort() };
+}
+export async function inspectEnvironmentKeys(input) {
+    const maxBytes = input.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        return {
+            kind: 'unreadable',
+            file: 'template',
+            path: input.templatePath,
+            code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_TOO_LARGE,
+        };
+    }
+    let canonicalRoot;
+    try {
+        const root = await lstat(input.siblingRoot, { bigint: true });
+        if (root.isSymbolicLink() || !root.isDirectory())
+            throw new RefusalError('invalid root');
+        canonicalRoot = await realpath(input.siblingRoot);
+    }
+    catch {
+        // The unreadable result carries the template-path code, not a cause.
+        return {
+            kind: 'unreadable',
+            file: 'template',
+            path: input.templatePath,
+            code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+        };
+    }
+    const template = await projectKeys(canonicalRoot, input.templatePath, maxBytes);
+    if (template.kind !== 'keys') {
+        return template.kind === 'malformed'
+            ? {
+                kind: 'malformed',
+                file: 'template',
+                path: input.templatePath,
+                line: template.line,
+                code: template.code,
+            }
+            : { kind: 'unreadable', file: 'template', path: input.templatePath, code: template.code };
+    }
+    const instance = await projectKeys(canonicalRoot, input.instancePath, maxBytes);
+    if (instance.kind === 'unreadable' && instance.code === ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND) {
+        return {
+            kind: 'absent',
+            templatePath: input.templatePath,
+            instancePath: input.instancePath,
+            requiredKeys: template.keys,
+            presentKeys: [],
+            missingKeys: template.keys,
+            unexpectedKeys: [],
+        };
+    }
+    if (instance.kind !== 'keys') {
+        return instance.kind === 'malformed'
+            ? {
+                kind: 'malformed',
+                file: 'instance',
+                path: input.instancePath,
+                line: instance.line,
+                code: instance.code,
+            }
+            : { kind: 'unreadable', file: 'instance', path: input.instancePath, code: instance.code };
+    }
+    const present = new Set(instance.keys);
+    const required = new Set(template.keys);
+    const missingKeys = template.keys.filter((key) => !present.has(key));
+    const unexpectedKeys = instance.keys.filter((key) => !required.has(key));
+    return {
+        kind: missingKeys.length === 0 && unexpectedKeys.length === 0 ? 'fresh' : 'stale',
+        templatePath: input.templatePath,
+        instancePath: input.instancePath,
+        requiredKeys: template.keys,
+        presentKeys: instance.keys,
+        missingKeys,
+        unexpectedKeys,
+    };
+}
+export async function observeEnvironmentKeys(input) {
+    const snapshot = snapshotJson(input);
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot))
+        throw new RefusalError('environment-key observation input is malformed');
+    const owned = snapshot;
+    const declaration = EnvironmentFile.safeParse(owned.declaration);
+    if (!declaration.success || typeof owned.stackId !== 'string' || !/^stack:[a-f0-9]{64}$/.test(owned.stackId)
+        || typeof owned.observedAt !== 'string' || !isCanonicalTimestamp(owned.observedAt) || typeof owned.siblingRoot !== 'string') {
+        throw new RefusalError('environment-key observation input is malformed');
+    }
+    const inspection = await inspectEnvironmentKeys({
+        siblingRoot: owned.siblingRoot,
+        templatePath: resolve(owned.siblingRoot, declaration.data.template),
+        instancePath: resolve(owned.siblingRoot, declaration.data.instance),
+    });
+    const source = inspection.kind === 'unreadable' || inspection.kind === 'malformed' ? inspection.path : inspection.instancePath;
+    const presence = inspection.kind !== 'absent' && !(inspection.kind === 'unreadable' && inspection.file === 'instance');
+    const fresh = inspection.kind === 'fresh';
+    return [
+        issueObservation({
+            code: ENVIRONMENT_CODES.ENVIRONMENT_KEYS_STALE, owner: OWNER, stackId: owned.stackId, source,
+            observed: inspection.kind === 'unreadable' || inspection.kind === 'malformed'
+                ? { state: 'failed', reason: `${inspection.file} environment file could not be projected`, observedAt: owned.observedAt }
+                : { state: 'available', value: fresh, observedAt: owned.observedAt },
+            expectation: { kind: 'equal', value: true }, applicability: { state: 'required', posture: 'environment' }, freshness: { state: 'current' },
+            remedy: 'synchronize the instance key names with its tracked template',
+        }),
+        issueObservation({
+            code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND, owner: OWNER, stackId: owned.stackId, source,
+            observed: { state: 'available', value: presence, observedAt: owned.observedAt }, expectation: { kind: 'equal', value: true },
+            applicability: { state: 'required', posture: 'environment' }, freshness: { state: 'current' }, remedy: 'seed the missing environment instance from its tracked template',
+        }),
+    ];
+}
+/** Health admits one row per code; aggregate here so every declaration retains owner-issued evidence. */
+export async function observeTemplateHealth(input) {
+    const groups = new Map();
+    let environmentFileCount = 0;
+    const add = (observation) => {
+        const group = groups.get(observation.code) ?? [];
+        group.push(observation);
+        groups.set(observation.code, group);
+    };
+    for (const value of input.siblings) {
+        const sibling = Sibling.parse(value);
+        add(await observeSiblingPresence({ stackId: input.stackId, observedAt: input.observedAt,
+            siblingRoot: input.siblingRoot, sibling }));
+        for (const declaration of sibling.environment_files ?? []) {
+            environmentFileCount += 1;
+            const observations = await observeEnvironmentKeys({ stackId: input.stackId, observedAt: input.observedAt,
+                siblingRoot: resolve(input.siblingRoot, sibling.dir), declaration });
+            observations.forEach(add);
+        }
+    }
+    if (environmentFileCount === 0) {
+        add(issueObservation({
+            code: ENVIRONMENT_CODES.ENVIRONMENT_KEYS_STALE, owner: OWNER, stackId: input.stackId,
+            source: input.siblingRoot, observed: { state: 'available', value: true, observedAt: input.observedAt },
+            expectation: { kind: 'equal', value: true }, applicability: { state: 'required', posture: 'environment' },
+            freshness: { state: 'current' }, remedy: 'synchronize the instance key names with its tracked template',
+        }));
+        add(issueObservation({
+            code: ENVIRONMENT_CODES.ENVIRONMENT_FILE_NOT_FOUND, owner: OWNER, stackId: input.stackId,
+            source: input.siblingRoot, observed: { state: 'available', value: true, observedAt: input.observedAt },
+            expectation: { kind: 'equal', value: true }, applicability: { state: 'required', posture: 'environment' },
+            freshness: { state: 'current' }, remedy: 'seed the missing environment instance from its tracked template',
+        }));
+    }
+    return [...groups.values()].map(group => {
+        if (group.length === 1)
+            return group[0];
+        const failures = group.filter(row => row.observed.state !== 'available' || row.observed.value !== true);
+        const unreadable = failures.filter(row => row.observed.state !== 'available');
+        const bounded = (value) => Buffer.byteLength(value) <= OBSERVATION_REASON_BYTE_LIMIT ? value
+            : `${Buffer.from(value).subarray(0, OBSERVATION_REASON_BYTE_LIMIT - 3).toString('utf8').replace(/�$/, '')}...`;
+        return issueObservation({
+            ...group[0],
+            source: bounded((failures.length > 0 ? failures : group).map(row => row.source).join('; ')),
+            observed: unreadable.length > 0
+                ? { state: 'failed', reason: bounded(unreadable.map(row => `${row.source}: ${row.observed.state === 'available' ? '' : row.observed.reason}`).join('; ')), observedAt: input.observedAt }
+                : { state: 'available', value: failures.length === 0, observedAt: input.observedAt },
+        });
+    });
+}
+function identityOf(stat) {
+    return {
+        dev: stat.dev.toString(),
+        ino: stat.ino.toString(),
+        mode: stat.mode.toString(),
+        size: stat.size.toString(),
+        mtimeNs: stat.mtimeNs.toString(),
+        ctimeNs: stat.ctimeNs.toString(),
+    };
+}
+function identitiesMatch(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function sameNode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode;
+}
+function isContained(root, candidate) {
+    const path = relative(root, candidate);
+    return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
+}
+async function secureIdentity(path) {
+    const stat = await lstat(path, { bigint: true });
+    return {
+        identity: identityOf(stat),
+        directory: stat.isDirectory(),
+        file: stat.isFile(),
+        symbolicLink: stat.isSymbolicLink(),
+    };
+}
+async function hasSafeComponents(root, relativePath, includeLeaf) {
+    const parts = relativePath.split('/');
+    const limit = includeLeaf ? parts.length : parts.length - 1;
+    let current = root;
+    for (let index = 0; index < limit; index += 1) {
+        current = join(current, parts[index]);
+        try {
+            const component = await secureIdentity(current);
+            if (component.symbolicLink || (index < limit - 1 && !component.directory))
+                return false;
+            const canonical = await realpath(current);
+            if (!isContained(root, canonical))
+                return false;
+        }
+        catch {
+            // Any filesystem failure on a component means it is not safely contained; the caller refuses the path.
+            return false;
+        }
+    }
+    return true;
+}
+function refusal(code, path) {
+    return { kind: 'refusal', code, path };
+}
+export async function planEnvironmentSeed(input) {
+    if (input.environmentFile === undefined)
+        return { kind: 'none' };
+    const declaration = EnvironmentFile.safeParse(input.environmentFile);
+    if (!declaration.success)
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, input.siblingRoot);
+    let root;
+    let canonicalRoot;
+    try {
+        root = await secureIdentity(input.siblingRoot);
+        canonicalRoot = await realpath(input.siblingRoot);
+    }
+    catch {
+        // The refusal carries a code and path, not a cause.
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, input.siblingRoot);
+    }
+    if (root.symbolicLink || !root.directory) {
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, input.siblingRoot);
+    }
+    if (typeof process.getuid === 'function') {
+        const rootStat = await lstat(input.siblingRoot, { bigint: true });
+        if (rootStat.uid !== BigInt(process.getuid())) {
+            return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, input.siblingRoot);
+        }
+    }
+    const source = resolve(canonicalRoot, declaration.data.template);
+    const destination = resolve(canonicalRoot, declaration.data.instance);
+    if (!isContained(canonicalRoot, source) || !isContained(canonicalRoot, destination) || source === destination) {
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+    }
+    if (!(await hasSafeComponents(canonicalRoot, declaration.data.template, true))) {
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, source);
+    }
+    if (!(await hasSafeComponents(canonicalRoot, declaration.data.instance, false))) {
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+    }
+    let sourceState;
+    let parentState;
+    try {
+        sourceState = await secureIdentity(source);
+    }
+    catch {
+        // The refusal carries a code and path, not a cause.
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_NOT_FOUND, source);
+    }
+    try {
+        parentState = await secureIdentity(dirname(destination));
+    }
+    catch {
+        // The refusal carries a code and path, not a cause.
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+    }
+    if (sourceState.symbolicLink || !sourceState.file || parentState.symbolicLink || !parentState.directory) {
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, source);
+    }
+    try {
+        if (!isContained(canonicalRoot, await realpath(source)) ||
+            !isContained(canonicalRoot, await realpath(dirname(destination)))) {
+            return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, source);
+        }
+    }
+    catch {
+        // The refusal carries a code and path, not a cause.
+        return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, source);
+    }
+    try {
+        const destinationState = await secureIdentity(destination);
+        if (destinationState.symbolicLink || !destinationState.file) {
+            return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+        }
+        if (destinationState.identity.dev === sourceState.identity.dev &&
+            destinationState.identity.ino === sourceState.identity.ino) {
+            return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+        }
+        return { kind: 'unchanged', siblingRoot: input.siblingRoot, destination };
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT')) {
+            return refusal(ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT, destination);
+        }
+    }
+    return {
+        kind: 'ready',
+        siblingRoot: input.siblingRoot,
+        canonicalRoot,
+        source,
+        destination,
+        rootIdentity: root.identity,
+        sourceIdentity: sourceState.identity,
+        destinationParentIdentity: parentState.identity,
+    };
+}
+function revalidatePlan(plan) {
+    try {
+        const rootStat = lstatSync(plan.canonicalRoot, { bigint: true });
+        const sourceStat = lstatSync(plan.source, { bigint: true });
+        const parentStat = lstatSync(dirname(plan.destination), { bigint: true });
+        const root = { identity: identityOf(rootStat), directory: rootStat.isDirectory(), symbolicLink: rootStat.isSymbolicLink() };
+        const source = { identity: identityOf(sourceStat), file: sourceStat.isFile(), symbolicLink: sourceStat.isSymbolicLink() };
+        const parent = { identity: identityOf(parentStat), directory: parentStat.isDirectory(), symbolicLink: parentStat.isSymbolicLink() };
+        const structurallySafe = !root.symbolicLink &&
+            root.directory &&
+            !source.symbolicLink &&
+            source.file &&
+            !parent.symbolicLink &&
+            parent.directory &&
+            sameNode(root.identity, plan.rootIdentity) &&
+            sameNode(parent.identity, plan.destinationParentIdentity) &&
+            isContained(plan.canonicalRoot, realpathSync(plan.source)) &&
+            isContained(plan.canonicalRoot, realpathSync(dirname(plan.destination)));
+        if (!structurallySafe)
+            return ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT;
+        // A regular template replaced inside the root is a changed precondition like an in-place
+        // rewrite, whatever inode it lands on: ext4 often reuses the one just freed, APFS does not.
+        return identitiesMatch(source.identity, plan.sourceIdentity)
+            ? undefined
+            : ENVIRONMENT_CODES.ENVIRONMENT_SEED_PRECONDITION_CHANGED;
+    }
+    catch {
+        // Any filesystem failure while rechecking means the paths are no longer provably inside the root.
+        return ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT;
+    }
+}
+function seedFromPinnedDirectory(plan) {
+    const destinationDirectory = dirname(plan.destination);
+    const destinationName = basename(plan.destination);
+    const temporaryName = `.${destinationName}.cockpit-seed-${randomUUID()}`;
+    const originalDirectory = process.cwd();
+    let sourceDescriptor;
+    let temporaryDescriptor;
+    let temporaryCreated = false;
+    let result = {
+        kind: 'refusal',
+        code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+        path: plan.destination,
+    };
+    try {
+        process.chdir(destinationDirectory);
+        const pinnedDirectory = realpathSync('.');
+        const declaredDirectory = realpathSync(destinationDirectory);
+        const pinnedState = lstatSync('.', { bigint: true });
+        if (pinnedDirectory !== declaredDirectory ||
+            !isContained(plan.canonicalRoot, pinnedDirectory) ||
+            !pinnedState.isDirectory() ||
+            !sameNode(identityOf(pinnedState), plan.destinationParentIdentity)) {
+            result = {
+                kind: 'refusal',
+                code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+                path: plan.destination,
+            };
+        }
+        else {
+            sourceDescriptor = openSync(plan.source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const sourceBefore = identityOf(fstatSync(sourceDescriptor, { bigint: true }));
+            const namedSource = lstatSync(plan.source, { bigint: true });
+            if (namedSource.isSymbolicLink() ||
+                !namedSource.isFile() ||
+                !identitiesMatch(sourceBefore, plan.sourceIdentity) ||
+                namedSource.dev !== BigInt(sourceBefore.dev) ||
+                namedSource.ino !== BigInt(sourceBefore.ino) ||
+                !isContained(plan.canonicalRoot, realpathSync(plan.source))) {
+                result = {
+                    kind: 'refusal',
+                    code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_PRECONDITION_CHANGED,
+                    path: plan.source,
+                };
+            }
+            else {
+                temporaryDescriptor = openSync(temporaryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                temporaryCreated = true;
+                const buffer = Buffer.allocUnsafe(64 * 1024);
+                while (true) {
+                    const count = readSync(sourceDescriptor, buffer, 0, buffer.byteLength, null);
+                    if (count === 0)
+                        break;
+                    let offset = 0;
+                    while (offset < count)
+                        offset += writeSync(temporaryDescriptor, buffer, offset, count - offset);
+                }
+                fchmodSync(temporaryDescriptor, 0o600);
+                fsyncSync(temporaryDescriptor);
+                if (!identitiesMatch(identityOf(fstatSync(sourceDescriptor, { bigint: true })), plan.sourceIdentity)) {
+                    result = {
+                        kind: 'refusal',
+                        code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_PRECONDITION_CHANGED,
+                        path: plan.source,
+                    };
+                }
+                else if (realpathSync(destinationDirectory) !== pinnedDirectory ||
+                    !sameNode(identityOf(lstatSync('.', { bigint: true })), plan.destinationParentIdentity)) {
+                    result = {
+                        kind: 'refusal',
+                        code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+                        path: plan.destination,
+                    };
+                }
+                else {
+                    try {
+                        linkSync(temporaryName, destinationName);
+                        const temporaryState = lstatSync(temporaryName, { bigint: true });
+                        const destinationState = lstatSync(destinationName, { bigint: true });
+                        result =
+                            destinationState.isFile() &&
+                                destinationState.dev === temporaryState.dev &&
+                                destinationState.ino === temporaryState.ino
+                                ? { kind: 'created', siblingRoot: plan.siblingRoot, destination: plan.destination }
+                                : {
+                                    kind: 'refusal',
+                                    code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+                                    path: plan.destination,
+                                };
+                    }
+                    catch (error) {
+                        if (!hasErrorCode(error, 'EEXIST')) {
+                            result = {
+                                kind: 'refusal',
+                                code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+                                path: plan.destination,
+                            };
+                        }
+                        else {
+                            let destinationDescriptor;
+                            try {
+                                const namedDestination = lstatSync(destinationName, { bigint: true });
+                                destinationDescriptor = openSync(destinationName, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                                const openedDestination = fstatSync(destinationDescriptor, { bigint: true });
+                                const sameDestination = namedDestination.dev === openedDestination.dev &&
+                                    namedDestination.ino === openedDestination.ino;
+                                const aliasesSource = openedDestination.dev === BigInt(sourceBefore.dev) &&
+                                    openedDestination.ino === BigInt(sourceBefore.ino);
+                                result =
+                                    namedDestination.isFile() &&
+                                        openedDestination.isFile() &&
+                                        sameDestination &&
+                                        !aliasesSource
+                                        ? {
+                                            kind: 'unchanged',
+                                            siblingRoot: plan.siblingRoot,
+                                            destination: plan.destination,
+                                        }
+                                        : {
+                                            kind: 'refusal',
+                                            code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+                                            path: plan.destination,
+                                        };
+                            }
+                            catch {
+                                // The refusal carries a code and path, not a cause.
+                                result = {
+                                    kind: 'refusal',
+                                    code: ENVIRONMENT_CODES.TEMPLATE_PATH_OUTSIDE_ROOT,
+                                    path: plan.destination,
+                                };
+                            }
+                            finally {
+                                if (destinationDescriptor !== undefined)
+                                    closeSync(destinationDescriptor);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // The refusal carries a code and path, not a cause.
+        result = {
+            kind: 'refusal',
+            code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+            path: plan.destination,
+        };
+    }
+    finally {
+        if (temporaryDescriptor !== undefined)
+            closeSync(temporaryDescriptor);
+        if (sourceDescriptor !== undefined)
+            closeSync(sourceDescriptor);
+        if (temporaryCreated) {
+            try {
+                unlinkSync(temporaryName);
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT')) {
+                    result = {
+                        kind: 'refusal',
+                        code: ENVIRONMENT_CODES.ENVIRONMENT_SEED_FAILED,
+                        path: plan.destination,
+                    };
+                }
+            }
+        }
+        process.chdir(originalDirectory);
+    }
+    return result;
+}
+export function seedEnvironmentInstanceSync(plan) {
+    if (plan.kind !== 'ready')
+        return plan;
+    const invalidPlan = revalidatePlan(plan);
+    if (invalidPlan !== undefined) {
+        return {
+            kind: 'refusal',
+            code: invalidPlan,
+            path: invalidPlan === ENVIRONMENT_CODES.ENVIRONMENT_SEED_PRECONDITION_CHANGED
+                ? plan.source
+                : plan.destination,
+        };
+    }
+    return seedFromPinnedDirectory(plan);
+}