alktunnels/docs/architecture/decisions/006-access-control-posture.md

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); amended 2026-09-16 (scope separation for the direct/forwarded ops + the hub re-produce policy sentence, see Amendment 1)

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, and 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

1. 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, and consumers will request grants by it). An identity without the scope is FORBIDDEN before any establisher code runs.
2. 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.
3. 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).
4. 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.
5. 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.
6. 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).
7. -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, which is 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, so 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)

Amendment 1 (per-flavor scopes + hub re-produce policy, 2026-09-16)

The posture stands; the scope space grows with the ops (ADR-007, ADR-008):

• TUNNEL_DIRECT_SCOPE = "tunnel:direct" gates channels/tunnel/direct for dynamic-target egress. Never implied by tunnel:open: "dial postgres-primary" and "dial anything from my network" are different capabilities, and the separation is structural (scopes attach to op specs, not params). A deployment granting both grants both explicitly.
• TUNNEL_FORWARDED_SCOPE = "tunnel:forwarded" gates channels/tunnel/forwarded on the opener side; it is the grant for RECEIVING producer-initiated forwarded connections (ingress). Ingress and egress are different grants (the alksocks POC #5 socks5:bind gate proved the distinction matters in practice).
• Hub re-produce policy sentence (the security model): a hub that re-produces the direct op applies ITS OWN target policy at the re-produce hop; the hub's ACL, not the original opener's, governs the final dial. The hub is the network boundary; the original opener's grant gets it to the hub, the hub's own grant decides what it will dial on the far side. Correct-by-default; pinned here because it is the boundary-allocation rule for every composed consumer (alknodes included).
• Scope strings are ACL-stable once published (§2 unchanged): renames are breaking; new gates are new scopes on new ops.