@omnitron-dev/omnitron 0.3.1 → 0.3.2

package/dist/files/file-node.js

@@ -0,0 +1,863 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { OMNITRON_HOME } from '../config/defaults.js';
+import { fileNameError } from '../shared/file-policy.js';
+import { assertStructuralChange, structuralPaths } from './structural-policy.js';
+export const FILE_LIMITS = {
+    chunk: 256 * 1024,
+    text: 1024 * 1024,
+    entries: 10_000,
+    page: 200,
+    fileBytes: 100 * 1024 ** 3,
+    uploads: 32,
+    records: 1000,
+};
+const INTERNAL = '.omnitron-files';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const missing = (e) => e?.code === 'ENOENT';
+export function filePath(value) {
+    if (typeof value !== 'string' ||
+        value.length > 4096 ||
+        /\\/.test(value) ||
+        Array.from(value).some((c) => c.charCodeAt(0) < 32) ||
+        value.startsWith('/') ||
+        (value !== '' && value.split('/').some((p) => fileNameError(p))))
+        throw new Error('Use a relative path inside the selected file root');
+    return value;
+}
+function fingerprint(s) {
+    return digest([s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs, s.mode].join(':'));
+}
+function entry(p, s) {
+    return {
+        name: path.posix.basename(p),
+        path: p,
+        kind: s.isSymbolicLink() ? 'symlink' : s.isDirectory() ? 'directory' : s.isFile() ? 'file' : 'special',
+        size: Number(s.size),
+        modifiedAt: new Date(Number(s.mtimeMs)).toISOString(),
+        mode: Number(s.mode) & 0o777,
+        version: fingerprint(s),
+    };
+}
+function integer(v, maximum) {
+    if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0 || v > maximum)
+        throw new Error('Invalid file byte offset or size');
+    return v;
+}
+function identifier(v) {
+    if (typeof v !== 'string' || !/^[a-f0-9-]{36}$/.test(v))
+        throw new Error('Invalid file operation ID');
+    return v;
+}
+async function exists(p) {
+    try {
+        await fs.lstat(p);
+        return true;
+    }
+    catch (e) {
+        if (missing(e))
+            return false;
+        throw e;
+    }
+}
+async function syncDirectory(p) {
+    const fd = await fs.open(p, 'r');
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+}
+/** Host-local filesystem provider. Explicit exports; no shell, SFTP or arbitrary absolute paths. */
+export class FileNode {
+    store;
+    archiveDirectory;
+    rootsById = new Map();
+    pins = new Map();
+    locks = new Map();
+    requests = 0;
+    archiveProvider;
+    archiveInstance;
+    stopped = false;
+    archiveCommits = new Map();
+    constructor(roots, store, archiveDirectory = path.join(OMNITRON_HOME, INTERNAL, 'archives')) {
+        this.store = store;
+        this.archiveDirectory = archiveDirectory;
+        if (!Array.isArray(roots) || roots.length > 32)
+            throw new Error('Configure at most 32 file roots');
+        for (const r of roots) {
+            if (!r ||
+                !/^[\w-]{1,64}$/.test(r.id) ||
+                this.rootsById.has(r.id) ||
+                typeof r.path !== 'string' ||
+                !path.isAbsolute(r.path) ||
+                typeof r.label !== 'string' ||
+                !r.label ||
+                r.label.length > 100 ||
+                (r.readOnly !== undefined && typeof r.readOnly !== 'boolean') ||
+                (r.protectedPaths !== undefined && (!Array.isArray(r.protectedPaths) || r.protectedPaths.length > 128)))
+                throw new Error('Invalid or duplicate file root');
+            for (const protectedPath of r.protectedPaths ?? []) {
+                if (!filePath(protectedPath))
+                    throw new Error('Protected structural paths must name entries inside the root');
+            }
+            this.rootsById.set(r.id, { ...r, ...(r.protectedPaths && { protectedPaths: [...r.protectedPaths] }) });
+        }
+    }
+    archives() {
+        return (this.archiveProvider ??= import('./archive-node.js').then(({ ArchiveNode }) => (this.archiveInstance = new ArchiveNode(async (actor, request) => (await this.invoke(actor, request)), async (rootId, relative) => {
+            const root = await this.root(rootId);
+            assertStructuralChange(root, filePath(relative), this.rootsById.get(rootId)?.protectedPaths);
+            await this.resolve(rootId, relative);
+        }, this.store, this.archiveDirectory))));
+    }
+    activeOperationCount() {
+        return (this.archiveInstance?.activeOperationCount() ?? 0) + this.archiveCommits.size;
+    }
+    async dispose() {
+        this.stopped = true;
+        const commits = [...this.archiveCommits.values()];
+        for (const operation of commits)
+            operation.controller.abort();
+        await Promise.all([
+            this.archiveProvider?.then((provider) => provider.dispose()),
+            ...commits.map((operation) => operation.done),
+        ]);
+        await Promise.allSettled([...this.locks.values()]);
+    }
+    roots() {
+        return {
+            protocol: 1,
+            roots: [...this.rootsById.values()].map((r) => ({
+                id: r.id,
+                label: r.label,
+                readOnly: Boolean(r.readOnly),
+                protectedPaths: structuralPaths(r.path, r.protectedPaths),
+            })),
+        };
+    }
+    async root(id, write = false) {
+        const config = this.rootsById.get(id);
+        if (!config || (write && config.readOnly))
+            throw new Error('File root is unavailable or read-only');
+        const real = await fs.realpath(config.path), stat = await fs.lstat(real, { bigint: true });
+        if (!stat.isDirectory())
+            throw new Error('Exported file root is not a directory');
+        const pin = this.pins.get(id);
+        if (pin && (pin.real !== real || pin.ino !== stat.ino || pin.dev !== stat.dev))
+            throw new Error('File root changed; review configuration and restart the daemon');
+        this.pins.set(id, { real, ino: stat.ino, dev: stat.dev });
+        return real;
+    }
+    async resolve(rootId, relative, write = false, absentLeaf = false) {
+        filePath(relative);
+        let resolved = await this.root(rootId, write);
+        const segments = relative ? relative.split('/') : [];
+        for (let i = 0; i < segments.length; i++) {
+            resolved = path.join(resolved, segments[i]);
+            let stat;
+            try {
+                stat = await fs.lstat(resolved);
+            }
+            catch (e) {
+                if (absentLeaf && i === segments.length - 1 && missing(e))
+                    return resolved;
+                throw e;
+            }
+            if (stat.isSymbolicLink())
+                throw new Error('Symbolic links are visible but cannot be followed');
+            if (i < segments.length - 1 && !stat.isDirectory())
+                throw new Error('A path component is not a directory');
+        }
+        return resolved;
+    }
+    async internal(rootId, kind, relative = '') {
+        let p = await this.resolve(rootId, relative, true);
+        for (const component of [INTERNAL, kind]) {
+            p = path.join(p, component);
+            try {
+                await fs.mkdir(p, { mode: 0o700 });
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+            const stat = await fs.lstat(p);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || stat.mode & 0o077)
+                throw new Error('Private file staging directory has unsafe ownership or permissions');
+        }
+        return p;
+    }
+    async locked(key, run) {
+        const before = this.locks.get(key) ?? Promise.resolve();
+        const current = before
+            .catch(() => { })
+            .then(() => {
+            if (this.stopped)
+                throw new Error('File provider is stopping');
+            return run();
+        });
+        this.locks.set(key, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.locks.get(key) === current)
+                this.locks.delete(key);
+        }
+    }
+    index(kind) {
+        return this.store.kvGetSync(`files:${kind}:index`) ?? [];
+    }
+    register(kind, id) {
+        let index = this.index(kind);
+        if (index.includes(id))
+            return;
+        // Keep terminal receipts for 30 days; never expire an unfinished write or un-restored trash.
+        if (index.length >= FILE_LIMITS.records) {
+            index = index.filter((key) => {
+                const value = kind === 'uploads'
+                    ? this.store.kvGetSync(`files:upload:${key}`)
+                    : this.store.kvGetSync(`files:trash:${key}`);
+                const expired = value &&
+                    ('state' in value
+                        ? ['complete', 'aborted'].includes(value.state) && value.updatedAt < Date.now() - 30 * 86400_000
+                        : value.restored);
+                if (expired)
+                    this.store.kvDeleteSync(`files:${kind === 'uploads' ? 'upload' : 'trash'}:${key}`);
+                return !expired;
+            });
+        }
+        if (index.length >= FILE_LIMITS.records)
+            throw new Error(`File ${kind} journal is full; inspect retained records before continuing`);
+        this.store.kvSetSync(`files:${kind}:index`, [...index, id]);
+    }
+    upload(actor, id) {
+        const value = this.store.kvGetSync(`files:upload:${identifier(id)}`);
+        if (!value || value.actor !== actor)
+            throw new Error('File write does not belong to this session');
+        return value;
+    }
+    persistUpload(value) {
+        value.updatedAt = Date.now();
+        this.store.kvSetSync(`files:upload:${value.id}`, value);
+    }
+    viewUpload(value) {
+        return {
+            id: value.id,
+            offset: value.offset,
+            size: value.size,
+            state: value.state,
+            ...(value.sha256 ? { sha256: value.sha256 } : {}),
+            ...(value.phase ? { phase: value.phase } : {}),
+            ...(value.restoredBytes !== undefined ? { restoredBytes: value.restoredBytes } : {}),
+            ...(value.publication ? { publication: value.publication } : {}),
+            ...(value.error ? { error: value.error } : {}),
+        };
+    }
+    viewTrash({ actor: _actor, identity: _identity, ...value }) {
+        return value;
+    }
+    async invoke(actor, request) {
+        if (this.stopped)
+            throw new Error('File provider is stopping');
+        if (!actor || actor.length > 300 || !request || typeof request !== 'object')
+            throw new Error('Invalid file request');
+        if (this.requests >= 32)
+            throw new Error('File request capacity reached');
+        this.requests++;
+        try {
+            return await this.dispatch(actor, request);
+        }
+        finally {
+            this.requests--;
+        }
+    }
+    async dispatch(actor, request) {
+        switch (request.op) {
+            case 'archiveFormats':
+            case 'prepareArchive':
+            case 'archiveStatus':
+            case 'readArchive':
+            case 'abortArchive':
+            case 'releaseArchive':
+                return this.locked('archive:' + ('id' in request ? request.id : 'formats'), async () => (await this.archives()).invoke(actor, request));
+            case 'roots':
+                return this.roots();
+            case 'list':
+                return this.list(request);
+            case 'stat':
+                return this.stat(request.rootId, request.path);
+            case 'readText':
+                return this.readText(request.rootId, request.path);
+            case 'readChunk':
+                return this.readChunk(request);
+            case 'saveText':
+                return this.locked(request.rootId, () => this.saveText(request));
+            case 'mkdir':
+                return this.locked(request.rootId, async () => {
+                    if (!filePath(request.path))
+                        throw new Error('Cannot create the exported root');
+                    const destination = await this.resolve(request.rootId, request.path, true, true);
+                    await fs.mkdir(destination, { mode: 0o700 });
+                    await syncDirectory(path.dirname(destination));
+                    return this.stat(request.rootId, request.path);
+                });
+            case 'rename':
+                return this.locked(request.rootId, () => this.rename(request));
+            case 'trash':
+                return this.locked(request.rootId, () => this.trash(actor, request));
+            case 'trashList':
+                return this.index('trash')
+                    .map((id) => this.store.kvGetSync(`files:trash:${id}`))
+                    .filter((r) => Boolean(r && r.actor === actor && r.rootId === request.rootId && !r.restored))
+                    .reverse()
+                    .map((r) => this.viewTrash(r));
+            case 'restore':
+                return this.restore(actor, request.id);
+            case 'beginArchiveWrite':
+                return this.locked(request.rootId, () => this.beginArchiveWrite(actor, request));
+            case 'beginWrite':
+                return this.locked(request.rootId, () => this.beginWrite(actor, request));
+            case 'acknowledgeWrite':
+                await this.archiveCommits.get(request.id)?.done;
+                return this.locked('receipts', () => this.acknowledgeWrite(actor, request.id));
+            case 'writeStatus': {
+                const upload = this.upload(actor, request.id);
+                if (upload.archive && upload.state === 'committing' && !this.archiveCommits.has(request.id))
+                    return {
+                        ...this.viewUpload(upload),
+                        state: 'failed',
+                        error: 'Archive restoration was interrupted before its receipt completed; resume to reconcile publication',
+                    };
+                return this.viewUpload(upload);
+            }
+            case 'writeChunk': {
+                const u = this.upload(actor, request.id);
+                return this.locked(u.rootId, () => this.writeChunk(actor, request));
+            }
+            case 'commitWrite': {
+                const u = this.upload(actor, request.id);
+                if (u.archive)
+                    return this.startArchiveCommit(actor, request.id);
+                return this.locked(u.rootId, () => this.commitWrite(actor, request.id));
+            }
+            case 'abortWrite': {
+                const u = this.upload(actor, request.id);
+                const active = this.archiveCommits.get(request.id);
+                active?.controller.abort();
+                await active?.done;
+                return this.locked(u.rootId, () => this.abortWrite(actor, request.id));
+            }
+            default:
+                throw new Error('Unsupported file protocol operation');
+        }
+    }
+    async stat(rootId, relative) {
+        const resolved = await this.resolve(rootId, relative);
+        return entry(relative, await fs.lstat(resolved, { bigint: true }));
+    }
+    async list(r) {
+        if (r.after !== undefined && (typeof r.after !== 'string' || r.after.length > 255))
+            throw new Error('Invalid directory cursor');
+        const directory = await this.resolve(r.rootId, r.path);
+        const before = await fs.lstat(directory, { bigint: true }), revision = fingerprint(before);
+        if (!before.isDirectory())
+            throw new Error('Not a directory');
+        if (r.revision && r.revision !== revision)
+            throw new Error('Directory changed; refresh before requesting the next page');
+        const names = [], stream = await fs.opendir(directory);
+        for await (const item of stream) {
+            if (item.name === INTERNAL)
+                continue;
+            names.push(item.name);
+            if (names.length > FILE_LIMITS.entries)
+                throw new Error('Directory exceeds the 10,000-entry interactive limit');
+        }
+        names.sort();
+        const remaining = names.filter((n) => r.after === undefined || n > r.after);
+        const page = remaining.slice(0, FILE_LIMITS.page);
+        const entries = [];
+        for (const name of page)
+            entries.push(entry(r.path ? `${r.path}/${name}` : name, await fs.lstat(path.join(directory, name), { bigint: true })));
+        if (fingerprint(await fs.lstat(directory, { bigint: true })) !== revision)
+            throw new Error('Directory changed while reading; refresh');
+        return { entries, next: remaining.length > page.length ? page.at(-1) : null, revision };
+    }
+    async open(rootId, relative, expected) {
+        const p = await this.resolve(rootId, relative);
+        const fd = await fs.open(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await fd.stat({ bigint: true });
+            if (!stat.isFile())
+                throw new Error('Only regular files can be read');
+            if (expected && fingerprint(stat) !== expected)
+                throw new Error('File changed; reload before continuing');
+            return { fd, stat };
+        }
+        catch (e) {
+            await fd.close();
+            throw e;
+        }
+    }
+    async readText(rootId, relative) {
+        const { fd, stat } = await this.open(rootId, relative);
+        try {
+            if (stat.size > BigInt(FILE_LIMITS.text))
+                throw new Error('Text editor supports files up to 1 MiB; use a transfer for larger files');
+            const bytes = Buffer.alloc(Number(stat.size));
+            let offset = 0;
+            while (offset < bytes.length) {
+                const read = await fd.read(bytes, offset, bytes.length - offset, offset);
+                if (!read.bytesRead)
+                    break;
+                offset += read.bytesRead;
+            }
+            if (offset !== bytes.length || fingerprint(await fd.stat({ bigint: true })) !== fingerprint(stat))
+                throw new Error('File changed while reading');
+            const decoded = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+            if (decoded.includes('\0'))
+                throw new Error('Binary content cannot be edited as text');
+            const bom = decoded.startsWith('\ufeff');
+            return { content: bom ? decoded.slice(1) : decoded, version: fingerprint(stat), bytes: bytes.length, bom };
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async readChunk(r) {
+        const offset = integer(r.offset, FILE_LIMITS.fileBytes);
+        if (typeof r.version !== 'string' || !/^[a-f0-9]{64}$/.test(r.version))
+            throw new Error('A source version is required');
+        const { fd, stat } = await this.open(r.rootId, r.path, r.version);
+        try {
+            if (stat.size > BigInt(FILE_LIMITS.fileBytes) || offset > Number(stat.size))
+                throw new Error('File size or offset exceeds the transfer limit');
+            const data = Buffer.alloc(Math.min(FILE_LIMITS.chunk, Number(stat.size) - offset));
+            let read = 0;
+            while (read < data.length) {
+                const result = await fd.read(data, read, data.length - read, offset + read);
+                if (!result.bytesRead)
+                    break;
+                read += result.bytesRead;
+            }
+            if (read !== data.length || fingerprint(await fd.stat({ bigint: true })) !== r.version)
+                throw new Error('Source changed during transfer');
+            return { data: data.toString('base64'), sha256: digest(data), offset, eof: offset + read === Number(stat.size) };
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async saveText(r) {
+        if (!filePath(r.path) ||
+            typeof r.content !== 'string' ||
+            r.content.includes('\0') ||
+            (r.bom !== undefined && typeof r.bom !== 'boolean'))
+            throw new Error('Invalid text document');
+        const bytes = Buffer.from((r.bom ? '\ufeff' : '') + r.content, 'utf8');
+        if (bytes.length > FILE_LIMITS.text)
+            throw new Error('Text editor supports at most 1 MiB');
+        const target = await this.resolve(r.rootId, r.path, true, true);
+        const prior = await fs.lstat(target, { bigint: true }).catch((e) => {
+            if (missing(e))
+                return null;
+            throw e;
+        });
+        if (prior ? !prior.isFile() || fingerprint(prior) !== r.version : r.version !== null)
+            throw new Error('Save conflict: file changed or no longer exists; reload or save a copy');
+        const staging = path.join(await this.internal(r.rootId, 'uploads', path.posix.dirname(r.path) === '.' ? '' : path.posix.dirname(r.path)), randomUUID());
+        try {
+            const fd = await fs.open(staging, 'wx', 0o600);
+            try {
+                await fd.writeFile(bytes);
+                if (prior) {
+                    await fd.chown(Number(prior.uid), Number(prior.gid));
+                    await fd.chmod(Number(prior.mode) & 0o777);
+                }
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+            await this.resolve(r.rootId, r.path, true, true);
+            const current = await fs.lstat(target, { bigint: true }).catch((e) => {
+                if (missing(e))
+                    return null;
+                throw e;
+            });
+            if (current ? fingerprint(current) !== r.version : r.version !== null)
+                throw new Error('Save conflict: file changed before commit');
+            // No-overwrite publication for new files. Existing files use atomic replacement after the version check.
+            if (!current) {
+                await fs.link(staging, target);
+                await fs.unlink(staging);
+            }
+            else
+                await fs.rename(staging, target);
+            await syncDirectory(path.dirname(target));
+            return await this.readText(r.rootId, r.path);
+        }
+        finally {
+            await fs.unlink(staging).catch((e) => {
+                if (!missing(e))
+                    throw e;
+            });
+        }
+    }
+    async structuralChange(rootId, relative, resolved) {
+        const config = this.rootsById.get(rootId);
+        assertStructuralChange(config.path, relative, config.protectedPaths);
+        const root = await this.root(rootId, true);
+        const canonical = await fs.realpath(resolved).catch(async (error) => {
+            if (!missing(error))
+                throw error;
+            return path.join(await fs.realpath(path.dirname(resolved)), path.basename(resolved));
+        });
+        assertStructuralChange(root, path.relative(root, canonical).split(path.sep).join('/'), config.protectedPaths);
+    }
+    async rename(r) {
+        if (!filePath(r.path) || !filePath(r.destination))
+            throw new Error('Cannot rename an exported root');
+        if (path.posix.dirname(r.path) !== path.posix.dirname(r.destination))
+            throw new Error('Rename must keep the same parent directory');
+        const source = await this.resolve(r.rootId, r.path, true);
+        const target = await this.resolve(r.rootId, r.destination, true, true);
+        await this.structuralChange(r.rootId, r.path, source);
+        await this.structuralChange(r.rootId, r.destination, target);
+        if ((await this.stat(r.rootId, r.path)).version !== r.version)
+            throw new Error('File changed before rename');
+        if (await exists(target))
+            throw new Error('Destination already exists');
+        await fs.rename(source, target);
+        await syncDirectory(path.dirname(target));
+        if (path.dirname(source) !== path.dirname(target))
+            await syncDirectory(path.dirname(source));
+        return this.stat(r.rootId, r.destination);
+    }
+    async trash(actor, r) {
+        if (!filePath(r.path))
+            throw new Error('Cannot remove an exported root');
+        const source = await this.resolve(r.rootId, r.path, true);
+        await this.structuralChange(r.rootId, r.path, source);
+        const sourceStat = await fs.lstat(source, { bigint: true });
+        if (fingerprint(sourceStat) !== r.version)
+            throw new Error('File changed before removal');
+        const value = {
+            id: randomUUID(),
+            actor,
+            rootId: r.rootId,
+            path: r.path,
+            removedAt: new Date().toISOString(),
+            restored: false,
+            identity: { device: String(sourceStat.dev), inode: String(sourceStat.ino) },
+        };
+        const destination = path.join(await this.internal(r.rootId, 'trash', path.posix.dirname(r.path) === '.' ? '' : path.posix.dirname(r.path)), value.id);
+        this.register('trash', value.id);
+        this.store.kvSetSync(`files:trash:${value.id}`, value);
+        await fs.rename(source, destination);
+        await syncDirectory(path.dirname(source));
+        await syncDirectory(path.dirname(destination));
+        return this.viewTrash(value);
+    }
+    async restore(actor, id) {
+        const value = this.store.kvGetSync(`files:trash:${identifier(id)}`);
+        if (!value || value.actor !== actor)
+            throw new Error('Trash record does not belong to this session');
+        return this.locked(value.rootId, async () => {
+            if (!value.restored) {
+                const target = await this.resolve(value.rootId, value.path, true, true);
+                const source = path.join(await this.internal(value.rootId, 'trash', path.posix.dirname(value.path) === '.' ? '' : path.posix.dirname(value.path)), value.id);
+                if (await exists(target)) {
+                    // A durable move may have succeeded before the journal acknowledgement failed.
+                    const restored = await fs.lstat(target, { bigint: true });
+                    if (!value.identity ||
+                        String(restored.dev) !== value.identity.device ||
+                        String(restored.ino) !== value.identity.inode ||
+                        (await exists(source)))
+                        throw new Error('Restore conflict: destination exists');
+                }
+                else {
+                    await fs.rename(source, target);
+                }
+                await syncDirectory(path.dirname(target));
+                await syncDirectory(path.dirname(source));
+                value.restored = true;
+                this.store.kvSetSync(`files:trash:${id}`, value);
+            }
+            return this.viewTrash(value);
+        });
+    }
+    async beginWrite(actor, r, archive) {
+        if (!filePath(r.path))
+            throw new Error('Choose a destination file');
+        integer(r.size, FILE_LIMITS.fileBytes);
+        if (r.sha256 !== undefined && (typeof r.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(r.sha256)))
+            throw new Error('Invalid expected file SHA-256');
+        const id = r.id === undefined ? randomUUID() : identifier(r.id);
+        const previous = this.store.kvGetSync(`files:upload:${id}`);
+        if (previous) {
+            if (previous.actor !== actor ||
+                previous.rootId !== r.rootId ||
+                previous.path !== r.path ||
+                previous.size !== r.size ||
+                previous.expectedSha256 !== r.sha256 ||
+                (previous.archive !== undefined && archive === undefined))
+                throw new Error('Upload key is already bound to another request');
+            if (previous.state === 'receiving' && previous.offset === 0) {
+                const staged = path.join(await this.internal(r.rootId, 'uploads', path.posix.dirname(r.path) === '.' ? '' : path.posix.dirname(r.path)), id);
+                try {
+                    const fd = await fs.open(staged, 'wx', 0o600);
+                    try {
+                        await fd.sync();
+                    }
+                    finally {
+                        await fd.close();
+                    }
+                    await syncDirectory(path.dirname(staged));
+                }
+                catch (e) {
+                    if (e.code !== 'EEXIST')
+                        throw e;
+                }
+            }
+            return this.viewUpload(previous);
+        }
+        if (await exists(await this.resolve(r.rootId, r.path, true, true)))
+            throw new Error('Destination exists; copy to a new name');
+        const uploads = this.index('uploads').map((key) => this.store.kvGetSync(`files:upload:${key}`));
+        if (uploads.filter((u) => u && !['complete', 'aborted'].includes(u.state)).length >= FILE_LIMITS.uploads)
+            throw new Error('File write capacity reached');
+        const u = {
+            id,
+            actor,
+            rootId: r.rootId,
+            path: r.path,
+            size: r.size,
+            offset: 0,
+            state: 'receiving',
+            updatedAt: Date.now(),
+            ...(archive ? { archive } : {}),
+            ...(r.sha256 ? { expectedSha256: r.sha256 } : {}),
+        };
+        const p = path.join(await this.internal(r.rootId, 'uploads', path.posix.dirname(r.path) === '.' ? '' : path.posix.dirname(r.path)), u.id);
+        this.register('uploads', u.id);
+        this.persistUpload(u);
+        const fd = await fs.open(p, 'wx', 0o600);
+        try {
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+        await syncDirectory(path.dirname(p));
+        return this.viewUpload(u);
+    }
+    async beginArchiveWrite(actor, r) {
+        if (!filePath(r.path) || !/^[a-f0-9]{64}$/.test(r.sha256))
+            throw new Error('A destination and archive SHA-256 are required');
+        const { validateArchiveManifest, probeArchiveFormats } = await import('./archive-codec.js');
+        validateArchiveManifest(r.manifest);
+        const previous = this.store.kvGetSync(`files:upload:${identifier(r.id)}`);
+        if (previous &&
+            (!previous.archive ||
+                previous.archive.format !== r.format ||
+                previous.archive.expectedSha256 !== r.sha256 ||
+                JSON.stringify(previous.archive.manifest) !== JSON.stringify(r.manifest)))
+            throw new Error('Upload key is bound to another archive request');
+        if (!previous &&
+            !(await probeArchiveFormats()).formats.some((item) => item.format === r.format && item.outputs.includes('directory')))
+            throw new Error('Archive restoration is unavailable for this format on the destination node');
+        // Reuse the durable chunk journal. Admission persists the decoding contract before any chunk can arrive.
+        await this.beginWrite(actor, r, {
+            format: r.format,
+            manifest: structuredClone(r.manifest),
+            expectedSha256: r.sha256,
+        });
+        const value = this.upload(actor, r.id);
+        return this.viewUpload(value);
+    }
+    async startArchiveCommit(actor, id) {
+        const u = this.upload(actor, id);
+        if (u.state === 'complete' || this.archiveCommits.has(id))
+            return this.viewUpload(u);
+        if (u.state === 'aborted' || u.offset !== u.size || !u.archive)
+            throw new Error('Cannot restore an incomplete archive');
+        if (this.archiveCommits.size >= 2)
+            throw new Error('Archive restoration capacity reached; retry after another operation completes');
+        u.state = 'committing';
+        delete u.error;
+        this.persistUpload(u);
+        const controller = new AbortController();
+        const done = Promise.resolve()
+            .then(() => this.locked(u.rootId, async () => {
+            const staged = path.join(await this.internal(u.rootId, 'uploads', path.posix.dirname(u.path) === '.' ? '' : path.posix.dirname(u.path)), id);
+            const { publishArchiveDirectory } = await import('./archive-publication.js');
+            await publishArchiveDirectory({
+                upload: u,
+                archive: u.archive,
+                staged,
+                tree: staged + '.tree',
+                target: () => this.resolve(u.rootId, u.path, true, true),
+                persist: () => this.persistUpload(u),
+                signal: AbortSignal.any([controller.signal, AbortSignal.timeout(60 * 60_000)]),
+            });
+            // The completed receipt survives cleanup errors; a lost acknowledgement can retry cleanup.
+            try {
+                await fs.unlink(staged);
+                await fs.rm(staged + '.tree', { recursive: true, force: true });
+                await syncDirectory(path.dirname(staged));
+            }
+            catch {
+                u.error = 'Directory published; private staging cleanup awaits receipt acknowledgement';
+                this.persistUpload(u);
+            }
+        }))
+            .catch((error) => {
+            if (u.state === 'complete')
+                return;
+            u.state = 'failed';
+            u.error = (error instanceof Error ? error.message : String(error)).slice(0, 1000);
+            if (u.publication === 'partial')
+                u.error = `Directory publication is partial. Resume this transfer to reconcile it; ${u.error}`;
+            this.persistUpload(u);
+        })
+            .finally(() => this.archiveCommits.delete(id));
+        this.archiveCommits.set(id, { controller, done });
+        // Journaling failures remain visible through the last durable committing receipt and explicit resume.
+        void done.catch(() => { });
+        return this.viewUpload(u);
+    }
+    async writeChunk(actor, r) {
+        const u = this.upload(actor, r.id), offset = integer(r.offset, FILE_LIMITS.fileBytes);
+        if (u.state !== 'receiving')
+            throw new Error('Write session is not receiving');
+        if (typeof r.data !== 'string' ||
+            r.data.length > Math.ceil(FILE_LIMITS.chunk / 3) * 4 ||
+            !/^[a-f0-9]{64}$/.test(r.sha256))
+            throw new Error('Invalid file chunk');
+        const data = Buffer.from(r.data, 'base64');
+        if (!data.length ||
+            data.length > FILE_LIMITS.chunk ||
+            data.toString('base64') !== r.data ||
+            digest(data) !== r.sha256 ||
+            offset + data.length > u.size)
+            throw new Error('File chunk size, encoding or checksum mismatch');
+        if (offset > u.offset)
+            throw new Error('File chunk arrived out of order');
+        const fd = await fs.open(path.join(await this.internal(u.rootId, 'uploads', path.posix.dirname(u.path) === '.' ? '' : path.posix.dirname(u.path)), u.id), constants.O_RDWR | constants.O_NOFOLLOW);
+        try {
+            if (!(await fd.stat()).isFile())
+                throw new Error('Invalid staged file');
+            if (offset < u.offset) {
+                if (offset + data.length > u.offset)
+                    throw new Error('File chunk overlaps the acknowledged boundary');
+                const previous = Buffer.alloc(data.length);
+                const read = await fd.read(previous, 0, previous.length, offset);
+                if (read.bytesRead !== previous.length || digest(previous) !== r.sha256)
+                    throw new Error('Conflicting duplicate file chunk');
+                return this.viewUpload(u);
+            }
+            await fd.truncate(u.offset); // A crash can leave durable bytes ahead of the last journal acknowledgement.
+            let written = 0;
+            while (written < data.length) {
+                const part = await fd.write(data, written, data.length - written, offset + written);
+                if (!part.bytesWritten)
+                    throw new Error('File write made no progress');
+                written += part.bytesWritten;
+            }
+            await fd.datasync();
+            u.offset += written;
+            this.persistUpload(u);
+            return this.viewUpload(u);
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async commitWrite(actor, id) {
+        const u = this.upload(actor, id);
+        if (u.state === 'complete')
+            return this.viewUpload(u);
+        if (u.state === 'aborted' || u.offset !== u.size)
+            throw new Error('Cannot commit an incomplete write');
+        const staged = path.join(await this.internal(u.rootId, 'uploads', path.posix.dirname(u.path) === '.' ? '' : path.posix.dirname(u.path)), u.id);
+        const target = await this.resolve(u.rootId, u.path, true, true);
+        const sourceStat = await fs.lstat(staged, { bigint: true });
+        if (!sourceStat.isFile() || sourceStat.size !== BigInt(u.size))
+            throw new Error('Staged file size changed');
+        const hash = createHash('sha256'), fd = await fs.open(staged, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            for await (const chunk of fd.createReadStream({ autoClose: false, highWaterMark: FILE_LIMITS.chunk }))
+                hash.update(chunk);
+        }
+        finally {
+            await fd.close();
+        }
+        u.sha256 = hash.digest('hex');
+        if (u.expectedSha256 && u.sha256 !== u.expectedSha256)
+            throw new Error('Transferred file SHA-256 does not match the admitted source');
+        u.state = 'committing';
+        this.persistUpload(u);
+        try {
+            await fs.link(staged, target);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            const dest = await fs.lstat(target, { bigint: true });
+            // An acknowledgement can be lost after link(). Only our exact staged inode is a successful retry.
+            if (dest.ino !== sourceStat.ino || dest.dev !== sourceStat.dev)
+                throw new Error('Destination exists; nothing was overwritten', { cause: e });
+        }
+        await syncDirectory(path.dirname(target));
+        u.state = 'complete';
+        this.persistUpload(u);
+        await fs.unlink(staged);
+        await syncDirectory(path.dirname(staged));
+        return this.viewUpload(u);
+    }
+    async acknowledgeWrite(actor, id) {
+        identifier(id);
+        if (!this.store.kvGetSync(`files:upload:${id}`))
+            return;
+        const u = this.upload(actor, id);
+        if (!['complete', 'aborted'].includes(u.state))
+            throw new Error('Only a final receipt can be acknowledged');
+        // The caller has durably advanced its cursor. Free admission capacity without touching the published file.
+        const staged = path.join(await this.internal(u.rootId, 'uploads', path.posix.dirname(u.path) === '.' ? '' : path.posix.dirname(u.path)), id);
+        await fs.unlink(staged).catch((e) => {
+            if (!missing(e))
+                throw e;
+        });
+        if (u.archive)
+            await fs.rm(staged + '.tree', { recursive: true, force: true });
+        await syncDirectory(path.dirname(staged));
+        this.store.kvSetSync('files:uploads:index', this.index('uploads').filter((key) => key !== id));
+        this.store.kvDeleteSync(`files:upload:${id}`);
+    }
+    async abortWrite(actor, id) {
+        const u = this.upload(actor, id);
+        if (u.archive?.reservationAttempted && u.state !== 'complete')
+            throw new Error('Directory publication is partial or uncertain; resume to reconcile before cancelling');
+        if (u.state === 'committing' && !u.archive)
+            throw new Error('Commit outcome must be reconciled before cancelling');
+        if (u.state === 'receiving' || (u.archive && ['failed', 'committing'].includes(u.state))) {
+            const p = path.join(await this.internal(u.rootId, 'uploads', path.posix.dirname(u.path) === '.' ? '' : path.posix.dirname(u.path)), u.id);
+            u.state = 'aborted';
+            this.persistUpload(u);
+            await fs.unlink(p).catch((e) => {
+                if (!missing(e))
+                    throw e;
+            });
+            if (u.archive)
+                await fs.rm(p + '.tree', { recursive: true, force: true });
+            await syncDirectory(path.dirname(p));
+        }
+        return this.viewUpload(u);
+    }
+}
+//# sourceMappingURL=file-node.js.map