0 Fork 0

Files

T

glm-5.3-flash 0d6b23b7cf docs: spec the graduation — ADR-007 (direct op), ADR-008 (listen metadata + forwarded op)

The alksocks graduation research (tunnels-graduation.md) is decided;
the ADRs are normative now:

- ADR-007: the direct open op — channels/tunnel/direct on the one
  alk/tunnel ALPN, params {substrate, target} (self-describing JSON
  target; ATYP bytes rejected as not schema-describable), scope
  tunnel:direct (never implied by tunnel:open), dial-only.
- ADR-008: listen metadata — bind-first listen establisher (reply
  gains additive 'bound' = BND.ADDR fidelity; the BIND deadlock +
  10s-bound findings dissolve) + the forwarded op
  channels/tunnel/forwarded (accept-as-open, params carry
  {channel, substrate, peer} = reply#2 fidelity). Accept-first stays.
- ADR-001/002/006 amendments: params layout is per-op; flavor-form
  op ids on the one ALPN; per-flavor scopes + the hub re-produce
  policy sentence (the hub's ACL governs the final dial).
- wire/producer/consumer/overview/README updated for the new ops,
  the three establisher shapes, TunnelListener, open_direct.
- OQ-TN-15/16 promoted + resolved; upstream alkcall asks filed at
  alkcall/docs/reviews/008-tunnels-graduation-upstream-review.md
  (flavor-form discovery derivation; the establisher → reply
  projection).

Verification: cargo test (22 passed), clippy -D warnings, fmt --check
(docs-only change; wasm check unaffected)

2026-09-16 08:31:56 +00:00

6.6 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); 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 — 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)

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 — 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 — 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.

6.6 KiB Raw Blame History