@oh-my-pi/pi-coding-agent 17.1.8 → 17.2.1

package/src/security/publication.ts

@@ -0,0 +1,326 @@
+import { type } from "arktype";
+import type { ToolDefinition } from "../extensibility/extensions";
+import securityPublishDescription from "../prompts/tools/security-publish.md" with { type: "text" };
+import type {
+	SecurityCoverage,
+	SecurityEvidence,
+	SecurityFinding,
+	SecurityLocation,
+	SecurityScan,
+	SecurityScanBundle,
+	SecurityScanPlan,
+} from "./contracts";
+import {
+	createSecurityEvidenceId,
+	createSecurityFindingFingerprint,
+	createSecurityFindingId,
+	createSecurityOccurrenceId,
+} from "./contracts";
+import { pathMatchesSecurityScope } from "./preflight";
+import { createNativeSecurityProducer, createNativeSecurityProvenance } from "./provenance";
+import { exportSecurityBundleToSarif } from "./sarif";
+import { type SecurityStore, writeSecurityBundleToDirectory } from "./store";
+
+const publishLocationSchema = type({
+	path: type("string > 0").describe("repository-relative source path"),
+	start_line: type("number.integer >= 1").describe("1-indexed first source line"),
+	"end_line?": type("number.integer >= 1").describe("1-indexed last source line"),
+	"start_column?": type("number.integer >= 1").describe("1-indexed first source column"),
+	"end_column?": type("number.integer >= 1").describe("1-indexed last source column"),
+	"role?": type("string").describe("entrypoint, root_control, sink, or supporting role"),
+});
+
+const publishEvidenceSchema = type({
+	label: "string > 0",
+	explanation: "string",
+	"excerpt?": "string",
+	"location?": publishLocationSchema,
+});
+
+const publishFindingSchema = type({
+	rule_id: "string > 0",
+	title: "string > 0",
+	summary: "string",
+	severity: "'critical' | 'high' | 'medium' | 'low' | 'informational'",
+	confidence: "'high' | 'medium' | 'low'",
+	category: "string > 0",
+	"anchor?": "string",
+	"cwe?": "string[]",
+	locations: publishLocationSchema.array().atLeastLength(1),
+	"evidence?": publishEvidenceSchema.array(),
+	"remediation?": "string",
+	"validation?": "'unvalidated' | 'validated' | 'partial'",
+});
+
+const publishSurfaceSchema = type({
+	label: "string > 0",
+	disposition: "'reported' | 'no_issue_found' | 'rejected' | 'not_applicable' | 'needs_follow_up'",
+	"risk_area?": "string",
+	"notes?": "string",
+	"receipt_refs?": "string[]",
+});
+
+const publishDeferredSchema = type({
+	reason: "string > 0",
+	"paths?": "string[]",
+	"surface_ids?": "string[]",
+});
+
+export const securityPublishSchema = type({
+	findings: publishFindingSchema.array(),
+	coverage: {
+		completeness: "'complete' | 'partial' | 'unknown'",
+		"surfaces?": publishSurfaceSchema.array(),
+		"explicit_exclusions?": type({ pattern: "string", reason: "string" }).array(),
+		"deferred?": publishDeferredSchema.array(),
+		"open_questions?": type({ question: "string > 0", "follow_up_prompt?": "string" }).array(),
+	},
+	report: "string",
+});
+
+export type SecurityPublishParams = typeof securityPublishSchema.infer;
+
+export interface SecurityPublishDetails {
+	scanId: string;
+	findingCount: number;
+	status: "completed";
+}
+
+export interface SecurityPublicationOptions {
+	plan: SecurityScanPlan;
+	scanId: string;
+	store: SecurityStore;
+	startedAt: string;
+	sessionId?: string;
+	operationId?: string;
+	onPublished?: (bundle: SecurityScanBundle) => void | Promise<void>;
+}
+
+function normalizePublishedPath(input: string): string {
+	const normalized = input.replaceAll("\\", "/").replace(/^\.\//, "");
+	const segments = normalized.split("/");
+	if (
+		!normalized ||
+		normalized.startsWith("/") ||
+		/^[a-zA-Z]:\//.test(normalized) ||
+		segments.some(segment => segment === "..")
+	) {
+		throw new Error(`Security finding paths must be repository-relative: ${input}`);
+	}
+	return normalized;
+}
+
+function toLocation(
+	input: SecurityPublishParams["findings"][number]["locations"][number],
+	plan: SecurityScanPlan,
+): SecurityLocation {
+	const normalizedPath = normalizePublishedPath(input.path);
+	if (!pathMatchesSecurityScope(normalizedPath, plan.target.includePaths, plan.target.excludePaths)) {
+		throw new Error(`Security finding path is outside the immutable scan scope: ${input.path}`);
+	}
+	const location: SecurityLocation = {
+		path: normalizedPath,
+		startLine: input.start_line,
+	};
+	if (input.end_line !== undefined) location.endLine = input.end_line;
+	if (input.start_column !== undefined) location.startColumn = input.start_column;
+	if (input.end_column !== undefined) location.endColumn = input.end_column;
+	if (input.role !== undefined) location.role = input.role;
+	return location;
+}
+
+function coverageMode(plan: SecurityScanPlan): SecurityCoverage["mode"] {
+	switch (plan.target.kind) {
+		case "ref_diff":
+			return "diff";
+		case "working_tree":
+			return "working_tree";
+		case "scoped_path":
+			return "scoped_path";
+		default:
+			return "repository";
+	}
+}
+
+function inventoryStrategy(plan: SecurityScanPlan): SecurityCoverage["inventoryStrategy"] {
+	switch (plan.target.kind) {
+		case "ref_diff":
+			return "diff";
+		case "scoped_path":
+			return "scoped_path";
+		default:
+			return "repository";
+	}
+}
+
+function buildFinding(
+	input: SecurityPublishParams["findings"][number],
+	options: SecurityPublicationOptions,
+	createdAt: string,
+): SecurityFinding {
+	const locations = input.locations.map(location => toLocation(location, options.plan));
+	const fingerprint = createSecurityFindingFingerprint({
+		ruleId: input.rule_id,
+		category: input.category,
+		anchor: input.anchor,
+		locations,
+	});
+	const evidence: SecurityEvidence[] = (input.evidence ?? []).map((item, index) => {
+		const entry: SecurityEvidence = {
+			id: createSecurityEvidenceId(fingerprint, item.label, index),
+			kind: "code",
+			label: item.label,
+			explanation: item.explanation,
+		};
+		if (item.excerpt !== undefined) entry.excerpt = item.excerpt;
+		if (item.location !== undefined) entry.location = toLocation(item.location, options.plan);
+		return entry;
+	});
+	const finding: SecurityFinding = {
+		id: createSecurityFindingId(fingerprint),
+		scanId: options.scanId,
+		fingerprint,
+		ruleId: input.rule_id,
+		title: input.title,
+		summary: input.summary,
+		severity: { level: input.severity },
+		confidence: { level: input.confidence },
+		taxonomy: { category: input.category, cwe: input.cwe ?? [] },
+		occurrences: [
+			{
+				id: createSecurityOccurrenceId(fingerprint, locations),
+				locations,
+				evidenceIds: evidence.map(item => item.id),
+			},
+		],
+		evidence,
+		validation: { status: input.validation ?? "unvalidated", evidenceIds: [] },
+		disposition: { status: "open" },
+		provenance: createNativeSecurityProvenance({
+			createdAt,
+			account: options.plan.account,
+			planFingerprint: options.plan.fingerprint,
+			workflowFingerprint: options.plan.workflowFingerprint,
+			sessionId: options.sessionId,
+		}),
+	};
+	if (input.anchor !== undefined) finding.anchor = input.anchor;
+	if (input.remediation !== undefined) finding.remediation = input.remediation;
+	return finding;
+}
+
+function buildCoverage(params: SecurityPublishParams, plan: SecurityScanPlan): SecurityCoverage {
+	const surfaces: SecurityCoverage["surfaces"] = (params.coverage.surfaces ?? []).map((surface, index) => {
+		const entry: SecurityCoverage["surfaces"][number] = {
+			id: `surface-${index + 1}`,
+			label: surface.label,
+			disposition: surface.disposition,
+			receiptRefs: surface.receipt_refs ?? [],
+		};
+		if (surface.risk_area !== undefined) entry.riskArea = surface.risk_area;
+		if (surface.notes !== undefined) entry.notes = surface.notes;
+		return entry;
+	});
+	const deferred: SecurityCoverage["deferred"] = (params.coverage.deferred ?? []).map((item, index) => {
+		const entry: SecurityCoverage["deferred"][number] = {
+			id: `deferred-${index + 1}`,
+			reason: item.reason,
+		};
+		if (item.paths !== undefined) entry.paths = item.paths;
+		if (item.surface_ids !== undefined) entry.surfaceIds = item.surface_ids;
+		return entry;
+	});
+	const coverage: SecurityCoverage = {
+		mode: coverageMode(plan),
+		completeness: params.coverage.completeness,
+		inventoryStrategy: inventoryStrategy(plan),
+		includePaths: [...plan.target.includePaths],
+		excludePaths: [...plan.target.excludePaths],
+		surfaces,
+		explicitExclusions: params.coverage.explicit_exclusions ?? [],
+		deferred,
+	};
+	if (params.coverage.open_questions !== undefined) {
+		coverage.openQuestions = params.coverage.open_questions.map(item => {
+			const question: NonNullable<SecurityCoverage["openQuestions"]>[number] = { question: item.question };
+			if (item.follow_up_prompt !== undefined) question.followUpPrompt = item.follow_up_prompt;
+			return question;
+		});
+	}
+	return coverage;
+}
+
+export function createSecurityPublicationTool(
+	options: SecurityPublicationOptions,
+): ToolDefinition<typeof securityPublishSchema, SecurityPublishDetails> {
+	let published = false;
+	return {
+		name: "security_publish",
+		label: "Publish Security Scan",
+		description: securityPublishDescription.trim(),
+		parameters: securityPublishSchema,
+		approval: "write",
+		strict: true,
+		async execute(_toolCallId, params) {
+			if (published) throw new Error(`Security scan ${options.scanId} has already been published`);
+			published = true;
+			let persisted = false;
+			try {
+				const completedAt = new Date().toISOString();
+				const findingsByFingerprint = new Map<string, SecurityFinding>();
+				for (const input of params.findings) {
+					const finding = buildFinding(input, options, completedAt);
+					if (!findingsByFingerprint.has(finding.fingerprint)) {
+						findingsByFingerprint.set(finding.fingerprint, finding);
+					}
+				}
+				const findings = [...findingsByFingerprint.values()];
+				const producer = createNativeSecurityProducer();
+				const provenance = createNativeSecurityProvenance({
+					createdAt: options.startedAt,
+					account: options.plan.account,
+					planFingerprint: options.plan.fingerprint,
+					workflowFingerprint: options.plan.workflowFingerprint,
+					sessionId: options.sessionId,
+					operationId: options.operationId,
+				});
+				const scan: SecurityScan = {
+					documentType: "omp-security.scan",
+					schemaVersion: "1.0",
+					id: options.scanId,
+					projectKey: options.store.projectKey,
+					status: "completed",
+					createdAt: options.plan.createdAt,
+					startedAt: options.startedAt,
+					completedAt,
+					plan: options.plan,
+					target: options.plan.target,
+					producer,
+					provenance,
+					findingIds: findings.map(finding => finding.id),
+					coverage: buildCoverage(params, options.plan),
+					reportRef: "report.md",
+					sarifRef: "results.sarif",
+				};
+				const provisional: SecurityScanBundle = { scan, findings, report: params.report };
+				const bundle: SecurityScanBundle = { ...provisional, sarif: exportSecurityBundleToSarif(provisional) };
+				await writeSecurityBundleToDirectory(options.plan.output.root, bundle);
+				await options.store.putBundle(bundle);
+				persisted = true;
+				await options.onPublished?.(bundle);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Published security scan ${options.scanId} with ${findings.length} finding(s).`,
+						},
+					],
+					details: { scanId: options.scanId, findingCount: findings.length, status: "completed" },
+				};
+			} catch (error) {
+				if (!persisted) published = false;
+				throw error;
+			}
+		},
+	};
+}

package/src/security/remediation.ts

@@ -0,0 +1,93 @@
+import type { IsoBackendKind } from "@oh-my-pi/pi-natives";
+import type { IsolationContext } from "../task/isolation-runner";
+import { prepareIsolationContext } from "../task/isolation-runner";
+import type { IsolationHandle, WorktreeBaseline } from "../task/worktree";
+import { cleanupIsolation, ensureIsolation } from "../task/worktree";
+
+export interface SecurityRemediationRequest {
+	cwd: string;
+	findingIds: string[];
+	isolationId?: string;
+	preferredBackend?: IsoBackendKind;
+}
+
+export interface SecurityRemediationWorkspace {
+	id: string;
+	repositoryRoot: string;
+	worktreePath: string;
+	findingIds: string[];
+	backend: IsoBackendKind;
+	fellBack: boolean;
+	fallbackReason: string | null;
+	cleanup(): Promise<void>;
+}
+
+export interface SecurityRemediationDependencies {
+	prepareContext?: (cwd: string) => Promise<IsolationContext>;
+	createIsolation?: (repositoryRoot: string, id: string, preferred?: IsoBackendKind) => Promise<IsolationHandle>;
+	cleanupIsolation?: (handle: IsolationHandle) => Promise<void>;
+	createId?: () => string;
+}
+
+function createRemediationId(): string {
+	return `security-remediation-${Bun.randomUUIDv7().replaceAll("-", "")}`;
+}
+
+function repoBaselineDirty(baseline: WorktreeBaseline): string[] {
+	const dirty: string[] = [];
+	if (baseline.root.staged.trim()) dirty.push("staged changes");
+	if (baseline.root.unstaged.trim()) dirty.push("unstaged changes");
+	if (baseline.root.untracked.length > 0 || baseline.root.untrackedPatch.trim()) dirty.push("untracked files");
+	for (const nested of baseline.nested) {
+		if (
+			nested.baseline.staged.trim() ||
+			nested.baseline.unstaged.trim() ||
+			nested.baseline.untracked.length > 0 ||
+			nested.baseline.untrackedPatch.trim()
+		) {
+			dirty.push(`dirty nested repository ${nested.relativePath}`);
+		}
+	}
+	return dirty;
+}
+
+export function assertSecurityRemediationBaselineClean(baseline: WorktreeBaseline): void {
+	const dirty = repoBaselineDirty(baseline);
+	if (dirty.length === 0) return;
+	throw new Error(
+		[
+			`Security remediation refuses a dirty working tree (${dirty.join(", ")}).`,
+			"Commit or stash the changes before creating an isolated remediation workspace.",
+		].join(" "),
+	);
+}
+
+export async function prepareSecurityRemediationWorkspace(
+	request: SecurityRemediationRequest,
+	dependencies: SecurityRemediationDependencies = {},
+): Promise<SecurityRemediationWorkspace> {
+	const findingIds = [...new Set(request.findingIds.map(id => id.trim()).filter(Boolean))];
+	if (findingIds.length === 0) throw new Error("Security remediation requires at least one finding id");
+	const prepareContext = dependencies.prepareContext ?? prepareIsolationContext;
+	const createIsolation = dependencies.createIsolation ?? ensureIsolation;
+	const disposeIsolation = dependencies.cleanupIsolation ?? cleanupIsolation;
+	const context = await prepareContext(request.cwd);
+	assertSecurityRemediationBaselineClean(context.baseline);
+	const id = request.isolationId?.trim() || dependencies.createId?.() || createRemediationId();
+	const handle = await createIsolation(context.repoRoot, id, request.preferredBackend);
+	let cleaned = false;
+	return {
+		id,
+		repositoryRoot: context.repoRoot,
+		worktreePath: handle.mergedDir,
+		findingIds,
+		backend: handle.backend,
+		fellBack: handle.fellBack,
+		fallbackReason: handle.fallbackReason,
+		async cleanup() {
+			if (cleaned) return;
+			cleaned = true;
+			await disposeIsolation(handle);
+		},
+	};
+}

package/src/security/resource-output.ts

@@ -0,0 +1,50 @@
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import type { InternalResource } from "../internal-urls";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateHead } from "../session/streaming-output";
+
+export interface SecurityResourceOptions {
+	url: string;
+	content: string;
+	contentType: InternalResource["contentType"];
+	isDirectory?: boolean;
+}
+
+function boundedJson(content: string): { content: string; truncated: boolean } {
+	const sanitized = sanitizeText(content);
+	const truncated = truncateHead(sanitized, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	if (!truncated.truncated) return { content: sanitized, truncated: false };
+	return {
+		content: `${JSON.stringify(
+			{
+				truncated: true,
+				originalBytes: truncated.totalBytes,
+				originalLines: truncated.totalLines,
+				preview: truncated.content,
+			},
+			null,
+			2,
+		)}\n`,
+		truncated: true,
+	};
+}
+
+export function createSecurityResource(options: SecurityResourceOptions): InternalResource {
+	const bounded =
+		options.contentType === "application/json"
+			? boundedJson(options.content)
+			: (() => {
+					const sanitized = sanitizeText(options.content);
+					const truncated = truncateHead(sanitized, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+					return { content: truncated.content, truncated: truncated.truncated };
+				})();
+	return {
+		url: options.url,
+		content: bounded.content,
+		contentType: options.contentType,
+		size: Buffer.byteLength(bounded.content),
+		isDirectory: options.isDirectory,
+		notes: bounded.truncated
+			? [`Security resource truncated to ${DEFAULT_MAX_LINES} lines / ${DEFAULT_MAX_BYTES} bytes.`]
+			: undefined,
+	};
+}

package/src/security/sarif.ts

@@ -0,0 +1,78 @@
+import { pathToFileURL } from "node:url";
+import type { SecurityFinding, SecurityScanBundle } from "./contracts";
+
+function sarifLevel(finding: SecurityFinding): "error" | "warning" | "note" | "none" {
+	switch (finding.severity.level) {
+		case "critical":
+		case "high":
+			return "error";
+		case "medium":
+			return "warning";
+		case "low":
+			return "note";
+		default:
+			return "none";
+	}
+}
+
+export function exportSecurityBundleToSarif(bundle: SecurityScanBundle): Record<string, unknown> {
+	const rules = new Map<string, SecurityFinding>();
+	for (const finding of bundle.findings) {
+		if (!rules.has(finding.ruleId)) rules.set(finding.ruleId, finding);
+	}
+	return {
+		$schema: "https://json.schemastore.org/sarif-2.1.0.json",
+		version: "2.1.0",
+		runs: [
+			{
+				tool: {
+					driver: {
+						name: bundle.scan.producer.name,
+						version: bundle.scan.producer.version,
+						informationUri: "https://omp.sh",
+						rules: [...rules.values()].map(finding => ({
+							id: finding.ruleId,
+							name: finding.ruleId,
+							shortDescription: { text: finding.title },
+							fullDescription: { text: finding.summary },
+							properties: {
+								tags: [...finding.taxonomy.cwe, ...(finding.taxonomy.tags ?? [])],
+								"security-severity": finding.severity.score,
+							},
+						})),
+					},
+				},
+				results: bundle.findings.map(finding => ({
+					ruleId: finding.ruleId,
+					level: sarifLevel(finding),
+					message: { text: finding.summary },
+					locations: finding.occurrences.flatMap(occurrence =>
+						occurrence.locations.map(location => ({
+							physicalLocation: {
+								artifactLocation: { uri: location.path, uriBaseId: "%SRCROOT%" },
+								region: {
+									startLine: location.startLine,
+									endLine: location.endLine,
+									startColumn: location.startColumn,
+									endColumn: location.endColumn,
+								},
+							},
+						})),
+					),
+					fingerprints: { "omp-security/v1": finding.fingerprint },
+					properties: {
+						findingId: finding.id,
+						confidence: finding.confidence.level,
+						validation: finding.validation.status,
+						disposition: finding.disposition.status,
+						category: finding.taxonomy.category,
+						"security-severity": finding.severity.score,
+					},
+				})),
+				originalUriBaseIds: {
+					"%SRCROOT%": { uri: pathToFileURL(bundle.scan.target.repositoryRoot).href.replace(/\/?$/, "/") },
+				},
+			},
+		],
+	};
+}