Files

glm-5.2 400c60e7f4 docs(architecture): security constraints from security review

Address security review findings by adding explicit constraints to specs
and implementation specialist role:

Architectural constraints (spec updates):
- metadata does not propagate through OperationEnv::invoke() — fresh
  HashMap for nested calls, closes the back-door leak channel where a
  handler that puts a secret in metadata would leak it to children and
  across from_call to remote nodes (ADR-014)
- Config reload must be authenticated/local-only — malicious reload =
  root-equivalent privilege grant (config.md)
- from_call trust is transitive — scoped env bounds reachability, not
  what the remote op does (operation-registry.md)
- Token entropy ≥128 bits — prefix is lookup aid not secret, offline
  hash verification requires high-entropy tokens (auth.md)

Implementation constraints (auth.md security constraints section + role spec):
- OsRng for cryptographic nonces (AES-GCM IV reuse is catastrophic)
- CachedKey derives Zeroize/ZeroizeOnDrop (no secrets in freed heap)
- No unwrap()/expect() outside tests (poisoned lock recovery, not crash)
- Implementation specialist role spec updated with all four constraints

2026-06-19 06:55:54 +00:00

call-protocol.md

docs(architecture): resolve OQ-11 and OQ-19 — all open questions resolved

2026-06-19 06:05:04 +00:00

operation-registry.md

docs(architecture): security constraints from security review

2026-06-19 06:55:54 +00:00

README.md

docs(architecture): resolve OQ-11 and OQ-19 — all open questions resolved

2026-06-19 06:05:04 +00:00

README.md

status, last_updated

status	last_updated
draft	2026-06-21

alknet-call

Structured RPC over QUIC: operations, request/response, streaming subscriptions, and service discovery. Implements ProtocolHandler on ALPN alknet/call.

Documents

Document	Status	Description
call-protocol.md	draft	CallAdapter, EventEnvelope framing, stream model, PendingRequestMap, bidirectional calls
operation-registry.md	draft	OperationSpec, Handler, OperationRegistry, AccessControl, service discovery, irpc integration

Applicable ADRs

ADR	Title	Relevance
001	ALPN-Based Protocol Dispatch	CallAdapter registers on ALPN `alknet/call`
002	ProtocolHandler Trait	CallAdapter implements ProtocolHandler
003	Crate Decomposition	alknet-call depends on alknet-core and irpc
004	Auth as Shared Core	AuthContext passed to call handlers
005	irpc as Call Protocol Foundation	irpc provides framing and service dispatch
006	ALPN String Convention	`alknet/call` ALPN, one ALPN per connection
007	BiStream Type Definition	CallAdapter receives Connection, not BiStream
008	Vault Integration Point	Vault accessed at assembly layer, not on the wire
010	ALPN Router and Endpoint	Static handler registration
012	Call Protocol Stream Model	Bidirectional streams, EventEnvelope, ID-based correlation
014	Secret Material Flow and Capability Injection	Call protocol carries no secret material; capabilities injected at assembly layer
015	Privilege Model and Authority Context	`internal` = authority switch not ACL skip; External/Internal visibility; handler identity + scoped env
016	Abort Cascade for Nested Calls	`call.aborted` cascades to descendants; default `abort-dependents`, `continue-running` opt-in
017	Call Protocol Client and Adapter Contract	`CallClient` opens connections; `from_call` imports remote ops; connection direction independent of call direction

Relevant Open Questions

OQ	Title	Status	Relevance
OQ-07	Call protocol scope within a connection	resolved (ADR-012)	Stream model, multiplexing, scope
OQ-13	Operation path format and routing scope	resolved	`/{service}/{op}` is the correct design; remote dispatch is a separate layer
OQ-14	Batch operation semantics	resolved	Correlated `call.requested` events is the correct protocol design
OQ-16	Safe vault operations for call protocol exposure	resolved (ADR-014)	None exposed for now
OQ-19	Session-scoped operation registries	resolved	Agent-written operations overlaid on global registry via `OperationEnv` trait layering. Protocol doesn't need changes; `OperationEnv` must remain a trait

Key Design Principles

One connection, full access: An alknet/call connection gives access to the entire operation registry — calls, subscriptions, batch, schema.
Protocol is symmetric: Both sides can initiate calls. The server calling a client uses the same EventEnvelope format and correlation.
Stream-agnostic correlation: PendingRequestMap correlates by request ID, not by stream. The protocol works with any stream arrangement.
Operation registry is static: Operations are registered at startup by the CLI binary. The registry supports JSON Schema discovery.
irpc is one dispatch backend: Local operations dispatch directly. irpc service calls (in-process, type-safe) are internal. The call protocol is the external interface.
Local dispatch only: The operation registry dispatches to local handlers. Remote dispatch (federation, head/worker routing) would be a separate mechanism at a different layer, not a modification to alknet-call's path format.
No secret material on the wire: The call protocol carries no private keys, API keys, mnemonics, or decrypted credentials. Handlers receive outbound credentials through OperationContext.capabilities, injected at the assembly layer. See ADR-014.
Abort cascades to descendants: call.aborted for a parent request cascades to all non-terminal descendants. Default abort-dependents; continue-running opt-in. See ADR-016.
Internal calls switch authority context, not skip ACL: The internal flag marks composition-originated calls. ACL runs against the handler's identity, not the caller's and not as a blanket skip. Operations have External/Internal visibility. Scoped composition env bounds reachability. See ADR-015.