archgraph-argo 0.1.0

package/argo/scripts/graph-rag/semanticReadinessAttestationStore.js

@@ -0,0 +1,398 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ATTESTATION_PATH = '.argo/temp/semantic-readiness-attestation.json';
+const SCHEMA_VERSION = '1.0';
+const ACL_REMEDIATION = 'Restrict .argo/temp and semantic-readiness-attestation.json ownership and ACLs to the current OS identity and SYSTEM, then run semantic readiness again';
+const FIELDS = Object.freeze([
+  'schemaVersion',
+  'authorizationOperation',
+  'graphPath',
+  'verified',
+  'canonicalVersion',
+  'contentVersion',
+  'indexVersion',
+  'completedChannels',
+  'missingChannels',
+  'mismatchedChannels',
+  'fullSnapshotFallback',
+  'canonicalDigest',
+  'integrityDigest',
+]);
+
+function createSemanticReadinessAttestationStore(options = {}) {
+  const repositoryRoot = path.resolve(options.repositoryRoot);
+  const graphPath = normalizeGraphPath(options.graphPath);
+  const metadataAdapter = options.metadataAdapter;
+  const attestationPath = path.join(repositoryRoot, ...ATTESTATION_PATH.split('/'));
+  const directoryPath = path.dirname(attestationPath);
+  const canonicalPath = path.join(repositoryRoot, ...graphPath.split('/'));
+
+  return Object.freeze({
+    record(readiness) {
+      const record = buildRecord(readiness, {
+        repositoryRoot,
+        graphPath,
+        canonicalPath,
+      });
+      writeAttestationAtomically(record, {
+        attestationPath,
+        directoryPath,
+        metadataAdapter,
+      });
+      return Object.freeze(record);
+    },
+
+    read() {
+      if (!fs.existsSync(attestationPath)) return null;
+      assertPathTrust(attestationPath, directoryPath);
+      let record;
+      try {
+        record = JSON.parse(fs.readFileSync(attestationPath, 'utf8'));
+      } catch {
+        throw attestationError('SEMANTIC_READINESS_ATTESTATION_INVALID');
+      }
+      assertRecord(record, repositoryRoot);
+      assertOperatingSystemTrust({
+        attestationPath,
+        directoryPath,
+        metadataAdapter,
+      });
+      if (digestFile(canonicalPath) !== record.canonicalDigest) {
+        throw attestationError('SEMANTIC_READINESS_ATTESTATION_STALE');
+      }
+      return Object.freeze(record);
+    },
+
+    clear() {
+      try {
+        fs.rmSync(attestationPath, { force: true });
+      } catch {
+        throw attestationError('SEMANTIC_READINESS_ATTESTATION_INVALID');
+      }
+    },
+
+    validate(attestation, readiness) {
+      assertOperatingSystemTrust({
+        attestationPath,
+        directoryPath,
+        metadataAdapter,
+      });
+      if (digestFile(canonicalPath) !== attestation.canonicalDigest) return false;
+      return exactReadinessMatch(attestation, readiness);
+    },
+  });
+}
+
+function buildRecord(readiness, context) {
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    authorizationOperation: 'verifyReadiness',
+    graphPath: context.graphPath,
+    verified: readiness.verified === true,
+    canonicalVersion: readiness.canonicalVersion,
+    contentVersion: readiness.contentVersion,
+    indexVersion: readiness.indexVersion,
+    completedChannels: copyChannels(readiness.completedChannels),
+    missingChannels: copyChannels(readiness.missingChannels),
+    mismatchedChannels: copyChannels(readiness.mismatchedChannels),
+    fullSnapshotFallback: false,
+    canonicalDigest: digestFile(context.canonicalPath),
+  };
+  record.integrityDigest = integrityDigest(record, context.repositoryRoot);
+  assertRecord(record, context.repositoryRoot);
+  return record;
+}
+
+function writeAttestationAtomically(readiness, context) {
+  fs.mkdirSync(context.directoryPath, { recursive: true, mode: 0o700 });
+  assertPathTrust(undefined, context.directoryPath);
+  const temporaryPath = `${context.attestationPath}.${process.pid}.${crypto.randomBytes(12).toString('hex')}.tmp`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporaryPath, 'wx', 0o600);
+    fs.writeSync(descriptor, `${JSON.stringify(readiness)}\n`, null, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporaryPath, context.attestationPath);
+    assertMetadataResult(context.metadataAdapter.readReadinessAttestationAcl());
+    assertMetadataResult(context.metadataAdapter.readReadinessAttestationOwner());
+    assertOperatingSystemTrust(context);
+    if (process.platform === 'win32') {
+      if (path.dirname(temporaryPath) !== path.dirname(context.attestationPath)) {
+        throw attestationError('ATTESTATION_RENAME_VOLUME_CHANGED');
+      }
+      recordDirectoryFlushFallback('WINDOWS_DIRECTORY_FSYNC_UNSUPPORTED_SAME_DIRECTORY_RENAME');
+    } else {
+      const directoryDescriptor = fs.openSync(path.dirname(context.attestationPath), 'r');
+      fs.fsyncSync(directoryDescriptor);
+      fs.closeSync(directoryDescriptor);
+    }
+    return readiness;
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try {
+        fs.closeSync(descriptor);
+      } catch {}
+    }
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {}
+    if (error && error.category) throw error;
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+}
+
+function assertRecord(record, repositoryRoot) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_INVALID');
+  }
+  if (
+    Object.keys(record).sort().join('\n') !== [...FIELDS].sort().join('\n')
+    || record.schemaVersion !== SCHEMA_VERSION
+    || record.authorizationOperation !== 'verifyReadiness'
+    || record.verified !== true
+    || record.fullSnapshotFallback !== false
+    || !isString(record.graphPath)
+    || !isString(record.canonicalVersion)
+    || !isString(record.contentVersion)
+    || !isString(record.indexVersion)
+    || !isString(record.canonicalDigest)
+    || !isString(record.integrityDigest)
+    || !areChannels(record.completedChannels)
+    || !areChannels(record.missingChannels)
+    || !areChannels(record.mismatchedChannels)
+    || record.integrityDigest !== integrityDigest(record, repositoryRoot)
+  ) {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_INVALID');
+  }
+}
+
+function assertPathTrust(attestationPath, directoryPath) {
+  let directory;
+  try {
+    directory = fs.lstatSync(directoryPath);
+  } catch {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  if (!directory.isDirectory() || directory.isSymbolicLink()) {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  if (!attestationPath) return;
+  let file;
+  try {
+    file = fs.lstatSync(attestationPath);
+  } catch {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  if (!file.isFile() || file.isSymbolicLink()) {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+}
+
+function assertOperatingSystemTrust(context) {
+  assertPathTrust(context.attestationPath, context.directoryPath);
+  if (process.platform === 'win32') {
+    const identity = assertCommandSucceeded(context.metadataAdapter, 'readCurrentIdentity');
+    const directoryAcl = normalizeWindowsAclEvidence(assertCommandSucceeded(
+      context.metadataAdapter,
+      'readReadinessAttestationDirectoryAcl',
+    ), context.directoryPath);
+    const fileAcl = normalizeWindowsAclEvidence(
+      assertCommandSucceeded(context.metadataAdapter, 'readReadinessAttestationAcl'),
+      context.attestationPath,
+    );
+    const owner = assertCommandSucceeded(
+      context.metadataAdapter,
+      'readReadinessAttestationOwner',
+    );
+    assertWindowsAclTrust({ identity, owner, directoryAcl, fileAcl });
+    return;
+  }
+  const file = fs.lstatSync(context.attestationPath);
+  const directory = fs.lstatSync(context.directoryPath);
+  if (
+    (file.mode & 0o077) !== 0
+    || (directory.mode & 0o077) !== 0
+    || (typeof process.getuid === 'function'
+      && (file.uid !== process.getuid() || directory.uid !== process.getuid()))
+  ) {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+}
+
+function assertCommandSucceeded(adapter, capability) {
+  if (!adapter || typeof adapter[capability] !== 'function') {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  const result = adapter[capability]();
+  if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  return result.stdout;
+}
+
+function assertMetadataResult(result) {
+  if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  }
+  return result.stdout;
+}
+
+function exactReadinessMatch(attestation, readiness) {
+  return Boolean(
+    readiness
+    && readiness.verified === true
+    && attestation.canonicalVersion === readiness.canonicalVersion
+    && attestation.contentVersion === readiness.contentVersion
+    && attestation.indexVersion === readiness.indexVersion
+    && sameArray(attestation.completedChannels, readiness.completedChannels)
+    && sameArray(attestation.missingChannels, readiness.missingChannels)
+    && sameArray(attestation.mismatchedChannels, readiness.mismatchedChannels)
+    && readiness.fullSnapshotFallback === false
+  );
+}
+
+function integrityDigest(record, repositoryRoot) {
+  const evidence = {};
+  for (const field of FIELDS) {
+    if (field !== 'integrityDigest') evidence[field] = record[field];
+  }
+  return digest(`${path.resolve(repositoryRoot)}\n${JSON.stringify(evidence)}`);
+}
+
+function digestFile(filePath) {
+  try {
+    return digest(fs.readFileSync(filePath));
+  } catch {
+    throw attestationError('SEMANTIC_READINESS_ATTESTATION_INVALID');
+  }
+}
+
+function digest(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function copyChannels(value) {
+  return Array.isArray(value) ? [...value] : [];
+}
+
+function sameArray(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function areChannels(value) {
+  return Array.isArray(value) && value.every(isString);
+}
+
+function isString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function normalizeGraphPath(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError('graphPath is required');
+  }
+  return value.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function normalizeIdentity(value) {
+  return String(value).trim().toLowerCase();
+}
+
+function normalizeWindowsAclEvidence(value, subjectPath) {
+  const lines = String(value).split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => (
+      line
+      && !/^Successfully processed \d+ files?; Failed processing \d+ files?$/i.test(line)
+      && !/\b\d+\b.*;\s*.*\b\d+\b/.test(line)
+    ));
+  if (lines.length > 0) {
+    const prefix = String(subjectPath);
+    if (lines[0].toLowerCase().startsWith(prefix.toLowerCase())) {
+      lines[0] = lines[0].slice(prefix.length).trim();
+    }
+  }
+  return lines.filter(Boolean).join('\n');
+}
+
+function parseWindowsAcl(value) {
+  const lines = String(value).split(/\r?\n/).filter(Boolean);
+  if (lines.length === 0) throw windowsTrustError();
+  return lines.map(line => {
+    const match = line.match(/^(.+?):((?:\([^)]*\))+?)$/);
+    if (!match) throw windowsTrustError();
+    const flags = Array.from(
+      match[2].matchAll(/\(([^)]*)\)/g),
+      entry => entry[1].toUpperCase(),
+    );
+    return {
+      principal: normalizeIdentity(match[1]),
+      denied: flags.includes('DENY'),
+      permissions: flags
+        .filter(flag => !['DENY', 'I', 'OI', 'CI', 'IO'].includes(flag))
+        .flatMap(flag => flag.split(',')),
+    };
+  });
+}
+
+function grantsProtectedAccess(entry) {
+  return entry.permissions.some(permission => /^(?:F|M|RX|R|W|D|DE|RC|WDAC|WO|S|AS|MA|GR|GW|GE|GA|RD|WD|AD|REA|WEA|X|DC|RA|WA)$/.test(permission));
+}
+
+function grantsRequiredIdentityAccess(entry) {
+  return entry.permissions.some(permission => permission === 'F' || permission === 'M');
+}
+
+function windowsTrustError() {
+  const error = new Error('SEMANTIC_READINESS_ATTESTATION_UNTRUSTED');
+  error.category = 'SEMANTIC_READINESS_ATTESTATION_UNTRUSTED';
+  error.fullSnapshotFallback = false;
+  error.action = ACL_REMEDIATION;
+  return error;
+}
+
+function assertWindowsAclTrust({ identity, owner, directoryAcl, fileAcl }) {
+  const current = normalizeIdentity(identity);
+  if (!current || normalizeIdentity(owner) !== current) throw windowsTrustError();
+  for (const acl of [directoryAcl, fileAcl]) {
+    const entries = parseWindowsAcl(acl);
+    const currentEntries = entries.filter(entry => entry.principal === current);
+    if (
+      !currentEntries.some(entry => !entry.denied && grantsRequiredIdentityAccess(entry))
+      || currentEntries.some(entry => entry.denied && grantsProtectedAccess(entry))
+      || entries.some(entry => (
+        !entry.denied
+        && grantsProtectedAccess(entry)
+        && entry.principal !== current
+        && entry.principal !== 'nt authority\\system'
+      ))
+    ) {
+      throw windowsTrustError();
+    }
+  }
+}
+
+function recordDirectoryFlushFallback(reason) {
+  return Object.freeze({ reason });
+}
+
+function attestationError(category) {
+  const error = new Error(category);
+  error.category = category;
+  error.fullSnapshotFallback = false;
+  error.action = category === 'SEMANTIC_READINESS_ATTESTATION_UNTRUSTED'
+    ? ACL_REMEDIATION
+    : 'Run semantic readiness verification again before semantic query';
+  return error;
+}
+
+module.exports = {
+  createSemanticReadinessAttestationStore,
+};

package/argo/scripts/graph-rag/systemMetadataCommandAdapter.js

@@ -0,0 +1,269 @@
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const {
+  getArgoEnvPath,
+} = require('../argo-paths.js');
+
+const CAPABILITY_NAMES = Object.freeze([
+  'isSecretFileIgnored',
+  'isSecretFileTracked',
+  'isSecretFileInsideGitRepository',
+  'readCurrentIdentity',
+  'readSecretFileAcl',
+]);
+
+function createSystemMetadataCommandAdapter(options = {}) {
+  requireExactKeys(options, ['repositoryRoot']);
+  const repositoryRoot = requireRepositoryRoot(options.repositoryRoot);
+  return createAdapter({
+    repositoryRoot,
+    executeMetadataCommand: spawnSync,
+    mutateInvocation: undefined,
+    forbiddenValues: [],
+  }).adapter;
+}
+
+function createReadinessAttestationMetadataAdapter(options = {}) {
+  requireExactKeys(options, ['repositoryRoot']);
+  const repositoryRoot = requireRepositoryRoot(options.repositoryRoot);
+  const file = path.join(
+    options.repositoryRoot,
+    '.argo',
+    'temp',
+    'semantic-readiness-attestation.json',
+  );
+  const directory = path.dirname(file);
+  const environment = sanitizedEnvironment();
+
+  function spawnExact(executable, args) {
+    return spawnSync(executable, args, {
+      cwd: repositoryRoot,
+      encoding: 'utf8',
+      env: { ...environment },
+      shell: false,
+      windowsHide: true,
+    });
+  }
+
+  return Object.freeze({
+    readCurrentIdentity: () => spawnExact('whoami', []),
+    readReadinessAttestationDirectoryAcl: () => spawnExact('icacls', [directory]),
+    readReadinessAttestationAcl: () => spawnExact('icacls', [file]),
+    readReadinessAttestationOwner: () => spawnExact('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      exactOwnerScript(file),
+    ]),
+  });
+}
+
+function exactOwnerScript(file) {
+  const literalPath = String(file).replace(/'/g, "''");
+  return `(Get-Acl -LiteralPath '${literalPath}').Owner`;
+}
+
+function sanitizedEnvironment() {
+  return Object.freeze(Object.fromEntries(
+    ['PATH', 'Path', 'PATHEXT', 'SystemRoot', 'WINDIR']
+      .filter(key => typeof process.env[key] === 'string')
+      .map(key => [key, process.env[key]]),
+  ));
+}
+
+function withSystemMetadataCommandTestComposition(options = {}, callback) {
+  requireExactKeys(options, [
+    'executeMetadataCommand',
+    'forbiddenValues',
+    'mutateInvocation',
+    'repositoryRoot',
+  ], true);
+  if (typeof options.executeMetadataCommand !== 'function' || typeof callback !== 'function') {
+    throw prohibited();
+  }
+  const composition = createAdapter({
+    repositoryRoot: requireRepositoryRoot(options.repositoryRoot),
+    executeMetadataCommand: options.executeMetadataCommand,
+    mutateInvocation: options.mutateInvocation,
+    forbiddenValues: Array.isArray(options.forbiddenValues) ? [...options.forbiddenValues] : [],
+  });
+  let result;
+  let then;
+  let asyncRevocationOwner = false;
+  try {
+    result = callback(composition.adapter);
+    if (
+      result !== null
+      && (typeof result === 'object' || typeof result === 'function')
+    ) {
+      then = result.then;
+    }
+    if (typeof then === 'function') {
+      asyncRevocationOwner = true;
+      return assimilateThenable(result, then, composition.revoke);
+    }
+    return undefined;
+  } finally {
+    if (!asyncRevocationOwner) composition.revoke();
+  }
+}
+
+async function assimilateThenable(value, then, revoke) {
+  try {
+    await new Promise((resolve, reject) => {
+      then.call(value, resolve, reject);
+    });
+    return undefined;
+  } finally {
+    revoke();
+  }
+}
+
+function createAdapter({
+  repositoryRoot,
+  executeMetadataCommand,
+  mutateInvocation,
+  forbiddenValues,
+}) {
+  const canonicalPath = getArgoEnvPath();
+  const gitDirectory = path.dirname(canonicalPath);
+  const sanitizedEnvironment = Object.freeze(Object.fromEntries(
+    ['PATH', 'PATHEXT', 'SystemRoot', 'WINDIR']
+      .filter(key => typeof process.env[key] === 'string')
+      .map(key => [key, process.env[key]]),
+  ));
+  let revoked = false;
+
+  function invoke(capabilityName, receivedArguments) {
+    if (revoked) {
+      const error = new Error('TEST_SYSTEM_METADATA_ADAPTER_REVOKED');
+      error.category = 'TEST_SYSTEM_METADATA_ADAPTER_REVOKED';
+      throw error;
+    }
+    if (receivedArguments.length !== 0) throw prohibited();
+    const expected = buildInvocation(
+      capabilityName,
+      gitDirectory,
+      canonicalPath,
+      sanitizedEnvironment,
+    );
+    const candidate = typeof mutateInvocation === 'function'
+      ? mutateInvocation(cloneInvocation(expected))
+      : expected;
+    validateInvocation(candidate, expected, forbiddenValues);
+    return executeMetadataCommand(
+      candidate.executable,
+      [...candidate.args],
+      cloneOptions(candidate.options),
+    );
+  }
+
+  const adapter = Object.create(null);
+  for (const capabilityName of CAPABILITY_NAMES) {
+    const capability = capabilityName === 'isSecretFileIgnored'
+      ? (...args) => invoke(capabilityName, args).status === 0
+      : capabilityName === 'isSecretFileTracked'
+        ? (...args) => invoke(capabilityName, args).status === 0
+        : (...args) => {
+          const result = invoke(capabilityName, args);
+          return {
+            status: result.status,
+            stdout: typeof result.stdout === 'string' ? result.stdout : '',
+          };
+        };
+    Object.freeze(capability);
+    Object.defineProperty(adapter, capabilityName, {
+      value: capability,
+      enumerable: true,
+      writable: false,
+      configurable: false,
+    });
+  }
+  Object.freeze(adapter);
+  return {
+    adapter,
+    revoke() {
+      revoked = true;
+    },
+  };
+}
+
+function buildInvocation(capabilityName, gitDirectory, canonicalPath, environment) {
+  const templates = {
+    isSecretFileInsideGitRepository: ['git', ['rev-parse', '--is-inside-work-tree']],
+    isSecretFileIgnored: ['git', ['check-ignore', '--quiet', '--', '.env']],
+    isSecretFileTracked: ['git', ['ls-files', '--error-unmatch', '--', '.env']],
+    readCurrentIdentity: ['whoami', []],
+    readSecretFileAcl: ['icacls', [canonicalPath]],
+  };
+  const template = templates[capabilityName];
+  if (!template) throw prohibited();
+  return {
+    executable: template[0],
+    args: [...template[1]],
+    options: {
+      cwd: gitDirectory,
+      encoding: 'utf8',
+      env: { ...environment },
+      shell: false,
+      windowsHide: true,
+    },
+  };
+}
+
+function validateInvocation(candidate, expected, forbiddenValues) {
+  if (!candidate || typeof candidate !== 'object') throw prohibited();
+  if (JSON.stringify(candidate) !== JSON.stringify(expected)) throw prohibited();
+  const serialized = JSON.stringify(candidate);
+  for (const forbiddenValue of forbiddenValues) {
+    if (typeof forbiddenValue === 'string' && forbiddenValue && serialized.includes(forbiddenValue)) {
+      throw prohibited();
+    }
+  }
+}
+
+function cloneInvocation(invocation) {
+  return {
+    executable: invocation.executable,
+    args: [...invocation.args],
+    options: cloneOptions(invocation.options),
+  };
+}
+
+function cloneOptions(options) {
+  return {
+    cwd: options.cwd,
+    encoding: options.encoding,
+    env: { ...options.env },
+    shell: options.shell,
+    windowsHide: options.windowsHide,
+  };
+}
+
+function requireExactKeys(value, allowedKeys, optional = false) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw prohibited();
+  const actual = Object.keys(value).sort();
+  const allowed = [...allowedKeys].sort();
+  if (actual.some(key => !allowed.includes(key))) throw prohibited();
+  if (!optional && (actual.length !== allowed.length || actual.some((key, index) => key !== allowed[index]))) {
+    throw prohibited();
+  }
+}
+
+function requireRepositoryRoot(value) {
+  if (typeof value !== 'string' || value.trim() === '') throw prohibited();
+  return path.resolve(value);
+}
+
+function prohibited() {
+  const error = new Error('SYSTEM_METADATA_COMMAND_PROHIBITED');
+  error.category = 'SYSTEM_METADATA_COMMAND_PROHIBITED';
+  return error;
+}
+
+module.exports = {
+  createReadinessAttestationMetadataAdapter,
+  createSystemMetadataCommandAdapter,
+  withSystemMetadataCommandTestComposition,
+};