@velora-cms/server 0.11.0

package/dist/plugins/structured-snapshot-service.js

@@ -0,0 +1,286 @@
+import { randomUUID } from "node:crypto";
+import { deriveSnapshotGroups } from "./snapshot-groups.js";
+const SNAPSHOT_PAGE_SIZE = 500;
+// True only for a genuine "table does not exist" error from the active
+// dialect's driver — checked unconditionally across all three shapes rather
+// than switching on adapter.dialect, since the codes never collide:
+// Postgres (node-postgres) sets SQLSTATE 42P01 (undefined_table) on `.code`;
+// MySQL (mysql2) sets `.errno` 1146 / `.code` "ER_NO_SUCH_TABLE"; SQLite
+// (better-sqlite3) has no error code for this and only a message matching
+// /no such table/i. Anything else (a dropped connection, a real bug, a
+// transient network blip) must NOT match here — snapshotPluginTables
+// rethrows those, which aborts the uninstall before its cleanup step runs,
+// so a live table's rows are never dropped without ever having been
+// captured.
+function isTableMissingError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const err = error;
+    if (err.code === "42P01")
+        return true; // Postgres: undefined_table
+    if (err.errno === 1146 || err.code === "ER_NO_SUCH_TABLE")
+        return true; // MySQL
+    if (/no such table/i.test(err.message))
+        return true; // SQLite
+    return false;
+}
+// Not a reuse of packages/content-service's SnapshotService — that one is
+// a version POINTER (content is immutable, nothing is ever really at
+// risk). Structured-storage rows are genuinely mutable, so this has to be
+// a real schema+data dump. Talks to DatabaseAdapter directly, never
+// through the registry-gated StructuredStorageAPI — by the time any of
+// this runs the plugin is either mid-uninstall or already uninstalled,
+// so the registry gate would reject it anyway.
+export class StructuredSnapshotService {
+    adapter;
+    prisma;
+    constructor(adapter, prisma) {
+        this.adapter = adapter;
+        this.prisma = prisma;
+    }
+    async snapshotPluginTables(pluginId, trigger) {
+        const tables = await this.prisma.pluginStructuredTable.findMany({ where: { pluginId } });
+        const snapshotGroupId = randomUUID();
+        // No transaction wraps this loop: if a later table rethrows (genuine
+        // failure, not a missing table), any PluginStructuredSnapshot rows
+        // already written for earlier tables under this snapshotGroupId are
+        // NOT rolled back. That's fine — the caller never sees a returned
+        // groupId for an aborted call (the throw propagates out before the
+        // `return` below), so nothing ever restores or drops against this
+        // groupId. The leftover partial rows are inert orphans, not a
+        // correctness or data-loss risk.
+        for (const table of tables) {
+            const schema = table.schema;
+            const pkColumn = schema.columns.find((c) => c.primaryKey).name;
+            const rows = [];
+            let cursor;
+            try {
+                // Cursor-walks to completion rather than one unbounded query — same
+                // pattern the Session 86 conformance tests already establish.
+                for (;;) {
+                    const page = await this.adapter.queryRows(table.physicalTableName, schema, {
+                        cursor,
+                        limit: SNAPSHOT_PAGE_SIZE,
+                    });
+                    rows.push(...page);
+                    if (page.length < SNAPSHOT_PAGE_SIZE)
+                        break;
+                    cursor = String(page[page.length - 1][pkColumn]);
+                }
+            }
+            catch (error) {
+                if (!isTableMissingError(error)) {
+                    // Anything other than a genuine "table does not exist" error —
+                    // e.g. a transient connection failure on a table that's still
+                    // very much live — must propagate. Swallowing it here would mean
+                    // a table with rows never gets a snapshot entry, and the caller
+                    // (uninstall) would then drop it via dropPluginTables believing
+                    // it was safely captured: permanent data loss. Rethrowing aborts
+                    // snapshotPluginTables (and therefore uninstall, before its
+                    // cleanup step ever runs) instead — the safe outcome.
+                    throw error;
+                }
+                // A tracked table whose physical table is genuinely already gone
+                // means an earlier snapshot attempt (before a mid-loop drop
+                // failure) already captured its rows — see
+                // dropPluginTables/restoreSnapshot. Skip it rather than throw so an
+                // uninstall retry, which re-snapshots every tracked table, isn't
+                // wedged by a table a prior attempt already finished dropping.
+                // Scoped to this table's iteration only, so a missing table never
+                // skips the next one.
+                console.warn(`[structured-snapshot] table ${table.physicalTableName} for ${pluginId} no longer exists — skipped (rows preserved in the earlier snapshot that captured them): ${String(error instanceof Error ? error.message : error)}`);
+                continue;
+            }
+            await this.prisma.pluginStructuredSnapshot.create({
+                data: {
+                    snapshotGroupId,
+                    pluginId,
+                    tableName: table.tableName,
+                    physicalTableName: table.physicalTableName,
+                    schema: table.schema,
+                    rows: rows,
+                    ...(trigger ? { trigger } : {}),
+                },
+            });
+        }
+        return snapshotGroupId;
+    }
+    async restoreSnapshot(snapshotGroupId) {
+        const snapshots = await this.prisma.pluginStructuredSnapshot.findMany({
+            where: { snapshotGroupId },
+        });
+        for (const snap of snapshots) {
+            const schema = snap.schema;
+            const rows = snap.rows;
+            await this.adapter.createTable({ ...schema, tableName: snap.physicalTableName });
+            for (const row of rows) {
+                await this.adapter.insertRow(snap.physicalTableName, schema, row);
+            }
+            await this.prisma.pluginStructuredTable.create({
+                data: {
+                    pluginId: snap.pluginId,
+                    tableName: snap.tableName,
+                    physicalTableName: snap.physicalTableName,
+                    schema: snap.schema,
+                },
+            });
+        }
+    }
+    async dropPluginTables(pluginId) {
+        const tables = await this.prisma.pluginStructuredTable.findMany({ where: { pluginId } });
+        for (const table of tables) {
+            await this.adapter.dropTable(table.physicalTableName);
+        }
+        await this.prisma.pluginStructuredTable.deleteMany({ where: { pluginId } });
+    }
+    // S154 Task 5: the UNION restore plan (mockup semantics) — the newest
+    // available copy of each DISTINCT table this plugin has ever
+    // snapshotted, picked independently per table across ALL of the
+    // plugin's snapshot groups. Reuses Task 4's deriveSnapshotGroups (newest
+    // groups first) rather than re-deriving "newest per table" from scratch:
+    // walking the already-sorted groups and taking the first (freshest)
+    // group that contains each table name is exactly the union-pick, and
+    // keeps this selection logic defined in exactly one place.
+    async planRestore(pluginId) {
+        const rows = await this.prisma.pluginStructuredSnapshot.findMany({
+            where: { pluginId },
+            select: { snapshotGroupId: true, tableName: true, trigger: true, createdAt: true },
+        });
+        if (rows.length === 0)
+            return [];
+        const groups = deriveSnapshotGroups(rows); // newest first
+        const pickedByTable = new Map();
+        for (const group of groups) {
+            // A "restore"-trigger group is the PRE-RESTORE SAFETY SNAPSHOT that
+            // restorePluginData takes of itself, not a genuine prior backup — it
+            // exists only to protect whatever was live the instant some earlier
+            // restore ran, which makes it (by construction) the newest group for
+            // every table it holds. It still lists normally on the groups
+            // surface (deriveSnapshotGroups/listSnapshotGroups are untouched)
+            // and still counts toward totalTableCount there — only the
+            // SELECTION below skips it. Leaving it eligible would make restore
+            // selection unstable: an immediate second confirmed restore would
+            // re-select it and "restore" the just-protected pre-restore state
+            // right back, silently REVERTING the first restore (a double-
+            // submit / stale-screen hazard), and a crash between the safety
+            // snapshot and the replace loop would make a crash-retry restore the
+            // half-replaced pre-restore state instead of completing the
+            // originally intended restore. Excluding restore-trigger groups here
+            // is what makes a double-confirmed restore idempotent (both calls
+            // re-select the same underlying source groups) and a crash-retry
+            // resume the original intent instead of undoing it.
+            if (group.trigger === "restore")
+                continue;
+            for (const tableName of group.tableNames) {
+                if (!pickedByTable.has(tableName)) {
+                    pickedByTable.set(tableName, {
+                        tableName,
+                        snapshotGroupId: group.snapshotGroupId,
+                        groupTakenAt: group.takenAt,
+                    });
+                }
+            }
+        }
+        // Deterministic order (by tableName) rather than Map insertion order,
+        // which would depend on which group happened to be walked first.
+        return [...pickedByTable.values()].sort((a, b) => a.tableName.localeCompare(b.tableName));
+    }
+    // S154 Task 5: replace-not-merge restore from the union plan above.
+    //
+    // The plan is computed FIRST, before the pre-restore safety snapshot.
+    // planRestore()'s own exclusion of trigger === "restore" groups (see its
+    // comment) is what actually makes a just-taken safety snapshot
+    // ineligible as a restore source — but computing the plan here before
+    // that snapshot is taken is a cheap second line of defense against the
+    // same failure mode, so a bug in that exclusion alone couldn't make this
+    // call's own safety snapshot self-select.
+    //
+    // The safety snapshot itself still runs before any destructive step
+    // (database.md's hard rule + the mockup's promised safety line): a
+    // crash between the snapshot and the per-table drop/create loop below
+    // leaves that pre-restore group fully intact — but the actual recovery
+    // is retrying THIS call (restorePluginData(pluginId)) again, not
+    // restoreSnapshot(groupId) on the safety group. restoreSnapshot() does a
+    // bare createTable for every snapshotted table with no drop first, so
+    // calling it here would fail outright: the plugin's live tables are
+    // still standing (the crash was before the drop/create loop ran), and
+    // createTable against an already-existing table errors. Retrying
+    // restorePluginData is safe specifically because of the eligibility fix
+    // above — planRestore's exclusion of trigger === "restore" groups means
+    // the retry recomputes the same original plan instead of self-selecting
+    // the safety snapshot it just took, so it resumes the intended restore
+    // rather than restoring the pre-restore state back onto itself.
+    async restorePluginData(pluginId) {
+        const plan = await this.planRestore(pluginId);
+        const trackedTables = await this.prisma.pluginStructuredTable.findMany({ where: { pluginId } });
+        let preRestoreSnapshotGroupId = null;
+        if (trackedTables.length > 0) {
+            const safetyGroupId = await this.snapshotPluginTables(pluginId, "restore");
+            // snapshotPluginTables ALWAYS returns a groupId, even when every one
+            // of the plugin's tracked tables turned out to have its physical
+            // table already gone (the isTableMissingError skip path in
+            // snapshotPluginTables) and zero PluginStructuredSnapshot rows
+            // actually got written under it. A groupId with nothing behind it
+            // protects nothing, and — being backed by zero rows — never appears
+            // on the groups listing either; reporting it to the caller as "your
+            // data was protected" would be a lie, so it collapses back to null
+            // here exactly like the "nothing was tracked at all" case above.
+            const capturedAnything = await this.prisma.pluginStructuredSnapshot.findFirst({
+                where: { snapshotGroupId: safetyGroupId },
+                select: { id: true },
+            });
+            preRestoreSnapshotGroupId = capturedAnything ? safetyGroupId : null;
+        }
+        const restoredTables = [];
+        for (const entry of plan) {
+            const snap = await this.prisma.pluginStructuredSnapshot.findFirst({
+                where: { snapshotGroupId: entry.snapshotGroupId, tableName: entry.tableName },
+            });
+            // Defensive only: the plan was derived from these exact rows a
+            // moment ago and nothing in between can delete a snapshot row, so
+            // this should never actually miss.
+            if (!snap)
+                continue;
+            const schema = snap.schema;
+            const rows = snap.rows;
+            // Idempotent drop THEN delete-the-tracking-row THEN recreate is
+            // what makes restoring onto a REINSTALLED plugin (live table +
+            // live tracking row already present, the deferred S87 collision)
+            // and restoring onto empty (neither present) the same safe path:
+            // a bare createTable would fail "table already exists" in the
+            // collision case, and the tracking-row create would hit a P2002
+            // unique violation on (pluginId, tableName) — dropping and
+            // deleting first means createTable and the tracking-row create
+            // always run against a clean slate either way.
+            await this.adapter.dropTable(snap.physicalTableName);
+            await this.prisma.pluginStructuredTable.deleteMany({
+                where: { pluginId, tableName: entry.tableName },
+            });
+            await this.adapter.createTable({ ...schema, tableName: snap.physicalTableName });
+            // The tracking row is created immediately after the table — BEFORE
+            // the insertRow loop below, not after. If a row partway through that
+            // loop fails (a bad value, a transient DB error), creating the
+            // tracking row first still leaves this table VISIBLE, as a
+            // (partially-filled) tracked table, to dropPluginTables /
+            // snapshotPluginTables / StructuredStorageAPI — a retried restore's
+            // replace path (drop -> delete-tracking -> recreate, same as this
+            // one) can then clean it up and finish. Creating the tracking row
+            // last would instead leave a live physical table with rows in it
+            // that no tracking row points to: invisible to every one of those
+            // callers, a silent leak no retry could ever find.
+            await this.prisma.pluginStructuredTable.create({
+                data: {
+                    pluginId,
+                    tableName: entry.tableName,
+                    physicalTableName: snap.physicalTableName,
+                    schema: snap.schema,
+                },
+            });
+            for (const row of rows) {
+                await this.adapter.insertRow(snap.physicalTableName, schema, row);
+            }
+            restoredTables.push(entry.tableName);
+        }
+        return { preRestoreSnapshotGroupId, restoredTables };
+    }
+}

package/dist/plugins/structured-storage-api.d.ts

@@ -0,0 +1,22 @@
+import type { PrismaClient } from "@prisma/client";
+import { type DatabaseAdapter, type PluginTableSchema } from "@velora-cms/db-adapter";
+import type { PluginRegistryService } from "./plugin-registry-service.js";
+import { StructuredQueryBuilder } from "./structured-query-builder.js";
+import { PluginTableNotDefinedError, StructuredStorageTransaction } from "./structured-storage-transaction.js";
+export declare class PluginTableAlreadyDefinedError extends Error {
+    constructor(pluginId: string, tableName: string);
+}
+export { PluginTableNotDefinedError };
+export declare class StructuredStorageAPI {
+    private readonly adapter;
+    private readonly registry;
+    private readonly prisma;
+    constructor(adapter: DatabaseAdapter, registry: PluginRegistryService, prisma: PrismaClient);
+    defineTable(pluginId: string, schema: PluginTableSchema): Promise<void>;
+    private resolveTable;
+    insert(pluginId: string, tableName: string, data: Record<string, unknown>): Promise<void>;
+    update(pluginId: string, tableName: string, where: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+    delete(pluginId: string, tableName: string, where: Record<string, unknown>): Promise<number>;
+    query<T = Record<string, unknown>>(pluginId: string, tableName: string): StructuredQueryBuilder<T>;
+    transaction(pluginId: string, fn: (tx: StructuredStorageTransaction) => Promise<void>): Promise<void>;
+}

package/dist/plugins/structured-storage-api.js

@@ -0,0 +1,91 @@
+import { validatePluginTableSchema } from "@velora-cms/db-adapter";
+import { StructuredQueryBuilder } from "./structured-query-builder.js";
+import { PluginTableNotDefinedError, resolvePluginTable, StructuredStorageTransaction, } from "./structured-storage-transaction.js";
+import { physicalTableName } from "./structured-table-naming.js";
+export class PluginTableAlreadyDefinedError extends Error {
+    constructor(pluginId, tableName) {
+        super(`Plugin "${pluginId}" has already defined a structured table named "${tableName}"`);
+        this.name = "PluginTableAlreadyDefinedError";
+    }
+}
+export { PluginTableNotDefinedError };
+// StructuredStorageAPI (Month 8). Mirrors SimpleStorageAPI's shape:
+// every method opens with registry.requireActivePlugin(pluginId), all
+// real persistence delegates to DatabaseAdapter, zero SQL of its own.
+export class StructuredStorageAPI {
+    adapter;
+    registry;
+    prisma;
+    constructor(adapter, registry, prisma) {
+        this.adapter = adapter;
+        this.registry = registry;
+        this.prisma = prisma;
+    }
+    async defineTable(pluginId, schema) {
+        await this.registry.requireActivePlugin(pluginId);
+        validatePluginTableSchema(schema);
+        const existing = await this.prisma.pluginStructuredTable.findUnique({
+            where: { pluginId_tableName: { pluginId, tableName: schema.tableName } },
+        });
+        if (existing) {
+            throw new PluginTableAlreadyDefinedError(pluginId, schema.tableName);
+        }
+        const physical = physicalTableName(pluginId, schema.tableName);
+        await this.adapter.createTable({ ...schema, tableName: physical });
+        try {
+            await this.prisma.pluginStructuredTable.create({
+                data: {
+                    pluginId,
+                    tableName: schema.tableName,
+                    physicalTableName: physical,
+                    // PluginTableSchema's optional fields (primaryKey?, notNull?,
+                    // etc.) type as `T | undefined`, which Prisma's Json input
+                    // type structurally rejects (only `T | null` is JSON-safe) —
+                    // the value itself is genuinely JSON-serializable, so this is
+                    // a type-system escape hatch, not a runtime concern.
+                    schema: schema,
+                },
+            });
+        }
+        catch (cause) {
+            // Never leave an untracked physical table behind — Session 87's
+            // snapshot-before-uninstall can only see what's in
+            // PluginStructuredTable, so an orphaned table here would become a
+            // silent data-loss blind spot later.
+            await this.adapter.dropTable(physical).catch(() => { });
+            throw cause;
+        }
+    }
+    async resolveTable(pluginId, tableName) {
+        return resolvePluginTable(this.prisma, pluginId, tableName);
+    }
+    async insert(pluginId, tableName, data) {
+        await this.registry.requireActivePlugin(pluginId);
+        const { physicalTableName, schema } = await this.resolveTable(pluginId, tableName);
+        await this.adapter.insertRow(physicalTableName, schema, data);
+    }
+    async update(pluginId, tableName, where, data) {
+        await this.registry.requireActivePlugin(pluginId);
+        const { physicalTableName, schema } = await this.resolveTable(pluginId, tableName);
+        return this.adapter.updateRows(physicalTableName, schema, where, data);
+    }
+    async delete(pluginId, tableName, where) {
+        await this.registry.requireActivePlugin(pluginId);
+        const { physicalTableName, schema } = await this.resolveTable(pluginId, tableName);
+        return this.adapter.deleteRows(physicalTableName, schema, where);
+    }
+    query(pluginId, tableName) {
+        return new StructuredQueryBuilder(async (options) => {
+            await this.registry.requireActivePlugin(pluginId);
+            const { physicalTableName, schema } = await this.resolveTable(pluginId, tableName);
+            return this.adapter.queryRows(physicalTableName, schema, options);
+        });
+    }
+    async transaction(pluginId, fn) {
+        await this.registry.requireActivePlugin(pluginId);
+        await this.adapter.transaction(async (tx) => {
+            const handle = new StructuredStorageTransaction(tx, this.adapter.dialect, this.prisma, pluginId);
+            await fn(handle);
+        });
+    }
+}

package/dist/plugins/structured-storage-transaction.d.ts

@@ -0,0 +1,22 @@
+import type { PrismaClient } from "@prisma/client";
+import { type DatabaseDialect, type PluginTableSchema, type TransactionContext } from "@velora-cms/db-adapter";
+import { StructuredQueryBuilder } from "./structured-query-builder.js";
+export declare class PluginTableNotDefinedError extends Error {
+    constructor(pluginId: string, tableName: string);
+}
+export declare function resolvePluginTable(prisma: PrismaClient, pluginId: string, tableName: string): Promise<{
+    physicalTableName: string;
+    schema: PluginTableSchema;
+}>;
+export declare class StructuredStorageTransaction {
+    private readonly tx;
+    private readonly dialect;
+    private readonly prisma;
+    private readonly pluginId;
+    constructor(tx: TransactionContext, dialect: DatabaseDialect, prisma: PrismaClient, pluginId: string);
+    private resolveTable;
+    insert(tableName: string, data: Record<string, unknown>): Promise<void>;
+    update(tableName: string, where: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+    delete(tableName: string, where: Record<string, unknown>): Promise<number>;
+    query<T = Record<string, unknown>>(tableName: string): StructuredQueryBuilder<T>;
+}

package/dist/plugins/structured-storage-transaction.js

@@ -0,0 +1,63 @@
+import { buildDeleteStatement, buildInsertStatement, buildSelectStatement, buildUpdateStatement, deserializeRow, } from "@velora-cms/db-adapter";
+import { StructuredQueryBuilder } from "./structured-query-builder.js";
+export class PluginTableNotDefinedError extends Error {
+    constructor(pluginId, tableName) {
+        super(`Plugin "${pluginId}" has not defined a structured table named "${tableName}"`);
+        this.name = "PluginTableNotDefinedError";
+    }
+}
+// Shared by StructuredStorageAPI and StructuredStorageTransaction — both
+// need to resolve a plugin's declared table name to its physical table
+// name and recorded schema before touching the adapter. Kept here (rather
+// than duplicated in both files) so the two paths can't drift.
+export async function resolvePluginTable(prisma, pluginId, tableName) {
+    const row = await prisma.pluginStructuredTable.findUnique({
+        where: { pluginId_tableName: { pluginId, tableName } },
+    });
+    if (!row) {
+        throw new PluginTableNotDefinedError(pluginId, tableName);
+    }
+    return { physicalTableName: row.physicalTableName, schema: row.schema };
+}
+// Plugin-safe transaction handle passed into StructuredStorageAPI's
+// transaction(pluginId, fn) callback. Deliberately does NOT expose the
+// raw TransactionContext (no plugin ever writes SQL) —
+// only insert/update/query, scoped to the plugin fixed for this
+// transaction's lifetime, reusing the exact same statement builders the
+// top-level (non-transactional) StructuredStorageAPI path uses.
+export class StructuredStorageTransaction {
+    tx;
+    dialect;
+    prisma;
+    pluginId;
+    constructor(tx, dialect, prisma, pluginId) {
+        this.tx = tx;
+        this.dialect = dialect;
+        this.prisma = prisma;
+        this.pluginId = pluginId;
+    }
+    async resolveTable(tableName) {
+        return resolvePluginTable(this.prisma, this.pluginId, tableName);
+    }
+    async insert(tableName, data) {
+        const { physicalTableName, schema } = await this.resolveTable(tableName);
+        await this.tx.execute(buildInsertStatement(this.dialect, physicalTableName, schema, data));
+    }
+    async update(tableName, where, data) {
+        const { physicalTableName, schema } = await this.resolveTable(tableName);
+        const result = await this.tx.execute(buildUpdateStatement(this.dialect, physicalTableName, schema, where, data));
+        return result.rowCount;
+    }
+    async delete(tableName, where) {
+        const { physicalTableName, schema } = await this.resolveTable(tableName);
+        const result = await this.tx.execute(buildDeleteStatement(this.dialect, physicalTableName, schema, where));
+        return result.rowCount;
+    }
+    query(tableName) {
+        return new StructuredQueryBuilder(async (options) => {
+            const { physicalTableName, schema } = await this.resolveTable(tableName);
+            const rows = await this.tx.query(buildSelectStatement(this.dialect, physicalTableName, schema, options));
+            return rows.map((row) => deserializeRow(schema, row));
+        });
+    }
+}

package/dist/plugins/structured-table-naming.d.ts

@@ -0,0 +1 @@
+export declare function physicalTableName(pluginId: string, tableName: string, maxLength?: number): string;

package/dist/plugins/structured-table-naming.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+// Plugin ids are reverse-domain strings (e.g. "com.velora.commerce") — not
+// safe as bare SQL identifiers — and unlike SimpleStorageAPI's shared
+// content_field_values table, structured storage has no shared table with
+// a plugin_id column to filter by: each plugin gets its own physical
+// table, so isolation has to happen at the naming level instead.
+//
+// Single-path, deterministic scheme (a hash prefix always present, never
+// a "short name passthrough vs. long name hash fallback" branch) — one
+// invariant to prove, not two, since Session 87's snapshot logic depends
+// on this staying stable forever.
+export function physicalTableName(pluginId, tableName, maxLength = 63) {
+    const sanitize = (value) => value.replace(/[^a-z0-9]+/gi, "_").toLowerCase();
+    const digest = createHash("sha256").update(`${pluginId}:${tableName}`).digest("hex").slice(0, 10);
+    const fixed = `p_${digest}_`;
+    const human = `${sanitize(pluginId)}_${sanitize(tableName)}`.slice(0, maxLength - fixed.length);
+    return `${fixed}${human}`;
+}

package/dist/plugins/trusted-keys.d.ts

@@ -0,0 +1,11 @@
+import type { TrustedKey } from "@velora-cms/plugin-package";
+/**
+ * The trusted key set for this process: what shipped with the CMS, plus
+ * anything VELORA_TRUSTED_SIGNING_KEYS supplies (later entries win on a
+ * keyId collision, so an operator can override a shipped key).
+ *
+ * An empty result is a legitimate, non-error state meaning "trust nobody".
+ * A malformed override warns and is ignored — a config typo must never
+ * stop the server booting.
+ */
+export declare function loadTrustedKeys(): TrustedKey[];

package/dist/plugins/trusted-keys.js

@@ -0,0 +1,67 @@
+import { deriveKeyId } from "@velora-cms/plugin-package";
+import { SHIPPED_TRUSTED_KEYS } from "./trusted-signing-keys.js";
+/**
+ * keyId is otherwise an unauthenticated label: nothing stops a {keyId,
+ * publicKey} pair whose keyId does not actually belong to that publicKey
+ * from entering the trusted set, at which point describeVerifyResult could
+ * log "verified against trusted key <keyId>" for a signature made by a
+ * completely different key. Re-deriving and comparing here is what makes
+ * D2's "cannot drift" claim true rather than aspirational — applied to
+ * BOTH the shipped set and any override, since a future entry in either
+ * place could get this wrong. deriveKeyId THROWS on a wrong-length key
+ * (envelope.ts's rawPublicKey), so it must be guarded, not assumed safe.
+ */
+function keyIdMatchesPublicKey(entry, source) {
+    let derived;
+    try {
+        derived = deriveKeyId(entry.publicKey);
+    }
+    catch (error) {
+        console.warn(`[plugin-verify] ${source} entry with keyId "${entry.keyId}" has a malformed publicKey — ignoring it: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    if (derived !== entry.keyId) {
+        console.warn(`[plugin-verify] ${source} entry declares keyId "${entry.keyId}" but its publicKey derives to keyId "${derived}" — ignoring it`);
+        return false;
+    }
+    return true;
+}
+function parseOverride(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        console.warn("[plugin-verify] VELORA_TRUSTED_SIGNING_KEYS is not valid JSON — ignoring it");
+        return [];
+    }
+    const keys = parsed?.keys;
+    if (!Array.isArray(keys)) {
+        console.warn('[plugin-verify] VELORA_TRUSTED_SIGNING_KEYS must be {"keys":[…]} — ignoring it');
+        return [];
+    }
+    return keys
+        .filter((entry) => {
+        const candidate = entry;
+        return typeof candidate?.keyId === "string" && typeof candidate?.publicKey === "string";
+    })
+        .filter((entry) => keyIdMatchesPublicKey(entry, "VELORA_TRUSTED_SIGNING_KEYS"));
+}
+/**
+ * The trusted key set for this process: what shipped with the CMS, plus
+ * anything VELORA_TRUSTED_SIGNING_KEYS supplies (later entries win on a
+ * keyId collision, so an operator can override a shipped key).
+ *
+ * An empty result is a legitimate, non-error state meaning "trust nobody".
+ * A malformed override warns and is ignored — a config typo must never
+ * stop the server booting.
+ */
+export function loadTrustedKeys() {
+    const raw = process.env.VELORA_TRUSTED_SIGNING_KEYS;
+    const shipped = SHIPPED_TRUSTED_KEYS.filter((entry) => keyIdMatchesPublicKey(entry, "SHIPPED_TRUSTED_KEYS"));
+    const merged = new Map();
+    for (const key of [...shipped, ...(raw ? parseOverride(raw) : [])]) {
+        merged.set(key.keyId, key);
+    }
+    return [...merged.values()];
+}

package/dist/plugins/trusted-signing-keys.d.ts

@@ -0,0 +1,27 @@
+import type { TrustedKey } from "@velora-cms/plugin-package";
+/**
+ * The signing keys this CMS build trusts, shipped with the CMS.
+ *
+ * SHIPPED AS OF SESSION 165: the production marketplace signing key,
+ * ROTATED in Session 180 — the active key's private half is held solely
+ * by the operator outside this repository; the production marketplace's
+ * environment receives it. It is never written to this repo, the dev
+ * `.env`, or any database — the marketplace's signing_keys table stores
+ * only public halves. The pre-rotation key was retired in Session 182 —
+ * see the active entry's own comment below.
+ *
+ * Consequence, stated plainly: a stock install now verifies any plugin
+ * signed by the real marketplace with zero configuration — the
+ * VELORA_TRUSTED_SIGNING_KEYS era of hand-fed keys is over for the
+ * default case. An operator can still add or override keys with that
+ * env var (e.g. a private/self-hosted marketplace signing under its own
+ * key).
+ *
+ * Rotation is add-new + re-sign current artifacts + retire old — never
+ * delete a key that signed an artifact any CMS may still need to verify
+ * (the one-version-one-artifact rule, Session 127).
+ *
+ * A SET rather than a single key from day one: the Trust model leaves the
+ * door open for v1.x enterprise org-signing.
+ */
+export declare const SHIPPED_TRUSTED_KEYS: TrustedKey[];

package/dist/plugins/trusted-signing-keys.js

@@ -0,0 +1,40 @@
+/**
+ * The signing keys this CMS build trusts, shipped with the CMS.
+ *
+ * SHIPPED AS OF SESSION 165: the production marketplace signing key,
+ * ROTATED in Session 180 — the active key's private half is held solely
+ * by the operator outside this repository; the production marketplace's
+ * environment receives it. It is never written to this repo, the dev
+ * `.env`, or any database — the marketplace's signing_keys table stores
+ * only public halves. The pre-rotation key was retired in Session 182 —
+ * see the active entry's own comment below.
+ *
+ * Consequence, stated plainly: a stock install now verifies any plugin
+ * signed by the real marketplace with zero configuration — the
+ * VELORA_TRUSTED_SIGNING_KEYS era of hand-fed keys is over for the
+ * default case. An operator can still add or override keys with that
+ * env var (e.g. a private/self-hosted marketplace signing under its own
+ * key).
+ *
+ * Rotation is add-new + re-sign current artifacts + retire old — never
+ * delete a key that signed an artifact any CMS may still need to verify
+ * (the one-version-one-artifact rule, Session 127).
+ *
+ * A SET rather than a single key from day one: the Trust model leaves the
+ * door open for v1.x enterprise org-signing.
+ */
+export const SHIPPED_TRUSTED_KEYS = [
+    {
+        // Active production marketplace signing key, since the Session 180
+        // rotation (2026-08-30). Its private half is held solely by the
+        // operator outside this repository; the production marketplace's
+        // environment receives it. Rotation is add-new + re-sign current
+        // artifacts + retire old — never delete a key that signed an artifact
+        // any CMS may still need to verify (the one-version-one-artifact
+        // rule, Session 127).
+        // Pre-rotation key 91d5529a9f997602 removed in S182 — every listed
+        // marketplace version was re-signed with this key in S180.
+        keyId: "73e409f633dbbea3",
+        publicKey: "MCowBQYDK2VwAyEAcTQOhyCUsvGCWooiC4cp1idRWzXE3W8acCU/uKzBOro=",
+    },
+];