@aperant/framework 0.8.0 → 0.8.4

package/src/cli/verify-proof/exec.mjs

@@ -0,0 +1,74 @@
+/**
+ * exec.mjs — execFile-only execution layer for local_command transports.
+ *
+ * ID-03 security invariant: drivers with `transport: { local_command }`
+ * MUST be invoked through execFile (NO shell, NO pipes, NO redirects).
+ *
+ * This module exposes ONE function — execLocalCommand — which:
+ *   1. Asserts the transport is { local_command: { binary, args[] } }
+ *      (the manifest validator already structurally enforces this; this
+ *      is defense-in-depth at runtime).
+ *   2. Rejects any args entry that is not a plain string.
+ *   3. Invokes node:child_process.execFile (NOT child_process.exec, NOT
+ *      spawn with shell:true).
+ *
+ * Grep guard (TD-05): the test verify-proof-local-command-security.test.ts
+ * statically asserts that exec.mjs imports execFile from
+ * 'node:child_process' and never references child_process.exec / spawn
+ * with shell:true.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Type-check that a transport is the structured local_command variant.
+ * @param {unknown} transport
+ * @returns {transport is {local_command: {binary: string, args: string[]}}}
+ */
+function isStructuredLocalCommand(transport) {
+	if (transport === null || typeof transport !== 'object' || Array.isArray(transport)) return false
+	const obj = /** @type {Record<string, unknown>} */ (transport)
+	if (obj.local_command === null || typeof obj.local_command !== 'object') return false
+	const lc = /** @type {Record<string, unknown>} */ (obj.local_command)
+	if (typeof lc.binary !== 'string') return false
+	if (!Array.isArray(lc.args)) return false
+	for (const a of lc.args) {
+		if (typeof a !== 'string') return false
+	}
+	return true
+}
+
+/**
+ * Execute a manifest's local_command transport via execFile (no shell).
+ * Throws if the transport is not the structured variant.
+ *
+ * @param {{transport: unknown}} manifest
+ * @param {string[]} [extraArgs] — appended to manifest.transport.local_command.args.
+ * @param {{cwd?: string, env?: Record<string,string>, timeout?: number}} [options]
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+export async function execLocalCommand(manifest, extraArgs = [], options = {}) {
+	const transport = manifest.transport
+	if (!isStructuredLocalCommand(transport)) {
+		throw new Error(
+			`execLocalCommand: transport is not a structured local_command — refusing to invoke. Got: ${JSON.stringify(transport)}`,
+		)
+	}
+	const { binary, args } = transport.local_command
+	for (const arg of extraArgs) {
+		if (typeof arg !== 'string') {
+			throw new Error(`execLocalCommand: extraArgs must be strings, got ${typeof arg}`)
+		}
+	}
+	return execFileAsync(binary, [...args, ...extraArgs], {
+		cwd: options.cwd,
+		env: options.env,
+		timeout: options.timeout,
+		// Explicit — never pass shell:true. execFile defaults to no shell, but
+		// we surface the invariant in code for grep-guard purposes.
+		shell: false,
+	})
+}

package/src/cli/verify-proof/idl/index.mjs

@@ -0,0 +1,24 @@
+/**
+ * idl/index.mjs — framework-side re-export of the IDL v1 runtime registry.
+ *
+ * The SINGLE SOURCE OF TRUTH lives in `@aperant/driver-sdk` (idl.ts) — see
+ * ID-04 in spec.md. This file just re-exports those runtime values so
+ * framework-internal callers (bundled drivers, resolver, driver-doctor,
+ * conformance kit) can import from the existing relative path without
+ * paying the cost of refactoring every callsite.
+ *
+ * If you add a verb, edit packages/framework-driver-sdk/src/idl.ts. This
+ * file requires no maintenance.
+ */
+
+export {
+	ASSERTION_VERBS,
+	ASYNC_VERBS,
+	EVIDENCE_VERBS,
+	IDL_VERB_ARGS,
+	IDL_VERB_NAMES,
+	INTERACTION_VERBS,
+	isVerbResult,
+	LIFECYCLE_VERBS,
+	validateVerbArgs,
+} from '@aperant/driver-sdk'

package/src/cli/verify-proof/idl/types.ts

@@ -0,0 +1,41 @@
+/**
+ * idl/types.ts — re-export the SDK's IDL types for framework-internal use.
+ *
+ * Single source of truth lives in `@aperant/driver-sdk/idl.ts`. Framework
+ * code imports from here so future moves (e.g. an internal-only IDL
+ * extension) only touch this re-export, not every call site.
+ */
+
+export type {
+	AssertNetworkArgs,
+	AssertOutputArgs,
+	AssertTextArgs,
+	AssertVisibleArgs,
+	AwaitSignalArgs,
+	CaptureLogsArgs,
+	ClickArgs,
+	DomDumpArgs,
+	DragDropArgs,
+	DriverModule,
+	DumpStateArgs,
+	ExecuteJsArgs,
+	Handle,
+	IdlVerbName,
+	KeyArgs,
+	LaunchArgs,
+	NavigateArgs,
+	RecordVideoArgs,
+	ScreenshotArgs,
+	SelectArgs,
+	SwipeArgs,
+	SwitchContextArgs,
+	Target,
+	TargetKind,
+	TeardownArgs,
+	TriggerArgs,
+	TypeArgs,
+	UploadFileArgs,
+	VerbResult,
+	WaitForEventArgs,
+	WaitForIdleArgs,
+} from '@aperant/driver-sdk'

package/src/cli/verify-proof/manifest-schema.json

@@ -0,0 +1,211 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://aperant.dev/schemas/driver-manifest-v1.json",
+	"title": "Aperant Driver Manifest v1",
+	"description": "Structural contract for a verify-proof driver manifest. Validates at publish-time (apt-tools driver doctor) and at load-time (resolver). The transport oneOf rejects free-form shell strings — local_command MUST be a structured {binary, args[]} object per ID-03.",
+	"type": "object",
+	"required": [
+		"driverId",
+		"version",
+		"targets",
+		"capabilities",
+		"frameworkApiRange",
+		"priority",
+		"stability",
+		"trust",
+		"security",
+		"transport"
+	],
+	"properties": {
+		"driverId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_-]*$"
+		},
+		"version": {
+			"type": "string"
+		},
+		"targets": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"capabilities": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"evidence_capabilities": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"frameworkApiRange": {
+			"type": "string"
+		},
+		"requires": {
+			"type": "object",
+			"properties": {
+				"allOf": { "type": "array", "items": { "type": "string" } },
+				"anyOf": { "type": "array", "items": { "type": "string" } }
+			}
+		},
+		"os": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"arch": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"container_support": { "type": "boolean" },
+		"conflicts_with": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"priority": { "type": "number" },
+		"stability": {
+			"type": "string",
+			"enum": ["experimental", "beta", "ga"]
+		},
+		"trust": {
+			"type": "object",
+			"required": ["tier"],
+			"properties": {
+				"tier": {
+					"type": "string",
+					"enum": [
+						"first_party_signed",
+						"community_verified",
+						"community_unverified",
+						"local_unverified"
+					]
+				},
+				"publisher": {
+					"type": "object",
+					"required": ["name"],
+					"properties": {
+						"name": { "type": "string" },
+						"npm_scope": { "type": "string" },
+						"github_org": { "type": "string" },
+						"verified": { "type": "boolean" }
+					}
+				},
+				"provenance": {
+					"type": "object",
+					"properties": {
+						"scheme": {
+							"type": "string",
+							"enum": ["sigstore", "npm-provenance", "gpg", "none"]
+						},
+						"identity": { "type": "string" },
+						"signature": { "type": "string" },
+						"certificate": { "type": "string" }
+					}
+				},
+				"integrity": {
+					"type": "object",
+					"properties": {
+						"manifest_sha256": { "type": "string" },
+						"artifact_digest": { "type": "string" }
+					}
+				}
+			}
+		},
+		"security": {
+			"type": "object",
+			"required": ["sandbox_profile", "network"],
+			"properties": {
+				"sandbox_profile": {
+					"type": "string",
+					"enum": ["read_only", "workspace_write", "system_write"]
+				},
+				"network": {
+					"type": "string",
+					"enum": ["deny", "allowlist", "allow"]
+				},
+				"allowed_executables": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"allow_shell": { "type": "boolean" },
+				"requires_user_approval": { "type": "boolean" }
+			}
+		},
+		"audit": {
+			"type": "object",
+			"required": ["log_invocations", "log_manifest_hash"],
+			"properties": {
+				"log_invocations": { "type": "boolean" },
+				"log_manifest_hash": { "type": "boolean" }
+			}
+		},
+		"preflight": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["name", "required"],
+				"properties": {
+					"name": { "type": "string" },
+					"command": {
+						"type": "object",
+						"required": ["binary", "args"],
+						"properties": {
+							"binary": { "type": "string" },
+							"args": {
+								"type": "array",
+								"items": { "type": "string" }
+							}
+						}
+					},
+					"required": { "type": "boolean" }
+				}
+			}
+		},
+		"transport": {
+			"oneOf": [
+				{
+					"type": "object",
+					"required": ["mcp_server_id"],
+					"properties": {
+						"mcp_server_id": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["local_command"],
+					"properties": {
+						"local_command": {
+							"type": "object",
+							"required": ["binary", "args"],
+							"properties": {
+								"binary": { "type": "string" },
+								"args": {
+									"type": "array",
+									"items": { "type": "string" }
+								}
+							}
+						}
+					}
+				},
+				{
+					"type": "object",
+					"required": ["http_endpoint"],
+					"properties": {
+						"http_endpoint": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["npm_package"],
+					"properties": {
+						"npm_package": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["builtin"],
+					"properties": {
+						"builtin": { "const": true }
+					}
+				}
+			]
+		}
+	}
+}

package/src/cli/verify-proof/manifest-validator.mjs

@@ -0,0 +1,184 @@
+/**
+ * manifest-validator.mjs — hand-rolled JSON-Schema subset validator.
+ *
+ * Validates driver manifests against manifest-schema.json. Implements
+ * exactly the JSON-Schema keywords we need:
+ *
+ *   type / required / properties / items / enum / const / pattern / oneOf
+ *
+ * Returns { valid: true } or { valid: false, errors: [{ path, message }] }
+ * where `path` is a JSON-pointer (`/transport/local_command/binary`).
+ *
+ * No external deps — keeps the validator installable as `dist/` with the
+ * framework package and avoids dragging ajv (or any v5+ JSON-Schema
+ * validator) into the runtime surface for ~80 lines of validator code per
+ * AC15. We don't need allOf / anyOf / definitions — manifest-schema.json
+ * is intentionally a thin contract.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/** Lazy-loaded JSON-Schema (read once on first call). */
+let cachedSchema = null
+
+/** Read the bundled manifest-schema.json. */
+export function loadManifestSchema() {
+	if (cachedSchema !== null) return cachedSchema
+	const schemaPath = join(__dirname, 'manifest-schema.json')
+	cachedSchema = JSON.parse(readFileSync(schemaPath, 'utf-8'))
+	return cachedSchema
+}
+
+/**
+ * Validate a manifest object against the bundled schema.
+ *
+ * @param {unknown} manifest — usually JSON.parse(manifest.json contents).
+ * @param {object} [schema] — override the bundled schema (used by tests).
+ * @returns {{valid: true} | {valid: false, errors: Array<{path: string, message: string}>}}
+ */
+export function validateManifest(manifest, schema) {
+	const root = schema ?? loadManifestSchema()
+	const errors = []
+	validateNode(manifest, root, '', errors)
+	if (errors.length === 0) return { valid: true }
+	return { valid: false, errors }
+}
+
+/** Type check — JSON-Schema's union of "string", "number", "object", "array", "boolean", "null". */
+function checkType(value, type) {
+	if (type === 'string') return typeof value === 'string'
+	if (type === 'number') return typeof value === 'number' && !Number.isNaN(value)
+	if (type === 'integer') return typeof value === 'number' && Number.isInteger(value)
+	if (type === 'boolean') return typeof value === 'boolean'
+	if (type === 'null') return value === null
+	if (type === 'array') return Array.isArray(value)
+	if (type === 'object') {
+		return value !== null && typeof value === 'object' && !Array.isArray(value)
+	}
+	return false
+}
+
+/**
+ * Human-readable name for the actual shape of a value. Distinguishes
+ * `null`, `array`, and plain `object` — JS `typeof` reports all three as
+ * `'object'`, which makes error messages like "expected type object, got
+ * object" misleading.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeType(value) {
+	if (value === null) return 'null'
+	if (Array.isArray(value)) return 'array'
+	return typeof value
+}
+
+/**
+ * Recursive validator. `errors` is mutated.
+ *
+ * @param {unknown} value
+ * @param {object} schema
+ * @param {string} path — JSON-pointer
+ * @param {Array<{path: string, message: string}>} errors
+ */
+function validateNode(value, schema, path, errors) {
+	// const
+	if ('const' in schema) {
+		if (value !== schema.const) {
+			errors.push({
+				path: path || '/',
+				message: `expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`,
+			})
+			return
+		}
+	}
+
+	// type
+	if (schema.type !== undefined) {
+		const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+		if (!types.some((t) => checkType(value, t))) {
+			errors.push({
+				path: path || '/',
+				message: `expected type ${types.join('|')}, got ${describeType(value)}`,
+			})
+			return
+		}
+	}
+
+	// enum
+	if (Array.isArray(schema.enum)) {
+		if (!schema.enum.includes(value)) {
+			errors.push({
+				path: path || '/',
+				message: `value ${JSON.stringify(value)} not in enum [${schema.enum.join(', ')}]`,
+			})
+			return
+		}
+	}
+
+	// pattern
+	if (typeof schema.pattern === 'string' && typeof value === 'string') {
+		const re = new RegExp(schema.pattern)
+		if (!re.test(value)) {
+			errors.push({
+				path: path || '/',
+				message: `value ${JSON.stringify(value)} does not match pattern ${schema.pattern}`,
+			})
+			return
+		}
+	}
+
+	// oneOf
+	if (Array.isArray(schema.oneOf)) {
+		let matchCount = 0
+		const branchErrors = []
+		for (let i = 0; i < schema.oneOf.length; i++) {
+			const sub = schema.oneOf[i]
+			const subErrors = []
+			validateNode(value, sub, path, subErrors)
+			if (subErrors.length === 0) matchCount++
+			else branchErrors.push({ branch: i, errors: subErrors })
+		}
+		if (matchCount !== 1) {
+			errors.push({
+				path: path || '/',
+				message:
+					matchCount === 0
+						? `oneOf: value matched no branch (${branchErrors.length} branches tried)`
+						: `oneOf: value matched ${matchCount} branches (must match exactly 1)`,
+			})
+			return
+		}
+	}
+
+	// object validation
+	if (checkType(value, 'object')) {
+		const obj = /** @type {Record<string, unknown>} */ (value)
+		if (Array.isArray(schema.required)) {
+			for (const key of schema.required) {
+				if (!(key in obj)) {
+					errors.push({ path: `${path}/${key}`, message: `required property "${key}" missing` })
+				}
+			}
+		}
+		if (schema.properties && typeof schema.properties === 'object') {
+			for (const [key, subSchema] of Object.entries(schema.properties)) {
+				if (key in obj) {
+					validateNode(obj[key], /** @type {object} */ (subSchema), `${path}/${key}`, errors)
+				}
+			}
+		}
+	}
+
+	// array validation
+	if (checkType(value, 'array') && schema.items) {
+		const arr = /** @type {unknown[]} */ (value)
+		for (let i = 0; i < arr.length; i++) {
+			validateNode(arr[i], schema.items, `${path}/${i}`, errors)
+		}
+	}
+}

package/src/cli/verify-proof/resolver.mjs

@@ -0,0 +1,163 @@
+/**
+ * resolver.mjs — driver selection + fallback chain.
+ *
+ * Given a project's runtime capabilities, the discovered drivers, and the
+ * test's required IDL capabilities, return the best driver — or throw
+ * UnsatisfiedRequiredCapabilityError if no driver in the chain satisfies
+ * a REQUIRED capability (ID-02 fail-closed).
+ *
+ * Scoring (ID-02, ordered high → low):
+ *   1. capability_coverage — how many required capabilities the driver has
+ *   2. compatibility — does the runtime match the manifest.targets?
+ *   3. stability — ga > beta > experimental
+ *   4. priority — higher wins (manifest.priority)
+ *   5. locality — bundled (packages/framework/drivers/) > user-installed
+ *      (.aperant/drivers/) > registry (.aperant/registry-cache/)
+ *
+ * Ties are broken by the next dimension; if every dimension is equal the
+ * driver with the lexicographically smaller driverId wins (deterministic).
+ */
+
+import { UnsatisfiedRequiredCapabilityError } from '@aperant/driver-sdk'
+
+/**
+ * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ * @typedef {import('./runtime-detect.mjs').RuntimeCapabilities} RuntimeCapabilities
+ */
+
+const STABILITY_RANK = { ga: 3, beta: 2, experimental: 1 }
+const LOCALITY_RANK = { bundled: 3, user: 2, registry: 1 }
+
+/**
+ * Score a single driver against the project's runtime + required capabilities.
+ *
+ * @param {DriverManifest & {locality?: 'bundled'|'user'|'registry'}} manifest
+ * @param {RuntimeCapabilities} runtime
+ * @param {string[]} required
+ * @returns {{score: number[], reason?: string}}
+ */
+export function scoreDriver(manifest, runtime, required) {
+	const caps = new Set(manifest.capabilities ?? [])
+	const coverage = required.filter((c) => caps.has(c)).length
+	const compatibility = matchesRuntime(manifest, runtime) ? 1 : 0
+	const stability = STABILITY_RANK[manifest.stability] ?? 0
+	const priority = manifest.priority ?? 0
+	const locality = LOCALITY_RANK[manifest.locality ?? 'bundled'] ?? 0
+	return { score: [coverage, compatibility, stability, priority, locality] }
+}
+
+/**
+ * Whether a manifest's targets[] mentions a runtime the project has.
+ *
+ * @param {DriverManifest} manifest
+ * @param {RuntimeCapabilities} runtime
+ * @returns {boolean}
+ */
+function matchesRuntime(manifest, runtime) {
+	const targets = manifest.targets ?? []
+	for (const t of targets) {
+		// Strip any version range suffix (e.g. "electron@>=25" → "electron").
+		const stripped = String(t).split('@')[0].toLowerCase()
+		if (stripped === 'electron' && runtime.is_electron) return true
+		if (stripped === 'tauri' && runtime.is_tauri) return true
+		if ((stripped === 'browser' || stripped === 'web') && runtime.is_web_frontend) return true
+		if (stripped === 'next' && runtime.is_nextjs) return true
+		if (stripped === 'nuxt' && runtime.is_nuxt) return true
+		if (stripped === 'expo' && runtime.is_expo) return true
+		if (stripped === 'react-native' && runtime.is_react_native) return true
+		if (stripped === 'node' && runtime.has_node) return true
+		if (stripped === 'cli' && runtime.has_node) return true
+		if (stripped === 'api' && runtime.has_node) return true
+		if (stripped === 'fake') return true // fixture-only — always matches
+	}
+	return false
+}
+
+/**
+ * Compare two driver-score tuples lexicographically.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+function compareScores(a, b) {
+	for (let i = 0; i < Math.min(a.length, b.length); i++) {
+		if (a[i] !== b[i]) return b[i] - a[i] // higher wins
+	}
+	return 0
+}
+
+/**
+ * Resolve the best driver for a given (runtime, drivers, override, required)
+ * tuple.
+ *
+ * @param {Object} opts
+ * @param {DriverManifest[]} opts.drivers — manifests of every discovered driver.
+ * @param {RuntimeCapabilities} opts.runtime — project's runtime capabilities.
+ * @param {string[]} opts.required_capabilities — IDL verbs the test needs.
+ * @param {string[]} [opts.required_stability] — accepted stability values; default ['ga'].
+ * @param {string[]} [opts.override] — config.json:verification.runtimes[]: explicit driverId precedence.
+ * @returns {{selected: DriverManifest, fallback_attempts: Array<{driver_id: string, reason: string}>}}
+ * @throws {UnsatisfiedRequiredCapabilityError} when no driver satisfies a REQUIRED capability.
+ */
+export function resolveDriver(opts) {
+	const drivers = opts.drivers ?? []
+	const runtime = opts.runtime
+	const required = opts.required_capabilities ?? []
+	const stabilityFilter = new Set(opts.required_stability ?? ['ga'])
+	const override = opts.override ?? []
+
+	const fallback = []
+
+	// Apply override precedence first (config-listed driverIds come first).
+	const overrideOrdered = []
+	const overrideSet = new Set(override)
+	for (const id of override) {
+		const d = drivers.find((m) => m.driverId === id)
+		if (d) overrideOrdered.push(d)
+	}
+	const remaining = drivers.filter((m) => !overrideSet.has(m.driverId))
+	const ordered = [...overrideOrdered, ...remaining]
+
+	// Filter by stability; rejected drivers go into fallback_attempts.
+	const stableOnly = []
+	for (const d of ordered) {
+		if (!stabilityFilter.has(d.stability)) {
+			fallback.push({
+				driver_id: d.driverId,
+				reason: `stability ${d.stability} not in allowed set [${[...stabilityFilter].join(', ')}]`,
+			})
+			continue
+		}
+		stableOnly.push(d)
+	}
+
+	// Score every survivor against required capabilities.
+	const scored = stableOnly.map((m) => ({ manifest: m, ...scoreDriver(m, runtime, required) }))
+
+	// Sort highest-first, tie-break on driverId for determinism.
+	scored.sort((a, b) => {
+		const cmp = compareScores(a.score, b.score)
+		if (cmp !== 0) return cmp
+		return a.manifest.driverId.localeCompare(b.manifest.driverId)
+	})
+
+	// Pick the top scorer that covers EVERY required capability. Others go into fallback.
+	for (const candidate of scored) {
+		const caps = new Set(candidate.manifest.capabilities ?? [])
+		const missing = required.filter((c) => !caps.has(c))
+		if (missing.length === 0) {
+			return { selected: candidate.manifest, fallback_attempts: fallback }
+		}
+		fallback.push({
+			driver_id: candidate.manifest.driverId,
+			reason: `missing required capabilities: ${missing.join(', ')}`,
+		})
+	}
+
+	// Exhausted the chain — fail closed (ID-02).
+	throw new UnsatisfiedRequiredCapabilityError(
+		`No driver in the chain satisfies every required capability: [${required.join(', ')}]`,
+		required[0],
+		fallback,
+	)
+}