feat(device-edge): add fail-closed ingress admission

device-plane/deployment/device-edge-admission-gate-v1.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": "nodedc.device-edge.admission-gate.v1",
+  "mode": "single-nic-ipvlan-b2-relay-only",
+  "runtimeHost": "ndcmini12",
+  "component": "device-edge",
+  "selectedServices": [
+    "device-edge-relay"
+  ],
+  "preservedServices": [
+    "device-edge-backhaul",
+    "tailnet"
+  ],
+  "composeProject": "nodedc-device-edge",
+  "composeFiles": [
+    "docker-compose.device-edge.yml",
+    "docker-compose.device-edge.ingress.yml"
+  ],
+  "parentInterface": "enp1s0f0",
+  "lanSubnet": "192.168.68.0/22",
+  "lanGateway": "192.168.68.1",
+  "ingressIpv4": "192.168.71.253",
+  "ingressIpv4Approval": "approved-outside-dhcp-pool",
+  "ingressNetwork": "nodedc-device-edge-ingress",
+  "deviceTcpListen": "192.168.71.253:9921",
+  "hostPortPublication": "disabled",
+  "healthPublication": "disabled",
+  "privateUpstream": "device-edge-backhaul:19921",
+  "sourceAdmission": "public-ipv4-only",
+  "maxTrackedSourceAddresses": 2048,
+  "maxBytesPerDirection": 262144,
+  "protocolInspection": "gateway-owned",
+  "identityTrust": "claimed-not-ownership-proof",
+  "discoveryLifecycle": "quarantine",
+  "commandTransport": "disabled",
+  "gelios": "untouched",
+  "amneziaHostFullTunnel": "preserved",
+  "routerNatFirewall": "separate-manual-gate",
+  "rollback": "restore-reviewed-ipvlan-predecessor-without-network-or-router-mutation"
+}

device-plane/docker-compose.device-edge.ingress.yml

@@ -9,6 +9,9 @@ services:
       DEVICE_EDGE_RELAY_MAX_SESSIONS: "100"
       DEVICE_EDGE_RELAY_MAX_SESSIONS_PER_ADDRESS: "10"
       DEVICE_EDGE_RELAY_MAX_CONNECTIONS_PER_MINUTE_PER_ADDRESS: "30"
+      DEVICE_EDGE_RELAY_SOURCE_POLICY: public-ipv4-only
+      DEVICE_EDGE_RELAY_MAX_TRACKED_SOURCE_ADDRESSES: "2048"
+      DEVICE_EDGE_RELAY_MAX_BYTES_PER_DIRECTION: "262144"
       DEVICE_EDGE_RELAY_SESSION_TIMEOUT_MS: "10000"
     networks:
       device-edge-private:

device-plane/docker-compose.device-edge.yml

@@ -18,6 +18,8 @@ services:
       DEVICE_EDGE_RELAY_MAX_SESSIONS: "100"
       DEVICE_EDGE_RELAY_MAX_SESSIONS_PER_ADDRESS: "10"
       DEVICE_EDGE_RELAY_MAX_CONNECTIONS_PER_MINUTE_PER_ADDRESS: "30"
+      DEVICE_EDGE_RELAY_MAX_TRACKED_SOURCE_ADDRESSES: "2048"
+      DEVICE_EDGE_RELAY_MAX_BYTES_PER_DIRECTION: "262144"
       DEVICE_EDGE_RELAY_SESSION_TIMEOUT_MS: "10000"
     networks:
       device-edge-private: {}

device-plane/docs/IMPLEMENTATION_BASELINE.md

@@ -108,9 +108,10 @@ does not build, restart, recreate or remove any service.
 
 ## Network boundary
 
-The accepted foundation publishes no device port. The reviewed pilot transition
-publishes `9921/TCP` from Device Gateway after a port-collision check and keeps
-health endpoints loopback-only.
+The accepted Synology foundation publishes no device port. Device Gateway's
+raw B2 listener is reachable only through `127.0.0.1:9921`; its health
+endpoints are loopback-only. The only planned external raw-TCP termination is
+the dedicated Mini Edge Relay described below.
 
 `device.nodedc.ru` is a DNS name, not an HTTP/TCP mode. The same name may later
 serve an HTTPS Control API on 443 and the B2 raw TCP protocol on 9921.
@@ -129,7 +130,19 @@ target removes even that host publication: health remains container-internal,
 the relay stays on the `internal: true` private bridge for backhaul, and a
 second IPvlan L2 attachment gives only the relay a LAN-routable address for
 `9921/TCP`. The relay has bounded global/per-address sessions and connection
-rate, emits no bytes of its own and does not inspect device payloads.
+rate, a bounded source-rate table and a per-direction byte budget. It emits no
+bytes of its own and does not inspect device payloads.
+
+The admission-gate transition is deliberately fail-closed at the relay: an
+ingress instance accepts only a syntactically public IPv4 source, limits its
+in-memory source table to 2,048 addresses and closes either direction after
+262,144 bytes. Private, loopback, link-local, carrier-grade NAT, multicast,
+reserved and documentation addresses are rejected before an upstream connection
+is made. This is a connection-admission and resource-boundary control, not a
+claim that Docker IPvlan traffic is filtered by a host firewall. A raw B2
+protocol has no TLS client identity and cellular devices do not offer a stable
+source-IP allowlist, so a router/NAT mapping remains prohibited until its
+separate exposure and abuse controls are reviewed.
 
 IPvlan deliberately reuses the Mini's one physical parent `enp1s0f0`; a second
 Ethernet adapter is not required. The host keeps `192.168.68.54/22` and the
@@ -138,8 +151,8 @@ IPv4 and default route through `192.168.68.1`, while its private connected route
 continues to reach `device-edge-backhaul:19921`. No Docker host `ports:` entry,
 host-network mode, privileged container or VPN teardown is allowed.
 
-Enabling ingress is a separate reviewed operation and requires all of the
-following evidence:
+Enabling public ingress is a separate reviewed operation and requires all of
+the following evidence:
 
 1. A distinct, no-shell Synology SSH account and key whose sole permitted open
    target is `127.0.0.1:9921`; host-key pinning and a persistent, monitored
@@ -147,9 +160,10 @@ following evidence:
 2. A private backhaul sidecar/network; the raw listener may forward only to
    that tunnel. The Core token and all Core/Database secrets remain on
    Synology.
-3. Router evidence proving the fixed relay IPv4 is outside DHCP, followed by a
-   manual router/NAT rule mapping only TCP `9921` to that IPv4. The artifact
+3. Router evidence proving the fixed relay IPv4 is outside DHCP. The artifact
    cannot choose an address and never changes router, firewall or DHCP state.
+   A manual router/NAT rule is a later independent approval, after the relay's
+   admission gate and external-exposure runbook have been accepted.
 4. The host full-tunnel VPN remains active. Before production activation, the
    exact single-NIC IPvlan design must pass duplicate-address detection,
    gateway reachability, external return-path and private-backhaul checks.
@@ -251,12 +265,13 @@ raw TCP remain forbidden until separate reviewed acceptance slices.
 2. Build the deterministic `component=device-edge` artifact, promote the
    root-owned Edge runner and review its `plan`. The Synology runner and inbox
    are not used for this host.
-3. Apply only `device-edge-relay`; prove exact IPvlan runtime, no host ports,
-   internal health, private backhaul reachability, unchanged backhaul/tailnet
-   identities and preserved Amnezia routes. Automatic rollback restores the
-   predecessor relay and removes the unused ingress network.
-4. Independently add the single router/NAT rule for TCP `9921` only and verify
-   that Synology still exposes no public device port.
+3. Apply the admission-gate update only to `device-edge-relay`; prove exact
+   IPvlan runtime, no host ports, `public-ipv4-only` admission, byte/source
+   limits, internal health, private backhaul reachability, unchanged
+   backhaul/tailnet identities and preserved Amnezia routes. Automatic rollback
+   restores the reviewed IPvlan predecessor and leaves router state unchanged.
+4. Independently review and add the single router/NAT rule for TCP `9921` only,
+   then verify that Synology still exposes no public device port.
 5. Add the NDC route to one approved B2 free server slot while preserving
    Gelios, then prove HEADER/discovery/PACKAGE acknowledgement. Claim and tenant
    assignment remain a later explicit platform-admin operation.

device-plane/services/device-edge-relay/src/runtime.mjs

@@ -11,9 +11,10 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
   let totalForwarded = 0;
 
   const tcpServer = createTcpServer({ allowHalfOpen: true }, (socket) => {
-    const remoteAddress = normalizeRemoteAddress(socket.remoteAddress);
+    const remoteAddress = config.resolveRemoteAddress(socket.remoteAddress);
     if (
-      sessions.size >= config.maxConcurrentSessions
+      !allowsSource(remoteAddress)
+      || sessions.size >= config.maxConcurrentSessions
       || currentAddressSessions(remoteAddress) >= config.maxSessionsPerAddress
       || !consumeConnectionPermit(remoteAddress)
     ) {
@@ -28,6 +29,8 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
       upstream: null,
       closed: false,
       forwarded: false,
+      inboundBytes: 0,
+      outboundBytes: 0,
     };
     sessions.set(socket, session);
     incrementAddressSessions(remoteAddress);
@@ -39,6 +42,12 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
     socket.on("timeout", () => rejectSession(session));
     socket.on("close", () => closeSession(session));
     socket.on("error", () => rejectSession(session));
+    socket.on("data", (chunk) => {
+      session.inboundBytes += chunk.length;
+      if (session.inboundBytes > config.maxBytesPerDirection) {
+        rejectSession(session);
+      }
+    });
 
     const upstream = connect({
       host: config.upstreamHost,
@@ -61,6 +70,12 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
     upstream.on("timeout", () => rejectSession(session));
     upstream.on("error", () => rejectSession(session));
     upstream.on("close", () => closeSession(session));
+    upstream.on("data", (chunk) => {
+      session.outboundBytes += chunk.length;
+      if (session.outboundBytes > config.maxBytesPerDirection) {
+        rejectSession(session);
+      }
+    });
   });
 
   const healthServer = createHttpServer((request, response) => {
@@ -79,6 +94,7 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
       ingress: config.ingressEnabled ? "relay-only" : "disabled",
       protocolInspection: "disabled",
       commandTransport: "disabled",
+      sourceAdmission: config.sourcePolicy,
       sessions: {
         active: sessions.size,
         accepted: totalAccepted,
@@ -115,6 +131,7 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
         ingress: config.ingressEnabled ? "relay-only" : "disabled",
         protocolInspection: "disabled",
         commandTransport: "disabled",
+        sourceAdmission: config.sourcePolicy,
       };
     },
   };
@@ -141,8 +158,16 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
 
   function consumeConnectionPermit(remoteAddress) {
     const nowMs = config.now().getTime();
+    for (const [address, window] of connectionWindows) {
+      if (nowMs - window.startedAt >= 60_000) {
+        connectionWindows.delete(address);
+      }
+    }
     const current = connectionWindows.get(remoteAddress);
     if (!current || nowMs - current.startedAt >= 60_000) {
+      if (connectionWindows.size >= config.maxTrackedSourceAddresses) {
+        return false;
+      }
       connectionWindows.set(remoteAddress, { startedAt: nowMs, count: 1 });
       return true;
     }
@@ -151,6 +176,11 @@ export function createDeviceEdgeRelayRuntime(options = {}) {
     return true;
   }
 
+  function allowsSource(remoteAddress) {
+    if (config.sourcePolicy === "any") return true;
+    return isPublicIpv4Address(remoteAddress);
+  }
+
   function rejectSession(session) {
     if (!session.closed) totalRejected += 1;
     session.socket.destroy();
@@ -219,6 +249,24 @@ function normalizeConfig(input) {
       10000,
       "device_edge_relay_connection_rate_invalid",
     ),
+    maxTrackedSourceAddresses: parseInteger(
+      input.maxTrackedSourceAddresses,
+      2048,
+      1,
+      65_536,
+      "device_edge_relay_source_table_limit_invalid",
+    ),
+    maxBytesPerDirection: parseInteger(
+      input.maxBytesPerDirection,
+      262_144,
+      1_024,
+      16 * 1024 * 1024,
+      "device_edge_relay_byte_limit_invalid",
+    ),
+    sourcePolicy: normalizeSourcePolicy(input.sourcePolicy, ingressEnabled),
+    resolveRemoteAddress: typeof input.resolveRemoteAddress === "function"
+      ? input.resolveRemoteAddress
+      : normalizeRemoteAddress,
     sessionTimeoutMs: parseInteger(
       input.sessionTimeoutMs,
       10000,
@@ -269,6 +317,48 @@ function normalizeRemoteAddress(value) {
   return normalized.slice(0, 64) || "unknown";
 }
 
+function normalizeSourcePolicy(value, ingressEnabled) {
+  const fallback = ingressEnabled ? "public-ipv4-only" : "any";
+  const normalized = String(value || fallback).trim().toLowerCase();
+  if (!["any", "public-ipv4-only"].includes(normalized)) {
+    throw new TypeError("device_edge_relay_source_policy_invalid");
+  }
+  if (ingressEnabled && normalized !== "public-ipv4-only") {
+    throw new TypeError("device_edge_relay_ingress_source_policy_invalid");
+  }
+  return normalized;
+}
+
+function isPublicIpv4Address(value) {
+  const normalized = String(value || "").trim().replace(/^::ffff:/i, "");
+  const parts = normalized.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map((part) => Number(part));
+  if (octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  const [first, second, third] = octets;
+  if (
+    first === 0
+    || first === 10
+    || first === 127
+    || first >= 224
+    || (first === 100 && second >= 64 && second <= 127)
+    || (first === 169 && second === 254)
+    || (first === 172 && second >= 16 && second <= 31)
+    || (first === 192 && second === 0 && third === 0)
+    || (first === 192 && second === 0 && third === 2)
+    || (first === 192 && second === 88 && third === 99)
+    || (first === 192 && second === 168)
+    || (first === 198 && (second === 18 || second === 19))
+    || (first === 198 && second === 51 && third === 100)
+    || (first === 203 && second === 0 && third === 113)
+  ) {
+    return false;
+  }
+  return true;
+}
+
 function parseInteger(value, fallback, minimum, maximum, errorCode) {
   const parsed = Number(value ?? fallback);
   if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {

device-plane/services/device-edge-relay/src/server.mjs

@@ -26,6 +26,15 @@ const runtime = createDeviceEdgeRelayRuntime({
     process.env.DEVICE_EDGE_RELAY_MAX_CONNECTIONS_PER_MINUTE_PER_ADDRESS,
     30,
   ),
+  maxTrackedSourceAddresses: parsePositiveInt(
+    process.env.DEVICE_EDGE_RELAY_MAX_TRACKED_SOURCE_ADDRESSES,
+    2048,
+  ),
+  maxBytesPerDirection: parsePositiveInt(
+    process.env.DEVICE_EDGE_RELAY_MAX_BYTES_PER_DIRECTION,
+    262_144,
+  ),
+  sourcePolicy: process.env.DEVICE_EDGE_RELAY_SOURCE_POLICY,
   sessionTimeoutMs: parsePositiveInt(
     process.env.DEVICE_EDGE_RELAY_SESSION_TIMEOUT_MS,
     10000,

device-plane/services/device-edge-relay/test/ingress-source.test.mjs

@@ -38,6 +38,9 @@ test("single-NIC ingress source has no host publication and a fixed ipvlan", asy
     "subnet: 192.168.68.0/22",
     "gateway: 192.168.68.1",
     "gw_priority: 100",
+    "DEVICE_EDGE_RELAY_SOURCE_POLICY: public-ipv4-only",
+    'DEVICE_EDGE_RELAY_MAX_TRACKED_SOURCE_ADDRESSES: "2048"',
+    'DEVICE_EDGE_RELAY_MAX_BYTES_PER_DIRECTION: "262144"',
   ]) {
     assert.ok(ingress.includes(required), `missing ingress boundary: ${required}`);
   }
@@ -82,3 +85,26 @@ test("ingress descriptor keeps address approval and router exposure gated", asyn
   assert.equal(descriptor.amneziaHostFullTunnel, "preserved");
   assert.equal(descriptor.routerNatFirewall, "separate-manual-gate");
 });
+
+test("admission-gate descriptor pins the fail-closed relay boundary", async () => {
+  const descriptor = JSON.parse(await readFile(
+    resolve(
+      devicePlaneRoot,
+      "deployment/device-edge-admission-gate-v1.json",
+    ),
+    "utf8",
+  ));
+
+  assert.equal(
+    descriptor.schemaVersion,
+    "nodedc.device-edge.admission-gate.v1",
+  );
+  assert.equal(descriptor.sourceAdmission, "public-ipv4-only");
+  assert.equal(descriptor.maxTrackedSourceAddresses, 2048);
+  assert.equal(descriptor.maxBytesPerDirection, 262144);
+  assert.equal(descriptor.hostPortPublication, "disabled");
+  assert.equal(descriptor.healthPublication, "disabled");
+  assert.equal(descriptor.commandTransport, "disabled");
+  assert.equal(descriptor.gelios, "untouched");
+  assert.equal(descriptor.routerNatFirewall, "separate-manual-gate");
+});

device-plane/services/device-edge-relay/test/runtime.test.mjs

@@ -31,6 +31,7 @@ test("relay is transparent and never emits its own protocol bytes", async () =>
     tcpPort: 0,
     upstreamHost: "127.0.0.1",
     upstreamPort: upstream.port,
+    resolveRemoteAddress: () => "8.8.8.8",
   });
   const addresses = await runtime.start();
   try {
@@ -47,6 +48,73 @@ test("relay is transparent and never emits its own protocol bytes", async () =>
   }
 });
 
+test("enabled ingress rejects a non-public source before opening upstream", async () => {
+  const upstream = await startEchoServer();
+  const runtime = createDeviceEdgeRelayRuntime({
+    healthPort: 0,
+    ingressEnabled: true,
+    tcpHost: "0.0.0.0",
+    tcpPort: 0,
+    upstreamHost: "127.0.0.1",
+    upstreamPort: upstream.port,
+    resolveRemoteAddress: () => "127.0.0.1",
+  });
+  const addresses = await runtime.start();
+  try {
+    const response = await sendAndCollect(
+      addresses.tcpAddress.port,
+      Buffer.from("denied"),
+    );
+    assert.equal(response.length, 0);
+    assert.equal(runtime.status().totalAccepted, 0);
+    assert.equal(runtime.status().totalForwarded, 0);
+    assert.equal(runtime.status().sourceAdmission, "public-ipv4-only");
+  } finally {
+    await runtime.stop();
+    await closeServer(upstream.server);
+  }
+});
+
+test("relay terminates a byte stream that exceeds its per-direction budget", async () => {
+  const upstream = await startEchoServer();
+  const runtime = createDeviceEdgeRelayRuntime({
+    healthPort: 0,
+    ingressEnabled: true,
+    tcpHost: "0.0.0.0",
+    tcpPort: 0,
+    upstreamHost: "127.0.0.1",
+    upstreamPort: upstream.port,
+    resolveRemoteAddress: () => "8.8.8.8",
+    maxBytesPerDirection: 1024,
+  });
+  const addresses = await runtime.start();
+  try {
+    const response = await sendAndCollect(
+      addresses.tcpAddress.port,
+      Buffer.alloc(1025, 0x5d),
+    );
+    assert.ok(response.length <= 1024);
+    assert.equal(runtime.status().totalForwarded, 1);
+    assert.ok(runtime.status().totalRejected >= 1);
+  } finally {
+    await runtime.stop();
+    await closeServer(upstream.server);
+  }
+});
+
+test("production ingress cannot opt out of public IPv4 admission", () => {
+  assert.throws(
+    () => createDeviceEdgeRelayRuntime({
+      ingressEnabled: true,
+      tcpHost: "0.0.0.0",
+      upstreamHost: "device-edge-backhaul",
+      upstreamPort: 19921,
+      sourcePolicy: "any",
+    }),
+    /device_edge_relay_ingress_source_policy_invalid/,
+  );
+});
+
 test("enabled relay requires a concrete private upstream", () => {
   assert.throws(
     () => createDeviceEdgeRelayRuntime({
@@ -77,14 +145,14 @@ function startEchoServer() {
 }
 
 function sendAndCollect(port, payload) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve) => {
     const chunks = [];
     const socket = connect({ host: "127.0.0.1", port }, () => {
       socket.end(payload);
     });
     socket.on("data", (chunk) => chunks.push(chunk));
     socket.on("close", () => resolve(Buffer.concat(chunks)));
-    socket.on("error", reject);
+    socket.on("error", () => {});
   });
 }