gentle-pi 2.1.2 → 2.2.0

package/lib/provider-contract-bundle.ts

@@ -0,0 +1,704 @@
+// gentle-pi provider contract bundle verifier (gentle-pi#311 P1/P2).
+//
+// Consumes the data-only `gentle-ai-review-provider-contract-<semver>.tar.gz`
+// release bundle (or its extracted tree) and verifies it fail-closed before
+// any layout, role, schema, or capability inside it is trusted:
+//
+// - exact eight-entry inventory (README.md, manifest.json, 3 schemas, 3 vectors);
+// - strict manifest decode: single JSON object, no duplicate keys, no unknown fields;
+// - per-file SHA-256 agreement between the manifest and the actual bytes;
+// - pinned transport capability and supported contract major (1);
+// - exactly the three provider roles `lens`, `refuter`, `targeted-validator`;
+// - only known mandatory capabilities;
+// - `runtimes` REQUIRED from contract 1.1.0 and it must register `pi`
+//   (a 1.0.x manifest without `runtimes` is a valid bundle, but the relay
+//   must then treat the `pi` runtime identity as unregistered);
+// - confined in-memory archive reading: regular tar entries only, canonical
+//   relative paths, no symlinks, no path escapes, safe modes, bounded sizes.
+//
+// Gentle AI remains the sole review authority. This module never derives
+// admission semantics from the bundle; it only proves the bundle is the exact
+// artifact the provider published before generated baselines are built from it.
+
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import { posix as posixPath, join as joinPath } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+export const PROVIDER_CONTRACT_BUNDLE_SCHEMA = "gentle-ai.review-provider-contract-bundle/v1";
+export const PROVIDER_TRANSPORT_CAPABILITY = "gentle-ai.provider-transport/v1";
+export const PI_RUNTIME_IDENTITY = "pi";
+export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
+// `runtimes` became part of the manifest in contract 1.1.0.
+export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
+// Exactly the provider roles gentle-pi supports, in the manifest's strict order.
+export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
+// Every mandatory capability a role may declare. An unknown mandatory
+// capability means this gentle-pi build cannot satisfy the role: fail closed.
+export const KNOWN_MANDATORY_CAPABILITIES: readonly string[] = [PROVIDER_TRANSPORT_CAPABILITY];
+
+const MAX_ARCHIVE_BYTES = 8 * 1024 * 1024;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 64 * 1024;
+const BUNDLE_ENTRY_COUNT = 8;
+// setuid/setgid/sticky, any execute bit, or world-writable content is never
+// acceptable for a data-only contract bundle.
+const FORBIDDEN_MODE_BITS = 0o7113;
+
+const SEMVER_PATTERN = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const RUNTIME_IDENTITY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export const PROVIDER_CONTRACT_BUNDLE_INVALID = "invalid-provider-contract-bundle";
+
+export class ProviderContractBundleError extends Error {
+	readonly code = PROVIDER_CONTRACT_BUNDLE_INVALID;
+	constructor(message: string) {
+		super(`${PROVIDER_CONTRACT_BUNDLE_INVALID}: ${message}`);
+		this.name = "ProviderContractBundleError";
+	}
+}
+
+function invalid(message: string): never {
+	throw new ProviderContractBundleError(message);
+}
+
+export interface VerifiedProviderRole {
+	readonly id: string;
+	readonly requestSchemaId: string;
+	readonly resultSchemaId: string;
+	readonly requiredCapabilities: readonly string[];
+	readonly schemaPath: string;
+	readonly schemaSha256: string;
+	readonly vectorPath: string;
+	readonly vectorSha256: string;
+}
+
+export interface VerifiedProviderContractBundle {
+	readonly contractSemver: string;
+	readonly major: number;
+	readonly minor: number;
+	readonly patch: number;
+	readonly transportCapability: string;
+	/** Present exactly when the manifest declares the runtime registry (>= 1.1.0). */
+	readonly runtimes: readonly string[] | undefined;
+	readonly roles: readonly VerifiedProviderRole[];
+	/** Canonical path -> exact verified bytes for all eight entries. */
+	readonly entries: ReadonlyMap<string, Buffer>;
+	/** Canonical path -> SHA-256 of the exact verified bytes. */
+	readonly entrySha256: ReadonlyMap<string, string>;
+	/** Deterministic digest over the sorted `<sha256>  <path>` inventory. */
+	readonly treeSha256: string;
+}
+
+export interface PiRuntimeRegistration {
+	readonly registered: boolean;
+	readonly reason?: string;
+}
+
+function sha256Hex(bytes: Buffer): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+// --- strict JSON (single object, no duplicate keys, no trailing data) -------
+
+class StrictJsonScanner {
+	private index = 0;
+	private readonly text: string;
+	constructor(text: string) {
+		this.text = text;
+	}
+
+	scanDocument(): unknown {
+		this.skipWhitespace();
+		if (this.peek() !== "{") invalid("manifest must be a single JSON object");
+		const value = this.scanValue();
+		this.skipWhitespace();
+		if (this.index !== this.text.length) invalid("manifest has trailing data after its JSON object");
+		return value;
+	}
+
+	private peek(): string {
+		if (this.index >= this.text.length) invalid("manifest JSON ends unexpectedly");
+		return this.text[this.index] as string;
+	}
+
+	private next(): string {
+		const character = this.peek();
+		this.index += 1;
+		return character;
+	}
+
+	private skipWhitespace(): void {
+		while (this.index < this.text.length && " \t\n\r".includes(this.text[this.index] as string)) this.index += 1;
+	}
+
+	private scanValue(): unknown {
+		this.skipWhitespace();
+		const character = this.peek();
+		if (character === "{") return this.scanObject();
+		if (character === "[") return this.scanArray();
+		if (character === '"') return this.scanString();
+		if (character === "-" || (character >= "0" && character <= "9")) return this.scanNumber();
+		if (this.text.startsWith("true", this.index)) { this.index += 4; return true; }
+		if (this.text.startsWith("false", this.index)) { this.index += 5; return false; }
+		if (this.text.startsWith("null", this.index)) { this.index += 4; return null; }
+		return invalid(`manifest JSON has an unexpected token at offset ${this.index}`);
+	}
+
+	private scanObject(): Record<string, unknown> {
+		this.next();
+		const value: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+		this.skipWhitespace();
+		if (this.peek() === "}") { this.next(); return value; }
+		for (;;) {
+			this.skipWhitespace();
+			if (this.peek() !== '"') invalid("manifest JSON object key is not a string");
+			const key = this.scanString();
+			if (Object.prototype.hasOwnProperty.call(value, key)) invalid(`manifest JSON has duplicate key ${JSON.stringify(key)}`);
+			this.skipWhitespace();
+			if (this.next() !== ":") invalid("manifest JSON object is missing a colon");
+			value[key] = this.scanValue();
+			this.skipWhitespace();
+			const separator = this.next();
+			if (separator === "}") return value;
+			if (separator !== ",") invalid("manifest JSON object is malformed");
+		}
+	}
+
+	private scanArray(): unknown[] {
+		this.next();
+		const values: unknown[] = [];
+		this.skipWhitespace();
+		if (this.peek() === "]") { this.next(); return values; }
+		for (;;) {
+			values.push(this.scanValue());
+			this.skipWhitespace();
+			const separator = this.next();
+			if (separator === "]") return values;
+			if (separator !== ",") invalid("manifest JSON array is malformed");
+		}
+	}
+
+	private scanString(): string {
+		if (this.next() !== '"') invalid("manifest JSON string is malformed");
+		let value = "";
+		for (;;) {
+			const character = this.next();
+			if (character === '"') return value;
+			if (character === "\\") {
+				const escape = this.next();
+				if (escape === '"' || escape === "\\" || escape === "/") value += escape;
+				else if (escape === "b") value += "\b";
+				else if (escape === "f") value += "\f";
+				else if (escape === "n") value += "\n";
+				else if (escape === "r") value += "\r";
+				else if (escape === "t") value += "\t";
+				else if (escape === "u") {
+					const hex = this.text.slice(this.index, this.index + 4);
+					if (!/^[0-9a-fA-F]{4}$/.test(hex)) invalid("manifest JSON has an invalid unicode escape");
+					this.index += 4;
+					value += String.fromCharCode(Number.parseInt(hex, 16));
+				} else invalid("manifest JSON has an invalid escape sequence");
+			} else if (character.charCodeAt(0) < 0x20) {
+				invalid("manifest JSON string has an unescaped control character");
+			} else {
+				value += character;
+			}
+		}
+	}
+
+	private scanNumber(): number {
+		const start = this.index;
+		if (this.peek() === "-") this.index += 1;
+		while (this.index < this.text.length && /[0-9.eE+-]/.test(this.text[this.index] as string)) this.index += 1;
+		const literal = this.text.slice(start, this.index);
+		if (!/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/.test(literal)) invalid("manifest JSON number is malformed");
+		return Number(literal);
+	}
+}
+
+function decodeStrictManifestObject(payload: Buffer): Record<string, unknown> {
+	if (payload.length > MAX_MANIFEST_BYTES) invalid("manifest.json exceeds its size limit");
+	if (payload.length >= 3 && payload[0] === 0xef && payload[1] === 0xbb && payload[2] === 0xbf) invalid("manifest.json must not carry a byte-order mark");
+	const value = new StrictJsonScanner(payload.toString("utf8")).scanDocument();
+	return value as Record<string, unknown>;
+}
+
+// --- manifest shape ----------------------------------------------------------
+
+function requireExactKeys(value: Record<string, unknown>, allowed: readonly string[], required: readonly string[], where: string): void {
+	for (const key of Object.keys(value)) {
+		if (!allowed.includes(key)) invalid(`${where} has unknown field ${JSON.stringify(key)}`);
+	}
+	for (const key of required) {
+		if (!Object.prototype.hasOwnProperty.call(value, key)) invalid(`${where} is missing field ${JSON.stringify(key)}`);
+	}
+}
+
+function requireString(value: unknown, where: string): string {
+	if (typeof value !== "string" || value === "") invalid(`${where} must be a non-empty string`);
+	return value;
+}
+
+function requireObject(value: unknown, where: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) invalid(`${where} must be a JSON object`);
+	return value as Record<string, unknown>;
+}
+
+interface ManifestFileReference {
+	readonly path: string;
+	readonly sha256: string;
+}
+
+function parseFileReference(value: unknown, where: string): ManifestFileReference {
+	const object = requireObject(value, where);
+	requireExactKeys(object, ["path", "sha256"], ["path", "sha256"], where);
+	const path = requireString(object.path, `${where}.path`);
+	const sha256 = requireString(object.sha256, `${where}.sha256`);
+	if (!isCanonicalBundlePath(path)) invalid(`${where}.path ${JSON.stringify(path)} is unsafe`);
+	if (!SHA256_PATTERN.test(sha256)) invalid(`${where}.sha256 is not a lowercase hex SHA-256`);
+	return { path, sha256 };
+}
+
+interface ManifestRole {
+	readonly id: string;
+	readonly requestSchemaId: string;
+	readonly resultSchemaId: string;
+	readonly requiredCapabilities: readonly string[];
+	readonly schema: ManifestFileReference;
+	readonly vector: ManifestFileReference;
+}
+
+function parseManifestRole(value: unknown, index: number): ManifestRole {
+	const where = `manifest role ${index}`;
+	const object = requireObject(value, where);
+	requireExactKeys(
+		object,
+		["id", "request_schema_id", "result_schema_id", "required_capabilities", "schema", "vector"],
+		["id", "request_schema_id", "result_schema_id", "required_capabilities", "schema", "vector"],
+		where,
+	);
+	const id = requireString(object.id, `${where}.id`);
+	if (!Array.isArray(object.required_capabilities) || object.required_capabilities.length === 0) {
+		invalid(`${where}.required_capabilities must be a non-empty array`);
+	}
+	const requiredCapabilities = object.required_capabilities.map((capability, capabilityIndex) =>
+		requireString(capability, `${where}.required_capabilities[${capabilityIndex}]`),
+	);
+	for (let position = 0; position < requiredCapabilities.length; position += 1) {
+		const capability = requiredCapabilities[position] as string;
+		if (position > 0 && (requiredCapabilities[position - 1] as string) >= capability) {
+			invalid(`${where}.required_capabilities must be strictly sorted and unique`);
+		}
+		if (!KNOWN_MANDATORY_CAPABILITIES.includes(capability)) {
+			invalid(`${where} declares unknown mandatory capability ${JSON.stringify(capability)}`);
+		}
+	}
+	return {
+		id,
+		requestSchemaId: requireString(object.request_schema_id, `${where}.request_schema_id`),
+		resultSchemaId: requireString(object.result_schema_id, `${where}.result_schema_id`),
+		requiredCapabilities,
+		schema: parseFileReference(object.schema, `${where}.schema`),
+		vector: parseFileReference(object.vector, `${where}.vector`),
+	};
+}
+
+interface ParsedManifest {
+	readonly contractSemver: string;
+	readonly major: number;
+	readonly minor: number;
+	readonly patch: number;
+	readonly transportCapability: string;
+	readonly runtimes: readonly string[] | undefined;
+	readonly readme: ManifestFileReference;
+	readonly roles: readonly ManifestRole[];
+}
+
+function parseManifest(payload: Buffer): ParsedManifest {
+	const object = decodeStrictManifestObject(payload);
+	requireExactKeys(
+		object,
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles"],
+		["schema", "contract_semver", "transport_capability", "readme", "roles"],
+		"manifest",
+	);
+	if (object.schema !== PROVIDER_CONTRACT_BUNDLE_SCHEMA) {
+		invalid(`manifest schema must be ${JSON.stringify(PROVIDER_CONTRACT_BUNDLE_SCHEMA)}`);
+	}
+	const contractSemver = requireString(object.contract_semver, "manifest.contract_semver");
+	const semverMatch = SEMVER_PATTERN.exec(contractSemver);
+	if (!semverMatch) invalid(`manifest.contract_semver ${JSON.stringify(contractSemver)} is not exact MAJOR.MINOR.PATCH`);
+	const major = Number(semverMatch[1]);
+	const minor = Number(semverMatch[2]);
+	const patch = Number(semverMatch[3]);
+	if (major !== SUPPORTED_PROVIDER_CONTRACT_MAJOR) {
+		invalid(`unsupported provider contract major ${major}; gentle-pi supports major ${SUPPORTED_PROVIDER_CONTRACT_MAJOR} only`);
+	}
+	const transportCapability = requireString(object.transport_capability, "manifest.transport_capability");
+	if (transportCapability !== PROVIDER_TRANSPORT_CAPABILITY) {
+		invalid(`manifest.transport_capability must be pinned to ${JSON.stringify(PROVIDER_TRANSPORT_CAPABILITY)}`);
+	}
+
+	const runtimesRequired = minor >= RUNTIMES_REQUIRED_SINCE_MINOR;
+	let runtimes: readonly string[] | undefined;
+	if (Object.prototype.hasOwnProperty.call(object, "runtimes")) {
+		if (!runtimesRequired) {
+			invalid(`manifest.runtimes is not part of contract ${contractSemver}; it exists from 1.${RUNTIMES_REQUIRED_SINCE_MINOR}.0`);
+		}
+		if (!Array.isArray(object.runtimes) || object.runtimes.length === 0) invalid("manifest.runtimes must be a non-empty array");
+		const identities = object.runtimes.map((runtime, index) => requireString(runtime, `manifest.runtimes[${index}]`));
+		for (let position = 0; position < identities.length; position += 1) {
+			const identity = identities[position] as string;
+			if (!RUNTIME_IDENTITY_PATTERN.test(identity)) invalid(`manifest.runtimes[${position}] ${JSON.stringify(identity)} is not a runtime identity`);
+			if (position > 0 && (identities[position - 1] as string) >= identity) invalid("manifest.runtimes must be strictly sorted and unique");
+		}
+		runtimes = identities;
+	} else if (runtimesRequired) {
+		invalid(`manifest.runtimes is required from contract 1.${RUNTIMES_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
+	}
+	if (runtimes !== undefined && !runtimes.includes(PI_RUNTIME_IDENTITY)) {
+		// A registry that exists but omits `pi` means this runtime identity is
+		// not registered for the published contract: the relay must not trust it.
+		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+	}
+
+	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
+	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
+	if (roles.length !== PROVIDER_CONTRACT_ROLE_IDS.length) {
+		invalid(`manifest declares ${roles.length} roles; exactly ${PROVIDER_CONTRACT_ROLE_IDS.length} are supported`);
+	}
+	roles.forEach((role, index) => {
+		if (role.id !== PROVIDER_CONTRACT_ROLE_IDS[index]) {
+			invalid(`manifest role ${index} is ${JSON.stringify(role.id)}; expected ${JSON.stringify(PROVIDER_CONTRACT_ROLE_IDS[index])}`);
+		}
+	});
+
+	return {
+		contractSemver,
+		major,
+		minor,
+		patch,
+		transportCapability,
+		runtimes,
+		readme: parseFileReference(object.readme, "manifest.readme"),
+		roles,
+	};
+}
+
+// --- entry-level verification -------------------------------------------------
+
+export function isCanonicalBundlePath(name: string): boolean {
+	if (name === "" || name.includes("\\") || name.startsWith("/") || posixPath.normalize(name) !== name) return false;
+	for (const component of name.split("/")) {
+		if (component === "" || component === "." || component === "..") return false;
+	}
+	return true;
+}
+
+function jsonDeepEqual(left: unknown, right: unknown): boolean {
+	if (left === right) return true;
+	if (Array.isArray(left) && Array.isArray(right)) {
+		return left.length === right.length && left.every((value, index) => jsonDeepEqual(value, right[index]));
+	}
+	if (typeof left === "object" && left !== null && typeof right === "object" && right !== null && !Array.isArray(left) && !Array.isArray(right)) {
+		const leftKeys = Object.keys(left as Record<string, unknown>).sort();
+		const rightKeys = Object.keys(right as Record<string, unknown>).sort();
+		return (
+			leftKeys.length === rightKeys.length &&
+			leftKeys.every(
+				(key, index) =>
+					key === rightKeys[index] &&
+					jsonDeepEqual((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]),
+			)
+		);
+	}
+	return false;
+}
+
+function verifyFileReference(entries: ReadonlyMap<string, Buffer>, reference: ManifestFileReference, expectedPath: string): Buffer {
+	if (reference.path !== expectedPath) invalid(`manifest references ${JSON.stringify(reference.path)}; expected ${JSON.stringify(expectedPath)}`);
+	const payload = entries.get(reference.path);
+	if (payload === undefined) invalid(`bundle is missing ${JSON.stringify(expectedPath)}`);
+	if (sha256Hex(payload) !== reference.sha256) invalid(`bundle entry ${JSON.stringify(expectedPath)} does not match its manifest SHA-256`);
+	return payload;
+}
+
+function verifyRoleArtifacts(entries: ReadonlyMap<string, Buffer>, role: ManifestRole): void {
+	const schemaPath = `schemas/${role.id}.schema.json`;
+	const vectorPath = `vectors/${role.id}.json`;
+	const schemaPayload = verifyFileReference(entries, role.schema, schemaPath);
+	const vectorPayload = verifyFileReference(entries, role.vector, vectorPath);
+
+	let schemaDocument: unknown;
+	try {
+		schemaDocument = JSON.parse(schemaPayload.toString("utf8"));
+	} catch {
+		invalid(`bundle schema ${JSON.stringify(schemaPath)} is not valid JSON`);
+	}
+	const schemaObject = requireObject(schemaDocument, `bundle schema ${JSON.stringify(schemaPath)}`);
+	if (schemaObject["$id"] !== role.resultSchemaId) {
+		invalid(`bundle schema ${JSON.stringify(schemaPath)} $id does not match the manifest result schema id`);
+	}
+	const examples = schemaObject.examples;
+	if (!Array.isArray(examples) || examples.length === 0) invalid(`bundle schema ${JSON.stringify(schemaPath)} has no canonical example`);
+
+	let vectorDocument: unknown;
+	try {
+		vectorDocument = JSON.parse(vectorPayload.toString("utf8"));
+	} catch {
+		invalid(`bundle vector ${JSON.stringify(vectorPath)} is not valid JSON`);
+	}
+	requireObject(vectorDocument, `bundle vector ${JSON.stringify(vectorPath)}`);
+	if (!vectorPayload.toString("utf8").endsWith("\n")) invalid(`bundle vector ${JSON.stringify(vectorPath)} must end with a newline`);
+	if (!jsonDeepEqual(vectorDocument, examples[0])) {
+		invalid(`bundle vector ${JSON.stringify(vectorPath)} does not equal the schema's canonical example`);
+	}
+}
+
+export function bundleTreeSha256(entrySha256: ReadonlyMap<string, string>): string {
+	const lines = [...entrySha256.entries()]
+		.sort(([leftPath], [rightPath]) => (leftPath < rightPath ? -1 : 1))
+		.map(([path, digest]) => `${digest}  ${path}\n`);
+	return sha256Hex(Buffer.from(lines.join(""), "utf8"));
+}
+
+/** Verifies a complete in-memory bundle inventory. The single trust anchor. */
+export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<string, Buffer>): VerifiedProviderContractBundle {
+	if (rawEntries.size !== BUNDLE_ENTRY_COUNT) {
+		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${BUNDLE_ENTRY_COUNT} are expected`);
+	}
+	for (const [name, payload] of rawEntries) {
+		if (!isCanonicalBundlePath(name)) invalid(`bundle path ${JSON.stringify(name)} is unsafe`);
+		if (payload.length > MAX_FILE_BYTES) invalid(`bundle entry ${JSON.stringify(name)} exceeds its size limit`);
+	}
+	const manifestPayload = rawEntries.get("manifest.json");
+	if (manifestPayload === undefined) invalid("bundle is missing manifest.json");
+	const manifest = parseManifest(manifestPayload);
+
+	verifyFileReference(rawEntries, manifest.readme, "README.md");
+	const expected = new Set(["README.md", "manifest.json"]);
+	for (const role of manifest.roles) {
+		verifyRoleArtifacts(rawEntries, role);
+		expected.add(`schemas/${role.id}.schema.json`);
+		expected.add(`vectors/${role.id}.json`);
+	}
+	for (const name of rawEntries.keys()) {
+		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
+	}
+
+	const entries = new Map<string, Buffer>();
+	const entrySha256 = new Map<string, string>();
+	for (const name of [...rawEntries.keys()].sort()) {
+		const payload = rawEntries.get(name) as Buffer;
+		entries.set(name, Buffer.from(payload));
+		entrySha256.set(name, sha256Hex(payload));
+	}
+
+	return {
+		contractSemver: manifest.contractSemver,
+		major: manifest.major,
+		minor: manifest.minor,
+		patch: manifest.patch,
+		transportCapability: manifest.transportCapability,
+		runtimes: manifest.runtimes,
+		roles: manifest.roles.map((role) => ({
+			id: role.id,
+			requestSchemaId: role.requestSchemaId,
+			resultSchemaId: role.resultSchemaId,
+			requiredCapabilities: [...role.requiredCapabilities],
+			schemaPath: role.schema.path,
+			schemaSha256: role.schema.sha256,
+			vectorPath: role.vector.path,
+			vectorSha256: role.vector.sha256,
+		})),
+		entries,
+		entrySha256,
+		treeSha256: bundleTreeSha256(entrySha256),
+	};
+}
+
+/**
+ * Reports whether the verified bundle registers the `pi` runtime identity.
+ *
+ * A 1.0.x bundle predates the runtime registry: it is a valid bundle, but the
+ * relay must treat `pi` as unregistered and must not trust the layout for
+ * host-relay work. From 1.1.0 the registry is mandatory and `pi` membership is
+ * already enforced during verification, so a verified >=1.1.0 bundle is
+ * always registered.
+ */
+export function piRuntimeRegistration(bundle: VerifiedProviderContractBundle): PiRuntimeRegistration {
+	if (bundle.runtimes === undefined) {
+		return {
+			registered: false,
+			reason: `contract ${bundle.contractSemver} predates the runtime identity registry; the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity is not registered and the relay must not trust this bundle`,
+		};
+	}
+	return { registered: bundle.runtimes.includes(PI_RUNTIME_IDENTITY) };
+}
+
+// --- extracted tree reading ---------------------------------------------------
+
+function assertSafeDirectory(path: string): void {
+	const details = lstatSync(path);
+	if (details.isSymbolicLink() || !details.isDirectory()) invalid(`bundle directory ${JSON.stringify(path)} is not a real directory`);
+}
+
+/** Reads and verifies an already-extracted local bundle tree. */
+export function verifyProviderContractBundleTree(directory: string): VerifiedProviderContractBundle {
+	assertSafeDirectory(directory);
+	const entries = new Map<string, Buffer>();
+	const walk = (current: string, relative: string): void => {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const absolute = joinPath(current, entry.name);
+			const relativeName = relative === "" ? entry.name : `${relative}/${entry.name}`;
+			const details = lstatSync(absolute);
+			if (details.isSymbolicLink()) invalid(`bundle tree entry ${JSON.stringify(relativeName)} is a symlink`);
+			if (details.isDirectory()) {
+				walk(absolute, relativeName);
+				continue;
+			}
+			if (!details.isFile()) invalid(`bundle tree entry ${JSON.stringify(relativeName)} is not a regular file`);
+			if (process.platform !== "win32" && (details.mode & FORBIDDEN_MODE_BITS) !== 0) {
+				invalid(`bundle tree entry ${JSON.stringify(relativeName)} has an unsafe file mode`);
+			}
+			if (!isCanonicalBundlePath(relativeName)) invalid(`bundle tree path ${JSON.stringify(relativeName)} is unsafe`);
+			if (details.size > MAX_FILE_BYTES) invalid(`bundle tree entry ${JSON.stringify(relativeName)} exceeds its size limit`);
+			if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`bundle tree has more than ${BUNDLE_ENTRY_COUNT} files`);
+			entries.set(relativeName, readFileSync(absolute));
+		}
+	};
+	walk(directory, "");
+	return verifyProviderContractBundleEntries(entries);
+}
+
+// --- archive reading (bounded, in memory, never extracted to disk) ------------
+
+const TAR_BLOCK_SIZE = 512;
+
+function parseOctalField(field: Buffer, where: string): number {
+	const text = field.toString("ascii").replace(/[\0 ]+$/g, "").replace(/^[\0 ]+/g, "");
+	if (text === "") return 0;
+	if (!/^[0-7]+$/.test(text)) invalid(`tar ${where} field is not octal`);
+	return Number.parseInt(text, 8);
+}
+
+function verifyTarHeaderChecksum(header: Buffer): void {
+	const recorded = parseOctalField(header.subarray(148, 156), "checksum");
+	let computed = 0;
+	for (let index = 0; index < TAR_BLOCK_SIZE; index += 1) {
+		computed += index >= 148 && index < 156 ? 0x20 : (header[index] as number);
+	}
+	if (computed !== recorded) invalid("tar header checksum does not match");
+}
+
+function readTarEntries(expanded: Buffer): Map<string, Buffer> {
+	const entries = new Map<string, Buffer>();
+	let offset = 0;
+	let totalBytes = 0;
+	for (;;) {
+		if (expanded.length - offset < TAR_BLOCK_SIZE) invalid("tar stream ends before a complete header");
+		const header = expanded.subarray(offset, offset + TAR_BLOCK_SIZE);
+		offset += TAR_BLOCK_SIZE;
+		if (header.every((byte) => byte === 0)) {
+			if (expanded.length - offset < TAR_BLOCK_SIZE) invalid("tar stream has an incomplete terminator");
+			const second = expanded.subarray(offset, offset + TAR_BLOCK_SIZE);
+			if (!second.every((byte) => byte === 0)) invalid("tar stream has an incomplete terminator");
+			offset += TAR_BLOCK_SIZE;
+			for (; offset < expanded.length; offset += 1) {
+				if (expanded[offset] !== 0) invalid("tar stream has data after its terminator");
+			}
+			return entries;
+		}
+		verifyTarHeaderChecksum(header);
+		const typeflag = header[156] as number;
+		// Only plain regular files: no symlinks, links, directories, devices,
+		// and no PAX/GNU metadata entries that could smuggle a second identity.
+		if (typeflag !== 0x30 && typeflag !== 0) invalid(`tar entry type ${JSON.stringify(String.fromCharCode(typeflag))} is forbidden`);
+		const prefix = header.subarray(345, 500).toString("ascii").replace(/\0+$/g, "");
+		if (prefix !== "") invalid("tar entry uses the ustar prefix field; canonical bundle paths never need it");
+		const name = header.subarray(0, 100).toString("ascii").replace(/\0+$/g, "");
+		if (!isCanonicalBundlePath(name)) invalid(`tar entry path ${JSON.stringify(name)} is unsafe`);
+		if (entries.has(name)) invalid(`tar entry path ${JSON.stringify(name)} is duplicated`);
+		const mode = parseOctalField(header.subarray(100, 108), "mode");
+		if ((mode & FORBIDDEN_MODE_BITS) !== 0) invalid(`tar entry ${JSON.stringify(name)} has an unsafe file mode`);
+		const size = parseOctalField(header.subarray(124, 136), "size");
+		if (size > MAX_FILE_BYTES) invalid(`tar entry ${JSON.stringify(name)} exceeds its size limit`);
+		totalBytes += size;
+		if (totalBytes > MAX_BUNDLE_BYTES) invalid("tar entries exceed the bundle size limit");
+		if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`tar has more than ${BUNDLE_ENTRY_COUNT} entries`);
+		const padding = (TAR_BLOCK_SIZE - (size % TAR_BLOCK_SIZE)) % TAR_BLOCK_SIZE;
+		if (expanded.length - offset < size + padding) invalid("tar stream ends before a complete entry");
+		entries.set(name, Buffer.from(expanded.subarray(offset, offset + size)));
+		offset += size + padding;
+	}
+}
+
+export interface VerifiedProviderContractArchive {
+	readonly bundle: VerifiedProviderContractBundle;
+	readonly archiveSha256: string;
+}
+
+/** Verifies a local `gentle-ai-review-provider-contract-<semver>.tar.gz` archive in memory. */
+export function verifyProviderContractBundleArchive(archivePath: string): VerifiedProviderContractArchive {
+	const details = lstatSync(archivePath);
+	if (details.isSymbolicLink() || !details.isFile()) invalid("archive is not a regular file");
+	if (details.size > MAX_ARCHIVE_BYTES) invalid("archive exceeds its size limit");
+	const compressed = readFileSync(archivePath);
+	let expanded: Buffer;
+	try {
+		expanded = gunzipSync(compressed, { maxOutputLength: MAX_BUNDLE_BYTES + 1 });
+	} catch {
+		invalid("archive is not a readable gzip stream within the bundle size limit");
+	}
+	if (expanded.length > MAX_BUNDLE_BYTES) invalid("expanded tar exceeds the bundle size limit");
+	const entries = readTarEntries(expanded);
+	return {
+		bundle: verifyProviderContractBundleEntries(entries),
+		archiveSha256: sha256Hex(compressed),
+	};
+}
+
+// --- generated consumer contract surface (P2) ---------------------------------
+
+export const PROVIDER_ROLES_BASELINE_SCHEMA = "gentle-pi.provider-contract-roles-baseline/v1";
+export const PROVIDER_CAPABILITIES_BASELINE_SCHEMA = "gentle-pi.provider-contract-capabilities-baseline/v1";
+export const PROVIDER_ROLES_BASELINE_FILE = "provider-roles.baseline.json";
+export const PROVIDER_CAPABILITIES_BASELINE_FILE = "provider-capabilities.baseline.json";
+
+/**
+ * Deterministically derives the provider-owned consumer contract surface from
+ * a verified bundle. Pi overlays never live in these files; they are pure
+ * projections of the provider bundle and are regenerated, never hand-edited.
+ */
+export function generateProviderContractBaselines(bundle: VerifiedProviderContractBundle): ReadonlyMap<string, string> {
+	const roles = {
+		schema: PROVIDER_ROLES_BASELINE_SCHEMA,
+		contract_semver: bundle.contractSemver,
+		roles: bundle.roles.map((role) => ({
+			id: role.id,
+			request_schema_id: role.requestSchemaId,
+			result_schema_id: role.resultSchemaId,
+			required_capabilities: [...role.requiredCapabilities],
+			schema_path: role.schemaPath,
+			schema_sha256: role.schemaSha256,
+			vector_path: role.vectorPath,
+			vector_sha256: role.vectorSha256,
+		})),
+	};
+	const mandatory = [...new Set(bundle.roles.flatMap((role) => [...role.requiredCapabilities]))].sort();
+	const capabilities = {
+		schema: PROVIDER_CAPABILITIES_BASELINE_SCHEMA,
+		contract_semver: bundle.contractSemver,
+		transport_capability: bundle.transportCapability,
+		mandatory_capabilities: mandatory,
+		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
+		pi_registered: piRuntimeRegistration(bundle).registered,
+	};
+	return new Map([
+		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],
+		[PROVIDER_CAPABILITIES_BASELINE_FILE, `${JSON.stringify(capabilities, null, 2)}\n`],
+	]);
+}