Files

T

glm-5.3-flash bd7d1ad8ec docs: Phase 1 architecture spec — ADRs 001..006, spec docs, OQ promotion

The Phase 0 OQ ledger (OQ-TN-01..10) promoted into
docs/architecture/open-questions.md (now OQ-TN-01..14, with four
new Phase 1 residues). Six ADRs and four spec docs, all Draft, all
decision-shaped per the SDD process (ADRs carry the WHY; specs carry
the WHAT and reference by number):

ADRs:
- 001 open-params-layout: params = {resource, substrate} — the
  producer's stable name, not an address; wire-stable from the first
  consumer; unknown substrates fail loudly at schema time
- 002 alpn-strategy: single alk/tunnel ALPN (option A); substrate in
  params selects the framing; prior art (SSH/SOCKS5/udpgw) gives no
  reason for the split
- 003 codec-and-udp-framing: raw pass-through (stream) / mandatory
  [len: u16 BE] (UDP) — F-2 mandate recorded (the codec is mandatory
  for correctness, not cosmetics); len=0 = legal empty datagram;
  OQ-TN-13 resolved fail-loud (truncation)
- 004 no-backend-trait: halves functions at the assembly layer;
  listen is an establisher shape; hub re-produce deferred(OQ-TN-12);
  trait re-evaluated at the alknet ADR-078 convergence threshold
- 005 consumer-session-owns-teardown: TunnelSession with
  open/adopt/stream_halves/take_halves/pump_against/close/join/Drop —
  the W3 adopter gap closes structurally; Drop is the best-effort
  fallback
- 006 access-control-posture: the open gate is the boundary;
  TUNNEL_OPEN_SCOPE = tunnel:open (stable once published); op-level
  ACL; ownership seam; no allowlists in v1; identity = 0.7.0's
  precedence chain

Spec docs:
- overview.md: purpose, resource model, deps (alkcall 0.7.0,
  wasm-clean default, local feature), module map
- wire.md: the open op (params/reply/typed errors), the data plane
  by substrate, sentinels + half-close, byte diagrams
- producer.md: spec, establisher (dial + listen shapes), pump
  handler (pump_bidi inline, R-02), registration API, ACL posture
- consumer.md: TunnelSession (forward open + reverse adopt
  construction), data plane, teardown API (close/join/Drop incl.
  pump-less join semantics)
- bast.md: the BAST doc for the UDP codec (convention 12's trigger
  fired — the framing IS binary beyond pass-through)
- open-questions.md: OQ-TN-01..14; 01..10 promoted (faithful to the
  phase-0 ledger's final states), 11 partially resolved (collision
  domain = per-producer registry per ADR-001; lifecycle open),
  12 deferred(scope), 13 resolved fail-loud (ADR-003), 14 open

Verified by an architecture-reviewer pass (2 criticals, 6 majors,
10 minors — all fixed: ADR-001/003-vs-OQ decision-state contradictions
resolved; the Layer-2 mislabel corrected to the ADR-047 §4 per-session
fork; alktty/alknet ADR misattributions fixed; codec placement pinned
to the establisher (pump stays substrate-agnostic); reverse-path
construction named (TunnelSession::adopt + pump_against); security
posture promoted to ADR-006; BAST doc written; F-2 rationale deduped;
README tables completed; channel_id > 0; MTU wording fixed; ADR-047 §5
attributions corrected; impacts lines added to unresolved OQs; review/
ledger pointer paths added to README references).

Verification: doc set internal cross-refs all resolve; cargo test,
fmt --check, doc --no-deps clean

2026-09-07 18:36:44 +00:00

5.1 KiB

Raw Blame History

ADR-006: Access-Control Posture — the Open Gate Is the Security Boundary

Status

Accepted (2026-09-07; records the OQ-TN-08 resolution as a decision — the posture was resolved in Phase 0 but the consumer-visible constants had no ADR backing)

Context

Tunnels reach local networks: opening a tunnel channel instructs the producer to dial (or accept for) a target — potentially anything the producer's host can reach. The open gate is therefore the security boundary of this crate, in the same sense that SSH's AllowTcpForwarding/PermitOpen govern direct-tcpip opens. The question (OQ-TN-08, Phase 0) was how much of that boundary lives in this crate vs alkcall's op-level ACL vs the assembly layer.

Phase 0 resolved the conceptual tangle (2026-09-05, the OQ-TN-08 resolution): at protocol-crate level, a produced resource belongs to the far side of the connection — the protocol works under that assumption, so the ACL story is exactly alkcall's existing op-level ACL. No new policy layer. The hub/overlay mechanism (workers connecting in, the hub re-exposing resources per ITS policy) is a downstream, assembly-layer concern (OQ-TN-12's scope).

What was left implicit — and needs pinning, because it is consumer-visible and stable-once-published:

The scope constant governing tunnel opens (tunnel:open) is ACL-surface: identities will be GRANTED this scope by name once consumers exist (the same one-way character as ALPN strings, which ADR-002 treats as wire-stable).
Whether v1 carries target allowlists / tunnel-specific ownership machinery.

Decision

The open gate is the boundary, and it is alkcall's ACL. The open op's AccessControl rides ChannelCore::register_openable — the registry runs the ACL before the establisher. The base gate is the scope constant TUNNEL_OPEN_SCOPE = "tunnel:open" (required scope, exact string — stable once published; consumers will request grants by it). An identity without the scope is FORBIDDEN before any establisher code runs.
The scope string is wire/ACL-stable from the first consumer: renaming is a breaking change to every deployed grant; new gates are additional scopes on new ops (additive), never a rename.
No target allowlists and no tunnel-specific policy machinery in v1. The resource is owned by the far side (the Phase 0 resolution); a producer that wants finer granularity wires OwnershipProvider checks into ITS establisher — the protocol provides the seam (the establisher sees the per-call opener identity, alkcall 0.7.0 CF-006), not the policy. This mirrors alktty's posture (TTY_OPEN_SCOPE + op-level ACL, no tty-specific allowlist).
The optional ownership seam: the establisher MAY consult OwnershipProvider.owns(id_ref, kind, &id, "tunnel") (the 4-arg shape; alknet ADR-050's model) for resource-scoped checks. v1 does not require it.
Discovery is the ACL-filtered ops listing (openable channels are operations, alkcall ADR-047): a consumer learns available tunnel resources through the existing bidirectional ops listing, OperationSpec.description round-trips through discovery (the human-readable hint). The live resource-enumeration half (alkcall OQ-40) stays deferred upstream.
Identity resolution is alkcall 0.7.0's precedence chain (CF-005): payload auth_token > ServingConfig.identity > transport identity; the establisher/pump handler receive the per-call opener identity (CF-006). Identity-less dispatch fails closed (FORBIDDEN).
-D/dynamic targets need no separate policy hook: a socks5 tunnel is an ordinary tunnel to a socks5 resource; whatever ACL governs that resource governs everything reachable through it, plus whatever policy the socks5 implementation applies downstream (target selection is in the socks5 protocol, not params).

Consequences

One security knob per producer deployment (the op-level ACL + scope grants) instead of a tunnel-specific policy language — the accepted simplicity; per-resource granularity is an establisher customization (the seam), not a v1 surface.
The scope constant is a compatibility commitment: treat tunnel:open like the ALPN string. Changing it after consumers request grants is a breaking ACL change.
No allowlist concept — a wildcard-egress producer (0.0.0.0/0-style egress) is expressed by registering a resource whose backing is that egress; gating it is the assembly layer's ownership check at the seam. The protocol stays out of the business.
Tunnels reach local networks — producers MUST treat the gate as the security boundary; the spec docs state this posture (producer.md).

References

OQ-TN-08 (promoted, resolved by this ADR)
alkcall ADR-047 (open ops + ACL wiring), ADR-017 §7 (the auth_token path), ledger CF-005/CF-006 (identity precedence, per-call opener); alknet ADR-024/ADR-050 (registry layering, ownership — the alkcall ports ADR-019/ADR-011)
alktty's TTY_OPEN_SCOPE posture (the sibling precedent)
AGENTS.md convention 13 (access control)

5.1 KiB Raw Blame History