socketduct 0.1.15

package/docs/reverse-gateway.md

@@ -0,0 +1,186 @@
+# Native reverse gateway
+
+Reverse-gateway mode lets a private home Docker host establish the only
+internet-facing connection. Neither CGNAT nor the absence of inbound port
+forwarding prevents Server3 from opening Docker streams through it.
+
+## Roles and public contract
+
+The roles are deliberately separate:
+
+```text
+TensorBuzz / local application on Server3
+  -> ReverseGatewayConnection (verified TLS client, one selected gateway ID)
+  -> reverse hub on Server3
+  <- OutboundReverseGateway (verified TLS client from the home Docker host)
+  -> docker-server:2375 on a private Compose network
+```
+
+- `startReverseGatewayHub(options)` is the reachable Server3 broker. It
+  authenticates both kinds of physical connection, binds gateway IDs to
+  principals, applies `authorizeClientGateway` before selection, authorizes
+  every client/gateway/target tuple, and never connects to a target itself.
+- `OutboundReverseGateway` is one home member. It makes one persistent outbound
+  TLS connection, registers one stable `gatewayId`, applies its own exact local
+  target policy, and multiplexes all accepted target streams on that transport.
+- `ReverseGatewayConnection` is the local application API. It selects one
+  registered gateway during connection readiness and returns ordinary
+  `VirtualSocket` objects from `createConnection()`.
+- `MultiplexedSocketductTransportSet` accepts `endpoint.reverseHub` members, so
+  TensorBuzz can keep its existing health-aware ordered round-robin behavior.
+  A three-member set points all three members at the same hub but selects
+  `o2`, `zyxel`, and `starlink` independently.
+
+Import these APIs from `socketduct/reverse`. The ordinary v2 and v3 edge/relay
+APIs and wire handshakes remain unchanged.
+
+## Protocol decision
+
+Reverse mode is a v3 extension, not a Socketduct tunnel inside another tunnel.
+It retains the 24-byte v3 frame and stream flow control. New connection-control
+frames authenticate registration and selection:
+
+- `GATEWAY_REGISTER` / `GATEWAY_REGISTERED` bind the authenticated outbound
+  transport to a configured gateway ID and monotonically increasing generation.
+- `GATEWAY_SELECT` / `GATEWAY_SELECTED` make client readiness depend on that
+  gateway currently being registered.
+- Client-created streams use odd IDs. The hub maps each one to a hub-created
+even ID on the selected gateway transport. `OPEN`, `OPENED`, `DATA`, `ACK`,
+`WINDOW`, `END`, `CLOSE`, and `RESET` then retain their v3 meanings.
+Gateway-originated `CLOSE` is acknowledged by a client `CLOSE`, after which the
+hub releases both mapped IDs; `RESET` remains immediately terminal.
+Valid `ACK` and `WINDOW` frames already in flight when that close starts are
+consumed by the hub, while late `DATA` or `END` resets only the closing stream.
+
+The hub rejects unknown IDs, registration by the wrong principal, a second
+connection identity claiming the same ID, stale generations, repeated IDs,
+malformed frames, unauthorized routes, and configured limits. A higher
+generation from the same stable connection identity fences its prior transport.
+At the configured identity bound, the oldest disconnected client identity is
+evicted; active owners are never evicted and retain generation fencing.
+The home gateway independently rejects any target outside its local allowlist.
+
+Reverse DATA compression is negotiated as `zstd`. The one DATA-only flag means
+the payload starts with a four-byte uncompressed length followed by one
+independent zstd frame. Sequence, ACK, window, and limit accounting uses raw
+bytes. Compression is adaptive: small or incompressible chunks remain raw.
+Decompression size and expansion are bounded, and outbound DATA chunks use the
+lower of the frame-size and decompressed-size limits. Reverse mode requires Node's
+zstd runtime support and always uses TLS with certificate verification enabled;
+there is no plaintext or `rejectUnauthorized:false` reverse option.
+
+Each peer advertises its receive window during authentication and stream open;
+senders use the smaller local and peer window for stream credit. A graceful hub
+shutdown is transient and reconnects the client and gateway registrations, while
+authentication, authorization, and stale-generation rejections remain terminal.
+
+An application write may be larger than the configured reverse-stream buffer.
+The client admits it in bounded slices no larger than the negotiated peer window
+as acknowledgements release capacity, holding Node's Writable callback while
+backpressure is active. Retained replay bytes therefore stay within both the
+per-stream and per-connection ceilings, and released connection capacity rotates
+among streams with pending writes. The ceilings limit retained flow-control state,
+not the size of one application write.
+
+Compression and decompression use Node's asynchronous native zstd APIs, whose
+work runs in the libuv worker pool across CPU cores. The hub keeps registration
+and stream ownership on one deterministic event loop instead of splitting its
+in-memory gateway registry across independent cluster workers.
+
+## Failure and replay boundary
+
+Gateway registration reconnects with bounded exponential delay and a higher
+generation. An established Docker stream does **not** survive that transport
+loss: the hub resets it with `GATEWAY_DISCONNECTED`, both endpoints release the
+stream, and the gateway destroys its local Docker socket. This is intentional.
+A Docker request whose write reached dockerd but whose response did not reach
+TensorBuzz has an ambiguous outcome and must never be replayed automatically.
+TensorBuzz must reconcile that Docker operation and then create a new stream.
+
+Consequently reverse streams have bounded in-memory flow-control/replay queues
+only for the live transport and report zero spool bytes. They do not persist an
+operation spool across disconnect or process replacement; `recoverConnection()`
+fails explicitly. Ordinary resumable Socketduct sessions retain their existing
+durable spool behavior. This split is the safety boundary between reconnecting
+the gateway registration and replaying privileged Docker operations.
+
+Target bytes already observed by the gateway are ordered before a subsequent
+target-error reset. Stream `END` remains a directional half-close, while protocol
+`CLOSE` retires both virtual-socket directions and releases stream capacity.
+
+## Server3 hub runtime
+
+Run one TLS hub:
+
+```sh
+SOCKETDUCT_MODE=reverse-hub \
+SOCKETDUCT_RELAY_HOST=0.0.0.0 \
+SOCKETDUCT_RELAY_PORT=3100 \
+SOCKETDUCT_TLS_CERT_FILE=/certs/hub.crt \
+SOCKETDUCT_TLS_KEY_FILE=/certs/hub.key \
+SOCKETDUCT_AUTH_TOKENS='home-o2:<secret>,home-zyxel:<secret>,home-starlink:<secret>,tensorbuzz:<secret>' \
+SOCKETDUCT_REVERSE_GATEWAY_BINDINGS='o2:home-o2,zyxel:home-zyxel,starlink:home-starlink' \
+SOCKETDUCT_REVERSE_ROUTES='tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375,tensorbuzz:starlink:docker-server:2375' \
+node src/index.js
+```
+
+Values shown as `<secret>` are placeholders for secret-manager input, not
+literal values. The runtime refuses to start without TLS, credentials,
+bindings, and routes.
+
+## One outbound member per router
+
+Run this once in each existing router-pinned network namespace, changing the
+two stable IDs and credential for the member:
+
+```sh
+SOCKETDUCT_MODE=reverse-gateway \
+SOCKETDUCT_REVERSE_GATEWAY_ID=o2 \
+SOCKETDUCT_REVERSE_CONNECTION_ID=home_o2_gateway_01 \
+SOCKETDUCT_REVERSE_HUB_HOST=server3.example.net \
+SOCKETDUCT_REVERSE_HUB_PORT=3100 \
+SOCKETDUCT_REVERSE_TOKEN='<secret>' \
+SOCKETDUCT_REVERSE_HUB_CA_FILE=/certs/hub-ca.crt \
+SOCKETDUCT_REVERSE_HUB_SERVERNAME=server3.example.net \
+SOCKETDUCT_TARGET_ALLOWLIST=docker-server:2375 \
+node src/index.js
+```
+
+The namespace/default-route configuration remains outside Socketduct. Pin the
+three processes to the routes whose next hops are O2 `192.168.86.1`, Zyxel
+`192.168.86.3`, and Starlink `192.168.86.25`. Socketduct needs no inbound rule
+on any home router. Do not publish port 2375: the gateway resolves
+`docker-server` and reaches plaintext Docker TCP only on their shared private
+Compose network.
+
+## TensorBuzz transport set
+
+```js
+import {MultiplexedSocketductTransportSet} from "socketduct/multiplexed"
+
+const set = new MultiplexedSocketductTransportSet({
+  connectionId: "tensorbuzz_docker_transport_01",
+  gateways: ["o2", "zyxel", "starlink"].map((gatewayId) => ({
+    gatewayId,
+    endpoint: {
+      reverseHub: {
+        host: "127.0.0.1",
+        port: 3100,
+        token: process.env.SOCKETDUCT_TENSORBUZZ_TOKEN
+      },
+      tls: {caFile: "/certs/hub-ca.crt", servername: "server3.example.net"}
+    }
+  }))
+})
+
+const starting = set.start()
+const socket = set.createConnection({host: "docker-server", port: 2375})
+await starting
+```
+
+The socket is returned immediately and waits inside Socketduct until the set
+reaches minimum readiness. New sockets rotate equally across ready members and
+stay on their assigned member. If all members are reconnecting, new sockets wait
+FIFO without selecting a connecting gateway; a recovered member resumes those
+opens. A disconnected member leaves readiness and rejoins after authenticated
+registration; existing streams on it fail for application-level reconciliation.

package/docs/runbooks/jsonl-integrity-rollout.md

@@ -0,0 +1,144 @@
+# Private JSONL-integrity rollout
+
+This runbook applies only to the private Socketduct release and Apoc's three
+gateways. It does not authorize production recreation. The coordinator owns
+independent review, private PR/check monitoring, release, explicit disruption
+approval, production execution and acceptance. Do not publish source, logs,
+images, evidence, credentials or packages publicly; keep `private: true`.
+
+## Evidence is not repair
+
+A disk-full append can leave a prefix. The fix separates that segment unchanged
+before accepting another record; it does not make the prefix valid JSON.
+Archive historical files byte-for-byte outside managed retention in a private
+0700 directory with 0600 files, with hashes, inode/size/offset metadata and the
+exact image/configuration rollback identity. Never truncate, normalize, replace
+newer logs with an older archive, or count skipped parse errors as success.
+Numbered evidence remains subject to ordinary bounded retention.
+
+With one retained file, or an incomplete active file larger than a newly lowered
+limit, preserve the file separately before an operator supplies a clean active
+path. Do not delete evidence simply to resume logging. Fix unsafe 0700/0600 modes
+or ownership without weakening access controls. Missing diagnostic events are
+not replayed; transport data remains governed by the existing tunnel protocol.
+
+## Isolated acceptance, never production disk fill
+
+Run as UID/GID1000 in the canonical development container:
+
+```sh
+npm exec --no -- velocious-test test/unit/logging/structured-logger.test.js
+npm exec --no -- velocious-test test/integration/logging-recovery.test.js
+npm test
+npm run typecheck
+npm run lint
+git diff --check
+```
+
+Run the two focused modules sequentially with the published `@velocious/testing`
+runner. `npm test` is the CI entry point: it discovers untouched legacy modules
+for Node's runner and then invokes the owning runner separately for each migrated
+logger module. `npm test -- --list` prints both selections without running tests.
+Do not run the full suite or shards locally during a correction pass; CI owns
+that coverage. Test cleanup uses the package's supported FIFO `withTestCleanup`.
+
+The process tests create and remove only their own private home subdirectories;
+the canonical `/home/dev` bind persists across child-process exits. They reuse
+the exact filename family and compare retained bytes and inode identity. Other
+tests cover actual permission/rename/create failures, retention 1/2/5 at the
+1024-byte minimum, privacy, live/unknown PID preservation, and an authenticated,
+destination-allowlisted loopback payload round-trip during logger failure.
+
+The Docker coordinator runs both real-fault fixtures against the **exact built
+candidate image**, not a working-source override. Set `IMAGE` to its inspected
+immutable private image ID and `FIXTURE_SOURCE` to the Docker daemon's existing
+canonical checkout `test/fixtures` bind source. The migrated fixtures also need
+the published `@velocious/testing` package: set `TESTING_PACKAGE_SOURCE` to the
+same checkout's registry-installed `node_modules/@velocious/testing` directory
+after normal `npm ci`. The package has no runtime dependencies. Its read-only
+mount is for disposable fault containers only; it stays a dev dependency and
+must not be bundled into production images. Without that additional test-only
+mount, the runtime image's `npm ci --omit=dev` cannot resolve the matcher import.
+The coordinator must account for this changed fixture dependency contract when
+refreshing the image/ENOSPC receipt.
+
+Do not guess a host route or mount credentials, a home directory, or a Docker
+socket into the fault container. Only fixtures and their installed test package
+are mounted; fixture source imports still resolve to the candidate's baked
+`/app/src` code, not a working-source override.
+
+```sh
+: "${IMAGE:?Set the immutable candidate image ID}"
+: "${FIXTURE_SOURCE:?Set the canonical fixture bind source}"
+: "${TESTING_PACKAGE_SOURCE:?Set the installed test-only package bind source}"
+for fixture in enospc-recovery.mjs enospc-matrix.mjs; do
+  docker run --rm --pull=never --network none --user 1000:1000 --read-only \
+    --cap-drop ALL --security-opt no-new-privileges \
+    --memory 256m --pids-limit 32 \
+    --mount "type=bind,source=$FIXTURE_SOURCE,target=/app/test/fixtures,readonly" \
+    --mount "type=bind,source=$TESTING_PACKAGE_SOURCE,target=/app/node_modules/@velocious/testing,readonly" \
+    --tmpfs /fault-space:rw,nosuid,nodev,noexec,size=65536,mode=0700,uid=1000,gid=1000 \
+    --workdir /app --entrypoint node "$IMAGE" "test/fixtures/logging/$fixture" \
+    || exit "$?"
+done
+```
+
+Fixtures refuse to fill any path other than an empty, dedicated 64 KiB Linux
+tmpfs at `/fault-space`. They require actual ENOSPC, nonempty exact short-write
+prefixes, restored filler space, byte-for-byte retained evidence, parseable new
+records, mode/cap/count limits, and once-only sanitized reports. The matrix also
+covers multiple short failures in one logger, several no-byte calls while full,
+retention 1/2/5, low-limit empty-file failures, and a child process that exits
+after a real torn append before a fresh writer resumes. Cleanup removes only
+fixture-owned contents; no sleeps, filesystem mocks, or production writes.
+
+Keep stdout/stderr, exit codes, source hashes, image ID and Node/UID identities
+in restricted private evidence. An unchanged defective image must fail the
+correct-output assertion **after** proving actual ENOSPC; a setup failure is not
+RED. Both candidate fixtures must exit zero. Static/unit passes alone do not
+establish real-filesystem GREEN. The internal `tear` mode only prepares a child
+fault and is not a standalone correct-output pass.
+
+## Private release and Apoc-only approval gate
+
+1. Complete the single independent read-only review, bounded corrections, exact
+   source validation and real-filesystem GREEN before private PR publication.
+   Never request a GitHub Codex review. Require exact-head checks before merge.
+2. Confirm live tags/version, then use the authorized private patch metadata;
+   do not publish to npm. The coordinator builds the existing runtime Dockerfile
+   from the exact release revision, verifies version/source/UID, and privately
+   distributes a checksum-verified immutable image archive.
+3. Read the live gateway topology and accepted traffic. Present the exact serial
+   recreation commands, service/image identities, traffic impact and rollback
+   commands to the operator and obtain **separate explicit approval**. Previous
+   fleet interruption approval does not carry over. No host/build-service restart.
+4. Before recreation, preserve historical logs plus exact previous image and
+   configuration in the restricted rollback bundle. Keep mounts, WAN/control
+   networks, addresses, restart policy, non-root user, read-only root, dropped
+   capabilities and no-new-privileges unchanged. Never copy secrets into this
+   runbook or a PR.
+5. After approval, recreate only `gateway-o2` / `socketduct-apoc-o2`, then
+   `gateway-zyxel` / `socketduct-apoc-zyxel`, then
+   `gateway-starlink` / `socketduct-apoc-starlink`. Gate each next service on
+   authenticated TLS readiness, source/image/UID verification, private bounded
+   logging, and ordinary traffic. Do not expand to other hosts, hub or clients.
+
+## Acceptance and serial rollback
+
+After all three gateways are ready, collect one baseline and a readback after
+at least five minutes of actual ordinary activity, with multiple complete new
+events per gateway. Track offsets, hashes and identities across rotations.
+Require zero new malformed completed lines, preserved historical evidence,
+proper permissions/bounds and authenticated readiness for all three members.
+Absent activity is incomplete acceptance, not a vacuous pass. Observe a naturally
+scheduled non-root Docker workload through Apoc when available; do not force
+scheduling or modify database/capacity settings. Distinguish this non-recurrence
+window from the isolated deterministic ENOSPC proof.
+
+Stop the serial rollout if a gateway fails readiness, harms traffic, loops,
+loses hardening, or produces newly joined records. Restore only that service's
+exact previous configuration and immutable image, keeping current logs and
+archives. Reverify it before proceeding; never overwrite newer logs with old
+bytes. Rollback restores the old logger defect, so record that limitation and
+keep acceptance open. Only the coordinator records completion after review,
+private release and the approved Apoc acceptance are all proven.

package/docs/running.md

@@ -0,0 +1,215 @@
+# Running Socketduct
+
+Socketduct is currently an MVP library/runtime skeleton for a resilient TCP forwarder. The checked-in test suite exercises the supported flow end-to-end:
+
+```text
+local app socket -> Socketduct edge -> Socketduct relay -> session-authorized TCP target
+```
+
+## Install
+
+```sh
+npm ci
+```
+
+## Local verification
+
+```sh
+npm run lint
+npm run typecheck
+npm test
+npm start
+```
+
+## Production Docker gateway
+
+Production Docker deployment uses the image-only contract in
+[`docker-compose.yml`](../docker-compose.yml) and requires
+`SOCKETDUCT_IMAGE=ghcr.io/kaspernj/socketduct@sha256:<64-lowercase-hex>`.
+Run `npm run gateway:deploy` (or add `-- --docker-host` for the private Docker
+socket shim). The command rejects missing or mutable image references before it
+validates Compose, pulls, and applies with `--wait --no-build`. Local source
+builds use the separate `docker-compose.dev.yml` path. See
+[Docker gateway setup](docker.md) for GHCR login, TLS, update, and rollback.
+
+`npm start` currently prints the startup summary:
+
+```text
+Socketduct starting in single-worker mode on node
+```
+
+## Current runtime building blocks
+
+- `src/server/primary.js` starts a Node.js `cluster` primary and forks workers.
+- `src/server/worker.js` starts a TCP worker server around an injected connection handler.
+- `src/server/control-handler.js` handles authenticated `session.create` and `session.resume` control messages.
+- `src/proxy/tcp-relay.js` starts the relay side and forwards authenticated stream frames to the target authorized for each session.
+- `src/edge/tcp-edge.js` starts the local edge side, spools client data, reconnects to the relay, and replays unacknowledged chunks.
+- `src/proxy/multiplexed-relay.js` and
+  `src/client/multiplexed-connection.js` provide protocol v3's one-physical,
+  many-virtual-stream transport.
+
+Set `SOCKETDUCT_PROTOCOL_VERSION=3` to run the v3 relay. Version `2` remains the
+default for rollback compatibility. V3 compression is disabled; frame, stream
+and aggregate safety bounds plus fair scheduling apply instead.
+
+Native reverse mode has separate `reverse-hub` and `reverse-gateway` runtime
+roles and always uses verified TLS plus adaptive zstd. See
+[Native reverse gateway](reverse-gateway.md) for the environment contract and
+three-member TensorBuzz API.
+
+## Persistent JSONL logs
+
+Set `SOCKETDUCT_LOG_DIRECTORY` to opt into bounded, per-process JSONL files. A
+Docker deployment should bind mount persistent host storage at that directory.
+`SOCKETDUCT_LOG_MAX_FILE_BYTES` defaults to 10 MiB and
+`SOCKETDUCT_LOG_MAX_FILES` defaults to five total files per process/role family.
+Existing stdout/stderr output is preserved. See
+[Persistent structured logging](logging.md) for the mount example, embedded
+client `logger` option, rotation layout, event list, and strict redaction
+contract.
+
+## Minimal programmatic relay/edge shape
+
+```js
+import { InMemoryUserStore, login, TokenStore } from './src/auth/user-store.js';
+import { startTcpEdge } from './src/edge/tcp-edge.js';
+import { startTcpRelay } from './src/proxy/tcp-relay.js';
+import { SessionStore } from './src/sessions/session.js';
+import { SessionSpool } from './src/spool/spool-file.js';
+
+const users = new InMemoryUserStore();
+const tokens = new TokenStore();
+await users.createUser({ username: 'edge', password: process.env.SOCKETDUCT_PASSWORD });
+const token = await login(users, tokens, { username: 'edge', password: process.env.SOCKETDUCT_PASSWORD });
+
+const relay = await startTcpRelay({
+  authorizeTarget: ({ principal, target }) => {
+    return principal.username === 'edge' && target.host === '127.0.0.1' && target.port === 22;
+  },
+  tokens,
+  sessions: new SessionStore(),
+});
+
+const edge = await startTcpEdge({
+  relayHost: '127.0.0.1',
+  relayPort: relay.port,
+  token: token.value,
+  sessionName: 'local-ssh',
+  target: { host: '127.0.0.1', port: 22 },
+  spool: new SessionSpool({ rootDir: '/tmp/socketduct-spool' }),
+});
+
+console.log(`Connect local clients to 127.0.0.1:${edge.port}`);
+```
+
+Do not hard-code real passwords or token values. Feed credentials through a secret manager or environment variable and keep logs redacted.
+
+## MVP limitations
+
+- No stable CLI flags yet.
+- Relay targets are requested per session and must be explicitly authorized by the injected target policy.
+- User/session stores are in-memory in the current MVP skeleton.
+- Spool files are temporary local files and may contain raw application payload.
+
+## Resource-exhaustion protections
+
+### Initial target acquisition retry
+
+`SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS` defaults to `10000` and bounds each individual target TCP connect attempt. `SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS` defaults to `250`. `SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS` defaults to `5000` and must be greater than or equal to the initial delay. While an authenticated, authorized session is still `creating`, the relay destroys a refused or timed-out attempt and retries with a doubling delay capped by the maximum. Request timeout, client abort/tunnel close, or relay shutdown cancels the attempt and every associated timer.
+
+The retry ends permanently at `session.created`. Established target failure and application-write uncertainty are terminal and are never automatically replayed.
+
+The relay enforces two configurable pre-authentication limits to prevent slow/partial resource exhaustion:
+
+### Handshake timeout
+
+`SOCKETDUCT_HANDSHAKE_TIMEOUT_MS` (default: `10000`, 10 seconds) limits how long a connection can stay open without sending a `session.create` or `session.resume` frame. When the timer fires before authentication completes, the relay closes the connection with a `HANDSHAKE_TIMEOUT` error frame.
+
+This prevents slow-loris-style connections that send data at an arbitrarily low rate to hold relay resources indefinitely.
+
+### Per-connection input budget
+
+`SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION` (default: `65536`, 64 KiB) limits the cumulative raw bytes a v2 or v3 connection may send before completing authentication. Once the budget is exceeded, the relay closes the connection; v3 reports `INPUT_LIMIT_EXCEEDED`. Authenticated stream traffic is governed by the separate frame and buffer limits.
+
+This prevents an attacker from sending large amounts of data (e.g., 100s of MiB of partial frame fragments) before the handshake deadline expires.
+
+### Incremental frame decoder
+
+The `FrameDecoder` uses a linear cursor over a single buffer rather than concatenating a new buffer on every `push()` call. This avoids the O(n²) copying pattern that could be exploited by repeated small TCP chunks.
+
+## TLS configuration
+
+The relay supports Node.js built-in TLS via `node:tls`. Configure with environment variables:
+
+```sh
+# Atomic pair: both must be set or neither
+SOCKETDUCT_TLS_CERT_FILE=/certs/relay.crt
+SOCKETDUCT_TLS_KEY_FILE=/certs/relay.key
+
+# Optional mTLS
+SOCKETDUCT_TLS_CLIENT_CA_FILE=/certs/client-ca.crt
+
+# Explicitly allow non-loopback plaintext (1 or true only)
+SOCKETDUCT_ALLOW_INSECURE_PUBLIC=1
+```
+
+The relay fails closed: binding to a non-loopback address without TLS is refused unless `SOCKETDUCT_ALLOW_INSECURE_PUBLIC` is explicitly set to `1` or `true`. Loopback (`127.0.0.0/8`, `::1`, `localhost`) plaintext binds remain compatible without this flag.
+
+Certificate material is read at runtime with `readFileSync` and the process fails loudly on missing or unreadable files. Sensitive material is never logged.
+
+Relay startup and periodic status messages are JSON. `SOCKETDUCT_STATUS_INTERVAL_MS` defaults to `30000`; set it to `0` to disable. Status messages include safe connection/session, initial target attempt/timer, and buffered-byte counts—never tokens, targets, payloads, certificate contents, or spool data.
+
+### Client configuration
+
+Connect to a TLS relay by providing a `tls` option with the server's CA certificate:
+
+```js
+const socket = connectSocketduct({
+  relay: {host: 'relay.example.com', port: 3100, token: '...'},
+  sessionName: 'secure-tunnel',
+  target: {host: 'docker-api', port: 2375},
+  spoolDirectory: '/tmp/socketduct-spool',
+  tls: {
+    caFile: '/path/to/ca.crt',
+  },
+})
+```
+
+`rejectUnauthorized` defaults to `true`. Set it to `false` only for testing with self-signed certificates.
+
+For mTLS, the client must present a certificate signed by the relay's client CA. Provide `certFile` and `keyFile` as an atomic pair in the `tls` option:
+
+```js
+const socket = connectSocketduct({
+  relay: {host: 'relay.example.com', port: 3100, token: '...'},
+  sessionName: 'secure-tunnel',
+  target: {host: 'docker-api', port: 2375},
+  spoolDirectory: '/tmp/socketduct-spool',
+  tls: {
+    caFile: '/path/to/ca.crt',
+    certFile: '/path/to/client.crt',
+    keyFile: '/path/to/client.key',
+  },
+})
+```
+
+Set `servername` to override the SNI hostname used for certificate identity validation when the certificate CN/SAN differs from `relayHost`.
+
+This `tls` option is relay TLS. For HTTPS or mTLS at the requested target, use `SocketductHttpsAgent` from `socketduct/https` with separate `relayTls` and `targetTls` options as documented in [Node-compatible socket API design](socket-api.md#socketducthttpsagent).
+
+For several explicit WAN paths in one process, use
+`MultiplexedSocketductTransportSet` and call `await set.start()` before accepting
+application work. Configure one stable gateway ID and pinned relay endpoint or
+physical socket factory per path. `minimumReadyMembers` defaults to 1, so a dead
+WAN does not block process readiness; inspect `set.status()` or `stateChange`
+notifications for slower members joining or recovering. While all members are
+reconnecting, bounded new opens wait for a ready member. If every member becomes
+terminal after readiness, they fail with `SOCKETDUCT_TRANSPORT_SET_TERMINAL`;
+inspect its ordered aggregate causes or privacy-safe per-member status codes.
+No extra physical member is created. Configure the set-wide buffer/spool/queue
+limits for the whole process rather than multiplying a desired budget by
+gateway count.
+For process replacement, call `recoverConnection()` with each stream's original
+gateway ID before `start()`; see the exact sequence in
+[Node-compatible socket API design](socket-api.md#multiplexedsocketducttransportset-multi-gateway-v3-api).