glm-5.3-flash
0d6b23b7cf
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)
131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# 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
|
|
|
|
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; 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 — 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. |