emdash 0.36.0 → 0.38.0

package/src/plugins/manager.ts

@@ -26,6 +26,7 @@ import {
 } from "./hooks.js";
 import { PluginRouteRegistry, type RouteResult, type InvokeRouteOptions } from "./routes.js";
 import type {
+	ActorInfo,
 	PluginDefinition,
 	ResolvedPlugin,
 	PluginStorageConfig,
@@ -305,12 +306,14 @@ export class PluginManager {
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
+		id?: string,
+		actor?: ActorInfo,
 	): Promise<{
 		content: Record<string, unknown>;
 		results: HookResult<Record<string, unknown>>[];
 	}> {
 		this.ensureInitialized();
-		return this.hookPipeline!.runContentBeforeSave(content, collection, isNew);
+		return this.hookPipeline!.runContentBeforeSave(content, collection, isNew, id, actor);
 	}
 
 	/**
@@ -320,9 +323,10 @@ export class PluginManager {
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
+		actor?: ActorInfo,
 	): Promise<HookResult<void>[]> {
 		this.ensureInitialized();
-		return this.hookPipeline!.runContentAfterSave(content, collection, isNew);
+		return this.hookPipeline!.runContentAfterSave(content, collection, isNew, actor);
 	}
 
 	/**

package/src/plugins/manifest-schema.ts

@@ -243,7 +243,7 @@ const pluginAdminConfigSchema = z.object({
 								action_id: z.string(),
 								label: z.string().optional(),
 							})
-							.passthrough(),
+							.loose(),
 					)
 					.optional(),
 			}),

package/src/plugins/routes.ts

@@ -8,6 +8,8 @@
  *
  */
 
+import { z } from "zod";
+
 import { MediaUsageActivationWriteBlockedError } from "../api/media-usage-write-fence.js";
 import { PluginContextFactory, type PluginContextFactoryOptions } from "./context.js";
 import { extractRequestMeta } from "./request-meta.js";
@@ -215,7 +217,7 @@ export class PluginRouteHandler {
 					error: {
 						code: "VALIDATION_ERROR",
 						message: "Invalid request body",
-						details: parseResult.error.format(),
+						details: z.formatError(parseResult.error),
 					},
 					status: 400,
 				};

package/src/plugins/sandbox/hook-result.ts

@@ -0,0 +1,52 @@
+/** Current wire-format version for sandbox hook result envelopes. */
+export const SANDBOX_HOOK_RESULT_VERSION = 1 as const;
+
+/** Maximum editor-facing rejection reason accepted from a sandboxed plugin. */
+export const MAX_SANDBOX_SAVE_REJECTION_REASON_LENGTH = 500;
+
+export interface SandboxSaveRejectedError {
+	code: "SAVE_REJECTED";
+	reason: string;
+}
+
+/**
+ * Returned from a sandboxed `content:beforeSave` hook to reject the save.
+ * The host validates every field before exposing the reason to an editor.
+ */
+export interface SandboxHookErrorEnvelope {
+	__emdashSandboxHookResult: true;
+	version: typeof SANDBOX_HOOK_RESULT_VERSION;
+	error: SandboxSaveRejectedError;
+}
+
+export type SandboxHookResultInspection =
+	| { kind: "value" }
+	| { kind: "malformed" }
+	| { kind: "error"; error: SandboxSaveRejectedError };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validate and normalize an untrusted value returned across the sandbox boundary. */
+export function inspectSandboxHookResult(value: unknown): SandboxHookResultInspection {
+	if (!isRecord(value) || !Object.hasOwn(value, "__emdashSandboxHookResult")) {
+		return { kind: "value" };
+	}
+	if (
+		value.__emdashSandboxHookResult !== true ||
+		value.version !== SANDBOX_HOOK_RESULT_VERSION ||
+		!isRecord(value.error) ||
+		value.error.code !== "SAVE_REJECTED" ||
+		typeof value.error.reason !== "string"
+	) {
+		return { kind: "malformed" };
+	}
+
+	const reason = value.error.reason.trim();
+	if (reason.length === 0 || reason.length > MAX_SANDBOX_SAVE_REJECTION_REASON_LENGTH) {
+		return { kind: "malformed" };
+	}
+
+	return { kind: "error", error: { code: "SAVE_REJECTED", reason } };
+}

package/src/plugins/sandbox/index.ts

@@ -11,6 +11,11 @@ export {
 	getSandboxRouteErrorDetails,
 	getSandboxRouteErrorEnvelope,
 } from "./types.js";
+export {
+	MAX_SANDBOX_SAVE_REJECTION_REASON_LENGTH,
+	SANDBOX_HOOK_RESULT_VERSION,
+	inspectSandboxHookResult,
+} from "./hook-result.js";
 
 export type {
 	SandboxRunner,
@@ -26,3 +31,8 @@ export type {
 	SandboxRouteErrorDetails,
 	SandboxRouteErrorEnvelope,
 } from "./types.js";
+export type {
+	SandboxHookErrorEnvelope,
+	SandboxHookResultInspection,
+	SandboxSaveRejectedError,
+} from "./hook-result.js";

package/src/plugins/sandbox/types.ts

@@ -236,6 +236,15 @@ export interface SandboxRunner {
 	 */
 	isHealthy(): boolean;
 
+	/**
+	 * Why the runner cannot run plugins, once isAvailable() or isHealthy()
+	 * has returned false. A lowercase clause without a final period: callers
+	 * append it to their own message after a colon.
+	 *
+	 * Making this required breaks runners implemented outside this repository.
+	 */
+	unavailableReason?(): string;
+
 	/**
 	 * Load a sandboxed plugin from code.
 	 *
@@ -260,6 +269,11 @@ export interface SandboxRunner {
 	terminateAll(): Promise<void>;
 }
 
+export function withUnavailableReason(message: string, runner: SandboxRunner | null): string {
+	const reason = runner?.unavailableReason?.();
+	return reason ? `${message}: ${reason}` : message;
+}
+
 /**
  * Error thrown when the sandbox runtime is unavailable.
  * This happens when the sidecar process has crashed or hasn't started.
@@ -273,11 +287,11 @@ export class SandboxUnavailableError extends Error {
 
 /**
  * Factory function type for creating sandbox runners.
- * Exported by platform adapters (e.g., @emdash-cms/adapter-cloudflare/sandbox).
+ * Exported by platform adapters (e.g., @emdash-cms/cloudflare/sandbox).
  *
  * @example
  * ```typescript
- * // In @emdash-cms/adapter-cloudflare/sandbox.ts
+ * // In @emdash-cms/cloudflare/sandbox
  * export const createSandboxRunner: SandboxRunnerFactory = (options) => {
  *   return new CloudflareSandboxRunner(options);
  * };

package/src/plugins/storage-query.ts

@@ -25,6 +25,38 @@ export class StorageQueryError extends Error {
 	}
 }
 
+/**
+ * Error thrown when a guarded `updateIf` loses a concurrent race by aborting
+ * rather than resolving to `{ applied: false }`.
+ *
+ * `updateIf`'s `{ applied: false }` contract (row absent OR guard failed)
+ * assumes READ COMMITTED — the default. There, a losing concurrent writer
+ * re-evaluates the guard against the winner's freshly committed row and
+ * cleanly resolves to `{ applied: false }`. Two aborts escape that contract:
+ *
+ * - `40001` (serialization_failure), only above READ COMMITTED, where the
+ *   loser cannot re-read against a newer snapshot.
+ * - `40P01` (deadlock_detected), at any isolation level, when transactions
+ *   take row locks in opposite order.
+ *
+ * This error surfaces either abort so the caller can retry the write.
+ *
+ * The no-oversell SAFETY invariant holds either way: a losing writer NEVER
+ * applies its update — it either sees `{ applied: false }` or throws here.
+ */
+export class StorageSerializationError extends Error {
+	readonly code = "STORAGE_SERIALIZATION_FAILURE";
+	readonly retryable = true;
+	/** The Postgres SQLSTATE that triggered this error (`40001` / `40P01`). */
+	readonly sqlState?: string;
+
+	constructor(message: string, options?: { cause?: unknown; sqlState?: string }) {
+		super(message, { cause: options?.cause });
+		this.name = "StorageSerializationError";
+		this.sqlState = options?.sqlState;
+	}
+}
+
 /**
  * Check if a value is a range filter
  */
@@ -213,6 +245,17 @@ export function buildCondition(
 		if (value.lt !== undefined) pushBound("<", value.lt);
 		if (value.lte !== undefined) pushBound("<=", value.lte);
 
+		// A filter with no defined bound contributes no SQL. Returning it would
+		// widen the caller's predicate to "match everything" — survivable in a
+		// read, but it strips the guard off a conditional write.
+		if (conditions.length === 0) {
+			throw new StorageQueryError(
+				`Range filter for field '${field}' has no defined bound`,
+				field,
+				"Provide at least one of gt, gte, lt, or lte, or omit the field.",
+			);
+		}
+
 		return {
 			sql: conditions.join(" AND "),
 			params,
@@ -238,6 +281,8 @@ export function buildWhereClause(
 
 	for (const [field, value] of Object.entries(where)) {
 		const condition = buildCondition(db, field, value);
+		// An empty slot in the join would emit `<cond> AND ` and fail to parse.
+		if (!condition.sql) continue;
 		conditions.push(condition.sql);
 		params.push(...condition.params);
 	}

package/src/plugins/storage-update.ts

@@ -0,0 +1,96 @@
+import { validateJsonFieldName } from "../database/validate.js";
+import type { RangeFilter, WhereClause, WhereValue } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+	if (!isRecord(value)) {
+		throw new TypeError(`${label} must be an object`);
+	}
+	const prototype: unknown = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new TypeError(`${label} must be a plain object`);
+	}
+	return value;
+}
+
+function operand(value: unknown): string | number {
+	if (typeof value === "string" || (typeof value === "number" && Number.isFinite(value))) {
+		return value;
+	}
+	throw new TypeError("Storage guard operands must be strings or finite numbers");
+}
+
+function normalizeFilter(value: unknown): WhereValue {
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string" || typeof value === "number") return operand(value);
+	const filter = requireRecord(value, "Storage guard filter");
+	const values = filter.in;
+	if (Array.isArray(values)) {
+		return { in: Array.from(values, operand) };
+	}
+	const prefix = filter.startsWith;
+	if (typeof prefix === "string") {
+		return { startsWith: prefix };
+	}
+	const range: RangeFilter = {};
+	for (const key of ["gt", "gte", "lt", "lte"] as const) {
+		if (key in filter) {
+			const bound = filter[key];
+			range[key] = bound === undefined ? undefined : operand(bound);
+		}
+	}
+	return range;
+}
+
+export function parseStorageUpdate(value: unknown): {
+	where: WhereClause;
+	setEntries: Array<[string, unknown]>;
+	deltaEntries: Array<[string, number]>;
+} {
+	const args = requireRecord(value, "Storage update arguments");
+	if (Object.keys(args).some((key) => key !== "where" && key !== "set" && key !== "delta")) {
+		throw new TypeError("Unknown storage update argument");
+	}
+	const where: WhereClause = {};
+	for (const [field, filter] of Object.entries(requireRecord(args.where, "Storage where guard"))) {
+		validateJsonFieldName(field);
+		where[field] = normalizeFilter(filter);
+	}
+	const set = args.set === undefined ? {} : requireRecord(args.set, "Storage set");
+	const delta = args.delta === undefined ? {} : requireRecord(args.delta, "Storage delta");
+	const setEntries: Array<[string, unknown]> = [];
+	for (const [field, entry] of Object.entries(set)) {
+		if (entry === undefined) continue;
+		validateJsonFieldName(field);
+		const serialized = JSON.stringify(entry);
+		if (serialized === undefined)
+			throw new TypeError("Storage set values must be JSON serializable");
+		const normalized: unknown = JSON.parse(serialized);
+		setEntries.push([field, normalized]);
+	}
+	const setFields = new Set(setEntries.map(([field]) => field));
+	const deltaEntries: Array<[string, number]> = [];
+	for (const [field, entry] of Object.entries(delta)) {
+		if (entry === undefined) continue;
+		validateJsonFieldName(field);
+		if (setFields.has(field)) throw new TypeError("Storage field appears in both set and delta");
+		const spec = requireRecord(entry, "Storage numeric delta");
+		const keys = Object.keys(spec);
+		const key = keys[0];
+		if (keys.length !== 1 || (key !== "inc" && key !== "dec")) {
+			throw new TypeError("Storage delta must contain exactly one of inc or dec");
+		}
+		const amount = spec[key];
+		if (typeof amount !== "number" || !Number.isSafeInteger(amount)) {
+			throw new TypeError("Storage delta must be a safe integer");
+		}
+		deltaEntries.push([field, key === "dec" ? -amount : amount]);
+	}
+	if (setEntries.length + deltaEntries.length === 0) {
+		throw new TypeError("Storage update requires at least one of set or delta");
+	}
+	return { where, setEntries, deltaEntries };
+}

package/src/plugins/types.ts

@@ -135,6 +135,71 @@ export interface PaginatedResult<T> {
 	hasMore: boolean;
 }
 
+export interface VersionedValue<T = unknown> {
+	value: T;
+	/** Opaque host revision, valid only for the key from which it was read. */
+	revision: string;
+}
+
+export type ConditionalWriteResult = { applied: true; revision: string } | { applied: false };
+
+export interface ConditionalDeleteResult {
+	applied: boolean;
+}
+
+/**
+ * A single per-field integer delta for {@link StorageCollection.updateIf}.
+ *
+ * `inc`/`dec` values must be safe integers, enforced at runtime with
+ * `Number.isSafeInteger` (which also rejects `NaN`/`Infinity`), because a TS
+ * `number` cannot forbid float literals. Deltas are applied entirely in-SQL
+ * over the stored value with `COALESCE(<value>, 0) ± n`, so a delta on a
+ * missing or JSON-`null` field starts from `0` (never corrupts the document).
+ *
+ * `updateIf` does NOT clamp: a `dec` can drive a field negative when the
+ * `where` guard doesn't cover the delta magnitude (e.g. stock `2` with
+ * `where: { stock: { gte: 1 } }` and `delta: { stock: { dec: 3 } }` → `-1`,
+ * `applied: true`). The guard is the caller's responsibility — pair a `dec: k`
+ * with a `gte: k` guard to prevent underflow.
+ */
+export type NumericDelta = { inc: number } | { dec: number };
+
+/**
+ * Arguments to {@link StorageCollection.updateIf}.
+ *
+ * `where` reuses the {@link QueryOptions} `WhereClause` verbatim — the guard is
+ * evaluated in-SQL with the same numeric-correct, total comparisons as
+ * `query()`. An empty `where: {}` emits no guard, i.e. it matches the row
+ * unconditionally (update-if-row-exists) — a footgun in the no-oversell case,
+ * where a real predicate (e.g. `{ stock: { gte: 1 } }`) is what you want.
+ *
+ * At least one of `set` / `delta` must be present (a runtime error is thrown
+ * otherwise). A field may not appear in both `set` and `delta` in the same
+ * call. `set` and `delta` are separate arguments (not a union) so a wholesale
+ * value that happens to look like `{ inc: 5 }` is never mistaken for a delta.
+ */
+export interface UpdateIfArgs<T> {
+	/**
+	 * Guard evaluated in-SQL; identical semantics to `query({ where })`. An
+	 * empty `{}` means "match the row unconditionally (no guard)".
+	 */
+	where: WhereClause;
+	/** Wholesale field values merged into the stored JSON document. */
+	set?: Partial<T>;
+	/** Per-field integer deltas applied in-SQL (`COALESCE(base, 0) ± n`). */
+	delta?: { [K in keyof T]?: NumericDelta };
+}
+
+/**
+ * Result of {@link StorageCollection.updateIf}.
+ *
+ * `applied: false` intentionally conflates "row absent" and "guard failed": a
+ * single-statement guarded `UPDATE` cannot distinguish them, and the caller
+ * should not need to. `updateIf` is update-only — it never inserts a missing
+ * row.
+ */
+export type UpdateIfResult<T> = { applied: true; data: T } | { applied: false };
+
 /**
  * Storage collection interface - the API exposed to plugins
  * No async iterators - all operations return promises with pagination
@@ -145,6 +210,15 @@ export interface StorageCollection<T = unknown> {
 	put(id: string, data: T): Promise<void>;
 	delete(id: string): Promise<boolean>;
 	exists(id: string): Promise<boolean>;
+	/** A stored JSON null returns an envelope with value: null; only an absent row returns null. */
+	getVersioned(id: string): Promise<VersionedValue<T> | null>;
+	/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+	compareAndSet(
+		id: string,
+		expectedRevision: string | null,
+		data: T,
+	): Promise<ConditionalWriteResult>;
+	compareAndDelete(id: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
 
 	// Batch operations
 	getMany(ids: string[]): Promise<Map<string, T>>;
@@ -154,6 +228,23 @@ export interface StorageCollection<T = unknown> {
 	// Query - always paginated
 	query(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>>;
 	count(where?: WhereClause): Promise<number>;
+
+	// Conditional write (single-statement, atomic per row).
+	/**
+	 * Predicate-guarded atomic update. Applies `set`/`delta` to the row `id`
+	 * only if it exists and the `where` guard matches, in a single guarded
+	 * `UPDATE … RETURNING`. This is the no-oversell primitive: the guard and the
+	 * arithmetic live in one statement, so N concurrent guarded decrements
+	 * serialize correctly. `applied: false` means the row was absent OR the
+	 * guard failed (the two are intentionally indistinguishable). Non-object
+	 * documents, invalid counters and unsafe arithmetic results also fail the
+	 * guard. Never inserts.
+	 *
+	 * Serialization failures and deadlocks throw `StorageSerializationError`.
+	 * Retry the write with a bounded policy; restart an explicit transaction
+	 * before retrying its operations.
+	 */
+	updateIf(id: string, args: UpdateIfArgs<T>): Promise<UpdateIfResult<T>>;
 }
 
 /**
@@ -176,6 +267,14 @@ export type PluginStorage<T extends PluginStorageConfig> = {
  */
 export interface KVAccess {
 	get<T>(key: string): Promise<T | null>;
+	getVersioned<T>(key: string): Promise<VersionedValue<T> | null>;
+	/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+	compareAndSet(
+		key: string,
+		expectedRevision: string | null,
+		value: unknown,
+	): Promise<ConditionalWriteResult>;
+	compareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
 	set(key: string, value: unknown): Promise<void>;
 	delete(key: string): Promise<boolean>;
 	list(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;
@@ -804,6 +903,15 @@ export interface HookConfig<THandler> {
 	handler: THandler;
 }
 
+/**
+ * Acting user that triggered a content hook. Present for authenticated
+ * saves; absent for unauthenticated or internal writes.
+ */
+export interface ActorInfo {
+	readonly id: string;
+	readonly role: number;
+}
+
 /**
  * Content hook event
  */
@@ -811,6 +919,18 @@ export interface ContentHookEvent {
 	content: Record<string, unknown>;
 	collection: string;
 	isNew: boolean;
+	/**
+	 * ID of the existing item on `content:beforeSave` for an update. Absent on
+	 * creates, where the ID is assigned when the save completes, and on
+	 * `content:afterSave`, where `content.id` carries it.
+	 */
+	id?: string;
+	/**
+	 * The acting user for this save. Carries the same authenticated identity
+	 * used to set the revision author, so plugins (e.g. audit logs) can record
+	 * who made the change.
+	 */
+	actor?: ActorInfo;
 }
 
 /**

package/src/query.ts

@@ -24,7 +24,7 @@
  * import resolves there at typecheck time without our help.
  */
 
-import { encodeCursor } from "./database/repositories/types.js";
+import { encodeCursor, type ContentSeo } from "./database/repositories/types.js";
 import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./i18n/config.js";
 import {
 	creditsFromFoldedBylines,
@@ -40,8 +40,10 @@ import {
 	contentNamespaces,
 	invalidateSchemaObjectCache,
 } from "./object-cache/index.js";
+import { primeSeoPanel } from "./page/seo-panel.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
+import { resetRegisteredCollectionsCache } from "./schema/collection-slugs-cache.js";
 import { compileUrlPattern } from "./schema/url-pattern.js";
 import type { TaxonomyTerm } from "./taxonomies/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
@@ -398,8 +400,21 @@ export async function getEmDashCollection<T extends string, D = InferCollectionD
 	// Cursor-paginated calls are exempt: their limit is part of the
 	// pagination contract.
 	const bucketed = bucketFilter(filter);
+
+	// Preview and edit-mode requests skip `loadCollectionCached`. That path
+	// reduces every entry to a JSON snapshot (`entrySnapshot`) and rebuilds it
+	// with `reviveEntry`, which cannot carry the `edit` proxy and re-attaches
+	// the no-op — so annotations spread as `{...entry.edit.title}` would render
+	// nothing on list pages. `getEmDashEntry` has the same bypass for the same
+	// reason (see its `serveDrafts` branch). The request-scoped cache still
+	// collapses duplicate queries within the render.
+	const ctx = getRequestContext();
+	const serveDrafts = ctx?.editMode === true || ctx?.preview !== undefined;
+
 	const cached = await requestCached(collectionCacheKey(type, bucketed.fetchFilter), () =>
-		loadCollectionCached<T, D>(type, bucketed.fetchFilter),
+		serveDrafts
+			? getEmDashCollectionUncached<T, D>(type, bucketed.fetchFilter)
+			: loadCollectionCached<T, D>(type, bucketed.fetchFilter),
 	);
 	return bucketed.requestedLimit === undefined
 		? cached
@@ -979,6 +994,15 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 	}
 	const revived = snapshot.value.entry ? reviveEntry<D>(snapshot.value.entry) : null;
 	if (revived && !canExposeRevisionMetadata(revived, type)) stripRevisionMetadata(revived);
+	if (revived) {
+		// On a warm object-cache hit the loader never runs, so prime the
+		// SEO panel cache from the snapshot's data (a no-op after a miss,
+		// where the loader already primed).
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- snapshot `data` is always a record
+		const { id: rowId, seo } = revived.data as Record<string, unknown>;
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- `data.seo` is written by the loader as ContentSeo
+		if (seo && typeof rowId === "string") primeSeoPanel(type, rowId, seo as ContentSeo);
+	}
 	return {
 		entry: revived,
 		isPreview: snapshot.value.isPreview,
@@ -1326,11 +1350,13 @@ const urlPatternCache: UrlPatternCache =
  * Call when collection URL patterns change (schema updates).
  *
  * Also busts the distributed schema cache (collection metadata such as
- * `commentsEnabled`, `supports`, fields read by `getCollectionInfo`), since
+ * `commentsEnabled`, `supports`, fields read by `getCollectionInfo`) and the
+ * per-isolate registered-collection-slugs cache used by term counting, since
  * every schema-mutation path already routes through here.
  */
 export function invalidateUrlPatternCache(): void {
 	urlPatternCache.patterns = null;
+	resetRegisteredCollectionsCache();
 	invalidateSchemaObjectCache();
 }
 

package/src/registry/artifact-checksum.ts

@@ -0,0 +1,15 @@
+import { verifyMultihash } from "@emdash-cms/registry-verification/checksum";
+
+const SHA256_HEX_PATTERN = /^[0-9a-fA-F]{64}$/;
+
+export async function verifyRegistryArtifactChecksum(
+	bytes: Uint8Array,
+	checksum: string,
+): Promise<boolean> {
+	if (SHA256_HEX_PATTERN.test(checksum)) {
+		const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)));
+		const actual = Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+		return actual === checksum.toLowerCase();
+	}
+	return (await verifyMultihash(bytes, checksum)).success;
+}

package/src/registry/artifact-verification.ts

@@ -0,0 +1,85 @@
+import type { VerificationErrorCode } from "@emdash-cms/registry-verification";
+import { validatePluginBundle } from "@emdash-cms/registry-verification/bundle";
+import {
+	computeArtifactDigestCandidates,
+	verifyMultihash,
+} from "@emdash-cms/registry-verification/checksum";
+
+import { pluginManifestSchema, reconcileManifestAccess } from "../plugins/manifest-schema.js";
+import type { PluginBundle } from "../plugins/marketplace.js";
+
+const bundleDecoder = new TextDecoder("utf-8", { fatal: true });
+
+export type RegistryArtifactVerificationCode =
+	| VerificationErrorCode
+	| "BUNDLE_INVALID_CODE_ENCODING"
+	| "BUNDLE_RUNTIME_UNSUPPORTED";
+
+export type RegistryArtifactVerificationResult =
+	| {
+			success: true;
+			value: {
+				bundle: PluginBundle;
+				artifactDigest: Uint8Array;
+				artifactDigests: readonly Uint8Array[];
+			};
+	  }
+	| {
+			success: false;
+			error: { code: RegistryArtifactVerificationCode; message: string };
+	  };
+
+export async function validateRegistryArtifact(
+	bytes: Uint8Array,
+	checksum: string,
+	slug: string,
+	version: string,
+): Promise<RegistryArtifactVerificationResult> {
+	const checksumReport = await verifyMultihash(bytes, checksum);
+	if (!checksumReport.success) return checksumReport;
+	const [artifactDigest, ...artifactDigests] = await computeArtifactDigestCandidates(bytes);
+
+	const bundleReport = await validatePluginBundle(bytes, {
+		expectedSlug: slug,
+		expectedVersion: version,
+	});
+	if (!bundleReport.success) return bundleReport;
+
+	const manifest = pluginManifestSchema.safeParse(bundleReport.value.manifest);
+	if (!manifest.success) {
+		return {
+			success: false,
+			error: {
+				code: "BUNDLE_RUNTIME_UNSUPPORTED",
+				message: "The plugin bundle uses manifest features unsupported by this EmDash version.",
+			},
+		};
+	}
+
+	try {
+		return {
+			success: true,
+			value: {
+				bundle: {
+					manifest: reconcileManifestAccess(manifest.data),
+					backendCode: bundleDecoder.decode(bundleReport.value.backend),
+					adminCode:
+						bundleReport.value.admin === undefined
+							? undefined
+							: bundleDecoder.decode(bundleReport.value.admin),
+					checksum,
+				},
+				artifactDigest,
+				artifactDigests,
+			},
+		};
+	} catch {
+		return {
+			success: false,
+			error: {
+				code: "BUNDLE_INVALID_CODE_ENCODING",
+				message: "Plugin bundle code must be valid UTF-8.",
+			},
+		};
+	}
+}