@peers-app/peers-sdk 0.30.4 → 0.30.5

package/dist/contracts/system/mesh-metrics-types.d.ts

@@ -5,7 +5,9 @@ export type MeshDialReason = "own-device" | "group-network-info" | "broadcast-an
 /** Bounded path categories used for lifetime counters; attempts also retain the address. */
 export type MeshPath = "websocket" | "webrtc" | "cloud" | "discovery";
 /** Failure categories, independent of free-form transport error messages. */
-export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known" | "trust-refused" | "identity-mismatch" | "cancelled" | "capacity";
+export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known"
+/** This device can't encrypt to the target yet: no owner-signed row or profile for it here. */
+ | "recipient-unknown" | "trust-refused" | "identity-mismatch" | "cancelled" | "capacity";
 /** Observed stage; timestamps are offsets in milliseconds from the attempt's queued time. */
 export type MeshStage = "queued" | "started" | "authenticated" | "admitted" | "ready" | "firstSync";
 /** Local dial metadata and cancellation; never serialized into device messages. */
@@ -19,6 +21,12 @@ export interface IMeshDial {
     targetDeviceId?: string;
     /** One-based retry number; absent for the initial dial. */
     retry?: number;
+    /**
+     * Metrics only: the logical dial this transport races alongside (a published address tried
+     * next to the device-id path). It's recorded as an attempt of its own but counted as part of
+     * that dial, and its failures don't end the dial.
+     */
+    siblingOf?: string;
 }
 /** One dial or inbound connection. Missing stages have not been observed. */
 export interface IMeshAttempt {
@@ -135,6 +143,17 @@ export interface IMeshStats {
             probes: number;
             connected: number;
         };
+        /**
+         * Dials helped by what devices publish: dials that tried a device's published addresses,
+         * those an address won, and the relayed protocol queries made and skipped because the
+         * device's protocols were known. Absent from devices older than these counters.
+         */
+        dialHints?: {
+            addressDials: number;
+            addressWins: number;
+            protocolQueries: number;
+            protocolQueriesSkipped: number;
+        };
         /** Lifetime episodes excluded from latency percentiles, by reason. */
         unmeasuredEpisodes?: {
             pageHidden: number;

package/dist/data/authority-write-checks.js

@@ -312,6 +312,14 @@ async function checkDevice(existing, candidate, context) {
         !signed(candidate)) {
         throw (0, write_checks_1.writeNotAuthorized)("Devices", "the ownership claim doesn't verify");
     }
+    // Only the owner publishes how to dial its device. Sync keeps the stored block when a writer
+    // drops it or holds an older one (retainDeviceReachability), so this refuses only a forgery.
+    if (candidate?.reachability &&
+        (candidate.userId !== existing?.userId ||
+            !(0, devices_1.sameDeviceReachability)(candidate.reachability, existing?.reachability)) &&
+        !(0, devices_1.isDeviceReachabilitySigned)(candidate, users.get(ownerId ?? candidate.userId)?.publicKey)) {
+        throw (0, write_checks_1.writeNotAuthorized)("Devices", "reachability isn't signed by the device's owner");
+    }
 }
 (0, write_checks_1.registerTableWriteCheck)("Users", checkUser);
 (0, write_checks_1.registerTableWriteCheck)("Devices", checkDevice);

package/dist/data/devices.d.ts

@@ -5,6 +5,34 @@ import { TrustLevel } from "../device/socket.type";
 export declare const DISPLAY_NAME_MAX_LENGTH = 128;
 /** Shared schema for bounded user and device display names. */
 export declare const displayNameSchema: z.ZodString;
+/** Most origins one device publishes: every LAN interface plus a configured public origin. */
+export declare const DEVICE_REACHABILITY_MAX_ADDRESSES = 16;
+/** Most protocol names one device publishes. */
+export declare const DEVICE_REACHABILITY_MAX_PROTOCOLS = 8;
+/**
+ * How a device can be dialed, published by its owner on its own Devices row: the origins its peer
+ * listener accepts connections on, and the protocols it supports. Only the owner writes it, signed
+ * with the owner's key, and the newest signed `updatedAt` wins. Addresses are a fast path; every
+ * dial still checks that the expected device answers.
+ */
+export declare const deviceReachabilitySchema: z.ZodObject<{
+    addresses: z.ZodArray<z.ZodString, "many">;
+    protocols: z.ZodArray<z.ZodString, "many">;
+    updatedAt: z.ZodNumber;
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    updatedAt: number;
+    addresses: string[];
+    protocols: string[];
+}, {
+    signature: string;
+    updatedAt: number;
+    addresses: string[];
+    protocols: string[];
+}>;
+/** How a device can be dialed, as its owner published it (see {@link deviceReachabilitySchema}). */
+export type IDeviceReachability = z.infer<typeof deviceReachabilitySchema>;
 /** Schema for a persisted, context-scoped device record. */
 export declare const deviceSchema: z.ZodObject<{
     deviceId: z.ZodEffects<z.ZodString, string, string>;
@@ -16,6 +44,22 @@ export declare const deviceSchema: z.ZodObject<{
     serverUrl: z.ZodOptional<z.ZodString>;
     trustLevel: z.ZodNativeEnum<typeof TrustLevel>;
     ownerSignature: z.ZodOptional<z.ZodString>;
+    reachability: z.ZodOptional<z.ZodObject<{
+        addresses: z.ZodArray<z.ZodString, "many">;
+        protocols: z.ZodArray<z.ZodString, "many">;
+        updatedAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    }, {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    }>>;
 }, "strip", z.ZodTypeAny, {
     userId: string;
     deviceId: string;
@@ -26,6 +70,12 @@ export declare const deviceSchema: z.ZodObject<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }, {
     userId: string;
     deviceId: string;
@@ -36,6 +86,12 @@ export declare const deviceSchema: z.ZodObject<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }>;
 /** A context-scoped device record containing local state and owner-reported metadata. */
 export type IDevice = z.infer<typeof deviceSchema>;
@@ -58,6 +114,41 @@ export declare function deviceOwnerStatement(device: Pick<IDevice, "deviceId" |
  * @param ownerPublicKey - The signing key of `device.userId`, as this device knows it.
  */
 export declare function isDeviceOwnerSigned(device: Pick<IDevice, "deviceId" | "userId" | "ownerSignature">, ownerPublicKey: string | undefined): boolean;
+/**
+ * What a device's owner signs to publish how to dial it: the contents of
+ * `reachability.signature`. Arrays are signed in the order given, so publishers sort them.
+ *
+ * @param deviceId - The device the reachability is for.
+ * @param reachability - Its addresses, protocols and publishing time.
+ */
+export declare function deviceReachabilityStatement(deviceId: string, reachability: Pick<IDeviceReachability, "addresses" | "protocols" | "updatedAt">): {
+    purpose: string;
+    deviceId: string;
+    addresses: string[];
+    protocols: string[];
+    updatedAt: number;
+};
+/**
+ * Whether `device.reachability` carries `ownerPublicKey`'s signature over
+ * {@link deviceReachabilityStatement}: the device's owner published it, not whoever wrote the row.
+ *
+ * @param device - A Devices row.
+ * @param ownerPublicKey - The signing key of the device's owner, as this device knows it.
+ */
+export declare function isDeviceReachabilitySigned(device: Pick<IDevice, "deviceId" | "reachability">, ownerPublicKey: string | undefined): boolean;
+/** Whether two reachability blocks are the same publication. */
+export declare function sameDeviceReachability(a: IDeviceReachability | undefined, b: IDeviceReachability | undefined): boolean;
+/**
+ * The row to store when `candidate` replaces `existing`: the candidate, keeping the stored
+ * `reachability` when the candidate has none or an older one (a tie keeps the stored one too).
+ * Writers that don't know the field (older builds) or hold a stale copy never roll it back;
+ * only a newer publication replaces it. Signatures are checked separately, by the group write
+ * check and by whoever dials.
+ *
+ * @param existing - The row as stored now, if any.
+ * @param candidate - The row about to be stored.
+ */
+export declare function retainDeviceReachability<T extends Partial<IDevice>>(existing: Partial<IDevice> | undefined, candidate: T): T;
 /** Schema for the signed identity and bounded presentation hints exchanged by devices. */
 export declare const deviceInfoSchema: z.ZodObject<{
     userId: z.ZodEffects<z.ZodString, string, string>;
@@ -237,6 +328,12 @@ export declare function Devices(dataContext?: DataContext): import("..").Table<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }>;
 /** Persistent identifier for the current physical/runtime device. */
 export declare const thisDeviceId: import("./persistent-vars").PersistentVar<string | undefined>;

package/dist/data/devices.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.thisDeviceId = exports.deviceHandshakeSchema = exports.handshakeFrameCryptoSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
+exports.thisDeviceId = exports.deviceHandshakeSchema = exports.handshakeFrameCryptoSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.deviceReachabilitySchema = exports.DEVICE_REACHABILITY_MAX_PROTOCOLS = exports.DEVICE_REACHABILITY_MAX_ADDRESSES = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
 exports.deviceOwnerStatement = deviceOwnerStatement;
 exports.isDeviceOwnerSigned = isDeviceOwnerSigned;
+exports.deviceReachabilityStatement = deviceReachabilityStatement;
+exports.isDeviceReachabilitySigned = isDeviceReachabilitySigned;
+exports.sameDeviceReachability = sameDeviceReachability;
+exports.retainDeviceReachability = retainDeviceReachability;
 exports.Devices = Devices;
 const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
@@ -17,6 +21,30 @@ const persistent_vars_1 = require("./persistent-vars");
 exports.DISPLAY_NAME_MAX_LENGTH = 128;
 /** Shared schema for bounded user and device display names. */
 exports.displayNameSchema = zod_1.z.string().max(exports.DISPLAY_NAME_MAX_LENGTH);
+/** Most origins one device publishes: every LAN interface plus a configured public origin. */
+exports.DEVICE_REACHABILITY_MAX_ADDRESSES = 16;
+/** Most protocol names one device publishes. */
+exports.DEVICE_REACHABILITY_MAX_PROTOCOLS = 8;
+/**
+ * How a device can be dialed, published by its owner on its own Devices row: the origins its peer
+ * listener accepts connections on, and the protocols it supports. Only the owner writes it, signed
+ * with the owner's key, and the newest signed `updatedAt` wins. Addresses are a fast path; every
+ * dial still checks that the expected device answers.
+ */
+exports.deviceReachabilitySchema = zod_1.z.object({
+    addresses: zod_1.z
+        .array(zod_1.z.string().max(256))
+        .max(exports.DEVICE_REACHABILITY_MAX_ADDRESSES)
+        .describe("Origins the device's peer listener accepts connections on, in a stable order"),
+    protocols: zod_1.z
+        .array(zod_1.z.string().max(32))
+        .max(exports.DEVICE_REACHABILITY_MAX_PROTOCOLS)
+        .describe("Protocols the device can be dialed with, such as ws and wrtc"),
+    updatedAt: zod_1.z.number().describe("When the owner published this, in ms; the newest one wins"),
+    signature: zod_1.z
+        .string()
+        .describe("The owner's signature over deviceReachabilityStatement, without the key prefix"),
+});
 /** Schema for a persisted, context-scoped device record. */
 exports.deviceSchema = zod_1.z.object({
     deviceId: zod_types_1.zodPeerId,
@@ -31,6 +59,9 @@ exports.deviceSchema = zod_1.z.object({
         .string()
         .optional()
         .describe("The owner's signature claiming this device for userId (see deviceOwnerStatement). In a group, only a row with a valid one says who a device belongs to, and it stays theirs"),
+    reachability: exports.deviceReachabilitySchema
+        .optional()
+        .describe("How to dial this device, published and signed by its owner. Sync keeps the newest signed copy, so a writer without it never clears it"),
 });
 /**
  * What a device's owner signs to claim it: the contents of `ownerSignature`. Each device signs
@@ -56,6 +87,74 @@ function isDeviceOwnerSigned(device, ownerPublicKey) {
         signature: `${ownerPublicKey}:${device.ownerSignature}`,
     }) === ownerPublicKey);
 }
+/**
+ * What a device's owner signs to publish how to dial it: the contents of
+ * `reachability.signature`. Arrays are signed in the order given, so publishers sort them.
+ *
+ * @param deviceId - The device the reachability is for.
+ * @param reachability - Its addresses, protocols and publishing time.
+ */
+function deviceReachabilityStatement(deviceId, reachability) {
+    return {
+        purpose: "peers-device-reachability",
+        deviceId,
+        addresses: reachability.addresses,
+        protocols: reachability.protocols,
+        updatedAt: reachability.updatedAt,
+    };
+}
+/**
+ * Whether `device.reachability` carries `ownerPublicKey`'s signature over
+ * {@link deviceReachabilityStatement}: the device's owner published it, not whoever wrote the row.
+ *
+ * @param device - A Devices row.
+ * @param ownerPublicKey - The signing key of the device's owner, as this device knows it.
+ */
+function isDeviceReachabilitySigned(device, ownerPublicKey) {
+    const reachability = device.reachability;
+    if (!reachability?.signature || !ownerPublicKey)
+        return false;
+    return ((0, keys_1.signedByKey)({
+        ...deviceReachabilityStatement(device.deviceId, reachability),
+        signature: `${ownerPublicKey}:${reachability.signature}`,
+    }) === ownerPublicKey);
+}
+/** Whether two reachability blocks are the same publication. */
+function sameDeviceReachability(a, b) {
+    if (!a || !b)
+        return a === b;
+    return (a.updatedAt === b.updatedAt &&
+        a.signature === b.signature &&
+        a.addresses.length === b.addresses.length &&
+        a.addresses.every((address, i) => address === b.addresses[i]) &&
+        a.protocols.length === b.protocols.length &&
+        a.protocols.every((protocol, i) => protocol === b.protocols[i]));
+}
+/**
+ * The row to store when `candidate` replaces `existing`: the candidate, keeping the stored
+ * `reachability` when the candidate has none or an older one (a tie keeps the stored one too).
+ * Writers that don't know the field (older builds) or hold a stale copy never roll it back;
+ * only a newer publication replaces it. Signatures are checked separately, by the group write
+ * check and by whoever dials.
+ *
+ * @param existing - The row as stored now, if any.
+ * @param candidate - The row about to be stored.
+ */
+function retainDeviceReachability(existing, candidate) {
+    const stored = existing?.reachability;
+    if (!stored)
+        return candidate;
+    // An unclaimed discovery row can acquire a different owner. Its former owner's
+    // publication must neither follow that claim nor prevent the new owner's publication.
+    if (existing.userId && candidate.userId && existing.userId !== candidate.userId)
+        return candidate;
+    const incoming = candidate.reachability;
+    if (incoming && incoming.updatedAt > stored.updatedAt)
+        return candidate;
+    if (incoming && sameDeviceReachability(incoming, stored))
+        return candidate;
+    return { ...candidate, reachability: stored };
+}
 /** Schema for the signed identity and bounded presentation hints exchanged by devices. */
 exports.deviceInfoSchema = zod_1.z.object({
     userId: zod_types_1.zodPeerId,

package/package.json

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