@undefineds.co/xpod 0.4.15 → 0.4.16

package/dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld

@@ -4,10 +4,43 @@
   ],
   "@id": "npmd:@undefineds.co/xpod",
   "components": [
+    {
+      "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions",
+      "@type": "AbstractClass",
+      "requireElement": "P2PDataPlaneSecurityOptions",
+      "comment": "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.",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions__member_role",
+          "memberFieldName": "role"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions__member_sessionId",
+          "memberFieldName": "sessionId"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions__member_secret",
+          "memberFieldName": "secret"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions__member_resolveSessionSecret",
+          "memberFieldName": "resolveSessionSecret"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions__member_handshakeTimeoutMs",
+          "memberFieldName": "handshakeTimeoutMs"
+        }
+      ],
+      "constructorArguments": []
+    },
     {
       "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneTransportOptions",
       "@type": "AbstractClass",
       "requireElement": "TcpP2PDataPlaneTransportOptions",
+      "extends": [
+        "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions"
+      ],
       "parameters": [],
       "memberFields": [
         {
@@ -29,6 +62,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneTransportOptions__member_randomId",
           "memberFieldName": "randomId"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneTransportOptions__member_secure",
+          "memberFieldName": "secure"
         }
       ],
       "constructorArguments": []
@@ -53,6 +90,9 @@
       "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneServerOptions",
       "@type": "AbstractClass",
       "requireElement": "TcpP2PDataPlaneServerOptions",
+      "extends": [
+        "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions"
+      ],
       "parameters": [],
       "memberFields": [
         {
@@ -62,6 +102,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneServerOptions__member_host",
           "memberFieldName": "host"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneServerOptions__member_secure",
+          "memberFieldName": "secure"
         }
       ],
       "constructorArguments": []
@@ -91,6 +135,9 @@
       "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneSocketOptions",
       "@type": "AbstractClass",
       "requireElement": "TcpP2PDataPlaneSocketOptions",
+      "extends": [
+        "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions"
+      ],
       "parameters": [],
       "memberFields": [
         {
@@ -100,6 +147,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneSocketOptions__member_handler",
           "memberFieldName": "handler"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneSocketOptions__member_secure",
+          "memberFieldName": "secure"
         }
       ],
       "constructorArguments": []

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

@@ -2,6 +2,7 @@ import { type Socket } from 'node:net';
 import type { AccessRoute, P2PCandidateRole, P2PSession, P2PTransportCandidate } from './types';
 import type { P2PSignalingClient } from './P2PSignalingClient';
 import type { P2PDataPlaneHandler } from './P2PDataPlane';
+import type { P2PDataPlaneSecurityOptions } from './TcpP2PDataPlaneTransport';
 import { type TcpP2PDataPlaneSocketHandle, type TcpP2PDataPlaneTransport, type TcpHolePunchPlan, type TcpHolePunchPlanOptions } from './TcpP2PDataPlaneTransport';
 export declare const RAW_TCP_HOLE_PUNCH_TRANSPORT: "raw-tcp-hole-punch";
 export declare const RAW_TCP_HOLE_PUNCH_CAPABILITY: "tcp-punch";
@@ -19,6 +20,8 @@ export interface CreateRawTcpHolePunchCandidatesOptions {
 export interface SignaledRawTcpP2PSessionOptions {
     signaling: P2PSignalingClient;
     clientId: string;
+    /** Overrides the generated per-session data plane secret (tests only). */
+    dataPlaneSecret?: string;
     host?: string;
     address?: string;
     capabilities?: string[];
@@ -33,6 +36,8 @@ export interface SignaledRawTcpP2PSession {
     plan: TcpHolePunchPlan;
     localCandidates: P2PTransportCandidate[];
     rawTcpRoute?: AccessRoute;
+    /** Secret both peers use to seal the data plane (audit N03). */
+    dataPlaneSecret: string;
 }
 export interface AnswerPendingRawTcpP2PSessionsOnceOptions {
     signaling: P2PSignalingClient;
@@ -53,6 +58,8 @@ export interface WaitForRawTcpRemoteCandidatesOptions {
     timeoutMs?: number;
 }
 export interface ConnectRawTcpP2PTransportOptions {
+    /** Data plane authentication; the signaled path always sets it (audit N03). */
+    secure?: P2PDataPlaneSecurityOptions;
     localCandidates: P2PTransportCandidate[];
     remoteCandidates: P2PTransportCandidate[];
     connectTimeoutMs?: number;

package/dist/edge/reachability/TcpP2PSignalingSession.js

@@ -13,6 +13,7 @@ exports.filterRawTcpRemoteCandidates = filterRawTcpRemoteCandidates;
 exports.selectRawTcpP2PRoute = selectRawTcpP2PRoute;
 exports.isRawTcpHolePunchCandidate = isRawTcpHolePunchCandidate;
 const node_net_1 = require("node:net");
+const P2PDataPlaneCrypto_1 = require("./P2PDataPlaneCrypto");
 const TcpP2PDataPlaneTransport_1 = require("./TcpP2PDataPlaneTransport");
 exports.RAW_TCP_HOLE_PUNCH_TRANSPORT = 'raw-tcp-hole-punch';
 exports.RAW_TCP_HOLE_PUNCH_CAPABILITY = 'tcp-punch';
@@ -61,6 +62,7 @@ async function createSignaledRawTcpP2PSession(options) {
         plan,
         candidateIdPrefix: options.candidateIdPrefix,
     });
+    const dataPlaneSecret = options.dataPlaneSecret ?? (0, P2PDataPlaneCrypto_1.createDataPlaneSecret)();
     const request = {
         clientId: options.clientId,
         capabilities: uniqueStrings([
@@ -68,6 +70,7 @@ async function createSignaledRawTcpP2PSession(options) {
             ...(options.capabilities ?? []),
         ]),
         candidates: localCandidates,
+        dataPlaneSecret,
     };
     const session = await options.signaling.createP2PSession(request);
     const effectiveLocalCandidates = localRawTcpCandidatesFromSessionOrFallback(session, localCandidates, 'client', options.clientId, plan.bucket);
@@ -76,6 +79,9 @@ async function createSignaledRawTcpP2PSession(options) {
         plan,
         localCandidates: effectiveLocalCandidates,
         rawTcpRoute: selectRawTcpP2PRoute(session.nodeCandidates),
+        // The API echoes the session back; a node that stripped the secret would otherwise let the
+        // client believe the plane is sealed while the node cannot open a single frame.
+        dataPlaneSecret: session.dataPlaneSecret ?? dataPlaneSecret,
     };
 }
 async function answerPendingRawTcpP2PSessionsOnce(options) {
@@ -159,7 +165,19 @@ async function acceptSignaledRawTcpP2PConnectionOnce(options) {
                 plan,
                 localCandidates: effectiveLocalCandidates,
                 remoteCandidates,
-                socketHandle: (0, TcpP2PDataPlaneTransport_1.attachTcpP2PDataPlaneSocket)({ socket, handler: options.handler }),
+                socketHandle: (0, TcpP2PDataPlaneTransport_1.attachTcpP2PDataPlaneSocket)({
+                    socket,
+                    handler: options.handler,
+                    ...(answeredSession.dataPlaneSecret
+                        ? {
+                            secure: {
+                                role: 'server',
+                                sessionId: answeredSession.sessionId,
+                                secret: answeredSession.dataPlaneSecret,
+                            },
+                        }
+                        : {}),
+                }),
             };
         }
         catch (error) {
@@ -208,6 +226,11 @@ async function connectSignaledRawTcpP2PTransport(options) {
         nowMs: options.nowMs,
         sleepMs: options.sleepMs,
         connectSocket: options.connectSocket,
+        secure: {
+            role: 'client',
+            sessionId: signaled.session.sessionId,
+            secret: signaled.dataPlaneSecret,
+        },
     });
     return {
         ...signaled,
@@ -222,6 +245,7 @@ async function connectRawTcpP2PTransport(options) {
         remotePort: attempt.remotePort,
         socket,
         timeoutMs: options.timeoutMs,
+        ...(options.secure ? { secure: options.secure } : {}),
     });
 }
 async function connectRawTcpP2PSocket(options) {

package/dist/edge/reachability/TcpP2PSignalingSession.jsonld

@@ -63,6 +63,10 @@
           "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#SignaledRawTcpP2PSessionOptions__member_clientId",
           "memberFieldName": "clientId"
         },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#SignaledRawTcpP2PSessionOptions__member_dataPlaneSecret",
+          "memberFieldName": "dataPlaneSecret"
+        },
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#SignaledRawTcpP2PSessionOptions__member_host",
           "memberFieldName": "host"
@@ -119,6 +123,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#SignaledRawTcpP2PSession__member_rawTcpRoute",
           "memberFieldName": "rawTcpRoute"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#SignaledRawTcpP2PSession__member_dataPlaneSecret",
+          "memberFieldName": "dataPlaneSecret"
         }
       ],
       "constructorArguments": []
@@ -203,6 +211,10 @@
       "requireElement": "ConnectRawTcpP2PTransportOptions",
       "parameters": [],
       "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#ConnectRawTcpP2PTransportOptions__member_secure",
+          "memberFieldName": "secure"
+        },
         {
           "@id": "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld#ConnectRawTcpP2PTransportOptions__member_localCandidates",
           "memberFieldName": "localCandidates"

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

@@ -4,6 +4,7 @@ export * from './ReachabilitySessionService';
 export * from './ManagedRouteSelector';
 export * from './CanonicalFetch';
 export * from './P2PDataPlane';
+export * from './P2PDataPlaneCrypto';
 export * from './P2PSignalingClient';
 export * from './TcpP2PDataPlaneTransport';
 export * from './TcpP2PSignalingSession';

package/dist/edge/reachability/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./ReachabilitySessionService"), exports);
 __exportStar(require("./ManagedRouteSelector"), exports);
 __exportStar(require("./CanonicalFetch"), exports);
 __exportStar(require("./P2PDataPlane"), exports);
+__exportStar(require("./P2PDataPlaneCrypto"), exports);
 __exportStar(require("./P2PSignalingClient"), exports);
 __exportStar(require("./TcpP2PDataPlaneTransport"), exports);
 __exportStar(require("./TcpP2PSignalingSession"), exports);

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

@@ -51,6 +51,12 @@ export interface P2PSessionRequest {
     owner?: P2PSessionOwner;
     capabilities?: string[];
     candidates?: unknown[];
+    /**
+     * Base64 per-session secret for the data plane (audit N03). The creator generates it; the
+     * signaling API is the only channel that carries it, so a network peer that can reach the
+     * punched port still cannot read or forge frames.
+     */
+    dataPlaneSecret?: string;
 }
 export interface P2PSessionOwner {
     type: 'solid';
@@ -94,6 +100,8 @@ export interface P2PSession {
     capabilities: string[];
     candidates: P2PTransportCandidate[];
     limits?: P2PSessionLimits;
+    /** Present for data planes that authenticate and encrypt their frames (audit N03). */
+    dataPlaneSecret?: string;
 }
 export interface P2PSessionList {
     kind: 'p2p';

package/dist/edge/reachability/types.jsonld

@@ -181,6 +181,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/types.jsonld#P2PSessionRequest__member_candidates",
           "memberFieldName": "candidates"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/types.jsonld#P2PSessionRequest__member_dataPlaneSecret",
+          "memberFieldName": "dataPlaneSecret"
         }
       ],
       "constructorArguments": []
@@ -354,6 +358,10 @@
         {
           "@id": "undefineds:dist/edge/reachability/types.jsonld#P2PSession__member_limits",
           "memberFieldName": "limits"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/types.jsonld#P2PSession__member_dataPlaneSecret",
+          "memberFieldName": "dataPlaneSecret"
         }
       ],
       "constructorArguments": []

package/dist/identity/drizzle/EdgeNodeRepository.d.ts

@@ -72,6 +72,18 @@ export declare class EdgeNodeRepository {
         lastConnectivityCheck?: Date;
     } | undefined>;
     mergeNodeMetadata(nodeId: string, patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Compare-and-swap on the whole `metadata` blob.
+     *
+     * Reachability state (sessions, candidates) lives inside that blob, so a read-modify-write
+     * silently drops whatever another writer committed in between — the lost update the audit
+     * calls out as N07. This write only lands when the stored value is still the one the caller
+     * read; `false` means somebody else won and the caller must re-read and re-apply.
+     *
+     * The comparison is on the serialized payload. Two equivalent-but-differently-ordered
+     * payloads therefore fail the swap, which costs a retry but can never lose a write.
+     */
+    updateNodeMetadataAtomic(nodeId: string, expected: Record<string, unknown> | null, next: Record<string, unknown>): Promise<boolean>;
     getNodeMetadata(nodeId: string): Promise<{
         nodeId: string;
         metadata: Record<string, unknown> | null;

package/dist/identity/drizzle/EdgeNodeRepository.js

@@ -152,6 +152,43 @@ class EdgeNodeRepository {
       WHERE id = ${nodeId}
     `);
     }
+    /**
+     * Compare-and-swap on the whole `metadata` blob.
+     *
+     * Reachability state (sessions, candidates) lives inside that blob, so a read-modify-write
+     * silently drops whatever another writer committed in between — the lost update the audit
+     * calls out as N07. This write only lands when the stored value is still the one the caller
+     * read; `false` means somebody else won and the caller must re-read and re-apply.
+     *
+     * The comparison is on the serialized payload. Two equivalent-but-differently-ordered
+     * payloads therefore fail the swap, which costs a retry but can never lose a write.
+     */
+    async updateNodeMetadataAtomic(nodeId, expected, next) {
+        await this.ready;
+        const payload = JSON.stringify(next);
+        const expectedPayload = expected === null ? null : JSON.stringify(expected);
+        const ts = (0, db_1.toDbTimestamp)(this.db, new Date());
+        const changed = await (0, db_1.executeStatementWithCount)(this.db, expectedPayload === null
+            ? (0, drizzle_orm_1.sql) `
+          UPDATE cluster_node
+          SET metadata = ${payload},
+              updated_at = ${ts}
+          WHERE id = ${nodeId} AND metadata IS NULL
+        `
+            : (0, drizzle_orm_1.sql) `
+          UPDATE cluster_node
+          SET metadata = ${payload},
+              updated_at = ${ts}
+          WHERE id = ${nodeId} AND metadata = ${expectedPayload}
+        `);
+        if (typeof changed === 'number') {
+            return changed > 0;
+        }
+        // A driver that reports no row count cannot answer "did my write land": verify instead of
+        // assuming, so a lost race is retried rather than reported as success.
+        const stored = await this.getNodeMetadata(nodeId);
+        return JSON.stringify(stored?.metadata ?? null) === payload;
+    }
     async getNodeMetadata(nodeId) {
         await this.ready;
         const result = await (0, db_1.executeQuery)(this.db, (0, drizzle_orm_1.sql) `

package/dist/identity/drizzle/PodInterfaceKeyRepository.d.ts

@@ -16,6 +16,8 @@ export interface PodInterfaceKeyRecord {
 }
 export interface PodInterfaceKeyRepositoryPort {
     read(ownerWebId: string): Promise<PodInterfaceKeyRecord | undefined>;
+    /** Every stored row, for the one-shot migration into the task layer. */
+    list(): Promise<PodInterfaceKeyRecord[]>;
     write(record: Omit<PodInterfaceKeyRecord, 'createdAt' | 'updatedAt'>): Promise<void>;
     remove(ownerWebId: string): Promise<void>;
 }
@@ -27,6 +29,7 @@ export declare class PodInterfaceKeyRepository implements PodInterfaceKeyReposit
     private initError?;
     constructor(db: IdentityDatabase);
     read(ownerWebId: string): Promise<PodInterfaceKeyRecord | undefined>;
+    list(): Promise<PodInterfaceKeyRecord[]>;
     write(record: Omit<PodInterfaceKeyRecord, 'createdAt' | 'updatedAt'>): Promise<void>;
     remove(ownerWebId: string): Promise<void>;
     private ensureReady;

package/dist/identity/drizzle/PodInterfaceKeyRepository.js

@@ -35,6 +35,17 @@ class PodInterfaceKeyRepository {
             updatedAt: (0, db_1.fromDbTimestamp)(row.updatedAt) ?? new Date(),
         };
     }
+    async list() {
+        await this.ensureReady();
+        const rows = await this.db.select().from(this.schema.podInterfaceKeys);
+        return rows.map((row) => ({
+            ownerWebId: String(row.ownerWebId),
+            clientId: String(row.clientId),
+            sealedSecret: String(row.sealedSecret),
+            createdAt: (0, db_1.fromDbTimestamp)(row.createdAt) ?? new Date(),
+            updatedAt: (0, db_1.fromDbTimestamp)(row.updatedAt) ?? new Date(),
+        }));
+    }
     async write(record) {
         await this.ensureReady();
         const existing = await this.read(record.ownerWebId);

package/dist/identity/drizzle/db.d.ts

@@ -57,6 +57,14 @@ export declare function executeQuery<T = Record<string, unknown>>(db: IdentityDa
  * Works uniformly across PostgreSQL and SQLite.
  */
 export declare function executeStatement(db: IdentityDatabase, query: SQL): Promise<void>;
+/**
+ * Execute a statement and report how many rows it changed.
+ *
+ * Optimistic concurrency (compare-and-swap) has to tell an applied write from a rejected one,
+ * which `executeStatement` throws away. Returns `undefined` when the driver reports no count,
+ * in which case callers must verify the stored value themselves instead of assuming success.
+ */
+export declare function executeStatementWithCount(db: IdentityDatabase, query: SQL): Promise<number | undefined>;
 export declare function executePostgresLockedStatements(db: IdentityDatabase, lockKey: number, statements: string[]): Promise<void>;
 /**
  * Creates the per-owner interface-key table.

package/dist/identity/drizzle/db.js

@@ -32,6 +32,7 @@ exports.closeAllIdentityConnections = closeAllIdentityConnections;
 exports.isDatabaseSqlite = isDatabaseSqlite;
 exports.executeQuery = executeQuery;
 exports.executeStatement = executeStatement;
+exports.executeStatementWithCount = executeStatementWithCount;
 exports.executePostgresLockedStatements = executePostgresLockedStatements;
 exports.ensurePodInterfaceKeyTable = ensurePodInterfaceKeyTable;
 exports.ensureCloudClusterTables = ensureCloudClusterTables;
@@ -229,6 +230,22 @@ async function executeStatement(db, query) {
     // PostgreSQL: db.execute() works for statements too
     await db.execute(query);
 }
+/**
+ * Execute a statement and report how many rows it changed.
+ *
+ * Optimistic concurrency (compare-and-swap) has to tell an applied write from a rejected one,
+ * which `executeStatement` throws away. Returns `undefined` when the driver reports no count,
+ * in which case callers must verify the stored value themselves instead of assuming success.
+ */
+async function executeStatementWithCount(db, query) {
+    await ensureDatabaseReady(db);
+    if (isDatabaseSqlite(db)) {
+        const result = db.run(query);
+        return typeof result?.changes === 'number' ? result.changes : undefined;
+    }
+    const result = await db.execute(query);
+    return typeof result?.rowCount === 'number' ? result.rowCount : undefined;
+}
 async function executePostgresLockedStatements(db, lockKey, statements) {
     await ensureDatabaseReady(db);
     if (isDatabaseSqlite(db)) {

package/dist/runtime/GatewayAdminProxyAuth.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingHttpHeaders, OutgoingHttpHeaders } from 'node:http';
+import type { IncomingHttpHeaders } from 'node:http';
 export declare const GATEWAY_ADMIN_PROXY_LOOPBACK_HEADER = "x-xpod-admin-proxy-loopback";
 export declare const GATEWAY_ADMIN_PROXY_TIMESTAMP_HEADER = "x-xpod-admin-proxy-timestamp";
 export declare const GATEWAY_ADMIN_PROXY_SIGNATURE_HEADER = "x-xpod-admin-proxy-signature";
@@ -20,7 +20,7 @@ export interface GatewayAdminProxyMarkerVerification {
     nonce?: string;
     reason?: string;
 }
-export declare function createGatewayAdminProxyHeaders(input: GatewayAdminProxyMarkerInput): OutgoingHttpHeaders;
+export declare function createGatewayAdminProxyHeaders(input: GatewayAdminProxyMarkerInput): Record<string, string>;
 export declare function stripGatewayAdminProxyHeaders(headers: IncomingHttpHeaders): void;
 export declare function isLoopbackRemoteAddress(remoteAddress: string | undefined): boolean;
 export declare function verifyGatewayAdminProxyHeaders(input: {

package/dist/runtime/Proxy.js

@@ -594,8 +594,11 @@ class GatewayProxy {
             // Status is the entry probe every client uses, and it carries no secrets.
             if (pathname === '/service/status') {
                 const status = this.supervisor.getAllStatus();
-                const cssReady = await this.isCssReady();
-                const code = cssReady ? 200 : 503;
+                // Readiness must cover every supervised child, not just CSS: a gateway whose API child
+                // crashed and gave up used to answer 200 here for hours while /api/* returned 502 (N20).
+                const servicesReady = this.supervisor.isReady();
+                const cssReady = servicesReady && await this.isCssReady();
+                const code = servicesReady && cssReady ? 200 : 503;
                 res.writeHead(code, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify(status));
                 return;

package/dist/runtime/css-process.d.ts

@@ -6,13 +6,13 @@ import type { AuthMode } from '../authorization/AuthMode';
  * The legacy CSS child process path injects it through a generated
  * Components.js config instead of CSS_* env aliases.
  */
-export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: NodeJS.ProcessEnv, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
+export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: Record<string, string | undefined>, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
 export declare function createCssChildRuntimeConfig(options: {
     configPath: string;
     runtimeRoot: string;
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): {
     configPath: string;
     cwd?: string;
@@ -36,5 +36,5 @@ export declare function buildApiChildEnv(options: {
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
     gatewayAdminProxyAuthSecret?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): Record<string, string>;

package/dist/runtime/index.d.ts

@@ -10,7 +10,13 @@ export { createOpenAuthContext, registerManagedRuntimeServices, startApiRuntime,
 export type { RuntimeServices } from './lifecycle';
 export { GatewayProxy } from './Proxy';
 export { createGatewayAdminProxyAuthSecret } from './GatewayAdminProxyAuth';
-export { findGatewayIngressPort, getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, requireFreePortForWildcard } from './port-finder';
+export { findGatewayIngressPort, getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, isFreePortForWildcard, requireFreePortForWildcard } from './port-finder';
+export { assertUsableIngressPort, parseExplicitIngressPort, resolveIngressPort, IngressPortConflictError } from './ingress-port';
+export type { IngressPortDeclaration, IngressPortResolution, IngressPortSource } from './ingress-port';
+export { identifyIngressPortOccupants } from './ingress-occupant';
+export { getUnreservedEphemeralPort, listenOnUnreservedPort, PORT_RESERVATION_DIR_ENV, RESERVED_PORTS_ENV, portReservation, portReservationDir, readPortReservations, releasePort, reservePort, reservedPorts, } from './port-reservations';
+export type { PortReservation } from './port-reservations';
+export type { IngressPortOccupant, IngressPortOccupants } from './ingress-occupant';
 export { ensureTrailingSlash, INVALID_CONFIGURATION_PREFIX, validateBaseUrl } from './base-url';
 export type { ValidateBaseUrlOptions } from './base-url';
 export { applyEnv, loadEnvFile } from './env-utils';

package/dist/runtime/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.requireFreePortForWildcard = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.findGatewayIngressPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.reservedPorts = exports.reservePort = exports.releasePort = exports.readPortReservations = exports.portReservationDir = exports.portReservation = exports.RESERVED_PORTS_ENV = exports.PORT_RESERVATION_DIR_ENV = exports.listenOnUnreservedPort = exports.getUnreservedEphemeralPort = exports.identifyIngressPortOccupants = exports.IngressPortConflictError = exports.resolveIngressPort = exports.parseExplicitIngressPort = exports.assertUsableIngressPort = exports.requireFreePortForWildcard = exports.isFreePortForWildcard = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.findGatewayIngressPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = void 0;
 require("./configure-drizzle-solid");
 var package_root_1 = require("./package-root");
 Object.defineProperty(exports, "PACKAGE_ROOT", { enumerable: true, get: function () { return package_root_1.PACKAGE_ROOT; } });
@@ -34,7 +35,26 @@ Object.defineProperty(exports, "findGatewayIngressPort", { enumerable: true, get
 Object.defineProperty(exports, "getEphemeralLoopbackPort", { enumerable: true, get: function () { return port_finder_1.getEphemeralLoopbackPort; } });
 Object.defineProperty(exports, "getFreePort", { enumerable: true, get: function () { return port_finder_1.getFreePort; } });
 Object.defineProperty(exports, "getFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.getFreePortForWildcard; } });
+Object.defineProperty(exports, "isFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.isFreePortForWildcard; } });
 Object.defineProperty(exports, "requireFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.requireFreePortForWildcard; } });
+var ingress_port_1 = require("./ingress-port");
+Object.defineProperty(exports, "assertUsableIngressPort", { enumerable: true, get: function () { return ingress_port_1.assertUsableIngressPort; } });
+Object.defineProperty(exports, "parseExplicitIngressPort", { enumerable: true, get: function () { return ingress_port_1.parseExplicitIngressPort; } });
+Object.defineProperty(exports, "resolveIngressPort", { enumerable: true, get: function () { return ingress_port_1.resolveIngressPort; } });
+Object.defineProperty(exports, "IngressPortConflictError", { enumerable: true, get: function () { return ingress_port_1.IngressPortConflictError; } });
+var ingress_occupant_1 = require("./ingress-occupant");
+Object.defineProperty(exports, "identifyIngressPortOccupants", { enumerable: true, get: function () { return ingress_occupant_1.identifyIngressPortOccupants; } });
+var port_reservations_1 = require("./port-reservations");
+Object.defineProperty(exports, "getUnreservedEphemeralPort", { enumerable: true, get: function () { return port_reservations_1.getUnreservedEphemeralPort; } });
+Object.defineProperty(exports, "listenOnUnreservedPort", { enumerable: true, get: function () { return port_reservations_1.listenOnUnreservedPort; } });
+Object.defineProperty(exports, "PORT_RESERVATION_DIR_ENV", { enumerable: true, get: function () { return port_reservations_1.PORT_RESERVATION_DIR_ENV; } });
+Object.defineProperty(exports, "RESERVED_PORTS_ENV", { enumerable: true, get: function () { return port_reservations_1.RESERVED_PORTS_ENV; } });
+Object.defineProperty(exports, "portReservation", { enumerable: true, get: function () { return port_reservations_1.portReservation; } });
+Object.defineProperty(exports, "portReservationDir", { enumerable: true, get: function () { return port_reservations_1.portReservationDir; } });
+Object.defineProperty(exports, "readPortReservations", { enumerable: true, get: function () { return port_reservations_1.readPortReservations; } });
+Object.defineProperty(exports, "releasePort", { enumerable: true, get: function () { return port_reservations_1.releasePort; } });
+Object.defineProperty(exports, "reservePort", { enumerable: true, get: function () { return port_reservations_1.reservePort; } });
+Object.defineProperty(exports, "reservedPorts", { enumerable: true, get: function () { return port_reservations_1.reservedPorts; } });
 var base_url_1 = require("./base-url");
 Object.defineProperty(exports, "ensureTrailingSlash", { enumerable: true, get: function () { return base_url_1.ensureTrailingSlash; } });
 Object.defineProperty(exports, "INVALID_CONFIGURATION_PREFIX", { enumerable: true, get: function () { return base_url_1.INVALID_CONFIGURATION_PREFIX; } });

package/dist/runtime/ingress-occupant.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Who holds a port.
+ *
+ * A tunnel console forwards to a number, not to a process: if something else already listens
+ * there, binding "somewhere else" would make the tunnel reach that other process, and killing
+ * it is not this runtime's decision to make. So the only thing this module does is *name* the
+ * occupant (pid, command line, cwd, start time) so a refused start points at a culprit instead
+ * of at a number. Nothing here ever signals a process.
+ */
+export interface IngressPortOccupant {
+    pid: number;
+    /** Full command line when it could be read. */
+    command: string;
+    cwd?: string;
+    startedAt?: string;
+}
+export interface IngressPortOccupants {
+    port: number;
+    occupants: IngressPortOccupant[];
+    /**
+     * One line naming every occupant, for an error message. When nothing can be identified it
+     * says so explicitly: "taken by something we cannot name" is a different fact from "free".
+     */
+    description: string;
+}
+export interface IdentifyOccupantsDeps {
+    /** Runs a command and returns stdout. Injected in tests. */
+    exec?: (file: string, args: readonly string[]) => string;
+}
+/**
+ * Names every process listening on the port.
+ *
+ * `lsof` is the portable answer on macOS and most Linux images; `ss` covers Linux hosts
+ * without lsof. When neither is available the answer is "an unidentified listener", never a
+ * silent success.
+ */
+export declare function identifyIngressPortOccupants(port: number, deps?: IdentifyOccupantsDeps): IngressPortOccupants;
+/** One line for an operator: pid, command, cwd and start time of everything on the port. */
+export declare function describeOccupants(port: number, occupants: readonly IngressPortOccupant[], probeFailure?: string): string;