@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/edge/reachability/ReachabilitySessionService.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.P2PSessionNotFoundError = exports.P2PSessionExpiredError = exports.P2PCandidateSessionLimitExceededError = exports.P2PCandidateUpdateLimitExceededError = exports.P2PActiveSessionLimitExceededError = exports.NodeRouteSourceNotFoundError = exports.InvalidRelaySessionRequestError = exports.ReachabilitySessionService = void 0;
+exports.P2PSessionNotFoundError = exports.P2PSessionExpiredError = exports.P2PCandidateSessionLimitExceededError = exports.P2PCandidateUpdateLimitExceededError = exports.P2PActiveSessionLimitExceededError = exports.NodeRouteSourceNotFoundError = exports.NodeMetadataConflictError = exports.InvalidRelaySessionRequestError = exports.InvalidP2PSessionRequestError = exports.ReachabilitySessionService = void 0;
 const RouteSetBuilder_1 = require("./RouteSetBuilder");
+const TcpP2PSignalingSession_1 = require("./TcpP2PSignalingSession");
 class ReachabilitySessionService {
     constructor(options) {
         this.options = options;
@@ -16,10 +17,6 @@ class ReachabilitySessionService {
     }
     async createP2PSession(nodeId, request) {
         const source = await this.loadNodeRouteSource(nodeId);
-        const activeSessions = this.readActiveP2PSessions(source.metadata);
-        if (activeSessions.length >= this.maxActiveP2PSessionsPerNode) {
-            throw new P2PActiveSessionLimitExceededError(`Node ${nodeId} reached active P2P session limit`);
-        }
         const createdAt = this.now();
         const expiresAt = addSeconds(createdAt, this.defaultP2PTtlSeconds);
         const suffix = this.randomId();
@@ -29,6 +26,7 @@ class ReachabilitySessionService {
         if (Array.isArray(request.candidates) && request.candidates.length > limits.maxCandidatesPerUpdate) {
             throw new P2PCandidateUpdateLimitExceededError('P2P candidate update limit exceeded');
         }
+        const dataPlaneSecret = this.resolveDataPlaneSecret(request);
         const candidates = this.normalizeP2PCandidates(request.candidates, {
             role: 'client',
             sourceId: request.clientId,
@@ -59,8 +57,14 @@ class ReachabilitySessionService {
             capabilities: normalizeStringArray(request.capabilities),
             candidates,
             limits,
+            ...(dataPlaneSecret ? { dataPlaneSecret } : {}),
         };
-        await this.appendSession(nodeId, 'p2p', session);
+        await this.appendSession(nodeId, 'p2p', session, (metadata) => {
+            const activeSessions = this.readActiveP2PSessions(metadata);
+            if (activeSessions.length >= this.maxActiveP2PSessionsPerNode) {
+                throw new P2PActiveSessionLimitExceededError(`Node ${nodeId} reached active P2P session limit`);
+            }
+        });
         return session;
     }
     async getP2PSession(nodeId, sessionId) {
@@ -84,37 +88,42 @@ class ReachabilitySessionService {
         return { kind: 'p2p', sessions };
     }
     async addP2PCandidates(nodeId, sessionId, request) {
-        const { reachabilitySessions, p2pSessions, sessionIndex, session } = await this.loadP2PSession(nodeId, sessionId);
-        this.assertP2PSessionActive(session);
-        const limits = this.resolveP2PSessionLimits(session);
-        if (request.candidates.length > limits.maxCandidatesPerUpdate) {
-            throw new P2PCandidateUpdateLimitExceededError('P2P candidate update limit exceeded');
-        }
-        const normalizedCandidates = this.normalizeP2PCandidates(request.candidates, {
-            role: request.role,
-            sourceId: request.sourceId,
-            createdAt: this.now(),
-        });
-        const nextCandidates = [
-            ...session.candidates,
-            ...normalizedCandidates,
-        ];
-        if (nextCandidates.length > limits.maxCandidatesTotal) {
-            throw new P2PCandidateSessionLimitExceededError('P2P candidate session limit exceeded');
-        }
-        const nextSession = {
-            ...session,
-            candidates: nextCandidates,
-        };
-        const nextP2PSessions = [...p2pSessions];
-        nextP2PSessions[sessionIndex] = nextSession;
-        await this.options.repository.mergeNodeMetadata(nodeId, {
-            reachabilitySessions: {
-                ...reachabilitySessions,
-                p2p: nextP2PSessions,
-            },
+        return await this.mutateNodeMetadata(nodeId, (metadata) => {
+            const { reachabilitySessions, p2pSessions, sessionIndex, session } = this.readP2PSession(metadata, sessionId);
+            this.assertP2PSessionActive(session);
+            const limits = this.resolveP2PSessionLimits(session);
+            if (request.candidates.length > limits.maxCandidatesPerUpdate) {
+                throw new P2PCandidateUpdateLimitExceededError('P2P candidate update limit exceeded');
+            }
+            const normalizedCandidates = this.normalizeP2PCandidates(request.candidates, {
+                role: request.role,
+                sourceId: request.sourceId,
+                createdAt: this.now(),
+            });
+            const nextCandidates = [
+                ...session.candidates,
+                ...normalizedCandidates,
+            ];
+            if (nextCandidates.length > limits.maxCandidatesTotal) {
+                throw new P2PCandidateSessionLimitExceededError('P2P candidate session limit exceeded');
+            }
+            const nextSession = {
+                ...session,
+                candidates: nextCandidates,
+            };
+            const nextP2PSessions = [...p2pSessions];
+            nextP2PSessions[sessionIndex] = nextSession;
+            return {
+                result: nextSession,
+                next: {
+                    ...metadata,
+                    reachabilitySessions: {
+                        ...reachabilitySessions,
+                        p2p: nextP2PSessions,
+                    },
+                },
+            };
         });
-        return nextSession;
     }
     async createRelaySession(nodeId, request) {
         const source = await this.loadNodeRouteSource(nodeId);
@@ -161,6 +170,48 @@ class ReachabilitySessionService {
         await this.appendSession(nodeId, 'relay', session);
         return session;
     }
+    /**
+     * Apply a metadata mutation without losing concurrent writes.
+     *
+     * Every reachability write lives inside the node's `metadata` blob, so the old
+     * read-modify-write pattern dropped whatever landed in between (audit N07). `mutate` is
+     * re-run against freshly read metadata on each attempt, which also re-runs the validations
+     * (session limits, expiry) against the state it is actually writing to.
+     */
+    async mutateNodeMetadata(nodeId, mutate, attempts = 5) {
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            const current = await this.options.repository.getNodeMetadata(nodeId);
+            if (!current) {
+                throw new NodeRouteSourceNotFoundError(`Node ${nodeId} not found`);
+            }
+            const metadata = current.metadata ?? {};
+            const { next, result } = mutate(metadata);
+            const applied = await this.options.repository.updateNodeMetadataAtomic(nodeId, current.metadata ?? null, next);
+            if (applied) {
+                return result;
+            }
+        }
+        // Retries exhausted: report the conflict instead of pretending the write happened. A node
+        // that disappeared meanwhile is a different failure and keeps its own error type.
+        const exists = await this.options.repository.getNodeMetadata(nodeId);
+        if (!exists) {
+            throw new NodeRouteSourceNotFoundError(`Node ${nodeId} not found`);
+        }
+        throw new NodeMetadataConflictError(`Node ${nodeId} metadata changed concurrently; gave up after ${attempts} attempts`);
+    }
+    /**
+     * Fail closed for the raw TCP data plane: a session that announces that capability must carry
+     * a data-plane secret, otherwise the peer would be invited to speak in the clear (audit N03).
+     */
+    resolveDataPlaneSecret(request) {
+        const capabilities = normalizeStringArray(request.capabilities);
+        const wantsRawTcp = capabilities.includes(TcpP2PSignalingSession_1.RAW_TCP_HOLE_PUNCH_CAPABILITY);
+        const secret = typeof request.dataPlaneSecret === 'string' ? request.dataPlaneSecret : undefined;
+        if (wantsRawTcp && !secret) {
+            throw new InvalidP2PSessionRequestError('A raw TCP P2P session must carry a data plane secret');
+        }
+        return secret;
+    }
     async loadNodeRouteSource(nodeId) {
         const [metadataRow, connectivity] = await Promise.all([
             this.options.repository.getNodeMetadata(nodeId),
@@ -200,24 +251,26 @@ class ReachabilitySessionService {
     resolveP2PSessionLimits(session) {
         return normalizeP2PSessionLimits(session.limits) ?? this.p2pSessionLimits();
     }
-    async appendSession(nodeId, key, session) {
-        const current = await this.options.repository.getNodeMetadata(nodeId);
-        const metadata = current?.metadata ?? {};
-        const existing = isRecord(metadata.reachabilitySessions) ? metadata.reachabilitySessions : {};
-        const previousSessions = Array.isArray(existing[key]) ? existing[key] : [];
-        await this.options.repository.mergeNodeMetadata(nodeId, {
-            reachabilitySessions: {
-                ...existing,
-                [key]: [...previousSessions, session],
-            },
+    async appendSession(nodeId, key, session, guard) {
+        await this.mutateNodeMetadata(nodeId, (metadata) => {
+            // The guard runs against the metadata being written, not against a copy read earlier:
+            // that is what keeps a limit from being exceeded by two concurrent creates.
+            guard?.(metadata);
+            const existing = isRecord(metadata.reachabilitySessions) ? metadata.reachabilitySessions : {};
+            const previousSessions = Array.isArray(existing[key]) ? existing[key] : [];
+            return {
+                result: undefined,
+                next: {
+                    ...metadata,
+                    reachabilitySessions: {
+                        ...existing,
+                        [key]: [...previousSessions, session],
+                    },
+                },
+            };
         });
     }
-    async loadP2PSession(nodeId, sessionId) {
-        const current = await this.options.repository.getNodeMetadata(nodeId);
-        if (!current) {
-            throw new NodeRouteSourceNotFoundError(`Node ${nodeId} not found`);
-        }
-        const metadata = current.metadata ?? {};
+    readP2PSession(metadata, sessionId) {
         const reachabilitySessions = isRecord(metadata.reachabilitySessions) ? metadata.reachabilitySessions : {};
         const p2pSessions = Array.isArray(reachabilitySessions.p2p)
             ? reachabilitySessions.p2p.map(toP2PSession).filter((session) => Boolean(session))
@@ -233,6 +286,13 @@ class ReachabilitySessionService {
             session: p2pSessions[sessionIndex],
         };
     }
+    async loadP2PSession(nodeId, sessionId) {
+        const current = await this.options.repository.getNodeMetadata(nodeId);
+        if (!current) {
+            throw new NodeRouteSourceNotFoundError(`Node ${nodeId} not found`);
+        }
+        return this.readP2PSession(current.metadata ?? {}, sessionId);
+    }
     assertP2PSessionActive(session) {
         if (!this.isP2PSessionActive(session)) {
             throw new P2PSessionExpiredError(`P2P session ${session.sessionId} expired`);
@@ -280,9 +340,15 @@ class ReachabilitySessionService {
     }
 }
 exports.ReachabilitySessionService = ReachabilitySessionService;
+class InvalidP2PSessionRequestError extends Error {
+}
+exports.InvalidP2PSessionRequestError = InvalidP2PSessionRequestError;
 class InvalidRelaySessionRequestError extends Error {
 }
 exports.InvalidRelaySessionRequestError = InvalidRelaySessionRequestError;
+class NodeMetadataConflictError extends Error {
+}
+exports.NodeMetadataConflictError = NodeMetadataConflictError;
 class NodeRouteSourceNotFoundError extends Error {
 }
 exports.NodeRouteSourceNotFoundError = NodeRouteSourceNotFoundError;
@@ -375,6 +441,9 @@ function toP2PSession(value) {
     const expiresAt = getString(value.expiresAt);
     const signalingUrl = getString(value.signalingUrl);
     const limits = normalizeP2PSessionLimits(value.limits);
+    // Dropping this here would silently downgrade every listed session to a plaintext data plane:
+    // the node reads its secret from the listed session (audit N03).
+    const dataPlaneSecret = getString(value.dataPlaneSecret);
     if (!sessionId || !nodeId || !clientId || !createdAt || !expiresAt || !signalingUrl) {
         return undefined;
     }
@@ -390,6 +459,7 @@ function toP2PSession(value) {
         nodeCandidates: Array.isArray(value.nodeCandidates) ? value.nodeCandidates : [],
         signalingUrl,
         capabilities: normalizeStringArray(value.capabilities),
+        ...(dataPlaneSecret ? { dataPlaneSecret } : {}),
         candidates: Array.isArray(value.candidates)
             ? value.candidates.map(toP2PTransportCandidate).filter((candidate) => Boolean(candidate))
             : [],

package/dist/edge/reachability/ReachabilitySessionService.jsonld

@@ -75,6 +75,14 @@
           "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_createRelaySession",
           "memberFieldName": "createRelaySession"
         },
+        {
+          "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_mutateNodeMetadata",
+          "memberFieldName": "mutateNodeMetadata"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_resolveDataPlaneSecret",
+          "memberFieldName": "resolveDataPlaneSecret"
+        },
         {
           "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_loadNodeRouteSource",
           "memberFieldName": "loadNodeRouteSource"
@@ -95,6 +103,10 @@
           "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_appendSession",
           "memberFieldName": "appendSession"
         },
+        {
+          "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_readP2PSession",
+          "memberFieldName": "readP2PSession"
+        },
         {
           "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService__member_loadP2PSession",
           "memberFieldName": "loadP2PSession"
@@ -118,6 +130,20 @@
         }
       ]
     },
+    {
+      "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#InvalidP2PSessionRequestError",
+      "@type": "Class",
+      "requireElement": "InvalidP2PSessionRequestError",
+      "parameters": [],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#NodeMetadataConflictError",
+      "@type": "Class",
+      "requireElement": "NodeMetadataConflictError",
+      "parameters": [],
+      "constructorArguments": []
+    },
     {
       "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#P2PActiveSessionLimitExceededError",
       "@type": "Class",

package/dist/edge/reachability/RouteValidation.d.ts

@@ -0,0 +1,29 @@
+import type { AccessRoute } from './types';
+/**
+ * Route validity, decided locally before anything is dialled.
+ *
+ * Both selection paths (the managed-client fetch and the best-effort chooser) used to trust
+ * whatever the node advertised: an expired access point, a loopback address from another
+ * machine, or an unrelated service on the same port could all be selected (audit N06). The
+ * rules live here so the two paths cannot drift apart.
+ */
+export interface RouteValidityContext {
+    now: Date;
+    /** A caller on another machine cannot use a loopback access point, whatever the node says. */
+    remoteClient: boolean;
+}
+/** Fail closed: an expiry that cannot be parsed is treated as no usable expiry information. */
+export declare function routeUnusableReason(route: AccessRoute, context: RouteValidityContext): string | undefined;
+export declare function isHttpTarget(targetUrl: string): boolean;
+/**
+ * Probe an HTTP access point and require evidence that it really is a Solid server.
+ *
+ * Captured from a running Community Solid Server: `HEAD /.well-known/solid` answers 405 with a
+ * `Link` header carrying Solid vocabulary and `x-powered-by: Community Solid Server`. A 404
+ * ("no Solid resource here") or 5xx (broken origin) always fails; any other answer still has to
+ * carry identity evidence, because the old `status < 500` rule let an unrelated service on the
+ * same port pass just by answering.
+ */
+export declare function probeSolidWellKnown(targetUrl: string, signal: AbortSignal, fetchImpl?: typeof fetch): Promise<boolean>;
+/** Identity evidence for a `/.well-known/solid` answer. */
+export declare function isSolidWellKnownResponse(response: Response): boolean;

package/dist/edge/reachability/RouteValidation.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeUnusableReason = routeUnusableReason;
+exports.isHttpTarget = isHttpTarget;
+exports.probeSolidWellKnown = probeSolidWellKnown;
+exports.isSolidWellKnownResponse = isSolidWellKnownResponse;
+/** Fail closed: an expiry that cannot be parsed is treated as no usable expiry information. */
+function routeUnusableReason(route, context) {
+    if (context.remoteClient && route.visibility === 'local-only') {
+        return 'loopback-only access point, not usable from a remote client';
+    }
+    if (route.expiresAt === undefined) {
+        return undefined;
+    }
+    const expiresAt = Date.parse(route.expiresAt);
+    if (!Number.isFinite(expiresAt)) {
+        return `unparseable expiresAt "${route.expiresAt}"`;
+    }
+    if (expiresAt <= context.now.getTime()) {
+        return `expired at ${route.expiresAt}`;
+    }
+    return undefined;
+}
+function isHttpTarget(targetUrl) {
+    return targetUrl.startsWith('http://') || targetUrl.startsWith('https://');
+}
+/**
+ * Probe an HTTP access point and require evidence that it really is a Solid server.
+ *
+ * Captured from a running Community Solid Server: `HEAD /.well-known/solid` answers 405 with a
+ * `Link` header carrying Solid vocabulary and `x-powered-by: Community Solid Server`. A 404
+ * ("no Solid resource here") or 5xx (broken origin) always fails; any other answer still has to
+ * carry identity evidence, because the old `status < 500` rule let an unrelated service on the
+ * same port pass just by answering.
+ */
+async function probeSolidWellKnown(targetUrl, signal, fetchImpl) {
+    const response = await (fetchImpl ?? fetch)(new URL('/.well-known/solid', targetUrl), {
+        method: 'HEAD',
+        signal,
+    });
+    if (response.status === 404 || response.status >= 500) {
+        return false;
+    }
+    return isSolidWellKnownResponse(response);
+}
+/** Identity evidence for a `/.well-known/solid` answer. */
+function isSolidWellKnownResponse(response) {
+    const link = response.headers.get('link') ?? '';
+    if (link.includes('http://www.w3.org/ns/solid/terms#')) {
+        return true;
+    }
+    if (link.includes('rel="acl"') && link.includes('rel="describedby"')) {
+        return true;
+    }
+    const poweredBy = response.headers.get('x-powered-by') ?? '';
+    return /community solid server/iu.test(poweredBy);
+}
+//# sourceMappingURL=RouteValidation.js.map

package/dist/edge/reachability/TcpP2PDataPlaneTransport.d.ts

@@ -1,27 +1,51 @@
 import { type AddressInfo, type Socket } from 'node:net';
-import type { P2PDataPlaneHandler, P2PDataPlaneTransport } from './P2PDataPlane';
-export interface TcpP2PDataPlaneTransportOptions {
+import { type P2PDataPlaneHandler, type P2PDataPlaneLimitsOptions, type P2PDataPlaneTransport } from './P2PDataPlane';
+/**
+ * Data plane authentication (audit N03).
+ *
+ * Both endpoints must configure the same per-session secret; it is only ever transported over
+ * the authenticated signaling API. Each side announces itself with a nonce, derives
+ * direction-separated keys, and then seals every frame. A peer without the secret cannot make
+ * the other side accept a frame, and a frame cannot be replayed into another session or
+ * direction.
+ */
+export interface P2PDataPlaneSecurityOptions {
+    role: 'client' | 'server';
+    /** Known session id. Required with `secret`; discovered from the hello otherwise. */
+    sessionId?: string;
+    /** Base64 per-session secret. */
+    secret?: string;
+    /** Server side that serves many sessions on one socket: look the secret up on hello. */
+    resolveSessionSecret?: (sessionId: string) => Uint8Array | string | undefined | Promise<Uint8Array | string | undefined>;
+    /** How long to wait for the peer's hello before failing closed. */
+    handshakeTimeoutMs?: number;
+}
+export interface TcpP2PDataPlaneTransportOptions extends P2PDataPlaneLimitsOptions {
     remoteHost: string;
     remotePort: number;
     socket?: Socket;
     timeoutMs?: number;
     randomId?: () => string;
+    /** Configure to seal the data plane; omitted means plaintext (only for tests/legacy). */
+    secure?: P2PDataPlaneSecurityOptions;
 }
 export interface TcpP2PDataPlaneTransport extends P2PDataPlaneTransport {
     close(): void;
 }
-export interface TcpP2PDataPlaneServerOptions {
+export interface TcpP2PDataPlaneServerOptions extends P2PDataPlaneLimitsOptions {
     handler: P2PDataPlaneHandler;
     host?: string;
+    secure?: P2PDataPlaneSecurityOptions;
 }
 export interface TcpP2PDataPlaneServer {
     listen(port?: number): Promise<void>;
     address(): AddressInfo;
     close(): Promise<void>;
 }
-export interface TcpP2PDataPlaneSocketOptions {
+export interface TcpP2PDataPlaneSocketOptions extends P2PDataPlaneLimitsOptions {
     socket: Socket;
     handler: P2PDataPlaneHandler;
+    secure?: P2PDataPlaneSecurityOptions;
 }
 export interface TcpP2PDataPlaneSocketHandle {
     close(): void;