List executors with RIPE Atlas-style addresses (API 1.16)

[vincent10400094]

Summary

The public executor listing follows the RIPE Atlas probe model for addresses and privacy (API 1.16).

• GET /executors adds is_public, address_v4, address_v6, prefix_v4, prefix_v6, asn_v4, asn_v6 and address_observations. The result admission snapshot records the same fields as provenance.vantage_point.addressing (result format 1.1, schema 1, additive).
• Observed addresses only. An address is the peer of one of the executor's authenticated connections (certificate plus current control-session credentials): the control connection (via: control, preferred for its family, observed_at = last heartbeat of that session) or the existing ReflectAddress call (via: reflection, observed_at = receipt). The dispatcher records the TCP peer, never a request value; public_host and the hello source IP stay operator-only claims. Observations end with the control session, as connectivity proof already does, so a moved executor does not keep its old address.
• Second family. No new RPC: executors call the existing ReflectAddress over each family every 10 minutes, resolving the host of dispatcher.addr and verifying the dispatcher certificate for that name (a resolved address that is not the dispatcher fails TLS). Families with a configured reflector are skipped, since their 30 s check already reflects. [connectivity] observe_addresses = false turns it off. It feeds the listing only, never the connectivity report or admission.
• Prefix/ASN come from the existing offline ASN lookup (Add offline ASN and approximate location metadata #351): the control family reuses ip_metadata.observed.asn, the reflected family is looked up on receipt. No change to the lookup source, so feat/ris-asn-database slots in unchanged.
• Privacy. [metadata] address_opt_out = true (protocol field VantagePointReport.address_opt_out = 13, read at registration like location_opt_out) makes the executor private: the public listing withholds both addresses and nothing else. Established operators still see them; the run owner sees them in provenance. is_public and location_opt_out are independent, as in RIPE Atlas (a private probe keeps its location public; location is the host's own choice). Rationale is in docs/vantage-points.md#privacy.
• Compatibility. Additive wire fields; older clients ignore them. Older executors don't send the flag and are public (the requested default). This changes privacy for existing deployments: the control-connection source IP, operator-only until now, becomes public on dispatcher upgrade. The CHANGELOG and privacy note say to upgrade and set address_opt_out first to stay private. /executors/by-ip and /attribution/candidates are unchanged.
• dbl nodes adds ADDRESS_V4 and ADDRESS_V6 columns (private when withheld, - when unknown, invalid values are not printed); --output json carries every field.

Example entry (other fields elided):

{
  "id": "eth-zurich-1",
  "is_public": true,
  "address_v4": "192.0.2.10",
  "address_v6": "2001:db8:10::7",
  "prefix_v4": "192.0.2.0/24",
  "prefix_v6": "2001:db8::/32",
  "asn_v4": 64500,
  "asn_v6": 64500,
  "address_observations": {
    "v4": {"source": "dispatcher-observed", "via": "control", "observed_at": 1791250000, "lookup_source": "database:GeoLite2-ASN@1790000000", "lookup_reason": ""},
    "v6": {"source": "dispatcher-observed", "via": "reflection", "observed_at": 1791249700, "lookup_source": "database:GeoLite2-ASN@1790000000", "lookup_reason": ""}
  }
}

Coordination

• API 1.16 is also claimed by draft Verify captured probes before key disclosure through the executor #382; whichever merges second renumbers.
• No overlap with the functions touched by Stop tagging when the clock cannot place packets in their epochs #376/Record destination opt-outs durably and revoke their traffic on executors #379/Verify captured probes before key disclosure through the executor #382: one field in VantagePointReport (13), one line in capabilityReport beside LocationOptOut, one struct field each in Executor/RegisteredExecutor, and one line in RegisterExecutor. The rest is new files (internal/dispatcher/probe_addresses.go, internal/executor/address_observation.go, pkg/wire/probe.go).

Testing

• go test for internal/dispatcher/..., internal/executor/..., pkg/..., cmd/dbl (macOS-only failures in cmd/dbl executor-join, internal/executor/debuglet listener quota and the canary driver also fail on main locally; CI runs them on Linux).
• New: control vs reflection preference, private hides only addresses, claimed source never published (internal/dispatcher/probe_addresses_test.go); real IPv6 reflection over [::1] through ReflectAddressAs and no carry-over to a replacement session; HTTP listing public/private/operator views validated against the OpenAPI contract (internal/dispatcher/transport/api/probe_addresses_test.go); config defaults; reflection targets; dbl nodes columns.
• scripts/ci-generate.sh write-proto, gofmt, go vet.

🤖 Generated with Claude Code

[vincent10400094]

Reviewed rebased head 2624bf9. Address observations are authenticated dispatcher-peer observations, never executor-provided values; the public listing has an explicit address opt-out; and the API/CLI/docs cover the resulting visibility and operator access. All required CI checks pass on this head. GitHub does not permit author self-approval, so this comment records the completed review before the authorized administrator merge.