Files
stack/packages/library/src/mirror.mjs
T
jason.woltje e54e054632 row 215: C2-04 the library entry in the business file, consumer skips, M9 organization-projects-protected, the bare mirror, library.file and library.status (#1716)
The business file accepts a kind "library" project entry, and each consumer
that assumed a project root skips it. An organization write whose projects
differ from the file's is refused (M9). The bare mirror is created at the
projectRepo path with no remote. library.file and library.status are human
only and refuse an agent session with human-required.
Candidate herb/row215-on197 dde3445ab on a36523713, Filbert APPROVE rev 2924.
2026-10-21 14:24:37 -05:00

258 lines
14 KiB
JavaScript

// C2-04: host-only bare library storage. No remote, fetch, credential or
// working tree. The broker receives these functions through the runtime.
import { constants, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync,
openSync, readSync, readdirSync, realpathSync, rmSync } from 'node:fs';
import { dirname, isAbsolute, join, normalize } from 'node:path';
import { execFile, spawn } from 'node:child_process';
import { projectRepo, noLinks } from '../../project/src/paths.mjs';
import { git } from '../../project/src/git.mjs';
import { checkMapping } from './mapping.mjs';
import { classify } from './scope.mjs';
import { LibraryError, RULES } from './problems.mjs';
import { listTree, readLibrary, readTexts } from './reader.mjs';
export const SYNC_STATE_FILE = 'mosaic-library-sync.json';
const LOCK_FILE = 'mosaic-library-sync.lock';
const STATE_MAX = 8 * 1024 * 1024;
const SHA = /^[a-f0-9]{40}$/;
const fail = (code, message = code) => { throw new LibraryError(code, message); };
const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
const keys = (value, expected) => object(value) && Object.keys(value).length === expected.length
&& Object.keys(value).every(key => expected.includes(key));
const optional = (value, check) => value === null || check(value);
const utc = value => {
if (typeof value !== 'string') return false;
try { return new Date(value).toISOString() === value; } catch { return false; }
};
const empty = branch => ({ version: 1, branch, served: null, lastFetch: null, lastError: null, diverged: null, problems: [] });
function contextEntry(context) {
const { business, project } = context;
if (!Object.hasOwn(business?.projects ?? {}, project)) fail('project-not-declared');
const entry = business.projects[project];
if (entry?.kind !== 'library') fail('library-mapping-invalid', 'expected a library project');
return checkMapping(entry);
}
export function mirrorPath(context) {
contextEntry(context);
try { return projectRepo(context, { allowLibrary: true }); }
catch (error) { throw new LibraryError(error.code ?? 'library-git', 'unsafe mirror path'); }
}
function ownedRoot(mirror) {
try {
if (typeof mirror !== 'string' || !isAbsolute(mirror) || normalize(mirror) !== mirror) throw Error();
noLinks(mirror);
const st = lstatSync(mirror);
if (!st.isDirectory() || st.uid !== process.getuid() || (st.mode & 0o077) || realpathSync(mirror) !== mirror) throw Error();
} catch { fail('library-git', 'expected a private owned bare mirror'); }
}
function privateFile(st) {
return st.isFile() && st.uid === process.getuid() && st.nlink === 1 && (st.mode & 0o077) === 0;
}
async function inspectMirrorUnchecked(mirror) {
ownedRoot(mirror);
const normal = ['HEAD', 'config', 'description', 'hooks', 'info', 'objects', 'refs', 'logs', 'packed-refs', 'shallow', 'FETCH_HEAD', 'ORIG_HEAD'];
const allowed = new Set([...normal, ...normal.filter(name => !['hooks', 'info', 'objects', 'refs', 'logs', 'description'].includes(name)).map(name => name + '.lock'), SYNC_STATE_FILE, LOCK_FILE]);
const top = readdirSync(mirror);
if (top.some(name => !allowed.has(name)) || ['HEAD', 'config', 'objects', 'refs'].some(name => !top.includes(name)))
fail('library-git', 'unexpected bare mirror layout');
for (const path of ['commondir', 'objects/info/alternates', 'objects/info/http-alternates'])
if (existsSync(join(mirror, path))) fail('library-git', 'Git metadata indirection refused');
const walk = (folder, topLevel = false) => {
for (const name of readdirSync(folder)) {
const file = join(folder, name); let st;
try { st = lstatSync(file); }
catch (error) { if (error.code === 'ENOENT') continue; throw error; }
const state = topLevel && [SYNC_STATE_FILE, LOCK_FILE].includes(name);
if (state) { if (!privateFile(st)) fail('library-state-invalid', 'unsafe state or lock metadata'); }
else if (st.isDirectory() && !st.isSymbolicLink()) walk(file);
else if (!st.isFile() || st.nlink !== 1 || st.uid !== process.getuid()) fail('library-git', 'unsafe Git metadata');
}
};
walk(mirror, true);
if (!top.includes(LOCK_FILE)) fail('library-state-invalid', 'mirror lock file missing');
if (lstatSync(join(mirror, 'config')).size > 65536) fail('library-git', 'Git config too large');
let config;
try { config = await git(mirror, ['config', '--no-includes', '--file', join(mirror, 'config'), '--list', '--null']); }
catch { fail('library-git', 'cannot inspect mirror config'); }
const values = { 'core.repositoryformatversion': ['0'], 'core.filemode': ['true', 'false'], 'core.bare': ['true'],
'core.logallrefupdates': ['true', 'false'], 'core.ignorecase': ['true', 'false'] };
let bare = false;
for (const item of config.split('\0').filter(Boolean)) {
const at = item.indexOf('\n'), key = item.slice(0, at), value = item.slice(at + 1);
if (key === 'core.bare' && value === 'true') bare = true;
if (at < 0 || !values[key]?.includes(value)) fail('library-git', 'unsupported bare mirror config');
}
if (!bare) fail('library-git', 'expected a bare repository');
}
async function inspectMirror(mirror) {
try { await inspectMirrorUnchecked(mirror); }
catch (error) {
if (error instanceof LibraryError) throw error;
fail('library-git', 'unreadable bare mirror metadata');
}
}
export async function ensureMirror(context) {
const mirror = mirrorPath(context);
if (existsSync(mirror)) { await inspectMirror(mirror); return mirror; }
const parent = dirname(mirror); mkdirSync(parent, { recursive: true, mode: 0o700 }); noLinks(parent);
const staged = mkdtempSync(join(parent, '.library-init-'));
const original = lstatSync(staged);
const isOwnStage = st => st.isDirectory() && st.uid === process.getuid() && st.dev === original.dev && st.ino === original.ino;
try {
await git(staged, ['init', '--bare', '--initial-branch=served', '--template=']);
const fd = openSync(join(staged, LOCK_FILE), constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
closeSync(fd);
await inspectMirror(staged);
// Coreutils versions disagree on the status of a skipped no-clobber
// rename. The original inode, rather than that status, decides who won.
const moveError = await new Promise(resolve => execFile('/usr/bin/mv', ['--no-clobber', '--no-target-directory', staged, mirror],
{ timeout: 5000, maxBuffer: 65536, env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' } }, error => resolve(error)));
let remaining;
try { remaining = lstatSync(staged); } catch (error) { if (error.code !== 'ENOENT') throw error; }
if (remaining) {
if (!isOwnStage(remaining)) fail('library-git', 'staging directory was replaced');
// A skipped rename is valid only when another intact mirror won.
// Signals, timeouts and spawn failures are always genuine errors.
if (moveError && (typeof moveError.code !== 'number' || moveError.killed || moveError.signal)) throw moveError;
} else {
if (!isOwnStage(lstatSync(mirror))) fail('library-git', 'mirror publication identity mismatch');
if (moveError) throw moveError;
}
await inspectMirror(mirror);
return mirror;
} catch (error) {
if (error instanceof LibraryError) throw error;
fail('library-git', 'bare mirror initialization refused');
} finally {
let remaining;
try { remaining = lstatSync(staged); } catch (error) { if (error.code !== 'ENOENT') throw error; }
if (remaining) {
if (!isOwnStage(remaining)) fail('library-git', 'refusing to remove replaced staging directory');
rmSync(staged, { recursive: true });
}
}
}
// Each acquisition opens a distinct description. flock(1) inherits it as
// fd 3 and exits after acquisition; this parent's fd retains the lock.
export async function withLibraryLock(mirror, operation) {
ownedRoot(mirror);
let fd;
try {
try {
fd = openSync(join(mirror, LOCK_FILE), constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
if (!privateFile(fstatSync(fd))) fail('library-state-invalid', 'unsafe library lock');
} catch { fail('library-state-invalid', 'library lock missing or unsafe'); }
await new Promise((resolve, reject) => {
const child = spawn('/usr/bin/flock', ['--exclusive', '--wait', '5', '--conflict-exit-code', '75', '3'],
{ env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' }, stdio: ['ignore', 'ignore', 'ignore', fd] });
child.once('error', () => reject(new LibraryError('library-state-invalid', 'host requires /usr/bin/flock')));
child.once('close', code => code === 0 ? resolve() : reject(new LibraryError(code === 75 ? 'library-sync-busy' : 'library-state-invalid', 'library lock acquisition refused')));
});
try {
const heldStat = fstatSync(fd), pathStat = lstatSync(join(mirror, LOCK_FILE));
if (!privateFile(pathStat) || pathStat.ino !== heldStat.ino || pathStat.dev !== heldStat.dev) throw Error();
} catch { fail('library-state-invalid', 'library lock was replaced'); }
let held = true;
const pending = new Set();
const readSyncState = options => {
if (!held) return Promise.reject(new LibraryError('library-state-invalid', 'library lock scope expired'));
const read = readStateHeld(mirror, options).finally(() => pending.delete(read));
pending.add(read); read.catch(() => {});
return read;
};
try { return await operation({ readSyncState }); }
finally {
held = false;
// An accidentally unawaited scoped read must finish before this fd
// releases the lock. No new read can start after the callback ends.
await Promise.allSettled([...pending]);
}
} finally { if (fd !== undefined) closeSync(fd); }
}
export async function servedCommit(mirror) {
await inspectMirror(mirror);
try {
const refs = await git(mirror, ['for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads/served']);
const line = refs.split('\n').find(line => line.startsWith('refs/heads/served '));
if (!line) {
if (existsSync(join(mirror, 'refs/heads/served'))) fail('library-state-invalid', 'invalid served ref');
return null;
}
const commit = line.slice('refs/heads/served '.length);
if (!SHA.test(commit) || await git(mirror, ['cat-file', '-t', commit]) !== 'commit') fail('library-state-invalid', 'served ref must name a commit');
return commit;
} catch { fail('library-state-invalid', 'served ref is unreadable'); }
}
function validProblem(value) {
return object(value) && Object.keys(value).every(key => ['code', 'path', 'message', 'line'].includes(key))
&& Object.hasOwn(RULES, value.code) && value.message === RULES[value.code]
&& typeof value.path === 'string' && value.path.length > 0 && value.path.length <= 4096 && !value.path.includes('\0')
&& (!Object.hasOwn(value, 'line') || Number.isSafeInteger(value.line) && value.line > 0);
}
async function readStateHeld(mirror, { branch } = {}) {
if (typeof branch !== 'string' || !branch) fail('library-state-invalid', 'configured branch required');
const served = await servedCommit(mirror);
let fd, value;
try {
try { fd = openSync(join(mirror, SYNC_STATE_FILE), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
catch (error) {
if (error.code === 'ENOENT' && served === null) return empty(branch);
fail('library-state-invalid', 'sync state missing or unsafe');
}
const st = fstatSync(fd);
if (!privateFile(st) || st.size > STATE_MAX) fail('library-state-invalid', 'sync state must be bounded and private');
const bytes = Buffer.alloc(Math.min(st.size + 1, STATE_MAX + 1));
let used = 0;
while (used < bytes.length) { const read = readSync(fd, bytes, used, bytes.length - used, null); if (!read) break; used += read; }
if (used > STATE_MAX || used > st.size) fail('library-state-invalid', 'state changed during bounded read');
value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, used)));
} catch { fail('library-state-invalid', 'invalid sync state'); }
finally { if (fd !== undefined) closeSync(fd); }
if (!keys(value, ['version', 'branch', 'served', 'lastFetch', 'lastError', 'diverged', 'problems'])
|| value.version !== 1 || value.branch !== branch || value.served !== served
|| !optional(value.served, v => typeof v === 'string' && SHA.test(v)) || !optional(value.lastFetch, utc)
|| !optional(value.lastError, v => keys(v, ['code', 'at']) && typeof v.code === 'string' && /^[a-z-]{1,64}$/.test(v.code) && utc(v.at))
|| !optional(value.diverged, v => keys(v, ['commit', 'at']) && typeof v.commit === 'string' && SHA.test(v.commit) && utc(v.at))
|| !Array.isArray(value.problems) || !value.problems.every(validProblem))
fail('library-state-invalid', 'sync state does not match its contract or served ref');
return value;
}
export async function readSyncState(mirror, options) {
return withLibraryLock(mirror, lock => lock.readSyncState(options));
}
export async function libraryStatus(context) {
const mapping = contextEntry(context), mirror = mirrorPath(context);
return { project: context.project, ...await readSyncState(mirror, { branch: mapping.branch }) };
}
export async function readLibraryFile(context) {
if (!object(context) || Object.keys(context).some(key => !['business', 'project', 'dataRoot', 'path'].includes(key)))
fail('project-read-path', 'unknown library read arguments');
const mapping = contextEntry(context), path = context.path;
if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\0') || path.split('/').some(p => !p || p === '.' || p === '..')
|| classify(mapping, path).scope === 'unmapped') fail('project-read-path', 'expected a mapped library note');
const mirror = mirrorPath(context);
// Snapshot under the publication lock, then read only immutable objects.
const state = await readSyncState(mirror, { branch: mapping.branch });
if (!state.served) fail('library-commit', 'library has never been synced');
const read = await readLibrary({ repo: mirror, commit: state.served, mapping });
if (!read.files.some(file => file.path === path)) fail('project-read-missing', 'file is absent or excluded at served commit');
const entry = (await listTree(mirror, state.served)).find(entry => entry.path === path);
const texts = await readTexts(mirror, [entry]);
if (!texts.has(path)) fail('project-read-missing', 'file is not readable');
return { project: context.project, path, commit: state.served, content: texts.get(path) };
}