alkcall/docs/architecture/decisions/012-connectioncredentials-decouple-dial-from-call.md

ADR-012: ConnectionCredentials — Decouple the Dial Credentials from the Call Protocol

Status

Accepted (amends ADR-045 §3 and §5; amends ADR-087's TlsClientConfig::new input framing; amended 2026-07-17 — CallCredentials is removed, not retained in alknet-call; from_call's credentials_auth_token dead path removed; auth_token is a per-request payload field, not a call-protocol credential)

Context

ADR-045 extracted the dial into AlknetClient and moved CallCredentials from alknet-call to alknet-core so the dial would not depend on the call protocol. The three dial signatures were:

dial_quic(addr, server_name, alpn, credentials: &CallCredentials) -> Connection
dial_tcp_tls(host, addr, alpn, credentials: &CallCredentials) -> Connection
dial_iroh(node_id: iroh::NodeId, alpn, local_key: &Ed25519SecretKey) -> Connection

Two problems surfaced on review:

Problem 1: the iroh dial signature is asymmetric

dial_quic and dial_tcp_tls take &CallCredentials; dial_iroh takes a bare &Ed25519SecretKey + a separate node_id: iroh::NodeId. The asymmetry exists because iroh has its own TLS (it shares the key, not the rustls config — ADR-087 §3), so the iroh dial bypasses TlsClientConfig and reads the key directly. But the asymmetry forces the caller to know which dimension of the credential bundle each transport consumes, and it leaves no path for the iroh dial to receive the same inputs as the rustls dials — even though all three consume the same two things: a local identity (key/cert) and an expected remote identity (fingerprint).

Problem 2: CallCredentials couples the dial to the call protocol

CallCredentials carries three dimensions (ADR-022 §7):

1. tls_identity: Option<TlsIdentity> — the local node's key/cert
2. auth_token: Option<AuthToken> — a call-protocol-level bearer token
3. remote_identity: Option<RemoteIdentity> — the expected remote fingerprint

The dial uses only dimensions 1 and 3 (the transport-identity layer). Dimension 2 (auth_token) is a call-protocol concept: it correlates a token to an identity via IdentityProvider::resolve_from_token — a mechanism that exists for two hub-dependent cases where TLS-fingerprint identity is unavailable:

• Browsers — no raw-key support, no client cert the hub can fingerprint; the browser authenticates via a bearer token over HTTP/WebSocket, and the hub's IdentityProvider resolves it.
• alknet/register — a native worker that hasn't been enrolled dials in with no prior peer relationship; a registration token (or open registration) establishes identity, not a TLS fingerprint.

Both depend on a hub running IdentityProvider with token-to-identity mapping. A pure P2P connection (two nodes with raw-key identities) never needs auth_token — the TLS fingerprint IS the identity.

auth_token is not a transport credential. It is a per-request field on call.requested payloads (Dispatcher::resolve_identity reads payload.get("auth_token"); the from_call forwarding handler sets it via build_forwarded_payload). The dial never delivers it to the protocol take-over — spawn_dispatch(&self, connection: Connection) takes no credentials, and Connection (a Box<dyn BidiStreamSource>) carries no auth_token field. The auth_token in CallCredentials is unused by the dial and dropped after connect() in the current code.

By moving CallCredentials (with auth_token in it) to alknet-core for the dial's benefit, ADR-045 §5 would drag a call-protocol concept into the shared-types crate for the dial's benefit — when the dial doesn't use it. The dial should consume a transport-level credential bundle, not a call-protocol one.

The two identity models

Underneath the three transports, there are two identity-consumption models, both consuming the same two dimensions:

Model	Transports	Consumes	What the transport does
rustls config	QUIC (quinn), TCP+TLS (tokio-rustls)	local_identity → TlsClientConfig (client cert); remote_identity → verifier (FingerprintPinVerifier / WebPkiServerVerifier)	Builds rustls::ClientConfig, hands to transport connector
key-native	iroh, SSH (future — docs/research/references/ssh/russh/06-usage-patterns.md)	local_identity → Ed25519SecretKey → transport's key type (iroh::SecretKey, russh key); remote_identity → fingerprint → transport's verifier (NodeId match, known_hosts)	Reads the key directly; transport handles identity internally

The difference is how each model consumes the dimensions, not what they are. A unified credential bundle carrying just those two dimensions lets every dial extract what its transport's identity layer needs, without call-protocol coupling.

Decision

ConnectionCredentials — the dial's credential bundle

A new type in alknet-core, carrying the two transport-identity dimensions every dial consumes:

/// Transport-level credentials for an outbound dial. Consumed by
/// `AlknetClient`'s dial methods and (for the server side) by the
/// assembly layer when building transports. Carries only the dimensions
/// the transport's identity layer needs — the local identity (key/cert
/// presented to the transport) and the expected remote identity
/// (fingerprint, driving verifier selection per ADR-034).
///
/// This is NOT the call-protocol credential bundle. The call-protocol
/// `auth_token` (hub-correlated bearer for browsers / `alknet/register`)
/// is a per-request field on `call.requested` payloads, not a
/// transport credential. It stays in the call-protocol layer.
pub struct ConnectionCredentials {
    /// The local node's identity (RFC 7250 raw key or X.509), presented
    /// to the transport's identity layer. rustls dials → `TlsClientConfig`
    /// (client cert via `RawKeyClientCertResolver`); iroh/SSH dials →
    /// key directly (`iroh::SecretKey::from_bytes`, russh key).
    pub local_identity: Option<TlsIdentity>,

    /// Expected identity of the remote node. `Some(fingerprint)` → pin
    /// (known peer); `None` → CA verification for X.509 remotes or
    /// fail-closed for Ed25519 raw-key remotes (ADR-034 §2/§3). `None`
    /// is the public-X.509-endpoint state, not a missing field.
    pub remote_identity: Option<RemoteIdentity>,
}

RemoteIdentity moves with ConnectionCredentials to alknet-core (both are transport-level types; the dial and the server-side transport construction both consume them).

Unified dial signatures

All three dials take &ConnectionCredentials:

impl AlknetClient {
    #[cfg(feature = "quinn")]
    pub async fn dial_quic(
        &self,
        addr: SocketAddr,
        server_name: &str,
        alpn: &[u8],
        creds: &ConnectionCredentials,
    ) -> Result<Connection, ClientDialError>;

    #[cfg(feature = "tcp")]
    pub async fn dial_tcp_tls(
        &self,
        host: &str,
        addr: SocketAddr,
        alpn: &[u8],
        creds: &ConnectionCredentials,
    ) -> Result<Connection, ClientDialError>;

    #[cfg(feature = "iroh")]
    pub async fn dial_iroh(
        &self,
        alpn: &[u8],
        creds: &ConnectionCredentials,
    ) -> Result<Connection, ClientDialError>;
}

The node_id: iroh::NodeId parameter on dial_iroh is removed — it is derived from creds.remote_identity.fingerprint (ed25519:<hex> → NodeId::from_bytes), the same way the rustls dials derive their verifier from remote_identity. The consistency is now in both the rule (ADR-034) and the type.

Each dial extracts what its transport's identity layer needs:

• rustls dials (dial_quic, dial_tcp_tls): creds.local_identity → TlsClientConfig::new (client cert); creds.remote_identity → ClientVerifierContext (verifier selection).
• iroh dial (dial_iroh): creds.local_identity → Ed25519SecretKey → iroh::SecretKey::from_bytes; creds.remote_identity.fingerprint → NodeId (verifier).

CallCredentials is removed (amendment 2026-07-17)

This section supersedes the original "CallCredentials stays in alknet-call" decision. The original rationale rested on a code path that does not exist. The trace below is the correction.

CallCredentials is removed, not retained. Once the transport dimensions (local_identity, remote_identity) move to ConnectionCredentials in alknet-core, CallCredentials would reduce to a one-field struct { auth_token: Option<AuthToken> } — and that field has no reader.

The trace (why the original rationale was wrong). The original section claimed the call protocol uses CallCredentials.auth_token because "the from_call forwarding handler populates auth_token on outgoing call.requested payloads." That chain does not connect:

• from_call's signature is from_call(connection: &CallConnection, config: FromCallConfig) — no CallCredentials parameter. FromCallConfig has no credential field.
• The auth_token the from_call forwarding handlers can set on payloads is sourced from OpSummary.credentials_auth_token, an Option<String> that is hardcoded to None at every construction site (from_call.rs:185, 748, 757). It is not read from CallCredentials.auth_token, and it is a different type (Option<String> vs Option<AuthToken>). The two were never connected, even in intent.
• The consuming side — Dispatcher::resolve_identity (dispatch.rs:119) — reads payload.get("auth_token").as_str() from the per-request call payload. It does not read CallCredentials.

Where auth_token actually originates. It is a per-request payload field, populated by two real paths, neither of which touches CallCredentials:

• Browsers over WebSocket — the browser sends auth_token directly in the call.requested JSON payload (websocket/mod.rs:202–206); the WS layer (upgrade.rs:178–181) passes envelope.payload straight to dispatch_requested. The browser is the originator; the WS layer is a transparent passthrough.
• HTTP gateway (bearer) — gateway/dispatch.rs resolves the Authorization: Bearer header to an Identity at the HTTP boundary (resolve_bearer, line 58) and passes the Identity into build_root_context. The call protocol sees the resolved Identity, not the token. auth_token does not enter the call payload on this path.

So CallCredentials.auth_token is a write-only field (it has a setter, with_auth_token, and zero readers). connect() — CallCredentials's only consumer — is removed in Phase 5 of the migration. With connect gone, nothing constructs or reads CallCredentials except the tests.

auth_token's two real use cases (confirming no call-protocol credential bundle is needed):

1. HTTP auth — the inbound case. The HTTP gateway resolves the bearer token to an Identity via IdentityProvider::resolve_from_token at the HTTP boundary. The call protocol receives the Identity, not the token.
2. Registration (alknet/register native ALPN, /register HTTP endpoint) — a client not yet associated with a hub presents a one-time registration token; the hub creates a PeerEntry (a new identity based on the fingerprint). Outbound, the vault manages the token on the client side; inbound, the hub's registration handler consumes it. Neither path involves CallCredentials.

A hub does not "forward with its own token" in the way the original rationale assumed. Where the hub authenticates to an outside service (another hub's HTTP interface, an external API), the vault manages that outbound token — it is not a call-protocol credential. The from_call credentials_auth_token path was a future hatch for a use case that dissolved once IdentityProvider::resolve_from_token solved the inbound identity problem: the hub authenticates as itself (its Identity is on the connection), and the spoke authorizes the hub as the direct caller. No per-forwarded-call token is needed.

from_call's credentials_auth_token is removed too. It is the same family of dead code — an always-None field of a different type than CallCredentials.auth_token, never connected to anything. The credentials_auth_token field on OpSummary, the credentials_auth_token parameters on make_forwarding_handler / make_streaming_forwarding_handler, and the auth_token parameter on build_forwarded_payload are removed. The forwarding handlers stop emitting auth_token in payloads (which they never did in practice — the source was always None). The two from_call tests asserting the Some path (build_forwarded_payload_sets_auth_token_when_provided, streaming_forwarding_handler_sets_auth_token_when_provided) are removed — they test a code path never exercised in production. If a future hub needs its own token on forwarded payloads, that is a fresh, end-to-end-wired feature, not a vestigial path.

What does NOT move to alknet-core: ConnectionCredentials and RemoteIdentity move (the original decision). CallCredentials does not move — it is removed. ADR-045 §5's move of CallCredentials to core is superseded twice over: first by the original ADR-012 (move ConnectionCredentials instead), and now by this amendment (remove CallCredentials entirely). There is no call-protocol credential bundle; auth_token is a per-request payload field, full stop.

TlsClientConfig::new input framing

TlsClientConfig::new (ADR-087) takes a ClientVerifierContext derived from the credential bundle's remote_identity. The rustls dials extract creds.local_identity and creds.remote_identity from ConnectionCredentials and build ClientVerifierContext from the latter — the same extraction ADR-087 described, just from ConnectionCredentials instead of CallCredentials. The auth_token dimension is simply not present in ConnectionCredentials, so the "stripped at the TLS boundary" framing (ADR-045's claim that the token "travels with the Connection") is no longer needed — the token was never in the dial's credential bundle to strip.

Future dial_ssh validates the shape

An SSH dial (docs/research/references/ssh/russh/06-usage-patterns.md) consumes the same two dimensions:

• check_server_key(&mut self, key: &ssh_key::PublicKey) — the verifier (fingerprint pin against known_hosts = remote_identity)
• authenticate_publickey("user", PrivateKeyWithHashAlg::new(...)) — local identity (the Ed25519 key = local_identity)
• channel_open_session() → Connection::from_bidi (ADR-007)

dial_ssh(addr, alpn, creds: &ConnectionCredentials) fits the same signature. The SSH host-key verification is fingerprint-pinning (known_hosts), which is what remote_identity carries. The local SSH key is the same Ed25519 key iroh and raw-key quinn use. The pattern is general — ConnectionCredentials covers it without call-protocol coupling. SSH itself is unspecced (not yet specced — comes after channels, tunnels, TTY rework), but the russh usage patterns confirm the credential dimensions.

Consequences

Positive:

• The dial is fully decoupled from the call protocol. ConnectionCredentials carries only transport-identity dimensions; alknet-client has no call-protocol coupling in its credential type. There is no call-protocol credential bundle — auth_token is a per-request payload field, not a credential.
• All three dial signatures are unified. A caller no longer needs to know that iroh takes a bare key while quinn/tcp take a credential bundle — all take &ConnectionCredentials. The node_id parameter on dial_iroh is derived from remote_identity, the same extraction pattern the rustls dials use for the verifier.
• The auth_token spec inaccuracy is fixed. ADR-045 claimed the auth_token "travels with the Connection into the protocol take-over, where it is sent as the first call-protocol frame." This was aspirational — Connection carries no auth_token, and spawn_dispatch takes no credentials. With CallCredentials removed, the claim is not merely unneeded; the field it described was never read. auth_token is a per-request field on call.requested payloads, set by browsers (in the WS payload) or resolved by the HTTP gateway at its boundary (bearer → Identity).
• dial_ssh fits the same shape when it arrives. The credential dimensions SSH needs (local key + expected host key) are exactly what ConnectionCredentials carries. No future ADR needed for the SSH dial signature.
• A dead credential type and a dead forwarding-token path are removed (amendment 2026-07-17). CallCredentials is removed (its auth_token field had no reader). from_call's credentials_auth_token is removed (always None, different type than CallCredentials.auth_token, never connected). Both were future hatches from the era before IdentityProvider::resolve_from_token solved the inbound identity problem; the hatches dissolved once it did. See the amended §"CallCredentials is removed" above for the trace.

Negative:

• CallCredentials is removed (a public type). Callers that constructed CallCredentials (the integration test; any future assembly-layer code) switch to ConnectionCredentials for the dial. auth_token, where needed, is a per-request payload field (browsers send it in the WS payload; the HTTP gateway resolves bearer → Identity at its boundary). This is expected — connect() was CallCredentials's only consumer and is removed in the same migration. There are no external consumers (develop branch is a total rewrite).
• The assembly layer builds one credential bundle, not two. Where ADR-045 had the assembly layer build one CallCredentials (and the original ADR-012 reframed it as two — ConnectionCredentials for the dial + a per-request auth_token), the assembly layer now builds ConnectionCredentials for the dial only. auth_token is not a credential the assembly layer constructs; it is a per-request payload field the browser (or the HTTP gateway's bearer resolution) supplies. This is fewer types at the assembly site, not more.
• ADR-045 §5's "CallCredentials moves to core" is superseded twice. The original ADR-012 reframed the move target as ConnectionCredentials (not CallCredentials); this amendment removes CallCredentials entirely. What moves to alknet-core: ConnectionCredentials + RemoteIdentity. What does not move: CallCredentials (removed, not relocated). This affects the extraction plan's Phase 0 (additive credentials move) and Phase 5 (the call prune now removes CallCredentials and the from_call dead path, not just connect and the TLS helpers).

Door type

One-way. The dial signatures (dial_quic / dial_tcp_tls / dial_iroh all taking &ConnectionCredentials) are the public API surface of alknet-client. The credential-type decoupling (ConnectionCredentials in core, no call-protocol credential bundle) determines the dep graph (alknet-client depends on alknet-core for ConnectionCredentials, not on alknet-call). Reversing would mean re-coupling the dial to the call protocol's credential type and re-asymmetrizing the iroh dial. The CallCredentials removal (amendment 2026-07-17) is the same door — removing a public type whose only consumer (connect) is removed in the same migration. The crate is greenfield (Phase 3 of the extraction plan), so the door is still open now — this ADR records the decisions before implementation.

References

• ADR-045 — AlknetClient native dial seam (§3 dial signatures amended — all take &ConnectionCredentials; §5 move amended — ConnectionCredentials/RemoteIdentity move to core, not CallCredentials; §5 further amended 2026-07-17 — CallCredentials removed, not retained in alknet-call)
• ADR-087 — TlsClientConfig not blocked on dial (input framing amended — ClientVerifierContext derived from ConnectionCredentials.remote_identity, not CallCredentials)
• ADR-034 — client-side verifier selection (the rule ConnectionCredentials.remote_identity drives — unchanged)
• ADR-022 §7 — the three credential dimensions (the historical source of CallCredentials's three fields; the transport dimensions moved to ConnectionCredentials, the auth_token dimension is a per-request payload field, and CallCredentials itself is removed)
• crates/alknet-call/src/protocol/dispatch.rs — Dispatcher::resolve_identity reads payload.get("auth_token") (per-request, not connection-level — the consumer of auth_token)
• crates/alknet-call/src/client/from_call.rs — the credentials_auth_token field on OpSummary and the auth_token parameter on build_forwarded_payload (the removed dead path; always None, different type than CallCredentials.auth_token, never connected)
• crates/alknet-http/src/gateway/dispatch.rs — resolve_bearer (the HTTP path: bearer → Identity at the boundary; the call layer sees the identity, not the token)
• crates/alknet-http/src/websocket/mod.rs — the WS path: auth_token in the browser's call payload, passed through to dispatch_requested unchanged
• docs/research/references/ssh/russh/06-usage-patterns.md — the SSH client usage patterns (check_server_key + authenticate_publickey) validating the ConnectionCredentials shape for a future dial_ssh