@peers-app/peers-sdk 0.28.11 → 0.29.0

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.

package/dist/data/package-table-identity.d.ts

@@ -1,4 +1,52 @@
+import { type IField } from "../types/field-type";
 import type { ITableDefinitionRecord } from "./table-definitions-table";
+/**
+ * The columns the host adds to a signed package table (`signedBy`): the owner's signature over
+ * the row, its signing time, the table/context it authorizes, and, in a table without
+ * `signedKey`, the seed its id was derived from. A package's schema doesn't declare them.
+ */
+export declare const SIGNED_TABLE_FIELDS: readonly IField[];
+/** The names of {@link SIGNED_TABLE_FIELDS}. */
+export declare const SIGNED_TABLE_FIELD_NAMES: ReadonlySet<string>;
+/** The parts of a table declaration {@link validateSignedTable} checks. */
+export interface ISignedTableDeclaration {
+    /** The table's declared fields. */
+    fields: readonly IField[];
+    /** The primary key field. */
+    primaryKeyName: string;
+    /** The owner field, if the table is signed. */
+    signedBy?: unknown;
+    /** The key fields, if declared. */
+    signedKey?: unknown;
+    /** The table's storage policy. */
+    localOnly?: boolean;
+}
+/**
+ * Validate a table's `signedBy` and `signedKey` declaration against its fields:
+ * - `signedBy` names a required field of type `id`, and the table isn't local-only (there'd be
+ *   nothing to verify);
+ * - the primary key is a single `id` field other than the owner field, since Peers derives
+ *   every row's id from its owner;
+ * - `signedKey`, when set, lists distinct required scalar fields (string, id, number, boolean)
+ *   other than the primary key and the owner field, and needs `signedBy`;
+ * - the schema doesn't declare the host's signature columns itself.
+ *
+ * @param table - The declaration's fields, primary key, `signedBy`, `signedKey`, and `localOnly`.
+ * @param label - Where the declaration comes from, for errors.
+ * @param options - `hostFields`: the fields already include the host's signature columns (a
+ *   stored definition), so they aren't refused.
+ * @throws When any of those conditions fails.
+ */
+export declare function validateSignedTable(table: ISignedTableDeclaration, label: string, options?: {
+    hostFields?: boolean;
+}): void;
+/**
+ * `fields` with the host's signature columns ({@link SIGNED_TABLE_FIELDS}) added, for a signed
+ * table. Columns already present are kept as they are, so a stored definition round-trips.
+ *
+ * @param fields - A signed table's declared fields.
+ */
+export declare function withSignedTableFields(fields: readonly IField[]): IField[];
 /**
  * Validate a guest-supplied isolated-table or field identifier before it can
  * reach ORM-generated SQL.

package/dist/data/package-table-identity.js

@@ -1,13 +1,149 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNED_TABLE_FIELD_NAMES = exports.SIGNED_TABLE_FIELDS = void 0;
+exports.validateSignedTable = validateSignedTable;
+exports.withSignedTableFields = withSignedTableFields;
 exports.validateIsolatedSqlIdentifier = validateIsolatedSqlIdentifier;
 exports.validateTableIndexes = validateTableIndexes;
 exports.validatePackageTableName = validatePackageTableName;
 exports.packageScopedTableName = packageScopedTableName;
 exports.packageScopedTableId = packageScopedTableId;
 exports.validateTableDefinitionRecord = validateTableDefinitionRecord;
+const field_type_1 = require("../types/field-type");
 const utils_1 = require("../utils");
 const ISOLATED_SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The columns the host adds to a signed package table (`signedBy`): the owner's signature over
+ * the row, its signing time, the table/context it authorizes, and, in a table without
+ * `signedKey`, the seed its id was derived from. A package's schema doesn't declare them.
+ */
+exports.SIGNED_TABLE_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "signature",
+        type: field_type_1.FieldType.string,
+        optional: true,
+        description: "The owner's signature over the row, written by the host.",
+    }),
+    Object.freeze({
+        name: "signedAt",
+        type: field_type_1.FieldType.number,
+        optional: true,
+        description: "When the owner signed the row, written by the host.",
+    }),
+    Object.freeze({
+        name: "signedContextId",
+        type: field_type_1.FieldType.id,
+        optional: true,
+        description: "The context this signature belongs to, written by the host.",
+    }),
+    Object.freeze({
+        name: "signedTableId",
+        type: field_type_1.FieldType.id,
+        optional: true,
+        description: "The package table this signature belongs to, written by the host.",
+    }),
+    Object.freeze({
+        name: "signedIdSeed",
+        type: field_type_1.FieldType.string,
+        optional: true,
+        description: "What the row's id was derived from, with its owner, in a table without signedKey; written by the host.",
+    }),
+]);
+/** The names of {@link SIGNED_TABLE_FIELDS}. */
+exports.SIGNED_TABLE_FIELD_NAMES = new Set(exports.SIGNED_TABLE_FIELDS.map((field) => field.name));
+/** The field types a signed table's key field may have: one scalar each. */
+const SIGNED_KEY_FIELD_TYPES = new Set([
+    field_type_1.FieldType.string,
+    field_type_1.FieldType.id,
+    field_type_1.FieldType.number,
+    field_type_1.FieldType.boolean,
+]);
+/**
+ * Validate a table's `signedBy` and `signedKey` declaration against its fields:
+ * - `signedBy` names a required field of type `id`, and the table isn't local-only (there'd be
+ *   nothing to verify);
+ * - the primary key is a single `id` field other than the owner field, since Peers derives
+ *   every row's id from its owner;
+ * - `signedKey`, when set, lists distinct required scalar fields (string, id, number, boolean)
+ *   other than the primary key and the owner field, and needs `signedBy`;
+ * - the schema doesn't declare the host's signature columns itself.
+ *
+ * @param table - The declaration's fields, primary key, `signedBy`, `signedKey`, and `localOnly`.
+ * @param label - Where the declaration comes from, for errors.
+ * @param options - `hostFields`: the fields already include the host's signature columns (a
+ *   stored definition), so they aren't refused.
+ * @throws When any of those conditions fails.
+ */
+function validateSignedTable(table, label, options = {}) {
+    const { fields, primaryKeyName, signedBy, signedKey, localOnly } = table;
+    if (signedBy === undefined) {
+        if (signedKey !== undefined)
+            throw new Error(`${label}.signedKey needs signedBy`);
+        return;
+    }
+    if (typeof signedBy !== "string" || signedBy.trim() === "") {
+        throw new Error(`${label}.signedBy must name a field`);
+    }
+    const field = fields.find((candidate) => candidate.name === signedBy);
+    if (!field) {
+        throw new Error(`${label}.signedBy names a field the table doesn't have: "${signedBy}"`);
+    }
+    if (field.type !== field_type_1.FieldType.id || field.isArray || field.optional) {
+        throw new Error(`${label}.signedBy must name a required field of type id, a user id`);
+    }
+    if (localOnly) {
+        throw new Error(`${label}.signedBy can't be set on a local-only table: nothing syncs`);
+    }
+    const primaryKey = fields.find((candidate) => candidate.name === primaryKeyName);
+    if (primaryKey && (primaryKey.type !== field_type_1.FieldType.id || primaryKey.isArray)) {
+        throw new Error(`${label}: a signed table's primary key must be an id field`);
+    }
+    if (primaryKeyName === signedBy) {
+        throw new Error(`${label}: a signed table's primary key can't be its owner field; use signedKey: [] for one row per owner`);
+    }
+    if (signedKey !== undefined) {
+        if (!Array.isArray(signedKey))
+            throw new Error(`${label}.signedKey must be a list of fields`);
+        const seen = new Set();
+        for (const name of signedKey) {
+            const keyField = typeof name === "string" ? fields.find((candidate) => candidate.name === name) : undefined;
+            if (!keyField) {
+                throw new Error(`${label}.signedKey names a field the table doesn't have: "${name}"`);
+            }
+            if (seen.has(name))
+                throw new Error(`${label}.signedKey lists "${name}" twice`);
+            seen.add(name);
+            if (name === primaryKeyName || name === signedBy || exports.SIGNED_TABLE_FIELD_NAMES.has(name)) {
+                throw new Error(`${label}.signedKey can't list "${name}": the owner and the id are already part of a row's identity`);
+            }
+            if (!SIGNED_KEY_FIELD_TYPES.has(keyField.type) ||
+                keyField.isArray ||
+                keyField.optional ||
+                keyField.defaultValue !== undefined) {
+                throw new Error(`${label}.signedKey field "${name}" must be a required string, id, number, or boolean`);
+            }
+        }
+    }
+    if (!options.hostFields) {
+        const reserved = fields.find((candidate) => exports.SIGNED_TABLE_FIELD_NAMES.has(candidate.name));
+        if (reserved) {
+            throw new Error(`${label} declares "${reserved.name}", which the host adds to a signed table itself`);
+        }
+    }
+}
+/**
+ * `fields` with the host's signature columns ({@link SIGNED_TABLE_FIELDS}) added, for a signed
+ * table. Columns already present are kept as they are, so a stored definition round-trips.
+ *
+ * @param fields - A signed table's declared fields.
+ */
+function withSignedTableFields(fields) {
+    const names = new Set(fields.map((field) => field.name));
+    return [
+        ...fields,
+        ...exports.SIGNED_TABLE_FIELDS.filter((field) => !names.has(field.name)).map((field) => ({ ...field })),
+    ];
+}
 /**
  * Validate a guest-supplied isolated-table or field identifier before it can
  * reach ORM-generated SQL.
@@ -155,4 +291,19 @@ function validateTableDefinitionRecord(record) {
         throw new Error("Missing primary key column");
     // Only what reaches SQL here: an old-style package may keep a unique index on a synced table.
     validateTableIndexes(meta.indexes, names, "Table indexes", true);
+    validateSignedTable(meta, "Table", { hostFields: true });
+    if (meta.signedBy !== undefined) {
+        if (!meta.packageId)
+            throw new Error("Only a package table can be signed");
+        for (const field of exports.SIGNED_TABLE_FIELDS) {
+            const stored = meta.fields.find((candidate) => candidate.name === field.name);
+            if (!stored ||
+                stored.type !== field.type ||
+                !stored.optional ||
+                stored.isArray ||
+                stored.defaultValue !== undefined) {
+                throw new Error(`A signed table needs the host's "${field.name}" column`);
+            }
+        }
+    }
 }

package/dist/data/signed-row-id.d.ts

@@ -0,0 +1,43 @@
+/** The longest seed a row without `signedKey` may carry. */
+export declare const MAX_SIGNED_ID_SEED_LENGTH = 64;
+/** A value a signed table's key field may hold. */
+export type SignedKeyValue = string | number | boolean;
+/** What derives a signed table's row ids: its name, owner field, and key fields. */
+export interface ISignedRowIdentity {
+    /** The table's declared name (not its physical `<name>_<packageId>`). */
+    name: string;
+    /** The field naming each row's owner. */
+    signedBy: string;
+    /** The fields that, with the owner, name a row; none declared means a seed per row. */
+    signedKey?: readonly string[];
+}
+/**
+ * The id of a row in a signed table: a hash of the table's name, the row's owner, and the row's
+ * key. Every device recomputes it and refuses a row whose id doesn't match, so another member
+ * can't claim an owner's row id: they'd have to name that owner, and only the owner can sign.
+ * The hash part is 21 base-36 characters (about 108 bits), so a collision costs about 2^54
+ * hashes: a member who chooses part of a victim's key could take one id first on some devices
+ * (availability only; the row's contents stay the owner's). That's the ceiling of 25-character
+ * peer ids.
+ *
+ * @param tableName - The table's declared name.
+ * @param ownerUserId - The row's owner.
+ * @param key - The key fields' values in declared order, or the row's seed.
+ */
+export declare function signedRowId(tableName: string, ownerUserId: string, key: readonly SignedKeyValue[] | string): string;
+/**
+ * Whether `id` has the form of a {@link signedRowId}: a hint, not a proof that it was derived.
+ *
+ * @param id - A candidate row id.
+ */
+export declare function isSignedRowId(id: unknown): boolean;
+/**
+ * The id `row` must have in `table`: from its owner and key fields when the table declares
+ * `signedKey`, otherwise from its owner and `seed` (the row's `signedIdSeed`).
+ *
+ * @param table - The table's name, owner field, and key fields.
+ * @param row - The row; its owner and key fields are read.
+ * @param seed - The row's seed, for a table without `signedKey`.
+ * @throws When the owner, a key field, or the seed is missing or isn't a valid value.
+ */
+export declare function signedRowIdFor(table: ISignedRowIdentity, row: Record<string, unknown>, seed?: unknown): string;

package/dist/data/signed-row-id.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SIGNED_ID_SEED_LENGTH = void 0;
+exports.signedRowId = signedRowId;
+exports.isSignedRowId = isSignedRowId;
+exports.signedRowIdFor = signedRowIdFor;
+/**
+ * Row ids of signed package tables (`defineTable({ signedBy })`), bound to each row's owner.
+ *
+ * Kept apart from `package-table-identity.ts` so package code (`define/table.ts`) can compute
+ * them without loading lodash.
+ */
+const peer_id_1 = require("../peer-id");
+/** Leading characters of every signed-row id, so they can't collide with other derived ids. */
+const SIGNED_ROW_ID_PREFIX = "000s";
+/** The longest seed a row without `signedKey` may carry. */
+exports.MAX_SIGNED_ID_SEED_LENGTH = 64;
+/**
+ * The id of a row in a signed table: a hash of the table's name, the row's owner, and the row's
+ * key. Every device recomputes it and refuses a row whose id doesn't match, so another member
+ * can't claim an owner's row id: they'd have to name that owner, and only the owner can sign.
+ * The hash part is 21 base-36 characters (about 108 bits), so a collision costs about 2^54
+ * hashes: a member who chooses part of a victim's key could take one id first on some devices
+ * (availability only; the row's contents stay the owner's). That's the ceiling of 25-character
+ * peer ids.
+ *
+ * @param tableName - The table's declared name.
+ * @param ownerUserId - The row's owner.
+ * @param key - The key fields' values in declared order, or the row's seed.
+ */
+function signedRowId(tableName, ownerUserId, key) {
+    return (0, peer_id_1.deterministicPeerId)(SIGNED_ROW_ID_PREFIX, JSON.stringify(["signed-row/1", tableName, ownerUserId, key]));
+}
+/**
+ * Whether `id` has the form of a {@link signedRowId}: a hint, not a proof that it was derived.
+ *
+ * @param id - A candidate row id.
+ */
+function isSignedRowId(id) {
+    return typeof id === "string" && id.length === 25 && id.startsWith(SIGNED_ROW_ID_PREFIX);
+}
+/**
+ * The id `row` must have in `table`: from its owner and key fields when the table declares
+ * `signedKey`, otherwise from its owner and `seed` (the row's `signedIdSeed`).
+ *
+ * @param table - The table's name, owner field, and key fields.
+ * @param row - The row; its owner and key fields are read.
+ * @param seed - The row's seed, for a table without `signedKey`.
+ * @throws When the owner, a key field, or the seed is missing or isn't a valid value.
+ */
+function signedRowIdFor(table, row, seed) {
+    const owner = row[table.signedBy];
+    if (typeof owner !== "string" || owner === "") {
+        throw new Error(`Table ${table.name}: "${table.signedBy}" must name the row's owner`);
+    }
+    if (table.signedKey) {
+        const values = table.signedKey.map((field) => {
+            const value = row[field];
+            if (typeof value === "string" ||
+                typeof value === "boolean" ||
+                (typeof value === "number" && Number.isFinite(value))) {
+                return value;
+            }
+            throw new Error(`Table ${table.name}: key field "${field}" must have a value`);
+        });
+        return signedRowId(table.name, owner, values);
+    }
+    if (typeof seed !== "string" || seed === "" || seed.length > exports.MAX_SIGNED_ID_SEED_LENGTH) {
+        throw new Error(`Table ${table.name}: the row has no id seed`);
+    }
+    return signedRowId(table.name, owner, seed);
+}

package/dist/define/context.d.ts

@@ -29,6 +29,15 @@ export interface IPackageContext {
     readonly deviceId: string;
     /** Run a tool on a contract this package consumes (or provides), as this call's caller. */
     callConsumedTool(contractId: string, version: number, toolName: string, args?: unknown, options?: IPackageProviderOptions): Promise<unknown>;
+    /**
+     * Ask for a direct connection to another device in this package's data context, before calls
+     * that benefit from one (a large transfer, say). Remote calls use a direct connection when one
+     * exists and the Peers mesh otherwise; they never dial on their own. Resolves `true` when a
+     * direct connection exists (at most about 15 seconds), `false` when none could be made; never
+     * rejects for an unreachable device. The connection may still drop later, and calls then go
+     * through the mesh.
+     */
+    connectToDevice(deviceId: string): Promise<boolean>;
     /** Run a tool on another device. The remote device authorizes the call. */
     callRemoteTool(contractId: string, version: number, deviceId: string, toolName: string, args?: unknown): Promise<unknown>;
     /** Subscribe to an event on a consumed or provided contract. */

package/dist/define/manifest.js

@@ -504,7 +504,7 @@ function observableValueShape(name, schema) {
     return empty ? { ...shape, optional: true } : shape;
 }
 function tableManifest(table) {
-    const { name, description, primaryKeyName, schema, versionNumber, localOnly, indexes } = table.definition;
+    const { name, description, primaryKeyName, schema, versionNumber, localOnly, indexes, signedBy, signedKey, } = table.definition;
     return {
         name,
         description,
@@ -512,6 +512,8 @@ function tableManifest(table) {
         fields: describing(`Table ${name}`, () => irFields(schema)),
         ...(versionNumber === undefined ? {} : { versionNumber }),
         ...(localOnly ? { localOnly: true } : {}),
+        ...(signedBy === undefined ? {} : { signedBy }),
+        ...(signedKey === undefined ? {} : { signedKey: [...signedKey] }),
         ...(indexes?.length
             ? {
                 indexes: indexes.map((index) => ({

package/dist/define/system-contracts.d.ts

@@ -11,6 +11,105 @@ export declare const SystemHttp: import("./contract-ref").IContractRef<{
         packageId: string;
     }): Promise<import("../contracts/system/http-contract").IHttpPolicyInfo>;
 }>;
+/** System Identity v1's package-safe session read. Other identity tools refuse packages. */
+export declare const SystemIdentity: import("./contract-ref").IContractRef<Pick<{
+    startSource(input: import("..").DevicePairingStartSourceInput): Promise<import("..").DevicePairingState>;
+    startDestination(input?: import("..").DevicePairingStartDestinationInput): Promise<import("..").DevicePairingState>;
+    approve(input: import("..").DevicePairingCeremonyAction): Promise<import("..").DevicePairingState>;
+    reject(input: import("..").DevicePairingCeremonyAction): Promise<import("..").DevicePairingState>;
+    cancel(input: import("..").DevicePairingCeremonyAction): Promise<import("..").DevicePairingState>;
+    getSession(): Promise<import("../contracts/system/identity-contract").IIdentitySessionInfo>;
+    signIn(input: {
+        userId: string;
+        secretKey: string;
+    }): Promise<void>;
+    signOut(): Promise<void>;
+    registerWithPeersServices(): Promise<{
+        token: string;
+    }>;
+    getKeyInfo(): Promise<import("../contracts/system/identity-contract").IIdentityKeyInfo>;
+    rotateKey(input?: import("../contracts/system/identity-contract").IIdentityRotateKeyInput): Promise<import("../contracts/system/identity-contract").IIdentityRotateKeyResult>;
+    getRecoveryEmail(): Promise<{
+        email?: string;
+    }>;
+    bindEmailStart(input: {
+        email: string;
+    }): Promise<{
+        status: string;
+    }>;
+    bindEmailVerify(input: {
+        email: string;
+        code: string;
+    }): Promise<{
+        email: string;
+    }>;
+    unbindEmail(): Promise<{
+        status: string;
+    }>;
+    startAnchorSession(input?: {
+        userId?: string;
+    }): Promise<{
+        status: string;
+    }>;
+    confirmAnchorSession(input: {
+        code: string;
+        userId?: string;
+    }): Promise<{
+        expiresIn: number;
+    }>;
+    contestRecovery(input: {
+        pendingKey: string;
+    }): Promise<{
+        status: string;
+    }>;
+    acceptRecovery(input: {
+        userId: string;
+        pendingKey: string;
+    }): Promise<{
+        status: string;
+    }>;
+    recoverKey(input: {
+        userId: string;
+        publish?: "anchors" | "manual";
+        confirm?: boolean;
+    }): Promise<{
+        publicKey: string;
+        committed: boolean;
+        manualDocument?: import("..").IAnchorDocument;
+        warnings: string[];
+    }>;
+    setAnchors(input: {
+        anchors: import("..").IAnchorRef[];
+    }): Promise<{
+        anchors: import("..").IAnchorRef[];
+    }>;
+    passkeyRegisterStart(input: {
+        origin: string;
+    }): Promise<{
+        options: Record<string, unknown>;
+    }>;
+    passkeyRegisterFinish(input: {
+        response: Record<string, unknown>;
+    }): Promise<{
+        status: string;
+    }>;
+    passkeyAuthStart(input: {
+        origin: string;
+        userId?: string;
+    }): Promise<{
+        options: Record<string, unknown>;
+    }>;
+    passkeyAuthFinish(input: {
+        response: Record<string, unknown>;
+        userId?: string;
+    }): Promise<{
+        expiresIn: number;
+    }>;
+}, "getSession">>;
+/** Current verified members of the calling package's own data context, including Readers. */
+export declare const SystemGroupMembers: import("./contract-ref").IContractRef<{
+    getMembers(): Promise<import("../contracts/system/group-members-contract").IGroupMembersResult>;
+}>;
 /**
  * System Scheduler v1: run one of the package's own tools later, on this device. Declare it
  * with `pkg.consumes(SystemScheduler)`, optionally.

package/dist/define/system-contracts.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SystemContractCatalog = exports.SystemScheduler = exports.SystemHttp = void 0;
+exports.SystemContractCatalog = exports.SystemScheduler = exports.SystemGroupMembers = exports.SystemIdentity = exports.SystemHttp = void 0;
 const system_ids_1 = require("../system-ids");
 const contract_ref_1 = require("./contract-ref");
 /**
@@ -8,6 +8,10 @@ const contract_ref_1 = require("./contract-ref");
  * with `pkg.consumes(SystemHttp)`.
  */
 exports.SystemHttp = (0, contract_ref_1.contractRef)(system_ids_1.httpContractId, 1);
+/** System Identity v1's package-safe session read. Other identity tools refuse packages. */
+exports.SystemIdentity = (0, contract_ref_1.contractRef)(system_ids_1.identityContractId, 1);
+/** Current verified members of the calling package's own data context, including Readers. */
+exports.SystemGroupMembers = (0, contract_ref_1.contractRef)(system_ids_1.groupMembersContractId, 1);
 /**
  * System Scheduler v1: run one of the package's own tools later, on this device. Declare it
  * with `pkg.consumes(SystemScheduler)`, optionally.

package/dist/define/table.d.ts

@@ -23,6 +23,28 @@ export interface IPackageTableDefinition<S extends z.AnyZodObject = z.AnyZodObje
      * schema change, so raise `versionNumber`.
      */
     indexes?: IPackageTableIndex<S>[];
+    /**
+     * Make each row its owner's: the named field, a required `zodPeerId`, holds the user id of
+     * the member who owns the row. Peers signs a row with the signed-in user's key when it's
+     * saved, refuses a save that names anyone else as owner, and in a group refuses any row
+     * (synced or local) that isn't validly signed by its owner, a Writer, or that was signed
+     * before the row on record. Peers sets each row's id from its owner (see `signedKey`), so use
+     * the id `save` returns. Rows aren't deleted: mark them instead. `save` refuses `weakInsert`,
+     * since a row counts from when its owner signs it. Can't be combined with
+     * `localOnly`; the primary key must be a `zodPeerId` other than the owner field; and the
+     * schema must leave `signature`, `signedAt`, `signedContextId`, `signedTableId`, and
+     * `signedIdSeed` to Peers. Signatures authorize only this table and context. A table is
+     * signed from its first version or not at all.
+     */
+    signedBy?: Extract<keyof z.infer<S>, string>;
+    /**
+     * With `signedBy`: the fields that, with the owner, name a row, so each owner has one row per
+     * key (`[]` for one row per owner). A row's id is derived from its owner and these fields:
+     * saving the same key again updates that row, and {@link IPackageTable.rowId} gives the id.
+     * Each is a required string, id, number, or boolean, and a row's key can't change. Without
+     * it, Peers derives a new row's id from its owner and the id you pass. Can't change later.
+     */
+    signedKey?: readonly Extract<keyof z.infer<S>, string>[];
     /**
      * The table's class, to override its methods: `Feeds(ctx)` returns one, and so does every
      * consumer call through a contract, so an override is always the logic in use. Defaults to
@@ -150,6 +172,16 @@ export interface IPackageTable<S extends z.AnyZodObject = z.AnyZodObject, N exte
     readonly definition: Readonly<IPackageTableDefinition<S>> & {
         readonly name: N;
     };
+    /**
+     * The id of a row in a table declared with `signedBy` and `signedKey`, from its owner and key
+     * fields: what `save` stores the row under, for `get`. Throws for any other table (a signed
+     * table without `signedKey` gets its ids from Peers when rows are first saved).
+     * Parses the owner and key inputs with their field schemas, including transforms, as `save`
+     * does; other fields may be omitted.
+     *
+     * @param row - The owner field and the key fields.
+     */
+    rowId(row: Partial<z.input<S>>): string;
 }
 /**
  * Declare one of the package's tables from a zod schema.