@peers-app/peers-sdk 0.24.0 → 0.25.1

package/dist/context/user-context.d.ts

@@ -76,6 +76,14 @@ export declare class UserContext {
      */
     syncUserAndGroupObjects(userId: string, keys: IPublicPrivateKeys, me?: IUser): Promise<void>;
     private syncMyUserToAllGroups;
+    /**
+     * Copy my personal (signed) `Users` row into one group context so members there can
+     * verify my identity. The write is authoritative, not a `weakInsert`: other members seed
+     * an unsigned placeholder for me when they approve my join, and a weakly-timestamped
+     * signed row would lose last-write-wins to that placeholder on sync, leaving every device
+     * (including mine) with an unverifiable stub. Serialized per group so overlapping calls
+     * cannot interleave.
+     */
     private syncMyUserToGroup;
     /**
      * Subscribe to `dataChanged` events for one table across the personal

package/dist/context/user-context.js

@@ -294,6 +294,14 @@ class UserContext {
     async syncMyUserToAllGroups() {
         await Promise.all(Array.from(this.groupDataContexts.values(), (dataContext) => this.syncMyUserToGroup(dataContext)));
     }
+    /**
+     * Copy my personal (signed) `Users` row into one group context so members there can
+     * verify my identity. The write is authoritative, not a `weakInsert`: other members seed
+     * an unsigned placeholder for me when they approve my join, and a weakly-timestamped
+     * signed row would lose last-write-wins to that placeholder on sync, leaving every device
+     * (including mine) with an unverifiable stub. Serialized per group so overlapping calls
+     * cannot interleave.
+     */
     async syncMyUserToGroup(dataContext) {
         const contextId = dataContext.dataContextId;
         const previousSync = this.groupUserSyncs.get(contextId);
@@ -306,7 +314,7 @@ class UserContext {
             }
             const groupMe = await (0, data_1.Users)(dataContext).get(currentUser.userId);
             if (!(0, lodash_1.isEqual)(groupMe, currentUser)) {
-                await (0, data_1.Users)(dataContext).save(currentUser, { weakInsert: true });
+                await (0, data_1.Users)(dataContext).save(currentUser);
             }
         });
         this.groupUserSyncs.set(contextId, currentSync);

package/dist/data/orm/data-query.d.ts

@@ -2,6 +2,7 @@ export interface ISaveOptions {
     restoreIfDeleted?: boolean;
     saveAsSnapshot?: boolean;
     weakInsert?: boolean;
+    insertOnly?: boolean;
 }
 export interface IDataSource<T extends {
     [key: string]: any;

package/dist/data/orm/sql.data-source.d.ts

@@ -1,7 +1,7 @@
 import type { z } from "zod";
 import type { Emitter } from "../../events";
 import type { FieldType, IField } from "../../types/field-type";
-import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource } from "./data-query";
+import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource, type ISaveOptions } from "./data-query";
 import type { ISqlDb } from "./sql-db";
 import type { IDataChangedEvent } from "./subscribable.data-source";
 import { type ITableMetaData } from "./types";
@@ -27,7 +27,8 @@ export declare class SQLDataSource<T extends {
     findOne(filter?: DataFilter<T>, opts?: {
         enforceUnique?: boolean;
     }): Promise<T | undefined>;
-    save(record: T): Promise<T>;
+    /** Insert or update by primary key. Honors `insertOnly` (leave an existing row untouched). */
+    save(record: T, opts?: ISaveOptions): Promise<T>;
     sqlRecordToJsRecord(record: any): T;
     insert(record: T): Promise<T>;
     update(record: T): Promise<T>;

package/dist/data/orm/sql.data-source.js

@@ -208,7 +208,8 @@ class SQLDataSource {
         }
         return records[0];
     }
-    async save(record) {
+    /** Insert or update by primary key. Honors `insertOnly` (leave an existing row untouched). */
+    async save(record, opts) {
         await this.initTable();
         let newRecord = true;
         const primaryKey = record[this.metaData.primaryKeyName];
@@ -221,9 +222,10 @@ class SQLDataSource {
         if (newRecord) {
             return await this.insert(record);
         }
-        else {
-            return await this.update(record);
+        if (opts?.insertOnly) {
+            return (await this.get(primaryKey));
         }
+        return await this.update(record);
     }
     sqlRecordToJsRecord(record) {
         if (record) {

package/dist/data/orm/subscribable.data-source.d.ts

@@ -1,5 +1,5 @@
 import { Emitter, type Event } from "../../events";
-import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource } from "./data-query";
+import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource, type ISaveOptions } from "./data-query";
 export interface IDataChangedEvent<T> {
     dataObject: T;
     op: "insert" | "update" | "delete";
@@ -18,7 +18,8 @@ export declare class SubscribableDataSource<T extends {
     list(filter?: DataFilter<T>, opts?: IDataQueryParams<T>): Promise<T[]>;
     count(filter?: DataFilter<T>): Promise<number>;
     cursor(filter?: DataFilter<T>, opts?: IDataQueryParams<T>): ICursorIterable<T>;
-    save(record: T): Promise<T>;
+    /** Insert or update by primary key. Honors `insertOnly` (leave an existing row untouched). */
+    save(record: T, opts?: ISaveOptions): Promise<T>;
     insert(record: T): Promise<T>;
     update(record: T): Promise<T>;
     delete(idOrRecord: string | T): Promise<void>;

package/dist/data/orm/subscribable.data-source.js

@@ -33,21 +33,17 @@ class SubscribableDataSource {
     cursor(filter = {}, opts = {}) {
         return (0, data_query_1.dataSourceCursor)(this.dataSource || this, filter, opts);
     }
-    async save(record) {
-        let newRecord = true;
+    /** Insert or update by primary key. Honors `insertOnly` (leave an existing row untouched). */
+    async save(record, opts) {
         const primaryKey = record[this.primaryKeyName];
-        if (primaryKey) {
-            const existingRecord = await this.dataSource.get(primaryKey);
-            if (existingRecord) {
-                newRecord = false;
-            }
-        }
-        if (newRecord) {
+        const existingRecord = primaryKey ? await this.dataSource.get(primaryKey) : undefined;
+        if (!existingRecord) {
             return await this.insert(record);
         }
-        else {
-            return await this.update(record);
+        if (opts?.insertOnly) {
+            return existingRecord;
         }
+        return await this.update(record);
     }
     async insert(record) {
         record = await this.dataSource.insert(record);

package/dist/data/users.d.ts

@@ -27,6 +27,17 @@ export type IUser = z.infer<typeof userSchema>;
 /** User table with owner-signature enforcement outside the personal context. */
 export declare class UsersTable extends Table<IUser> {
     static isPassthrough: boolean;
+    /**
+     * Save a user row. Outside the personal context the write must carry a valid owner
+     * signature (or be an unsigned stub where nothing signed exists yet).
+     *
+     * An unsigned `weakInsert` is a discovery placeholder (connection handshake, invite
+     * identity, join approval). It is written `insertOnly`: seed the row when the table has
+     * nothing for that user, otherwise leave whatever is stored alone. Checking here and then
+     * writing is not enough — the owner's signed row (via sync or `syncMyUserToGroup`) can land
+     * between the two, and a plain update would replace it with an unsigned snapshot carrying a
+     * fresh timestamp that then wins last-write-wins on every device.
+     */
     save(user: IUser, opts?: ISaveOptions): Promise<IUser>;
     signAndSave(user: IUser, opts?: ISaveOptions): Promise<IUser>;
     private static addSignatureToUser;

package/dist/data/users.js

@@ -79,9 +79,23 @@ let UsersTable = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         static isPassthrough = false;
+        /**
+         * Save a user row. Outside the personal context the write must carry a valid owner
+         * signature (or be an unsigned stub where nothing signed exists yet).
+         *
+         * An unsigned `weakInsert` is a discovery placeholder (connection handshake, invite
+         * identity, join approval). It is written `insertOnly`: seed the row when the table has
+         * nothing for that user, otherwise leave whatever is stored alone. Checking here and then
+         * writing is not enough — the owner's signed row (via sync or `syncMyUserToGroup`) can land
+         * between the two, and a plain update would replace it with an unsigned snapshot carrying a
+         * fresh timestamp that then wins last-write-wins on every device.
+         */
         async save(user, opts) {
             opts = opts || {};
             opts = { saveAsSnapshot: true, ...opts };
+            if (opts.weakInsert && !user.signature) {
+                opts = { ...opts, insertOnly: true };
+            }
             if (UsersTable.isPassthrough) {
                 return super.save(user, opts);
             }
@@ -93,8 +107,7 @@ let UsersTable = (() => {
             }
             // Get the old user record if it exists
             const oldUser = await this.get(user.userId);
-            if (opts.weakInsert && oldUser?.signature && !user.signature) {
-                // A weak (placeholder) write must never clobber a signed record; keep what we have.
+            if (opts.insertOnly && oldUser) {
                 return oldUser;
             }
             await (0, user_permissions_1.verifyUserSignature)(user, oldUser);

package/dist/device/device-election.d.ts

@@ -18,11 +18,31 @@ export interface ISortConnectionsArgs {
     unconnectedDeviceIds: Set<string>;
     connections: ISortableConnection[];
 }
+/** A direct connection annotated with the shared groups it serves, as seen by the shedding logic. */
+export interface IShedCandidateConnection extends IDeviceConnection {
+    /** Data-context ids this connection is a member of on both sides. */
+    groups: string[];
+    /**
+     * How many other devices the remote is known to be connected to (from its last network
+     * snapshot). `undefined` when the remote's topology is not known yet. A device whose only
+     * known route into the mesh is this connection has `0` alternatives.
+     */
+    alternativeRoutes?: number;
+}
+/** Inputs for {@link getLeastPreferredConnection}. */
 export interface IGetLeastPreferredConnectionArgs {
-    connections: (IDeviceConnection & {
-        groups: string[];
-    })[];
+    connections: IShedCandidateConnection[];
     preferredDeviceIds: string[];
     preferredByDeviceIds: string[];
 }
+/**
+ * Choose the connection to drop when this device is at its connection cap.
+ *
+ * Preference order: connections that are neither preferred by us nor prefer us, then
+ * connections we do not depend on, then connections that do not depend on us, then anything.
+ * Within the chosen tier, a remote whose only known route into the mesh is this connection is
+ * never shed while some other candidate is known to have alternative routes; shedding it would
+ * isolate it and it would only redial us and force another shed. Remaining ties go to the
+ * connection serving the fewest groups, then to the worst latency x error rate.
+ */
 export declare function getLeastPreferredConnection({ connections, preferredDeviceIds, preferredByDeviceIds, }: IGetLeastPreferredConnectionArgs): IDeviceConnection | undefined;

package/dist/device/device-election.js

@@ -104,6 +104,16 @@ function sortConnections({ myDeviceId, connections, unconnectedDeviceIds }) {
     });
     return connections;
 }
+/**
+ * Choose the connection to drop when this device is at its connection cap.
+ *
+ * Preference order: connections that are neither preferred by us nor prefer us, then
+ * connections we do not depend on, then connections that do not depend on us, then anything.
+ * Within the chosen tier, a remote whose only known route into the mesh is this connection is
+ * never shed while some other candidate is known to have alternative routes; shedding it would
+ * isolate it and it would only redial us and force another shed. Remaining ties go to the
+ * connection serving the fewest groups, then to the worst latency x error rate.
+ */
 function getLeastPreferredConnection({ connections, preferredDeviceIds, preferredByDeviceIds, }) {
     // first consider connections that are not critical to me and I'm not critical to them
     let candidates = connections.filter((c) => !(preferredByDeviceIds.includes(c.deviceId) || preferredDeviceIds.includes(c.deviceId)));
@@ -119,6 +129,11 @@ function getLeastPreferredConnection({ connections, preferredDeviceIds, preferre
         // if none, then just consider all connections
         candidates = [...connections];
     }
+    // never strand a device: if anyone here is known to have another way into the mesh, leave
+    // the candidates whose only known route is through us alone
+    if (candidates.some((c) => (c.alternativeRoutes ?? 0) > 0)) {
+        candidates = candidates.filter((c) => c.alternativeRoutes !== 0);
+    }
     // start with random order to avoid biasing the selection to newer connections
     candidates = (0, lodash_1.shuffle)(candidates);
     // sort by latency * error rate (smaller is better)

package/dist/device/device-election.test.js

@@ -308,6 +308,79 @@ describe("device-election", () => {
             expect(result).toBeDefined();
             expect([device1, device2, device3]).toContain(result?.deviceId);
         });
+        describe("alternativeRoutes", () => {
+            it("never sheds a device whose only known route is through us when others have alternatives", () => {
+                const stranded = (0, utils_1.newid)();
+                const others = [(0, utils_1.newid)(), (0, utils_1.newid)(), (0, utils_1.newid)()];
+                const connections = [
+                    // worst latency and most groups would normally make this the victim
+                    { ...createConnection(stranded, 900, 0.5), groups: ["g"], alternativeRoutes: 0 },
+                    ...others.map((id) => ({
+                        ...createConnection(id, 5, 0.001),
+                        groups: ["g", "h"],
+                        alternativeRoutes: 3,
+                    })),
+                ];
+                for (let i = 0; i < 20; i++) {
+                    const result = (0, device_election_1.getLeastPreferredConnection)({
+                        connections: (0, lodash_1.shuffle)(connections),
+                        preferredDeviceIds: [],
+                        preferredByDeviceIds: [],
+                    });
+                    expect(result).toBeDefined();
+                    expect(result?.deviceId).not.toBe(stranded);
+                    expect(others).toContain(result?.deviceId);
+                }
+            });
+            it("falls back to the usual ordering when no candidate is known to have alternatives", () => {
+                const device1 = (0, utils_1.newid)();
+                const device2 = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(device1, 10, 0.001), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(device2, 500, 0.5), groups: ["g"], alternativeRoutes: 0 },
+                ];
+                const result = (0, device_election_1.getLeastPreferredConnection)({
+                    connections,
+                    preferredDeviceIds: [],
+                    preferredByDeviceIds: [],
+                });
+                expect(result?.deviceId).toBe(device2);
+            });
+            it("treats unknown topology as neither protected nor preferred", () => {
+                const unknown = (0, utils_1.newid)();
+                const stranded = (0, utils_1.newid)();
+                const connected = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(unknown, 500, 0.5), groups: ["g"] },
+                    { ...createConnection(stranded, 10, 0.001), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(connected, 10, 0.001), groups: ["g"], alternativeRoutes: 2 },
+                ];
+                for (let i = 0; i < 20; i++) {
+                    const result = (0, device_election_1.getLeastPreferredConnection)({
+                        connections: (0, lodash_1.shuffle)(connections),
+                        preferredDeviceIds: [],
+                        preferredByDeviceIds: [],
+                    });
+                    // the stranded device is excluded; unknown stays in the pool and loses on latency
+                    expect(result?.deviceId).toBe(unknown);
+                }
+            });
+            it("still respects preference tiers before route protection", () => {
+                const stranded = (0, utils_1.newid)();
+                const preferred = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(stranded), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(preferred), groups: ["g"], alternativeRoutes: 4 },
+                ];
+                // the only non-preferred candidate is the stranded one, so the tier leaves just it
+                const result = (0, device_election_1.getLeastPreferredConnection)({
+                    connections,
+                    preferredDeviceIds: [preferred],
+                    preferredByDeviceIds: [],
+                });
+                expect(result?.deviceId).toBe(stranded);
+            });
+        });
     });
     describe("Network simulations", () => {
         it.skip("should work as connections grow", () => {

package/dist/keys.d.ts

@@ -10,6 +10,17 @@ export declare function stableStringify(obj: any): string;
 export declare function hashObject(obj: {
     [key: string]: any;
 }): string;
+/**
+ * Canonical JSON used for object signatures.
+ *
+ * Signed objects round-trip through SQLite (rows come back in schema column order and `NULL`
+ * becomes `undefined`), msgpack, and object spreads, all of which reorder keys or blur
+ * absent / `null` / `undefined`. The signed bytes must not depend on any of that, so this form:
+ * drops `null` / `undefined` valued keys, encodes extended types via {@link toJSON}, and sorts keys
+ * at every level. Sign and verify with this and only this; see {@link openSignedObject} for the
+ * legacy insertion-order fallback that keeps pre-existing signatures valid.
+ */
+export declare function canonicalJSONString(obj: any): string;
 /** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
 export declare function encodeBase64(data: Uint8Array): string;
 /**
@@ -52,12 +63,17 @@ export declare function signMessageWithSecretKey(msg: string, secretKey: string)
  */
 export declare function openMessageWithPublicKey(msg: string, publicKey: string): string;
 /**
- * Detached sign over stable JSON: `undefined` / `null` are encoded with sentinel fields for round-trip.
+ * Detached sign over {@link canonicalJSONString} (sorted keys, `null` / `undefined` keys dropped),
+ * so the signature survives key reordering and storage round-trips. A top-level `undefined` /
+ * `null` is encoded with a sentinel object so it can be signed and restored.
  * @returns Payload with original `contents`, `signature`, and signer's Ed25519 public key (32-byte slice, base64url)
  */
 export declare function signObjectWithSecretKey<T>(obj: T, secretKey: string): ISignedObject<T>;
 /**
  * Verifies a detached signature and returns `contents` after undoing the undefined/null sentinels.
+ * Verifies against {@link canonicalJSONString} first and falls back to the legacy insertion-order
+ * serialization so signatures written by older builds (already in databases, invite tokens, and
+ * `peers-services`) stay valid. New signatures are always canonical.
  * @throws If the signature is invalid
  */
 export declare function openSignedObject<T>(signedObj: ISignedObject<T>): T;

package/dist/keys.js

@@ -5,6 +5,7 @@ exports.hashValue = hashValue;
 exports.hashBytes = hashBytes;
 exports.stableStringify = stableStringify;
 exports.hashObject = hashObject;
+exports.canonicalJSONString = canonicalJSONString;
 exports.encodeBase64 = encodeBase64;
 exports.decodeBase64 = decodeBase64;
 exports.newToken = newToken;
@@ -60,6 +61,53 @@ function hashObject(obj) {
     const hash = hashValue(stableJson);
     return hash;
 }
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Recursively drops `null` / `undefined` valued keys from plain objects and rebuilds them with
+ * sorted keys. Arrays keep every element (position is meaning); non-plain objects (Date, Buffer,
+ * Uint8Array, RegExp, Error, …) pass through untouched for {@link toJSON} to encode.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const v = value[key];
+        if (v === undefined || v === null)
+            continue;
+        out[key] = canonicalize(v);
+    }
+    return out;
+}
+/**
+ * Canonical JSON used for object signatures.
+ *
+ * Signed objects round-trip through SQLite (rows come back in schema column order and `NULL`
+ * becomes `undefined`), msgpack, and object spreads, all of which reorder keys or blur
+ * absent / `null` / `undefined`. The signed bytes must not depend on any of that, so this form:
+ * drops `null` / `undefined` valued keys, encodes extended types via {@link toJSON}, and sorts keys
+ * at every level. Sign and verify with this and only this; see {@link openSignedObject} for the
+ * legacy insertion-order fallback that keeps pre-existing signatures valid.
+ */
+function canonicalJSONString(obj) {
+    return stableStringify((0, serial_json_1.toJSON)(canonicalize(obj)));
+}
+/**
+ * Pre-canonical serialization: insertion-order keys, `undefined` kept as a sentinel string.
+ * Only used to verify signatures written before {@link canonicalJSONString} existed.
+ */
+function legacySignatureJSONString(obj) {
+    return (0, serial_json_1.toJSONString)(obj);
+}
 /** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
 function encodeBase64(data) {
     // return Buffer.from(data).toString("base64url"); // no padding by default
@@ -127,7 +175,9 @@ function openMessageWithPublicKey(msg, publicKey) {
     return (0, tweetnacl_util_1.encodeUTF8)(msgOpened);
 }
 /**
- * Detached sign over stable JSON: `undefined` / `null` are encoded with sentinel fields for round-trip.
+ * Detached sign over {@link canonicalJSONString} (sorted keys, `null` / `undefined` keys dropped),
+ * so the signature survives key reordering and storage round-trips. A top-level `undefined` /
+ * `null` is encoded with a sentinel object so it can be signed and restored.
  * @returns Payload with original `contents`, `signature`, and signer's Ed25519 public key (32-byte slice, base64url)
  */
 function signObjectWithSecretKey(obj, secretKey) {
@@ -138,7 +188,7 @@ function signObjectWithSecretKey(obj, secretKey) {
     if (obj === null) {
         obj = { __isNull: true };
     }
-    const objStr = (0, serial_json_1.toJSONString)(obj);
+    const objStr = canonicalJSONString(obj);
     const objDecoded = (0, tweetnacl_util_1.decodeUTF8)(objStr);
     const signatureByteArray = nacl.sign.detached(objDecoded, _secretKey);
     return {
@@ -149,14 +199,17 @@ function signObjectWithSecretKey(obj, secretKey) {
 }
 /**
  * Verifies a detached signature and returns `contents` after undoing the undefined/null sentinels.
+ * Verifies against {@link canonicalJSONString} first and falls back to the legacy insertion-order
+ * serialization so signatures written by older builds (already in databases, invite tokens, and
+ * `peers-services`) stay valid. New signatures are always canonical.
  * @throws If the signature is invalid
  */
 function openSignedObject(signedObj) {
     const _publicKey = decodeBase64(signedObj.publicKey);
-    const objStr = (0, serial_json_1.toJSONString)(signedObj.contents);
-    const objDecoded = (0, tweetnacl_util_1.decodeUTF8)(objStr);
     const signature = decodeBase64(signedObj.signature);
-    const valid = nacl.sign.detached.verify(objDecoded, signature, _publicKey);
+    const verify = (objStr) => nacl.sign.detached.verify((0, tweetnacl_util_1.decodeUTF8)(objStr), signature, _publicKey);
+    const valid = verify(canonicalJSONString(signedObj.contents)) ||
+        verify(legacySignatureJSONString(signedObj.contents));
     if (!valid) {
         throw new Error("Signature verification failed");
     }

package/dist/keys.test.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const nacl = require("tweetnacl");
+const tweetnacl_util_1 = require("tweetnacl-util");
+const zod_1 = require("zod");
+const sql_data_source_1 = require("./data/orm/sql.data-source");
+const types_1 = require("./data/orm/types");
 const keys_1 = require("./keys");
+const serial_json_1 = require("./serial-json");
+const zod_types_1 = require("./types/zod-types");
+const utils_1 = require("./utils");
 describe("keys", () => {
     it("should allow creating a new key pair", () => {
         const keys = (0, keys_1.newKeys)();
@@ -220,4 +229,108 @@ describe("keys", () => {
             expect((0, keys_1.getPublicKeyFromObjectSignature)(signedObj)).toBe(keys.publicKey);
         });
     });
+    describe("canonical signatures", () => {
+        it("canonicalJSONString sorts keys at every level and drops null/undefined keys", () => {
+            const a = { z: 1, a: { y: [3, { q: 1, p: 2 }], x: undefined, w: null }, m: undefined };
+            const b = { a: { y: [3, { p: 2, q: 1 }] }, z: 1 };
+            expect((0, keys_1.canonicalJSONString)(a)).toBe((0, keys_1.canonicalJSONString)(b));
+            expect((0, keys_1.canonicalJSONString)(a)).toBe('{"a":{"y":[3,{"p":2,"q":1}]},"z":1}');
+        });
+        it("canonicalJSONString keeps array elements and encodes extended types", () => {
+            const date = new Date("2026-01-02T03:04:05.000Z");
+            expect((0, keys_1.canonicalJSONString)([1, null, undefined])).toBe('[1,null,"__UNDEFINED"]');
+            expect((0, keys_1.canonicalJSONString)({ when: date })).toBe(`{"when":"__DATE ${date.toISOString()}"}`);
+            expect((0, keys_1.canonicalJSONString)({ b: Buffer.from("hi") })).toBe('{"b":"__BUFFER aGk="}');
+        });
+        it("verifies after the keys are reordered", () => {
+            const keys = (0, keys_1.newKeys)();
+            const signed = (0, keys_1.addSignatureToObject)({ userId: "u1", name: "Alice", publicKey: keys.publicKey }, keys.secretKey);
+            // Same fields, different insertion order (as a row read back from SQLite would be).
+            const reordered = {
+                publicKey: signed.publicKey,
+                signature: signed.signature,
+                name: signed.name,
+                userId: signed.userId,
+            };
+            expect(() => (0, keys_1.verifyObjectSignature)(reordered)).not.toThrow();
+        });
+        it("treats an absent, undefined, and null optional field identically", () => {
+            const keys = (0, keys_1.newKeys)();
+            const signed = (0, keys_1.addSignatureToObject)({ userId: "u1", name: "Alice" }, keys.secretKey);
+            expect((0, keys_1.isObjectSignatureValid)({ ...signed, avatar: undefined })).toBe(true);
+            expect((0, keys_1.isObjectSignatureValid)({ ...signed, avatar: null })).toBe(true);
+            // A real value change still fails.
+            expect((0, keys_1.isObjectSignatureValid)({ ...signed, avatar: "x" })).toBe(false);
+        });
+        it("still fails when a value changes, regardless of order", () => {
+            const keys = (0, keys_1.newKeys)();
+            const signed = (0, keys_1.addSignatureToObject)({ a: 1, b: 2 }, keys.secretKey);
+            expect((0, keys_1.isObjectSignatureValid)({ b: 3, a: 1, signature: signed.signature })).toBe(false);
+        });
+        it("accepts legacy insertion-order signatures written before canonicalization", () => {
+            const keys = (0, keys_1.newKeys)();
+            // Key order deliberately not sorted, so canonical and legacy bytes differ.
+            const contents = { userId: "u1", name: "Alice", publicKey: keys.publicKey, maybe: undefined };
+            const legacyBytes = (0, tweetnacl_util_1.decodeUTF8)((0, serial_json_1.toJSONString)(contents));
+            expect((0, serial_json_1.toJSONString)(contents)).not.toBe((0, keys_1.canonicalJSONString)(contents));
+            const legacySig = nacl.sign.detached(legacyBytes, (0, keys_1.decodeBase64)(keys.secretKey));
+            const signature = Buffer.from(legacySig).toString("base64url");
+            expect(() => (0, keys_1.openSignedObject)({ contents, signature, publicKey: keys.publicKey })).not.toThrow();
+            expect(() => (0, keys_1.verifyObjectSignature)({ ...contents, signature: `${keys.publicKey}:${signature}` })).not.toThrow();
+            // Tampering is still caught on the legacy path.
+            expect(() => (0, keys_1.openSignedObject)({
+                contents: { ...contents, name: "Mallory" },
+                signature,
+                publicKey: keys.publicKey,
+            })).toThrow(/signature/i);
+        });
+        it("survives a round trip through a SQLite table", async () => {
+            const db = new SQLiteDB(":memory:");
+            const harness = {
+                get: async (sql, params = []) => db.prepare(sql).get(params),
+                all: async (sql, params = []) => db.prepare(sql).all(params),
+                exec: async (sql, params = []) => ({
+                    changes: db.prepare(sql).run(params).changes,
+                }),
+                close: async () => {
+                    db.close();
+                },
+            };
+            const schema = zod_1.z.object({
+                userId: zod_types_1.zodPeerId,
+                name: zod_1.z.string(),
+                publicKey: zod_1.z.string(),
+                publicBoxKey: zod_1.z.string(),
+                avatar: zod_1.z.string().optional(),
+                signature: zod_1.z.string(),
+            });
+            const metaData = {
+                name: "test_signed_users",
+                description: "signed users",
+                primaryKeyName: "userId",
+                fields: (0, types_1.schemaToFields)(schema),
+            };
+            const table = new sql_data_source_1.SQLDataSource(harness, metaData);
+            try {
+                const keys = (0, keys_1.newKeys)();
+                // Signed with keys in an order that differs from the schema's column order and with an
+                // optional field omitted; SQLite will hand back column order and `avatar: undefined`.
+                const signed = (0, keys_1.addSignatureToObject)({
+                    publicBoxKey: keys.publicBoxKey,
+                    name: "Alice",
+                    userId: (0, utils_1.newid)(),
+                    publicKey: keys.publicKey,
+                }, keys.secretKey);
+                await table.save(signed);
+                const stored = await table.get(signed.userId);
+                if (!stored)
+                    throw new Error("row was not stored");
+                expect(Object.keys(stored)).not.toEqual(Object.keys(signed));
+                expect(() => (0, keys_1.verifyObjectSignature)(stored)).not.toThrow();
+            }
+            finally {
+                await harness.close();
+            }
+        });
+    });
 });

package/dist/serial-json.d.ts

@@ -10,7 +10,10 @@ export declare function toJSON(obj: any): any;
  * @param _externalReferences Reserved for future use (function revival, etc.)
  */
 export declare function fromJSON(obj: any, _externalReferences?: any): any;
-/** `JSON.stringify` of {@link toJSON} (stable, extended types). */
+/**
+ * `JSON.stringify` of {@link toJSON}: extended types are encoded deterministically, but keys keep
+ * insertion order. Not canonical; for signatures use `canonicalJSONString` in `keys.ts`.
+ */
 export declare function toJSONString(obj: any): string;
 /** `JSON.parse` then {@link fromJSON}. */
 export declare function fromJSONString(str: string): any;

package/dist/serial-json.js

@@ -194,7 +194,10 @@ function fromJSON(obj, _externalReferences) {
     obj = recurse(obj);
     return obj;
 }
-/** `JSON.stringify` of {@link toJSON} (stable, extended types). */
+/**
+ * `JSON.stringify` of {@link toJSON}: extended types are encoded deterministically, but keys keep
+ * insertion order. Not canonical; for signatures use `canonicalJSONString` in `keys.ts`.
+ */
 function toJSONString(obj) {
     return JSON.stringify(toJSON(obj));
 }

package/package.json

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