ATOR (Anyone Protocol) integration: ready to consume — guide + verified topologies in connector repo

[ALLiDoizCode]

Summary

The ATOR transport in @toon-protocol/connector is shipped (Epic 35) and a Town-facing integration guide + three verified end-to-end topologies have just landed in the connector repo. Filing this so the Town team has a clear pickup point if/when ATOR-enabled relay deployments are on the roadmap. No immediate action required from Town — this is awareness + a concrete spec.

What's available now

• Town integration guide — docs/ator-integration-for-town.md in the connector repo. Covers both consumption modes (embedded npm, standalone Docker), config schema, six gotchas, verification cookbook. Source: toon-protocol/connector#51.
• Verified topologies Town can study/lift directly:
  • make two-home-ator-local-up && make two-home-ator-local-verify — two connectors, real .anon HS rendezvous, offline (~3 min wall clock)
  • make standalone-test-ator-p2p — same topology over PUBLIC ATOR (~5-8 min, online)
• @anyone-protocol/anyone-client is bundled in ghcr.io/toon-protocol/connector:3.3.3 (verified). After toon-protocol/connector#52 lands it'll be a regular dep (no longer optional) so install reproducibility is CI-enforced.
• ghcr.io/toon-protocol/ator-sidecar:v0.4.10.0-beta image will be published by toon-protocol/connector#52. Town can pull this directly for compose-based sidecar deployments — no need to copy or rebuild.

What Town would need to build (8-item checklist from the guide)

• Decide: in-process embedded mode (Mode A) or Docker sidecar mode (Mode B), or both
• Add @anyone-protocol/anyone-client to packages/town's dependencies (Mode A) — or rely on the published connector image (Mode B)
• Extend the townhouse config generator to emit a transport: block when TRANSPORT_MODE=socks5 (currently always direct per docker-compose-townhouse.yml:39)
• If Mode B: extend docker-compose-townhouse.yml with an anon sidecar service (mirror the standalone-ator-p2p shape from connector repo) and rewire the connector container to network_mode: service:<sidecar>
• Reserve a persistent volume for hiddenServiceDir
• Tune timeouts (STREAM, SDK, settlement) for ATOR-paired peers — see latency table in the guide
• Audit logging for .anon leaks (anything passing peer URLs to log lines)
• Document for relay operators: make town-up-with-ator (or equivalent)

Six gotchas worth flagging now (full detail in the guide)

1. BTP authToken is empty-string by default — and BTP server accepts it (BTP_ALLOW_NOAUTH=false to opt out). Town's existing permissionless relay model already lives here.
2. First HS publish takes 30-90s — Town's startup probes / health checks need to budget for this.
3. ATOR latency — 3-hop ILP RTT is ~1.2-2.1s vs ~300ms direct. STREAM senders + per-call timeouts must be tuned.
4. .anon addresses are sensitive — DEBUG-only logging convention. Anything in Town that handles peer URLs needs the same hygiene.
5. Optional dep gotcha — if Town's install pipeline uses --omit=optional the SDK will be missing. Resolved upstream by toon-protocol/connector#52 when it lands.
6. Hidden-service directory persistence — delete ${hiddenServiceDir}/hostname and the next start publishes a NEW .anon URL; all peers lose reachability. Mount on a persistent volume.

BTP-server inbound-auth surprise (worth a closer read)

The BTP server validates inbound auth secrets against process.env.BTP_PEER_<peer-id-uppercase>_SECRET, NOT against peers[].authToken in YAML. The YAML token is only the OUTBOUND (client) secret. This asymmetry is documented in packages/connector/src/btp/btp-server.ts:573-588 and btp-client.ts:330 — and is easy to miss when wiring up permissioned peers. The connector repo's tools/two-home-ator-handshake/handshake.sh script handles the env-var wiring automatically; useful as a reference for whatever Town builds.

Roadmap alignment

This connects to the ATOR transport testing placeholder noted in your CLAUDE.md (port 28050 → 1080 SOCKS5 proxy, story 21.15). The connector-side work makes the underlying capability solid; the Town-side story can pick up from the guide when prioritized.

References

• Connector ATOR operator deployment guide: docs/ator-transport.md
• Town integration guide: docs/ator-integration-for-town.md (will be at the link above once PR #51 merges)
• Verification tooling + cookbook: tools/two-home-ator-handshake/README.md (in PR #51)
• Stacked PRs that need to merge in order: #51 then #52