alkcall/docs/reviews/consumer-findings-ledger.md

Consumer findings ledger — alkhttp consuming alkcall

Findings from writing the first real consumer (alkhttp) against alkcall. alkcall is deliberately minimal; expect missing features and edge-case bugs to surface here first. Extract items into alkcall tasks/reviews as the project sees fit.

Format: date | found-in (alkhttp context) | severity | status.

---

Open

(none)

---

Resolved

CF-005 — connect-side serving path (from_connection_with_serving) has no caller-identity capture; scope-gated ops are satisfiable only via payload auth_token (2026-09-07) — RESOLVED 2026-09-07

• Found in: alktunnels reverse-flow POC (alktunnels-reverse-poc, summary at /workspace/@alkdev/alktunnels/docs/research/reverse-poc-summary.md §W1; verified against alkcall 0.6.0). The worker is the connect side AND the serving side (ADR-022 §2 both-sides): it serves its tunnel open op to the hub over the connection it dialed. The open op is scope-gated (AccessControl.required_scopes), but the identity the ACL sees comes from Dispatcher::dispatch_start → resolve_identity(connection_identity, payload), and:
  • connection.identity() is None — from_connection_with_serving builds channel 0 internally via Connection::from_source (client.rs channel-0 block) and never sets an identity; there is no capture point for the transport-authenticated peer (mTLS/QUIC identity) on this path.
  • The only caller-identity path is the payload auth_token → ServingConfig.identity_provider (resolve_from_token).
  • Corollary: the AuthContext closed over by register_openable*'s wrapper (what the establisher and pump handler receive) is the connection-establishment-time context, not the per-call opener's identity — on the accept side the install hook receives the transport AuthContext and can channel0_conn.set_identity, but from_connection_with_serving has no equivalent seam.
• Impact: a connect-side serving op with a scope gate cannot authenticate the legitimate peer by transport identity — the POC had to attach auth_token payloads from the hub side (CallConnection::call_with_payload). Acceptable for hub-forwarding topologies (from_call's ADR-017 §7 token path), but a gap for direct connect-side serving where the transport already authenticated the peer.
• Verification: confirmed statically (the chain Connection::from_source → empty OnceLock identity → dispatch_start → resolve_identity(None, payload) → AccessControl::check(None) fails closed) and empirically (e2e duplex tests reproducing the POC shape; the tokenless scope-gated call was denied FORBIDDEN: authentication required while the token path succeeded).
• Fix (both remediations (a) + (b), 2026-09-07): the caller identity for the connect-side serving dispatch resolves in precedence order — (1) payload auth_token → ServingConfig.identity_provider (unchanged; the hub-forwarding / browser-token fallback, ADR-017 §7); (2) new ServingConfig.identity: Option<Identity> — the explicit override (remediation (a)); (3) the transport connection's identity, propagated automatically: from_connection_with_serving copies connection.identity() to the channel-0 connection via set_identity before the serving loop starts (remediation (b) — the native-client mTLS/QUIC key-based path; mirrors the accept side's install-hook set_identity). Also added the public core::auth::NoopIdentityProvider (resolves nothing) — the identity-less posture and the ServingConfig::default() identity provider; three private test copies of it existed.
  • Behavior change (semver-relevant): ServingConfig gained an identity field — struct literals must add identity: None (0.x; changelog note). The call half is unaffected (spawn_dispatch takes the consumer-owned Connection, so the consumer can set_identity before wrapping).
  • The corollary (register_openable's closed-over establishment-time AuthContext vs the per-call opener identity) was resolved in the same batch (2026-09-07, CF-006 below).
• Status: resolved — 2026-09-07 (regression gates: cf005_* tests in src/channels/client.rs).

CF-006 — open-op establisher/pump handler receive the install-time AuthContext, never the per-call opener's identity (CF-005 corollary) (2026-09-07) — RESOLVED 2026-09-07

• Found in: the CF-005 verification pass (same alktunnels reverse-flow POC W1 material; the ledger's CF-005 entry named it as a "design follow-up, tracked separately"). run_open_wrapper (src/channels/operations.rs) closed over the install_channel_zero-time AuthContext and passed auth.clone() verbatim to both the establisher (ADR-049 §1) and the pump handler (OpenHandler's 4th parameter). The per-call opener's identity — the same identity the ACL gate and the per-identity cap check saw — reached neither hook. On a per-connection registry (ADR-047 §4) install-time identity IS the caller's, so the gap was invisible there; it shows on hub-forwarded opens (the establisher saw the hub, not the end client) and on the connect-side serving path (token- or ServingConfig.identity-resolved callers). alktty review 002 R3 independently recorded the same seam (closed per-connection by design, with the "registry must stay per-connection" constraint).
• Impact: an establisher doing per-principal authorization or ownership checks on the backend could not see the actual opener; the pump handler tagging sessions by principal saw the hub.
• Fix (2026-09-07): run_open_wrapper derives a per-call AuthContext — the opener's dispatch-resolved identity overlaid onto the install-time context — and passes it to both the establisher and the pump handler. When the call has no resolved identity, the install-time identity is kept (anonymous-keep; no synthetic-anonymous rewrite of a real install-time identity). Transport-truthful fields (alpn, remote_addr, tls_client_fingerprint) are never rewritten. Signatures are unchanged (OpenEstablisher, OpenHandler still take AuthContext) — behavior-only, additive; downstream code compiles unchanged. Regression gates: open_wrapper_overlays_per_call_identity_on_install_time_auth + open_wrapper_keeps_install_time_identity_when_call_identityless in src/channels/operations.rs.
• Also in this batch: ChannelPlan's type doc now spells out the Send + Sync payload constraint (alktunnels POC F-1 re-derived it by compiler error — a doc line prevents the next consumer repeating that).
• Status: resolved — 2026-09-07.

CF-007 — ADR-016's protocol-code list is stale: omits ALREADY_EXISTS and CONNECTION_CLOSED (2026-09-07) — RESOLVED 2026-09-07

• Found in: alkhttp review 006, Part C (alkhttp/docs/reviews/006-alkcall-0.3.0-consequence-review.md L207–233, L319–324 — "upstream doc drift … flagged for the next alkcall doc pass"). ADR-016 said "six codes" and its table listed only the original six, while the wire vocabulary had grown: ALREADY_EXISTS (ADR-022 collision sub-amendment, 0.3.0) and CONNECTION_CLOSED (CF-001, 0.4.x, the retryable provably-undelivered-call code). Downstream consumers already handle both; the authoritative ADR was the thing that was wrong.
• Fix (2026-09-07): ADR-016 amended — Status notes the 2026-09-07 extension to eight; the Context paragraph and the §3 table carry both codes with their semantics (ALREADY_EXISTS non-retryable, registration state; CONNECTION_CLOSED retryable — the only protocol code a caller may auto-retry), a §2a subsection documents the undelivered-vs-ambiguous write-failure distinction, the from_openapi collision rule lists all eight, and the cross-references cite the two amendments. Doc-only; the wire surface is unchanged.
• Status: resolved — 2026-09-07.

---

CF-004 — services_schema_handler discloses Internal/ACL-restricted op specs — no visibility or AccessControl check (2026-08-30) — RESOLVED 2026-08-31

• Found in: alkhttp Review 002, finding PRJ-16 (alkhttp/docs/reviews/002-post-remediation-review.md, Part F', verified against tree 91483a7 + alkcall source). Filed to this ledger 2026-08-30. src/registry/discovery.rs:327-343 (services_schema_handler) — the handler did a bare registry.registration(&name) and returned spec_to_json(&reg.spec) verbatim, with no Visibility check and no AccessControl::check(peer_identity).
• Fix: the handler now applies the same two gates as OperationRegistry::invoke — the Internal-visibility rejection (!ctx.internal → spec-404) and AccessControl::check with the same identity resolution invoke() uses (handler_identity when internal, identity otherwise). Restricted ops return NOT_FOUND (spec-404) rather than FORBIDDEN — no information leaks about the restricted surface's existence or shape. The gate is in the handler itself, so every transport (wire /call, HTTP routes, MCP tools) is covered.
• Status: resolved — 2026-08-30.

CF-003 — publish_schema compile failure is fail-open on the wire dispatch path (2026-08-30) — RESOLVED 2026-08-30

• Found in: alkhttp Review 001 post-remediation task review-001-publish-schema-validation-robust (the GW-01/#1 follow-up work). While fixing alkhttp's HTTP-side instance of the pattern, the identical instance was verified on the wire dispatch path: src/protocol/dispatch.rs:352-366 (Dispatcher::dispatch, OperationType::Pub arm) — when a Pub op's publish_schema failed to compile, the pump logged a warn and proceeded with validator: None (silent unvalidated ingest, plus per-request recompile cost).
• Fix: fail-closed at the source — publish_schema is now compiled at registration time in both insertion points (OperationRegistry::register and OperationRegistryBuilder::store); an un-compilable schema is a registration error, so an unvalidated-ingest path can never be constructed. The compiled validator is cached per-op (OperationRegistry::publish_validator) and the dispatch path consumes the cache — the per-request compile is gone. The from_call import path inherits the guarantee (imports register through the same choke point); forwarded-chunk validation on the producer side is the remote peer's dispatch path and now inherits the same fail-closed property.
• Behavior change (semver-relevant): register/builder methods return Err for an un-compilable publish_schema (previously: accepted). Code that registered garbage schemas will now get a registration error instead of a silently-unvalidated op.
• Status: resolved — 2026-08-30.

CF-002 — demux TooLarge skip allocates the full peer-declared length up front (up to ~4 GiB from an 8-byte header) (2026-08-30) — RESOLVED 2026-08-30

• Found in: alkhttp Review 001, finding WS-12 (cross-crate; docs/reviews/001-initial-implementation-review.md, Part B, verified against tree 4a825d3). Filed to this ledger 2026-08-30. src/channels/adapter.rs:144 (run_demux_loop_for_client) — the ChunkError::TooLarge arm allocated let mut discard = vec![0u8; length as usize]; before reading: the buffer was sized from the peer's untrusted 8-byte header (u32 length, up to ~4 GiB).
• Fix: stream-skip with a fixed 64 KiB buffer + read_exact loop consuming length bytes — no allocation sized from peer input. Plus a cumulative skipped-bytes budget (256 MiB) that tears down the connection when a peer loops TooLarge headers to burn bandwidth/CPU. The budget resets on each valid chunk, so legitimate isolated oversized chunks (the resync path, covered by the existing test) are unaffected. The existing demux_resyncs_after_oversized_chunk test passes unchanged.
• Status: resolved — 2026-08-30.

CF-001 — call_single_stream write-failure maps to non-retryable INTERNAL (2026-08-29) — RESOLVED 2026-08-30

• Found in: alkhttp from_wss drop-monitor race tests (WS-02/CON-02, review-001-ws-eof-signal). When the transport mux died mid-call, the write path failed fast and the write-failure mapping produced a non-retryable INTERNAL: failed to write request frame — even though the call never reached the producer and a reconnect/retry would be safe.
• Fix: new retryable CallError::connection_closed constructor (CONNECTION_CLOSED code, retryable: true), applied only to write failures where the call is provably undelivered: call.requested frame write failures on all consumer paths (call/subscribe/publish, single-stream and stream-per-request; the publish pump tags its write stages so only the request-frame stage is retryable). Mid-publish and completed-frame write failures stay INTERNAL (delivery ambiguous — retry unsafe), and the producer-side fail_all(...) on connection close stays INTERNAL. The new code string is additive to the wire error vocabulary; CONNECTION_CLOSED is new — consumers should treat unknown codes per their existing policy (the retryable flag is the machine-readable signal).
• Status: resolved — 2026-08-30. alkhttp follow-up: the review-001-ws-eof-signal race test can now tighten back to retryable-only asserts.