socketduct 0.1.15

package/docs/docker.md

@@ -0,0 +1,281 @@
+# Docker gateway setup
+
+This setup runs the Socketduct relay on a Docker server so edges can create authenticated, resumable sessions to targets reachable from that server. In Docker-host gateway mode the common target is the local Docker Engine API.
+
+For the native outbound home topology—especially Zyxel and Starlink paths
+behind CGNAT—use [Native reverse gateway](reverse-gateway.md) and
+[`docker-compose.reverse-gateway.yml`](../docker-compose.reverse-gateway.yml).
+That mode uses no socket shim and publishes no Docker or Socketduct port at
+home: the gateway connects outbound to Server3 and directly to
+`docker-server:2375` on the shared private control network.
+
+## 1. Prepare the server
+
+Install these host prerequisites before cloning the versioned deployment
+contract:
+
+- Docker Engine with Docker Compose v2.
+- Node.js 24 or newer, including npm. Install it from your operating-system
+  vendor's supported packages or the official Node.js distribution; the
+  repository's `gateway:deploy` command runs on the host and does not run inside
+  Docker.
+
+Verify the tools before continuing:
+
+```sh
+docker compose version
+node --version
+npm --version
+```
+
+`node --version` must report v24 or newer. Then clone the repository and copy
+the example environment:
+
+```sh
+git clone https://github.com/kaspernj/socketduct.git
+cd socketduct
+cp .env.example .env
+```
+
+The production relay image is private in GHCR unless its package visibility has
+been made public. Before deployment, authenticate Docker to `ghcr.io` using a
+GitHub account or token that has package read access:
+
+```sh
+docker login ghcr.io
+```
+
+Supply credentials only to Docker's login prompt or an external credential
+helper. Do not put GHCR credentials in this repository, `.env`, Compose files,
+shell history, or deployment logs.
+
+Generate a bearer token for the edge:
+
+```sh
+openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n'
+```
+
+Edit `.env`:
+
+```sh
+SOCKETDUCT_IMAGE=ghcr.io/kaspernj/socketduct@sha256:<64-lowercase-hex>
+SOCKETDUCT_MODE=relay
+SOCKETDUCT_RELAY_HOST=0.0.0.0
+SOCKETDUCT_RELAY_PORT=3100
+SOCKETDUCT_PROTOCOL_VERSION=3
+SOCKETDUCT_PUBLISH_HOST=192.0.2.10
+SOCKETDUCT_RESUME_WINDOW_MS=30000
+SOCKETDUCT_AUTH_TOKENS=edge-user:replace-with-generated-token
+SOCKETDUCT_TARGET_ALLOWLIST=docker-socket-shim:2375
+```
+
+Replace `<64-lowercase-hex>` with the published digest for the exact Socketduct
+image to deploy. `SOCKETDUCT_IMAGE` accepts only the untagged
+`ghcr.io/kaspernj/socketduct@sha256:<digest>` form. Mutable `latest`, branch, and
+commit-SHA tags are rejected before Docker runs. Keep `.env` private.
+`SOCKETDUCT_AUTH_TOKENS` accepts comma-separated `username:token` entries.
+`SOCKETDUCT_TARGET_ALLOWLIST` accepts comma-separated `host:port` entries. The
+relay rejects any requested session target that is not on the allowlist. If the
+relay listens on a non-loopback interface, configure the built-in TLS settings
+in [TLS for Docker deployments](#tls-for-docker-deployments) before starting it;
+public plaintext requires the explicit emergency opt-out documented there.
+
+Compose publishes on `127.0.0.1` by default. Set `SOCKETDUCT_PUBLISH_HOST` explicitly to the private host interface that trusted edges use; avoid `0.0.0.0` unless the firewall policy and exposure are deliberate. The relay container runs as UID/GID 1000 with a read-only root filesystem, dropped capabilities, and `no-new-privileges`, so mounted TLS files must be readable by UID 1000 without becoming group/world writable.
+
+The committed `.env.example` token is intentionally rejected by the runtime; replace it before starting the relay.
+
+## 2. Choose the Docker target shape
+
+### Docker socket shim, preferred for Docker-host gateway mode
+
+The Compose file includes an optional `docker-socket-shim` service behind the `docker-host` profile. It mounts `/var/run/docker.sock` and exposes TCP port `2375` only on the private Compose network. The host does **not** publish `2375`, so Docker API access still has to pass through Socketduct authentication and the target allowlist.
+
+Use this allowlist entry:
+
+```sh
+SOCKETDUCT_TARGET_ALLOWLIST=docker-socket-shim:2375
+```
+
+Deploy with the profile enabled as described below. The profile does not publish
+the shim port on the host.
+
+```sh
+npm run gateway:deploy -- --docker-host
+```
+
+### Existing Docker TCP endpoint
+
+If the Docker server already has a secured Docker TCP endpoint, allowlist that host and port instead:
+
+```sh
+SOCKETDUCT_TARGET_ALLOWLIST=docker.example.internal:2376
+```
+
+Use the hostname as resolved from the relay container, not from the edge machine.
+
+### Host-network target
+
+If you run Socketduct with host networking outside the provided Compose file, the target can be a host-local address such as `127.0.0.1:2375`. Do not use this with the default Compose network expecting container loopback to mean the Docker host; `127.0.0.1` inside the relay container is the relay container itself.
+
+## 3. Start the relay
+
+For a normal remote relay without the Docker socket shim:
+
+```sh
+npm run gateway:deploy
+```
+
+For Docker-host gateway mode:
+
+```sh
+npm run gateway:deploy -- --docker-host
+```
+
+The deployment command validates the image setting first, fixes the production
+Compose file, `.env`, project directory/name, and optional profile explicitly,
+then validates the rendered Compose JSON. It neutralizes ambient Compose model and
+profile selectors while preserving Docker connection settings such as
+`DOCKER_HOST` and `DOCKER_CONTEXT`. The rendered `socketduct-relay` image must
+exactly equal the validated digest and must not contain a build source before the
+command runs `docker compose pull`, then runs
+`docker compose up -d --wait --no-build`. It cannot build from the checkout or
+silently fall back to a local image. A missing or malformed image setting stops
+the command before Docker is invoked. Automatic Compose override files and
+ambient `COMPOSE_FILE`, `COMPOSE_ENV_FILES`, and `COMPOSE_PROFILES` values are
+not part of this production path. Compose also rejects a missing setting if it
+is invoked directly.
+
+Check status and logs:
+
+```sh
+COMPOSE_PROFILES= docker compose --file docker-compose.yml --env-file .env --project-directory . --project-name socketduct-gateway ps
+COMPOSE_PROFILES= docker compose --file docker-compose.yml --env-file .env --project-directory . --project-name socketduct-gateway logs -f socketduct-relay
+```
+
+For persistent structured logs, create a host directory writable by the
+container's uid/gid 1000 and enable the opt-in sink in `.env`:
+
+```sh
+sudo install -d -o 1000 -g 1000 -m 0700 /srv/socketduct/logs
+```
+
+```text
+SOCKETDUCT_LOG_HOST_DIRECTORY=/srv/socketduct/logs
+SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
+SOCKETDUCT_LOG_MAX_FILE_BYTES=10485760
+SOCKETDUCT_LOG_MAX_FILES=5
+```
+
+The production relay and reverse-gateway Compose files mount the host directory
+at `/var/log/socketduct`. Existing container stdout/stderr remains enabled. See
+[Persistent structured logging](logging.md) for file names, rotation, embedded
+client configuration, and the redaction contract.
+
+Expected startup log (formatted here for readability; the actual line is JSON):
+
+```text
+{"event":"relay.started","host":"0.0.0.0","port":3100,"transportSecurity":"TLS","compression":"auto"}
+```
+
+## 4. Connect an edge
+
+Configure the local edge with:
+
+- relay host: the remote server hostname or IP
+- relay port: `SOCKETDUCT_RELAY_PORT`
+- token: the generated token from `.env`
+- target: one of the `SOCKETDUCT_TARGET_ALLOWLIST` entries
+
+For Docker-host gateway mode the target should be:
+
+```text
+docker-socket-shim:2375
+```
+
+The target host is resolved from the relay container, not from the local edge machine. For TensorBuzz this means the allowlisted hostname must be reachable from the remote gateway server/container.
+
+## 5. Update and rollback
+
+To update, change only `SOCKETDUCT_IMAGE` in `.env` to the digest of the intended
+new image, then re-apply with `npm run gateway:deploy` (or add
+`-- --docker-host`). Verify the selected digest and service health before
+discarding the previous digest.
+
+For deterministic rollback, change the digest back to the previously verified
+value and run the same deployment command again. The pull plus
+`up -d --wait --no-build` sequence applies that exact image without rebuilding
+or resolving a mutable tag.
+
+## 6. Stop
+
+```sh
+COMPOSE_PROFILES= COMPOSE_REMOVE_ORPHANS=false docker compose --file docker-compose.yml --env-file .env --project-directory . --project-name socketduct-gateway --profile docker-host down
+```
+
+Add `-v` to that explicit `down` command only if you intentionally want to
+remove named Socketduct state volumes.
+
+## Security notes
+
+- Do not commit real `.env` files or tokens.
+- The Docker socket shim has Docker-host-equivalent privileges. Keep it private to the Compose network and expose only the Socketduct relay port.
+- Expose the relay port only to trusted edge hosts where possible, for example with a firewall/security group.
+- Put the relay behind TLS or a private network before production exposure.
+- Keep `SOCKETDUCT_TARGET_ALLOWLIST` tight. This is the open-proxy guardrail.
+
+## Source-independent development validation
+
+The production Compose file is image-only and contains no `build` directive.
+Local source builds remain explicit in `docker-compose.dev.yml`; development
+gates run as UID 1000 from source copied into that separate image, without host
+source mounts:
+
+```sh
+docker compose -f docker-compose.dev.yml build socketduct-dev
+docker compose -f docker-compose.dev.yml run --rm socketduct-dev npm test
+docker compose -f docker-compose.dev.yml run --rm socketduct-dev npm run typecheck
+docker compose -f docker-compose.dev.yml run --rm socketduct-dev npm run lint
+```
+
+## TensorBuzz container workflow
+
+TensorBuzz is the sole repository CI and private-container publication workflow
+owner. Every build uses the checked-in `tensorbuzz.yml` to run the package gates
+and build the Dockerfile against an isolated Docker-in-Docker service. The
+validation image is local to that ephemeral service and is never pushed by a
+pull-request build.
+
+Private GHCR publication is currently disabled. Enabling it safely requires
+TensorBuzz to provide trusted default-branch, tag, and manual-trigger metadata
+to build commands, plus an established secret-backed Socketduct project input
+containing a private-GHCR write credential. Ordinary TensorBuzz project
+environment variables are readable project configuration and must not hold that
+credential. Until both capabilities are configured, publication must remain
+paused; repository CI must not infer trust from the checked-out commit or
+expose registry credentials in source or logs.
+
+## TLS for Docker deployments
+
+To run the relay with TLS in Docker:
+
+1. Place your PEM-encoded certificate (`relay.crt`) and private key (`relay.key`) in a `certs/` directory next to `docker-compose.yml`.
+2. Set the following in `.env`:
+   ```sh
+   SOCKETDUCT_TLS_CERT_FILE=/certs/relay.crt
+   SOCKETDUCT_TLS_KEY_FILE=/certs/relay.key
+   ```
+3. Optionally add mTLS:
+   ```sh
+   SOCKETDUCT_TLS_CLIENT_CA_FILE=/certs/client-ca.crt
+   ```
+4. The Compose file automatically mounts `./certs` (or `SOCKETDUCT_TLS_CERT_DIR`) as `/certs:ro` in the container.
+5. Restart:
+   ```sh
+   npm run gateway:deploy
+   ```
+6. Expected startup log with TLS (the actual log is one JSON line):
+   ```text
+   {"event":"relay.started","host":"0.0.0.0","port":3100,"transportSecurity":"TLS","compression":"auto"}
+   ```
+
+To run without TLS on a non-loopback interface (not recommended for production), set `SOCKETDUCT_ALLOW_INSECURE_PUBLIC=1` in `.env`. The relay will refuse to start on `0.0.0.0` without this explicit opt-out.

package/docs/logging.md

@@ -0,0 +1,185 @@
+# Persistent structured logging
+
+Socketduct can write lifecycle diagnostics as newline-delimited JSON (JSONL) to
+a directory mounted from persistent host storage. File logging is opt-in.
+Existing startup/status output on stdout and errors on stderr remain unchanged
+when file logging is enabled.
+
+## Standalone runtime configuration
+
+Set `SOCKETDUCT_LOG_DIRECTORY` for a `relay`, `reverse-hub`, or
+`reverse-gateway` process:
+
+```sh
+SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
+SOCKETDUCT_LOG_MAX_FILE_BYTES=10485760
+SOCKETDUCT_LOG_MAX_FILES=5
+```
+
+`SOCKETDUCT_LOG_MAX_FILE_BYTES` defaults to 10 MiB and must be at least 1024.
+`SOCKETDUCT_LOG_MAX_FILES` defaults to 5, includes the active file, and must be
+between 1 and 100. The size/count settings are ignored unless a non-empty log
+directory enables the sink.
+
+Each process writes its own `<role>-<pid>.jsonl` file, with older files renamed
+to `.1`, `.2`, and so on. A writer never rotates another live process's active
+file, which avoids cross-process rename races. Each file in the current
+process/role family is bounded by the configured byte limit and the family
+retains at most the configured file count. A reused PID continues the same
+bounded filename family.
+
+On its first write, a logger also caps files left by definitely exited
+same-role process instances to the configured file count in total, retaining
+the newest files. Repeated signal-0 PID probes must report `ESRCH`, and the file
+must remain unchanged, before it can be deleted. A live/reused PID, permission
+failure, unsupported probe, changed file, or other indeterminate result
+preserves every file in that family. Files are created with mode `0600`; a newly
+created log directory uses mode `0700`.
+
+For Docker, bind mount a persistent host directory and point Socketduct at the
+container path:
+
+```yaml
+services:
+  socketduct:
+    environment:
+      SOCKETDUCT_LOG_DIRECTORY: /var/log/socketduct
+      SOCKETDUCT_LOG_MAX_FILE_BYTES: "10485760"
+      SOCKETDUCT_LOG_MAX_FILES: "5"
+    volumes:
+      - /srv/socketduct/logs:/var/log/socketduct
+```
+
+Create `/srv/socketduct/logs` with mode `0700` and ownership that permits the
+container user to write it; for uid/gid 1000, use
+`sudo install -d -o 1000 -g 1000 -m 0700 /srv/socketduct/logs`.
+A permission, disk, or rotation error does not change tunnel,
+session, target, or reconnect behavior. Socketduct reports only
+`Socketduct logger failure (LOGGER_IO_ERROR)` to stderr, at most once per
+logger, without including the path or underlying error text.
+
+## Interrupted writes and retained evidence
+
+Before appending, the file sink checks the last byte of a nonempty active file.
+This bounded check also runs for a fresh logger or restarted process reusing
+the same filename; it does not scan or parse historical records. A failed
+append may have written a prefix even when the filesystem reports an error.
+
+If the active file does not end in a newline, Socketduct moves the entire file
+byte-for-byte into the existing numbered retention family and writes subsequent
+events to a clean active file. The retained segment may still contain an
+incomplete final record: it is incident evidence, not repaired JSONL. Normal
+bounded retention eventually ages it out, so preserve incident evidence outside
+the managed family before rollout or forensic work. New complete records must
+parse independently; ignoring malformed historical lines is not proof of recovery.
+
+If tail inspection, rotation, clean-file creation, or mode verification fails,
+that logging call writes no new record. Later ordinary calls recheck the
+filesystem; there is no background retry loop or replay of missed diagnostics.
+If an append itself fails, it may leave another incomplete prefix that the next
+call must separate. Logging failures still do not interrupt tunnel traffic.
+
+With `maxFiles: 1`, there is no retained slot: an incomplete active file is left
+untouched and file logging pauses. An incomplete active file already larger
+than a newly lowered size limit also pauses logging **before startup pruning**;
+it is not deleted to satisfy that limit. These pre-existing bytes can remain
+outside the newly configured bound, but Socketduct will not grow them. An
+operator must preserve the evidence separately and provide a clean path before
+logging can continue. Socketduct never truncates or rewrites damaged records.
+Already newline-terminated malformed historical records are not repaired.
+
+The sink requires a regular active file with mode `0600` and a directory with
+mode `0700`, including on reused paths. It checks the newly created file's
+actual mode before writing and does not follow an active-file symlink. Fix
+ownership/modes on an operator-preserved path rather than making logs public.
+
+See [the private rollout runbook](runbooks/jsonl-integrity-rollout.md) for the
+isolated fault commands and evidence-preserving Apoc-only rollout gates.
+
+The checked-in production relay and reverse-gateway Compose files already mount
+`${SOCKETDUCT_LOG_HOST_DIRECTORY:-./logs}` at `/var/log/socketduct`. Enable the
+sink in `.env` after creating the host directory for the container's uid/gid
+1000:
+
+```sh
+SOCKETDUCT_LOG_HOST_DIRECTORY=/srv/socketduct/logs
+SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
+```
+
+`SOCKETDUCT_STATUS_INTERVAL_MS` controls both console and file-backed periodic
+status events. Its default remains 30000 milliseconds; `0` disables periodic
+status only, not lifecycle logging.
+
+## Embedded client configuration
+
+Create one file logger per process/role and pass it to the client, agent, or
+transport set through its `logger` option:
+
+```js
+import {createJsonlFileLogger} from "socketduct"
+import {MultiplexedSocketductTransportSet} from "socketduct/multiplexed"
+
+const logger = createJsonlFileLogger({
+  directory: "/var/log/socketduct",
+  role: "tensorbuzz-client",
+  maxFileBytes: 10 * 1024 * 1024,
+  maxFiles: 5
+})
+
+const transports = new MultiplexedSocketductTransportSet({
+  connectionId: "runner_01_stable_identity",
+  spoolDirectory: "/tmp/socketduct-v3-set",
+  gateways,
+  logger
+})
+```
+
+The same `logger` option is supported by `MultiplexedSocketductConnection`,
+`ReverseGatewayConnection`, `OutboundReverseGateway`, `connectSocketduct`,
+`createSocketductConnectionFactory`, `SocketductHttpAgent`, and
+`SocketductHttpsAgent`. A transport set owns logger propagation to its members;
+do not put `logger` inside `memberOptions`.
+
+For an existing logging system, use the exported line-writer adapter:
+
+```js
+import {createStructuredLogger} from "socketduct"
+
+const logger = createStructuredLogger({
+  role: "tensorbuzz-client",
+  writeLine(line) {
+    destination.append(line)
+  }
+})
+```
+
+Alternatively, pass an object with `log(event, fields)` directly. Socketduct
+calls it only with a known event and already-sanitized fields. A direct custom
+logger is responsible for adding its own timestamp/process/role envelope and
+for preserving one-object-per-line framing. Synchronous throws and rejected
+promises from custom loggers/writers are isolated from connection behavior.
+
+## Event and data contract
+
+The built-in logger emits one JSON object per line, capped at 1024 bytes. Every
+entry contains an ISO-8601 `timestamp`, an allowlisted `event`, numeric
+`processId`, and validated `role`. Depending on the component, events cover:
+
+- process startup and periodic status counters
+- physical transport connect, disconnect, retry scheduling, recovery, and
+  terminal failure
+- transport-set readiness, member state/generation replacement, and terminal
+  loss
+- reverse-gateway target open success, open failure, and close
+- virtual-stream opening, opened, closed, and error transitions
+
+Only finite allowlisted booleans, non-negative integer counters, validated
+gateway IDs, states, and error classifications can be included. Unknown events
+are dropped. Unknown error codes become `UNKNOWN`. Errors supplied through
+`errorDiagnostics()` retain their name, message, and stack so terminal
+transport and virtual-stream failures are actionable.
+
+The diagnostic path never serializes protocol payloads or arbitrary caller
+fields. It serializes error messages and stack traces produced by
+`errorDiagnostics()` after redacting bearer credentials, URL userinfo, and
+password/token/authorization values.

package/docs/plans/initial-implementation.md

@@ -0,0 +1,205 @@
+# Initial Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** Build the first Node.js foundation for Socketduct: authenticated session create/resume, framed protocol primitives, temporary spool files, and a multi-core server skeleton.
+
+**Architecture:** Start with a small standalone Node.js codebase. Use a primary process plus `node:cluster` workers for multi-core connection handling. Keep protocol/session/spool logic isolated and unit-tested before adding real proxy streaming.
+
+**Tech Stack:** Node.js, TypeScript preferred, built-in `node:net`, `node:cluster`, `node:fs`, `node:stream`, test runner TBD (`node:test` is fine for MVP).
+
+---
+
+## Task 1: Initialize Node.js project
+
+**Objective:** Add the minimal package structure for a Node.js service.
+
+**Files:**
+
+- Create: `package.json`
+- Create: `src/index.ts` or `src/index.js`
+- Create: `test/`
+
+**Steps:**
+
+1. Choose TypeScript or plain Node.js. Prefer TypeScript unless setup friction slows the MVP.
+2. Add scripts:
+   - `test`
+   - `lint` once linting exists
+   - `start`
+3. Add a trivial startup entrypoint.
+4. Run `npm test` and verify it passes.
+5. Commit: `chore: initialize node project`
+
+## Task 2: Add framed protocol encoder/decoder
+
+**Objective:** Encode/decode length-prefixed protocol frames.
+
+**Files:**
+
+- Create: `src/protocol/frame.*`
+- Create: `test/unit/protocol/frame.test.*`
+
+**Acceptance criteria:**
+
+- Encodes JSON header + binary payload.
+- Decodes frames split across multiple TCP chunks.
+- Rejects invalid header length and oversized payload.
+- Preserves payload bytes exactly.
+
+**Commit:** `feat: add protocol frame codec`
+
+## Task 3: Add session model and state transitions
+
+**Objective:** Represent sessions with name, identifier, owner, sequence positions, and state.
+
+**Files:**
+
+- Create: `src/sessions/session.*`
+- Create: `src/sessions/session-store.*`
+- Create: `test/unit/sessions/session.test.*`
+
+**Acceptance criteria:**
+
+- Create session with `name` and generated `identifier`.
+- Resume lookup by `identifier`.
+- Enforce legal state transitions.
+- Reject resume for missing/expired session.
+
+**Commit:** `feat: add session lifecycle model`
+
+## Task 4: Add local user authentication
+
+**Objective:** Add local users with password hashing and login validation.
+
+**Files:**
+
+- Create: `src/auth/user-store.*`
+- Create: `src/auth/passwords.*`
+- Create: `src/auth/tokens.*`
+- Create: `test/unit/auth/*.test.*`
+
+**Acceptance criteria:**
+
+- Passwords are hashed, never stored plaintext.
+- Login returns an opaque token.
+- Invalid username/password fails.
+- Token maps back to user until expiry/revocation.
+
+**Commit:** `feat: add local authentication primitives`
+
+## Task 5: Add spool file writer/reader
+
+**Objective:** Persist interrupted session data to temp files and read it back for resume.
+
+**Files:**
+
+- Create: `src/spool/spool-file.*`
+- Create: `test/unit/spool/spool-file.test.*`
+
+**Acceptance criteria:**
+
+- Creates user-private temp spool directory.
+- Writes metadata and chunks.
+- Reads only chunks after a requested sequence.
+- Truncates/removes acked chunks.
+- Rejects path traversal or mismatched session identifiers.
+
+**Commit:** `feat: add session spool files`
+
+## Task 6: Add multi-core server skeleton
+
+**Objective:** Start a primary process and cluster workers.
+
+**Files:**
+
+- Create: `src/server/primary.*`
+- Create: `src/server/worker.*`
+- Modify: `src/index.*`
+
+**Acceptance criteria:**
+
+- Primary starts one worker per available CPU by default.
+- Worker count can be configured.
+- Worker crash is logged and replaced.
+- Single-worker mode is available for tests/dev.
+
+**Commit:** `feat: add clustered server skeleton`
+
+## Task 7: Add authenticated session create/resume messages
+
+**Objective:** Wire auth + session store + protocol messages without real proxying yet.
+
+**Files:**
+
+- Create: `src/server/control-handler.*`
+- Create: `test/integration/session-create-resume.test.*`
+
+**Acceptance criteria:**
+
+- Unauthenticated `session.create` is rejected.
+- Authenticated `session.create` returns identifier.
+- Authenticated `session.resume` by owner succeeds.
+- Different user cannot resume the session.
+- Unknown identifier returns machine-readable error.
+
+**Commit:** `feat: add authenticated session control flow`
+
+## Task 8: Add first TCP forwarding prototype
+
+**Objective:** Forward bytes from a local edge connection through relay to target using framed stream data.
+
+**Files:**
+
+- Create: `src/edge/*`
+- Create: `src/proxy/*`
+- Create: `test/integration/tcp-forwarding.test.*`
+
+**Acceptance criteria:**
+
+- Local app connects to edge port.
+- Relay connects to configured target port.
+- Bytes flow both ways.
+- Sequence numbers and acknowledgements are emitted.
+
+**Commit:** `feat: add tcp forwarding prototype`
+
+## Task 9: Add interruption/resume integration test
+
+**Objective:** Prove the core Socketduct behavior in a controlled test.
+
+**Files:**
+
+- Create: `test/integration/interruption-resume.test.*`
+
+**Acceptance criteria:**
+
+- Start app socket -> edge -> relay -> fake target.
+- Send bytes.
+- Simulate edge-relay connection drop.
+- Edge writes spool file.
+- Reconnect and resume by identifier.
+- Edge sends spool data.
+- Fake target receives the stream exactly once and in order.
+
+**Commit:** `test: cover interrupted session resume`
+
+## Task 10: Add docs for running and security limits
+
+**Objective:** Document local dev usage and known limitations.
+
+**Files:**
+
+- Modify: `README.md`
+- Create: `docs/running.md`
+- Modify: `docs/security.md`
+
+**Acceptance criteria:**
+
+- Local dev command documented.
+- Example user creation documented.
+- Example edge/relay run documented.
+- Open proxy prevention documented.
+- Known non-guarantees documented.
+
+**Commit:** `docs: add running guide`