forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/protected-path-manifest.js

@@ -0,0 +1,281 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const PROTECTED_PATH_CATEGORY_IDS = [
+	'forge_core',
+	'user_protocol',
+	'generated_artifacts',
+	'append_only_logs',
+	'secrets',
+	'beads_state',
+	'immutable',
+];
+
+const ALLOWED_MODES = new Set([
+	'checksum-verified',
+	'cli-only',
+	'ci-blocked',
+	'runtime-only',
+	'secret-scan-blocked',
+	'bd-cli-only',
+	'tool-owned',
+]);
+
+const EXPECTED_CATEGORY_MODES = {
+	forge_core: 'checksum-verified',
+	user_protocol: 'cli-only',
+	generated_artifacts: 'ci-blocked',
+	append_only_logs: 'runtime-only',
+	secrets: 'secret-scan-blocked',
+	beads_state: 'bd-cli-only',
+	immutable: 'tool-owned',
+};
+
+const DEFAULT_PROTECTED_PATH_MANIFEST_PATH = path.resolve(__dirname, '..', '.forge', 'protected-paths.yaml');
+
+const PROTECTED_PATH_HARNESS_ENFORCEMENT = {
+	claude: {
+		status: 'native',
+		surface: 'Claude PreToolUse hook for write/edit tools',
+		configPath: '.claude/settings.json',
+		delivered: 'Rendered by lib/hook-renderer.js into .claude/settings.json; the installed .forge/hooks/forge-native-hook.js adapter receives tool_input.file_path and denies protected writes with a repair hint.',
+		evidenceRequired: ['hook receives target path', 'blocked write returns repair hint'],
+	},
+	cursor: {
+		status: 'fallback',
+		surface: 'Forge CLI/pre-commit check or file-watcher fallback',
+		configPath: 'lefthook.yml',
+		evidenceRequired: ['staged file check', 'watcher proof before native hook claim'],
+		knownIssue: 'No verified Cursor hook surface; keep Cursor protected-path enforcement on Forge CLI/pre-commit fallback until proven.',
+	},
+	codex: {
+		status: 'native-hook-contract',
+		surface: 'Codex lifecycle hook for write/edit tools',
+		configPath: '.codex/config.toml',
+		evidenceRequired: ['hook receives target path', 'blocked write returns repair hint'],
+	},
+};
+
+function clone(value) {
+	return structuredClone(value);
+}
+
+function getDefaultProtectedPathManifest() {
+	return loadProtectedPathManifest(DEFAULT_PROTECTED_PATH_MANIFEST_PATH);
+}
+
+function getProtectedPathHarnessEnforcement() {
+	return clone(PROTECTED_PATH_HARNESS_ENFORCEMENT);
+}
+
+function validateProtectedPathManifest(manifest) {
+	const errors = [];
+	if (!manifest || typeof manifest !== 'object') {
+		return { ok: false, errors: ['Manifest must be an object.'] };
+	}
+	if (!isSupportedManifestKind(manifest)) {
+		errors.push('kind must be ProtectedPathManifest or forge.protectedPaths.');
+	}
+	if (!isSupportedManifestVersion(manifest)) {
+		errors.push('schemaVersion/version must be 1.0.0 or 1.');
+	}
+
+	if (isLegacyProtectedPathsManifest(manifest)) {
+		if (!Array.isArray(manifest.paths) || manifest.paths.length === 0) {
+			errors.push('Legacy forge.protectedPaths manifest must declare at least one path.');
+		}
+		return { ok: errors.length === 0, errors };
+	}
+
+	if (!Array.isArray(manifest.categories)) errors.push('categories must be an array.');
+
+	const categories = Array.isArray(manifest.categories) ? manifest.categories : [];
+	const ids = categories.map(category => category?.id).filter(Boolean);
+	for (const requiredId of PROTECTED_PATH_CATEGORY_IDS) {
+		if (!ids.includes(requiredId)) errors.push(`Missing required protected path category: ${requiredId}.`);
+	}
+	const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+	if (duplicates.length > 0) errors.push(`Duplicate protected path categories: ${[...new Set(duplicates)].join(', ')}.`);
+
+	for (const category of categories) {
+		validateCategory(category, errors);
+	}
+	validateLegacySurfaceCoverage(manifest, categories, errors);
+
+	return { ok: errors.length === 0, errors };
+}
+
+function validateCategory(category, errors) {
+	if (!category || typeof category !== 'object') {
+		errors.push('Each category must be an object.');
+		return;
+	}
+	if (!category.id || typeof category.id !== 'string') errors.push('Category id must be a string.');
+	if (!ALLOWED_MODES.has(category.mode)) {
+		const modeLabel = category.mode ?? '<missing>';
+		errors.push(`Invalid mode for ${category.id || 'unknown'}: ${modeLabel}.`);
+	}
+	const expectedMode = EXPECTED_CATEGORY_MODES[category.id];
+	if (expectedMode && category.mode !== expectedMode) {
+		errors.push(`Category ${category.id} must use mode ${expectedMode}.`);
+	}
+	if (!Array.isArray(category.paths) || category.paths.length === 0) {
+		errors.push(`Category ${category.id || 'unknown'} must declare at least one path.`);
+	}
+	if (!category.ownerSurface || typeof category.ownerSurface !== 'string') {
+		errors.push(`Category ${category.id || 'unknown'} must declare ownerSurface.`);
+	}
+	if (!category.repairHint || typeof category.repairHint !== 'string') {
+		errors.push(`Category ${category.id || 'unknown'} must declare repairHint.`);
+	}
+}
+
+function isSupportedManifestKind(manifest) {
+	return manifest.kind === 'ProtectedPathManifest' || manifest.kind === 'forge.protectedPaths';
+}
+
+function isSupportedManifestVersion(manifest) {
+	if (manifest.kind === 'ProtectedPathManifest') {
+		return manifest.schemaVersion === '1.0.0';
+	}
+	if (manifest.kind === 'forge.protectedPaths') {
+		return manifest.version === '1' || manifest.version === 1;
+	}
+	return false;
+}
+
+function isLegacyProtectedPathsManifest(manifest) {
+	return manifest.kind === 'forge.protectedPaths';
+}
+
+function loadProtectedPathManifest(filePath) {
+	try {
+		const content = fs.readFileSync(filePath, 'utf8');
+		return YAML.parse(content);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const wrapped = new Error(`Failed to load protected path manifest at ${filePath}: ${message}`, { cause: error });
+		if (error && typeof error === 'object' && 'code' in error) {
+			wrapped.code = error.code;
+		}
+		throw wrapped;
+	}
+}
+
+function buildProtectedPathManifestEvidence(manifest = getDefaultProtectedPathManifest()) {
+	let categoryIds = [];
+	if (Array.isArray(manifest.categories)) {
+		categoryIds = manifest.categories.map(category => category?.id).filter(Boolean);
+	}
+	return {
+		schemaVersion: manifest.schemaVersion,
+		kind: 'forge.protectedPathManifest',
+		manifestPath: manifest.manifestPath || '.forge/protected-paths.yaml',
+		categoryIds,
+		categories: manifest.categories,
+		harnessEnforcement: getProtectedPathHarnessEnforcement(),
+		validation: validateProtectedPathManifest(manifest),
+	};
+}
+
+function validateLegacySurfaceCoverage(manifest, categories, errors) {
+	if (!manifest.surfaces) return;
+	if (manifest.surfacesDeprecated !== true) {
+		errors.push('surfaces must be marked surfacesDeprecated: true when categories are authoritative.');
+	}
+	if (!manifest.surfacesMigrationNote || typeof manifest.surfacesMigrationNote !== 'string') {
+		errors.push('surfacesMigrationNote must describe the legacy surfaces migration.');
+	}
+	const categoryPaths = categories.flatMap(category => (Array.isArray(category?.paths) ? category.paths : []));
+	for (const [surfaceId, surface] of Object.entries(manifest.surfaces)) {
+		if (!Array.isArray(surface?.examples) || surface.examples.length === 0) {
+			errors.push(`Legacy surface ${surfaceId} must declare examples for category coverage.`);
+			continue;
+		}
+		for (const example of surface.examples) {
+			if (!categoryPaths.some(pattern => pathPatternCoversExample(pattern, example))) {
+				errors.push(`Legacy surface ${surfaceId} example is not covered by category paths: ${example}.`);
+			}
+		}
+	}
+}
+
+function pathPatternCoversExample(pattern, example) {
+	const normalizedPattern = normalizeManifestPath(pattern);
+	const normalizedExample = normalizeManifestPath(example);
+	if (normalizedPattern === normalizedExample) return true;
+	if (normalizedPattern.endsWith('/**')) {
+		const prefix = normalizedPattern.slice(0, -3);
+		return normalizedExample === prefix || normalizedExample.startsWith(`${prefix}/`);
+	}
+	return wildcardPathMatches(normalizedPattern, normalizedExample);
+}
+
+function normalizeManifestPath(value) {
+	let normalized = String(value || '').replaceAll('\\', '/');
+	if (normalized.startsWith('./')) normalized = normalized.slice(2);
+	while (normalized.endsWith('/')) normalized = normalized.slice(0, -1);
+	return normalized;
+}
+
+function wildcardPathMatches(pattern, candidate) {
+	return pathSegmentsMatch(pattern.split('/'), candidate.split('/'), 0, 0, new Map());
+}
+
+function pathSegmentsMatch(patternParts, candidateParts, patternIndex, candidateIndex, memo) {
+	const memoKey = `${patternIndex}:${candidateIndex}`;
+	if (memo.has(memoKey)) return memo.get(memoKey);
+	if (patternIndex === patternParts.length) return candidateIndex === candidateParts.length;
+
+	const patternPart = patternParts[patternIndex];
+	let matches;
+	if (patternPart === '**') {
+		matches =
+			pathSegmentsMatch(patternParts, candidateParts, patternIndex + 1, candidateIndex, memo) ||
+			(candidateIndex < candidateParts.length && pathSegmentsMatch(patternParts, candidateParts, patternIndex, candidateIndex + 1, memo));
+	} else {
+		matches =
+			candidateIndex < candidateParts.length &&
+			segmentPatternMatches(patternPart, candidateParts[candidateIndex]) &&
+			pathSegmentsMatch(patternParts, candidateParts, patternIndex + 1, candidateIndex + 1, memo);
+	}
+	memo.set(memoKey, matches);
+	return matches;
+}
+
+function segmentPatternMatches(pattern, candidate) {
+	let patternIndex = 0;
+	let candidateIndex = 0;
+	let starIndex = -1;
+	let candidateCheckpoint = 0;
+	while (candidateIndex < candidate.length) {
+		if (pattern[patternIndex] === candidate[candidateIndex]) {
+			patternIndex += 1;
+			candidateIndex += 1;
+		} else if (pattern[patternIndex] === '*') {
+			starIndex = patternIndex;
+			candidateCheckpoint = candidateIndex;
+			patternIndex += 1;
+		} else if (starIndex === -1) {
+			return false;
+		} else {
+			patternIndex = starIndex + 1;
+			candidateCheckpoint += 1;
+			candidateIndex = candidateCheckpoint;
+		}
+	}
+	while (pattern[patternIndex] === '*') patternIndex += 1;
+	return patternIndex === pattern.length;
+}
+
+module.exports = {
+	PROTECTED_PATH_CATEGORY_IDS,
+	buildProtectedPathManifestEvidence,
+	getDefaultProtectedPathManifest,
+	getProtectedPathHarnessEnforcement,
+	loadProtectedPathManifest,
+	validateProtectedPathManifest,
+};

package/lib/protected-state-surfaces.js

@@ -0,0 +1,387 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { redact } = require('./audit-evidence');
+
+function normalizeRepoPath(filePath) {
+	return String(filePath || '')
+		.replace(/\\/g, '/')
+		.replace(/^\.\//, '')
+		.replace(/\/+/g, '/');
+}
+
+function startsWithAny(filePath, prefixes) {
+	return prefixes.some(prefix => filePath === prefix || filePath.startsWith(`${prefix}/`));
+}
+
+const PROTECTED_SURFACES = [
+	{
+		id: 'immutable',
+		label: 'Immutable runtime paths',
+		matches: filePath => startsWithAny(filePath, ['.git', '.hg', '.svn']),
+		repairHint: 'Do not edit immutable VCS/runtime internals directly; use git or the owning tool command.',
+	},
+	{
+		id: 'secrets',
+		label: 'Secrets',
+		matches: filePath =>
+			filePath === '.env' ||
+			filePath.startsWith('.env.') ||
+			filePath.endsWith('/.env') ||
+			filePath.includes('/.env.') ||
+			/(^|\/)(secrets?|credentials?)(\.|\/|$)/i.test(filePath),
+		repairHint: 'Use the project secret manager or local environment setup command; never hand-edit or commit secrets.',
+	},
+	{
+		id: 'append_only_logs',
+		label: 'Append-only logs',
+		matches: filePath =>
+			[
+				'.forge/log.jsonl',
+				'.forge/audit.log',
+				'.forge/agent-log.ndjson',
+				'.beads/interactions.jsonl',
+			].includes(filePath),
+		repairHint: 'append-only logs must be written by the Forge or Beads audit writer; do not rewrite existing log content.',
+	},
+	{
+		id: 'beads_state',
+		label: 'Beads state',
+		matches: filePath => startsWithAny(filePath, ['.beads']),
+		repairHint: 'Use bd or Forge issue commands such as bd update, bd close, forge ready, or forge close.',
+	},
+	{
+		id: 'forge_config',
+		label: 'Forge config',
+		matches: filePath =>
+			filePath === '.forge/config.yaml' ||
+			filePath === '.forge/config.yml' ||
+			filePath === '.forge/config.json' ||
+			filePath === '.forge/protected-paths.yaml',
+		repairHint: 'Use Forge setup/config commands or the protected Forge API writer for .forge configuration.',
+	},
+	{
+		id: 'extension_manifests',
+		label: 'Extension manifests',
+		matches: filePath =>
+			filePath === '.github/PLUGIN_TEMPLATE.json' ||
+			/^\.forge\/extensions\/[^/]+\/manifest\.json$/i.test(filePath) ||
+			/^plugins\/[^/]+\/(?:plugin|extension|manifest)\.json$/i.test(filePath),
+		repairHint: 'Use the Forge extension/plugin manager so manifests and trust metadata stay consistent.',
+	},
+	{
+		id: 'lockfiles',
+		label: 'Lockfiles',
+		matches: filePath =>
+			/(^|\/)(bun\.lock|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.lock|poetry\.lock|Cargo\.lock|go\.sum)$/.test(filePath) ||
+			filePath === '.forge/extensions.lock',
+		repairHint: 'Regenerate lockfiles through the package manager or Forge extension installer instead of editing them by hand.',
+	},
+	{
+		id: 'workflows',
+		label: 'Workflow definitions',
+		matches: filePath =>
+			startsWithAny(filePath, ['.github/workflows', '.forge/hooks']) ||
+			filePath === 'lefthook.yml',
+		repairHint: 'Use Forge workflow/setup commands so workflow files and hooks remain in sync.',
+	},
+	{
+		id: 'generated_harness',
+		label: 'Generated harness files',
+		matches: filePath =>
+			startsWithAny(filePath, [
+				'.agents/skills',
+				'.claude/skills',
+				'.codex/skills',
+				'.cursor/rules',
+			]) ||
+			['AGENTS.md', 'CLAUDE.md', '.mcp.json'].includes(filePath),
+		repairHint: 'Regenerate harness files with forge setup or the owning Forge API surface instead of direct edits.',
+	},
+	{
+		id: 'memory_projection',
+		label: 'Memory projection files',
+		matches: filePath =>
+			startsWithAny(filePath, ['docs/sessions', 'docs/memory', '.forge/memory']) ||
+			filePath.endsWith('/memory.md') ||
+			filePath.endsWith('/MEMORY.md'),
+		repairHint: 'Use the Forge memory projection command or append-only session writer; do not edit projections directly.',
+	},
+];
+
+function classifyProtectedPath(filePath) {
+	const normalized = normalizeRepoPath(filePath);
+	if (!normalized) return null;
+	const surface = PROTECTED_SURFACES.find(candidate => candidate.matches(normalized));
+	if (!surface) return null;
+	return {
+		path: normalized,
+		surface: surface.id,
+		label: surface.label,
+		repairHint: surface.repairHint,
+	};
+}
+
+function resolveRepoRelativePath(projectRoot, filePath) {
+	const root = path.resolve(projectRoot);
+	const target = path.resolve(root, filePath);
+	if (!pathStaysInsideRoot(root, target)) {
+		return {
+			insideRoot: false,
+			root,
+			target,
+			relativePath: normalizeRepoPath(filePath),
+		};
+	}
+	return {
+		insideRoot: true,
+		root,
+		target,
+		relativePath: normalizeRepoPath(path.relative(root, target)),
+	};
+}
+
+function pathStaysInsideRoot(root, candidate) {
+	return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+function lstatIfPresent(candidate) {
+	try {
+		return fs.lstatSync(candidate);
+	} catch (error) {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	}
+}
+
+function nearestExistingPath(candidate) {
+	let current = candidate;
+	while (!lstatIfPresent(current)) {
+		const parent = path.dirname(current);
+		if (parent === current) return current;
+		current = parent;
+	}
+	return current;
+}
+
+function assertNoAncestorSymlinkEscape(root, target) {
+	const realRoot = fs.realpathSync(root);
+	const existing = nearestExistingPath(path.dirname(target));
+	const existingStat = lstatIfPresent(existing);
+	if (existing !== root && existingStat?.isSymbolicLink()) {
+		return {
+			allowed: false,
+			decision: 'blocked',
+			reason: `Write ancestor is a symlink: ${existing}`,
+			repairHint: 'Remove the symlink escape or write through a real directory inside the project root.',
+		};
+	}
+
+	const realExisting = fs.realpathSync(existing);
+	if (!pathStaysInsideRoot(realRoot, realExisting)) {
+		return {
+			allowed: false,
+			decision: 'blocked',
+			reason: `Write ancestor resolves outside project root: ${existing}`,
+			repairHint: 'Remove the symlink escape or write through a real directory inside the project root.',
+		};
+	}
+	return null;
+}
+
+function assertNoSymlinkEscape(root, target) {
+	const parent = path.dirname(target);
+	const realRoot = fs.realpathSync(root);
+	const existingParent = fs.existsSync(parent) ? fs.realpathSync(parent) : parent;
+	if (!pathStaysInsideRoot(realRoot, existingParent)) {
+		return {
+			allowed: false,
+			decision: 'blocked',
+			reason: `Write parent resolves outside project root: ${parent}`,
+			repairHint: 'Remove the symlink escape or write through a real directory inside the project root.',
+		};
+	}
+
+	try {
+		if (fs.lstatSync(target).isSymbolicLink()) {
+			return {
+				allowed: false,
+				decision: 'blocked',
+				reason: `Write target is a symlink: ${target}`,
+				repairHint: 'Replace the symlink with a real file through the owning Forge API before writing.',
+			};
+		}
+	} catch (error) {
+		if (error.code !== 'ENOENT') {
+			throw error;
+		}
+	}
+
+	return null;
+}
+
+function assertProtectedWriteAllowed(filePath, options = {}) {
+	const classification = classifyProtectedPath(filePath);
+	const actor = options.actor || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown';
+	const operation = options.operation || 'write';
+
+	if (!classification) {
+		return {
+			allowed: true,
+			decision: 'allowed',
+			actor,
+			path: normalizeRepoPath(filePath),
+			operation,
+			requiredSurface: null,
+			reason: 'Path is not protected.',
+			repairHint: null,
+		};
+	}
+
+	const requiredSurface = classification.surface;
+	const declaredSurface = options.surface || options.requiredSurface;
+	const allowed = Boolean(options.viaForgeApi && declaredSurface === requiredSurface);
+
+	return {
+		allowed,
+		decision: allowed ? 'allowed' : 'blocked',
+		actor,
+		path: classification.path,
+		operation,
+		requiredSurface,
+		surfaceLabel: classification.label,
+		declaredSurface: declaredSurface || null,
+		reason: allowed
+			? `Forge API write declared required surface: ${requiredSurface}.`
+			: `Direct edits to protected ${requiredSurface} paths are not allowed.`,
+		repairHint: classification.repairHint,
+	};
+}
+
+function writeProtectedFile(projectRoot, filePath, content, options = {}) {
+	const resolved = resolveRepoRelativePath(projectRoot, filePath);
+	if (!resolved.insideRoot) {
+		return {
+			allowed: false,
+			decision: 'blocked',
+			actor: options.actor || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown',
+			path: resolved.relativePath,
+			operation: options.operation || 'write',
+			requiredSurface: null,
+			reason: `Write path escapes project root: ${filePath}`,
+			repairHint: 'Write only repo-relative paths inside the project root.',
+		};
+	}
+
+	const decision = assertProtectedWriteAllowed(resolved.relativePath, {
+		...options,
+		operation: options.operation || 'write',
+	});
+	if (!decision.allowed) return decision;
+
+	const ancestorEscape = assertNoAncestorSymlinkEscape(resolved.root, resolved.target);
+	if (ancestorEscape) {
+		return {
+			...decision,
+			...ancestorEscape,
+		};
+	}
+
+	fs.mkdirSync(path.dirname(resolved.target), { recursive: true });
+	const symlinkEscape = assertNoSymlinkEscape(resolved.root, resolved.target);
+	if (symlinkEscape) {
+		return {
+			...decision,
+			...symlinkEscape,
+		};
+	}
+
+	fs.writeFileSync(resolved.target, content, options.encoding || 'utf8');
+	return { ...decision, fullPath: resolved.target };
+}
+
+function buildProtectedStateAuditEvent(decision) {
+	if (!decision || typeof decision !== 'object') {
+		throw new TypeError('Protected state decision is required');
+	}
+
+	const event = {
+		kind: 'protected_state_write',
+		actor: decision.actor || 'unknown',
+		path: decision.path,
+		decision: decision.decision,
+		requiredSurface: decision.requiredSurface,
+		declaredSurface: decision.declaredSurface || null,
+		operation: decision.operation || 'write',
+		reason: decision.reason,
+		repairHint: decision.repairHint,
+		metadata: {
+			actor: decision.actor || 'unknown',
+			path: decision.path,
+			operation: decision.operation || 'write',
+			requiredSurface: decision.requiredSurface,
+			declaredSurface: decision.declaredSurface || null,
+			decision: decision.decision,
+			reason: decision.reason,
+			repairHint: decision.repairHint,
+		},
+	};
+
+	return redact(event);
+}
+
+function recordProtectedStateAuditEvent(decision, options = {}) {
+	const event = buildProtectedStateAuditEvent(decision);
+	const runCommand = options.runCommand || execFileSync;
+	try {
+		const args = [
+			'audit',
+			'record',
+			'--json',
+			'--kind',
+			'protected_state_write',
+			'--model',
+			'forge-protected-state',
+			'--prompt',
+			JSON.stringify({
+				actor: event.actor,
+				path: event.path,
+				operation: event.operation,
+			}),
+			'--response',
+			JSON.stringify({
+				decision: event.decision,
+				requiredSurface: event.requiredSurface,
+				repairHint: event.repairHint,
+			}),
+		];
+
+		if (event.metadata) {
+			args.push('--meta-json', JSON.stringify(event.metadata));
+		}
+
+		const output = runCommand('bd', args, {
+			cwd: options.cwd || process.cwd(),
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+			timeout: options.timeoutMs || 5000,
+		});
+		return { success: true, event, output };
+	} catch (error) {
+		return { success: false, event, error: error.message };
+	}
+}
+
+module.exports = {
+	PROTECTED_SURFACES,
+	normalizeRepoPath,
+	resolveRepoRelativePath,
+	lstatIfPresent,
+	assertNoAncestorSymlinkEscape,
+	assertNoSymlinkEscape,
+	classifyProtectedPath,
+	assertProtectedWriteAllowed,
+	writeProtectedFile,
+	buildProtectedStateAuditEvent,
+	recordProtectedStateAuditEvent,
+};