ctf-ad-mirror-tool-rust/task_plan.md

# Rust rewrite plan

## Acceptance
One native executable with an async TCP engine and embedded web UI. No Python/runtime frontend build required for operation. Typed TOML configuration, atomic durable operator state, authenticated same-origin controls, reusable scoreboard connection, bounded networking resources, graceful shutdown, explicit replica delivery policies. Local functional/integration checks and Linux tests pass; benchmark results are measured and reproducible.

## Phases
1. [complete] Capture legacy behavior and verify ForcAD wire format; establish module contracts.
2. [complete] Async forwarding, lifecycle/metrics, backpressure and recoverable accept supervision.
3. [complete] Scoreboard clients, observed-health freshness and deterministic failover.
4. [complete] Authenticated API/persistence and literal legacy UI restoration with original interactions.
5. [complete] Native and Orb integration/failure tests, ForcAD library interoperability, browser checks and measured benchmarks. Final fixed-source gates passed.
6. [complete] R6 cancellation safety fixed and independently accepted; final validation, documentation and local release artifacts complete.

## Latest correction and review gate
- Original appearance/workflows restored; source CSS parity and browser checks recorded in `docs/verification.md`.
- Initial `docs/review.md` is historical. Final findings and resolution belong in `docs/final-review.md`; R6 is independently verified and final review is approved.
- New code must preserve original columns, primary/replica interaction, direct-IP custom proxies, robot, own-team status strip and counters.

## Global constraints
- User means upstream routing, not host firewall interception.
- Never drop chunks from a live replica silently. Strict mode uses bounded backpressure; isolation mode disconnects a lagging replica explicitly and counts/reports it. Availability and lossless mirroring cannot both be guaranteed for an indefinitely slower/unavailable replica.
- Existing sessions keep their selected target. Do not replay partially sent requests on another primary.
- Preserve TCP half-close; no inherited 3-second idle timeout.
- All fixtures use loopback/test addresses, not old configured hosts.
- Do not store passwords, keys, tokens, session values or flags in source or logs.
- No mandatory external UI CDNs. Single embedded frontend, accessible keyboard controls.

## Errors/research corrections
- Initial CTF skill path under `.agents` was wrong; correct installed path is `.codex/skills/ctf-attack-defense`.
- Guessed C4T-BuT-S4D ForcAD repository does not exist; discover canonical upstream before implementing its protocol.
- Integrated build briefly blocked by not-yet-created UI assets while UI implementer was working; not a Rust source failure.

## UI follow-up — 2026-10-23
- [complete] Fix dialog centering/overflow, selected-team wrapping and dark numeric inputs.
- [complete] Preserve invalid IP/add-form drafts; expose team add/rename and compact configuration/scoreboard help through existing API.
- [complete] Lightweight browser/functional checks and required Rust gates; preserve live demo state and migrate to data/demo before restart.

## Flag protection — 2026-10-23
- [complete] Optional per-service length-preserving tokenization; encrypted durable SQLite mapping cache; global fixed-shape format, environment key, TTL and capacity. Explain design before implementation.
- [complete] Streaming scanner handles all split positions, bounded candidate tail and timeout, EOF, unknown outgoing matches; encode once before replica fanout, decode primary replies only.
- [complete] UI opt-in/status, API/config/docs and tests for persistence, collision/capacity, wrong key, cache failure, isolation, TCP integrity/half-close.
- [complete] Fresh native/Orb gates and isolated smoke; preserve legacy UI and live demo state; journal/commit/checkpoint.

Design limits: stateful tokenization, not stateless same-length AEAD; XChaCha20-Poly1305 protects mappings on disk. Raw visible fixed-shape ASCII only; no TLS/compression/framing adapter. Incomplete possible flags may hold a protocol tail; bounded timeout closes rather than leaking. All clients get reverse translation, so not an authorization boundary. Disabled by default; no real game hosts/flags used.

Flag implementation issues recorded: cargo-add combined feature syntax rejected and corrected with separate calls; first module write preceded async mkdir and was retried after explicit directory creation; first test compile warned about unused Arc import, removed before Clippy gate. No failing runtime regressions so far. Final durability review upgraded SQLite synchronous from FULL to EXTRA; final native/Orb gates rerun on that source.