---
id: core/peer-entry-model
name: Add PeerEntry struct and replace AuthPolicy.authorized_fingerprints with peers (ADR-030)
status: completed
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

Implemented PeerEntry struct (7 fields) in config.rs, replaced `AuthPolicy.authorized_fingerprints: HashSet<String>` with `peers: Vec<PeerEntry>`. Added `resolve_identity_from_token` (PeerEntry.auth_token_hash → fall through to resolve_api_key) and updated `resolve_identity_from_fingerprint` to resolve via PeerEntry returning `Identity.id = peer_id` (stable). Added `validate_peer_ids()` returning `DuplicatePeerId` error. Migrated all auth.rs/config.rs tests to PeerEntry model with new unit tests covering fingerprint resolution (known/unknown/disabled), token resolution (matching/non-matching/fall-through), multi-fingerprint peers, resource population on both paths, and duplicate peer_id detection. Also fixed a pre-existing test compile bug in endpoint.rs (StaticConfig.iroh_relay field reference not gated behind #[cfg(feature = "iroh")]). 110 tests pass, clippy clean, fmt clean.