@peers-app/peers-sdk 0.28.11 → 0.29.0

package/dist/keys.js

@@ -33,9 +33,9 @@ const sha2_1 = require("@noble/hashes/sha2");
 const buffer_1 = require("buffer");
 const ed2curve = require("ed2curve");
 const nacl = require("tweetnacl");
-const utils = require("tweetnacl-util");
 const tweetnacl_util_1 = require("tweetnacl-util");
 const tx_encoding_1 = require("./device/tx-encoding");
+const native_codecs_1 = require("./native-codecs");
 const serial_json_1 = require("./serial-json");
 globalThis.Buffer = buffer_1.Buffer; // shim for browsers/RN
 const _stableStringify = require("fast-json-stable-stringify");
@@ -113,15 +113,42 @@ function canonicalJSONString(obj) {
 function legacySignatureJSONString(obj) {
     return (0, serial_json_1.toJSONString)(obj);
 }
-/** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
+const utf8Encoder = new TextEncoder();
+const supportsBase64Url = buffer_1.Buffer.isEncoding("base64url");
+/**
+ * UTF-8 bytes of `str`, rejecting what `tweetnacl-util`'s `decodeUTF8` rejected (non-strings and
+ * lone surrogates), so signatures are unchanged. `TextEncoder` is native and far faster.
+ * @throws TypeError if `str` is not a string; URIError if it has a lone surrogate
+ */
+function decodeUTF8(str) {
+    if (typeof str !== "string")
+        throw new TypeError("expected string");
+    const wellFormed = str.isWellFormed;
+    if (wellFormed ? !wellFormed.call(str) : /[\uD800-\uDFFF]/.test(str)) {
+        // Slow path only when a surrogate may be unpaired; matches encodeURIComponent's check.
+        encodeURIComponent(str);
+    }
+    return utf8Encoder.encode(str);
+}
+/**
+ * Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats).
+ * Uses `Buffer` (native in Node, the `buffer` package in browsers).
+ */
 function encodeBase64(data) {
-    // return Buffer.from(data).toString("base64url"); // no padding by default
-    const str = utils.encodeBase64(data);
-    return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    // Keep tweetnacl-util's coercion and errors for callers passing other array-like values.
+    if (!(data instanceof Uint8Array)) {
+        return (0, tweetnacl_util_1.encodeBase64)(data).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    }
+    const bytes = buffer_1.Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    if (supportsBase64Url)
+        return bytes.toString("base64url");
+    return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 /**
  * Inverse of {@link encodeBase64}; accepts standard or URL-safe base64 and repads as needed.
- * @throws TypeError if `data` is not a string
+ * Accepts exactly what `tweetnacl-util` did (whole groups of four, then at most two `=`), and
+ * returns a fresh `Uint8Array` that owns its buffer.
+ * @throws TypeError if `data` is not a string or not valid base64
  */
 function decodeBase64(data) {
     if (typeof data !== "string") {
@@ -131,7 +158,11 @@ function decodeBase64(data) {
     while (data.length % 4 !== 0) {
         data += "=";
     }
-    return utils.decodeBase64(data);
+    // A single character class, so it doesn't grow V8's regex stack on large inputs.
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+        throw new TypeError("invalid encoding");
+    }
+    return new Uint8Array(buffer_1.Buffer.from(data, "base64"));
 }
 /** Random token as base64url string (`size` raw bytes, default 32). */
 function newToken(size = 32) {
@@ -178,10 +209,28 @@ function derivePublicBoxKey(publicKey) {
     const converted = ed2curve.convertPublicKey(bytes);
     return converted ? encodeBase64(converted) : null;
 }
+/** Ed25519 detached signature; native when the host installed it (identical bytes), else tweetnacl. */
+function signDetached(message, secretKey) {
+    const native = secretKey.length === 64 ? (0, native_codecs_1.getNativeCodecs)()?.sign(message, secretKey) : undefined;
+    return native ?? nacl.sign.detached(message, secretKey);
+}
+/**
+ * Ed25519 detached verify. A native "valid" is trusted (OpenSSL is at least as strict as tweetnacl:
+ * it also rejects a non-canonical S); anything else is decided by tweetnacl, so every signature
+ * tweetnacl accepted still verifies, and its size errors still throw.
+ */
+function verifyDetached(message, signature, publicKey) {
+    const native = (0, native_codecs_1.getNativeCodecs)();
+    if (native && signature.length === 64 && publicKey.length === 32) {
+        if (native.verify(message, signature, publicKey))
+            return true;
+    }
+    return nacl.sign.detached.verify(message, signature, publicKey);
+}
 /** Signs a UTF-8 message with Ed25519; returns base64url signed message (NaCl `sign` combined format). */
 function signMessageWithSecretKey(msg, secretKey) {
     const _secretKey = decodeBase64(secretKey);
-    const msgDecoded = (0, tweetnacl_util_1.decodeUTF8)(msg);
+    const msgDecoded = decodeUTF8(msg);
     const msgSigned = nacl.sign(msgDecoded, _secretKey);
     return encodeBase64(msgSigned);
 }
@@ -213,8 +262,8 @@ function signObjectWithSecretKey(obj, secretKey) {
         obj = { __isNull: true };
     }
     const objStr = canonicalJSONString(obj);
-    const objDecoded = (0, tweetnacl_util_1.decodeUTF8)(objStr);
-    const signatureByteArray = nacl.sign.detached(objDecoded, _secretKey);
+    const objDecoded = decodeUTF8(objStr);
+    const signatureByteArray = signDetached(objDecoded, _secretKey);
     return {
         contents: obj,
         signature: encodeBase64(signatureByteArray),
@@ -231,7 +280,7 @@ function signObjectWithSecretKey(obj, secretKey) {
 function openSignedObject(signedObj) {
     const _publicKey = decodeBase64(signedObj.publicKey);
     const signature = decodeBase64(signedObj.signature);
-    const verify = (objStr) => nacl.sign.detached.verify((0, tweetnacl_util_1.decodeUTF8)(objStr), signature, _publicKey);
+    const verify = (objStr) => verifyDetached(decodeUTF8(objStr), signature, _publicKey);
     const valid = verify(canonicalJSONString(signedObj.contents)) ||
         verify(legacySignatureJSONString(signedObj.contents));
     if (!valid) {
@@ -317,7 +366,7 @@ function openBoxWithSecretKey(box, mySecretKey) {
 }
 function encryptString(data, secretKey) {
     const _secretKey = decodeBase64(secretKey);
-    const _data = (0, tweetnacl_util_1.decodeUTF8)(data);
+    const _data = decodeUTF8(data);
     const nonce = nacl.randomBytes(24);
     const encryptedData = nacl.secretbox(_data, nonce, _secretKey.slice(0, 32));
     return `${encodeBase64(encryptedData)}~${encodeBase64(nonce)}`;

package/dist/native-codecs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Native implementations a Node host can install for the two most expensive steps of a device
+ * message: gzip and Ed25519. Without them the pure-JS paths (`fflate`, `tweetnacl`) run, so
+ * browsers keep working; with them a large device message costs a fraction of the CPU.
+ *
+ * Every implementation must be interchangeable with the pure-JS one on the wire: a peer without
+ * native codecs must accept what this one sends, and the reverse.
+ */
+export interface INativeCodecs {
+    /** gzip `data` at `level` (1-9). Any valid gzip stream will do; receivers only inflate it. */
+    gzip(data: Uint8Array, level: number): Uint8Array;
+    /** Inflate one gzip stream (from {@link INativeCodecs.gzip} or from `fflate`). */
+    gunzip(data: Uint8Array): Uint8Array;
+    /**
+     * Ed25519 detached signature of `message` with a tweetnacl-format 64-byte secret key (seed then
+     * public key). Ed25519 is deterministic, so this must equal tweetnacl's signature byte for byte;
+     * return `undefined` when that can't be guaranteed (for example, a key whose public half doesn't
+     * match its seed) and the caller signs with tweetnacl.
+     */
+    sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array | undefined;
+    /**
+     * Whether `signature` is a valid Ed25519 signature of `message` by the 32-byte `publicKey`.
+     * Callers fall back to tweetnacl when this returns false, so it may be stricter than tweetnacl
+     * but never more lenient.
+     */
+    verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean;
+}
+/**
+ * Install (or with no argument, remove) native codecs for this process. Node hosts call this once
+ * at startup, before any device message is signed or sent.
+ */
+export declare function installNativeCodecs(codecs?: INativeCodecs): void;
+/** The installed native codecs, or `undefined` when the pure-JS paths should run. */
+export declare function getNativeCodecs(): INativeCodecs | undefined;

package/dist/native-codecs.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installNativeCodecs = installNativeCodecs;
+exports.getNativeCodecs = getNativeCodecs;
+let installed;
+/**
+ * Install (or with no argument, remove) native codecs for this process. Node hosts call this once
+ * at startup, before any device message is signed or sent.
+ */
+function installNativeCodecs(codecs) {
+    installed = codecs;
+}
+/** The installed native codecs, or `undefined` when the pure-JS paths should run. */
+function getNativeCodecs() {
+    return installed;
+}

package/dist/package-loader/isolated-artifact.d.ts

@@ -113,6 +113,21 @@ export interface IIsolatedPackageTable {
      * table. Storage policy, like `localOnly`: changing them needs a higher `versionNumber`.
      */
     indexes?: IIsolatedTableIndex[];
+    /**
+     * The required `id` field holding each row's owner, a user id. The host derives each row's
+     * id from its owner (see `signedKey`), signs rows on save with the signed-in user's key, and
+     * adds the signature, signing time, table/context binding, and `signedIdSeed` columns. In a
+     * group it refuses a row that isn't validly signed by its owner, a Writer, under its derived
+     * id. Not on a local-only table. A table has it, and the same primary key, from its first
+     * version or never.
+     */
+    signedBy?: string;
+    /**
+     * With `signedBy`: the fields that, with the owner, name a row; each row's id is derived from
+     * its owner and these fields. Without it, from its owner and a host-chosen seed. A table has
+     * the same `signedKey` in every version.
+     */
+    signedKey?: string[];
 }
 /** One index of an isolated package table: field names in order, each ascending unless set. */
 export interface IIsolatedTableIndex {
@@ -255,6 +270,8 @@ export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 export declare const ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /** Host-contract member guests use to publish an in-memory provided-contract observable. */
 export declare const ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
+/** Host-contract member guests use to ask for a direct connection to another device. */
+export declare const ISOLATED_CONNECT_HOST_MEMBER = "device.connect";
 /**
  * How deep field lists may nest through object `fields`: a tool's inputs, say, are level 1.
  * Deeper nesting is refused, so a hostile manifest can't exhaust the validator's stack.

package/dist/package-loader/isolated-artifact.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_MAX_FIELD_DEPTH = exports.ISOLATED_OBSERVABLE_HOST_MEMBER = exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_GUEST_API_VERSION = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.ISOLATED_MAX_FIELD_DEPTH = exports.ISOLATED_CONNECT_HOST_MEMBER = exports.ISOLATED_OBSERVABLE_HOST_MEMBER = exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_GUEST_API_VERSION = exports.ISOLATED_PACKAGE_MAGIC = void 0;
 exports.enumValueFits = enumValueFits;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
@@ -45,6 +45,8 @@ exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 exports.ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /** Host-contract member guests use to publish an in-memory provided-contract observable. */
 exports.ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
+/** Host-contract member guests use to ask for a direct connection to another device. */
+exports.ISOLATED_CONNECT_HOST_MEMBER = "device.connect";
 const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
 const OBSERVABLE_FIELD_TYPES = new Set([
     field_type_1.FieldType.id,
@@ -281,7 +283,17 @@ function validatePackageTables(manifest, strict) {
         if (forbiddenIdentity) {
             throw new Error(`${tableLabel} must not declare ${forbiddenIdentity}`);
         }
-        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber", "localOnly", "indexes"], tableLabel);
+        assertOnlyKeys(table, [
+            "name",
+            "description",
+            "primaryKeyName",
+            "fields",
+            "versionNumber",
+            "localOnly",
+            "indexes",
+            "signedBy",
+            "signedKey",
+        ], tableLabel);
         if (typeof table.name !== "string" || table.name.trim() === "") {
             throw new Error(`${tableLabel}.name is required`);
         }
@@ -318,6 +330,7 @@ function validatePackageTables(manifest, strict) {
             table.versionNumber = 1;
         }
         (0, package_table_identity_1.validateTableIndexes)(table.indexes, new Set(table.fields.map((field) => field.name)), `${tableLabel}.indexes`, table.localOnly);
+        (0, package_table_identity_1.validateSignedTable)(table, tableLabel);
     }
 }
 function validateProvidedContract(contract, index, packageTables, strict) {

package/dist/package-loader/isolated-runtime.d.ts

@@ -207,6 +207,10 @@ export interface IIsolatedPackageTableDeclaration extends IIsolatedPackageTableR
     localOnly?: boolean;
     /** Indexes; see `IIsolatedPackageTable.indexes`. */
     indexes?: IIsolatedTableIndex[];
+    /** The field holding each row's owner; see `IIsolatedPackageTable.signedBy`. */
+    signedBy?: string;
+    /** The fields naming a row among its owner's; see `IIsolatedPackageTable.signedKey`. */
+    signedKey?: string[];
 }
 /**
  * Trusted host capability for isolated-package table persistence.
@@ -347,6 +351,12 @@ export interface IIsolatedPackageRuntimeFactoryOptions {
     onWorkerOutput?: (output: IIsolatedWorkerOutput) => void;
     /** This device's id, which package code reads as `ctx.deviceId`. */
     getDeviceId?: () => string | undefined;
+    /**
+     * Ask for a direct connection to `deviceId` within this data context, for package code's
+     * `ctx.connectToDevice`. Resolves whether a verified direct connection exists; never rejects
+     * for an unreachable device. Without it, `ctx.connectToDevice` resolves false.
+     */
+    connectToDevice?: (deviceId: string) => Promise<boolean>;
 }
 /**
  * Host callback that builds an {@link IIsolatedPackageRuntime} for one

package/dist/package-loader/isolated-table-gateway.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMemoryIsolatedPackageTableGateway = createMemoryIsolatedPackageTableGateway;
 exports.createIsolatedPackageTableGateway = createIsolatedPackageTableGateway;
+const lodash_1 = require("lodash");
+const authority_write_checks_1 = require("../data/authority-write-checks");
 const table_container_1 = require("../data/orm/table-container");
 const types_1 = require("../data/orm/types");
 const package_table_identity_1 = require("../data/package-table-identity");
@@ -44,12 +46,16 @@ function validateDeclaration(declaration) {
         throw new Error("Isolated table localOnly must be a boolean");
     }
     (0, package_table_identity_1.validateTableIndexes)(declaration.indexes, fieldNames, "Isolated table indexes", declaration.localOnly);
-    const { localOnly, ...rest } = declaration;
+    // A stored definition's fields already carry the host's signature columns.
+    (0, package_table_identity_1.validateSignedTable)(declaration, "Isolated table", { hostFields: true });
+    const { localOnly, signedBy, signedKey, ...rest } = declaration;
     return {
         ...rest,
         fields: declaration.fields.map((field) => ({ ...field })),
         versionNumber: versionNumber(declaration),
         ...(localOnly ? { localOnly: true } : {}),
+        ...(signedBy === undefined ? {} : { signedBy }),
+        ...(signedKey === undefined ? {} : { signedKey: [...signedKey] }),
     };
 }
 function toMetaData(rawDeclaration) {
@@ -60,11 +66,14 @@ function toMetaData(rawDeclaration) {
         name: declaration.tableName,
         description: declaration.description,
         primaryKeyName: declaration.primaryKeyName,
-        fields: declaration.fields,
+        // A signed table stores the host's signature columns beside the package's fields.
+        fields: declaration.signedBy ? (0, package_table_identity_1.withSignedTableFields)(declaration.fields) : declaration.fields,
         versionNumber: versionNumber(declaration),
         // Only when set: stored definitions hash their metadata, and older ones have no such keys.
         ...(declaration.localOnly ? { localOnly: true } : {}),
         ...(declaration.indexes?.length ? { indexes: declaration.indexes } : {}),
+        ...(declaration.signedBy === undefined ? {} : { signedBy: declaration.signedBy }),
+        ...(declaration.signedKey === undefined ? {} : { signedKey: declaration.signedKey }),
     };
 }
 function normalizedMetaData(metaData) {
@@ -92,6 +101,15 @@ function selectNewerDefinition(existing, incoming) {
     if (existingVersion === incomingVersion && !sameDefinition(existing, incoming)) {
         throw new Error(`Isolated table "${(0, package_table_identity_1.packageScopedTableName)(requiredPackageId(incoming), incoming.name)}" has different schemas at version ${incomingVersion}`);
     }
+    if (existing.signedBy !== incoming.signedBy) {
+        throw new Error(`Isolated table "${(0, package_table_identity_1.packageScopedTableName)(requiredPackageId(incoming), incoming.name)}" is signed from its first version or never; signedBy can't change`);
+    }
+    if (!(0, lodash_1.isEqual)(existing.signedKey, incoming.signedKey)) {
+        throw new Error(`Isolated table "${(0, package_table_identity_1.packageScopedTableName)(requiredPackageId(incoming), incoming.name)}" derives row ids from its signedKey, so signedKey can't change`);
+    }
+    if (existing.signedBy && existing.primaryKeyName !== incoming.primaryKeyName) {
+        throw new Error(`Isolated table "${(0, package_table_identity_1.packageScopedTableName)(requiredPackageId(incoming), incoming.name)}" keeps its derived row ids in its primary key, so the primary key can't change`);
+    }
     const decision = (0, table_container_1.checkVersionedUpdate)(existingVersion, incomingVersion, existing, incoming);
     if (decision === "update") {
         return incoming;
@@ -114,6 +132,8 @@ function declarationFromMetaData(metaData) {
         versionNumber: metaData.versionNumber,
         localOnly: metaData.localOnly,
         ...(metaData.indexes?.length ? { indexes: metaData.indexes } : {}),
+        ...(metaData.signedBy === undefined ? {} : { signedBy: metaData.signedBy }),
+        ...(metaData.signedKey === undefined ? {} : { signedKey: metaData.signedKey }),
     });
 }
 function metaDataFromStoredDefinition(record, incoming) {
@@ -136,6 +156,9 @@ function metaDataFromStoredDefinition(record, incoming) {
 }
 function registerDeclaration(declarations, byTableId, rawDeclaration) {
     const declaration = validateDeclaration(rawDeclaration);
+    // Package declarations leave the host columns out. Only internal reconstruction of a
+    // stored definition (declarationFromMetaData) may already include those columns.
+    (0, package_table_identity_1.validateSignedTable)(declaration, "Isolated table");
     const key = tableKey(declaration);
     const tableId = (0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName);
     const existingKey = byTableId.get(tableId);
@@ -430,9 +453,11 @@ function createIsolatedPackageTableGateway(dataContext) {
                         if (plan.existingRecord) {
                             await definitionsTable.save(plan.existingRecord, { restoreIfDeleted: true });
                         }
-                        else {
+                        else if (!plan.activeMetaData.signedBy) {
                             await definitionsTable.delete(requiredTableId(plan.activeMetaData));
                         }
+                        // A signed declaration is permanent even if activation fails. Retaining an unused
+                        // definition is safe; deleting it would reopen the unsigned-definition bypass.
                     }
                     catch (rollbackError) {
                         failures.push(rollbackError);
@@ -445,6 +470,9 @@ function createIsolatedPackageTableGateway(dataContext) {
             }
             for (const definition of definitions) {
                 dataContext.tableContainer.registerTableDefinition(definition, { overwrite: true });
+                // A signed table's check is keyed by its physical name; register it with the table, so
+                // the host finds it when it builds the table's data source.
+                (0, authority_write_checks_1.tableWriteCheckFor)(definition.metaData);
             }
             declarations.clear();
             byTableId.clear();

package/dist/package-loader/package-loader.js

@@ -127,6 +127,7 @@ class PackageLoader {
                 },
                 onWorkerOutput: (output) => this.logWorkerOutput(output),
                 getDeviceId: () => this.dataContext.userContext?.deviceId(),
+                connectToDevice: (deviceId) => (0, remote_contract_transport_1.connectToRemoteDevice)({ deviceId, dataContextId: this.dataContext.dataContextId }, this.dataContext.userContext),
             });
             this.unsubscribePackageHealth = this.isolatedRuntime.subscribePackageHealth?.((packageId) => {
                 const previous = this.runtimeStates()[packageId];

package/dist/serial-json.d.ts

@@ -26,6 +26,13 @@ export declare function isObject(x: any): x is Record<string, any>;
  * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 export declare function toJSON(obj: any): any;
+/**
+ * {@link toJSON}, except that `Uint8Array` and `Buffer` values stay in the tree as they are (the
+ * same instances), for an encoder that writes bytes natively: `txEncode` with `binaryBytes`
+ * hands the tree to msgpack. {@link fromJSON} passes them through, so the round trip still
+ * restores everything else. Never sign this output; signatures cover {@link toJSON}'s.
+ */
+export declare function toJSONKeepingBytes(obj: any): any;
 /**
  * Reverses {@link toJSON}: restores the sentinel values, shared objects and cycles, and keys
  * escaped with `__DOLLAR_`.

package/dist/serial-json.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isObject = isObject;
 exports.toJSON = toJSON;
+exports.toJSONKeepingBytes = toJSONKeepingBytes;
 exports.fromJSON = fromJSON;
 exports.toJSONString = toJSONString;
 exports.fromJSONString = fromJSONString;
@@ -40,6 +41,19 @@ const ARRAY_TAG_PREFIX = "__this_ref:";
  * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 function toJSON(obj) {
+    return encodeTree(obj, false);
+}
+/**
+ * {@link toJSON}, except that `Uint8Array` and `Buffer` values stay in the tree as they are (the
+ * same instances), for an encoder that writes bytes natively: `txEncode` with `binaryBytes`
+ * hands the tree to msgpack. {@link fromJSON} passes them through, so the round trip still
+ * restores everything else. Never sign this output; signatures cover {@link toJSON}'s.
+ */
+function toJSONKeepingBytes(obj) {
+    return encodeTree(obj, true);
+}
+/** The walk behind {@link toJSON} and {@link toJSONKeepingBytes}. */
+function encodeTree(obj, keepBytes) {
     if (!_.isObject(obj)) {
         return obj;
     }
@@ -76,9 +90,9 @@ function toJSON(obj) {
         if (_.isError(value))
             return `__ERROR ${value.stack}`;
         if (Buffer.isBuffer(value))
-            return `__BUFFER ${value.toString("base64")}`;
+            return keepBytes ? value : `__BUFFER ${value.toString("base64")}`;
         if (value instanceof Uint8Array)
-            return `__UINT8ARRAY ${Buffer.from(value).toString("base64")}`;
+            return keepBytes ? value : `__UINT8ARRAY ${Buffer.from(value).toString("base64")}`;
         const known = seen.get(value);
         if (known) {
             const target = known.copy;

package/dist/system-ids.d.ts

@@ -213,3 +213,5 @@ export declare const packagesContractId = "00mvdhk66tdqrj3hy0bacmj32";
  * Allocated once with newid() for System Host Shell v1.
  */
 export declare const hostShellContractId = "00mveexhw7ezjfghxomlo011g";
+/** Local-only System Group Members v1; allocated once with newid(). */
+export declare const groupMembersContractId = "00mvzfzkuf4djwjrsxq9cnaxt";

package/dist/system-ids.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hostShellContractId = exports.packagesContractId = exports.desktopToolsContractId = exports.hostToolsContractId = exports.toolCatalogContractId = exports.schedulerToolIds = exports.schedulerContractId = exports.contractCatalogToolIds = exports.contractCatalogContractId = exports.httpToolIds = exports.httpContractId = exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.syncCheckContractId = exports.appUpdatesContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.groupMembersContractId = exports.hostShellContractId = exports.packagesContractId = exports.desktopToolsContractId = exports.hostToolsContractId = exports.toolCatalogContractId = exports.schedulerToolIds = exports.schedulerContractId = exports.contractCatalogToolIds = exports.contractCatalogContractId = exports.httpToolIds = exports.httpContractId = exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.syncCheckContractId = exports.appUpdatesContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
 /** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
 /** Default assistant used when no user-selected assistant is available. */
@@ -220,3 +220,5 @@ exports.packagesContractId = "00mvdhk66tdqrj3hy0bacmj32";
  * Allocated once with newid() for System Host Shell v1.
  */
 exports.hostShellContractId = "00mveexhw7ezjfghxomlo011g";
+/** Local-only System Group Members v1; allocated once with newid(). */
+exports.groupMembersContractId = "00mvzfzkuf4djwjrsxq9cnaxt";

package/dist/types/peer-device.d.ts

@@ -73,6 +73,12 @@ export interface IDeviceConnection {
     /** Whether the connection has already closed. */
     closed?: boolean;
 }
+/**
+ * Message of the error a device RPC fails with when its connection closes before the reply
+ * arrives, or when it is sent on a connection that has already closed. Sync treats it as an
+ * expected disconnect, not a failure.
+ */
+export declare const CONNECTION_CLOSED_MESSAGE = "connection has been closed";
 /** Shared tuning constants for device synchronization and routing. */
 export declare const PeerDeviceConsts: Readonly<{
     readonly MAX_CONNECTIONS: 30;

package/dist/types/peer-device.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeerDeviceConsts = void 0;
+exports.PeerDeviceConsts = exports.CONNECTION_CLOSED_MESSAGE = void 0;
+/**
+ * Message of the error a device RPC fails with when its connection closes before the reply
+ * arrives, or when it is sent on a connection that has already closed. Sync treats it as an
+ * expected disconnect, not a failure.
+ */
+exports.CONNECTION_CLOSED_MESSAGE = "connection has been closed";
 /** Shared tuning constants for device synchronization and routing. */
 exports.PeerDeviceConsts = Object.freeze({
     // TODO set this based on device type (desktops and servers should be able to handle 100 connections)

package/dist/utils.js

@@ -293,7 +293,7 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             timeoutCount++;
             finalError = undefined;
             if (connection.closed) {
-                throw new Error(`connection has been closed`);
+                throw new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE);
             }
         }
         catch (error) {
@@ -303,7 +303,7 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
             if (opts.shouldRetry?.(error) === false)
                 throw error;
             if (connection.closed) {
-                throw new Error(`connection has been closed`);
+                throw new Error(peer_device_1.CONNECTION_CLOSED_MESSAGE);
             }
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.28.11",
+  "version": "0.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"