emdash 0.36.0 → 0.38.0

package/src/api/handlers/registry.ts

@@ -1,46 +1,19 @@
 /**
- * Registry plugin install handler.
- *
- * Installs a plugin published to the experimental decentralized plugin
- * registry described in RFC 0001. The install flow:
- *
- *   1. Resolve `(handle, slug)` to a publisher DID via the configured
- *      aggregator's `resolvePackage` XRPC.
- *   2. Look up the requested release (or the policy-filtered latest one)
- *      via `getLatestRelease` / `listReleases`.
- *   3. Require the aggregator's approved listing projection, then apply the
- *      independent release-age and environment policies.
- *   4. Fetch the bundle artifact through an advertised record-scoped cache,
- *      the publisher PDS, or the publisher-declared URL.
- *   5. Verify the artifact's multibase checksum against the signed
- *      release record's `artifacts.package.checksum`.
- *   6. Extract `manifest.json` + `backend.js` + optional `admin.js` from
- *      the gzipped tar bundle.
- *   7. Store the extracted files in site-local R2 under the
- *      `registry/<plugin-id>/<version>/` prefix.
- *   8. Write a `plugin_states` row with `source = "registry"` and the
- *      `(publisher_did, slug)` pair so updates can be resolved later.
- *   9. Sync the runtime so the plugin becomes active immediately.
- *
- * Known gaps (tracked separately):
- *
- *   - The aggregator-supplied records are not yet cryptographically
- *     verified against the publisher's MST signature. The signed bytes
- *     and CIDs are passed through verbatim per the lexicon, but full
- *     PDS-direct verification with proof traversal is follow-up work.
- *     The artifact checksum is verified end-to-end against the value
- *     in the (aggregator-relayed) release record, which is the actual
- *     trust boundary for the bytes that end up in the sandbox.
- *   - Listing approval controls whether metadata is eligible for discovery.
- *     It is never treated as approval of plugin code: checksum, bundle,
- *     manifest, access, consent, sandbox, and environment gates remain
- *     independent below.
+ * Registry installs use aggregator results only for discovery and moderation
+ * metadata. The handler reads profile and release records from the publisher's
+ * PDS, verifies their repository proofs, then validates the bundle checksum,
+ * manifest, policy, and consent before storing or activating executable code.
+ * Applicable labels can block installation but cannot supply any verified
+ * record, checksum, permission, or executable byte.
  */
 
 import { ClientResponseError, ClientValidationError } from "@atcute/client";
 import type { Did } from "@atcute/lexicons";
+import { canonicalizeDeclaredAccess } from "@emdash-cms/plugin-types";
+import type { CanonicalDeclaredAccess } from "@emdash-cms/plugin-types";
 import { checkEnvCompatibility, findSkippedEnvConstraints } from "@emdash-cms/registry-client/env";
 import type { HostEnv } from "@emdash-cms/registry-client/env";
+import { isProvenFirstRelease } from "@emdash-cms/registry-client/listing-policy";
 import { evaluateRegistryReleaseWithdrawal } from "@emdash-cms/registry-client/withdrawal";
 import { NSID } from "@emdash-cms/registry-lexicons";
 import {
@@ -50,8 +23,7 @@ import {
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
-import { extractBundle } from "../../plugins/marketplace.js";
-import type { PluginBundle } from "../../plugins/marketplace.js";
+import { withUnavailableReason } from "../../plugins/sandbox/types.js";
 import type { SandboxRunner } from "../../plugins/sandbox/types.js";
 import { PluginStateRepository } from "../../plugins/state.js";
 import {
@@ -61,6 +33,19 @@ import {
 import { declaredAccessToCapabilities } from "../../plugins/types.js";
 import type { DeclaredAccess } from "../../plugins/types.js";
 import { fetchRegistryArtifactUrl } from "../../registry/artifact-fetch.js";
+import {
+	validateRegistryArtifact,
+	type RegistryArtifactVerificationCode,
+} from "../../registry/artifact-verification.js";
+import {
+	readAuthoritativePackageRelease,
+	verifyAuthoritativePackageRelease,
+	type AuthoritativeRecordErrorCode,
+	type AuthoritativeRecordReader,
+	type AuthoritativeRecordReadOptions,
+	type VerifiedAuthoritativeReleaseReport,
+	type VerifiedAuthoritativeRecords,
+} from "../../registry/authoritative-records.js";
 import {
 	canonicalCapabilitiesForDriftCheck,
 	coerceRegistryConfig,
@@ -69,6 +54,7 @@ import {
 	validateAggregatorUrl,
 } from "../../registry/config.js";
 import { makeRegistryPluginId } from "../../registry/plugin-id.js";
+import { hasCurrentRecordLabel } from "../../registry/record-labels.js";
 import type { RegistryConfigInput } from "../../registry/types.js";
 import { resolveAndValidateExternalUrlTarget } from "../../security/ssrf.js";
 import { EmDashStorageError } from "../../storage/types.js";
@@ -84,8 +70,6 @@ import {
 
 export { assertSafeArtifactUrl } from "../../registry/artifact-fetch.js";
 
-const RELEASE_EXTENSION_NSID = "com.emdashcms.experimental.package.releaseExtension";
-
 /**
  * Whether two `declaredAccess` blocks grant exactly the same enforced access --
  * the same capabilities AND the same host allow-list. Both are lowered through
@@ -104,6 +88,10 @@ export function enforcedAccessEqual(a: DeclaredAccess, b: DeclaredAccess): boole
 	);
 }
 
+function verifiedAccessEqual(a: CanonicalDeclaredAccess, b: DeclaredAccess): boolean {
+	return JSON.stringify(a) === JSON.stringify(canonicalizeDeclaredAccess(b));
+}
+
 // ── Types ──────────────────────────────────────────────────────────
 
 export interface RegistryInstallInput {
@@ -134,6 +122,8 @@ export interface RegistryInstallInput {
 	 */
 	acknowledgedDeclaredAccess?: unknown;
 	acknowledgedMcpTools?: unknown;
+	acknowledgedProfileCid?: string;
+	acknowledgedReleaseCid?: string;
 }
 
 export interface RegistryInstallResult {
@@ -147,84 +137,120 @@ export interface RegistryInstallResult {
 	version: string;
 	/** Capabilities surfaced from the bundle's manifest. */
 	capabilities: string[];
+	declaredAccess: DeclaredAccess;
+	mcpTools: RegistryMcpConsentTool[];
+	verification: RegistryRecordVerificationSummary;
 }
 
-// ── Helpers ────────────────────────────────────────────────────────
-
-/** Matches a bare 64-character lowercase/uppercase hex SHA-256 digest. */
-const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/i;
+export interface RegistryMcpConsentTool {
+	name: string;
+	description: string;
+	route: string;
+	permission: string;
+	destructive: boolean;
+}
 
-/** Compute the SHA-256 of `bytes` as a lowercase hex string. */
-async function sha256Hex(bytes: Uint8Array): Promise<string> {
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Uint8Array is a valid BufferSource at runtime
-	const buf = await crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);
-	const arr = new Uint8Array(buf);
-	return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+export interface RegistryRecordVerificationSummary {
+	profileCid: string;
+	releaseCid: string;
+	provenance: "verified" | "absent-optional";
+	policy: {
+		requireProvenance: boolean;
+		confirmation: "escalation-only" | "always";
+		approvers: string[];
+	};
 }
 
-/** multihash code for sha2-256 (single-byte varint). */
-const MULTIHASH_SHA256_CODE = 0x12;
-/** sha2-256 digest length in bytes (single-byte varint). */
-const MULTIHASH_SHA256_LENGTH = 0x20;
+// ── Helpers ────────────────────────────────────────────────────────
 
-/**
- * Compute the multibase-multihash sha2-256 checksum of `bytes`, in the
- * same `b<base32>` shape the registry CLI publishes
- * (`packages/plugin-cli/src/multihash.ts`). Returns a 56-character
- * string starting with `b`.
- *
- * The trust contract is: if both sides produce the same string for
- * the same bytes, the bytes are unchanged. We don't decode the
- * publisher-supplied checksum -- we just re-encode our own and compare,
- * which is equivalent and avoids needing a base32 decoder.
- */
-async function sha256MultibaseMultihash(bytes: Uint8Array): Promise<string> {
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Uint8Array is a valid BufferSource at runtime
-	const digestBuf = await crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);
-	const digest = new Uint8Array(digestBuf);
-	const multihash = new Uint8Array(2 + digest.length);
-	multihash[0] = MULTIHASH_SHA256_CODE;
-	multihash[1] = MULTIHASH_SHA256_LENGTH;
-	multihash.set(digest, 2);
-	const { toBase32 } = await import("@atcute/multibase");
-	return `b${toBase32(multihash)}`;
+export function registryArtifactError(
+	code: RegistryArtifactVerificationCode,
+	message: string,
+	operation: "install" | "update",
+): ApiResult<never> {
+	let apiCode: string;
+	switch (code) {
+		case "BUNDLE_ID_MISMATCH":
+			apiCode = operation === "install" ? "MANIFEST_ID_MISMATCH" : "BUNDLE_IDENTITY_MISMATCH";
+			break;
+		case "BUNDLE_VERSION_MISMATCH":
+			apiCode = operation === "install" ? "MANIFEST_VERSION_MISMATCH" : code;
+			break;
+		case "CHECKSUM_MISMATCH":
+		case "INVALID_MULTIHASH":
+		case "UNSUPPORTED_MULTIHASH":
+			apiCode = "CHECKSUM_MISMATCH";
+			break;
+		case "FETCH_FAILED":
+		case "HOST_REJECTED":
+		case "REDIRECT_LIMIT_EXCEEDED":
+		case "REDIRECT_LOCATION_MISSING":
+		case "RESOURCE_STATUS_ERROR":
+		case "RESOURCE_TIMEOUT":
+			apiCode = operation === "install" ? "INSTALL_FAILED" : "UPDATE_FAILED";
+			break;
+		default:
+			apiCode = "INVALID_BUNDLE";
+	}
+	return {
+		success: false,
+		error: {
+			code: apiCode,
+			message,
+			details: { verificationCode: code },
+		},
+	};
 }
 
-/**
- * Verify that a checksum string from a release record's
- * `artifact.checksum` field corresponds to the SHA-256 of the given
- * bytes.
- *
- * Accepts two formats:
- *
- *   - Bare lowercase/uppercase hex SHA-256 (64 chars). Convenience for
- *     publishers / tools that emit hex rather than multibase.
- *   - Multibase-multihash with the `b` (base32) prefix and sha2-256.
- *     This is the format RFC 0001 mandates and the registry CLI emits
- *     (see `packages/plugin-cli/src/multihash.ts`).
- *
- * Hash functions other than sha2-256 are out of scope for this
- * initial release; the install fails closed.
- */
-export async function verifyChecksum(bytes: Uint8Array, checksum: string): Promise<boolean> {
-	if (SHA256_HEX_PATTERN.test(checksum)) {
-		const actual = await sha256Hex(bytes);
-		return checksum.toLowerCase() === actual;
-	}
+function registryRecordError(
+	code: AuthoritativeRecordErrorCode,
+	message: string,
+): ApiResult<never> {
+	return {
+		success: false,
+		error: {
+			code: "RECORD_VERIFICATION_FAILED",
+			message,
+			details: { verificationCode: code },
+		},
+	};
+}
 
-	// Multibase-base32 multihash with sha2-256. We re-encode our own
-	// digest in the same shape and compare strings -- equivalent to
-	// decoding and comparing bytes, but doesn't need a base32 decoder.
-	// 56 chars = 'b' + base32(34 bytes) = 'b' + 55 chars.
-	if (checksum.length === 56 && checksum.startsWith("b")) {
-		const actual = await sha256MultibaseMultihash(bytes);
-		// Case-insensitive: multibase 'b' is lowercase by convention but
-		// some emitters use uppercase. RFC 4648 base32 alphabets are
-		// case-insensitive.
-		return actual.toLowerCase() === checksum.toLowerCase();
+function recordConsentError(
+	input: { profileCid?: string; releaseCid?: string },
+	records: VerifiedAuthoritativeRecords,
+): ApiResult<never> | null {
+	if (!input.profileCid || !input.releaseCid) {
+		return {
+			success: false,
+			error: {
+				code: "RECORD_CONSENT_REQUIRED",
+				message: "Verify the signed package records before confirming this action.",
+			},
+		};
 	}
+	if (input.profileCid !== records.profile.cid || input.releaseCid !== records.release.cid) {
+		return {
+			success: false,
+			error: {
+				code: "RECORD_VERIFICATION_DRIFT",
+				message: "The signed package records changed after review. Verify them again.",
+			},
+		};
+	}
+	return null;
+}
 
-	return false;
+function recordVerificationSummary(
+	records: VerifiedAuthoritativeRecords,
+	report: VerifiedAuthoritativeReleaseReport,
+): RegistryRecordVerificationSummary {
+	return {
+		profileCid: records.profile.cid,
+		releaseCid: records.release.cid,
+		provenance: report.provenance.status,
+		policy: report.value.policy,
+	};
 }
 
 /**
@@ -281,6 +307,16 @@ const AGGREGATOR_REQUEST_TIMEOUT_MS = 15_000;
  */
 const AGGREGATOR_TOTAL_BUDGET_MS = 30_000;
 
+class RegistryArtifactFetchError extends Error {
+	constructor(
+		readonly code: RegistryArtifactVerificationCode,
+		message: string,
+	) {
+		super(message);
+		this.name = "RegistryArtifactFetchError";
+	}
+}
+
 /** Build a fetch function that enforces a per-request and per-budget timeout. */
 function timedFetch(totalDeadline: number): typeof fetch {
 	return (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
@@ -339,7 +375,7 @@ async function fetchArtifact(
 		},
 	);
 	if (!result.success) {
-		throw new Error(`Artifact retrieval failed (${result.error.code}): ${result.error.message}`);
+		throw new RegistryArtifactFetchError(result.error.code, result.error.message);
 	}
 	return result.value.bytes;
 }
@@ -398,7 +434,13 @@ export async function handleRegistryInstall(
 	sandboxRunner: SandboxRunner | null,
 	registryConfigInput: RegistryConfigInput | undefined,
 	input: RegistryInstallInput,
-	opts?: { configuredPluginIds?: Set<string>; hostEnv?: HostEnv },
+	opts?: {
+		configuredPluginIds?: Set<string>;
+		hostEnv?: HostEnv;
+		authoritativeRecords?: AuthoritativeRecordReadOptions;
+		readAuthoritativeRecords?: AuthoritativeRecordReader;
+		verifyOnly?: boolean;
+	},
 ): Promise<ApiResult<RegistryInstallResult>> {
 	// Accept either the bare-string shorthand or the full
 	// `RegistryConfig` object (see `RegistryConfigInput`).
@@ -428,7 +470,10 @@ export async function handleRegistryInstall(
 			success: false,
 			error: {
 				code: "SANDBOX_NOT_AVAILABLE",
-				message: "Sandbox runner is required for registry plugins",
+				message: withUnavailableReason(
+					"Sandbox runner is required for registry plugins",
+					sandboxRunner,
+				),
 			},
 		};
 	}
@@ -549,19 +594,9 @@ export async function handleRegistryInstall(
 			};
 		}
 
-		// Identity cross-check on every field the aggregator denormalises
-		// onto the package and release views. A buggy or compromised
-		// aggregator could otherwise return a release view for a
-		// different `(did, slug, version)` than we asked for; the
-		// handler would then fetch + checksum-verify + install bytes
-		// under the requested package's pluginId but for a different
-		// publisher's record. Checksum verification only proves the bytes
-		// match the *returned* record, not that the record belongs to
-		// the package we requested.
-		// `releaseView.release` is validated against the release lexicon by
-		// DiscoveryClient (or `null` if it didn't conform). A `null` here makes
-		// the identity checks below fail closed, which is the desired outcome.
-		const signedRelease = releaseView.release;
+		// The aggregator selects the package/version and supplies mirrors and
+		// moderation metadata. Its copies of the signed records are not
+		// verification inputs.
 		if (packageView.did !== publisherDid || packageView.slug !== slug) {
 			return {
 				success: false,
@@ -574,9 +609,7 @@ export async function handleRegistryInstall(
 		if (
 			releaseView.did !== publisherDid ||
 			releaseView.package !== slug ||
-			signedRelease?.package !== slug ||
-			(requestedVersion !== undefined && releaseView.version !== requestedVersion) ||
-			signedRelease?.version !== releaseView.version
+			(requestedVersion !== undefined && releaseView.version !== requestedVersion)
 		) {
 			return {
 				success: false,
@@ -599,6 +632,55 @@ export async function handleRegistryInstall(
 			};
 		}
 
+		const authoritative = await (opts?.readAuthoritativeRecords ?? readAuthoritativePackageRelease)(
+			publisherDid,
+			slug,
+			version,
+			opts?.authoritativeRecords,
+		);
+		if (!authoritative.success) {
+			return registryRecordError(authoritative.error.code, authoritative.error.message);
+		}
+		const records = authoritative.value;
+		const { profile, release } = records.inspection.value;
+		if (
+			packageView.uri !== records.profile.uri ||
+			packageView.cid !== records.profile.cid ||
+			releaseView.uri !== records.release.uri ||
+			releaseView.cid !== records.release.cid
+		) {
+			return {
+				success: false,
+				error: {
+					code: "AGGREGATOR_RECORD_MISMATCH",
+					message: "Aggregator metadata does not match the publisher's signed records.",
+				},
+			};
+		}
+		if (!opts?.verifyOnly) {
+			const consentError = recordConsentError(
+				{
+					profileCid: input.acknowledgedProfileCid,
+					releaseCid: input.acknowledgedReleaseCid,
+				},
+				records,
+			);
+			if (consentError) return consentError;
+		}
+
+		const packageYanked =
+			hasCurrentRecordLabel(packageView.labels ?? [], "security:yanked", records.profile) ||
+			hasCurrentRecordLabel(packageView.labels ?? [], "security-yanked", records.profile);
+		if (packageYanked) {
+			return {
+				success: false,
+				error: {
+					code: "RELEASE_YANKED",
+					message: "This release has been withdrawn",
+				},
+			};
+		}
+
 		// Environment compatibility remains an install-safety gate. Listing
 		// approval says only that displayed metadata passed moderation. A release
 		// may carry a `requires` block (`env:emdash`, `env:astro`, ...). Refuse
@@ -607,7 +689,7 @@ export async function handleRegistryInstall(
 		// disabled Install button. `requires` is lexicon-`unknown`; the
 		// helper guards its shape.
 		if (opts?.hostEnv) {
-			const envError = assertEnvCompatible(releaseView.release?.requires, opts.hostEnv);
+			const envError = assertEnvCompatible(release.requires, opts.hostEnv);
 			if (envError) return { success: false, error: envError };
 		}
 
@@ -617,13 +699,11 @@ export async function handleRegistryInstall(
 		// must still hit the holdback. The `minimumReleaseAgeExclude`
 		// allowlist short-circuits the check for trusted publisher DIDs.
 		//
-		// Caveat: `releaseView.indexedAt` is aggregator-supplied envelope
-		// data, not a signed timestamp. A compromised aggregator can
-		// claim an arbitrary indexed-at date and bypass the holdback;
-		// closing this gap requires fetching the release record's
-		// signed createdAt from the publisher's PDS (deferred to the
-		// follow-up that adds full MST verification). If the timestamp
-		// is missing or malformed, we fail closed and reject the install.
+		// `releaseView.indexedAt` is aggregator operational data, not part
+		// of the signed release. The release schema has no publication
+		// timestamp, so minimum age remains a local discovery holdback
+		// rather than a cryptographic property. A missing or malformed
+		// timestamp fails closed.
 		// `registryConfig` is the user-supplied integration option, not
 		// the normalized manifest shape, so the duration parse runs once
 		// per install. Catch a malformed value here -- normally caught at
@@ -653,7 +733,9 @@ export async function handleRegistryInstall(
 			const exclude = registryConfig.policy?.minimumReleaseAgeExclude?.map((e) =>
 				e.trim().toLowerCase(),
 			);
-			const exempt = releaseExemptFromMinimumAge(exclude, publisherDid, slug);
+			const exempt =
+				releaseExemptFromMinimumAge(exclude, publisherDid, slug) ||
+				isProvenFirstRelease(packageView);
 			if (!exempt) {
 				const indexedAt = Date.parse(releaseView.indexedAt);
 				if (!Number.isFinite(indexedAt)) {
@@ -728,13 +810,10 @@ export async function handleRegistryInstall(
 			};
 		}
 
-		// Step 4: fetch the artifact bytes.
-		// `releaseView.release` is lexicon-validated by DiscoveryClient (or
-		// `null`); a missing source/checksum (including the `null` case) fails
-		// closed below. Cache descriptors are unsigned aggregator operational data.
-		const release = releaseView.release;
-		const packageArtifact = release?.artifacts?.package;
-		const declaredChecksum = packageArtifact?.checksum;
+		// Step 6: fetch bytes through an aggregator cache, the publisher PDS,
+		// or the URL in the authoritative signed release. Every source remains untrusted.
+		const packageArtifact = release.artifacts.package;
+		const declaredChecksum = release.artifacts.package.checksum;
 
 		if (!packageArtifact || !declaredChecksum) {
 			return {
@@ -746,72 +825,54 @@ export async function handleRegistryInstall(
 			};
 		}
 
-		const artifactBytes = await fetchArtifact(
-			releaseView.artifactCaches ?? [],
-			packageArtifact,
-			{
-				did: publisherDid,
-				collection: NSID.packageRelease,
-				rkey: `${slug}:${version}`,
-				cid: releaseView.cid,
-			},
-			release.auth,
-		);
-
-		// Step 5: verify the bytes against the signed record's checksum.
-		const checksumOk = await verifyChecksum(artifactBytes, declaredChecksum);
-		if (!checksumOk) {
-			return {
-				success: false,
-				error: {
-					code: "CHECKSUM_MISMATCH",
-					message:
-						"Artifact bytes do not match the release record's checksum, or the checksum encoding is unsupported.",
-				},
-			};
-		}
-
-		// Step 6: extract the bundle.
-		let bundle: PluginBundle;
+		let artifactBytes: Uint8Array;
 		try {
-			bundle = await extractBundle(artifactBytes);
-		} catch (err) {
-			return {
-				success: false,
-				error: {
-					code: "INVALID_BUNDLE",
-					message: err instanceof Error ? err.message : "Failed to extract plugin bundle",
+			artifactBytes = await fetchArtifact(
+				releaseView.artifactCaches ?? [],
+				packageArtifact,
+				{
+					did: publisherDid,
+					collection: NSID.packageRelease,
+					rkey: `${slug}:${version}`,
+					cid: releaseView.cid,
 				},
-			};
+				release.auth,
+			);
+		} catch (error) {
+			if (error instanceof RegistryArtifactFetchError) {
+				return registryArtifactError(error.code, error.message, "install");
+			}
+			throw error;
 		}
 
-		// Manifest sanity: declared version must match the release's version.
-		if (bundle.manifest.version !== version) {
-			return {
-				success: false,
-				error: {
-					code: "MANIFEST_VERSION_MISMATCH",
-					message: `Bundle manifest version (${bundle.manifest.version}) does not match release version (${version})`,
-				},
-			};
+		// Steps 6-7: verify the signed checksum, archive, manifest, and
+		// expected package identity with the runtime-neutral verifier used
+		// by the release service.
+		const artifactReport = await validateRegistryArtifact(
+			artifactBytes,
+			declaredChecksum,
+			slug,
+			version,
+		);
+		if (!artifactReport.success) {
+			return registryArtifactError(
+				artifactReport.error.code,
+				artifactReport.error.message,
+				"install",
+			);
 		}
-
-		// Manifest identity: the bundle's `manifest.id` is the publisher's
-		// natural plugin id (their slug). It MUST equal the slug the
-		// install was requested for; otherwise a malicious registry bundle
-		// could declare `manifest.id: "audit-log"` and confuse the sandbox
-		// bridge, which uses `manifest.id` as the trust key for
-		// per-plugin storage, cron schedules, and bridge-scoped
-		// operations.
-		if (bundle.manifest.id !== slug) {
-			return {
-				success: false,
-				error: {
-					code: "MANIFEST_ID_MISMATCH",
-					message: `Bundle manifest id (${bundle.manifest.id}) does not match registry slug (${slug})`,
-				},
-			};
+		const { bundle, artifactDigest, artifactDigests } = artifactReport.value;
+		const recordReport = await verifyAuthoritativePackageRelease(records, artifactDigest, {
+			...opts?.authoritativeRecords,
+			artifactDigests,
+		});
+		if (!recordReport.success) {
+			return registryRecordError(
+				recordReport.code,
+				recordReport.reasons[0]?.message ?? "The release provenance is invalid.",
+			);
 		}
+		const verification = recordVerificationSummary(records, recordReport);
 
 		// Rewrite the manifest's id to the derived opaque pluginId before
 		// it reaches R2 storage or the sandbox loader. The sandbox uses
@@ -829,13 +890,8 @@ export async function handleRegistryInstall(
 		// outside what the user reviewed. The capability-set consent gate below
 		// is blind to constraint content (host scope), so compare the full
 		// enforced access of record vs bundle here and refuse on any difference.
-		const recordExt =
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- extensions is the lexicon's open `unknown` map; narrow to read our own extension
-			(release?.extensions as Record<string, { declaredAccess?: DeclaredAccess }> | undefined)?.[
-				RELEASE_EXTENSION_NSID
-			];
 		if (
-			!enforcedAccessEqual(recordExt?.declaredAccess ?? {}, bundle.manifest.declaredAccess ?? {})
+			!verifiedAccessEqual(recordReport.value.declaredAccess, bundle.manifest.declaredAccess ?? {})
 		) {
 			return {
 				success: false,
@@ -849,13 +905,9 @@ export async function handleRegistryInstall(
 
 		// Capability consent gate: the admin MUST acknowledge the
 		// capabilities the bundle's manifest actually declares before we
-		// install it. The bundle manifest is the only source of truth
-		// the runtime sandbox enforces -- the release record's
-		// `declaredAccess` extension is an aggregator-supplied
-		// assertion that the publisher may or may not have included,
-		// and trusting it would let a malicious publisher (or a
-		// compromised aggregator) ship a bundle whose manifest
-		// requests `content:*` etc. behind an empty consent dialog.
+		// install it. The bundle manifest is the runtime enforcement
+		// currency; the exact-equality check above binds it to the
+		// independently verified signed release.
 		//
 		// Two outcomes after normalization (filter to strings, dedupe,
 		// sort):
@@ -872,7 +924,7 @@ export async function handleRegistryInstall(
 		// the runtime starts enforcing `declaredAccess` natively, this
 		// comparison switches to that shape.
 		const actualCapabilities = canonicalCapabilitiesForDriftCheck(bundle.manifest.capabilities);
-		if (actualCapabilities.length > 0) {
+		if (!opts?.verifyOnly && actualCapabilities.length > 0) {
 			if (input.acknowledgedDeclaredAccess === undefined) {
 				return {
 					success: false,
@@ -902,19 +954,31 @@ export async function handleRegistryInstall(
 		const actualMcpTools = (bundle.manifest.mcp?.tools ?? []).map(
 			({ inputSchema: _, outputSchema: __, ...tool }) => tool,
 		);
-		if (actualMcpTools.length > 0) {
+		if (!opts?.verifyOnly && actualMcpTools.length > 0) {
 			if (JSON.stringify(input.acknowledgedMcpTools) !== JSON.stringify(actualMcpTools)) {
 				return {
 					success: false,
 					error: {
 						code: "MCP_TOOL_CONSENT_REQUIRED",
 						message: "Plugin MCP tools require explicit consent",
-						details: { mcpTools: actualMcpTools },
+						details: { mcpTools: actualMcpTools, verification },
 					},
 				};
 			}
 		}
 
+		const result: RegistryInstallResult = {
+			pluginId,
+			publisherDid,
+			slug,
+			version,
+			capabilities: bundle.manifest.capabilities,
+			declaredAccess: recordReport.value.releaseExtension.declaredAccess,
+			mcpTools: actualMcpTools,
+			verification,
+		};
+		if (opts?.verifyOnly) return { success: true, data: result };
+
 		// Step 7: store in R2 under the registry prefix.
 		await storeBundleInR2(storage, pluginId, version, bundle, "registry");
 
@@ -947,13 +1011,11 @@ export async function handleRegistryInstall(
 		// Cleanup is best-effort; if it also fails, the row failure
 		// still surfaces to the caller and the orphan R2 bundle costs
 		// only the storage of a single checksum-verified zip.
-		// `packageView.profile` is lexicon-validated by DiscoveryClient (or null).
-		const profile = packageView.profile;
 		try {
 			await stateRepo.upsert(pluginId, version, "active", {
 				source: "registry",
-				displayName: profile?.name ?? slug,
-				description: profile?.description ?? undefined,
+				displayName: profile.name ?? slug,
+				description: profile.description ?? undefined,
 				registryPublisherDid: publisherDid,
 				registrySlug: slug,
 			});
@@ -985,13 +1047,7 @@ export async function handleRegistryInstall(
 
 		return {
 			success: true,
-			data: {
-				pluginId,
-				publisherDid,
-				slug,
-				version,
-				capabilities: bundle.manifest.capabilities,
-			},
+			data: result,
 		};
 	} catch (err) {
 		if (err instanceof ClientValidationError) {
@@ -1129,6 +1185,7 @@ export interface RegistryUpdateResult {
 	capabilityChanges: { added: string[]; removed: string[] };
 	/** Set only when `newlyPublic` is non-empty, mirroring marketplace. */
 	routeVisibilityChanges?: { newlyPublic: string[] };
+	verification: RegistryRecordVerificationSummary;
 }
 
 /**
@@ -1153,7 +1210,11 @@ export async function handleRegistryUpdate(
 		confirmCapabilityChanges?: boolean;
 		confirmRouteVisibilityChanges?: boolean;
 		confirmMcpTools?: boolean;
+		acknowledgedProfileCid?: string;
+		acknowledgedReleaseCid?: string;
 		hostEnv?: HostEnv;
+		authoritativeRecords?: AuthoritativeRecordReadOptions;
+		readAuthoritativeRecords?: AuthoritativeRecordReader;
 	},
 ): Promise<ApiResult<RegistryUpdateResult>> {
 	const registryConfig = coerceRegistryConfig(registryConfigInput);
@@ -1175,7 +1236,10 @@ export async function handleRegistryUpdate(
 	if (!sandboxRunner || !sandboxRunner.isAvailable()) {
 		return {
 			success: false,
-			error: { code: "SANDBOX_NOT_AVAILABLE", message: "Sandbox runner is required" },
+			error: {
+				code: "SANDBOX_NOT_AVAILABLE",
+				message: withUnavailableReason("Sandbox runner is required", sandboxRunner),
+			},
 		};
 	}
 	try {
@@ -1264,16 +1328,12 @@ export async function handleRegistryUpdate(
 			};
 		}
 
-		// Identity cross-check. A buggy/compromised aggregator must not
-		// trick us into installing a record signed for a different
-		// (did, slug, version) under this plugin's pluginId.
-		const signedRelease = releaseView.release;
+		// The aggregator selects the target version and supplies mirrors and
+		// moderation metadata. Its release-record copy is not trusted.
 		if (
 			releaseView.did !== publisherDid ||
 			releaseView.package !== slug ||
-			signedRelease?.package !== slug ||
-			(opts?.version !== undefined && releaseView.version !== opts.version) ||
-			signedRelease?.version !== releaseView.version
+			(opts?.version !== undefined && releaseView.version !== opts.version)
 		) {
 			return {
 				success: false,
@@ -1284,6 +1344,16 @@ export async function handleRegistryUpdate(
 				},
 			};
 		}
+		const packageView = await discovery.getPackage({ did: publisherDid, slug });
+		if (!packageView || packageView.did !== publisherDid || packageView.slug !== slug) {
+			return {
+				success: false,
+				error: {
+					code: "AGGREGATOR_IDENTITY_MISMATCH",
+					message: "Aggregator returned a package view that does not match the installed plugin.",
+				},
+			};
+		}
 
 		const newVersion = releaseView.version;
 		if (evaluateRegistryReleaseWithdrawal(releaseView, discovery.labelerPolicy).withdrawn) {
@@ -1301,17 +1371,64 @@ export async function handleRegistryUpdate(
 				},
 			};
 		}
-
+		const authoritative = await (opts?.readAuthoritativeRecords ?? readAuthoritativePackageRelease)(
+			publisherDid,
+			slug,
+			newVersion,
+			opts?.authoritativeRecords,
+		);
+		if (!authoritative.success) {
+			return registryRecordError(authoritative.error.code, authoritative.error.message);
+		}
+		const records = authoritative.value;
+		const { profile, release } = records.inspection.value;
+		if (
+			packageView.uri !== records.profile.uri ||
+			packageView.cid !== records.profile.cid ||
+			releaseView.uri !== records.release.uri ||
+			releaseView.cid !== records.release.cid
+		) {
+			return {
+				success: false,
+				error: {
+					code: "AGGREGATOR_RECORD_MISMATCH",
+					message: "Aggregator metadata does not match the publisher's signed records.",
+				},
+			};
+		}
+		const packageYanked =
+			hasCurrentRecordLabel(packageView.labels ?? [], "security:yanked", records.profile) ||
+			hasCurrentRecordLabel(packageView.labels ?? [], "security-yanked", records.profile);
+		if (packageYanked) {
+			return {
+				success: false,
+				error: { code: "YANKED", message: "Package has been withdrawn" },
+			};
+		}
+		if (
+			opts?.confirmCapabilityChanges ||
+			opts?.confirmRouteVisibilityChanges ||
+			opts?.confirmMcpTools
+		) {
+			const consentError = recordConsentError(
+				{
+					profileCid: opts.acknowledgedProfileCid,
+					releaseCid: opts.acknowledgedReleaseCid,
+				},
+				records,
+			);
+			if (consentError) return consentError;
+		}
 		// Environment compatibility remains independent from listing approval.
 		// An ungated update could otherwise
 		// land a version whose `requires` the host doesn't satisfy. Same
 		// guard as install; `requires` is lexicon-`unknown`.
 		if (opts?.hostEnv) {
-			const envError = assertEnvCompatible(signedRelease.requires, opts.hostEnv);
+			const envError = assertEnvCompatible(release.requires, opts.hostEnv);
 			if (envError) return { success: false, error: envError };
 		}
 
-		const packageArtifact = signedRelease.artifacts?.package;
+		const packageArtifact = release.artifacts.package;
 		const declaredChecksum = packageArtifact?.checksum;
 		if (!packageArtifact || !declaredChecksum) {
 			return {
@@ -1323,47 +1440,50 @@ export async function handleRegistryUpdate(
 			};
 		}
 
-		const artifactBytes = await fetchArtifact(
-			releaseView.artifactCaches ?? [],
-			packageArtifact,
-			{
-				did: publisherDid,
-				collection: NSID.packageRelease,
-				rkey: `${slug}:${newVersion}`,
-				cid: releaseView.cid,
-			},
-			signedRelease.auth,
-		);
-		if (!(await verifyChecksum(artifactBytes, declaredChecksum))) {
-			return {
-				success: false,
-				error: {
-					code: "CHECKSUM_MISMATCH",
-					message: "Artifact bytes do not match the release's published checksum",
+		let artifactBytes: Uint8Array;
+		try {
+			artifactBytes = await fetchArtifact(
+				releaseView.artifactCaches ?? [],
+				packageArtifact,
+				{
+					did: publisherDid,
+					collection: NSID.packageRelease,
+					rkey: `${slug}:${newVersion}`,
+					cid: releaseView.cid,
 				},
-			};
+				release.auth,
+			);
+		} catch (error) {
+			if (error instanceof RegistryArtifactFetchError) {
+				return registryArtifactError(error.code, error.message, "update");
+			}
+			throw error;
 		}
-
-		const bundle: PluginBundle = await extractBundle(artifactBytes);
-
-		if (bundle.manifest.version !== newVersion) {
-			return {
-				success: false,
-				error: {
-					code: "BUNDLE_VERSION_MISMATCH",
-					message: `Bundle manifest version (${bundle.manifest.version}) does not match release version (${newVersion})`,
-				},
-			};
+		const artifactReport = await validateRegistryArtifact(
+			artifactBytes,
+			declaredChecksum,
+			slug,
+			newVersion,
+		);
+		if (!artifactReport.success) {
+			return registryArtifactError(
+				artifactReport.error.code,
+				artifactReport.error.message,
+				"update",
+			);
 		}
-		if (bundle.manifest.id !== slug) {
-			return {
-				success: false,
-				error: {
-					code: "BUNDLE_IDENTITY_MISMATCH",
-					message: `Bundle manifest id (${bundle.manifest.id}) does not match registry slug (${slug})`,
-				},
-			};
+		const { bundle, artifactDigest, artifactDigests } = artifactReport.value;
+		const recordReport = await verifyAuthoritativePackageRelease(records, artifactDigest, {
+			...opts?.authoritativeRecords,
+			artifactDigests,
+		});
+		if (!recordReport.success) {
+			return registryRecordError(
+				recordReport.code,
+				recordReport.reasons[0]?.message ?? "The release provenance is invalid.",
+			);
 		}
+		const verification = recordVerificationSummary(records, recordReport);
 
 		// Rewrite manifest.id to the opaque pluginId so the sandbox loader
 		// and R2 layout stay in sync across install and update.
@@ -1374,13 +1494,8 @@ export async function handleRegistryUpdate(
 		// that changes only the host scope (e.g. api.good.com -> evil.com) keeps
 		// the capability set identical, sails through the escalation diff below,
 		// and installs a bundle enforcing a scope the record never showed.
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- extensions is the lexicon's open `unknown` map; narrow to read our own extension
-		const updateRecordExtensions = signedRelease?.extensions as
-			| Record<string, { declaredAccess?: DeclaredAccess }>
-			| undefined;
-		const recordExt = updateRecordExtensions?.[RELEASE_EXTENSION_NSID];
 		if (
-			!enforcedAccessEqual(recordExt?.declaredAccess ?? {}, bundle.manifest.declaredAccess ?? {})
+			!verifiedAccessEqual(recordReport.value.declaredAccess, bundle.manifest.declaredAccess ?? {})
 		) {
 			return {
 				success: false,
@@ -1406,7 +1521,7 @@ export async function handleRegistryUpdate(
 				error: {
 					code: "CAPABILITY_ESCALATION",
 					message: "Plugin update requires new capabilities",
-					details: { capabilityChanges },
+					details: { capabilityChanges, verification },
 				},
 			};
 		}
@@ -1419,7 +1534,7 @@ export async function handleRegistryUpdate(
 				error: {
 					code: "ROUTE_VISIBILITY_ESCALATION",
 					message: "Plugin update exposes new public (unauthenticated) routes",
-					details: { routeVisibilityChanges, capabilityChanges },
+					details: { routeVisibilityChanges, capabilityChanges, verification },
 				},
 			};
 		}
@@ -1438,6 +1553,7 @@ export async function handleRegistryUpdate(
 					message: "Plugin update changes its MCP tools",
 					details: {
 						mcpTools: newMcpTools.map(({ inputSchema: _, outputSchema: __, ...tool }) => tool),
+						verification,
 					},
 				},
 			};
@@ -1447,28 +1563,20 @@ export async function handleRegistryUpdate(
 		// so a retry of the same update is idempotent.
 		await storeBundleInR2(storage, pluginId, newVersion, bundle, "registry");
 
-		// Update state. Preserve publisher/slug; refresh displayName /
-		// description from the install handler's seeded values (we don't
-		// re-fetch the profile here — that's a separate `getPackage` round
-		// trip and the install-time values are still authoritative for
-		// the same package identity).
+		// Refresh display metadata from the same signed profile used for
+		// release-policy verification.
 		await stateRepo.upsert(pluginId, newVersion, "active", {
 			source: "registry",
 			registryPublisherDid: publisherDid,
 			registrySlug: slug,
-			displayName: existing.displayName ?? slug,
-			description: existing.description ?? undefined,
+			displayName: profile.name ?? slug,
+			description: profile.description ?? undefined,
 			mcpToolsEnabled: false,
 			mcpToolsConsent: null,
 		});
 
 		await syncDeclaredStorageIndexes(db, [bundle.manifest]);
 
-		// Best-effort cleanup of the old bundle. Failures here don't roll
-		// back the upgrade (the new bundle is already stored and committed
-		// in the state row); the orphan is just storage we'll pay for.
-		deleteBundleFromR2(storage, pluginId, oldVersion, "registry").catch(() => {});
-
 		return {
 			success: true,
 			data: {
@@ -1477,6 +1585,7 @@ export async function handleRegistryUpdate(
 				newVersion,
 				capabilityChanges,
 				routeVisibilityChanges: hasNewPublicRoutes ? routeVisibilityChanges : undefined,
+				verification,
 			},
 		};
 	} catch (err) {