@thebackstoryis/engineering-with-ai 0.2.9

package/src/salesforce-source-map.mjs

@@ -0,0 +1,212 @@
+import { basename } from 'node:path';
+import {
+  PlatformAnalysisError,
+  assertBoundedPlatformStructure,
+  createPlatformFactCollector,
+  normalisePlatformIdentifier,
+  normalisePlatformPathIdentifier,
+  parseSafePlatformXml,
+  platformBoolean,
+  platformFactsFile,
+  xmlChildText,
+  xmlChildren,
+  xmlDescendants
+} from './platform-metadata-analysis.mjs';
+
+const parser = 'ewai-salesforce-metadata/v1';
+
+function normalPath(path) {
+  return String(path ?? '').replaceAll('\\', '/').replace(/^\.\//, '');
+}
+
+function stem(path, suffix) {
+  return basename(path).slice(0, -suffix.length);
+}
+
+function analysePackage(path, content) {
+  const root = parseSafePlatformXml(content);
+  if (root.name.toLowerCase() !== 'package') throw new PlatformAnalysisError('unsupported-platform-layout');
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout: 'metadata-package-xml' });
+  const packageName = 'package';
+  collector.addSymbol('salesforce_package', packageName);
+  for (const type of xmlChildren(root, 'types')) {
+    const typeName = normalisePlatformIdentifier(xmlChildText(type, 'name'));
+    if (!typeName) {
+      collector.markPartial();
+      continue;
+    }
+    for (const member of xmlChildren(type, 'members')) {
+      const memberName = normalisePlatformIdentifier(member.text);
+      if (!memberName) continue;
+      const componentName = `${typeName}:${memberName}`;
+      collector.addSymbol('salesforce_component', componentName, { component_type: typeName });
+      collector.addRelationship('salesforce_package', packageName, 'contains', 'salesforce_component', componentName);
+    }
+  }
+  return platformFactsFile(collector.finish({ format_version: xmlChildText(root, 'version') }), {
+    language: 'xml', parser, content
+  });
+}
+
+function analyseProject(content) {
+  let value;
+  try {
+    value = JSON.parse(String(content ?? '').replace(/^\uFEFF/, ''));
+    assertBoundedPlatformStructure(value);
+  } catch (error) {
+    if (error instanceof PlatformAnalysisError) throw error;
+    throw new PlatformAnalysisError('invalid-platform-document');
+  }
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout: 'sfdx-project-json' });
+  collector.addSymbol('salesforce_project', 'sfdx-project');
+  for (const entry of Array.isArray(value.packageDirectories) ? value.packageDirectories : []) {
+    const directory = normalisePlatformPathIdentifier(entry?.path);
+    if (!directory) {
+      collector.markPartial(1);
+      continue;
+    }
+    collector.addSymbol('salesforce_package_directory', directory);
+    collector.addRelationship('salesforce_project', 'sfdx-project', 'contains', 'salesforce_package_directory', directory);
+  }
+  return platformFactsFile(collector.finish(), { language: 'json', parser, content });
+}
+
+function analyseObject(path, content) {
+  parseSafePlatformXml(content);
+  const object = normalPath(path).match(/(?:^|\/)objects\/([^/]+)\/[^/]+\.object-meta\.xml$/i)?.[1];
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout: 'decomposed-custom-object' });
+  if (object) collector.addSymbol('salesforce_object', object);
+  else collector.markPartial();
+  return platformFactsFile(collector.finish(), { language: 'xml', parser, content });
+}
+
+function analyseField(path, content) {
+  const root = parseSafePlatformXml(content);
+  const match = normalPath(path).match(/(?:^|\/)objects\/([^/]+)\/fields\/([^/]+)\.field-meta\.xml$/i);
+  const object = normalisePlatformIdentifier(match?.[1]);
+  const field = normalisePlatformIdentifier(xmlChildText(root, 'fullName') || match?.[2]);
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout: 'decomposed-custom-field' });
+  if (object && field) {
+    const qualified = field.includes('.') ? field : `${object}.${field}`;
+    collector.addSymbol('salesforce_object', object);
+    collector.addSymbol('salesforce_field', qualified);
+    collector.addRelationship('salesforce_object', object, 'contains', 'salesforce_field', qualified);
+  } else collector.markPartial();
+  return platformFactsFile(collector.finish(), { language: 'xml', parser, content });
+}
+
+function booleanMetadata(node, fields) {
+  const metadata = {};
+  for (const [xml, output] of fields) {
+    const parsed = platformBoolean(xmlChildText(node, xml));
+    if (parsed !== null) metadata[output] = parsed;
+  }
+  return metadata;
+}
+
+function analysePermissions(path, content, layout, kind, suffix) {
+  const root = parseSafePlatformXml(content);
+  const name = normalisePlatformIdentifier(stem(path, suffix));
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout });
+  if (!name) collector.markPartial();
+  else collector.addSymbol(kind, name);
+
+  const addAccess = (element, targetElement, targetKind, relationshipKind, metadata = {}) => {
+    const target = normalisePlatformIdentifier(xmlChildText(element, targetElement));
+    if (!name || !target) return;
+    collector.addSymbol(targetKind, target);
+    collector.addRelationship(kind, name, relationshipKind, targetKind, target, metadata);
+  };
+  for (const item of xmlDescendants(root, 'objectPermissions')) {
+    addAccess(item, 'object', 'salesforce_object', 'object_permission', booleanMetadata(item, [
+      ['allowCreate', 'allow_create'], ['allowDelete', 'allow_delete'], ['allowEdit', 'allow_edit'],
+      ['allowRead', 'allow_read'], ['modifyAllRecords', 'modify_all_records'], ['viewAllRecords', 'view_all_records']
+    ]));
+  }
+  for (const item of xmlDescendants(root, 'fieldPermissions')) {
+    addAccess(item, 'field', 'salesforce_field', 'field_permission', booleanMetadata(item, [
+      ['editable', 'editable'], ['readable', 'readable']
+    ]));
+  }
+  for (const item of xmlDescendants(root, 'classAccesses')) {
+    addAccess(item, 'apexClass', 'salesforce_apex_class', 'apex_class_access', booleanMetadata(item, [['enabled', 'enabled']]));
+  }
+  for (const item of xmlDescendants(root, 'applicationVisibilities')) {
+    addAccess(item, 'application', 'salesforce_application', 'application_visibility', booleanMetadata(item, [['visible', 'visible']]));
+  }
+  for (const item of xmlDescendants(root, 'tabSettings')) {
+    addAccess(item, 'tab', 'salesforce_tab', 'tab_visibility', { visibility: xmlChildText(item, 'visibility') });
+  }
+  return platformFactsFile(collector.finish(), { language: 'xml', parser, content });
+}
+
+function analyseFlow(path, content) {
+  const root = parseSafePlatformXml(content);
+  const name = normalisePlatformIdentifier(stem(path, '.flow-meta.xml'));
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout: 'flow-metadata' });
+  if (name) collector.addSymbol('salesforce_flow', name);
+  else collector.markPartial();
+  for (const [element, relationship] of [
+    ['recordCreates', 'creates_records'],
+    ['recordLookups', 'reads_records'],
+    ['recordUpdates', 'updates_records'],
+    ['recordDeletes', 'deletes_records']
+  ]) {
+    for (const operation of xmlDescendants(root, element)) {
+      const object = normalisePlatformIdentifier(xmlChildText(operation, 'object'));
+      if (!name || !object) continue;
+      collector.addSymbol('salesforce_object', object);
+      collector.addRelationship('salesforce_flow', name, relationship, 'salesforce_object', object);
+    }
+  }
+  return platformFactsFile(collector.finish(), { language: 'xml', parser, content });
+}
+
+function analyseCompanion(path, content) {
+  parseSafePlatformXml(content);
+  const value = normalPath(path);
+  let kind = '';
+  let name = '';
+  let layout = '';
+  const apex = value.match(/(?:^|\/)classes\/([^/]+)\.cls-meta\.xml$/i);
+  const lightning = value.match(/(?:^|\/)(lwc|aura)\/([^/]+)\/[^/]+\.(?:js|cmp|app|evt)-meta\.xml$/i);
+  if (apex) {
+    kind = 'salesforce_apex_class';
+    name = apex[1];
+    layout = 'apex-companion';
+  } else if (lightning) {
+    kind = lightning[1].toLowerCase() === 'lwc' ? 'salesforce_lwc' : 'salesforce_aura';
+    name = lightning[2];
+    layout = 'lightning-companion';
+  }
+  if (!kind || !name) throw new PlatformAnalysisError('unsupported-platform-layout');
+  const collector = createPlatformFactCollector({ platform: 'salesforce', layout });
+  collector.addSymbol(kind, name);
+  return platformFactsFile(collector.finish(), { language: 'xml', parser, content });
+}
+
+export function salesforceLayout(path) {
+  const value = normalPath(path).toLowerCase();
+  if (/(?:^|\/)(?:manifest\/|unpackaged\/)?package\.xml$/.test(value)) return 'metadata-package-xml';
+  if (/(?:^|\/)sfdx-project\.json$/.test(value)) return 'sfdx-project-json';
+  if (/\.object-meta\.xml$/.test(value)) return 'decomposed-custom-object';
+  if (/\.field-meta\.xml$/.test(value)) return 'decomposed-custom-field';
+  if (/\.permissionset-meta\.xml$/.test(value)) return 'permission-set-metadata';
+  if (/\.profile-meta\.xml$/.test(value)) return 'profile-metadata';
+  if (/\.flow-meta\.xml$/.test(value)) return 'flow-metadata';
+  if (/\.cls-meta\.xml$/.test(value) || /(?:^|\/)(?:lwc|aura)\/[^/]+\/[^/]+\.(?:js|cmp|app|evt)-meta\.xml$/.test(value)) return 'component-companion';
+  return '';
+}
+
+export function analyseSalesforceMetadata(path, content) {
+  const layout = salesforceLayout(path);
+  if (layout === 'metadata-package-xml') return analysePackage(path, content);
+  if (layout === 'sfdx-project-json') return analyseProject(content);
+  if (layout === 'decomposed-custom-object') return analyseObject(path, content);
+  if (layout === 'decomposed-custom-field') return analyseField(path, content);
+  if (layout === 'permission-set-metadata') return analysePermissions(path, content, layout, 'salesforce_permission_set', '.permissionset-meta.xml');
+  if (layout === 'profile-metadata') return analysePermissions(path, content, layout, 'salesforce_profile', '.profile-meta.xml');
+  if (layout === 'flow-metadata') return analyseFlow(path, content);
+  if (layout === 'component-companion') return analyseCompanion(path, content);
+  throw new PlatformAnalysisError('unsupported-platform-layout');
+}

package/src/security-validation-config.mjs

@@ -0,0 +1,224 @@
+import { isAbsolute } from 'node:path';
+
+export const ASSURANCE_NOTICE = 'Security validation is evidence, not certification or proof that this system is secure. Tools can miss vulnerabilities and produce false positives. A qualified human must review the scope, findings, limitations and residual risk before release.';
+
+export const SECURITY_CAPABILITIES = Object.freeze([
+  'source-static',
+  'dependency-sbom',
+  'secret-detection',
+  'infrastructure-configuration',
+  'llm-runtime-red-team',
+]);
+
+export const SECURITY_INTERACTION_MODES = Object.freeze(['command', 'skill', 'artifact-import']);
+
+export const SECURITY_PROVIDER_CATALOGUE = Object.freeze([
+  Object.freeze({
+    id: 'agentic-security',
+    name: 'Agentic Security',
+    publisher: 'Clear Capabilities',
+    official_sources: Object.freeze(['https://github.com/Clear-Capabilities/agentic-security']),
+    capabilities: Object.freeze([...SECURITY_CAPABILITIES]),
+    artifact_import_supported: true,
+    summary: 'Security analysis across source, dependencies, secrets, infrastructure, agent and LLM surfaces, with reporting and remediation workflows.',
+    cautions: Object.freeze([
+      'EWAI does not install, redistribute, license or endorse this provider.',
+      'Review the provider licence before repackaging, resale or use in a competing scanner.',
+      'Automated findings can be incomplete or false positive and require qualified human review.',
+    ]),
+    discovery: Object.freeze({ root: '.agentic-security', signals: Object.freeze(['findings.json', 'last-scan.json']) }),
+  }),
+  Object.freeze({
+    id: 'deepsec',
+    name: 'DeepSec',
+    publisher: 'Vercel Labs',
+    official_sources: Object.freeze([
+      'https://github.com/vercel-labs/deepsec',
+      'https://www.npmjs.com/package/deepsec',
+    ]),
+    capabilities: Object.freeze(['source-static', 'secret-detection']),
+    artifact_import_supported: true,
+    summary: 'Agent-powered source vulnerability investigation with resumable scans, revalidation, diff review and Markdown or JSON reporting.',
+    cautions: Object.freeze([
+      'EWAI does not install, configure, license or endorse this provider.',
+      'Model use can be expensive on large repositories and the tool should be trusted like a coding agent with shell access.',
+      'Optional sandbox execution can upload a working-tree archive; review data handling before use.',
+    ]),
+    discovery: Object.freeze({ root: '.deepsec', signals: Object.freeze(['report.json', 'run.json', 'runs', 'reports']) }),
+  }),
+  Object.freeze({
+    id: 'visa-vvah',
+    name: 'Visa Vulnerability Agentic Harness (VVAH)',
+    publisher: 'Visa',
+    official_sources: Object.freeze(['https://github.com/visa/visa-vulnerability-agentic-harness']),
+    capabilities: Object.freeze(['source-static']),
+    artifact_import_supported: false,
+    summary: 'Threat-modelled agentic source vulnerability discovery and structured reporting, with optional upstream remediation and validation stages.',
+    cautions: Object.freeze([
+      'EWAI does not install, invoke, redistribute, license or endorse this provider.',
+      'Use detection-only mode with vvaharness scan --repo <path> --stop-after s9; the upstream default can continue into remediation and edit target source.',
+      'VVAH can send source-derived prompt data to configured model providers, uses elevated local privileges, can be token-intensive and produces nondeterministic triage candidates requiring qualified human review.',
+      'Native VVAH artefact import is not supported; use the revision-bound skill handoff and an organisation-controlled translator to ewai.security-scan-response/v1.',
+    ]),
+    discovery: Object.freeze({ root: '.', signals: Object.freeze(['security-scan', 'run_manifest.json']) }),
+  }),
+]);
+
+const configFields = new Set(['enabled', 'profiles']);
+const profileFields = new Set([
+  'id', 'capability', 'required', 'freshness_hours', 'timeout_seconds', 'accountable_role',
+  'modes', 'provider', 'adapter', 'checkpoint', 'thresholds', 'scope', 'target_class', 'target_ref',
+]);
+const profileIdPattern = /^[a-z][a-z0-9-]{1,63}$/;
+const adapterIdPattern = /^[a-z][a-z0-9.-]{1,79}$/;
+const thresholdFields = new Set(['blocking_severities']);
+const scopeFields = new Set(['include', 'exclude']);
+const securitySeverities = Object.freeze(['critical', 'high', 'medium', 'low', 'info', 'unknown']);
+const targetClasses = new Set(['local', 'development', 'test', 'staging', 'production']);
+
+function credentialShaped(value) {
+  return /(?:Bearer\s+[A-Za-z0-9._~+\/-]{12,}|sk-[A-Za-z0-9_-]{16,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/i.test(String(value ?? ''));
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+}
+
+function rejectUnknown(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function boundedInteger(value, label, minimum, maximum, fallback) {
+  const selected = value === undefined ? fallback : value;
+  if (!Number.isInteger(selected) || selected < minimum || selected > maximum) {
+    throw new Error(`${label} must be an integer between ${minimum} and ${maximum}.`);
+  }
+  return selected;
+}
+
+function normaliseThresholds(value) {
+  if (value === undefined) return { blocking_severities: ['critical', 'high'] };
+  assertObject(value, 'Security profile thresholds');
+  rejectUnknown(value, thresholdFields, 'Security profile thresholds');
+  const severities = value.blocking_severities ?? ['critical', 'high'];
+  if (!Array.isArray(severities) || !severities.length || severities.length > securitySeverities.length) {
+    throw new Error('Security profile blocking_severities must be a non-empty severity array.');
+  }
+  const normalised = severities.map((severity) => String(severity).trim().toLowerCase());
+  if (new Set(normalised).size !== normalised.length || normalised.some((severity) => !securitySeverities.includes(severity))) {
+    throw new Error('Security profile blocking_severities contains a duplicate or unsupported severity.');
+  }
+  return { blocking_severities: normalised };
+}
+
+function normaliseScopeList(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 100) throw new Error(`${label} must be an array of at most 100 project-relative paths.`);
+  const seen = new Set();
+  return value.map((candidate) => {
+    const path = String(candidate ?? '').trim().replaceAll('\\', '/');
+    if (!path || path.length > 240 || credentialShaped(path) || isAbsolute(path) || path === '..' || path.startsWith('../') || path.includes('/../')) {
+      throw new Error(`${label} must contain safe project-relative paths.`);
+    }
+    if (seen.has(path)) throw new Error(`${label} contains a duplicate path: ${path}`);
+    seen.add(path);
+    return path;
+  });
+}
+
+function normaliseScope(value) {
+  if (value === undefined) return { include: [], exclude: [] };
+  assertObject(value, 'Security profile scope');
+  rejectUnknown(value, scopeFields, 'Security profile scope');
+  return {
+    include: normaliseScopeList(value.include, 'Security profile scope.include'),
+    exclude: normaliseScopeList(value.exclude, 'Security profile scope.exclude'),
+  };
+}
+
+function normaliseProfile(profile, seen) {
+  assertObject(profile, 'Security profile');
+  rejectUnknown(profile, profileFields, 'Security profile');
+  const id = String(profile.id ?? '').trim();
+  if (!profileIdPattern.test(id)) throw new Error('Security profile id must be lower-kebab-case and 2-64 characters.');
+  if (seen.has(id)) throw new Error(`Duplicate profile id: ${id}`);
+  seen.add(id);
+  const capability = String(profile.capability ?? '').trim();
+  if (!SECURITY_CAPABILITIES.includes(capability)) throw new Error(`Unsupported security capability: ${capability || '(empty)'}`);
+  const required = profile.required !== false;
+  const accountableRole = String(profile.accountable_role ?? '').trim();
+  if (!accountableRole || accountableRole.length > 120 || credentialShaped(accountableRole)) throw new Error(`Security profile ${id} requires a bounded accountable_role.`);
+  if (required && profile.freshness_hours === undefined) throw new Error(`Required security profile ${id} requires freshness_hours.`);
+  const freshnessHours = boundedInteger(profile.freshness_hours, `${id}.freshness_hours`, 1, 8760, 168);
+  const timeoutSeconds = boundedInteger(profile.timeout_seconds, `${id}.timeout_seconds`, 1, 3600, 300);
+  const modes = profile.modes === undefined ? [...SECURITY_INTERACTION_MODES] : profile.modes;
+  if (!Array.isArray(modes) || !modes.length || modes.some((mode) => !SECURITY_INTERACTION_MODES.includes(mode))) {
+    throw new Error(`Security profile ${id} modes must contain supported interaction modes.`);
+  }
+  if (new Set(modes).size !== modes.length) throw new Error(`Security profile ${id} contains duplicate interaction modes.`);
+  const provider = String(profile.provider ?? '').trim();
+  if (profile.provider !== undefined && !provider) throw new Error(`Security profile ${id} provider is invalid.`);
+  if (provider && !SECURITY_PROVIDER_CATALOGUE.some((candidate) => candidate.id === provider)) {
+    throw new Error(`Unknown security provider: ${provider}`);
+  }
+  const providerDefinition = provider ? securityProvider(provider) : null;
+  if (providerDefinition?.artifact_import_supported === false && modes.includes('artifact-import')) {
+    throw new Error(`${providerDefinition.name} does not support native artefact import; use a skill handoff.`);
+  }
+  const adapter = profile.adapter ? String(profile.adapter).trim() : '';
+  if (profile.adapter !== undefined && !adapter) throw new Error(`Security profile ${id} adapter identity is invalid.`);
+  if (adapter && !adapterIdPattern.test(adapter)) throw new Error(`Security profile ${id} adapter identity is invalid.`);
+  const checkpoint = String(profile.checkpoint ?? 'release').trim();
+  if (!checkpoint || checkpoint.length > 80) throw new Error(`Security profile ${id} checkpoint is invalid.`);
+  const targetClass = profile.target_class ? String(profile.target_class).trim() : '';
+  if (profile.target_class !== undefined && !targetClass) throw new Error(`Security profile ${id} target_class is invalid.`);
+  if (targetClass && !targetClasses.has(targetClass)) throw new Error(`Security profile ${id} target_class is invalid.`);
+  const targetRef = profile.target_ref ? String(profile.target_ref).trim() : '';
+  if (profile.target_ref !== undefined && !targetRef) throw new Error(`Security profile ${id} target_ref is invalid.`);
+  if (targetRef.length > 160 || credentialShaped(targetRef)) throw new Error(`Security profile ${id} target_ref is unsafe.`);
+  return {
+    id,
+    capability,
+    required,
+    freshness_hours: freshnessHours,
+    timeout_seconds: timeoutSeconds,
+    accountable_role: accountableRole,
+    modes: [...modes],
+    provider: provider || null,
+    adapter: adapter || null,
+    checkpoint,
+    thresholds: normaliseThresholds(profile.thresholds),
+    scope: normaliseScope(profile.scope),
+    target_class: targetClass || null,
+    target_ref: targetRef || null,
+  };
+}
+
+export function normaliseSecurityValidationConfig(config = {}) {
+  assertObject(config, 'Project configuration');
+  const raw = config.security_validation;
+  if (raw === undefined || raw === null || raw === false) {
+    return { schema: 'ewai.security-policy/v1', status: 'not-configured', enabled: false, profiles: [], assurance_notice: ASSURANCE_NOTICE };
+  }
+  assertObject(raw, 'security_validation');
+  rejectUnknown(raw, configFields, 'security_validation');
+  if (raw.enabled === false) {
+    return { schema: 'ewai.security-policy/v1', status: 'not-configured', enabled: false, profiles: [], assurance_notice: ASSURANCE_NOTICE };
+  }
+  if (raw.enabled !== true) throw new Error('security_validation.enabled must be true or false.');
+  if (!Array.isArray(raw.profiles) || !raw.profiles.length) throw new Error('Enabled security validation requires at least one profile.');
+  const seen = new Set();
+  return {
+    schema: 'ewai.security-policy/v1',
+    status: 'configured',
+    enabled: true,
+    profiles: raw.profiles.map((profile) => normaliseProfile(profile, seen)),
+    assurance_notice: ASSURANCE_NOTICE,
+  };
+}
+
+export function securityProvider(providerId) {
+  return SECURITY_PROVIDER_CATALOGUE.find((provider) => provider.id === providerId) ?? null;
+}