glm-5.2
df355c53a9
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.
85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
---
|
|
id: core/three-remote-roles-docs
|
|
name: Document the three remote roles and client-side verifier selection rule (ADR-034)
|
|
status: pending
|
|
depends_on: [core/peer-entry-model]
|
|
scope: single
|
|
risk: trivial
|
|
impact: isolated
|
|
level: 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
|
|
|
|
1. **`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.
|
|
|
|
2. **`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.
|
|
|
|
3. **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 |