alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
glm-5.2
2026-06-28 21:08:41 +00:00
parent 4a52779460
commit df355c53a9
16 changed files with 2179 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
tasks/call/call-client-verifier-selection.md Normal file
View File

@@ -0,0 +1,177 @@
---
id: call/call-client-verifier-selection
name: Wire CallClient TLS client-auth and server cert verifier selection by PeerEntry presence (OQ-29, ADR-034)
status: pending
depends_on: [call/peer-composite-env]
scope: moderate
risk: high
impact: component
level: implementation
---
## Description
Wire the `CallClient` TLS client-auth (present Ed25519 key as RFC 7250 raw
public key client cert) and the server cert verifier selection by `PeerEntry`
presence. Per OQ-29 (resolved) and ADR-034 §2-3. This is the most
security-critical call-side change — TLS wiring and verifier selection.
### Current state
```rust
// crates/alknet-call/src/client/call_client.rs
fn build_quinn_client_config(_credentials: &CallCredentials, alpn: &[u8])
-> Result<quinn::ClientConfig, String>
{
let config = rustls::ClientConfig::builder()
.dangerous()
.with_custom_certificate_verifier(Arc::new(AcceptAnyServerCertVerifier)) // ← accepts ANY
.with_no_client_auth(); // ← doesn't present client cert
// ...
}
```
`AcceptAnyServerCertVerifier` is a security hole for X.509 (accepts any cert
without CA verification). `with_no_client_auth()` doesn't present the client's
Ed25519 key, so the server has no client cert to extract a fingerprint from —
the ADR-030 `PeerEntry` fingerprint → `peer_id` resolution path is not
activated for quinn connections.
### Target state (OQ-29 + ADR-034)
#### 1. TLS client-auth: present Ed25519 key as raw public key client cert
Replace `with_no_client_auth()` with presenting the client's Ed25519 key as an
RFC 7250 raw public key client cert. This is the client-side equivalent of the
server's `RawKeyCertResolver`. The `CallCredentials.tls_identity` carries the
`TlsIdentity::RawKey(Ed25519SecretKey)` (or X.509 cert pair).
```rust
fn build_quinn_client_config(credentials: &CallCredentials, alpn: &[u8])
-> Result<quinn::ClientConfig, String>
{
// 1. Client cert: present Ed25519 raw key (if configured)
let client_auth = build_client_auth(&credentials.tls_identity)?;
// 2. Server cert verifier: by PeerEntry presence (ADR-034 §3)
let verifier = select_server_verifier(&credentials.remote_identity)?;
let config = rustls::ClientConfig::builder()
.dangerous()
.with_custom_certificate_verifier(verifier)
.with_client_auth(client_auth); // ← present the key, not no_client_auth
// ...
}
```
#### 2. Server cert verifier selection by PeerEntry presence (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>`) |
`CallCredentials.remote_identity: Option<RemoteIdentity>` is load-bearing:
- `Some(fingerprint)` → known peer → fingerprint pin (the fingerprint IS the
trust anchor).
- `None` → no `PeerEntry` for the remote → CA verification for X.509, fail
closed for Ed25519 raw key. `None` is the public-X.509-endpoint state, not a
missing field. An implementer must not default `remote_identity` to a
placeholder, and must not treat `None` as "skip verification."
```rust
fn select_server_verifier(remote_identity: &Option<RemoteIdentity>)
-> Result<Arc<dyn ServerCertVerifier>, String>
{
match remote_identity {
Some(ri) => {
// Known peer → fingerprint pin
Ok(Arc::new(FingerprintPinVerifier::new(ri.fingerprint.clone())))
}
None => {
// Unknown remote → CA verification (WebPkiServerVerifier)
// For Ed25519 raw-key remotes, this fails closed (no CA).
// This is the public-X.509-endpoint path (ADR-034 §2).
let roots = rustls::crypto::aws_lc_rs::default_provider().root_certificates;
Ok(Arc::new(rustls::client::WebPkiServerVerifier::builder(roots.into()).build()?))
}
}
}
```
#### 3. FingerprintPinVerifier
A new `ServerCertVerifier` that pins a specific fingerprint:
- For `ed25519:<hex>` remotes: extract the raw Ed25519 pub key from the
presented cert and match against the pinned fingerprint.
- For `SHA256:<hex>` remotes: hash the cert DER and match against the pinned
fingerprint.
- No match → verification failure (connection rejected).
#### 4. CallCredentials
`CallCredentials` (already defined) carries the three credential dimensions:
```rust
pub struct CallCredentials {
pub tls_identity: Option<TlsIdentity>, // RFC 7250 raw key or X.509
pub auth_token: Option<AuthToken>, // call-protocol-level token
pub remote_identity: Option<RemoteIdentity>, // expected fingerprint (None = CA path)
}
pub struct RemoteIdentity { pub fingerprint: String }
```
`remote_identity: None` is load-bearing — the public-X.509-endpoint state
(ADR-034 §2). The implementation must not default it to a placeholder.
### What this task does NOT do
- Does NOT change the server-side endpoint (`AcceptAnyCertVerifier` in
alknet-core is unchanged — it's "request-but-don't-require" for fingerprint
extraction).
- Does NOT build `PeerCompositeEnv` (that's `call/peer-composite-env`, a
dependency) — but a connection with no resolved identity (no `PeerEntry`) gets
no `PeerId` and is not added to `PeerCompositeEnv` (that's handled in
`call/peer-composite-env` / `call/dispatch-peer-identity`).
## Acceptance Criteria
- [ ] `build_quinn_client_config` presents Ed25519 key as RFC 7250 raw public key client cert (replaces `with_no_client_auth()`)
- [ ] `select_server_verifier` selects verifier by `remote_identity` presence
- [ ] `Some(fingerprint)` → `FingerprintPinVerifier` (fingerprint match)
- [ ] `None` + X.509 → `WebPkiServerVerifier` (CA verification)
- [ ] `None` + Ed25519 raw key → fails closed (no CA to fall back to)
- [ ] `FingerprintPinVerifier` matches `ed25519:<hex>` (raw key extraction) and `SHA256:<hex>` (DER hash)
- [ ] `AcceptAnyServerCertVerifier` removed (security hole for X.509)
- [ ] `CallCredentials.remote_identity: None` is load-bearing (not defaulted to placeholder)
- [ ] No-env-vars invariant preserved (credentials from Capabilities, not env vars)
- [ ] Unit test: `FingerprintPinVerifier` matches correct fingerprint
- [ ] Unit test: `FingerprintPinVerifier` rejects wrong fingerprint
- [ ] Unit test: `select_server_verifier` returns CA verifier for `None`
- [ ] Unit test: client auth presents Ed25519 key (config built without error)
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/client-and-adapters.md — CallCredentials, verifier selection, TLS client-auth
- docs/architecture/crates/core/auth.md — Client-side verifier selection table
- docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md — ADR-034 §2-3
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030 §6 (fingerprint normalization)
## Notes
> Most security-critical call-side change. `AcceptAnyServerCertVerifier` is a
> security hole for X.509 — replaced by verifier selection by `PeerEntry`
> presence. `None` + X.509 = CA verification (public X.509 endpoint); `None` +
> Ed25519 = fail closed (raw-key remotes are always known peers). `Some` =
> fingerprint pin (known peer). The client presents its Ed25519 key as a raw
> public key client cert so the server can extract the fingerprint — this
> activates the PeerEntry fingerprint → peer_id resolution path on quinn.
## Summary
> To be filled on completion

129
tasks/call/dispatch-peer-identity.md Normal file
View File

@@ -0,0 +1,129 @@
---
id: call/dispatch-peer-identity
name: Wire dispatch_requested to resolve peer Identity and run AccessControl::check (ADR-029 §3, ADR-030 §5)
status: pending
depends_on: [call/peer-composite-env, call/retire-remote-safe]
scope: narrow
risk: medium
impact: component
level: implementation
---
## Description
Wire `dispatch_requested` to resolve the peer's `Identity` and run
`AccessControl::check(peer_identity)` as the authorization mechanism, and
ensure the `PeerId` for a connection comes from `connection.identity().id`
(IdentityProvider resolution). Per ADR-029 §3 (AccessControl-based peer
authorization) and ADR-030 §5 (PeerId from IdentityProvider resolution).
### Current state
After `call/retire-remote-safe`, the `RemoteFilter` gate is removed.
`dispatch_requested` resolves identity (connection-level + auth_token override)
and `OperationRegistry::invoke` runs `AccessControl::check`. The remaining gap
is ensuring the `PeerId` for the connection comes from `IdentityProvider`
resolution (not a UUID), and that connections with no resolved identity get no
`PeerId` (not added to `PeerCompositeEnv`).
### Target state
#### 1. PeerId from IdentityProvider resolution (ADR-030 §5)
The `PeerId` for a connection is `connection.identity().id` — the resolved
`Identity.id` from `IdentityProvider` (= `PeerEntry.peer_id`, stable). The UUID
workaround is removed (done in `call/peer-composite-env`). This task verifies
the dispatch path reads `connection.identity().id` for the peer-keyed overlay
and that a connection with no resolved identity is handled correctly.
#### 2. AccessControl::check(peer_identity) is the authorization gate
`dispatch_requested` resolves the peer's `Identity` (from the connection's TLS
fingerprint or the `auth_token` payload, via the existing `IdentityProvider`)
and `OperationRegistry::invoke` runs `AccessControl::check(peer_identity)`
against the op's `AccessControl`:
- If the op's `AccessControl` is satisfied → dispatch (capabilities populated
from the bundle).
- If not → `FORBIDDEN` before the handler runs (capabilities never populated —
the security property).
- If the op is `Visibility::Internal` → `NOT_FOUND` before ACL (existing
behavior).
This is the existing `OperationRegistry::invoke` path — the `RemoteFilter` gate
(removed in `call/retire-remote-safe`) was a *parallel* gate. This task
verifies the `AccessControl::check` path is the sole authorization mechanism
and that no `remote_safe`/`trusted_peer` remnants remain.
#### 3. Connections with no resolved identity
A connection with no resolved identity (no client cert, unrecognized
fingerprint) has no `PeerId` and is not added to `PeerCompositeEnv`
(ADR-030 §5). The handler either rejects the connection or falls back to a
connection-without-peer-identity path. The dispatch path must handle this case:
- `connection.identity()` returns `None` → no `PeerId`
- The connection's ops (if any discovered via `from_call`) are invoked through
the `CallConnection` handle directly, not via `PeerRef::Specific`
### dispatch_requested flow (post-sync)
```rust
async fn dispatch_requested(&self, connection: &Arc<CallConnection>,
request_id: String, payload: Value) -> ResponseEnvelope {
let operation_id = payload.get("operationId").and_then(|v| v.as_str()).unwrap_or("");
let operation_name = Self::strip_leading_slash(operation_id).to_string();
// No RemoteFilter gate (removed). AccessControl::check in invoke is the gate.
let connection_identity = connection.connection().identity().cloned();
let identity = self.resolve_identity(connection_identity, &payload);
let forwarded_for = payload.get("forwarded_for")
.and_then(|v| serde_json::from_value::<Identity>(v.clone()).ok());
let input = payload.get("input").cloned().unwrap_or(Value::Null);
let context = self.build_root_context(
request_id.clone(), &operation_name, identity, forwarded_for, connection);
// OperationRegistry::invoke runs AccessControl::check(identity) —
// the sole authorization mechanism (ADR-029 §3).
self.registry.invoke(&operation_name, input, context).await
}
```
## Acceptance Criteria
- [ ] `dispatch_requested` resolves peer `Identity` (connection-level + auth_token override)
- [ ] `OperationRegistry::invoke` runs `AccessControl::check(peer_identity)` as the sole authorization gate
- [ ] No `RemoteFilter`/`remote_safe`/`trusted_peer` remnants in dispatch
- [ ] `PeerId` for connection comes from `connection.identity().id` (not UUID)
- [ ] Connection with no resolved identity → no `PeerId`, not added to `PeerCompositeEnv`
- [ ] Op with `AccessControl::default()` dispatches to any peer
- [ ] Op with `required_scopes` → `FORBIDDEN` for unauthorized peers (capabilities never populated)
- [ ] Op with `Visibility::Internal` → `NOT_FOUND` before ACL
- [ ] `forwarded_for` extracted from payload and passed to `build_root_context`
- [ ] Unit test: authorized peer → dispatch (capabilities populated)
- [ ] Unit test: unauthorized peer → FORBIDDEN (capabilities never populated)
- [ ] Unit test: Internal op → NOT_FOUND from wire
- [ ] Unit test: connection with no identity → no PeerId
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/call-protocol.md — dispatch_requested, AuthContext and Identity Resolution
- docs/architecture/crates/call/client-and-adapters.md — peer authorization via AccessControl
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §3 (AccessControl-based peer auth)
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030 §5 (PeerId from IdentityProvider)
## Notes
> The `RemoteFilter` gate (removed in `call/retire-remote-safe`) was a parallel
> authorization system. This task verifies `AccessControl::check` in
> `OperationRegistry::invoke` is the sole gate and that the `PeerId` comes from
> `IdentityProvider` resolution (not UUID). Connections with no resolved
> identity get no `PeerId` and are not in the peer-keyed overlay — their ops
> are invoked through the `CallConnection` handle directly.
## Summary
> To be filled on completion

114
tasks/call/from-call-forwarded-for.md Normal file
View File

@@ -0,0 +1,114 @@
---
id: call/from-call-forwarded-for
name: Wire from_call forwarding handler to populate forwarded_for and use peer-keyed registration (ADR-029 §5, ADR-032)
status: pending
depends_on: [call/operation-context-forwarded-for, call/peer-composite-env]
scope: narrow
risk: low
impact: component
level: implementation
---
## Description
Update the `from_call` forwarding handler to populate `forwarded_for` on the
`call.requested` payload it constructs, and update `from_call` registration to
use the peer-keyed overlay model. Per ADR-029 §5 (peer-keyed registration,
collision rule change) and ADR-032 §3 (from_call populates forwarded_for).
### forwarded_for population (ADR-032 §3)
The hub's `from_call` forwarding handler constructs the `call.requested` payload
to send to the spoke. It populates `forwarded_for` with the end user's identity
— read from the hub's `OperationContext.identity` (the caller the hub
authenticated) when the hub forwards the call.
```rust
// In the from_call forwarding handler:
let mut payload = serde_json::json!({
"operationId": operation_id,
"input": input,
});
// Populate forwarded_for from the hub's context.identity (ADR-032)
if let Some(originator) = &context.identity {
payload["forwarded_for"] = serde_json::to_value(originator).ok().unwrap_or(Value::Null);
}
// The hub authenticates as itself (its own auth_token)
if let Some(token) = &credentials.auth_token {
payload["auth_token"] = serde_json::Value::String(token);
}
```
The hub may set `forwarded_for: None` (omit the field) if it doesn't want to
disclose the originator. The spoke receives it as metadata on its
`OperationContext` — available for logging, auditing, per-user rate limiting,
but never used by `AccessControl::check` (the spoke authorizes the hub, its
direct caller).
### Peer-keyed registration (ADR-029 §5)
`from_call` registers into the specific peer's sub-overlay (via
`CallConnection::register_imported`), not a flat overlay. Cross-peer collision
dissolves: same name on different peers is fine (separate sub-overlays, no
collision, no prefix needed). Same-peer collision stays an error (a peer
shouldn't expose two ops with the same name).
`FromCallConfig::namespace_prefix` becomes optional local-naming sugar for
when the importing node wants to expose a peer's ops under a different name
*locally* — a local-naming concern, not a disambiguation concern. It defaults
to `None`.
### Collision rule change
- **Same-peer collision** = error (a peer shouldn't expose two ops with the
same name). `AdapterError::SamePeerCollision`.
- **Cross-peer collision** dissolves (same name on different peers is fine —
separate sub-overlays, ADR-029 §5).
The existing `from_call` namespace-collision check (which was flat-namespace)
changes to same-peer-only. The `AdapterError::Conflict` variant (if it exists)
renames to `SamePeerCollision` (OQ-26).
### What this task does NOT do
- Does NOT build `PeerCompositeEnv` (that's `call/peer-composite-env`, a
dependency) — `from_call` registers into the connection's overlay, which
`PeerCompositeEnv` aggregates by peer.
- Does NOT add `forwarded_for` to `OperationContext` (that's
`call/operation-context-forwarded-for`, a dependency) — this task populates
the wire field.
## Acceptance Criteria
- [ ] `from_call` forwarding handler populates `forwarded_for` on the `call.requested` payload from `context.identity`
- [ ] `forwarded_for` omitted (None) when the hub chooses not to disclose the originator
- [ ] `from_call` registers into the connection's overlay (peer-keyed via `PeerCompositeEnv`)
- [ ] Same-peer collision = error (`AdapterError::SamePeerCollision`)
- [ ] Cross-peer collision dissolves (same name on different peers is fine)
- [ ] `FromCallConfig::namespace_prefix` defaults to `None` (optional local-naming sugar)
- [ ] `AdapterError::Conflict` renamed to `SamePeerCollision` (OQ-26)
- [ ] Unit test: `forwarded_for` populated from `context.identity` on forwarding
- [ ] Unit test: `forwarded_for` omitted when context.identity is None
- [ ] Unit test: same-peer collision returns `SamePeerCollision` error
- [ ] Unit test: cross-peer same name does not collide (separate sub-overlays)
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/client-and-adapters.md — from_call, forwarded_for, namespace collision
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §5 (peer-keyed registration, collision rule)
- docs/architecture/decisions/032-forwarded-for-identity.md — ADR-032 §3 (from_call populates forwarded_for)
## Notes
> The `from_call` handler is the hub's forwarding path. It populates
> `forwarded_for` from the hub's `context.identity` (the end user) so the spoke
> has the originator as metadata. The spoke authorizes the hub (its direct
> caller), not the end user — `AccessControl::check` never reads
> `forwarded_for`. Cross-peer collision dissolves under the peer-keyed model
> (separate sub-overlays); same-peer collision stays an error.
## Summary
> To be filled on completion

148
tasks/call/operation-context-forwarded-for.md Normal file
View File

@@ -0,0 +1,148 @@
---
id: call/operation-context-forwarded-for
name: Add forwarded_for field to OperationContext and wire from call.requested (ADR-032)
status: pending
depends_on: [call/retire-remote-safe]
scope: narrow
risk: low
impact: component
level: implementation
---
## Description
Add the `forwarded_for: Option<Identity>` field to `OperationContext` and wire
it from the `call.requested` payload. Per ADR-032, `forwarded_for` is metadata
only — `AccessControl::check` never reads it; the ACL always authorizes the
direct caller's `identity`. This is the wire-format one-way door folded into
the `OperationContext` edit window (ADR-032 says this is the cheapest point
since `OperationContext` is under edit for the ADR-029 migration).
### OperationContext change
```rust
pub struct OperationContext {
// ... existing fields ...
pub forwarded_for: Option<Identity>, // NEW (ADR-032)
}
```
- `forwarded_for`: The original caller when this call was forwarded by a
`from_call` handler (ADR-032). **Metadata only** — `AccessControl::check`
never reads it; the ACL always authorizes `identity` (the direct caller).
Handlers may read it for logging, auditing, per-user rate limiting, or
application context. The forwarder's claim, not a verified identity — a
malicious hub can lie (same property as HTTP `X-Forwarded-For`).
### Wire format (call.requested payload)
The `call.requested` payload already carries `operationId`, `input`, and
optional `auth_token`. Add optional `forwarded_for`:
```json
{
"operationId": "/docker/start",
"input": { ... },
"auth_token": "alk_...",
"forwarded_for": { // optional (ADR-032)
"id": "alice",
"scopes": ["fs:read", "docker:start"],
"resources": {}
}
}
```
The payload is a `serde_json::Value` (not a typed struct), so `forwarded_for`
is read from `payload.get("forwarded_for")` and deserialized into `Identity`.
### build_root_context wiring
`Dispatcher::build_root_context` reads `forwarded_for` from the payload and
populates the field:
```rust
fn build_root_context(
&self,
request_id: String,
operation_name: &str,
identity: Option<Identity>,
forwarded_for: Option<Identity>, // NEW parameter
connection: &CallConnection,
) -> OperationContext {
// ...
OperationContext {
// ...
forwarded_for, // from call.requested.forwarded_for
// ...
}
}
```
`dispatch_requested` extracts `forwarded_for` from the payload:
```rust
let forwarded_for = payload.get("forwarded_for")
.and_then(|v| serde_json::from_value::<Identity>(v.clone()).ok());
```
### OperationEnv::invoke sets None for composed children
`forwarded_for` is **wire-ingress only** (ADR-032 Assumption 3). Composed
children (calls via `OperationEnv::invoke`) do NOT inherit `forwarded_for` —
they get `None`. The field is populated from `call.requested.forwarded_for` by
the dispatch path, and the `from_call` forwarding handler sets it when
constructing the forwarded payload (that's `call/from-call-forwarded-for`).
In `LocalOperationEnv::invoke_with_policy` (and `PeerCompositeEnv` when built):
```rust
let context = OperationContext {
// ...
forwarded_for: None, // composed children do not inherit (ADR-032)
// ...
};
```
### AccessControl::check never reads forwarded_for
The security property is structural: `AccessControl::check` takes
`Option<&Identity>` (the direct caller's `identity`). The `forwarded_for` field
is `Option<Identity>` on `OperationContext`, but the check signature doesn't
accept it. Verify this invariant holds — no code path passes `forwarded_for`
to `AccessControl::check`.
## Acceptance Criteria
- [ ] `OperationContext.forwarded_for: Option<Identity>` field added
- [ ] `build_root_context` accepts `forwarded_for` parameter and populates the field
- [ ] `dispatch_requested` extracts `forwarded_for` from `payload.get("forwarded_for")`
- [ ] `forwarded_for` deserialized from JSON `{ id, scopes, resources }` into `Identity`
- [ ] `OperationEnv::invoke_with_policy` sets `forwarded_for: None` for composed children
- [ ] `AccessControl::check` never reads `forwarded_for` (verify no code path passes it)
- [ ] Missing `forwarded_for` in payload → `None` (no error)
- [ ] Unit test: `forwarded_for` populated from payload
- [ ] Unit test: missing `forwarded_for` → None
- [ ] Unit test: composed children get `forwarded_for: None`
- [ ] Unit test: `AccessControl::check` still uses `identity` (not `forwarded_for`)
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/operation-registry.md — OperationContext.forwarded_for
- docs/architecture/crates/call/call-protocol.md — call.requested payload, build_root_context
- docs/architecture/decisions/032-forwarded-for-identity.md — ADR-032
## Notes
> `forwarded_for` is a wire-format one-way door (ADR-032) — folded into the
> OperationContext edit window because ADR-029 is already rewriting the
> composition env. The field is metadata only: `AccessControl::check` never
> reads it; the ACL always authorizes the direct caller's `identity`. The
> `from_call` handler populates it when forwarding (that's
> `call/from-call-forwarded-for`). Composed children get `None` (wire-ingress
> only, not composition-ingress).
## Summary
> To be filled on completion

156
tasks/call/operation-env-invoke-peer.md Normal file
View File

@@ -0,0 +1,156 @@
---
id: call/operation-env-invoke-peer
name: Add invoke_peer/peer_contains/PeerRef to OperationEnv trait for peer-keyed routing (ADR-029 §2)
status: pending
depends_on: [call/peer-composite-env]
scope: moderate
risk: medium
impact: component
level: implementation
---
## Description
Add the `invoke_peer` and `peer_contains` methods to the `OperationEnv` trait,
with the `PeerRef` selector enum. Per ADR-029 §2. `PeerCompositeEnv` (built in
`call/peer-composite-env`) overrides these with real peer-keyed routing; the
default-impl preserves back-compat for single-layer envs
(`LocalOperationEnv`, connection overlays) that don't route by peer.
### PeerRef enum
```rust
pub enum PeerRef {
Specific(PeerId), // route to this peer; NOT_FOUND if it doesn't serve the op
Any, // first peer (insertion order) that serves it
}
```
`PeerRef::Specific(PeerId)` routes to the named peer's overlay only — no
fallthrough (explicit routing must be honored or fail loudly, ADR-029 §2).
`PeerRef::Any` reuses `invoke_with_policy` (the insertion-order fan-out built
in `call/peer-composite-env`).
### OperationEnv trait additions
```rust
#[async_trait]
pub trait OperationEnv: Send + Sync {
// ... existing invoke, invoke_with_policy, contains ...
/// Peer-routing composition (ADR-029 §2). Routes to a specific peer
/// (`PeerRef::Specific`) or to the first peer that serves the op
/// (`PeerRef::Any`). The default impl ignores the peer selector and
/// delegates to `invoke_with_policy`, preserving back-compat for
/// single-layer envs that don't route by peer. `PeerCompositeEnv`
/// overrides with real peer-keyed routing.
async fn invoke_peer(
&self,
peer: &PeerRef,
namespace: &str,
operation: &str,
input: Value,
parent: &OperationContext,
policy: AbortPolicy,
) -> ResponseEnvelope {
let _ = peer; // unused — single-layer envs don't route by peer
self.invoke_with_policy(namespace, operation, input, parent, policy).await
}
/// Does this env contain the named op *on the named peer*? Used by
/// `PeerCompositeEnv` to probe a specific peer's sub-overlay before
/// dispatching via `invoke_peer` with `PeerRef::Specific`. Default impl
/// delegates to `contains` (single-layer envs ignore the peer dimension).
fn peer_contains(&self, _peer: &PeerId, name: &str) -> bool {
self.contains(name)
}
}
```
### PeerCompositeEnv overrides
```rust
#[async_trait]
impl OperationEnv for PeerCompositeEnv {
// ... invoke_with_policy, contains from call/peer-composite-env ...
async fn invoke_peer(
&self,
peer: &PeerRef,
namespace: &str,
operation: &str,
input: Value,
parent: &OperationContext,
policy: AbortPolicy,
) -> ResponseEnvelope {
let name = format!("{namespace}/{operation}");
if !parent.scoped_env.allows(&name) {
return ResponseEnvelope::not_found(parent.request_id.clone(), &name);
}
match peer {
PeerRef::Specific(peer_id) => {
// Route to this peer's sub-overlay only. No fallthrough —
// explicit routing must be honored or fail loudly (ADR-029 §2).
match self.connections.get(peer_id) {
Some(conn_env) if conn_env.contains(&name) => {
conn_env.invoke_with_policy(namespace, operation, input, parent, policy).await
}
_ => ResponseEnvelope::not_found(parent.request_id.clone(), &name),
}
}
PeerRef::Any => {
// Same as invoke_with_policy: session → peers in order → base.
self.invoke_with_policy(namespace, operation, input, parent, policy).await
}
}
}
fn peer_contains(&self, peer: &PeerId, name: &str) -> bool {
self.connections.get(peer).map_or(false, |c| c.contains(name))
}
}
```
### Back-compat
Existing impls (`LocalOperationEnv`, connection overlay envs) use the default
`invoke_peer` (delegates to `invoke_with_policy`, ignores peer selector) and
default `peer_contains` (delegates to `contains`). No changes needed to those
impls — the trait surface grows, the behavior is preserved.
## Acceptance Criteria
- [ ] `PeerRef` enum with `Specific(PeerId)` and `Any` variants
- [ ] `OperationEnv::invoke_peer` method with default-impl (delegates to `invoke_with_policy`)
- [ ] `OperationEnv::peer_contains` method with default-impl (delegates to `contains`)
- [ ] `PeerCompositeEnv` overrides `invoke_peer` with real peer-keyed routing
- [ ] `PeerRef::Specific` routes to named peer only (no fallthrough → NOT_FOUND if peer doesn't serve op)
- [ ] `PeerRef::Any` reuses `invoke_with_policy` (insertion-order fan-out)
- [ ] `PeerCompositeEnv` overrides `peer_contains` (checks specific peer's sub-overlay)
- [ ] Reachability check (`scoped_env.allows`) gates before peer routing
- [ ] `LocalOperationEnv` and overlay envs use default-impls (no changes)
- [ ] Unit test: `PeerRef::Specific` routes to the named peer
- [ ] Unit test: `PeerRef::Specific` → NOT_FOUND when peer doesn't serve the op (no fallthrough)
- [ ] Unit test: `PeerRef::Any` routes to first peer (insertion order) that serves it
- [ ] Unit test: `peer_contains` checks specific peer's overlay
- [ ] Unit test: default-impl `invoke_peer` delegates to `invoke_with_policy` (back-compat)
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/operation-registry.md — OperationEnv, invoke_peer, PeerRef
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §2 (PeerRef routing)
## Notes
> The default-impl preserves back-compat — existing single-layer envs
> (`LocalOperationEnv`, connection overlays) work unchanged. `PeerCompositeEnv`
> overrides with real peer-keyed routing. `PeerRef::Specific` has no
> fallthrough (explicit routing must be honored or fail loudly). `PeerRef::Any`
> reuses the `invoke_with_policy` fan-out. The reachability check
> (`scoped_env.allows`) gates before peer routing, same as before.
## Summary
> To be filled on completion

187
tasks/call/peer-composite-env.md Normal file
View File

@@ -0,0 +1,187 @@
---
id: call/peer-composite-env
name: Replace CompositeOperationEnv with PeerCompositeEnv (peer-keyed overlays) and PeerId from Identity.id (ADR-029/030)
status: pending
depends_on: [call/retire-remote-safe]
scope: broad
risk: high
impact: phase
level: implementation
---
## Description
Replace `CompositeOperationEnv` (singular `connection: Option<Arc<dyn
OperationEnv>>`) with `PeerCompositeEnv` (peer-keyed `HashMap<PeerId,
connection_overlay>`), and change `PeerId` from a connection-assigned UUID to
`Identity.id` from `IdentityProvider` resolution (= `PeerEntry.peer_id`,
stable across key rotation). Per ADR-029 §1 and ADR-030 §4-5.
This is the highest-risk call task — a structural rewrite of the composition
env that aggregates multiple connections. The singular-connection case (one
peer) is the degenerate case with a single-entry map.
### PeerCompositeEnv struct
```rust
pub struct PeerCompositeEnv {
pub base: Arc<dyn OperationEnv + Send + Sync>, // Layer 0 curated
pub session: Option<Arc<dyn OperationEnv + Send + Sync>>, // Layer 1
pub connections: HashMap<PeerId, Arc<dyn OperationEnv + Send + Sync>>, // Layer 2, peer-keyed
connection_order: Vec<PeerId>, // insertion order for PeerRef::Any first-match
}
pub type PeerId = String; // = Identity.id from IdentityProvider resolution
// = PeerEntry.peer_id (stable, not crypto material — ADR-030)
```
### PeerCompositeEnv methods
```rust
impl PeerCompositeEnv {
pub fn new(base: Arc<dyn OperationEnv + Send + Sync>) -> Self;
pub fn with_session(mut self, session: Arc<dyn OperationEnv + Send + Sync>) -> Self;
/// Attach a peer's connection overlay. The `peer_id` comes from
/// `connection.identity().id` (IdentityProvider resolution). A connection
/// with no resolved identity has no PeerId and is NOT attached (ADR-030 §5).
pub fn attach_peer(&mut self, peer_id: PeerId, overlay: Arc<dyn OperationEnv + Send + Sync>);
/// Detach a peer's overlay (on disconnect). The peer's sub-overlay drops;
/// in-flight PeerRef::Specific(that_peer) gets NOT_FOUND.
pub fn detach_peer(&mut self, peer_id: &PeerId);
}
```
### PeerCompositeEnv::invoke_with_policy
```rust
async fn invoke_with_policy(&self, namespace: &str, operation: &str, input: Value,
parent: &OperationContext, policy: AbortPolicy) -> ResponseEnvelope {
let name = format!("{namespace}/{operation}");
if !parent.scoped_env.allows(&name) {
return ResponseEnvelope::not_found(parent.request_id.clone(), &name);
}
// PeerRef::Any routing (ADR-029 §2): session → peers in insertion
// order → curated base. First overlay that contains the op wins.
if let Some(session) = &self.session {
if session.contains(&name) {
return session.invoke_with_policy(namespace, operation, input, parent, policy).await;
}
}
for peer_id in &self.connection_order {
if let Some(conn_env) = self.connections.get(peer_id) {
if conn_env.contains(&name) {
return conn_env.invoke_with_policy(namespace, operation, input, parent, policy).await;
}
}
}
self.base.invoke_with_policy(namespace, operation, input, parent, policy).await
}
fn contains(&self, name: &str) -> bool {
self.session.as_ref().map_or(false, |s| s.contains(name))
|| self.connections.values().any(|c| c.contains(name))
|| self.base.contains(name)
}
```
The `invoke_peer` / `peer_contains` methods (PeerRef routing) are
`call/operation-env-invoke-peer` — this task builds the struct and the
`invoke_with_policy` / `contains` methods; the peer-routing methods are the
next task.
### compose_root_env rewrite
`Dispatcher::compose_root_env` builds a `PeerCompositeEnv` per incoming call:
```rust
fn compose_root_env(&self, connection: &CallConnection, context: &OperationContext)
-> Arc<dyn OperationEnv + Send + Sync>
{
let base = Arc::new(LocalOperationEnv::new(Arc::clone(&self.registry)));
let session = self.session_source.as_ref()
.and_then(|s| s.overlay_for(context));
let mut env = PeerCompositeEnv::new(base);
if let Some(session) = session {
env = env.with_session(session);
}
// Attach this connection's overlay, keyed by the peer's PeerId.
// PeerId = connection.identity().id (IdentityProvider resolution).
// A connection with no resolved identity is NOT attached to the
// peer-keyed overlay (ADR-030 §5) — its ops are invoked through the
// CallConnection handle directly, not via PeerRef::Specific.
if let Some(peer_id) = connection.connection().identity().map(|id| id.id.clone()) {
env.attach_peer(peer_id, connection.overlay_env());
}
Arc::new(env)
}
```
### PeerId source: Identity.id (remove UUID workaround)
`PeerId` is `Identity.id` from `IdentityProvider` resolution — the stable
`PeerEntry.peer_id` (ADR-030 §4). The UUID workaround (ADR-029 Assumption 1's
connection-assigned UUID) is removed. A connection with no resolved identity
has no `PeerId` and is not added to `PeerCompositeEnv` (ADR-030 §5).
### Migration: CompositeOperationEnv → PeerCompositeEnv
All call sites that construct `CompositeOperationEnv::new(base, Some(conn),
session)` migrate to `PeerCompositeEnv::new(base).with_session(session).
attach_peer(peer_id, conn)`. The singular-connection case (one peer) is the
degenerate case (`connections` with one entry).
### What this task does NOT do
- Does NOT add `invoke_peer` / `peer_contains` / `PeerRef` — that's
`call/operation-env-invoke-peer`. This task builds the struct and the
`invoke_with_policy` (PeerRef::Any equivalent) + `contains` methods.
- Does NOT change `from_call` registration — that's
`call/from-call-forwarded-for` (peer-keyed registration, forwarded_for).
- Does NOT change `services/list` — that's
`call/services-list-accesscontrol-filtered`.
## Acceptance Criteria
- [ ] `PeerCompositeEnv` struct with `base`, `session`, `connections: HashMap<PeerId, ...>`, `connection_order: Vec<PeerId>`
- [ ] `PeerId = String` (= `Identity.id`, not UUID)
- [ ] `PeerCompositeEnv::new(base)`, `with_session(session)`, `attach_peer(peer_id, overlay)`, `detach_peer(peer_id)`
- [ ] `invoke_with_policy` routes: session → peers in insertion order → base (first `contains` wins)
- [ ] `contains` checks session + all connections + base
- [ ] `compose_root_env` builds `PeerCompositeEnv` per call, attaches this connection's overlay keyed by `connection.identity().id`
- [ ] Connection with no resolved identity → not attached to peer-keyed overlay (no PeerId)
- [ ] `CompositeOperationEnv` removed (all call sites migrated)
- [ ] UUID workaround removed (no connection-assigned UUID for PeerId)
- [ ] Singular-connection case works (degenerate single-entry map)
- [ ] Unit test: PeerCompositeEnv routes to session when it contains the op
- [ ] Unit test: PeerCompositeEnv routes to first peer (insertion order) that contains the op
- [ ] Unit test: PeerCompositeEnv falls through to base when no overlay contains the op
- [ ] Unit test: attach_peer + detach_peer (detach → NOT_FOUND for that peer)
- [ ] Unit test: connection with no identity → not attached
- [ ] Unit test: reachability check (scoped_env.allows) still gates before routing
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/operation-registry.md — PeerCompositeEnv, OperationEnv
- docs/architecture/crates/call/call-protocol.md — compose_root_env, build_root_context
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §1 (peer-keyed overlays)
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030 §4-5 (PeerId source)
## Notes
> Highest-risk call task — structural rewrite of the composition env. The
> singular-connection case is the degenerate case (one-entry map). PeerId is
> `Identity.id` (stable `peer_id`), not a UUID — the UUID workaround is removed.
> A connection with no resolved identity gets no PeerId and is not attached
> (ADR-030 §5). The `invoke_peer` / `PeerRef` routing methods are the next
> task (`call/operation-env-invoke-peer`); this task builds the struct and the
> PeerRef::Any-equivalent routing (`invoke_with_policy`).
## Summary
> To be filled on completion

125
tasks/call/retire-remote-safe.md Normal file
View File

@@ -0,0 +1,125 @@
---
id: call/retire-remote-safe
name: Retire remote_safe/trusted_peer/RemoteFilter — peer authorization via AccessControl (ADR-029 §3)
status: pending
depends_on: [core/review-core-sync]
scope: moderate
risk: medium
impact: component
level: implementation
---
## Description
Remove the ADR-028 peer-authorization machinery from alknet-call. Per ADR-029
§3, peer authorization now flows through the existing `AccessControl::check
(peer_identity)` — the same mechanism that gates every other call. No
`remote_safe` flag, no `trusted_peer` bypass, no `RemoteFilter` gate.
This task is the "remove the old" step before the "build the new" (PeerCompositeEnv,
invoke_peer). Removing the ADR-028 machinery first means the new
`AccessControl`-based authorization replaces the old model rather than
coexisting.
### What to remove
1. **`HandlerRegistration.remote_safe: bool`** (`registry/registration.rs`):
- Remove the field
- Remove `HandlerRegistration::remote_safe()` setter
- Remove `OperationRegistryBuilder::remote_safe()` method
- Remove all tests asserting `remote_safe` defaults/setter
2. **`OperationRegistry::list_operations_peer_scoped`** (`registry/registration.rs`):
- Remove the method (replaced by AccessControl-filtered `services/list` in
`call/services-list-accesscontrol-filtered`)
3. **`services_list_handler_peer_scoped`** (`registry/discovery.rs`):
- Remove the function (replaced by single AccessControl-filtered handler in
`call/services-list-accesscontrol-filtered`)
4. **`RemoteFilter`** (`protocol/dispatch.rs`):
- Remove the `RemoteFilter` struct and its `default_deny()`/`trusted()`/
`allows()` methods
- Remove the `remote_filter` field from `Dispatcher`
- Remove the `RemoteFilter` parameter from `Dispatcher::new()`
- Remove the `remote_filter.allows(registration.remote_safe)` gate in
`dispatch_requested` (the AccessControl gate in `OperationRegistry::invoke`
already handles authorization — this task removes the *parallel* gate)
5. **`CallClient::trusted_peer`** (`client/call_client.rs`):
- Remove the `trusted_peer: bool` field
- Remove `CallClient::trusted_peer()` constructor
- Remove `CallClient::is_trusted_peer()` method
- Remove the `RemoteFilter::trusted()`/`default_deny()` selection in
`spawn_dispatch`
- `CallClient::new()` stays; `spawn_dispatch` constructs `Dispatcher::new`
without `RemoteFilter`
6. **All ADR-028 tests**:
- Remove tests asserting `remote_safe` behavior, `trusted_peer` mode,
`RemoteFilter` filtering, `list_operations_peer_scoped`,
`services_list_handler_peer_scoped`
- These tests verify the old model; the new model's tests land in the
consuming tasks (`call/services-list-accesscontrol-filtered`,
`call/dispatch-peer-identity`)
### Transient state
After this task, the dispatch path authorizes via `AccessControl::check` (which
`OperationRegistry::invoke` already runs) — no parallel gate. The
`PeerCompositeEnv` and `invoke_peer` are not yet built (those are
`call/peer-composite-env` and `call/operation-env-invoke-peer`), so the
composition env is still `CompositeOperationEnv` (singular connection). The
`services/list` handler is the unfiltered `services_list_handler` until
`call/services-list-accesscontrol-filtered` adds the AccessControl filter.
This transient state compiles and is correct — it's just the ADR-028 model
removed without the ADR-029 peer-keyed routing yet added. The
`AccessControl::check` gate in `OperationRegistry::invoke` is the authorization
mechanism throughout.
### ADR-029 §3 mapping (the three `remote_safe` cases)
| `remote_safe` case | Replacement (already in place via AccessControl) |
|---|---|
| Op callable by any peer (was `remote_safe: true`) | `AccessControl::default()` — no restrictions |
| Op callable only by some peers | `AccessControl { required_scopes: [...] }` — peer's `Identity.scopes` must satisfy |
| Op never callable from wire | `Visibility::Internal` — `NOT_FOUND` before ACL |
## Acceptance Criteria
- [ ] `HandlerRegistration.remote_safe` field removed
- [ ] `HandlerRegistration::remote_safe()` setter removed
- [ ] `OperationRegistryBuilder::remote_safe()` removed
- [ ] `OperationRegistry::list_operations_peer_scoped` removed
- [ ] `services_list_handler_peer_scoped` removed
- [ ] `RemoteFilter` struct removed from `protocol/dispatch.rs`
- [ ] `Dispatcher.remote_filter` field removed
- [ ] `Dispatcher::new()` no longer takes `RemoteFilter`
- [ ] `CallClient.trusted_peer` field removed
- [ ] `CallClient::trusted_peer()` constructor removed
- [ ] `CallClient::is_trusted_peer()` removed
- [ ] `dispatch_requested` no longer has the `remote_filter.allows` gate
- [ ] All ADR-028 tests removed
- [ ] No `remote_safe`/`trusted_peer`/`RemoteFilter` references remain in the crate
- [ ] `cargo test -p alknet-call` succeeds (remaining tests pass — the AccessControl gate in invoke still works)
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §3 (retire remote_safe/trusted_peer)
- docs/architecture/crates/call/operation-registry.md — HandlerRegistration (remote_safe removed)
- docs/architecture/crates/call/client-and-adapters.md — CallClient (trusted_peer removed)
## Notes
> This is the "remove the old" step. The new model (PeerCompositeEnv,
> invoke_peer, AccessControl-filtered services/list) lands in subsequent tasks.
> The transient state after this task compiles and is correct —
> `AccessControl::check` in `OperationRegistry::invoke` is the authorization
> mechanism throughout. The ADR-028 tests are removed because they verify the
> old model; the new model's tests land in the consuming tasks.
## Summary
> To be filled on completion

155
tasks/call/review-call-sync.md Normal file
View File

@@ -0,0 +1,155 @@
---
id: call/review-call-sync
name: Review alknet-call ADR-029/030/032/034 sync for spec conformance
status: pending
depends_on: [call/operation-env-invoke-peer, call/services-list-accesscontrol-filtered, call/call-client-verifier-selection, call/from-call-forwarded-for, call/dispatch-peer-identity]
scope: broad
risk: low
impact: phase
level: review
---
## Description
Review the alknet-call implementation after the ADR-029/030/032/034 sync for
spec conformance, pattern consistency, and correctness. This is the quality
checkpoint at the end of the call phase — the most complex sync in this batch.
### Review Checklist
1. **remote_safe/trusted_peer retirement** (ADR-029 §3):
- No `remote_safe` field on `HandlerRegistration`
- No `trusted_peer` on `CallClient`
- No `RemoteFilter` in dispatch
- No `list_operations_peer_scoped` / `services_list_handler_peer_scoped`
- No ADR-028 test remnants
- Peer authorization via `AccessControl::check(peer_identity)` only
2. **PeerCompositeEnv conformance** (ADR-029 §1, ADR-030 §4-5):
- `PeerCompositeEnv` with peer-keyed `connections: HashMap<PeerId, ...>`
- `connection_order: Vec<PeerId>` (insertion order for `PeerRef::Any`)
- `PeerId = Identity.id` (stable `peer_id`, not UUID)
- `compose_root_env` builds `PeerCompositeEnv` per call
- Connection with no resolved identity → not attached (no PeerId)
- `CompositeOperationEnv` removed (all call sites migrated)
- Singular-connection case works (degenerate single-entry map)
3. **invoke_peer / PeerRef conformance** (ADR-029 §2):
- `PeerRef::Specific(PeerId)` / `PeerRef::Any` enum
- `OperationEnv::invoke_peer` with default-impl (back-compat)
- `OperationEnv::peer_contains` with default-impl
- `PeerCompositeEnv` overrides with real peer-keyed routing
- `PeerRef::Specific` → no fallthrough (NOT_FOUND if peer doesn't serve op)
- `PeerRef::Any` → insertion-order first-match
- Reachability check (`scoped_env.allows`) gates before routing
4. **forwarded_for conformance** (ADR-032):
- `OperationContext.forwarded_for: Option<Identity>` field
- `build_root_context` populates from `call.requested.forwarded_for`
- `OperationEnv::invoke` sets `None` for composed children (wire-ingress only)
- `AccessControl::check` never reads `forwarded_for` (structural invariant)
- `from_call` handler populates `forwarded_for` from `context.identity`
5. **services/list AccessControl-filtered** (ADR-029 §6):
- `services/list` filters by `AccessControl::check(calling_peer_identity)`
- Op with `AccessControl::default()` listed to any peer
- Op with `required_scopes` hidden from unauthorized peers
- `services/list-peers` opt-in (peer-attributed, AccessControl-filtered)
- `services/schema` unchanged
6. **CallClient verifier selection** (OQ-29, ADR-034):
- Client presents Ed25519 key as RFC 7250 raw public key client cert
- `AcceptAnyServerCertVerifier` removed (security hole)
- Verifier by `PeerEntry` presence: `Some` → fingerprint pin, `None` + X.509 → CA, `None` + Ed25519 → fail closed
- `CallCredentials.remote_identity: None` is load-bearing (not placeholder)
- No-env-vars invariant preserved (credentials from Capabilities)
7. **from_call peer-keyed registration** (ADR-029 §5):
- `from_call` registers into peer's sub-overlay
- Same-peer collision = error (`SamePeerCollision`)
- Cross-peer collision dissolves (separate sub-overlays)
- `namespace_prefix` defaults to `None` (optional local-naming sugar)
- `forwarded_for` populated from hub's `context.identity`
8. **dispatch_peer_identity** (ADR-029 §3, ADR-030 §5):
- `dispatch_requested` resolves peer `Identity`
- `AccessControl::check(peer_identity)` is the sole authorization gate
- `PeerId` from `connection.identity().id` (not UUID)
- Connection with no identity → no PeerId, not in PeerCompositeEnv
9. **ADR conformance**:
- ADR-029: peer-keyed overlays, PeerRef routing, AccessControl-based peer auth, retire remote_safe
- ADR-030: PeerId = Identity.id = PeerEntry.peer_id (stable)
- ADR-032: forwarded_for (metadata only, wire-ingress only, never in ACL)
- ADR-034: three remote roles, verifier selection by PeerEntry presence
10. **Security constraints**:
- Capabilities non-serializable, zeroized, immutable (unchanged)
- No secret material on wire (unchanged)
- `forwarded_for` is metadata, not authority (AccessControl::check never reads it)
- Internal ops → NOT_FOUND from wire (unchanged)
- Reachability check bounds composition (unchanged)
- No-env-vars invariant (credentials from Capabilities, not env vars)
- `AcceptAnyServerCertVerifier` removed (no security hole for X.509)
11. **Pattern consistency**:
- `OperationEnv` is a trait (not concrete) — preserved
- `PeerCompositeEnv` uses `contains()` probe before dispatch — preserved
- Authority switch on `internal: true` — preserved
- Deadline inheritance — preserved
- Metadata fresh on composition (`HashMap::new()`) — preserved
12. **Test coverage**:
- PeerCompositeEnv routing (session, peers in order, base fallthrough)
- PeerRef::Specific (routes, NOT_FOUND on missing peer)
- PeerRef::Any (insertion-order first-match)
- forwarded_for (populated, None for composed children, never in ACL)
- services/list AccessControl-filtered
- AccessControl::check peer authorization (allowed, FORBIDDEN, Internal NOT_FOUND)
- CallClient verifier selection (fingerprint pin, CA, fail closed)
- from_call forwarded_for + peer-keyed registration + collision rules
## Acceptance Criteria
- [ ] No `remote_safe`/`trusted_peer`/`RemoteFilter` references remain
- [ ] `PeerCompositeEnv` matches ADR-029 §1 (peer-keyed, insertion order)
- [ ] `PeerId = Identity.id` (stable, not UUID)
- [ ] `invoke_peer`/`peer_contains`/`PeerRef` match ADR-029 §2
- [ ] `forwarded_for` matches ADR-032 (metadata only, wire-ingress only, never in ACL)
- [ ] `services/list` AccessControl-filtered; `services/list-peers` opt-in
- [ ] CallClient verifier selection matches ADR-034 §3
- [ ] `from_call` peer-keyed registration + forwarded_for + collision rules
- [ ] `AccessControl::check(peer_identity)` is the sole authorization gate
- [ ] `AcceptAnyServerCertVerifier` removed
- [ ] No-env-vars invariant preserved
- [ ] `OperationEnv` is a trait (not concrete)
- [ ] Test coverage adequate for all new functionality
- [ ] `cargo fmt --check -p alknet-call` passes
- [ ] `cargo clippy -p alknet-call` passes with no warnings
- [ ] All tests pass
## References
- docs/architecture/crates/call/README.md
- docs/architecture/crates/call/call-protocol.md
- docs/architecture/crates/call/operation-registry.md
- docs/architecture/crates/call/client-and-adapters.md
- docs/architecture/decisions/029-peer-graph-routing-model.md
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md
- docs/architecture/decisions/032-forwarded-for-identity.md
- docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md
## Notes
> This is the most complex sync in this batch. The review should verify that
> the peer-keyed routing model (ADR-029), the stable PeerId (ADR-030), the
> forwarded_for metadata field (ADR-032), and the verifier selection (ADR-034)
> all work correctly together. The `OperationEnv` trait-object design is
> load-bearing — verify it's still a trait, not concrete. The
> `AccessControl::check`-based peer authorization is the security property —
> verify no parallel gate remains. If deviations are found, document and fix
> before considering the call sync complete.
## Summary
> To be filled on completion

122
tasks/call/services-list-accesscontrol-filtered.md Normal file
View File

@@ -0,0 +1,122 @@
---
id: call/services-list-accesscontrol-filtered
name: Filter services/list by AccessControl::check(peer_identity) and add services/list-peers opt-in (ADR-029 §6)
status: pending
depends_on: [call/retire-remote-safe]
scope: narrow
risk: medium
impact: component
level: implementation
---
## Description
Change `services/list` to filter by `AccessControl::check(calling_peer_identity)`
— the calling peer sees only ops it is authorized to call. Collapse the
`services_list_handler` / `services_list_handler_peer_scoped` split (the latter
was removed in `call/retire-remote-safe`) into a single AccessControl-filtered
handler. Add the opt-in `services/list-peers` for peer-attributed re-export
listing. Per ADR-029 §6.
### services/list (AccessControl-filtered)
The single `services_list_handler` filters by `AccessControl::check` against
the calling peer's resolved `Identity`:
```rust
pub fn services_list_handler(registry: Arc<OperationRegistry>) -> Handler {
Arc::new(move |_input, context| {
let registry = Arc::clone(&registry);
Box::pin(async move {
let calling_identity = &context.identity;
let ops: Vec<Value> = registry.list_operations()
.into_iter()
.filter(|spec| {
// Only list ops the calling peer is authorized to call.
// AccessControl::check returns Allowed/Forbidden.
spec.access_control.check(calling_identity.as_ref()).is_allowed()
})
.map(|spec| serde_json::json!({
"name": spec.name,
"namespace": spec.namespace,
"op_type": spec.op_type,
}))
.collect();
ResponseEnvelope::ok(context.request_id, serde_json::json!({ "operations": ops }))
})
})
}
```
- An op with `AccessControl::default()` (no restrictions) is listed to any
peer — implicitly callable by any authenticated peer.
- An op with `required_scopes` is listed only to peers whose `Identity.scopes`
satisfy them.
- An op with `Visibility::Internal` is never listed (excluded from
`list_operations()` which already filters to `External`).
### services/list-peers (opt-in)
The opt-in for peer-attributed re-export listing — each peer's sub-overlay
listed with attribution, filtered by the calling peer's authorization:
```rust
pub fn services_list_peers_handler(/* ... */) -> Handler {
// Lists ops from each peer's sub-overlay in PeerCompositeEnv,
// attributed by peer_id, filtered by AccessControl::check(calling_identity).
// Opt-in: the calling peer invokes this operation name explicitly.
}
```
This operation is registered alongside `services/list` and `services/schema`.
It iterates the peer-keyed overlays (via `context.env`), lists each peer's ops
with `peer_id` attribution, and filters by the calling peer's authorization.
### What this task does NOT do
- Does NOT change `services/schema` (unchanged — returns full spec for a
named op).
- Does NOT build the `PeerCompositeEnv` (that's `call/peer-composite-env`) —
but `services/list-peers` consumes it via `context.env`. If
`PeerCompositeEnv` is not yet built, `services/list-peers` can be registered
with a stub that returns empty until the env is ready, or this task can
depend on `call/peer-composite-env`. **This task depends only on
`call/retire-remote-safe`** so `services/list` (the AccessControl filter)
can land independently; `services/list-peers` is implemented to consume
`PeerCompositeEnv` via `context.env.peer_contains` (which has a default-impl
that works even before `PeerCompositeEnv` is wired).
## Acceptance Criteria
- [ ] `services_list_handler` filters by `AccessControl::check(context.identity)`
- [ ] Op with `AccessControl::default()` listed to any peer
- [ ] Op with `required_scopes` listed only to authorized peers
- [ ] Op with `Visibility::Internal` never listed (unchanged — `list_operations` filters to External)
- [ ] `services_list_handler_peer_scoped` removed (was removed in `call/retire-remote-safe`; verify gone)
- [ ] `services/list-peers` opt-in operation added (peer-attributed, AccessControl-filtered)
- [ ] `services/schema` unchanged
- [ ] Unit test: `services/list` lists only ops the calling peer is authorized for
- [ ] Unit test: op with no restrictions listed to any peer
- [ ] Unit test: op with required_scopes hidden from unauthorized peer
- [ ] Unit test: `services/list-peers` attributes ops by peer_id
- [ ] `cargo test -p alknet-call` succeeds
- [ ] `cargo clippy -p alknet-call` succeeds with no warnings
## References
- docs/architecture/crates/call/operation-registry.md — Service Discovery
- docs/architecture/crates/call/client-and-adapters.md — services/list AccessControl-filtered
- docs/architecture/decisions/029-peer-graph-routing-model.md — ADR-029 §6
## Notes
> `services/list` semantics change: the filter is `AccessControl`-based, not
> `remote_safe`-based. An op with `AccessControl::default()` is now listed to
> any peer — this is correct (it's implicitly callable by any authenticated
> peer). Operators who relied on `remote_safe: false` to hide ops from peers
> must instead set `required_scopes` or `Visibility::Internal`. The
> `services/list-peers` opt-in is for peer-attributed re-export listing.
## Summary
> To be filled on completion

114
tasks/core/config-identity-provider-peerentry.md Normal file
View File

@@ -0,0 +1,114 @@
---
id: core/config-identity-provider-peerentry
name: Rewrite ConfigIdentityProvider resolution to use PeerEntry multi-credential path (ADR-030)
status: pending
depends_on: [core/peer-entry-model]
scope: narrow
risk: medium
impact: component
level: implementation
---
## Description
Rewrite `ConfigIdentityProvider::resolve_from_fingerprint` and
`resolve_from_token` to use the new `PeerEntry`-based resolution from
`core/peer-entry-model`. This is the resolution-logic half of the ADR-030
change — the data model (PeerEntry struct, AuthPolicy.peers) lands in
`core/peer-entry-model`; this task updates the `ConfigIdentityProvider` methods
that delegate to `AuthPolicy`.
### Current state (pre-ADR-030)
```rust
impl IdentityProvider for ConfigIdentityProvider {
fn resolve_from_fingerprint(&self, fingerprint: &str) -> Option<Identity> {
let config = self.dynamic.load();
config.auth.resolve_identity_from_fingerprint(fingerprint)
}
fn resolve_from_token(&self, token: &AuthToken) -> Option<Identity> {
let config = self.dynamic.load();
let token_str = String::from_utf8_lossy(&token.raw);
config.auth.resolve_api_key(&token_str) // ← only ApiKeyEntry path
}
}
```
### Target state (ADR-030)
```rust
impl IdentityProvider for ConfigIdentityProvider {
fn resolve_from_fingerprint(&self, fingerprint: &str) -> Option<Identity> {
let config = self.dynamic.load();
config.auth.resolve_identity_from_fingerprint(fingerprint)
// Now resolves: fingerprint → PeerEntry → Identity { id: peer_id, ... }
}
fn resolve_from_token(&self, token: &AuthToken) -> Option<Identity> {
let config = self.dynamic.load();
let token_str = String::from_utf8_lossy(&token.raw);
config.auth.resolve_identity_from_token(&token_str)
// Now tries PeerEntry.auth_token_hash first, falls through to ApiKeyEntry
}
}
```
The key change in `resolve_from_token`: it now calls
`AuthPolicy::resolve_identity_from_token` (added in `core/peer-entry-model`),
which tries the `PeerEntry.auth_token_hash` path first (token is one credential
path among several for a stable logical peer → `Identity.id = peer_id`), then
falls through to `resolve_api_key` (token IS the identity → `Identity.id =
prefix`).
### ConfigIdentityProvider stays read-only
`ConfigIdentityProvider` still reads from `ArcSwap<DynamicConfig>` on every call
(hot-reloadable). It does NOT implement `IdentityStore` (that's
`core/identity-store-trait` — config reload is its write path, not a method
call).
### Test migration
The existing auth.rs tests use `authorized_fingerprints: HashSet<String>` and
expect `Identity.id == fingerprint`. These must migrate to the `PeerEntry` model:
- `config_with_fingerprint` helper → `config_with_peer_entry` helper
- Fingerprint resolution tests expect `Identity.id == peer_id` (not the fingerprint)
- Add token-resolution-via-PeerEntry tests (auth_token_hash path)
- Config reload tests use `PeerEntry` in the new config
## Acceptance Criteria
- [ ] `ConfigIdentityProvider::resolve_from_fingerprint` delegates to `AuthPolicy::resolve_identity_from_fingerprint` (PeerEntry path)
- [ ] `ConfigIdentityProvider::resolve_from_token` delegates to `AuthPolicy::resolve_identity_from_token` (PeerEntry.auth_token_hash → fall through to ApiKeyEntry)
- [ ] `ConfigIdentityProvider` reads from ArcSwap on every call (hot-reloadable — unchanged)
- [ ] `ConfigIdentityProvider` does NOT implement `IdentityStore`
- [ ] Fingerprint resolution returns `Identity { id: peer_id, ... }` (stable, not the fingerprint)
- [ ] Token resolution: PeerEntry.auth_token_hash match → `Identity { id: peer_id }`; no match → ApiKeyEntry fall-through → `Identity { id: prefix }`
- [ ] All existing auth.rs tests migrated to PeerEntry model (no `authorized_fingerprints` references)
- [ ] Unit test: fingerprint resolution via PeerEntry (known → Some with peer_id, unknown → None)
- [ ] Unit test: token resolution via PeerEntry.auth_token_hash (matching → Some with peer_id)
- [ ] Unit test: token resolution falls through to ApiKeyEntry when no PeerEntry matches
- [ ] Unit test: config reload changes resolution results immediately (PeerEntry model)
- [ ] Unit test: disabled PeerEntry returns None
- [ ] `cargo test -p alknet-core` succeeds
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
## References
- docs/architecture/crates/core/auth.md — ConfigIdentityProvider, multi-credential resolution
- docs/architecture/crates/core/config.md — AuthPolicy.peers, PeerEntry
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030 §2 (resolution semantics)
## Notes
> This is the resolution-logic half of the ADR-030 change. The data model lands
> in `core/peer-entry-model`; this task wires `ConfigIdentityProvider` to the
> new `AuthPolicy` methods. The semantic shift: `Identity.id` changes from the
> fingerprint to the `peer_id` on the fingerprint path. The token path gains a
> new first-try (PeerEntry.auth_token_hash) before the existing ApiKeyEntry
> fall-through. ConfigIdentityProvider stays read-only and ArcSwap-backed.
## Summary
> To be filled on completion

144
tasks/core/credential-store-trait.md Normal file
View File

@@ -0,0 +1,144 @@
---
id: core/credential-store-trait
name: Add CredentialStore trait, InMemoryCredentialStore, EncryptedData mirror, and StoreError (ADR-031/035)
status: pending
depends_on: []
scope: narrow
risk: low
impact: component
level: implementation
---
## Description
Add the second repo trait to alknet-core: `CredentialStore` for encrypted-
credential persistence, alongside its in-memory default adapter and the shared
`StoreError` type. Per ADR-031 (the trait) and ADR-035 (refines `put`/`delete`
to async, renames the error to `StoreError`).
This task is standalone — it has no dependency on `core/peer-entry-model`. The
`CredentialStore` trait persists `EncryptedData` blobs (the vault's encrypted
output); it never decrypts (ADR-025 — the vault is the sole decryption
boundary).
### CredentialStore trait
```rust
pub trait CredentialStore: Send + Sync {
fn get(&self, provider: &str) -> Option<EncryptedData>;
async fn put(&self, provider: &str, data: &EncryptedData) -> Result<(), StoreError>;
async fn delete(&self, provider: &str) -> Result<(), StoreError>;
}
```
- `get` is **sync** (cached read — the hot path; ADR-035 §1).
- `put`/`delete` are **async** (they hit the backend; ADR-035 §3 refines
ADR-031's sync sketch to async within the one-way door).
- `get` returns `Option<EncryptedData>` (missing credential is the common case,
not an error).
- No `list` method (ADR-031 §4 — additive if needed later).
### InMemoryCredentialStore
```rust
pub struct InMemoryCredentialStore {
entries: RwLock<HashMap<String, EncryptedData>>,
}
impl InMemoryCredentialStore {
pub fn new() -> Self;
pub fn with_entries(entries: HashMap<String, EncryptedData>) -> Self;
}
impl CredentialStore for InMemoryCredentialStore { ... }
```
The default adapter covers tests and config-loaded deployments. `put`/`delete`
are async with no `.await` points (trivially satisfy an async trait — ADR-035
§3). Same posture as `ConfigIdentityProvider` — no persistence, no backend
dependency, no env vars.
### EncryptedData core mirror
A thin serializable struct mirroring the vault's `EncryptedData` (ADR-020),
so the trait can reference it without a vault dependency (ADR-018 — vault is
standalone with zero alknet-crate dependencies):
```rust
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct EncryptedData {
pub key_version: u32,
pub salt: Vec<u8>, // wire-format compat (OQ-20); unused in v2 but kept
pub iv: Vec<u8>, // AES-GCM IV (OsRng-generated)
pub data: Vec<u8>, // ciphertext
}
```
The `salt` field is kept for wire-format compatibility with the TS predecessor
(OQ-20) — a core mirror that omitted it could not round-trip the vault's
`EncryptedData`. v2 may write a zero-length salt but must not drop the field
(ADR-035 §6).
### StoreError
```rust
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum StoreError {
#[error("backend error: {message}")]
Backend { message: String },
#[error("not found: {entity}")]
NotFound { entity: String },
#[error("serialization error: {message}")]
Serialization { message: String },
}
```
Shared by both `CredentialStore` and `IdentityStore` (ADR-035 §7 renames
ADR-031's `CredentialStoreError` to `StoreError`). `#[non_exhaustive]` so
adapter crates can extend without breaking match arms. Lives in alknet-core
(where the traits live).
### Module placement
Add a new `store` module (or `credential_store` module) in `alknet-core/src/`.
Re-export `CredentialStore`, `InMemoryCredentialStore`, `EncryptedData`, and
`StoreError` from `lib.rs`.
## Acceptance Criteria
- [ ] `CredentialStore` trait with sync `get`, async `put`/`delete`
- [ ] `InMemoryCredentialStore` with `new()` and `with_entries()`
- [ ] `InMemoryCredentialStore` implements `CredentialStore` (async put/delete with no .await points)
- [ ] `EncryptedData` core mirror with 4 fields (`key_version`, `salt`, `iv`, `data`), derives Serialize/Deserialize/Clone/Debug
- [ ] `StoreError` enum with 3 variants, `#[non_exhaustive]`, `thiserror::Error`
- [ ] No vault dependency added to alknet-core (EncryptedData is a core-owned mirror)
- [ ] No `list` method on the trait
- [ ] Unit test: InMemoryCredentialStore get/put/delete round-trip
- [ ] Unit test: get returns None for missing provider
- [ ] Unit test: EncryptedData serializes and deserializes (round-trip)
- [ ] Unit test: StoreError Display formatting
- [ ] `cargo test -p alknet-core` succeeds
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
## References
- docs/architecture/crates/core/auth.md — CredentialStore, StoreError, EncryptedData mirror
- docs/architecture/decisions/031-credentialstore-repo-trait.md — ADR-031 (the trait)
- docs/architecture/decisions/035-concrete-persistence-adapter-shapes.md — ADR-035 (async put/delete, StoreError rename, schema)
- docs/architecture/decisions/033-storage-boundary-and-repo-adapter-pattern.md — ADR-033 (the pattern)
## Notes
> Standalone task — no dependency on PeerEntry. The `CredentialStore` trait is
> the second repo trait in core (alongside `IdentityProvider`), establishing
> the repo/adapter pattern concretely (ADR-033). The trait is the one-way door;
> the in-memory default is the reference implementation; persistence adapters
> (alknet-store-sqlite, ADR-035) are separate crates, not built in this sync.
> `get` stays sync because the credential load happens at startup into
> `Capabilities` (ADR-031); `put`/`delete` are async because a SQLite-backed
> adapter cannot do a sync write without blocking (ADR-035 §3).
## Summary
> To be filled on completion

127
tasks/core/fingerprint-normalization.md Normal file
View File

@@ -0,0 +1,127 @@
---
id: core/fingerprint-normalization
name: Normalize quinn Ed25519 raw-key fingerprint to ed25519:hex format (ADR-030 §6)
status: pending
depends_on: [core/peer-entry-model]
scope: narrow
risk: medium
impact: component
level: implementation
---
## Description
Normalize the quinn Ed25519 raw-key fingerprint extraction to produce
`ed25519:<hex of 32-byte pub key>`, matching the iroh path. Currently
`fingerprint_from_cert_der` produces `SHA256:<hex of cert DER>` for ALL certs,
including RFC 7250 raw public keys. ADR-030 §6 requires that Ed25519 raw keys
produce `ed25519:<hex>` regardless of transport (quinn or iroh), so the same
key has the same fingerprint in `PeerEntry.fingerprints` — one entry, both
transports.
### Current state
```rust
// crates/alknet-core/src/endpoint.rs
fn extract_quinn_client_fingerprint(connection: &quinn::Connection) -> Option<String> {
let identity = connection.peer_identity()?;
let cert = identity.iter().next()?;
fingerprint_from_cert_der(cert.as_ref())
}
fn fingerprint_from_cert_der(cert_der: &[u8]) -> Option<String> {
// Always SHA256:<hex of DER> — wrong for Ed25519 raw keys
let mut hasher = Sha256::new();
hasher.update(cert_der);
Some(format!("SHA256:{}", hex::encode(hasher.finalize())))
}
fn extract_iroh_client_fingerprint(connection: &iroh::endpoint::Connection) -> Option<String> {
let node_id = connection.remote_node_id().ok()?;
Some(format!("ed25519:{}", node_id)) // ← already correct
}
```
### Target state (ADR-030 §6)
`fingerprint_from_cert_der` (or a new `fingerprint_from_client_cert` function)
must distinguish:
1. **RFC 7250 raw public key cert** (SPKI with Ed25519 algorithm identifier):
extract the raw 32-byte Ed25519 public key from the SPKI DER and format as
`ed25519:<lowercase hex of 32 bytes>`. This matches the iroh path — the same
key has the same fingerprint regardless of transport.
2. **X.509 cert**: keep `SHA256:<hex of cert DER>` (the DER hash — X.509 certs
don't have a "raw public key" form).
The distinction is whether the presented cert is an RFC 7250 raw public key
(SPKI with Ed25519 algorithm identifier, no X.509 wrapper) or a full X.509
cert. The `RawKeyCertResolver` on the server side already has the raw key bytes
via `Ed25519SecretKey::public()`; the client-side extraction must parse the
SPKI DER to extract the raw key.
### Fingerprint format table (ADR-030 §6)
| Transport | Source | Format |
|-----------|--------|--------|
| iroh (direct or relay) | peer `NodeId` (Ed25519 public key) | `ed25519:<lowercase hex of 32-byte pub key>` |
| quinn (RFC 7250 raw key) | SPKI cert → extract raw Ed25519 pub key | `ed25519:<lowercase hex of 32-byte pub key>` (normalized) |
| quinn (X.509) | leaf client cert DER | `SHA256:<hex of SHA-256(cert_der)>` |
### Implementation approach
Parse the cert DER to detect whether it's a raw public key (SPKI) or an X.509
cert. If SPKI with Ed25519 algorithm identifier, extract the 32-byte public key
and format as `ed25519:<hex>`. Otherwise, hash the full DER as `SHA256:<hex>`.
The `rustls-pki-types` crate (already a dependency) provides
`CertificateDer`. The `rustls` crate's webpki or a manual DER parse of the
SPKI's `SubjectPublicKeyInfo` → `subjectPublicKey` field can extract the raw
key. A minimal DER parser for the SPKI structure (AlgorithmIdentifier +
subjectPublicKey) is sufficient — the structure is small and well-defined.
### Test migration
The existing endpoint.rs tests expect `SHA256:` for all fingerprints. Tests
with Ed25519 raw keys must migrate to expect `ed25519:`. Tests with X.509 certs
stay `SHA256:`. Add a test that the same Ed25519 key produces the same
fingerprint via both the quinn SPKI-extraction path and the iroh NodeId path
(if testable without a live iroh connection, test the format function directly).
## Acceptance Criteria
- [ ] `fingerprint_from_cert_der` (or replacement) distinguishes RFC 7250 raw key SPKI from X.509 cert
- [ ] Ed25519 raw key (SPKI) → `ed25519:<lowercase hex of 32-byte pub key>`
- [ ] X.509 cert → `SHA256:<hex of SHA-256(cert_der)>` (unchanged)
- [ ] iroh path already produces `ed25519:<hex>` (unchanged — verify)
- [ ] Same Ed25519 key produces same fingerprint via quinn and iroh paths
- [ ] No-client-cert case still produces `tls_client_fingerprint: None` (no regression)
- [ ] Unit test: Ed25519 raw key SPKI → `ed25519:<hex>` format
- [ ] Unit test: X.509 cert → `SHA256:<hex>` format (unchanged)
- [ ] Unit test: fingerprint is lowercase hex
- [ ] Unit test: 32-byte pub key extracted correctly (not the DER wrapper)
- [ ] Existing endpoint.rs fingerprint tests migrated (Ed25519 → `ed25519:`, X.509 → `SHA256:`)
- [ ] `cargo test -p alknet-core` succeeds
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
## References
- docs/architecture/crates/core/auth.md — Fingerprint string format table
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030 §6 (normalization rationale)
- docs/architecture/decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md — ADR-027 (RawKey model)
## Notes
> The normalization is load-bearing for the peer graph: a peer that connects
> via quinn direct and via iroh must have the same fingerprint in
> `PeerEntry.fingerprints` — one entry, both transports. Without this, the same
> key produces `ed25519:abc...` on iroh and `SHA256:def...` on quinn, breaking
> the ADR-030 resolution path. The X.509 path stays `SHA256:<hex of DER>`
> because X.509 certs don't have a "raw public key" form. This also simplifies
> the coming WebTransport relay work (proxied Ed25519 identity is the same
> `ed25519:<hex>` whether direct or proxied).
## Summary
> To be filled on completion

98
tasks/core/identity-store-trait.md Normal file
View File

@@ -0,0 +1,98 @@
---
id: core/identity-store-trait
name: Add IdentityStore async write trait extending IdentityProvider (ADR-035)
status: pending
depends_on: [core/peer-entry-model]
scope: single
risk: low
impact: component
level: implementation
---
## Description
Add the `IdentityStore` async write trait for peer management, extending the
read-only `IdentityProvider` trait. Per ADR-035 §2.
`IdentityProvider` is read-only today and stays read-only — it is the hot-path
trait called on every incoming connection (sync, no `.await`). Peer mutations
(add/update/remove a `PeerEntry`) go through this separate async trait.
### IdentityStore trait
```rust
/// Write trait — management path, async (ADR-035). ConfigIdentityProvider
/// does NOT implement this (config reload is its write path — see below).
/// SqliteIdentityProvider does: writes hit SQLite, emit honker NOTIFY,
/// and the local LISTEN refreshes the in-memory read index.
#[async_trait]
pub trait IdentityStore: IdentityProvider {
async fn put_peer(&self, peer: &PeerEntry) -> Result<(), StoreError>;
async fn update_peer(&self, peer_id: &str, peer: &PeerEntry) -> Result<(), StoreError>;
async fn remove_peer(&self, peer_id: &str) -> Result<(), StoreError>;
}
```
- `put_peer` — insert or replace a `PeerEntry` (upsert by `peer_id`).
- `update_peer` — update an existing `PeerEntry` (error if `peer_id` not found;
for upsert semantics use `put_peer`).
- `remove_peer` — delete a `PeerEntry` by `peer_id`.
### Why a separate trait, not async methods on IdentityProvider
- The hot-path read trait is consumed by the accept loop and every handler —
those call sites are sync and must not gain `.await`. If `put_peer` were on
`IdentityProvider`, every consumer would see the async method even though
only the management path calls it. A separate `IdentityStore: IdentityProvider`
supertrait keeps the read surface lean and makes the write surface opt-in.
- `ConfigIdentityProvider` does **not** implement `IdentityStore`. Its write
path is config reload (`ConfigReloadHandle::reload`), not a method call. This
preserves the config-is-source-of-truth model. Implementing `IdentityStore`
> for `ConfigIdentityProvider` "for symmetry" would violate that model — the
> constraint is the absence of a backend, not a type-system constraint.
### ConfigIdentityProvider posture
`ConfigIdentityProvider` deliberately does NOT implement `IdentityStore`. This
task does not change `ConfigIdentityProvider` — it only adds the trait. The
trait is defined for future adapters (`SqliteIdentityProvider` in
`alknet-store-sqlite`) to implement. `StoreError` is already defined by
`core/credential-store-trait`.
### Module placement
Add `IdentityStore` alongside `IdentityProvider` in `alknet-core/src/auth.rs`
(or a new `store` module if `CredentialStore` landed there). Re-export from
`lib.rs`.
## Acceptance Criteria
- [ ] `IdentityStore` trait with `put_peer`, `update_peer`, `remove_peer` (all async)
- [ ] `IdentityStore: IdentityProvider` (supertrait)
- [ ] `StoreError` used as the error type (from `core/credential-store-trait`)
- [ ] `ConfigIdentityProvider` does NOT implement `IdentityStore`
- [ ] `#[async_trait]` on the trait
- [ ] No changes to `IdentityProvider` trait (stays read-only, sync)
- [ ] Unit test: a mock/test impl of `IdentityStore` compiles and works (verify the trait is implementable)
- [ ] Unit test: `ConfigIdentityProvider` does not implement `IdentityStore` (compile-time or trait-bound assertion)
- [ ] `cargo test -p alknet-core` succeeds
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
## References
- docs/architecture/crates/core/auth.md — IdentityStore write trait, ConfigIdentityProvider posture
- docs/architecture/decisions/035-concrete-persistence-adapter-shapes.md — ADR-035 §2 (the trait, read/write split rationale)
- docs/architecture/decisions/033-storage-boundary-and-repo-adapter-pattern.md — ADR-033 (the pattern)
## Notes
> Small task but locks the trait shape — a one-way door. The read/write split
> keeps the hot path sync (no `.await` in the accept loop). `ConfigIdentityProvider`
> not implementing `IdentityStore` is a design posture, not a type-system
> constraint: it holds no backend, and its write path is config reload. A
> deployment that wants method-call peer management wires the SQLite adapter
> (a separate crate, not built in this sync).
## Summary
> To be filled on completion

175
tasks/core/peer-entry-model.md Normal file
View File

@@ -0,0 +1,175 @@
---
id: core/peer-entry-model
name: Add PeerEntry struct and replace AuthPolicy.authorized_fingerprints with peers (ADR-030)
status: pending
depends_on: []
scope: moderate
risk: medium
impact: component
level: implementation
---
## Description
Replace `AuthPolicy.authorized_fingerprints: HashSet<String>` with
`AuthPolicy.peers: Vec<PeerEntry>`, per ADR-030. This is the foundational data
change for the entire ADR-029/030 sync — every downstream task (core resolution
logic, IdentityStore, call peer-keyed routing, fingerprint normalization) depends
on this struct and the `AuthPolicy.peers` field.
This task adds the `PeerEntry` struct and the `AuthPolicy.peers` field, and
migrates the `AuthPolicy` resolution methods to the new model. The
`ConfigIdentityProvider` rewrite (the resolution-logic half) is a separate task
(`core/config-identity-provider-peerentry`) so this task stays focused on the
data model + `AuthPolicy` resolution methods.
### PeerEntry struct
```rust
pub struct PeerEntry {
/// Stable logical peer id ("worker-a", "alice"). Does NOT change on
/// key rotation. This becomes Identity.id on resolution, regardless of
/// which credential path resolved the identity.
pub peer_id: String,
/// TLS fingerprints for this peer — one or more. A peer may have
/// multiple keys (e.g., an Ed25519 raw key for P2P and an X.509 cert
/// for domain-facing). Resolution matches against any entry.
/// Format: "ed25519:<hex of 32-byte pub key>" for RFC 7250 raw keys
/// (normalized across quinn and iroh — ADR-030 §6), "SHA256:<hex>" for
/// X.509 certs (DER hash). Changes on key rotation.
pub fingerprints: Vec<String>,
/// Optional: bearer-token authentication for this peer. A peer that
/// also authenticates via auth_token (e.g., HTTP clients that can't
/// do TLS client-auth) stores the SHA-256 hash of the token here.
/// Resolution via resolve_from_token matches this field and returns
/// the same Identity { id: peer_id, ... } as the fingerprint path.
pub auth_token_hash: Option<String>,
/// Authorization scopes granted to this peer. Resolved into
/// Identity.scopes.
pub scopes: Vec<String>,
/// Named resource lists granted to this peer. Resolved into
/// Identity.resources.
pub resources: HashMap<String, Vec<String>>,
/// Human-readable display name for logs / UIs. Optional.
pub display_name: Option<String>,
/// Whether this peer is authorized at all. false = recognized but
/// disabled (revoked). Resolution returns None.
pub enabled: bool,
}
```
### AuthPolicy change
```rust
pub struct AuthPolicy {
/// Replaces authorized_fingerprints: HashSet<String>. Each entry maps
/// a stable logical peer_id to its credential paths (fingerprints,
/// optional auth_token_hash) + scopes + resources. The list is keyed
/// by peer_id; resolution looks up by fingerprint OR auth_token.
pub peers: Vec<PeerEntry>,
/// API keys for bearer-token auth where the token IS the identity
/// (rotation = new identity). Unchanged by ADR-030.
pub api_keys: Vec<ApiKeyEntry>,
}
```
### AuthPolicy resolution methods (new model)
`AuthPolicy::resolve_identity_from_fingerprint` and a new
`resolve_identity_from_token` method resolve via `PeerEntry`:
```rust
impl AuthPolicy {
pub fn resolve_identity_from_fingerprint(&self, fingerprint: &str) -> Option<Identity> {
self.peers.iter()
.find(|p| p.enabled && p.fingerprints.iter().any(|f| f == fingerprint))
.map(|p| Identity {
id: p.peer_id.clone(),
scopes: p.scopes.clone(),
resources: p.resources.clone(),
})
}
pub fn resolve_identity_from_token(&self, token: &str) -> Option<Identity> {
let token_hash = sha256(token);
self.peers.iter()
.find(|p| p.enabled && p.auth_token_hash.as_deref() == Some(&token_hash))
.map(|p| Identity {
id: p.peer_id.clone(),
scopes: p.scopes.clone(),
resources: p.resources.clone(),
})
.or_else(|| self.resolve_api_key(token)) // fall through to ApiKeyEntry
}
}
```
The key change: `Identity.id` is now the stable `peer_id`, **not** the
fingerprint. Key rotation changes the fingerprint but not the `peer_id`, so ACL
entries and routing references stay stable (ADR-030 §2-3).
`resolve_api_key` stays unchanged (the `ApiKeyEntry` path where the token IS the
identity — `Identity.id = prefix`).
### Config validation
`PeerEntry.peer_id` is operator-chosen and unique within a config. Add a
validation method or assertion that duplicate `peer_id` values in
`AuthPolicy.peers` are a config error (ADR-030 Assumption 2).
### What this task does NOT do
- Does NOT rewrite `ConfigIdentityProvider` — that's
`core/config-identity-provider-peerentry` (the `ConfigIdentityProvider` methods
delegate to `AuthPolicy` resolution, so they keep working once `AuthPolicy`
is updated, but the token-resolution path in `ConfigIdentityProvider` needs to
call the new `resolve_identity_from_token` instead of only `resolve_api_key`).
- Does NOT normalize quinn fingerprints to `ed25519:<hex>` — that's
`core/fingerprint-normalization`.
- Does NOT add `IdentityStore` or `CredentialStore` — those are separate tasks.
## Acceptance Criteria
- [ ] `PeerEntry` struct with all 7 fields (`peer_id`, `fingerprints`, `auth_token_hash`, `scopes`, `resources`, `display_name`, `enabled`)
- [ ] `AuthPolicy.authorized_fingerprints` removed; replaced with `peers: Vec<PeerEntry>`
- [ ] `AuthPolicy.api_keys` unchanged
- [ ] `AuthPolicy::resolve_identity_from_fingerprint` resolves fingerprint → PeerEntry → `Identity { id: peer_id, ... }`
- [ ] `AuthPolicy::resolve_identity_from_token` resolves token hash → PeerEntry → `Identity { id: peer_id, ... }`, falls through to `resolve_api_key`
- [ ] `Identity.id` is the `peer_id` (stable), not the fingerprint
- [ ] Disabled peers (`enabled: false`) return `None` from resolution
- [ ] Duplicate `peer_id` validation (config error)
- [ ] Unit test: fingerprint resolution via PeerEntry (known → Some with peer_id, unknown → None, disabled → None)
- [ ] Unit test: token resolution via PeerEntry.auth_token_hash (matching → Some with peer_id, non-matching → fall through to ApiKeyEntry)
- [ ] Unit test: multi-fingerprint PeerEntry (any fingerprint in the list resolves to the same peer_id)
- [ ] Unit test: resources populated from PeerEntry.resources on both paths
- [ ] Unit test: duplicate peer_id detected/rejected
- [ ] `cargo test -p alknet-core` succeeds
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
## References
- docs/architecture/crates/core/config.md — PeerEntry, AuthPolicy.peers
- docs/architecture/crates/core/auth.md — Identity.id = peer_id, multi-credential resolution
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md — ADR-030
## Notes
> This is the foundational data change for the ADR-029/030 sync. The key
> semantic shift: `Identity.id` changes from the fingerprint (crypto material)
> to the `peer_id` (stable logical id). Key rotation changes the fingerprint
> but not the `peer_id`, so ACL entries and `PeerRef::Specific(peer_id)`
> references stay stable. `ConfigIdentityProvider` keeps working (it delegates
> to `AuthPolicy`), but the token path needs the new
> `resolve_identity_from_token` — that's the separate
> `core/config-identity-provider-peerentry` task.
## Summary
> To be filled on completion

123
tasks/core/review-core-sync.md Normal file
View File

@@ -0,0 +1,123 @@
---
id: core/review-core-sync
name: Review alknet-core ADR-029/030/031/034/035 sync for spec conformance
status: pending
depends_on: [core/credential-store-trait, core/identity-store-trait, core/config-identity-provider-peerentry, core/fingerprint-normalization, core/three-remote-roles-docs]
scope: moderate
risk: low
impact: phase
level: review
---
## Description
Review the alknet-core implementation after the ADR-029/030/031/034/035 sync
for spec conformance, pattern consistency, and correctness. This is the quality
checkpoint at the end of the core phase — before alknet-call (which depends on
the new `Identity.id = peer_id` semantics) begins its sync.
### Review Checklist
1. **PeerEntry / AuthPolicy conformance** (config.md, auth.md, ADR-030):
- `PeerEntry` has all 7 fields (peer_id, fingerprints, auth_token_hash, scopes, resources, display_name, enabled)
- `AuthPolicy.authorized_fingerprints` removed; `peers: Vec<PeerEntry>` in place
- `AuthPolicy.api_keys` unchanged
- `resolve_identity_from_fingerprint` resolves fingerprint → PeerEntry → `Identity { id: peer_id }`
- `resolve_identity_from_token` resolves auth_token_hash → PeerEntry → falls through to ApiKeyEntry
- `Identity.id` is the stable `peer_id`, not the fingerprint
- Disabled peers (`enabled: false`) return None
- Duplicate `peer_id` validation
2. **ConfigIdentityProvider conformance** (auth.md, ADR-030):
- `resolve_from_fingerprint` delegates to `AuthPolicy::resolve_identity_from_fingerprint`
- `resolve_from_token` delegates to `AuthPolicy::resolve_identity_from_token` (PeerEntry first, ApiKeyEntry fall-through)
- Reads from ArcSwap on every call (hot-reloadable — unchanged)
- Does NOT implement `IdentityStore`
3. **CredentialStore conformance** (auth.md, ADR-031/035):
- `CredentialStore` trait with sync `get`, async `put`/`delete`
- `InMemoryCredentialStore` default adapter (async put/delete with no .await points)
- `EncryptedData` core mirror (4 fields, serializable, no vault dep)
- `StoreError` enum (`#[non_exhaustive]`, thiserror, 3 variants)
- No `list` method
- No vault dependency added to core
4. **IdentityStore conformance** (auth.md, ADR-035):
- `IdentityStore: IdentityProvider` supertrait
- `put_peer`/`update_peer`/`remove_peer` all async
- `ConfigIdentityProvider` does NOT implement it
- `IdentityProvider` trait unchanged (read-only, sync)
5. **Fingerprint normalization conformance** (auth.md, ADR-030 §6):
- Ed25519 raw key (SPKI) → `ed25519:<lowercase hex of 32 bytes>`
- X.509 cert → `SHA256:<hex of DER>` (unchanged)
- iroh path → `ed25519:<hex>` (unchanged)
- Same key, same fingerprint across quinn and iroh
- No-client-cert → None (no regression)
6. **Three remote roles documentation** (ADR-034):
- `auth.rs` comments document the three roles and verifier selection rule
- `endpoint.rs` comments clarify server-side vs client-side verifier concerns
7. **Pattern consistency**:
- ArcSwap used consistently for DynamicConfig (unchanged)
- Repo/adapter pattern consistent (trait + in-memory default, no backend dep in core)
- No russh dependency in core (unchanged)
- Feature flags (quinn, iroh) gate transport code correctly
8. **Security constraints**:
- `PeerEntry.enabled: false` → resolution returns None (revoked peers)
- `StoreError` is `#[non_exhaustive]`
- `EncryptedData` carries no plaintext (encrypted blob only)
- No env vars in the credential path (ADR-014 invariant preserved)
9. **Test coverage**:
- PeerEntry resolution (fingerprint, auth_token_hash, ApiKeyEntry fall-through)
- Multi-fingerprint PeerEntry
- Disabled peer → None
- Duplicate peer_id validation
- CredentialStore get/put/delete round-trip
- EncryptedData serialization round-trip
- Fingerprint normalization (Ed25519 → ed25519:, X.509 → SHA256:)
- Config reload with PeerEntry model
## Acceptance Criteria
- [ ] All PeerEntry / AuthPolicy types match config.md and auth.md
- [ ] ConfigIdentityProvider resolution matches auth.md (PeerEntry multi-credential path)
- [ ] CredentialStore trait + InMemoryCredentialStore + EncryptedData + StoreError match ADR-031/035
- [ ] IdentityStore trait matches ADR-035 (read/write split, ConfigIdentityProvider posture)
- [ ] Fingerprint normalization matches ADR-030 §6 (ed25519: for raw keys, SHA256: for X.509)
- [ ] Three remote roles documented in source comments (ADR-034)
- [ ] No `authorized_fingerprints` references remain
- [ ] No `remote_safe`/`trusted_peer` references in core (those are call-side)
- [ ] ArcSwap pattern consistent
- [ ] No russh dependency, no vault dependency in core
- [ ] Test coverage adequate for all new functionality
- [ ] `cargo fmt --check -p alknet-core` passes
- [ ] `cargo clippy -p alknet-core` passes with no warnings
- [ ] All tests pass
## References
- docs/architecture/crates/core/README.md
- docs/architecture/crates/core/auth.md
- docs/architecture/crates/core/config.md
- docs/architecture/decisions/030-peerentry-and-identity-id-decoupling.md
- docs/architecture/decisions/031-credentialstore-repo-trait.md
- docs/architecture/decisions/033-storage-boundary-and-repo-adapter-pattern.md
- docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md
- docs/architecture/decisions/035-concrete-persistence-adapter-shapes.md
## Notes
> This review verifies core is spec-conformant after the ADR-029/030/031/034/035
> sync before alknet-call begins its sync. alknet-call depends heavily on the new
> `Identity.id = peer_id` semantics (PeerCompositeEnv keys, PeerRef::Specific
> routing, AccessControl-based peer authorization) — any issues here propagate
> to call. If deviations are found, document and fix before proceeding to the
> call phase.
## Summary
> To be filled on completion

85
tasks/core/three-remote-roles-docs.md Normal file
View 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