alknet/tasks/core/three-remote-roles-docs.md at df355c53a945d799d7c8e03536084b9c1242a708

Files

glm-5.2 df355c53a9 tasks: decompose ADR-029/030/031/032/034/035 source sync into 17 tasks

Decompose the source-to-spec sync for the core and call crates into atomic,
dependency-ordered tasks for implementation agents:

Core (7 tasks + review):
- peer-entry-model: PeerEntry struct, AuthPolicy.peers (ADR-030 keystone)
- credential-store-trait: CredentialStore/InMemoryCredentialStore/StoreError (ADR-031/035)
- identity-store-trait: IdentityStore async write trait (ADR-035)
- config-identity-provider-peerentry: ConfigIdentityProvider PeerEntry resolution (ADR-030)
- fingerprint-normalization: ed25519:hex for raw keys across quinn/iroh (ADR-030 §6)
- three-remote-roles-docs: document ADR-034 roles and verifier selection
- review-core-sync: phase gate before call consumes new identity semantics

Call (9 tasks + review):
- retire-remote-safe: remove ADR-028 machinery, AccessControl is the gate (ADR-029 §3)
- operation-context-forwarded-for: forwarded_for field, wire-ingress only (ADR-032)
- peer-composite-env: PeerCompositeEnv, PeerId=Identity.id, remove UUID (ADR-029/030)
- operation-env-invoke-peer: invoke_peer/peer_contains/PeerRef (ADR-029 §2)
- services-list-accesscontrol-filtered: AccessControl filter, list-peers opt-in (ADR-029 §6)
- call-client-verifier-selection: TLS client-auth, verifier by PeerEntry (OQ-29, ADR-034)
- from-call-forwarded-for: populate forwarded_for, peer-keyed registration (ADR-029 §5, ADR-032)
- dispatch-peer-identity: AccessControl::check(peer_identity), PeerId from resolution (ADR-029 §3, ADR-030 §5)
- review-call-sync: phase gate for the call sync

Validated: 58 tasks, no cycles, logical topo order, two review checkpoints.

2026-06-28 21:08:41 +00:00

3.7 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level

name

status

depends_on

scope

risk

impact

level

core/three-remote-roles-docs

Document the three remote roles and client-side verifier selection rule (ADR-034)

pending

core/peer-entry-model

single

trivial

isolated

implementation

Description

Update the in-code comments and doc comments in alknet-core/src/auth.rs and alknet-core/src/endpoint.rs to document the three remote roles (ADR-034) and the client-side verifier selection rule. This is a documentation/comment task — the server-side endpoint code is unchanged; the client-side verifier selection is a call-side task (call/call-client-verifier-selection).

Three remote roles (ADR-034 §1)

Role	Identity	alknet peer?	`PeerEntry` on local side?
Public X.509 endpoint	Domain + CA-issued X.509	No (local node is a client)	No
Transport relay (iroh's DERP-equivalent)	iroh `NodeId` (Ed25519)	No (infrastructure)	No
Hub / hosting node	Ed25519 raw key and/or X.509	Yes (full peer)	Yes

PeerEntry (and the PeerId it resolves to) is the model for peers in the call-protocol peer graph (ADR-029). A pure-client connection to a public X.509 endpoint is not in that graph on the client side: no PeerEntry, no PeerId, no PeerRef::Specific routing.

Client-side verifier selection rule (ADR-034 §3)

Local has `PeerEntry` for remote?	Remote cert type	Client verifier
No (public X.509 endpoint)	X.509	`WebPkiServerVerifier` (CA verification)
No	Ed25519 raw key	fails closed (no CA to fall back to)
Yes (hub, Ed25519 path)	Ed25519 raw key	fingerprint match (`ed25519:<hex>`)
Yes (hub, X.509 path)	X.509	fingerprint match (`SHA256:<hex>`)

What to update

auth.rs doc comments: add the three-roles table and the verifier selection rule to the Identity / PeerEntry section doc comments, referencing ADR-034. The auth.md spec already has this; mirror it in the source comments.
endpoint.rs doc comments: clarify that the server-side AcceptAnyCertVerifier is "request-but-don't-require" mode for fingerprint extraction (unchanged), and that the client-side verifier selection is by PeerEntry presence (ADR-034 §3) — note that this is a CallClient concern, not an endpoint concern.
No code changes — this is comments/docs only. The server-side endpoint is unchanged by ADR-034. The client-side verifier is call/call-client-verifier-selection.

Acceptance Criteria

auth.rs doc comments document the three remote roles (ADR-034 §1)
auth.rs doc comments document the client-side verifier selection rule (ADR-034 §3)
endpoint.rs doc comments clarify server-side vs client-side verifier concerns
Comments reference ADR-034 and auth.md
No code changes (comments only)
cargo test -p alknet-core succeeds (no regressions from comment changes)
cargo clippy -p alknet-core succeeds with no warnings

References

docs/architecture/crates/core/auth.md — Three Remote Roles, Client-side verifier selection
docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md — ADR-034

Notes

Documentation-only task to ensure the three-roles model and verifier selection rule are visible in the source, not just the specs. The server-side endpoint is unchanged by ADR-034; the client-side verifier selection is implemented in call/call-client-verifier-selection. Folding this into a standalone task keeps the fingerprint-normalization and resolution-logic tasks focused on code, not prose.

Summary

To be filled on completion

3.7 KiB Raw Blame History