// 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) }; }