DEVELOPMENT DOCUMENTATION / ARCHITECTURE

An outbound connection with scoped authority.

The relay connects a consumer to a specific enrolled device and service. Authorization and local export policy both constrain what can happen.

Authorized consumer
        | HTTPS or filesystem WebSocket
        v
Relay ingress -- private mTLS HTTP/3 --> owning relay
        |                                  |
        +----- Redis authority catalog ----+
                                           ^
                          outbound mTLS WebSockets
                                           |
                              Enrolled device client
                              /     |      |      \
                            MCP    files   ACP    CUA

Three transport roles

Permissions are not implied by connectivity

Authority is scoped by tenant, principal, device, service and permitted operations. Local configuration defines exports. A connected computer is not an unrestricted remote desktop or shell.

Two sockets in steady state

Each device uses one control and one data socket. Ordered data-socket rotation permits a bounded temporary third socket while old streams drain. Transport acknowledgements do not prove an application side effect completed.

Finite echo retention

Current main implements owner-issued STREAM_FORGET for successfully completed finite echoes and explicitly rejected opens, reclaiming connector retention only after the required terminal and acknowledgement evidence. Cleanup waits while rotation or recovery holds the stream roster. Rotation fencing now includes the dispatched FIN and preserves completed echoes until the attempt finishes.

These are scoped fixes, not complete echo or transport acceptance. Repository regression gates cover more than 128 sequential echoes and echoes crossing rotations; they were not rerun for this website review. Cancellation, RESET, authorization invalidation and timeout cleanup remain open, as does automatic session replacement when retained opens exhaust capacity. See support boundaries.

State and recovery

Redis is the authoritative catalog and coordination store. Process-local sockets and in-flight work are ephemeral. The supported coordination profile uses one authoritative Redis primary; replication is not a promise of automatic, lossless failover. Recovery must reconcile revocations and fence old ownership.

A Redis restart changes its run identity. Current main has a narrow, single-relay path to keep the namespace after an in-place restart from the same durable AOF: a serving relay can verify its continuity token, or an operator can attest the restart using rebind-redis-run. See the prerequisites and exclusions. Neither path is backup-restore or failover recovery. Cluster Redis restarts, restores and ambiguous authority still need externally approved recovery; its signing authority is not shipped. A fresh namespace is a new deployment, not restoration of old authorization. Never delete authority keys to bypass fencing.

Cluster readiness

In current main, /readyz and public admission both require a non-empty verified transport key-pin set, alongside membership and peer readiness. If those pins are withdrawn, readiness fails and public work is refused even before the next peer refresh. Restoring pins alone is not enough if another readiness condition still fails.

This check applies to the cluster peer runtime, not the non-cluster M1/M2 profile. Readiness is an admission check, not proof of an end-to-end service operation or full cluster acceptance. Source and regression tests cover pin withdrawal and recovery; deployment-specific verification remains required.

Trust boundary

Private keys stay outside the catalog. Diagnostics should expose identifiers, phases and counters, not payloads or credentials. Never automatically replay an ambiguous click, write or agent prompt after losing its outcome.