@peers-app/peers-sdk 0.19.14 → 0.20.1

package/dist/contracts/system/device-operations-contract.d.ts

@@ -0,0 +1,72 @@
+import type { ITool } from "../../data/tools";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Device Operations contract. */
+export declare const DEVICE_OPERATIONS_CONTRACT_VERSION = 1;
+/** Maximum SQL text accepted by the remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_QUERY_LENGTH = 20000;
+/** Maximum rows returned by one remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_ROWS = 500;
+/** Maximum serialized result size returned by one remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_RESULT_BYTES = 1000000;
+/** Maximum tools returned by one remote tool-list operation. */
+export declare const DEVICE_OPERATIONS_MAX_TOOLS = 100;
+/** Stable IDs for the live tools implementing System Device Operations v1. */
+export declare const deviceOperationsToolIds: {
+    readonly getDeviceStatus: "00mriijkhr4iptdefp4a7ifcq";
+    readonly queryDatabase: "00mriijkhrd54n33ey0omeejo";
+    readonly listTools: "00mriijkhr4fpyd70nyo5iqlq";
+    readonly getTool: "00mriijkhrid4wpf89i4ikvay";
+    readonly runTool: "00mriijkhrfequch2qaeoihol";
+};
+/** Portable operations supported by System Device Operations v1. */
+export type DeviceOperationCapability = "device-status" | "database-query" | "tool-list" | "tool-get" | "tool-run";
+/** Status and capability information returned by a remote device. */
+export interface IDeviceOperationStatus {
+    deviceId: string;
+    userId: string;
+    dataContextId: string;
+    contractVersion: number;
+    capabilities: DeviceOperationCapability[];
+    limits: {
+        maxQueryLength: number;
+        maxRows: number;
+        maxResultBytes: number;
+        maxTools: number;
+    };
+}
+/** Input for a bounded, read-only remote SQLite query. */
+export interface IDeviceDatabaseQueryInput {
+    query: string;
+}
+/** Serializable result from a bounded, read-only remote SQLite query. */
+export interface IDeviceDatabaseQueryResult {
+    columns: string[];
+    rows: unknown[][];
+    rowCount: number;
+    truncated: boolean;
+}
+/** Input for listing tools available in the selected data context. */
+export interface IDeviceToolListInput {
+    limit?: number;
+}
+/** Input for exact-ID, exact-name, or unambiguous-text tool lookup. */
+export interface IDeviceToolLookupInput {
+    toolIdOrName: string;
+}
+/** Input for running a tool on the remote device. */
+export interface IDeviceToolRunInput extends IDeviceToolLookupInput {
+    args?: Record<string, unknown>;
+    assistantId?: string;
+}
+/** Result of an unambiguous tool lookup, or `null` when no tool matched. */
+export type IDeviceToolLookupResult = ITool | null;
+/**
+ * Return the portable, owner-authorized device administration contract shape.
+ *
+ * The contract intentionally exposes explicit operations instead of arbitrary table,
+ * filesystem, shell, UI, or lifecycle access. Authorization is supplied by the verified
+ * connection host before the live resolver is invoked.
+ */
+export declare function getDeviceOperationsContractDefinition(): IContractDefinition;
+/** Package ID used by live System Device Operations tool instances. */
+export declare const deviceOperationsProviderPackageId = "000peers0system0000000001";

package/dist/contracts/system/device-operations-contract.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceOperationsProviderPackageId = exports.deviceOperationsToolIds = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+exports.getDeviceOperationsContractDefinition = getDeviceOperationsContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+/** Version of the built-in System Device Operations contract. */
+exports.DEVICE_OPERATIONS_CONTRACT_VERSION = 1;
+/** Maximum SQL text accepted by the remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = 20_000;
+/** Maximum rows returned by one remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_ROWS = 500;
+/** Maximum serialized result size returned by one remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = 1_000_000;
+/** Maximum tools returned by one remote tool-list operation. */
+exports.DEVICE_OPERATIONS_MAX_TOOLS = 100;
+/** Stable IDs for the live tools implementing System Device Operations v1. */
+exports.deviceOperationsToolIds = {
+    getDeviceStatus: "00mriijkhr4iptdefp4a7ifcq",
+    queryDatabase: "00mriijkhrd54n33ey0omeejo",
+    listTools: "00mriijkhr4fpyd70nyo5iqlq",
+    getTool: "00mriijkhrid4wpf89i4ikvay",
+    runTool: "00mriijkhrfequch2qaeoihol",
+};
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Return the portable, owner-authorized device administration contract shape.
+ *
+ * The contract intentionally exposes explicit operations instead of arbitrary table,
+ * filesystem, shell, UI, or lifecycle access. Authorization is supplied by the verified
+ * connection host before the live resolver is invoked.
+ */
+function getDeviceOperationsContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.deviceOperationsContractId,
+        version: exports.DEVICE_OPERATIONS_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Device Operations",
+        description: "Owner-authorized status, bounded read-only database, and installed-tool operations.",
+        tables: [],
+        tools: [
+            {
+                name: "getDeviceStatus",
+                usageDescription: "Return this device's identity, supported operations, and limits.",
+                inputFields: [],
+                outputFields: [
+                    field("deviceId", field_type_1.FieldType.id, "The provider device ID."),
+                    field("userId", field_type_1.FieldType.id, "The provider user ID."),
+                    field("dataContextId", field_type_1.FieldType.id, "The selected data context ID."),
+                    field("contractVersion", field_type_1.FieldType.number, "The supported contract version."),
+                    field("capabilities", field_type_1.FieldType.string, "Supported portable operations.", {
+                        isArray: true,
+                    }),
+                    field("limits", field_type_1.FieldType.object, "Provider-enforced request and result limits."),
+                ],
+            },
+            {
+                name: "queryDatabase",
+                usageDescription: "Run one bounded read-only SELECT or approved PRAGMA query.",
+                inputFields: [field("query", field_type_1.FieldType.string, "One read-only SQLite statement.")],
+                outputFields: [
+                    field("columns", field_type_1.FieldType.string, "Result column names.", { isArray: true }),
+                    field("rows", field_type_1.FieldType.any, "Serializable result rows.", { isArray: true }),
+                    field("rowCount", field_type_1.FieldType.number, "Number of returned rows."),
+                    field("truncated", field_type_1.FieldType.boolean, "Whether rows were omitted by provider limits."),
+                ],
+            },
+            {
+                name: "listTools",
+                usageDescription: "List installed tools in the selected data context.",
+                inputFields: [
+                    field("limit", field_type_1.FieldType.number, "Maximum tools to return.", { optional: true }),
+                ],
+                outputFields: [
+                    field("tools", field_type_1.FieldType.object, "Installed tool definitions.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getTool",
+                usageDescription: "Resolve a tool by exact ID, exact name, or unambiguous text.",
+                inputFields: [
+                    field("toolIdOrName", field_type_1.FieldType.string, "Tool ID, exact name, or search text."),
+                ],
+                outputFields: [
+                    field("tool", field_type_1.FieldType.object, "The matching tool definition, or null.", {
+                        optional: true,
+                    }),
+                ],
+            },
+            {
+                name: "runTool",
+                usageDescription: "Resolve and run an installed tool in the selected data context.",
+                inputFields: [
+                    field("toolIdOrName", field_type_1.FieldType.string, "Tool ID, exact name, or search text."),
+                    field("args", field_type_1.FieldType.object, "Tool input arguments.", { optional: true }),
+                    field("assistantId", field_type_1.FieldType.id, "Optional assistant execution context.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.any, "The tool execution result.")],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+/** Package ID used by live System Device Operations tool instances. */
+exports.deviceOperationsProviderPackageId = system_ids_1.peersSystemPackageId;

package/dist/contracts/system/logs-contract.d.ts

@@ -0,0 +1,24 @@
+import type { DataContext } from "../../context/data-context";
+import type { IContractResolution } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Logs contract. */
+export declare const LOGS_CONTRACT_VERSION = 1;
+/**
+ * The first built-in **system contract**: read and write the local device's console logs.
+ *
+ * It declares only the `ConsoleLogs` table — the table's own methods (`list`, `count`,
+ * `deleteOldLogs`, …) are the entire surface we need, so no bespoke tools are required.
+ * The table shape is derived from {@link consoleLogSchema} so the contract stays accurate.
+ *
+ * Built lazily and memoized: reading `consoleLogsMetaData` / `consoleLogSchema` at module
+ * load would race the import cycle between the logging table and the SDK barrel, so we defer
+ * construction until first use (well after all modules have finished initializing).
+ */
+export declare function getLogsContractDefinition(): IContractDefinition;
+/**
+ * Resolve the logs contract to its live implementation for a data context: the
+ * `ConsoleLogs` table backing that context.
+ */
+export declare function resolveLogsContract(ctx: {
+    dataContext: DataContext;
+}): IContractResolution;

package/dist/contracts/system/logs-contract.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOGS_CONTRACT_VERSION = void 0;
+exports.getLogsContractDefinition = getLogsContractDefinition;
+exports.resolveLogsContract = resolveLogsContract;
+const user_context_singleton_1 = require("../../context/user-context-singleton");
+const types_1 = require("../../data/orm/types");
+const console_logs_table_1 = require("../../logging/console-logs.table");
+const system_ids_1 = require("../../system-ids");
+const contract_resolvers_1 = require("../contract-resolvers");
+/** Version of the built-in System Logs contract. */
+exports.LOGS_CONTRACT_VERSION = 1;
+let _definition;
+/**
+ * The first built-in **system contract**: read and write the local device's console logs.
+ *
+ * It declares only the `ConsoleLogs` table — the table's own methods (`list`, `count`,
+ * `deleteOldLogs`, …) are the entire surface we need, so no bespoke tools are required.
+ * The table shape is derived from {@link consoleLogSchema} so the contract stays accurate.
+ *
+ * Built lazily and memoized: reading `consoleLogsMetaData` / `consoleLogSchema` at module
+ * load would race the import cycle between the logging table and the SDK barrel, so we defer
+ * construction until first use (well after all modules have finished initializing).
+ */
+function getLogsContractDefinition() {
+    if (!_definition) {
+        _definition = {
+            contractId: system_ids_1.logsContractId,
+            version: exports.LOGS_CONTRACT_VERSION,
+            devTag: "dev",
+            name: "System Logs",
+            description: "Read and write the local device's console logs.",
+            tables: [
+                {
+                    name: console_logs_table_1.consoleLogsMetaData.name,
+                    description: console_logs_table_1.consoleLogsMetaData.description,
+                    primaryKeyName: console_logs_table_1.consoleLogsMetaData.primaryKeyName,
+                    fields: (0, types_1.schemaToFields)(console_logs_table_1.consoleLogSchema),
+                },
+            ],
+            tools: [],
+            observables: [],
+            events: [],
+        };
+    }
+    return _definition;
+}
+/**
+ * Resolve the logs contract to its live implementation for a data context: the
+ * `ConsoleLogs` table backing that context.
+ */
+function resolveLogsContract(ctx) {
+    const consoleLogs = (0, user_context_singleton_1.getTableContainer)(ctx.dataContext).getTable(console_logs_table_1.consoleLogsMetaData, console_logs_table_1.consoleLogSchema, console_logs_table_1.ConsoleLogsTable);
+    return {
+        contractId: system_ids_1.logsContractId,
+        version: exports.LOGS_CONTRACT_VERSION,
+        tables: { [console_logs_table_1.consoleLogsMetaData.name]: consoleLogs },
+    };
+}
+(0, contract_resolvers_1.registerContractResolver)(system_ids_1.logsContractId, exports.LOGS_CONTRACT_VERSION, resolveLogsContract);

package/dist/contracts/types.d.ts

@@ -1,11 +1,12 @@
 import type { Table } from "../data/orm/table";
 import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { IToolInstance } from "../data/tools";
+import type { Event } from "../events";
 import type { Observable } from "../observable";
 import type { FieldType, IField } from "../types/field-type";
 /**
- * A versioned interface definition declaring the shape of tables, tools, and
- * observables that a package provides. Pure data — no executable code.
+ * A versioned interface definition declaring the shape of tables, tools,
+ * observables, and events that a package provides. Pure data — no executable code.
  */
 export interface IContractDefinition {
     contractId: string;
@@ -17,6 +18,12 @@ export interface IContractDefinition {
     tables: IContractTable[];
     tools: IContractTool[];
     observables: IContractObservable[];
+    /**
+     * Events a provider may emit and consumers may subscribe to. Optional so
+     * existing contract definitions stay valid; the {@link ContractBuilder} always
+     * emits an array (possibly empty) and consumers read `contract.events ?? []`.
+     */
+    events?: IContractEvent[];
 }
 /** Table shape within a contract — derived from ITableMetaData + IField[]. */
 export interface IContractTable {
@@ -39,6 +46,18 @@ export interface IContractObservable {
     valueType: FieldType;
     writable: boolean;
 }
+/**
+ * A generic event a contract provider may emit. Consumers subscribe by name; the
+ * provider only forwards payloads over the transport while at least one consumer
+ * has an active subscription (see the provider session). Pure shape — the live
+ * {@link Event} is supplied at resolution time in {@link IContractResolution.events}.
+ */
+export interface IContractEvent {
+    name: string;
+    description: string;
+    /** Shape of the payload delivered to subscribers when the event fires. */
+    payloadFields: IField[];
+}
 /**
  * A reference to a contract that a package wants to consume.
  * Recorded during `definePackage` and checked at install time.
@@ -46,6 +65,7 @@ export interface IContractObservable {
 export interface IConsumedContract {
     contractId: string;
     version: number;
+    optional?: boolean;
 }
 /**
  * Declares that the owning contract's implementation also satisfies another
@@ -86,15 +106,18 @@ export interface IResolvedContract {
     tables: Record<string, Table<any>>;
     tools: Record<string, IToolInstance>;
     observables: Record<string, Observable<any>>;
+    /** Live events the provider forwards from, keyed by contract event name. */
+    events?: Record<string, Event<any>>;
 }
 /** Outcome of a validation check. */
 export interface IValidationResult {
     valid: boolean;
     errors: IValidationError[];
 }
+/** One incompatibility found while validating a contract definition or provider. */
 export interface IValidationError {
-    /** Which element failed: `'table'`, `'tool'`, `'observable'`, `'contract'` */
-    kind: "table" | "tool" | "observable" | "contract" | "field";
+    /** Which contract element failed validation. */
+    kind: "table" | "tool" | "observable" | "event" | "contract" | "field";
     /** Name of the element (table name, tool name, etc.) */
     name: string;
     message: string;

package/dist/contracts/validate.d.ts

@@ -1,8 +1,8 @@
 import type { IAlsoImplementsDeclaration, IContractDefinition, IValidationResult } from "./types";
 /**
  * Validate that an implementation contract satisfies a target contract shape.
- * The implementation must be a superset: all contract tables, tools, and
- * observables must be present with compatible shapes.
+ * The implementation must be a superset: all contract tables, tools,
+ * observables, and events must be present with compatible shapes.
  */
 export declare function validateProviderSatisfiesContract(impl: IContractDefinition, contract: IContractDefinition): IValidationResult;
 /**

package/dist/contracts/validate.js

@@ -114,10 +114,36 @@ function validateToolFields(contractTool, implTool, direction) {
     }
     return errors;
 }
+function validateEventFields(contractEvent, implEvent) {
+    const errors = [];
+    const implFieldMap = new Map(implEvent.payloadFields.map((field) => [field.name, field]));
+    for (const contractField of contractEvent.payloadFields) {
+        const implField = implFieldMap.get(contractField.name);
+        if (!implField) {
+            if (!contractField.optional) {
+                errors.push({
+                    kind: "field",
+                    name: `${contractEvent.name}.payload.${contractField.name}`,
+                    message: `Required payload field '${contractField.name}' missing from implementation event '${implEvent.name}'`,
+                });
+            }
+            continue;
+        }
+        const compat = isFieldCompatible(contractField, implField);
+        if (compat) {
+            errors.push({
+                kind: "field",
+                name: `${contractEvent.name}.payload.${contractField.name}`,
+                message: `Payload field '${contractField.name}' in event '${implEvent.name}': ${compat}`,
+            });
+        }
+    }
+    return errors;
+}
 /**
  * Validate that an implementation contract satisfies a target contract shape.
- * The implementation must be a superset: all contract tables, tools, and
- * observables must be present with compatible shapes.
+ * The implementation must be a superset: all contract tables, tools,
+ * observables, and events must be present with compatible shapes.
  */
 function validateProviderSatisfiesContract(impl, contract) {
     const errors = [];
@@ -184,6 +210,20 @@ function validateProviderSatisfiesContract(impl, contract) {
             });
         }
     }
+    // Events
+    const implEventMap = new Map((impl.events ?? []).map((event) => [event.name, event]));
+    for (const contractEvent of contract.events ?? []) {
+        const implEvent = implEventMap.get(contractEvent.name);
+        if (!implEvent) {
+            errors.push({
+                kind: "event",
+                name: contractEvent.name,
+                message: `Event '${contractEvent.name}' required by contract but not provided by implementation`,
+            });
+            continue;
+        }
+        errors.push(...validateEventFields(contractEvent, implEvent));
+    }
     return errors.length === 0 ? ok() : fail(errors);
 }
 /**
@@ -212,11 +252,13 @@ function validateImmutability(existing, incoming) {
         tables: existing.tables,
         tools: existing.tools,
         observables: existing.observables,
+        events: existing.events ?? [],
     });
     const incomingShape = JSON.stringify({
         tables: incoming.tables,
         tools: incoming.tools,
         observables: incoming.observables,
+        events: incoming.events ?? [],
     });
     if (existingShape !== incomingShape) {
         return fail([

package/dist/data/assistants.d.ts

@@ -18,8 +18,8 @@ export declare const assistantSchema: z.ZodObject<{
     packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;
@@ -42,10 +42,10 @@ export declare const assistantSchema: z.ZodObject<{
     toolInclusionStrategy?: ToolInclusionStrategy | undefined;
 }>;
 export type IAssistant = z.infer<typeof assistantSchema>;
-export declare function Assistants(dataContext?: DataContext): import("./orm").Table<{
+export declare function Assistants(dataContext?: DataContext): import("..").Table<{
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;
@@ -68,8 +68,8 @@ export declare const userPrimaryAssistantVar: import("./persistent-vars").Persis
 export declare const groupPrimaryAssistantVar: import("./persistent-vars").PersistentVar<string | undefined>;
 export declare const getPrimaryAssistant: (dataContext?: DataContext) => Promise<{
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;

package/dist/data/channels.d.ts

@@ -20,7 +20,7 @@ export declare const channelSchema: z.ZodObject<{
     owningGroupId: string;
 }>;
 export type IChannel = z.infer<typeof channelSchema>;
-export declare function Channels(dataContext?: DataContext): import("./orm").Table<{
+export declare function Channels(dataContext?: DataContext): import("..").Table<{
     name: string;
     description: string;
     createdAt: Date;

package/dist/data/devices.d.ts

@@ -38,7 +38,7 @@ export interface IDeviceHandshake extends IDeviceInfo {
     serverAddress: string;
     timestamp: number;
 }
-export declare function Devices(dataContext?: DataContext): import("./orm").Table<{
+export declare function Devices(dataContext?: DataContext): import("..").Table<{
     userId: string;
     deviceId: string;
     firstSeen: Date;

package/dist/data/embeddings.d.ts

@@ -34,7 +34,7 @@ export declare const embeddingSchema: z.ZodObject<{
     embeddingType: string;
 }>;
 export type IEmbedding = z.infer<typeof embeddingSchema>;
-export declare function Embeddings(dataContext?: DataContext): import("./orm").Table<{
+export declare function Embeddings(dataContext?: DataContext): import("..").Table<{
     metadata: {
         fkId?: string | undefined;
     } & {

package/dist/data/group-secret.d.ts

@@ -0,0 +1,21 @@
+import type { DataContext } from "../context/data-context";
+import { type IPublicKeys, type IPublicPrivateKeys } from "../keys";
+import { type IPersistentVar } from "./persistent-vars";
+/** Prefix used for each group's encrypted secret-key persistent variable. */
+export declare const GROUP_SECRET_KEY_PVAR_PREFIX = "groupSecretKey_";
+/** Return the personal-context persistent-variable name for a group secret key. */
+export declare function groupSecretKeyPvarName(groupId: string): string;
+/**
+ * Derive a group secret's public keys and verify they match the signed group record.
+ *
+ * @throws When the secret is malformed or derives different signing/box public keys.
+ */
+export declare function validateGroupSecretKey(secretKey: string, expected: IPublicKeys): IPublicPrivateKeys;
+/**
+ * Save a known-valid group secret in the user's personal context.
+ *
+ * Legacy random IDs and duplicate name rows are canonicalized before the replacement is
+ * encrypted and saved. The caller must supply the expected signed group public keys, so this
+ * function cannot silently install unrelated key material.
+ */
+export declare function saveGroupSecretKey(userDataContext: DataContext, groupId: string, secretKey: string, expected: IPublicKeys): Promise<IPersistentVar>;

package/dist/data/group-secret.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROUP_SECRET_KEY_PVAR_PREFIX = void 0;
+exports.groupSecretKeyPvarName = groupSecretKeyPvarName;
+exports.validateGroupSecretKey = validateGroupSecretKey;
+exports.saveGroupSecretKey = saveGroupSecretKey;
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const persistent_vars_1 = require("./persistent-vars");
+/** Prefix used for each group's encrypted secret-key persistent variable. */
+exports.GROUP_SECRET_KEY_PVAR_PREFIX = "groupSecretKey_";
+/** Return the personal-context persistent-variable name for a group secret key. */
+function groupSecretKeyPvarName(groupId) {
+    return `${exports.GROUP_SECRET_KEY_PVAR_PREFIX}${groupId}`;
+}
+/**
+ * Derive a group secret's public keys and verify they match the signed group record.
+ *
+ * @throws When the secret is malformed or derives different signing/box public keys.
+ */
+function validateGroupSecretKey(secretKey, expected) {
+    const derived = (0, keys_1.hydrateKeys)(secretKey);
+    if (derived.publicKey !== expected.publicKey || derived.publicBoxKey !== expected.publicBoxKey) {
+        throw new Error("Group secret key does not match the group's public keys");
+    }
+    return derived;
+}
+/**
+ * Save a known-valid group secret in the user's personal context.
+ *
+ * Legacy random IDs and duplicate name rows are canonicalized before the replacement is
+ * encrypted and saved. The caller must supply the expected signed group public keys, so this
+ * function cannot silently install unrelated key material.
+ */
+async function saveGroupSecretKey(userDataContext, groupId, secretKey, expected) {
+    validateGroupSecretKey(secretKey, expected);
+    const name = groupSecretKeyPvarName(groupId);
+    const table = (0, persistent_vars_1.PersistentVars)(userDataContext);
+    const records = await table.list({ name });
+    let canonical = records.find((record) => record.persistentVarId === (0, utils_1.deterministicPvarId)(name));
+    for (const record of records) {
+        if (record !== canonical) {
+            canonical = await table.migrateLegacyId(record);
+        }
+    }
+    return table.save({
+        persistentVarId: canonical?.persistentVarId ?? "",
+        name,
+        scope: "groupUser",
+        isSecret: true,
+        value: { value: secretKey },
+    });
+}

package/dist/data/index.d.ts

@@ -8,6 +8,7 @@ export * from "./files";
 export * from "./group-member-roles";
 export * from "./group-members";
 export * from "./group-permissions";
+export * from "./group-secret";
 export * from "./group-share";
 export * from "./groups";
 export * from "./messages";

package/dist/data/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./files"), exports);
 __exportStar(require("./group-member-roles"), exports);
 __exportStar(require("./group-members"), exports);
 __exportStar(require("./group-permissions"), exports);
+__exportStar(require("./group-secret"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
 __exportStar(require("./messages"), exports);

package/dist/data/messages.d.ts

@@ -35,7 +35,7 @@ export declare const messageSchema: z.ZodObject<{
     fileIds?: string[] | undefined;
 }>;
 export type IMessage = z.infer<typeof messageSchema>;
-export declare function Messages(dataContext?: DataContext): import("./orm").Table<{
+export declare function Messages(dataContext?: DataContext): import("..").Table<{
     message: string;
     userId: string;
     createdAt: Date;

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

@@ -1,3 +1,9 @@
+/**
+ * Return whether a table method was explicitly marked for remote invocation by
+ * {@link ProxyClientTableMethodCalls}. Client proxies are recognized through their
+ * marked `__original` implementation as well.
+ */
+export declare function isContractRemoteTableMethod(method: unknown): boolean;
 /**
  * Decorator that marks a table method as server-side only.
  * When used on the client side, these methods will be automatically proxied

package/dist/data/orm/decorators.js

@@ -1,7 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isContractRemoteTableMethod = isContractRemoteTableMethod;
 exports.ProxyClientTableMethodCalls = ProxyClientTableMethodCalls;
 const rpc_types_1 = require("../../rpc-types");
+const contractRemoteTableMethod = Symbol("contractRemoteTableMethod");
+function markContractRemoteTableMethod(method) {
+    Object.defineProperty(method, contractRemoteTableMethod, { value: true });
+}
+/**
+ * Return whether a table method was explicitly marked for remote invocation by
+ * {@link ProxyClientTableMethodCalls}. Client proxies are recognized through their
+ * marked `__original` implementation as well.
+ */
+function isContractRemoteTableMethod(method) {
+    if (typeof method !== "function") {
+        return false;
+    }
+    const candidate = method;
+    return Boolean(candidate[contractRemoteTableMethod] || candidate.__original?.[contractRemoteTableMethod]);
+}
 /**
  * Decorator that marks a table method as server-side only.
  * When used on the client side, these methods will be automatically proxied
@@ -13,6 +30,9 @@ const rpc_types_1 = require("../../rpc-types");
  */
 function ProxyClientTableMethodCalls() {
     return (target, context) => {
+        if (context.kind === "method") {
+            markContractRemoteTableMethod(target);
+        }
         if (context.kind === "method" && rpc_types_1.isClient) {
             const methodName = context.name;
             // WARNING: Using typescript's magical `this` param
@@ -21,6 +41,7 @@ function ProxyClientTableMethodCalls() {
                 return rpc_types_1.rpcServerCalls.tableMethodCall(dataContextId, this.tableName, methodName, ...args);
             };
             proxyFn.__original = target;
+            markContractRemoteTableMethod(proxyFn);
             return proxyFn;
         }
         return target;