Server Edition 1-2-3-4-5-6 Remediation Plan
Last reviewed: 2026-10-26
Scope: server-edition/
Purpose: Current, actionable remediation plan for the SLeeLa Server Edition, incorporating the initial transport/security review and the subsequent hardening changes.
Review type: Static source/documentation review. The CLI and default-bind changes have been committed, but a build, automated test suite, runtime test, and penetration test have not been completed in this review.
Overall status: Initial hardening committed; further implementation and verification required before public production deployment.
Current status snapshot — 2026-10-26
The command-line executable now defaults to loopback, validates port and maximum-packet-size arguments, rejects unknown options, and requires --allow-remote for a non-loopback bind. The transport implementation now uses strict bounded integer parsing for numeric protocol headers, an absolute deadline for each complete read operation, and a write-all loop for response statuses. The server lifecycle now uses atomic running/active-connection counters, rejects excess active clients, tracks worker threads, and joins tracked workers when the accept loop ends. This lifecycle change is still uncompiled and requires stress testing. These are source changes only: compilation and runtime tests have not yet verified them. The remote-bind gate now requires TLS 1.3, client-certificate verification, allowlisted certificate identity, and explicit service/operation authorization. These controls remain unverified until CI and runtime security tests pass.
| Area | Current observation | Priority / status |
|---|---|---|
| Network exposure | CLI and ServerConfig now default to 127.0.0.1:19866; non-loopback CLI binding requires --allow-remote. | Initial mitigation committed; tests pending |
| Authentication and transport security | Inspected server path does not implement built-in TLS or authenticated peer identity. | Critical / outstanding |
| Worker lifecycle | Detached threads were replaced with tracked joinable workers and a join phase after the accept loop. Shutdown races, blocked-client interruption, and repeated start/stop still require testing. | Partial / tests pending |
| Concurrency state | running_ and active-connection accounting now use atomics. Listener descriptor access and stop/accept coordination still need a fully defined synchronization strategy. | Partial / tests pending |
| Connection limits | An active-connection counter now rejects excess clients with status 503; backlog and active-worker limits remain separate. Stress testing and invalid-config checks remain outstanding. | Partial / tests pending |
| Socket handling | Response status writes now retry partial sends; each read_exact call uses an absolute deadline. Interrupted writes are retried on POSIX. Cross-platform compile/runtime tests remain pending. | Partial / tests pending |
| Rate limiting | Inspected rate check is per connection and uses an elapsed-time integer average, not a global/per-peer windowed limiter. | High / outstanding |
| Input validation | CLI port/packet-size parsing and protocol header integer bounds improved. Header grammar, semantic field validation, and regression tests remain outstanding. | Partial / tests pending |
| Service dispatch | Accepted packets receive an admission status but are not routed through a verified application-service handler path. | High / outstanding |
| Build/documentation alignment | Annotation bridge build integration and generation-specific protocol claims need reconciliation with the code. | High / outstanding |
| Platform support | Socket descriptors are stored as int; Windows SOCKET handling and documented platform builds need validation. | High / outstanding |
| Firewall lifecycle | Port-awareness documentation exists, but the inspected server does not itself apply firewall rules. | Medium / decision required |
Safe operating posture: Keep the listener local-only unless the service is placed behind a deliberately configured, authenticated, access-controlled deployment boundary. Do not expose the current server directly to untrusted networks.
1. Stabilize Transport and Input Handling
Goal: Make packet I/O predictable under partial reads, partial writes, malformed input, and slow clients.
- [ ] Implement a write-all loop for TCP responses; handle partial sends, interruption, disconnects, and platform-specific socket errors.
- [ ] Use a monotonic deadline for each complete frame/header/payload read instead of restarting the full timeout after every partial read.
- [ ] Keep the CLI validation already added and add tests for port boundaries, invalid numeric syntax, overflow, missing values, unknown flags, and packet-size boundaries.
- [x] Validate protocol-grade, flags, stream/request/sequence numeric header values before narrowing or accepting them. Committed; tests pending.
- [ ] Complete semantic validation of fixed-header flags, reserved fields, header grammar, and cross-field invariants.
- [ ] Apply explicit upper bounds to header, payload, and total packet sizes; use overflow-safe arithmetic before allocation.
- [ ] Validate header names and values according to the wire protocol, including control characters and required fields.
- [ ] Ensure parser failures cannot leave partially trusted packets eligible for dispatch; make
reject_malformedbehavior effective and documented. - [ ] Ensure response/log events reflect the actual send result; do not log a response as sent before the socket write succeeds.
- [ ] Add tests for truncated frames, oversized lengths, duplicate headers, invalid numeric fields, partial writes, peer disconnects, and slow/trickling clients.
Exit criteria: Partial operations are handled correctly; all untrusted lengths and numeric fields are validated; transport tests pass on each supported platform.
2. Correct Concurrency, Limits, and Shutdown
Goal: Enforce resource limits and guarantee that server-owned state remains alive while client workers use it.
- [x] Replace detached client threads with tracked joinable workers and join them after the accept loop exits. Committed; lifecycle tests pending.
- [x] Enforce
max_connectionsas an active-connection limit separate from thelisten()backlog. Committed; stress tests pending. - [x] Make the running flag and active-connection count atomic. Committed.
- [ ] Define synchronization for listener descriptor access, active sockets, and concurrent
stop()/run()calls. - [ ] Stop accepting new connections, interrupt or close active work safely, join workers, then destroy packet loggers and shared state.
- [ ] Verify cross-platform behavior when closing a listening socket while another thread is blocked in
accept(). - [ ] Ensure Winsock startup and cleanup are paired on every success and failure path.
- [ ] Add global and per-peer rate limits with a defined time window and burst policy.
- [ ] Implement a real failure-rate policy if
max_failures_per_minuteis an enforcement control; otherwise rename/document it as a heuristic. - [ ] Add stress tests for concurrent clients, connection floods, shutdown under load, repeated start/stop cycles, and logging during shutdown.
Exit criteria: No worker can outlive the server; limits are enforced; shutdown is deterministic and stress-tested.
3. Establish the Security Boundary
Goal: Prevent unauthenticated or unauthorized remote clients from reaching sensitive services.
- [ ] Keep the loopback default and explicit remote-bind gate; test both the CLI path and direct
ServerConfiguse. - [ ] Implement TLS 1.3 with certificate validation, or document and test a supported authenticated tunnel/proxy deployment. A bind flag or firewall alone is not authentication.
- [ ] Define authenticated peer identity and service/operation authorization policies.
- [ ] Treat source IP, packet metadata, grades, classifications, and annotation fields as untrusted claims rather than identity or privileges.
- [ ] Define replay protection and request uniqueness for operations with side effects.
- [ ] Keep secrets out of logs and errors; define log permissions, rotation, retention, and disk-exhaustion behavior.
- [ ] Document firewall exposure, trusted-proxy assumptions, certificate handling, secret rotation, and production deployment requirements.
- [ ] Add negative tests for unauthenticated peers, unauthorized operations, invalid/expired credentials, replayed requests, and spoofed proxy metadata.
- [ ] State which controls are native to the server and which are deployment-provided; test the shipped path end to end.
Exit criteria: The trust model is implemented and documented; security tests demonstrate enforcement; remote exposure is deliberate and protected.
4. Complete Service Integration, Port Awareness, and Release Verification
Goal: Ensure the implementation matches the documented architecture and behaves consistently across supported platforms.
- [ ] Define a service-dispatch interface and route accepted packets to registered handlers.
- [ ] Inspect and test the annotation bridge API; include it in the build if intended to ship, or correct claims about the current implementation.
- [ ] Integrate port-awareness lifecycle behavior if required, including cleanup and rollback; otherwise document that firewall management is external.
- [ ] Reconcile
HTTP-GENERATIONS.mdwith the implementation. Distinguish SLPK framing from native HTTP parsing and generation-specific adapters. - [ ] Align Makefile sources and dependencies with Linux, macOS, and Windows build instructions.
- [ ] Use platform-correct socket types and startup/cleanup paths.
- [ ] Add automated build and test jobs for every platform claimed as supported.
- [ ] Run protocol, malformed-input, concurrency, lifecycle, authorization, and end-to-end service-dispatch tests.
- [ ] Update operational documentation with tested capabilities, limitations, defaults, and reproducible verification commands.
Exit criteria: Documentation matches tested behavior, advertised platform builds pass, and integration tests pass.
5. Formalize Standards, Secure Development, and Supply-Chain Controls
Goal: Turn security expectations into repeatable engineering checks and evidence-based release decisions.
- [ ] Maintain a threat model covering assets, trust boundaries, attackers, abuse cases, and mitigations.
- [ ] Use CWE categories to track each confirmed weakness and its remediation/test evidence.
- [ ] Map applicable requirements to OWASP ASVS as a verification checklist; record applicability and exceptions rather than claiming blanket compliance.
- [ ] Align development and release workflows with NIST SP 800-218 SSDF: review, testing, vulnerability response, and release evidence.
- [ ] Use compiler warnings and static analysis; add AddressSanitizer/UndefinedBehaviorSanitizer builds where supported and appropriate.
- [ ] Add fuzzing for packet framing, header parsing, numeric conversions, and malformed-input paths.
- [ ] Track third-party dependencies, versions, provenance, and known vulnerabilities; use dependency scanning where applicable.
- [ ] Protect release artifacts and checksums; document how source, build inputs, and artifacts are linked.
- [ ] Add a security-reporting contact and a process for triage, patching, and communicating vulnerabilities.
- [ ] Keep test evidence tied to a specific commit; do not infer compliance from a document or checklist alone.
Exit criteria: Security requirements are traceable to code and tests; analysis/fuzzing/dependency checks are repeatable; vulnerabilities have an ownership and response path.
6. Establish Protocol Conformance, Observability, and Production Operations
Goal: Make deployments diagnosable and ensure protocol claims, operational behavior, and release evidence are verifiable.
- [ ] Define a versioned protocol specification with required/optional fields, canonical numeric ranges, framing limits, error codes, compatibility rules, and unknown-field behavior.
- [ ] Add golden test vectors and independent client/server interoperability tests for every supported protocol version.
- [ ] Define compatibility and deprecation rules; test backward/forward compatibility instead of relying on generation labels alone.
- [ ] Standardize structured log event names, timestamps, correlation IDs, and result fields while redacting secrets and sensitive payload data.
- [ ] Add operational metrics for active connections, rejected frames, timeout counts, rate-limit actions, handler latency, and internal errors; avoid high-cardinality labels and sensitive data.
- [ ] Add health/readiness behavior that does not expose sensitive configuration or treat a listening socket as proof that application services are healthy.
- [ ] Define graceful shutdown, restart behavior, log rotation, retention, disk-full handling, and resource limits in deployment documentation.
- [ ] Document service ownership, authorization policy, firewall/network requirements, backup/recovery needs for any durable state, and incident response steps.
- [ ] Add deployment smoke tests and a release checklist that records commit, compiler/toolchain, platform, test results, known issues, and rollback instructions.
- [ ] Review public claims and examples for accuracy; label unimplemented adapters, features, and standards mappings as planned rather than supported.
Exit criteria: Protocol behavior is testable and versioned; operational signals and runbooks exist; production releases have reproducible evidence and rollback guidance.
Implementation and Verification Record
Update this table only with evidence-backed status. A documentation change alone does not make an implementation item verified.
| Workstream | Owner | Implementation (file + commit/PR) | Verification (test/command + result) | Status |
|---|---|---|---|---|
| 1. Transport and input handling | TBD | server.cpp, sleela_server.cpp — commits 3af3b46, cca533e | Build/runtime/regression tests not run | In progress — CLI/header validation and basic I/O hardening committed; tests pending |
| 2. Concurrency, limits, and shutdown | TBD | sleela_server.hpp, sleela_server.cpp — commits b0666ce, a3186c9 | Build/stress/shutdown tests not run | Partial — active limit and tracked workers implemented; lifecycle hardening/tests pending |
| 3. Security boundary | TBD | Loopback default and remote-bind gate committed | Not run | Partial — TLS/authentication/authorization outstanding |
| 4. Service integration and release verification | TBD | TBD | Not run | Not started |
| 5. Standards and secure development | TBD | SECURITY-STANDARDS.md | Not run | Planning baseline |
| 6. Protocol and production operations | TBD | TBD | Not run | Not started |
Status meanings: Not started / In progress / Implemented, tests pending / Verified.
A feature is Verified only after the implementation and relevant tests have been reviewed and passed. Keep static-review observations separate from build, runtime, and security-test results.
Review References
- Server implementation
- Server interface and configuration
- Command-line entry point
- Build configuration
- Security and standards baseline
- Wire protocol
- Production guidance
- Port-awareness contract
- HTTP generation notes
- Annotation language notes
- Annotation forwarding notes
- Logging and heuristics
- Server Edition README
Document date: 2026-10-26
Baseline branch: master
Baseline note: The loopback-default, CLI validation, strict protocol numeric parsing, absolute read deadline, response write-all, active connection limit, atomic state, and tracked-worker changes are committed but have not been compiled or tested as part of this review. Remaining items are not claimed complete.
Next Implementation Notes — Priorities 1–6
Added: 2026-10-26 Purpose: Record the next concrete engineering priorities identified after the initial concurrency and transport changes. These notes supplement the six workstreams above; they do not mark any item verified.
1. Shutdown Correctness and Socket Ownership
- [ ] Define one synchronization strategy for listener descriptor ownership, run(), and concurrent stop() calls.
- [ ] Ensure stopping the server reliably interrupts a blocked accept() on each supported platform without descriptor-reuse races.
- [ ] Track active client sockets so shutdown can interrupt blocked client reads and writes before joining workers.
- [ ] Ensure worker joining cannot deadlock, including when shutdown is initiated from an unexpected call path.
- [ ] Pair Winsock startup/cleanup across all success and failure paths; close each socket exactly once.
- [ ] Add repeated start/stop, stop-during-accept, stop-during-read, and shutdown-under-load tests.
Acceptance evidence: Sanitizer-enabled and stress tests show deterministic shutdown, no deadlocks, descriptor reuse races, use-after-free, or double closes.
2. Resource Management and Slow-Client Resistance
- [ ] Validate configuration values, including nonzero and reasonable max_connections, packet/header/payload limits, and timeout values.
- [ ] Ensure a slow or idle client cannot occupy a worker indefinitely; apply absolute deadlines to the entire request lifecycle, not only individual reads.
- [ ] Revisit retained thread handles: avoid joining an older worker synchronously on the accept thread where that worker may still be serving a long-lived client.
- [ ] Prefer a bounded worker pool or another explicitly bounded scheduling model with documented queue/rejection behavior.
- [ ] Implement global and per-peer rate limits with a defined time window and burst policy; avoid relying on per-connection averages.
- [ ] Add load tests for connection floods, slowloris-style trickling, long-lived clients, and maximum-size frames.
Acceptance evidence: Tests demonstrate bounded threads, memory, sockets, and response latency under documented load; excess work is rejected predictably.
3. Protocol Correctness and Malformed-Frame Isolation
- [ ] Validate the fixed header's magic, version, flags, reserved fields, and every encoded length before allocation or parsing.
- [ ] Enforce one consistent total-frame limit with overflow-safe arithmetic across header, payload, and fixed-header sizes.
- [ ] Enforce max_header_bytes and max_payload_bytes independently and consistently with max_packet_bytes.
- [ ] Make parsing transactional: a failed parse must not leave a partially populated packet eligible for inspection or dispatch.
- [ ] Validate header names, required fields, field lengths, control characters, unknown fields, and duplicate-field behavior according to the wire specification.
- [ ] Define and test behavior for malformed input, truncated frames, trailing bytes, unsupported versions, and unknown flags.
- [ ] Make the configured reject_malformed option effective or remove it if it cannot be supported clearly.
Acceptance evidence: Unit tests and fuzzing show malformed or oversized input is rejected without unsafe allocation, parser-state leakage, or service dispatch.
4. Real Service Dispatch
- [ ] Define a service-handler interface with explicit registration, request context, response type, error mapping, and lifecycle ownership.
- [ ] Dispatch packets only after framing, parsing, authorization, and policy checks succeed.
- [ ] Return a clear unsupported-service/unsupported-operation response when no handler is registered; do not imply that an admitted packet was executed.
- [ ] Define handler deadlines, cancellation, exception containment, and concurrency guarantees.
- [ ] Add tests for registered handlers, unknown services, unknown operations, denied services, handler errors, and concurrent requests.
- [ ] Update README and protocol documentation to distinguish transport acceptance from successful application execution.
Acceptance evidence: End-to-end tests prove a valid request reaches the intended handler and receives its defined result, while denied or malformed requests never reach it.
5. Authentication, Transport Security, and Authorization
- [ ] Preserve loopback-only defaults and the explicit remote-bind acknowledgement until a secure deployment path is implemented.
- [ ] Select and implement a maintained TLS integration (or a documented authenticated reverse-proxy boundary); specify certificate validation and rotation.
- [ ] Establish authenticated peer identity before applying identity-based service permissions.
- [ ] Define authorization for service and operation identifiers, with deny-by-default behavior for protected handlers.
- [ ] Ensure secrets, credentials, tokens, and sensitive payloads are not logged.
- [ ] Document trust boundaries, certificate/key handling, revocation or expiry policy, and secure deployment examples.
- [ ] Add negative tests for unauthenticated clients, invalid/expired certificates, unauthorized services, and downgrade/misconfiguration scenarios.
Acceptance evidence: Security tests demonstrate that remote access cannot reach protected services without the documented authenticated and authorized path. The --allow-remote option alone must never be described as security.
6. Automated Verification and Release Gate
- [ ] Add reproducible Linux, Windows, and macOS builds for the platforms the project claims to support.
- [ ] Add unit tests for parsing and policy decisions, integration tests for client/server exchanges, and stress tests for concurrency and shutdown.
- [ ] Add malformed-frame fuzzing and compiler/static-analysis jobs; use address/undefined-behavior sanitizers where supported.
- [ ] Test partial reads/writes, peer disconnects, timeouts, maximum-size packets, connection caps, and restart behavior.
- [ ] Record test results against the exact commit and toolchain; preserve logs/artifacts for failures.
- [ ] Add a release checklist covering supported platforms, protocol compatibility, known limitations, security configuration, and rollback instructions.
- [ ] Do not label the server production-ready until all critical/high-risk acceptance criteria are passed or formally documented as release-blocking exceptions.
Acceptance evidence: Required CI jobs pass on the release commit, test artifacts are retained, and known limitations are disclosed in release documentation.
Tracking status for these notes
| Priority | Current status | Blocking evidence |
|---|---|---|
| 1. Shutdown correctness | In progress; not verified | Socket ownership, stop/accept synchronization, active-client interruption, stress tests |
| 2. Resource management | Partial; not verified | Bounded worker scheduling, slow-client controls, global/per-peer rate limits, load tests |
| 3. Protocol correctness | Partial; not verified | Complete frame validation, transactional parsing, fuzz/regression tests |
| 4. Service dispatch | Not implemented/verified in this review | Handler contract and end-to-end dispatch tests |
| 5. Security boundary | Partial; not verified | TLS or authenticated boundary, peer identity, authorization tests |
| 6. Automated verification | Not run | Cross-platform CI, unit/integration/stress/fuzz evidence |
Important: These notes are an implementation backlog and acceptance checklist. Committed source changes remain uncompiled and untested until verified by actual build and test runs.
Implementation Progress — 2026-10-26
The following incremental work has been committed toward priorities 1–6. This is a progress record, not a claim that all six priorities are complete.
- Priority 1 — Shutdown/socket ownership: Still open. The current listener-close/accept race and interruption of blocked client workers require a dedicated lifecycle change and platform testing. Do not treat shutdown as verified.
- Priority 2 — Resource/configuration bounds: Added startup validation for zero/oversized connection limits, invalid packet/header/payload relationships, zero idle timeout, and zero packet-rate configuration. A bounded worker pool, global/per-peer rate limits, and slow-client load tests remain outstanding.
- Priority 3 — Protocol/input correctness: Header parsing now stages changes in a candidate packet and commits only on success; header names and control characters are checked; fixed-header version-one flags must be zero and fixed/header flags must agree. A protocol regression test source and
make testtarget were added. Tests have not been run in this environment. - Priority 4 — Service dispatch: Not implemented. The current server still returns an admission response; it must not be described as executing application services.
- Priority 5 — Authentication/security: Not implemented. Loopback default and remote-bind warning remain the safety boundary; built-in TLS, authenticated peer identity, and operation-level authorization are outstanding. Do not expose directly to untrusted networks.
- Priority 6 — Automated verification: Added parser regression coverage and a Makefile test target, but no build, test, fuzzing, or cross-platform CI result is available yet. Add and run the remaining test matrix before release.
Commits in this progress batch: 8dda7c4 (configuration checks and transactional parsing), be6be1b (frame/flag consistency), 20af280 (parser regression tests), e01cbfe (test target), and f034f00 (wire-protocol documentation).
Priority 5 Implementation Update — Mutual TLS and Authorization (2026-10-26)
Source and documentation changes have been committed for the initial native security boundary:
- Added TLS 1.3-only server configuration using OpenSSL.
- TLS mode requires a server certificate/key pair and a client CA; the TLS context requests and requires a verified client certificate.
- Client identity is extracted from the verified certificate Common Name and must match an explicit
--allow-peerentry. - Requests over TLS are authorized by exact
--authorize ID:SERVICE:OPERATIONrules. Missing rules deny the operation; packet metadata is not used as identity. - The CLI rejects incomplete TLS configuration and refuses non-loopback binds unless
--allow-remote, the full TLS configuration, an allowlisted identity, and explicit permissions are supplied. - The Makefile links OpenSSL, and README/security documentation describes the configuration.
Not yet verified: No build or test run has been completed. Certificate revocation/rotation, TLS handshake tests, cross-platform OpenSSL packaging, slow-handshake limits, rate limiting, replay protection, and production security review remain required. Treat this as implemented source, not a verified production-ready security release.
Commits: 2ebe3c3, 2307d78, aeacc3a, 75a4a31, d550d4f, 95d548c, c34e370, 2cb47c6, b824e15, a527700.
Security verification and network-awareness update — 2026-10-26
Committed source changes now:
- Explicitly restrict TLS 1.3 ephemeral key-exchange groups to
X25519:P-256:P-384through OpenSSL. The integration test now offers only X25519 and requires a successful TLS 1.3 handshake; execution is pending CI. - Add
tools/nat-awareness.py, an opt-in STUN binding probe that reports the local source address and externally mapped address. It makes no router/firewall changes and does not claim to prove inbound reachability or classify every NAT type. - Add unit tests for STUN request framing, XOR-MAPPED-ADDRESS parsing, transaction validation, and truncated responses.
- Extend
make testto run both the C++ protocol suite and Python NAT parser tests. - Add
.github/workflows/server-edition-security.ymlwith Linux/macOS build and test jobs plus a Windows MSYS2 build/test job.
Verification state: The workflow has been committed but its results have not been observed in this session. A local build was attempted but this environment could not resolve github.com, so no local compile or test result is available. Do not mark the release gate passed until the actual GitHub Actions jobs complete successfully. Follow-up required: integration tests for valid/invalid client certificates, identity allowlist failures, unauthorized service operations, negotiated TLS group, NAT discovery timeouts, and platform-specific socket lifecycle behavior.
Additional security test gate
The test target now also runs tests/test_tls_integration.py, which creates temporary local test certificates and checks a trusted TLS 1.3 client, an unauthorized operation (expected 403), a client without a certificate, and a client certificate signed by an untrusted CA. The test binds only to 127.0.0.1 and does not touch router configuration. These tests have been added but have not yet run in GitHub Actions in this session.