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.
This commit is contained in:
85
tasks/core/three-remote-roles-docs.md
Normal file
85
tasks/core/three-remote-roles-docs.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user