@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/edge/reachability/P2PDataPlane.js

@@ -1,30 +1,124 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XPOD_P2P_HTTP_PROTOCOL = void 0;
+exports.XPOD_P2P_ACCEPT_CHUNKED = exports.XPOD_P2P_ACCEPT_HEADER = exports.P2PDataPlaneAbortError = exports.P2PDataPlaneLimitError = exports.P2P_DATA_PLANE_LIMITS = exports.XPOD_P2P_HTTP_PROTOCOL = void 0;
 exports.createP2PDataPlaneFetch = createP2PDataPlaneFetch;
 exports.createP2PDataPlaneHandler = createP2PDataPlaneHandler;
+exports.base64ByteLength = base64ByteLength;
 exports.XPOD_P2P_HTTP_PROTOCOL = 'xpod-p2p-http/1';
+/**
+ * Resource ceilings for the P2P data plane (audit N17).
+ *
+ * The data plane is a byte pipe between two processes, so every unbounded quantity on it is a
+ * denial-of-service waiting to happen: a single line that never ends, a body that never stops,
+ * or a peer that opens more requests than the other side can serve. The numbers are deliberately
+ * generous for Pod traffic and small enough to fail fast.
+ */
+exports.P2P_DATA_PLANE_LIMITS = {
+    /** Largest single wire line (one JSON envelope, base64 included). */
+    maxFrameBytes: 8 * 1024 * 1024,
+    /** Largest request or response body carried inside frames. */
+    maxBodyBytes: 4 * 1024 * 1024,
+    /** In-flight requests allowed per transport and per socket. */
+    maxConcurrentRequests: 16,
+    /** Chunk size used when a response body is streamed. */
+    chunkBytes: 256 * 1024,
+};
+/** Exceeding a ceiling is its own error so callers can answer 413/429 instead of a generic 502. */
+class P2PDataPlaneLimitError extends Error {
+    constructor(message, limit) {
+        super(message);
+        this.limit = limit;
+        this.name = 'P2PDataPlaneLimitError';
+    }
+}
+exports.P2PDataPlaneLimitError = P2PDataPlaneLimitError;
+/** The caller aborted: the request may still be running on the peer until the cancel lands. */
+class P2PDataPlaneAbortError extends Error {
+    constructor(message = 'P2P data plane request was aborted') {
+        super(message);
+        this.name = 'P2PDataPlaneAbortError';
+    }
+}
+exports.P2PDataPlaneAbortError = P2PDataPlaneAbortError;
+/** Header a client sets to say it can consume chunked (streamed) response bodies. */
+exports.XPOD_P2P_ACCEPT_HEADER = 'x-xpod-p2p-accept';
+exports.XPOD_P2P_ACCEPT_CHUNKED = 'chunked';
 function createP2PDataPlaneFetch(options) {
     if (options.route.kind !== 'p2p') {
         throw new Error(`P2P data plane requires a p2p route, got ${options.route.kind}`);
     }
     const canonicalOrigin = new URL(options.route.canonicalUrl).origin;
+    const maxBodyBytes = options.maxBodyBytes ?? exports.P2P_DATA_PLANE_LIMITS.maxBodyBytes;
     return async (input, init) => {
         const request = new Request(input, init);
         const canonicalUrl = new URL(request.url);
         if (canonicalUrl.origin !== canonicalOrigin) {
             throw new Error(`Request ${canonicalUrl.toString()} is outside canonical origin ${canonicalOrigin}`);
         }
+        const bodyBase64 = await bodyToBase64(request, maxBodyBytes);
+        const headers = headersToList(request.headers);
+        // Only a transport that can carry chunk envelopes may ask for a streamed body. An older
+        // peer ignores the header and answers with one frame, which this side still accepts.
+        if (options.transport.supportsStreaming
+            && !headers.some(([key]) => key.toLowerCase() === exports.XPOD_P2P_ACCEPT_HEADER)) {
+            headers.push([exports.XPOD_P2P_ACCEPT_HEADER, exports.XPOD_P2P_ACCEPT_CHUNKED]);
+        }
         const frame = {
             protocol: exports.XPOD_P2P_HTTP_PROTOCOL,
             method: request.method,
             url: canonicalUrl.toString(),
-            headers: headersToList(request.headers),
-            bodyBase64: await bodyToBase64(request),
+            headers,
+            bodyBase64,
         };
-        const responseFrame = await options.transport.request(frame);
-        validateResponseFrame(responseFrame);
-        return new Response(base64ToBody(responseFrame.bodyBase64), {
+        const signal = init?.signal ?? request.signal;
+        let streamController;
+        const streamedBody = new ReadableStream({
+            start(controller) {
+                streamController = controller;
+            },
+            cancel() {
+                // The consumer stopped reading: the request must not keep the peer working.
+                streamController = undefined;
+            },
+        });
+        let responseFrame;
+        try {
+            responseFrame = await options.transport.request(frame, {
+                ...(signal ? { signal } : {}),
+                onChunk: (chunk) => {
+                    streamController?.enqueue(chunk);
+                },
+                onEnd: () => {
+                    streamController?.close();
+                    streamController = undefined;
+                },
+                onError: (error) => {
+                    streamController?.error(error);
+                    streamController = undefined;
+                },
+            });
+        }
+        catch (error) {
+            // Nothing will read the stream prepared above, and an aborted request must surface as an
+            // abort rather than as a transport error (fetch semantics).
+            await streamedBody.cancel().catch(() => undefined);
+            if (signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            throw error;
+        }
+        validateResponseFrame(responseFrame, maxBodyBytes);
+        if (responseFrame.streamed) {
+            // Hand the stream over even when it already completed: the consumer still has to read
+            // the chunks that were enqueued before the end envelope arrived.
+            return new Response(streamedBody, {
+                status: responseFrame.status,
+                statusText: responseFrame.statusText,
+                headers: new Headers(responseFrame.headers),
+            });
+        }
+        await streamedBody.cancel().catch(() => undefined);
+        return new Response(base64ToBody(responseFrame.bodyBase64, maxBodyBytes), {
             status: responseFrame.status,
             statusText: responseFrame.statusText,
             headers: new Headers(responseFrame.headers),
@@ -34,9 +128,10 @@ function createP2PDataPlaneFetch(options) {
 function createP2PDataPlaneHandler(options) {
     const targetBaseUrl = new URL(options.targetBaseUrl.toString());
     const fetchImpl = options.fetchImpl ?? fetch;
+    const maxBodyBytes = options.maxBodyBytes ?? exports.P2P_DATA_PLANE_LIMITS.maxBodyBytes;
     return {
-        async handleRequest(frame) {
-            validateRequestFrame(frame);
+        async handleRequest(frame, requestOptions) {
+            validateRequestFrame(frame, maxBodyBytes);
             const canonicalUrl = new URL(frame.url);
             const targetUrl = rewriteTargetUrl(targetBaseUrl, canonicalUrl);
             const headers = new Headers(frame.headers);
@@ -47,20 +142,35 @@ function createP2PDataPlaneHandler(options) {
             const response = await fetchImpl(targetUrl, {
                 method: frame.method,
                 headers,
-                body: methodCanHaveBody(frame.method) ? base64ToBody(frame.bodyBase64) : undefined,
+                body: methodCanHaveBody(frame.method) ? base64ToBody(frame.bodyBase64, maxBodyBytes) : undefined,
+                // Cancellation has to reach the upstream request, otherwise a cancelled client leaves
+                // the node fetching a body nobody will read (audit N17).
+                ...(requestOptions?.signal ? { signal: requestOptions.signal } : {}),
             });
+            const wantsStream = (frame.headers ?? [])
+                .some(([key, value]) => key.toLowerCase() === exports.XPOD_P2P_ACCEPT_HEADER && value === exports.XPOD_P2P_ACCEPT_CHUNKED);
+            if (wantsStream && response.body) {
+                return {
+                    protocol: exports.XPOD_P2P_HTTP_PROTOCOL,
+                    requestId: frame.requestId,
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: headersToList(response.headers),
+                    bodyStream: response.body,
+                };
+            }
             return {
                 protocol: exports.XPOD_P2P_HTTP_PROTOCOL,
                 requestId: frame.requestId,
                 status: response.status,
                 statusText: response.statusText,
                 headers: headersToList(response.headers),
-                bodyBase64: await responseToBase64(response),
+                bodyBase64: await responseToBase64(response, maxBodyBytes),
             };
         },
     };
 }
-function validateRequestFrame(frame) {
+function validateRequestFrame(frame, maxBodyBytes) {
     if (frame.protocol !== exports.XPOD_P2P_HTTP_PROTOCOL) {
         throw new Error(`Unsupported P2P HTTP protocol: ${String(frame.protocol)}`);
     }
@@ -73,14 +183,30 @@ function validateRequestFrame(frame) {
     catch {
         throw new Error('P2P HTTP request URL must be absolute');
     }
+    // The client is expected to refuse oversized bodies itself; this is the side that must not
+    // trust it (audit N17).
+    if (frame.bodyBase64 !== undefined && base64ByteLength(frame.bodyBase64) > maxBodyBytes) {
+        throw new P2PDataPlaneLimitError(`P2P HTTP request body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
 }
-function validateResponseFrame(frame) {
+function validateResponseFrame(frame, maxBodyBytes) {
     if (frame.protocol !== exports.XPOD_P2P_HTTP_PROTOCOL) {
         throw new Error(`Unsupported P2P HTTP protocol: ${String(frame.protocol)}`);
     }
     if (!Number.isInteger(frame.status) || frame.status < 100 || frame.status > 599) {
         throw new Error(`Invalid P2P HTTP response status: ${String(frame.status)}`);
     }
+    if (frame.bodyBase64 !== undefined && base64ByteLength(frame.bodyBase64) > maxBodyBytes) {
+        throw new P2PDataPlaneLimitError(`P2P HTTP response body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
+}
+/** Decoded size of a base64 payload without allocating the buffer. */
+function base64ByteLength(value) {
+    if (value.length === 0) {
+        return 0;
+    }
+    const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;
+    return Math.floor((value.length * 3) / 4) - padding;
 }
 function rewriteTargetUrl(targetBase, canonicalUrl) {
     const basePath = targetBase.pathname.endsWith('/')
@@ -134,27 +260,42 @@ function methodCanHaveBody(method) {
     const normalized = method.toUpperCase();
     return normalized !== 'GET' && normalized !== 'HEAD';
 }
-async function bodyToBase64(request) {
+async function bodyToBase64(request, maxBodyBytes) {
     if (!methodCanHaveBody(request.method)) {
         return undefined;
     }
+    const declared = request.headers.get('content-length');
+    if (declared !== null && Number(declared) > maxBodyBytes) {
+        // Refuse before reading: buffering an oversized upload just to reject it is the failure
+        // mode this limit exists to prevent.
+        throw new P2PDataPlaneLimitError(`P2P HTTP request body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
     const body = await request.arrayBuffer();
+    if (body.byteLength > maxBodyBytes) {
+        throw new P2PDataPlaneLimitError(`P2P HTTP request body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
     if (body.byteLength === 0) {
         return undefined;
     }
     return Buffer.from(body).toString('base64');
 }
-async function responseToBase64(response) {
+async function responseToBase64(response, maxBodyBytes) {
     const body = await response.arrayBuffer();
+    if (body.byteLength > maxBodyBytes) {
+        throw new P2PDataPlaneLimitError(`P2P HTTP response body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
     if (body.byteLength === 0) {
         return undefined;
     }
     return Buffer.from(body).toString('base64');
 }
-function base64ToBody(value) {
+function base64ToBody(value, maxBodyBytes) {
     if (!value) {
         return undefined;
     }
+    if (base64ByteLength(value) > maxBodyBytes) {
+        throw new P2PDataPlaneLimitError(`P2P HTTP body exceeds ${maxBodyBytes} bytes`, 'maxBodyBytes');
+    }
     return Buffer.from(value, 'base64');
 }
 //# sourceMappingURL=P2PDataPlane.js.map

package/dist/edge/reachability/P2PDataPlane.jsonld

@@ -66,6 +66,39 @@
         {
           "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PHttpResponseFrame__member_bodyBase64",
           "memberFieldName": "bodyBase64"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PHttpResponseFrame__member_streamed",
+          "memberFieldName": "streamed"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PHttpResponseFrame__member_bodyStream",
+          "memberFieldName": "bodyStream"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions",
+      "@type": "AbstractClass",
+      "requireElement": "P2PDataPlaneRequestOptions",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions__member_signal",
+          "memberFieldName": "signal"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions__member_onChunk",
+          "memberFieldName": "onChunk"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions__member_onEnd",
+          "memberFieldName": "onEnd"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions__member_onError",
+          "memberFieldName": "onError"
         }
       ],
       "constructorArguments": []
@@ -76,6 +109,10 @@
       "requireElement": "P2PDataPlaneTransport",
       "parameters": [],
       "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneTransport__member_supportsStreaming",
+          "memberFieldName": "supportsStreaming"
+        },
         {
           "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneTransport__member_request",
           "memberFieldName": "request"
@@ -83,10 +120,34 @@
       ],
       "constructorArguments": []
     },
+    {
+      "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions",
+      "@type": "AbstractClass",
+      "requireElement": "P2PDataPlaneLimitsOptions",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions__member_maxFrameBytes",
+          "memberFieldName": "maxFrameBytes"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions__member_maxBodyBytes",
+          "memberFieldName": "maxBodyBytes"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions__member_maxConcurrentRequests",
+          "memberFieldName": "maxConcurrentRequests"
+        }
+      ],
+      "constructorArguments": []
+    },
     {
       "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneFetchOptions",
       "@type": "AbstractClass",
       "requireElement": "P2PDataPlaneFetchOptions",
+      "extends": [
+        "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions"
+      ],
       "parameters": [],
       "memberFields": [
         {
@@ -104,6 +165,9 @@
       "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneHandlerOptions",
       "@type": "AbstractClass",
       "requireElement": "P2PDataPlaneHandlerOptions",
+      "extends": [
+        "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions"
+      ],
       "parameters": [],
       "memberFields": [
         {

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

@@ -0,0 +1,42 @@
+/**
+ * Authenticated encryption for the raw TCP data plane (audit N03).
+ *
+ * The data plane used to be plaintext JSON over a hole-punched TCP socket: anyone who could
+ * reach the port could read, forge or replay Pod traffic, and the node could not tell which
+ * session a connection belonged to. Both sides now share a per-session secret that travels
+ * only over the authenticated signaling API, derive direction-separated keys from it, and seal
+ * every frame with AES-256-GCM — so a peer without the secret cannot produce a frame the other
+ * side accepts, and a frame cannot be replayed into a different session or direction.
+ */
+export declare const P2P_DATA_PLANE_KEY_BYTES = 32;
+export declare const P2P_DATA_PLANE_NONCE_BYTES = 12;
+/** Distinct from protocol errors so callers can close the connection instead of retrying. */
+export declare class P2PDataPlaneSecurityError extends Error {
+    constructor(message: string);
+}
+export type P2PDataPlaneDirection = 'client-to-server' | 'server-to-client';
+export interface P2PDataPlaneKeys {
+    clientToServer: Buffer;
+    serverToClient: Buffer;
+}
+/** A fresh per-session secret, base64 so it can travel inside the session record. */
+export declare function createDataPlaneSecret(): string;
+/** Decode a session secret, rejecting anything that is not exactly one key long. */
+export declare function decodeDataPlaneSecret(value: string): Buffer;
+export declare function createDataPlaneNonce(): Buffer;
+/**
+ * Direction-separated keys.
+ *
+ * Both nonces and the session id go into the derivation, so a frame sealed for one session (or
+ * for one direction inside it) cannot be replayed into another.
+ */
+export declare function deriveDataPlaneKeys(secret: Buffer, sessionId: string, clientNonce: Buffer, serverNonce: Buffer): P2PDataPlaneKeys;
+export declare function keyForDirection(keys: P2PDataPlaneKeys, direction: P2PDataPlaneDirection): Buffer;
+export interface SealedDataPlaneFrame {
+    /** Monotonic per direction: the receiver refuses anything but the next value, so replays fail. */
+    sequence: number;
+    nonce: string;
+    ciphertext: string;
+}
+export declare function sealDataPlaneFrame(key: Buffer, sessionId: string, direction: P2PDataPlaneDirection, sequence: number, plaintext: Buffer): SealedDataPlaneFrame;
+export declare function openDataPlaneFrame(key: Buffer, sessionId: string, direction: P2PDataPlaneDirection, sealed: SealedDataPlaneFrame, expectedSequence: number): Buffer;

package/dist/edge/reachability/P2PDataPlaneCrypto.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.P2PDataPlaneSecurityError = exports.P2P_DATA_PLANE_NONCE_BYTES = exports.P2P_DATA_PLANE_KEY_BYTES = void 0;
+exports.createDataPlaneSecret = createDataPlaneSecret;
+exports.decodeDataPlaneSecret = decodeDataPlaneSecret;
+exports.createDataPlaneNonce = createDataPlaneNonce;
+exports.deriveDataPlaneKeys = deriveDataPlaneKeys;
+exports.keyForDirection = keyForDirection;
+exports.sealDataPlaneFrame = sealDataPlaneFrame;
+exports.openDataPlaneFrame = openDataPlaneFrame;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Authenticated encryption for the raw TCP data plane (audit N03).
+ *
+ * The data plane used to be plaintext JSON over a hole-punched TCP socket: anyone who could
+ * reach the port could read, forge or replay Pod traffic, and the node could not tell which
+ * session a connection belonged to. Both sides now share a per-session secret that travels
+ * only over the authenticated signaling API, derive direction-separated keys from it, and seal
+ * every frame with AES-256-GCM — so a peer without the secret cannot produce a frame the other
+ * side accepts, and a frame cannot be replayed into a different session or direction.
+ */
+exports.P2P_DATA_PLANE_KEY_BYTES = 32;
+exports.P2P_DATA_PLANE_NONCE_BYTES = 12;
+const GCM_TAG_BYTES = 16;
+const HKDF_SALT = 'xpod-p2p-data-plane/v1';
+/** Distinct from protocol errors so callers can close the connection instead of retrying. */
+class P2PDataPlaneSecurityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'P2PDataPlaneSecurityError';
+    }
+}
+exports.P2PDataPlaneSecurityError = P2PDataPlaneSecurityError;
+/** A fresh per-session secret, base64 so it can travel inside the session record. */
+function createDataPlaneSecret() {
+    return (0, node_crypto_1.randomBytes)(exports.P2P_DATA_PLANE_KEY_BYTES).toString('base64');
+}
+/** Decode a session secret, rejecting anything that is not exactly one key long. */
+function decodeDataPlaneSecret(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new P2PDataPlaneSecurityError('Data plane secret is missing');
+    }
+    let decoded;
+    try {
+        decoded = Buffer.from(value, 'base64');
+    }
+    catch {
+        throw new P2PDataPlaneSecurityError('Data plane secret is not valid base64');
+    }
+    if (decoded.byteLength !== exports.P2P_DATA_PLANE_KEY_BYTES) {
+        throw new P2PDataPlaneSecurityError(`Data plane secret must be ${exports.P2P_DATA_PLANE_KEY_BYTES} bytes, got ${decoded.byteLength}`);
+    }
+    return decoded;
+}
+function createDataPlaneNonce() {
+    return (0, node_crypto_1.randomBytes)(exports.P2P_DATA_PLANE_NONCE_BYTES);
+}
+/**
+ * Direction-separated keys.
+ *
+ * Both nonces and the session id go into the derivation, so a frame sealed for one session (or
+ * for one direction inside it) cannot be replayed into another.
+ */
+function deriveDataPlaneKeys(secret, sessionId, clientNonce, serverNonce) {
+    const derive = (direction) => Buffer.from((0, node_crypto_1.hkdfSync)('sha256', secret, Buffer.concat([Buffer.from(HKDF_SALT), clientNonce, serverNonce]), Buffer.from(`${sessionId}|${direction}`), exports.P2P_DATA_PLANE_KEY_BYTES));
+    return {
+        clientToServer: derive('client-to-server'),
+        serverToClient: derive('server-to-client'),
+    };
+}
+function keyForDirection(keys, direction) {
+    return direction === 'client-to-server' ? keys.clientToServer : keys.serverToClient;
+}
+function additionalData(sessionId, direction, sequence) {
+    return Buffer.from(`${sessionId}|${direction}|${sequence}`);
+}
+function sealDataPlaneFrame(key, sessionId, direction, sequence, plaintext) {
+    const nonce = createDataPlaneNonce();
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, nonce);
+    cipher.setAAD(additionalData(sessionId, direction, sequence));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+    return {
+        sequence,
+        nonce: nonce.toString('base64'),
+        ciphertext: ciphertext.toString('base64'),
+    };
+}
+function openDataPlaneFrame(key, sessionId, direction, sealed, expectedSequence) {
+    if (sealed.sequence !== expectedSequence) {
+        throw new P2PDataPlaneSecurityError(`Data plane frame out of order: expected ${expectedSequence}, got ${String(sealed.sequence)}`);
+    }
+    const nonce = Buffer.from(sealed.nonce, 'base64');
+    if (nonce.byteLength !== exports.P2P_DATA_PLANE_NONCE_BYTES) {
+        throw new P2PDataPlaneSecurityError('Data plane frame nonce has the wrong length');
+    }
+    const payload = Buffer.from(sealed.ciphertext, 'base64');
+    if (payload.byteLength < GCM_TAG_BYTES) {
+        throw new P2PDataPlaneSecurityError('Data plane frame is too short to be authentic');
+    }
+    const ciphertext = payload.subarray(0, payload.byteLength - GCM_TAG_BYTES);
+    const tag = payload.subarray(payload.byteLength - GCM_TAG_BYTES);
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, nonce);
+        decipher.setAAD(additionalData(sessionId, direction, sealed.sequence));
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        // Authentication failed: wrong key, tampered frame, or a frame from another session.
+        throw new P2PDataPlaneSecurityError('Data plane frame failed authentication');
+    }
+}
+//# sourceMappingURL=P2PDataPlaneCrypto.js.map

package/dist/edge/reachability/P2PDataPlaneCrypto.jsonld

@@ -0,0 +1,69 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError",
+      "@type": "Class",
+      "requireElement": "P2PDataPlaneSecurityError",
+      "comment": "Distinct from protocol errors so callers can close the connection instead of retrying.",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError_message",
+          "range": "xsd:string"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError__member_constructor",
+          "memberFieldName": "constructor"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError_message"
+        }
+      ]
+    },
+    {
+      "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneKeys",
+      "@type": "AbstractClass",
+      "requireElement": "P2PDataPlaneKeys",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneKeys__member_clientToServer",
+          "memberFieldName": "clientToServer"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneKeys__member_serverToClient",
+          "memberFieldName": "serverToClient"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#SealedDataPlaneFrame",
+      "@type": "AbstractClass",
+      "requireElement": "SealedDataPlaneFrame",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#SealedDataPlaneFrame__member_sequence",
+          "memberFieldName": "sequence"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#SealedDataPlaneFrame__member_nonce",
+          "memberFieldName": "nonce"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#SealedDataPlaneFrame__member_ciphertext",
+          "memberFieldName": "ciphertext"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

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

@@ -9,6 +9,8 @@ export interface CreateP2PSessionInput {
     clientId: string;
     capabilities?: string[];
     candidates?: P2PTransportCandidate[];
+    /** Per-session data plane secret; required for raw TCP sessions (audit N03). */
+    dataPlaneSecret?: string;
 }
 export interface P2PSignalingClient {
     createP2PSession(request: CreateP2PSessionInput): Promise<P2PSession>;

package/dist/edge/reachability/P2PSignalingClient.js

@@ -26,6 +26,7 @@ class HttpP2PSignalingClient {
                 clientId: request.clientId,
                 capabilities: request.capabilities ?? [],
                 candidates: request.candidates ?? [],
+                ...(request.dataPlaneSecret ? { dataPlaneSecret: request.dataPlaneSecret } : {}),
             },
         });
     }

package/dist/edge/reachability/P2PSignalingClient.jsonld

@@ -46,6 +46,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/P2PSignalingClient.jsonld#CreateP2PSessionInput__member_candidates",
           "memberFieldName": "candidates"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/P2PSignalingClient.jsonld#CreateP2PSessionInput__member_dataPlaneSecret",
+          "memberFieldName": "dataPlaneSecret"
         }
       ],
       "constructorArguments": []

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

@@ -29,18 +29,37 @@ export declare class ReachabilitySessionService {
     listP2PSessions(nodeId: string): Promise<P2PSessionList>;
     addP2PCandidates(nodeId: string, sessionId: string, request: P2PCandidateUpdateRequest): Promise<P2PSession>;
     createRelaySession(nodeId: string, request: RelaySessionRequest): Promise<RelaySession>;
+    /**
+     * 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.
+     */
+    private mutateNodeMetadata;
+    /**
+     * 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).
+     */
+    private resolveDataPlaneSecret;
     private loadNodeRouteSource;
     private readActiveP2PSessions;
     private p2pSessionLimits;
     private resolveP2PSessionLimits;
     private appendSession;
+    private readP2PSession;
     private loadP2PSession;
     private assertP2PSessionActive;
     private isP2PSessionActive;
     private normalizeP2PCandidates;
 }
+export declare class InvalidP2PSessionRequestError extends Error {
+}
 export declare class InvalidRelaySessionRequestError extends Error {
 }
+export declare class NodeMetadataConflictError extends Error {
+}
 export declare class NodeRouteSourceNotFoundError extends Error {
 }
 export declare class P2PActiveSessionLimitExceededError extends Error {