@peers-app/peers-sdk 0.28.11 → 0.28.12

package/dist/data/orm/signed-package-table.d.ts

@@ -0,0 +1,126 @@
+import { type ISignedRowIdentity } from "../signed-row-id";
+import type { ISaveOptions } from "./data-query";
+import { Table } from "./table";
+import { type ITableMetaData } from "./types";
+/** A row of a signed table, as stored: the owner's signature and the signing time it covers. */
+export interface ISignedRow {
+    /** `publicKey:signature` over the row, from `addSignatureToObject`. */
+    signature?: string;
+    /** When the owner signed the row; a replacement must not be signed earlier. */
+    signedAt?: number;
+    /** Context the signature authorizes: the group id, or the personal user's id. */
+    signedContextId?: string;
+    /** Deterministic package table id the signature authorizes. */
+    signedTableId?: string;
+    /** In a table without `signedKey`: what the row's id was derived from, with its owner. */
+    signedIdSeed?: string;
+}
+/** Signs a row with the signed-in user's key; installed by the host. */
+export type SignedTableSigner = <T extends Record<string, any>>(row: T) => T & {
+    signature: string;
+};
+/**
+ * Project a signed row onto its stored columns, applying empty-field handling, defaults, and
+ * scalar TEXT encoding before signing or verification. Verification must judge these values:
+ * a signature over extra columns or a pre-storage value must not authorize a different row.
+ *
+ * @param metaData - The signed table's stored definition.
+ * @param record - The candidate row, including any existing signature.
+ * @param schema - Optional code schema used for local saves; synced rows use metadata only.
+ * @param existing - Stored row whose omitted required columns an update would preserve.
+ * @throws When the row fails validation, including text with unpaired surrogates anywhere in
+ *   a field (a scalar, or a string or key inside an object or array).
+ */
+export declare function signedPackageRowForStorage(metaData: ITableMetaData, record: Record<string, any>, schema?: import("zod").AnyZodObject, existing?: Record<string, any>): Record<string, any>;
+/**
+ * The table class of every package table declared with `signedBy`: the host signs each row on
+ * save, whoever saves it (package code through the bridge, a UI, the CLI). A row names its owner
+ * in the `signedBy` field, and only the signed-in user can save rows they own; the signature and
+ * `signedAt` are stamped over the row as it will be stored, so every device can verify it.
+ *
+ * Peers sets each row's id, derived from its owner ({@link signedRowIdFor}), so no other member
+ * can claim it: from the owner and the `signedKey` fields when the table declares them (one row
+ * per owner per key), otherwise from the owner and a seed stored in `signedIdSeed`. A new row's
+ * seed is the id the caller passed when that's a plain peer id, so saving it again with that id
+ * updates the same row; otherwise a fresh one. Callers use the id `save` returns.
+ *
+ * Rows aren't deleted: a synced delete carries no author, so a package marks a row instead. The
+ * group's write check (`signedTableWriteCheck`) judges the row again, on this device and on
+ * every device it syncs to. Package code never sees the key: the host installs the signer
+ * with {@link SignedPackageTable.enableSignedTableSigning}.
+ */
+export declare class SignedPackageTable<T extends {
+    [key: string]: any;
+}> extends Table<T> {
+    /** The field naming each row's owner. */
+    get ownerField(): string;
+    /** What derives this table's row ids: its declared name, owner field, and key fields. */
+    get rowIdentity(): ISignedRowIdentity;
+    /**
+     * Sign and store a row the signed-in user owns, as a full snapshot written at its signing
+     * time, under the id derived from its owner (see the class). Refuses a row naming anyone else
+     * as owner, a change to a row's key fields, and `weakInsert`. In a renderer the host signs:
+     * the row is passed through to it.
+     *
+     * @param record - The row. Its id is replaced by the derived one unless it's already on record.
+     * @param opts - Save options; `saveAsSnapshot` and `writtenAt` are set here.
+     * @throws When `opts.weakInsert` is set: a weak insert's change time would be near zero while
+     *   its `signedAt` is current, so sync (by change time) and the write check (by `signedAt`)
+     *   would order it differently and devices could keep different versions of the row.
+     */
+    save(record: T, opts?: ISaveOptions): Promise<T>;
+    /**
+     * Sign a row on record again, unchanged, with `secretKey` instead of the installed signer, at
+     * a new signing time. Key rotation calls it for the rows the user signed with the key they
+     * rotated away from, since every device verifies a row against its owner's current key, and
+     * the running host still signs with the old key until it restarts. Host code only.
+     *
+     * Static so the instance-method table RPC cannot invoke it with a caller-supplied key.
+     *
+     * @param table - The host's table instance.
+     * @param record - The row as stored.
+     * @param secretKey - The owner's new secret key.
+     * @throws Like {@link save}: when the row names someone else as owner, or the group's write
+     *   check refuses the new signature; also when the row on record is no longer `record`, or
+     *   re-signing would change its content.
+     */
+    static resign<T extends Record<string, any>>(table: SignedPackageTable<T>, record: T, secretKey: string): Promise<T>;
+    /** Store a row {@link signRow} signed, as a full snapshot written at its signing time. */
+    private saveSigned;
+    /** Same as {@link save}: every write to a signed table is signed. */
+    insert(record: T): Promise<T>;
+    /** Same as {@link save}: every write to a signed table is signed. */
+    update(record: T): Promise<T>;
+    /** Refused: a delete can't be signed, so a package marks the row instead. */
+    delete(_idOrRecord: string | T): Promise<void>;
+    /**
+     * The row as it will be stored, signed by the signed-in user: its declared columns only, with
+     * empty fields removed and defaults applied as storage does, under the id derived from its
+     * owner, then stamped with the signing time and signed with `sign` over all of it.
+     *
+     * @param record - The row being saved.
+     * @param sign - Signs with the signed-in user's key.
+     */
+    private signRow;
+    /**
+     * The id `record` is saved under, its seed (in a table without `signedKey`), and the row on
+     * record under that id. A row on record keeps its id. Otherwise the id is derived: from the
+     * owner and key fields, or from the owner and a seed, which is the id the caller passed when
+     * that's a plain peer id (so saving it again updates the same row) or a fresh one.
+     *
+     * @param record - The row being saved.
+     * @param owner - Its owner, the signed-in user.
+     */
+    private resolveRowId;
+    /**
+     * Install the signer every signed table uses, for all SDK copies in this JavaScript realm.
+     * Replaces any prior signer. The host calls it with the signed-in user's key.
+     *
+     * @param fn - Signs a row, typically `addSignatureToObject(row, secretKey)`.
+     */
+    static enableSignedTableSigning(fn: SignedTableSigner): void;
+}
+/** The table class for `metaData`: {@link SignedPackageTable} when it has `signedBy`, else {@link Table}. */
+export declare function defaultTableClass(metaData: {
+    signedBy?: string;
+}): typeof Table;

package/dist/data/orm/signed-package-table.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignedPackageTable = void 0;
+exports.signedPackageRowForStorage = signedPackageRowForStorage;
+exports.defaultTableClass = defaultTableClass;
+const keys_1 = require("../../keys");
+const rpc_types_1 = require("../../rpc-types");
+const serial_json_1 = require("../../serial-json");
+const field_type_1 = require("../../types/field-type");
+const utils_1 = require("../../utils");
+const package_table_identity_1 = require("../package-table-identity");
+const signed_row_id_1 = require("../signed-row-id");
+const sql_data_source_1 = require("./sql.data-source");
+const table_1 = require("./table");
+const types_1 = require("./types");
+const write_checks_1 = require("./write-checks");
+// Symbol.for keeps the signer shared by separately installed SDK copies, as the system tables do.
+const signingKey = Symbol.for("@peers-app/peers-sdk/signed-table-signing");
+const signingGlobals = globalThis;
+// In Unicode mode this class matches only unpaired surrogates, not valid astral characters.
+const UNPAIRED_SURROGATE = /[\uD800-\uDFFF]/u;
+/**
+ * Whether a `toJSON` tree (the form sync encodes) holds an unpaired UTF-16 surrogate in any
+ * string or object key, at any depth.
+ *
+ * @param tree - A value as `toJSON` returns it: no cycles, Dates or Buffers left.
+ */
+function hasUnpairedSurrogate(tree) {
+    if (typeof tree === "string")
+        return UNPAIRED_SURROGATE.test(tree);
+    if (Array.isArray(tree))
+        return tree.some(hasUnpairedSurrogate);
+    if (tree !== null && typeof tree === "object") {
+        return Object.entries(tree).some(([key, value]) => UNPAIRED_SURROGATE.test(key) || hasUnpairedSurrogate(value));
+    }
+    return false;
+}
+/**
+ * Project a signed row onto its stored columns, applying empty-field handling, defaults, and
+ * scalar TEXT encoding before signing or verification. Verification must judge these values:
+ * a signature over extra columns or a pre-storage value must not authorize a different row.
+ *
+ * @param metaData - The signed table's stored definition.
+ * @param record - The candidate row, including any existing signature.
+ * @param schema - Optional code schema used for local saves; synced rows use metadata only.
+ * @param existing - Stored row whose omitted required columns an update would preserve.
+ * @throws When the row fails validation, including text with unpaired surrogates anywhere in
+ *   a field (a scalar, or a string or key inside an object or array).
+ */
+function signedPackageRowForStorage(metaData, record, schema = (0, types_1.fieldsToSchema)(metaData.fields), existing) {
+    const columns = Object.fromEntries(metaData.fields
+        .filter((field) => record[field.name] !== undefined)
+        .map((field) => [field.name, record[field.name]]));
+    for (const field of metaData.fields) {
+        if (!field.optional &&
+            record[field.name] === undefined &&
+            existing?.[field.name] !== undefined) {
+            columns[field.name] = existing[field.name];
+        }
+    }
+    const row = (0, types_1.withoutEmptyFields)(metaData.fields, columns);
+    const parsed = schema.parse(row);
+    for (const field of metaData.fields) {
+        if (row[field.name] === undefined && parsed[field.name] !== undefined) {
+            row[field.name] = parsed[field.name];
+        }
+        if (row[field.name] !== undefined) {
+            // SQLite stores scalar text as UTF-8, and sync sends every string (nested ones and object
+            // keys too) as UTF-8: an unpaired UTF-16 surrogate would arrive as different text,
+            // invalidating the signature on other devices and possibly the owner-derived id.
+            if (hasUnpairedSurrogate((0, serial_json_1.toJSON)(row[field.name]))) {
+                throw new Error(`Field "${field.name}" must contain well-formed Unicode`);
+            }
+            const value = (0, sql_data_source_1.jsValueToSqlValue)(row[field.name]);
+            // Untyped/blob scalar columns use TEXT storage and read back without a decoder. Other
+            // columns also need their serialization round trip (including nested sentinel values).
+            row[field.name] =
+                !field.isArray && (field.type === field_type_1.FieldType.any || field.type === field_type_1.FieldType.blob)
+                    ? value == null
+                        ? undefined
+                        : String(value)
+                    : (0, sql_data_source_1.sqlValueToJsValue)(value, field.type, field.isArray ?? false);
+        }
+    }
+    return row;
+}
+/**
+ * The table class of every package table declared with `signedBy`: the host signs each row on
+ * save, whoever saves it (package code through the bridge, a UI, the CLI). A row names its owner
+ * in the `signedBy` field, and only the signed-in user can save rows they own; the signature and
+ * `signedAt` are stamped over the row as it will be stored, so every device can verify it.
+ *
+ * Peers sets each row's id, derived from its owner ({@link signedRowIdFor}), so no other member
+ * can claim it: from the owner and the `signedKey` fields when the table declares them (one row
+ * per owner per key), otherwise from the owner and a seed stored in `signedIdSeed`. A new row's
+ * seed is the id the caller passed when that's a plain peer id, so saving it again with that id
+ * updates the same row; otherwise a fresh one. Callers use the id `save` returns.
+ *
+ * Rows aren't deleted: a synced delete carries no author, so a package marks a row instead. The
+ * group's write check (`signedTableWriteCheck`) judges the row again, on this device and on
+ * every device it syncs to. Package code never sees the key: the host installs the signer
+ * with {@link SignedPackageTable.enableSignedTableSigning}.
+ */
+class SignedPackageTable extends table_1.Table {
+    /** The field naming each row's owner. */
+    get ownerField() {
+        const field = this.metaData.signedBy;
+        if (!field)
+            throw new Error(`Table ${this.tableName} isn't a signed table`);
+        return field;
+    }
+    /** What derives this table's row ids: its declared name, owner field, and key fields. */
+    get rowIdentity() {
+        return {
+            name: this.metaData.name,
+            signedBy: this.ownerField,
+            signedKey: this.metaData.signedKey,
+        };
+    }
+    /**
+     * Sign and store a row the signed-in user owns, as a full snapshot written at its signing
+     * time, under the id derived from its owner (see the class). Refuses a row naming anyone else
+     * as owner, a change to a row's key fields, and `weakInsert`. In a renderer the host signs:
+     * the row is passed through to it.
+     *
+     * @param record - The row. Its id is replaced by the derived one unless it's already on record.
+     * @param opts - Save options; `saveAsSnapshot` and `writtenAt` are set here.
+     * @throws When `opts.weakInsert` is set: a weak insert's change time would be near zero while
+     *   its `signedAt` is current, so sync (by change time) and the write check (by `signedAt`)
+     *   would order it differently and devices could keep different versions of the row.
+     */
+    async save(record, opts) {
+        if (opts?.weakInsert) {
+            throw new Error(`Signed table ${this.tableName} can't take weakInsert: a row counts from when its owner signs it. Save a row only when there's something to save, and read a missing row as its defaults`);
+        }
+        if (rpc_types_1.isClient && !(0, rpc_types_1.isSingleProcessClient)())
+            return super.save(record, opts);
+        return this.saveSigned(await this.signRow(record, installedSigner()), opts);
+    }
+    /**
+     * Sign a row on record again, unchanged, with `secretKey` instead of the installed signer, at
+     * a new signing time. Key rotation calls it for the rows the user signed with the key they
+     * rotated away from, since every device verifies a row against its owner's current key, and
+     * the running host still signs with the old key until it restarts. Host code only.
+     *
+     * Static so the instance-method table RPC cannot invoke it with a caller-supplied key.
+     *
+     * @param table - The host's table instance.
+     * @param record - The row as stored.
+     * @param secretKey - The owner's new secret key.
+     * @throws Like {@link save}: when the row names someone else as owner, or the group's write
+     *   check refuses the new signature; also when the row on record is no longer `record`, or
+     *   re-signing would change its content.
+     */
+    static async resign(table, record, secretKey) {
+        if (rpc_types_1.isClient && !(0, rpc_types_1.isSingleProcessClient)())
+            throw new Error("Re-signing is host-only");
+        // A newer version that arrived since `record` was read isn't overwritten by the older one.
+        const current = await table.get(record[table.primaryKeyName]);
+        if (!current || current.signature !== record.signature) {
+            throw new Error(`Row ${record[table.primaryKeyName]} of ${table.tableName} changed before it could be re-signed`);
+        }
+        const signed = await table.signRow(record, (row) => (0, keys_1.addSignatureToObject)(row, secretKey));
+        const content = ({ signature: _signature, signedAt: _signedAt, ...row }) => (0, keys_1.canonicalJSONString)(row);
+        if (content(signed) !== content(record)) {
+            throw new Error(`Re-signing ${table.tableName} would change the row's content`);
+        }
+        return table.saveSigned(signed);
+    }
+    /** Store a row {@link signRow} signed, as a full snapshot written at its signing time. */
+    async saveSigned(signed, opts) {
+        // Signed tables never have an authorized tombstone. Refused deletes remain in history,
+        // so their tombstones must not prevent the owner creating a row on this device later.
+        return super.save(signed, {
+            ...opts,
+            restoreIfDeleted: true,
+            saveAsSnapshot: true,
+            writtenAt: signed.signedAt,
+        });
+    }
+    /** Same as {@link save}: every write to a signed table is signed. */
+    async insert(record) {
+        return this.save(record);
+    }
+    /** Same as {@link save}: every write to a signed table is signed. */
+    async update(record) {
+        return this.save(record);
+    }
+    /** Refused: a delete can't be signed, so a package marks the row instead. */
+    async delete(_idOrRecord) {
+        throw new Error(`Rows in signed table ${this.tableName} aren't deleted; the owner marks them instead (a field such as deleted: true)`);
+    }
+    /**
+     * The row as it will be stored, signed by the signed-in user: its declared columns only, with
+     * empty fields removed and defaults applied as storage does, under the id derived from its
+     * owner, then stamped with the signing time and signed with `sign` over all of it.
+     *
+     * @param record - The row being saved.
+     * @param sign - Signs with the signed-in user's key.
+     */
+    async signRow(record, sign) {
+        const ownerField = this.ownerField;
+        const { getUserContext } = await Promise.resolve().then(() => require("../../context/user-context-singleton"));
+        const userId = (await getUserContext()).userId;
+        const owner = record[ownerField];
+        if (owner !== userId) {
+            throw (0, write_checks_1.writeNotAuthorized)(this.tableName, `only the row's owner writes it, and "${ownerField}" names ${owner ?? "nobody"}, not ${userId}`);
+        }
+        const { recordId, seed, existing } = await this.resolveRowId(record, owner);
+        if (existing && existing[ownerField] !== owner) {
+            throw (0, write_checks_1.writeNotAuthorized)(this.tableName, "the row on record belongs to another member");
+        }
+        const columns = {};
+        for (const field of this.metaData.fields) {
+            if (!package_table_identity_1.SIGNED_TABLE_FIELD_NAMES.has(field.name) && record[field.name] !== undefined) {
+                columns[field.name] = record[field.name];
+            }
+        }
+        columns[this.primaryKeyName] = recordId;
+        if (seed !== undefined)
+            columns.signedIdSeed = seed;
+        const row = signedPackageRowForStorage(this.metaData, columns, this.schema, existing);
+        // The key fields as stored name the row: a changed key is a different row.
+        if ((0, signed_row_id_1.signedRowIdFor)(this.rowIdentity, row, row.signedIdSeed) !== recordId) {
+            throw new Error(`Row ${recordId} of ${this.tableName} has other key fields (${(this.metaData.signedKey ?? []).join(", ")}); a row's key can't change, so save a new row instead`);
+        }
+        const stamped = {
+            ...row,
+            ...(await (0, write_checks_1.signingStamp)(this, row, existing)),
+            signedContextId: this.groupId ?? userId,
+            signedTableId: (0, package_table_identity_1.packageScopedTableId)(this.metaData.packageId, this.metaData.name),
+        };
+        return sign(stamped);
+    }
+    /**
+     * The id `record` is saved under, its seed (in a table without `signedKey`), and the row on
+     * record under that id. A row on record keeps its id. Otherwise the id is derived: from the
+     * owner and key fields, or from the owner and a seed, which is the id the caller passed when
+     * that's a plain peer id (so saving it again updates the same row) or a fresh one.
+     *
+     * @param record - The row being saved.
+     * @param owner - Its owner, the signed-in user.
+     */
+    async resolveRowId(record, owner) {
+        const identity = this.rowIdentity;
+        const supplied = record[this.primaryKeyName];
+        const onRecord = typeof supplied === "string" && supplied !== "" ? await this.get(supplied) : undefined;
+        if (onRecord) {
+            return {
+                recordId: supplied,
+                seed: identity.signedKey ? undefined : onRecord.signedIdSeed,
+                existing: onRecord,
+            };
+        }
+        if (identity.signedKey) {
+            const recordId = (0, signed_row_id_1.signedRowIdFor)(identity, record);
+            if ((0, signed_row_id_1.isSignedRowId)(supplied) && supplied !== recordId) {
+                throw new Error(`Row ${supplied} of ${this.tableName} isn't the row its owner and key fields (${identity.signedKey.join(", ")}) name; a row's key can't change, so save a new row instead`);
+            }
+            return { recordId, existing: await this.get(recordId) };
+        }
+        if ((0, signed_row_id_1.isSignedRowId)(supplied)) {
+            // Derived elsewhere (another device of the owner, not synced here yet, or another signed
+            // table's row): its seed is unknown, so saving it would make a second row.
+            throw new Error(`Row ${supplied} isn't a row of ${this.tableName} on this device (it may not have synced here yet, or be another signed table's id); a new row's id comes from Peers, so leave it out or pass a new peer id`);
+        }
+        const seed = typeof supplied === "string" && (0, utils_1.isid)(supplied) ? supplied : (0, utils_1.newid)();
+        const recordId = (0, signed_row_id_1.signedRowId)(identity.name, owner, seed);
+        return { recordId, seed, existing: await this.get(recordId) };
+    }
+    /**
+     * Install the signer every signed table uses, for all SDK copies in this JavaScript realm.
+     * Replaces any prior signer. The host calls it with the signed-in user's key.
+     *
+     * @param fn - Signs a row, typically `addSignatureToObject(row, secretKey)`.
+     */
+    static enableSignedTableSigning(fn) {
+        signingGlobals[signingKey] = fn;
+    }
+}
+exports.SignedPackageTable = SignedPackageTable;
+/** The signer the host installed with {@link SignedPackageTable.enableSignedTableSigning}. */
+function installedSigner() {
+    const sign = signingGlobals[signingKey];
+    if (!sign) {
+        throw new Error("Signed table signing is not enabled. Call SignedPackageTable.enableSignedTableSigning(fn) to enable it.");
+    }
+    return sign;
+}
+/** The table class for `metaData`: {@link SignedPackageTable} when it has `signedBy`, else {@link Table}. */
+function defaultTableClass(metaData) {
+    return metaData.signedBy ? SignedPackageTable : table_1.Table;
+}

package/dist/data/orm/table-container.d.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 import type { ITableDefinitionRecord } from "../table-definitions-table";
-import { Table } from "./table";
+import type { Table } from "./table";
 import type { ITableDefinition, TableConstructor, TableFactory } from "./table-definitions.type";
 import { type ITableMetaData } from "./types";
 /**
@@ -19,7 +19,20 @@ export declare class TableContainer {
     private readonly fallbackDefinitions;
     private fallbackInstances;
     private fallbackSubscribed;
+    private readonly definitionListeners;
     constructor(tableFactory: TableFactory, groupId?: string | undefined);
+    /**
+     * Call `listener` whenever this container takes a table definition it didn't have: a code
+     * definition registered (a package loading, or replacing its tables on an update), or a synced
+     * definition for a table no package defines, first or newer. Sync uses it to recheck rows an
+     * older definition refused. Runs synchronously, after the new definition is in place, so a
+     * table looked up from the listener (or after it) uses it.
+     *
+     * @param listener - Receives the new definition's metadata.
+     * @returns A function that removes the listener.
+     */
+    onDefinitionChanged(listener: (metaData: ITableMetaData) => void): () => void;
+    private definitionChanged;
     /** Register a code-owned table, preserving an existing binding unless overwrite is set. */
     registerTableDefinition<T extends {
         [key: string]: any;
@@ -29,11 +42,13 @@ export declare class TableContainer {
     /**
      * Validate and stage the entire batch before changing any live table binding.
      * An invalid later definition leaves earlier definitions and instances intact.
-     * No table factories or schema persistence run during registration.
+     * Staging runs no table factories or schema persistence. Listeners are notified only after
+     * the entire batch is published, and may then resolve tables against those bindings.
      */
     registerTableDefinitions(definitions: readonly ITableDefinition<any>[], opts?: {
         overwrite?: boolean;
     }): void;
+    /** Stage one definition on a candidate container; true when it took the definition. */
     private stageTableDefinition;
     /**
      * This shouldn't be used unless you have a good reason to bypass the normal table creation process.
@@ -60,6 +75,11 @@ export declare class TableContainer {
     getTableByName<T extends {
         [key: string]: any;
     }>(tableName: string): Table<T>;
+    /**
+     * A table over a synced definition: no package code, so the class is the generic one, or the
+     * signed one when the definition is signed, so a local write still can't skip signing.
+     */
+    private createFallbackInstance;
     /**
      * Lazily look up a fallback table by name from the TableDefinitions system table.
      * On first call, subscribes to TableDefinitions.dataChanged so future synced

package/dist/data/orm/table-container.js

@@ -5,7 +5,7 @@ exports.checkVersionedUpdate = checkVersionedUpdate;
 const rpc_types_1 = require("../../rpc-types");
 const utils_1 = require("../../utils");
 const package_table_identity_1 = require("../package-table-identity");
-const table_1 = require("./table");
+const signed_package_table_1 = require("./signed-package-table");
 const table_definitions_system_1 = require("./table-definitions.system");
 const types_1 = require("./types");
 /**
@@ -63,10 +63,37 @@ class TableContainer {
     fallbackDefinitions = {};
     fallbackInstances = {};
     fallbackSubscribed = false;
+    definitionListeners = new Set();
     constructor(tableFactory, groupId) {
         this.tableFactory = tableFactory;
         this.groupId = groupId;
     }
+    /**
+     * Call `listener` whenever this container takes a table definition it didn't have: a code
+     * definition registered (a package loading, or replacing its tables on an update), or a synced
+     * definition for a table no package defines, first or newer. Sync uses it to recheck rows an
+     * older definition refused. Runs synchronously, after the new definition is in place, so a
+     * table looked up from the listener (or after it) uses it.
+     *
+     * @param listener - Receives the new definition's metadata.
+     * @returns A function that removes the listener.
+     */
+    onDefinitionChanged(listener) {
+        this.definitionListeners.add(listener);
+        return () => {
+            this.definitionListeners.delete(listener);
+        };
+    }
+    definitionChanged(metaData) {
+        for (const listener of this.definitionListeners) {
+            try {
+                listener(metaData);
+            }
+            catch (error) {
+                console.warn(`Table definition listener failed for ${(0, utils_1.getFullTableName)(metaData)}`, error);
+            }
+        }
+    }
     /** Register a code-owned table, preserving an existing binding unless overwrite is set. */
     registerTableDefinition(tableDefinition, opts) {
         this.registerTableDefinitions([tableDefinition], opts);
@@ -74,17 +101,20 @@ class TableContainer {
     /**
      * Validate and stage the entire batch before changing any live table binding.
      * An invalid later definition leaves earlier definitions and instances intact.
-     * No table factories or schema persistence run during registration.
+     * Staging runs no table factories or schema persistence. Listeners are notified only after
+     * the entire batch is published, and may then resolve tables against those bindings.
      */
     registerTableDefinitions(definitions, opts) {
         const candidate = new TableContainer(this.tableFactory, this.groupId);
         Object.assign(candidate.tableDefinitions, this.tableDefinitions);
         Object.assign(candidate.tableInstances, this.tableInstances);
-        for (const definition of definitions)
-            candidate.stageTableDefinition(definition, opts);
+        const staged = definitions.filter((definition) => candidate.stageTableDefinition(definition, opts));
         Object.assign(this.tableDefinitions, candidate.tableDefinitions);
         this.tableInstances = candidate.tableInstances;
+        for (const definition of staged)
+            this.definitionChanged(definition.metaData);
     }
+    /** Stage one definition on a candidate container; true when it took the definition. */
     stageTableDefinition(tableDefinition, opts) {
         const tableId = tableDefinition.metaData.tableId;
         if (!(0, utils_1.isid)(tableId)) {
@@ -94,18 +124,19 @@ class TableContainer {
         const existing = this.tableInstances[tableName] || this.tableDefinitions[tableName];
         if (existing && !opts?.overwrite) {
             console.warn(`Table ${tableName} is already registered.`);
-            return;
+            return false;
         }
         if (existing && opts?.overwrite) {
             const existingDef = this.tableDefinitions[tableName];
             if (existingDef &&
                 (0, utils_1.simpleObjectHash)(existingDef.metaData) === (0, utils_1.simpleObjectHash)(tableDefinition.metaData)) {
-                return; // definition hasn't changed, no need to overwrite
+                return false; // definition hasn't changed, no need to overwrite
             }
             console.warn(`Overwriting table definition for ${tableName}.`);
             delete this.tableInstances[tableName];
         }
         this.tableDefinitions[tableName] = tableDefinition;
+        return true;
     }
     /**
      * This shouldn't be used unless you have a good reason to bypass the normal table creation process.
@@ -136,7 +167,7 @@ class TableContainer {
             schema ??= (0, types_1.fieldsToSchema)(metaData.fields);
             // Check if there's a registered custom constructor
             const registeredDef = this.tableDefinitions[tableName] || table_definitions_system_1.systemTableDefinitions[tableName];
-            const TableClass = tableConstructor || registeredDef?.tableConstructor || (table_1.Table);
+            const TableClass = tableConstructor || registeredDef?.tableConstructor || (0, signed_package_table_1.defaultTableClass)(metaData);
             const table = this.tableFactory(metaData, schema, TableClass, this.groupId);
             this.tableInstances[tableName] = table;
             this.saveTableDefinition(metaData);
@@ -224,13 +255,19 @@ class TableContainer {
         // 4. Check for a fallback definition and create a fallback instance
         const fallbackDef = this.fallbackDefinitions[tableName];
         if (fallbackDef) {
-            const { metaData, schema } = fallbackDef;
-            const table = this.tableFactory(metaData, schema ?? (0, types_1.fieldsToSchema)(metaData.fields), table_1.Table, this.groupId);
+            const table = this.createFallbackInstance(fallbackDef);
             this.fallbackInstances[tableName] = table;
             return table;
         }
         throw new Error(`There is no instantiated table or registered definition for ${tableName}`);
     }
+    /**
+     * A table over a synced definition: no package code, so the class is the generic one, or the
+     * signed one when the definition is signed, so a local write still can't skip signing.
+     */
+    createFallbackInstance({ metaData, schema }) {
+        return this.tableFactory(metaData, schema ?? (0, types_1.fieldsToSchema)(metaData.fields), (0, signed_package_table_1.defaultTableClass)(metaData), this.groupId);
+    }
     /**
      * Lazily look up a fallback table by name from the TableDefinitions system table.
      * On first call, subscribes to TableDefinitions.dataChanged so future synced
@@ -242,8 +279,7 @@ class TableContainer {
         if (this.fallbackInstances[tableName])
             return this.fallbackInstances[tableName];
         if (this.fallbackDefinitions[tableName]) {
-            const { metaData, schema } = this.fallbackDefinitions[tableName];
-            const table = this.tableFactory(metaData, schema ?? (0, types_1.fieldsToSchema)(metaData.fields), table_1.Table, this.groupId);
+            const table = this.createFallbackInstance(this.fallbackDefinitions[tableName]);
             this.fallbackInstances[tableName] = table;
             return table;
         }
@@ -372,6 +408,7 @@ class TableContainer {
         }
         const schema = (0, types_1.fieldsToSchema)(metaData.fields);
         this.fallbackDefinitions[tableName] = { metaData, schema };
+        this.definitionChanged(metaData);
         return true;
     }
     /**
@@ -394,9 +431,7 @@ class TableContainer {
         // 2. Instantiate fallback definitions that don't already have a full instance
         for (const [tableName, fallbackDef] of Object.entries(this.fallbackDefinitions)) {
             if (!this.tableInstances[tableName] && !this.fallbackInstances[tableName]) {
-                const { metaData, schema } = fallbackDef;
-                const table = this.tableFactory(metaData, schema ?? (0, types_1.fieldsToSchema)(metaData.fields), table_1.Table, this.groupId);
-                this.fallbackInstances[tableName] = table;
+                this.fallbackInstances[tableName] = this.createFallbackInstance(fallbackDef);
             }
         }
         // 3. Merge: full instances take precedence, then add fallbacks for tables not in full

package/dist/data/orm/types.d.ts

@@ -24,6 +24,18 @@ export interface ITableMetaData {
     iconClassName?: string;
     localOnly?: boolean;
     versionNumber?: number;
+    /**
+     * The `id` field naming the user who owns each row. The host signs a row with the signed-in
+     * user's key when it's saved, and a group refuses a row that isn't validly signed by its
+     * owner. Set from `defineTable({ signedBy })`; a table has it from its first version or never.
+     */
+    signedBy?: string;
+    /**
+     * In a signed table, the fields that with the owner name a row: each owner has one row per
+     * key, and its id is derived from the owner and the key. Without it, a row's id is derived
+     * from its owner and a host-chosen seed. Set from `defineTable({ signedKey })`; it can't change.
+     */
+    signedKey?: string[];
 }
 /**
  * Convert field metadata to the runtime Zod schema the Runtime validates table rows with.