@saiteja1123/mcp-server 1.1.4 → 1.1.5

package/src/deep-scan/test-plan.js

@@ -0,0 +1,760 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { createArtifactRef, validateRunIdSegment } from './contracts.js';
+import { assertSourceSafePayload, cloneSourceSafe, findRawSourceField } from './sourceSafe.js';
+
+export const SECURITY_TEST_PLAN_SCHEMA_VERSION = 'security_test_plan.v1';
+export const SECURITY_TEST_PLAN_STEPPER_ID = 'tests.plan';
+export const SECURITY_TEST_PLAN_STEPPER_VERSION = '1.0.0';
+export const SECURITY_TEST_PLAN_STATUSES = Object.freeze(['planned', 'runnable', 'blocked', 'manual']);
+export const SECURITY_TEST_PLAN_STATUS_SEMANTICS = Object.freeze({
+  planned: 'Evidence-linked candidate that still needs a human or agent to create or identify a local test harness.',
+  runnable: 'Existing local test command or harness signal was discovered; Vibesecur has not generated or executed a test.',
+  blocked: 'Candidate cannot run until the missing local harness, environment, or dependency is supplied.',
+  manual: 'Candidate requires human local review because credentials, session context, or secret values must stay outside artifacts.',
+});
+export const SECURITY_TEST_PLAN_STABLE_CANDIDATE_FIELDS = Object.freeze([
+  'id',
+  'title',
+  'category',
+  'status',
+  'priority',
+  'evidence',
+  'sourceArtifactRefs',
+  'sourceFindingIds',
+  'suggestedCommand',
+  'blockedReason',
+  'manualReason',
+  'rank',
+  'dedupeKey',
+]);
+
+const nowIso = () => new Date().toISOString();
+const SHA256 = /^[a-f0-9]{64}$/i;
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+const TEST_PLAN_FILE = 'security-test-plan.json';
+
+const SEVERITY_WEIGHT = Object.freeze({
+  critical: 400,
+  high: 300,
+  medium: 200,
+  low: 100,
+});
+
+const STATUS_WEIGHT = Object.freeze({
+  runnable: 40,
+  planned: 30,
+  manual: 20,
+  blocked: 10,
+});
+
+const LOCAL_TEST_COMMAND_PATTERNS = Object.freeze([
+  /\bnode\s+--test\b/i,
+  /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b/i,
+  /\b(?:vitest|jest|mocha|ava|tap|c8)\b/i,
+  /\bplaywright\s+test\b/i,
+  /\bcypress\s+run\b/i,
+  /\bpytest\b/i,
+  /\bpython3?\s+-m\s+pytest\b/i,
+  /\bgo\s+test\b/i,
+  /\bcargo\s+test\b/i,
+  /\b(?:mvn|gradle)\s+test\b/i,
+  /\brspec\b/i,
+  /\bphpunit\b/i,
+  /\bdotnet\s+test\b/i,
+]);
+
+const FINDING_CATEGORY_MAP = [
+  [/secret|credential|password|token|key|jwt/i, 'secrets_config'],
+  [/sql|injection|command|subprocess|eval/i, 'injection'],
+  [/xss|html|script/i, 'input_validation_xss'],
+  [/ssrf|request|fetch|metadata/i, 'ssrf'],
+  [/path|traversal|file/i, 'path_traversal'],
+  [/cors|rate|auth|admin|payment|billing/i, 'api_abuse'],
+];
+
+function stableSort(value) {
+  if (Array.isArray(value)) return value.map(stableSort);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = stableSort(value[key]);
+      return acc;
+    }, {});
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableSort(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function requireString(value, name, { max = 500, pattern = null } = {}) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  if (value.length > max) throw new Error(`${name} must be ${max} characters or fewer`);
+  if (pattern && !pattern.test(value)) throw new Error(`${name} has an invalid format`);
+  return value;
+}
+
+function optionalString(value, name, options) {
+  if (value === undefined || value === null) return undefined;
+  return requireString(value, name, options);
+}
+
+function requireIsoDate(value, name) {
+  requireString(value, name, { max: 40 });
+  if (Number.isNaN(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+}
+
+function asArray(value, name) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+}
+
+function asObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value;
+}
+
+function safeText(value, fallback, max = 240) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+  if (!text) return fallback;
+  if (findRawSourceField(text, 'testPlan.text')) return fallback;
+  return text;
+}
+
+function safeIdSegment(value, fallback = 'item') {
+  const token = String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_.:-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 80);
+  return token || fallback;
+}
+
+function isRecognizedLocalTestCommand(command) {
+  const normalized = String(command || '').trim();
+  if (!normalized || /\[redacted\]/i.test(normalized)) return false;
+  return LOCAL_TEST_COMMAND_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function firstRunnableCommand(projectMap = {}) {
+  const command = (projectMap.testCommands || [])
+    .find((item) => typeof item?.command === 'string' && isRecognizedLocalTestCommand(item.command));
+  return command?.command;
+}
+
+function mapFindingCategory(finding = {}) {
+  const haystack = [
+    finding.category,
+    finding.ruleId,
+    finding.ruleName,
+    finding.title,
+  ].filter(Boolean).join(' ');
+  const mapped = FINDING_CATEGORY_MAP.find(([pattern]) => pattern.test(haystack));
+  return mapped ? mapped[1] : safeIdSegment(finding.category || 'security_regression', 'security_regression');
+}
+
+function normalizeRisk(value) {
+  const risk = safeIdSegment(value || 'medium', 'medium');
+  return SEVERITY_WEIGHT[risk] ? risk : 'medium';
+}
+
+function makeEvidence({ type, label, sourceArtifactRef, preview, summary, metadata = {} }) {
+  const evidence = {
+    type: requireString(type, 'evidence.type', { max: 80, pattern: UUIDISH }),
+    label: requireString(label, 'evidence.label', { max: 180 }),
+    sourceArtifactRef: requireString(sourceArtifactRef, 'evidence.sourceArtifactRef', { max: 160, pattern: UUIDISH }),
+    preview: optionalString(preview, 'evidence.preview', { max: 300 }),
+    summary: optionalString(summary, 'evidence.summary', { max: 500 }),
+    metadata: cloneSourceSafe(metadata, 'testPlan.evidence.metadata'),
+  };
+  assertSourceSafePayload(evidence, 'testPlan.evidence');
+  return evidence;
+}
+
+function candidateId(dedupeKey) {
+  return `test-${sha256(dedupeKey).slice(0, 16)}`;
+}
+
+function defaultStatusSemantics() {
+  return { ...SECURITY_TEST_PLAN_STATUS_SEMANTICS };
+}
+
+function defaultDownstreamContract() {
+  return {
+    schemaVersion: SECURITY_TEST_PLAN_SCHEMA_VERSION,
+    consumerIntent: 'Ralph tasks, reports, passports, and release governance consume metadata refs only.',
+    stableCandidateFields: [...SECURITY_TEST_PLAN_STABLE_CANDIDATE_FIELDS],
+    executionProof: {
+      planned: false,
+      runnable: false,
+      blocked: false,
+      manual: false,
+    },
+    sourceSafety: {
+      rawSourceRequired: false,
+      evidenceUsesRefsOnly: true,
+      generatedTestBodiesStored: false,
+    },
+  };
+}
+
+function normalizeStatusSemantics(input) {
+  const semantics = cloneSourceSafe(input || defaultStatusSemantics(), 'testPlan.statusSemantics');
+  for (const status of SECURITY_TEST_PLAN_STATUSES) {
+    requireString(semantics[status], `testPlan.statusSemantics.${status}`, { max: 240 });
+  }
+  return semantics;
+}
+
+function normalizeDownstreamContract(input) {
+  const contract = cloneSourceSafe(input || defaultDownstreamContract(), 'testPlan.downstreamContract');
+  const stableCandidateFields = asArray(
+    contract.stableCandidateFields,
+    'testPlan.downstreamContract.stableCandidateFields',
+  ).map((field, index) =>
+    requireString(field, `testPlan.downstreamContract.stableCandidateFields[${index}]`, {
+      max: 80,
+      pattern: UUIDISH,
+    }));
+  for (const field of SECURITY_TEST_PLAN_STABLE_CANDIDATE_FIELDS) {
+    if (!stableCandidateFields.includes(field)) {
+      throw new Error(`testPlan.downstreamContract.stableCandidateFields must include ${field}`);
+    }
+  }
+  return {
+    ...contract,
+    schemaVersion: requireString(
+      contract.schemaVersion || SECURITY_TEST_PLAN_SCHEMA_VERSION,
+      'testPlan.downstreamContract.schemaVersion',
+      { max: 80, pattern: UUIDISH },
+    ),
+    stableCandidateFields,
+  };
+}
+
+function makeCandidate(input) {
+  const dedupeKey = requireString(input.dedupeKey, 'testCase.dedupeKey', { max: 240 });
+  const status = requireString(input.status, 'testCase.status', { max: 40, pattern: UUIDISH });
+  if (!SECURITY_TEST_PLAN_STATUSES.includes(status)) {
+    throw new Error(`testCase.status must be one of ${SECURITY_TEST_PLAN_STATUSES.join(', ')}`);
+  }
+  const commandHint = optionalString(input.commandHint ?? input.suggestedCommand, 'testCase.commandHint', { max: 300 });
+  const blockedReason = optionalString(input.blockedReason, 'testCase.blockedReason', { max: 400 });
+  const manualReason = optionalString(input.manualReason, 'testCase.manualReason', { max: 400 });
+  const risk = normalizeRisk(input.risk);
+  const testCase = {
+    id: candidateId(dedupeKey),
+    version: SECURITY_TEST_PLAN_SCHEMA_VERSION,
+    title: requireString(input.title, 'testCase.title', { max: 220 }),
+    purpose: requireString(input.purpose, 'testCase.purpose', { max: 500 }),
+    category: requireString(input.category, 'testCase.category', { max: 80, pattern: UUIDISH }),
+    risk,
+    priority: normalizeRisk(input.priority || risk),
+    status,
+    runner: requireString(input.runner, 'testCase.runner', { max: 80, pattern: UUIDISH }),
+    commandHint: commandHint || null,
+    suggestedCommand: commandHint || null,
+    blockedReason: blockedReason || null,
+    manualReason: manualReason || null,
+    targetSurface: {
+      type: requireString(input.targetSurface?.type, 'testCase.targetSurface.type', { max: 80, pattern: UUIDISH }),
+      files: asArray(input.targetSurface?.files, 'testCase.targetSurface.files')
+        .map((file, index) => requireString(file, `testCase.targetSurface.files[${index}]`, { max: 300 })),
+      routes: asArray(input.targetSurface?.routes, 'testCase.targetSurface.routes')
+        .map((route, index) => requireString(route, `testCase.targetSurface.routes[${index}]`, { max: 160 })),
+    },
+    sourceFindingIds: asArray(input.sourceFindingIds, 'testCase.sourceFindingIds')
+      .map((id, index) => requireString(id, `testCase.sourceFindingIds[${index}]`, { max: 160, pattern: UUIDISH })),
+    sourceArtifactRefs: asArray(input.sourceArtifactRefs, 'testCase.sourceArtifactRefs')
+      .map((id, index) => requireString(id, `testCase.sourceArtifactRefs[${index}]`, { max: 160, pattern: UUIDISH })),
+    evidence: asArray(input.evidence, 'testCase.evidence'),
+    setup: asArray(input.setup, 'testCase.setup')
+      .map((item, index) => requireString(item, `testCase.setup[${index}]`, { max: 300 })),
+    steps: asArray(input.steps, 'testCase.steps')
+      .map((item, index) => requireString(item, `testCase.steps[${index}]`, { max: 400 })),
+    assertion: requireString(input.assertion, 'testCase.assertion', { max: 500 }),
+    dedupeKey,
+    rank: Number.isInteger(input.rank) && input.rank > 0 ? input.rank : 1,
+    metadata: cloneSourceSafe(input.metadata || {}, 'testPlan.testCase.metadata'),
+  };
+
+  if (testCase.sourceArtifactRefs.length === 0) throw new Error('testCase.sourceArtifactRefs must include evidence refs');
+  if (testCase.evidence.length === 0) throw new Error('testCase.evidence must include at least one evidence item');
+  if (status === 'runnable' && !testCase.commandHint) throw new Error('runnable tests require commandHint');
+  if (status === 'blocked' && !testCase.blockedReason) throw new Error('blocked tests require blockedReason');
+  if (status === 'manual' && !testCase.manualReason) throw new Error('manual tests require manualReason');
+  assertSourceSafePayload(testCase, 'testPlan.testCase');
+  return testCase;
+}
+
+function findingCandidate({ finding, sourceRef, commandHint }) {
+  const filePath = safeText(finding.source?.filePath, 'unknown-file', 300);
+  const ruleId = safeIdSegment(finding.ruleId || 'rule');
+  const category = mapFindingCategory(finding);
+  const risk = normalizeRisk(finding.severity);
+  const status = commandHint ? 'runnable' : 'planned';
+  const dedupeKey = `finding:${finding.fingerprint || finding.id || ruleId}:${category}`;
+  return makeCandidate({
+    dedupeKey,
+    title: `Regression coverage for ${safeText(finding.ruleId || 'scanner finding', 'scanner finding', 80)} in ${filePath}`,
+    purpose: `Prove the referenced ${risk} finding is fixed or intentionally accepted before release.`,
+    category,
+    risk,
+    status,
+    runner: commandHint ? 'local_test_command' : 'agent_written_test',
+    commandHint,
+    targetSurface: { type: 'finding', files: [filePath], routes: [] },
+    sourceFindingIds: [finding.id || `finding-${sha256(dedupeKey).slice(0, 12)}`],
+    sourceArtifactRefs: [sourceRef],
+    evidence: [
+      makeEvidence({
+        type: 'deterministic_finding',
+        label: `${safeText(finding.ruleId || 'finding', 'finding', 80)} finding evidence`,
+        sourceArtifactRef: sourceRef,
+        preview: `${filePath}:${finding.source?.lineNumber || 1}`,
+        summary: safeText(finding.title || finding.ruleName || 'Deterministic scanner finding.', 'Deterministic scanner finding.'),
+        metadata: {
+          findingId: finding.id,
+          ruleId: finding.ruleId,
+          severity: risk,
+          filePath,
+          lineNumber: finding.source?.lineNumber || null,
+        },
+      }),
+    ],
+    setup: commandHint
+      ? ['Use the local test command discovered in the Project Map artifact.']
+      : ['Add or identify a local test harness before executing this regression check.'],
+    steps: [
+      'Create or update a focused security regression test for the referenced file and rule.',
+      'Run the local regression command or keep the test item planned if no harness exists yet.',
+      'Rerun Vibesecur deterministic scan and confirm the linked finding is resolved or explicitly accepted.',
+    ],
+    assertion: 'The risky behavior is removed or safely rejected, and the deterministic finding no longer appears on rerun.',
+    metadata: {
+      generatedFrom: 'deterministic_scan',
+      ruleId: finding.ruleId,
+      fingerprint: finding.fingerprint,
+    },
+  });
+}
+
+function routeCandidate({ routeFile, sourceRef, commandHint }) {
+  const filePath = safeText(routeFile.path, 'unknown-route', 300);
+  const status = commandHint ? 'runnable' : 'blocked';
+  return makeCandidate({
+    dedupeKey: `route:${filePath}:api_abuse`,
+    title: `Security coverage for route-like file ${filePath}`,
+    purpose: 'Verify route access, validation, and abuse controls for an observed project entry point.',
+    category: 'api_abuse',
+    risk: 'medium',
+    status,
+    runner: commandHint ? 'local_test_command' : 'blocked_no_harness',
+    commandHint,
+    blockedReason: status === 'blocked' ? 'No local test command was discovered in the Project Map artifact.' : undefined,
+    targetSurface: { type: 'route_file', files: [filePath], routes: [] },
+    sourceFindingIds: [],
+    sourceArtifactRefs: [sourceRef],
+    evidence: [
+      makeEvidence({
+        type: 'project_map_route',
+        label: 'Observed route-like file',
+        sourceArtifactRef: sourceRef,
+        preview: filePath,
+        summary: `Project Map classified this file as ${safeText(routeFile.kind, 'route_like', 80)}.`,
+        metadata: { filePath, kind: routeFile.kind || 'route_like' },
+      }),
+    ],
+    setup: commandHint
+      ? ['Use the local test command discovered in the Project Map artifact.']
+      : ['Add a local route test harness before this check can run.'],
+    steps: [
+      'Exercise the observed route surface through the local test harness.',
+      'Assert unauthenticated, malformed, and over-broad requests fail safely.',
+      'Keep the case linked to the Project Map route evidence for reruns.',
+    ],
+    assertion: 'The route rejects unauthorized or malformed access with an explicit safe failure.',
+    metadata: { generatedFrom: 'project_map', routeKind: routeFile.kind || 'route_like' },
+  });
+}
+
+function isAuthSessionRoute(routeFile = {}) {
+  return /(^|[/._-])(auth|login|logout|session|sessions|jwt|oauth|saml|callback)([/._-]|$)/i
+    .test(String(routeFile.path || ''));
+}
+
+function authSessionCandidate({ routeFile, sourceRef }) {
+  const filePath = safeText(routeFile.path, 'unknown-auth-route', 300);
+  return makeCandidate({
+    dedupeKey: `auth-session:${filePath}:manual`,
+    title: `Manual auth/session review for ${filePath}`,
+    purpose: 'Verify login, session, token, and authorization behavior using local credentials and browser or API state only.',
+    category: 'auth_session',
+    risk: 'high',
+    status: 'manual',
+    runner: 'manual_review',
+    manualReason: 'Auth/session checks require local credentials, cookies, or tokens that must not be copied into Vibesecur artifacts.',
+    targetSurface: { type: 'auth_session', files: [filePath], routes: [] },
+    sourceFindingIds: [],
+    sourceArtifactRefs: [sourceRef],
+    evidence: [
+      makeEvidence({
+        type: 'project_map_route',
+        label: 'Auth/session route-like file',
+        sourceArtifactRef: sourceRef,
+        preview: filePath,
+        summary: `Project Map classified this auth/session file as ${safeText(routeFile.kind, 'route_like', 80)}.`,
+        metadata: { filePath, kind: routeFile.kind || 'route_like', manualOnly: true },
+      }),
+    ],
+    setup: ['Prepare local credentials, cookies, or session fixtures without copying values into Vibesecur artifacts.'],
+    steps: [
+      'Exercise login, logout, session refresh, and unauthorized access behavior locally.',
+      'Confirm credentials, provider keys, install tokens, JWTs, and cookies are never pasted into Vibesecur outputs.',
+      'Record pass/fail evidence as redacted metadata or a local-only report reference.',
+    ],
+    assertion: 'Auth and session controls fail closed without exposing credential or token values in Vibesecur artifacts.',
+    metadata: { generatedFrom: 'project_map', routeKind: routeFile.kind || 'route_like', manualOnly: true },
+  });
+}
+
+function envCandidate({ envFile, sourceRef }) {
+  const filePath = safeText(envFile.path, 'env-file', 300);
+  return makeCandidate({
+    dedupeKey: `env:${filePath}:secrets_config`,
+    title: `Manual secret-handling check for ${filePath}`,
+    purpose: 'Confirm environment values stay local and are represented only by filenames or hashes in Vibesecur artifacts.',
+    category: 'secrets_config',
+    risk: 'high',
+    status: 'manual',
+    runner: 'manual_review',
+    manualReason: 'Environment filenames are visible but values are intentionally unread; human review must happen locally.',
+    targetSurface: { type: 'env_file', files: [filePath], routes: [] },
+    sourceFindingIds: [],
+    sourceArtifactRefs: [sourceRef],
+    evidence: [
+      makeEvidence({
+        type: 'project_map_env_file',
+        label: 'Environment filename observed',
+        sourceArtifactRef: sourceRef,
+        preview: filePath,
+        summary: 'Project Map recorded the env filename with valuesCaptured:false.',
+        metadata: { filePath, valuesCaptured: envFile.valuesCaptured === true },
+      }),
+    ],
+    setup: ['Review local env handling without copying values into Vibesecur artifacts.'],
+    steps: [
+      'Confirm the env file is ignored by version control or intentionally templated.',
+      'Confirm runtime secrets are supplied through the deployment secret manager.',
+      'Confirm no Vibesecur artifact includes environment values.',
+    ],
+    assertion: 'Secret values remain outside source control and outside hosted Vibesecur storage.',
+    metadata: { generatedFrom: 'project_map', valuesCaptured: false },
+  });
+}
+
+function deploymentCandidate({ deploymentFile, sourceRef }) {
+  const filePath = safeText(deploymentFile.path, 'deployment-file', 300);
+  return makeCandidate({
+    dedupeKey: `deployment:${filePath}:deployment_config`,
+    title: `Deployment configuration review for ${filePath}`,
+    purpose: 'Verify deployment config does not bypass the local-first and no-secret-retention trust model.',
+    category: 'deployment_config',
+    risk: 'medium',
+    status: 'planned',
+    runner: 'static_config_review',
+    targetSurface: { type: 'deployment_file', files: [filePath], routes: [] },
+    sourceFindingIds: [],
+    sourceArtifactRefs: [sourceRef],
+    evidence: [
+      makeEvidence({
+        type: 'project_map_deployment_file',
+        label: 'Deployment file observed',
+        sourceArtifactRef: sourceRef,
+        preview: filePath,
+        summary: `Project Map classified this as ${safeText(deploymentFile.type, 'deployment', 80)} config.`,
+        metadata: { filePath, deploymentType: deploymentFile.type || 'deployment' },
+      }),
+    ],
+    setup: ['Review the deployment file locally with source and secrets excluded from Vibesecur storage.'],
+    steps: [
+      'Check security headers, secret references, and environment variable handling in the deployment config.',
+      'Record any required local follow-up as a Ralph task or accepted risk.',
+    ],
+    assertion: 'Deployment config preserves safe secret handling and does not expose source or provider credentials.',
+    metadata: { generatedFrom: 'project_map', deploymentType: deploymentFile.type || 'deployment' },
+  });
+}
+
+function candidateScore(candidate) {
+  return (SEVERITY_WEIGHT[candidate.risk] || 0)
+    + (STATUS_WEIGHT[candidate.status] || 0)
+    + (candidate.sourceFindingIds.length > 0 ? 20 : 0)
+    + (candidate.targetSurface.files.length > 0 ? 5 : 0);
+}
+
+function dedupeAndRank(candidates) {
+  const byKey = new Map();
+  for (const candidate of candidates) {
+    const current = byKey.get(candidate.dedupeKey);
+    if (!current || candidateScore(candidate) > candidateScore(current)) {
+      byKey.set(candidate.dedupeKey, candidate);
+    }
+  }
+  return [...byKey.values()]
+    .sort((a, b) => candidateScore(b) - candidateScore(a) || a.dedupeKey.localeCompare(b.dedupeKey))
+    .map((candidate, index) => ({ ...candidate, rank: index + 1 }));
+}
+
+function countsBy(items, key) {
+  return items.reduce((acc, item) => {
+    const value = item[key] || 'unknown';
+    acc[value] = (acc[value] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function buildSources({ projectMap = {}, deterministicScan = {}, sourceRefs }) {
+  return {
+    projectMap: {
+      artifactRef: sourceRefs.projectMap,
+      schemaVersion: projectMap.schemaVersion || null,
+      rootPathHash: projectMap.root?.pathHash || null,
+      routeFileCount: (projectMap.routeFiles || []).length,
+      envFileCount: (projectMap.envFiles || []).length,
+      deploymentFileCount: (projectMap.deploymentFiles || []).length,
+      testCommandCount: (projectMap.testCommands || []).length,
+    },
+    deterministicScan: {
+      artifactRef: sourceRefs.deterministicScan,
+      schemaVersion: deterministicScan.schemaVersion || null,
+      rootPathHash: deterministicScan.root?.pathHash || null,
+      findingCount: (deterministicScan.findings || []).length,
+      deterministicRuleCount: deterministicScan.engine?.counts?.deterministic || null,
+      checklistCount: deterministicScan.engine?.counts?.checklist || null,
+    },
+  };
+}
+
+export function buildSecurityTestPlanArtifact({
+  projectMap,
+  deterministicScan,
+  generatedAt = nowIso(),
+  sourceRefs = {},
+} = {}) {
+  const safeProjectMap = cloneSourceSafe(projectMap || {}, 'testPlan.projectMapInput');
+  const safeDeterministicScan = cloneSourceSafe(deterministicScan || {}, 'testPlan.deterministicScanInput');
+  const projectMapRef = sourceRefs.projectMap || 'project_map';
+  const deterministicScanRef = sourceRefs.deterministicScan || 'deterministic_scan';
+  const commandHint = firstRunnableCommand(safeProjectMap);
+  const routeFiles = safeProjectMap.routeFiles || [];
+
+  const candidates = [
+    ...(safeDeterministicScan.findings || []).map((finding) =>
+      findingCandidate({ finding, sourceRef: deterministicScanRef, commandHint })),
+    ...routeFiles.map((routeFile) =>
+      routeCandidate({ routeFile, sourceRef: projectMapRef, commandHint })),
+    ...routeFiles.filter(isAuthSessionRoute).map((routeFile) =>
+      authSessionCandidate({ routeFile, sourceRef: projectMapRef })),
+    ...(safeProjectMap.envFiles || []).map((envFile) =>
+      envCandidate({ envFile, sourceRef: projectMapRef })),
+    ...(safeProjectMap.deploymentFiles || []).map((deploymentFile) =>
+      deploymentCandidate({ deploymentFile, sourceRef: projectMapRef })),
+  ];
+
+  const testCases = dedupeAndRank(candidates);
+  const artifact = {
+    schemaVersion: SECURITY_TEST_PLAN_SCHEMA_VERSION,
+    generatedAt: requireIsoDate(generatedAt, 'testPlan.generatedAt'),
+    root: {
+      name: safeProjectMap.root?.name || safeDeterministicScan.root?.name || 'project',
+      pathHash: safeProjectMap.root?.pathHash || safeDeterministicScan.root?.pathHash || null,
+    },
+    sources: buildSources({
+      projectMap: safeProjectMap,
+      deterministicScan: safeDeterministicScan,
+      sourceRefs: { projectMap: projectMapRef, deterministicScan: deterministicScanRef },
+    }),
+    statusSemantics: defaultStatusSemantics(),
+    downstreamContract: defaultDownstreamContract(),
+    summary: {
+      totalTests: testCases.length,
+      byStatus: countsBy(testCases, 'status'),
+      byCategory: countsBy(testCases, 'category'),
+      highestRisk: testCases[0]?.risk || null,
+      runnableCount: testCases.filter((testCase) => testCase.status === 'runnable').length,
+      blockedCount: testCases.filter((testCase) => testCase.status === 'blocked').length,
+      manualCount: testCases.filter((testCase) => testCase.status === 'manual').length,
+      plannedCount: testCases.filter((testCase) => testCase.status === 'planned').length,
+    },
+    testCommands: cloneSourceSafe(safeProjectMap.testCommands || [], 'testPlan.testCommands'),
+    testCases,
+    privacy: {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      evidenceUsesRefsOnly: true,
+      artifactStorage: 'local_metadata_and_hash_refs',
+    },
+  };
+
+  return validateSecurityTestPlanArtifact(artifact);
+}
+
+export function validateSecurityTestPlanArtifact(input = {}) {
+  assertSourceSafePayload(input, 'securityTestPlanArtifact');
+  const artifact = {
+    schemaVersion: requireString(input.schemaVersion, 'testPlan.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: requireIsoDate(input.generatedAt, 'testPlan.generatedAt'),
+    root: {
+      name: requireString(input.root?.name || 'project', 'testPlan.root.name', { max: 180 }),
+      pathHash: optionalString(input.root?.pathHash, 'testPlan.root.pathHash', { max: 64, pattern: SHA256 }),
+    },
+    sources: cloneSourceSafe(asObject(input.sources || {}, 'testPlan.sources'), 'testPlan.sources'),
+    statusSemantics: normalizeStatusSemantics(input.statusSemantics),
+    downstreamContract: normalizeDownstreamContract(input.downstreamContract),
+    summary: cloneSourceSafe(asObject(input.summary || {}, 'testPlan.summary'), 'testPlan.summary'),
+    testCommands: cloneSourceSafe(asArray(input.testCommands, 'testPlan.testCommands'), 'testPlan.testCommands'),
+    testCases: asArray(input.testCases, 'testPlan.testCases').map((testCase) => makeCandidate(testCase)),
+    privacy: cloneSourceSafe(asObject(input.privacy || {}, 'testPlan.privacy'), 'testPlan.privacy'),
+  };
+  if (artifact.schemaVersion !== SECURITY_TEST_PLAN_SCHEMA_VERSION) {
+    throw new Error(`testPlan.schemaVersion must be ${SECURITY_TEST_PLAN_SCHEMA_VERSION}`);
+  }
+  assertSourceSafePayload(artifact, 'securityTestPlanArtifact');
+  return artifact;
+}
+
+export function hashSecurityTestPlanArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'securityTestPlanArtifact');
+  return sha256(stableStringify(validateSecurityTestPlanArtifact(artifact)));
+}
+
+async function readLocalArtifact({ rootPath, ref, type }) {
+  if (!ref || ref.type !== type || ref.storage !== 'local' || !ref.uri) {
+    throw new Error(`Security Test Plan requires a local ${type} artifact reference`);
+  }
+  const resolvedRoot = path.resolve(rootPath);
+  const target = path.resolve(resolvedRoot, ref.uri);
+  const relative = path.relative(resolvedRoot, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Security Test Plan artifact ref for ${type} escapes the bound root`);
+  }
+  const raw = await fs.readFile(target, 'utf8');
+  const parsed = JSON.parse(raw);
+  assertSourceSafePayload(parsed, `securityTestPlan.${type}`);
+  return parsed;
+}
+
+function findArtifactRef(state, type, preferredKeys = []) {
+  const artifacts = state?.artifacts || {};
+  for (const key of preferredKeys) {
+    if (artifacts[key]?.type === type) return artifacts[key];
+  }
+  return Object.values(artifacts).find((ref) => ref?.type === type) || null;
+}
+
+export async function writeSecurityTestPlanArtifact({ rootPath, runId, artifact }) {
+  const safeArtifact = validateSecurityTestPlanArtifact(artifact);
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/${TEST_PLAN_FILE}`;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(safeArtifact), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return {
+    uri: relativeUri,
+    hash: sha256(serialized),
+  };
+}
+
+export function securityTestPlanStepper() {
+  return {
+    id: SECURITY_TEST_PLAN_STEPPER_ID,
+    version: SECURITY_TEST_PLAN_STEPPER_VERSION,
+    title: 'Security Test Plan Stepper',
+    category: 'test_plan_generation',
+    requiredInputs: ['project_map', 'deterministic_scan'],
+    producedArtifacts: ['security_test_plan'],
+    defaultTimeoutMs: 30000,
+    async run({ runId, config = {}, state = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const projectMapRef = findArtifactRef(state, 'project_map', ['project.map']);
+      const deterministicScanRef = findArtifactRef(state, 'deterministic_scan', ['rules.scan']);
+      const projectMap = await readLocalArtifact({ rootPath, ref: projectMapRef, type: 'project_map' });
+      const deterministicScan = await readLocalArtifact({
+        rootPath,
+        ref: deterministicScanRef,
+        type: 'deterministic_scan',
+      });
+      const artifact = buildSecurityTestPlanArtifact({
+        projectMap,
+        deterministicScan,
+        generatedAt: config.generatedAt || startedAt,
+        sourceRefs: {
+          projectMap: projectMapRef.id,
+          deterministicScan: deterministicScanRef.id,
+        },
+      });
+      const contentHash = hashSecurityTestPlanArtifact(artifact);
+      const written = await writeSecurityTestPlanArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-security-test-plan`,
+        type: 'security_test_plan',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Security Test Plan metadata: evidence-linked planned, runnable, blocked, and manual tests only.',
+        metadata: {
+          schemaVersion: SECURITY_TEST_PLAN_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: SECURITY_TEST_PLAN_STEPPER_ID,
+          totalTests: artifact.summary.totalTests,
+          runnableCount: artifact.summary.runnableCount,
+          blockedCount: artifact.summary.blockedCount,
+          manualCount: artifact.summary.manualCount,
+          plannedCount: artifact.summary.plannedCount,
+        },
+      });
+
+      return {
+        stepperId: SECURITY_TEST_PLAN_STEPPER_ID,
+        version: SECURITY_TEST_PLAN_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'hash',
+          label: 'Security Test Plan artifact hash',
+          hash: ref.hash,
+          preview: 'Evidence-linked security test plan artifact written locally.',
+          summary: `${artifact.summary.totalTests} test candidate(s), ${artifact.summary.runnableCount} runnable.`,
+          metadata: {
+            artifactId: ref.id,
+            contentHash,
+            projectMapArtifactId: projectMapRef.id,
+            deterministicScanArtifactId: deterministicScanRef.id,
+          },
+        }],
+        findings: [],
+        artifacts: [ref],
+        receipts: [],
+        summary: `Security Test Plan generated: ${artifact.summary.totalTests} candidate(s), ${artifact.summary.runnableCount} runnable, ${artifact.summary.blockedCount} blocked, ${artifact.summary.manualCount} manual.`,
+        nextActions: ['Use the test plan artifact for Ralph tasks, reports, passports, and local rerun planning.'],
+      };
+    },
+  };
+}