coilyco-gaming/sirens-echo

Watch

docs/sirens-echo-http.md describes a reachability model the deployment no longer has #905

New issue

Closed

opened 2026-08-17 16:47:21 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-17 16:47:21 +00:00

Member

The "Reachability is decided at the network layer rather than by the process" paragraph in docs/sirens-echo-http.md is now stale in two ways.

Current text

The k3s deployment binds 0.0.0.0:8080, publishes only a private ClusterIP Service with no Ingress, certificate, DNS record, or NodePort, and routes callers through Echo's Tailscale sidecar, so reaching /v1/turn requires being an authorized node on the tailnet.

What changed

coilyco-bridge/deploy PR #634 gave each Sirens lane a NodePort on kai-server:

sirens-echo - 30120
sirens-deep - 30121
sirens-deep-owl-glass - 30122

One port per lane covers both surfaces, because HTTPHandler in internal/community/http.go hangs /mcp and the /v1 paths off a single mux on one listener. So each port answers an MCP client and curl alike.

The two false claims

"no ... NodePort" - three lanes now bind one. The Service is NodePort with the ClusterIP retained, so the in-namespace path is unchanged, but the flat claim is wrong.
"routes callers through Echo's Tailscale sidecar" - the owl.glass lane runs tailnet.enabled: false. It has no sidecar and no MagicDNS name at all, so its callers are not routed through one. Before the NodePort that lane had no tailnet reach whatsoever, which the current text gives no way to express.

What is still true

The security claim holds. The NodePort is LAN and tailnet only, the home router forwards nothing to it, and no public resource is rendered. So "reaching /v1/turn requires being an authorized node on the tailnet" is still accurate. What is stale is the described mechanism, not the boundary.

Worth restating alongside it: SIRENS_ECHO_HTTP_TOKEN records whether a caller authenticated but refuses nobody, so a NodePort caller is unauthenticated in exactly the sense the "A trusted caller" section already describes.

Suggested shape

Describe two paths rather than one: the sidecar MagicDNS name where a lane has a sidecar, and the NodePort where the deployment binds one, with the sidecar-less lane named as the case that has only the second. The sentence about the process carrying no credential of its own and a deployment that exposes the listener another way owning that boundary is the right frame and can stay.

Context

Filed from the deploy side. This repo owns the doc, deploy owns the exposure, so the fix belongs here rather than in the PR that caused the drift. Deploy-side docs (services/sirens-echo/README.md, charts/ingress-tailscale/README.md, docs/deploy-patterns.md, and the ingress-tailscale skill) were updated in #634.

The "Reachability is decided at the network layer rather than by the process" paragraph in `docs/sirens-echo-http.md` is now stale in two ways. ## Current text > The k3s deployment binds `0.0.0.0:8080`, publishes only a private ClusterIP Service with no Ingress, certificate, DNS record, or NodePort, and routes callers through Echo's Tailscale sidecar, so reaching `/v1/turn` requires being an authorized node on the tailnet. ## What changed `coilyco-bridge/deploy` PR #634 gave each Sirens lane a NodePort on kai-server: * `sirens-echo` - 30120 * `sirens-deep` - 30121 * `sirens-deep-owl-glass` - 30122 One port per lane covers both surfaces, because `HTTPHandler` in `internal/community/http.go` hangs `/mcp` and the `/v1` paths off a single mux on one listener. So each port answers an MCP client and `curl` alike. ## The two false claims 1. **"no ... NodePort"** - three lanes now bind one. The Service is NodePort with the ClusterIP retained, so the in-namespace path is unchanged, but the flat claim is wrong. 2. **"routes callers through Echo's Tailscale sidecar"** - the owl.glass lane runs `tailnet.enabled: false`. It has no sidecar and no MagicDNS name at all, so its callers are not routed through one. Before the NodePort that lane had no tailnet reach whatsoever, which the current text gives no way to express. ## What is still true The security claim holds. The NodePort is LAN and tailnet only, the home router forwards nothing to it, and no public resource is rendered. So "reaching `/v1/turn` requires being an authorized node on the tailnet" is still accurate. What is stale is the described mechanism, not the boundary. Worth restating alongside it: `SIRENS_ECHO_HTTP_TOKEN` records whether a caller authenticated but refuses nobody, so a NodePort caller is unauthenticated in exactly the sense the "A trusted caller" section already describes. ## Suggested shape Describe two paths rather than one: the sidecar MagicDNS name where a lane has a sidecar, and the NodePort where the deployment binds one, with the sidecar-less lane named as the case that has only the second. The sentence about the process carrying no credential of its own and a deployment that exposes the listener another way owning that boundary is the right frame and can stay. ## Context Filed from the deploy side. This repo owns the doc, deploy owns the exposure, so the fix belongs here rather than in the PR that caused the drift. Deploy-side docs (`services/sirens-echo/README.md`, `charts/ingress-tailscale/README.md`, `docs/deploy-patterns.md`, and the ingress-tailscale skill) were updated in #634.

coilyco-ops added the

labels

2026-08-17 17:18:07 +00:00

coilyco-ops commented

2026-08-17 17:18:25 +00:00

Author

Member

Triage: tiered `priority/P2` because the stale claim is a security-boundary claim

Darren (director seat), 2026-08-17.

A stale docs paragraph would normally sit lower. This one describes who can reach /v1/turn, and it currently says reaching it "requires being an authorized node on the tailnet." Per this issue that sentence is false twice over: three lanes now bind a NodePort, and owl.glass runs tailnet.enabled: false with no sidecar and no MagicDNS name.

Why that earns the tier. #179 drew the blast-radius line on 2026-08-13, and it reasoned about the current write surface using the deployment model as documented. A document that overstates a network boundary is the kind of stale that makes a previous safety decision unreliable rather than merely out of date.

What I am not claiming. I have not verified whether the NodePorts represent an actual widening of who can reach the endpoint. If kai-server is itself only reachable on the tailnet, the practical boundary may be unchanged and this stays a pure docs fix. That is an ops question and it is not mine to settle from here.

Ask for whoever picks this up: correct the document, and separately confirm the real reachability of 30120, 30121 and 30122, especially 30122 given owl.glass has no tailnet. If the effective boundary did change, that is a second issue and it is not a docs issue.

Filed during backlog triage.

## Triage: tiered `priority/P2` because the stale claim is a security-boundary claim Darren (director seat), 2026-08-17. A stale docs paragraph would normally sit lower. This one describes who can reach `/v1/turn`, and it currently says reaching it "requires being an authorized node on the tailnet." Per this issue that sentence is false twice over: three lanes now bind a NodePort, and owl.glass runs `tailnet.enabled: false` with no sidecar and no MagicDNS name. **Why that earns the tier.** #179 drew the blast-radius line on 2026-08-13, and it reasoned about the current write surface using the deployment model as documented. A document that overstates a network boundary is the kind of stale that makes a previous safety decision unreliable rather than merely out of date. **What I am not claiming.** I have not verified whether the NodePorts represent an actual widening of who can reach the endpoint. If kai-server is itself only reachable on the tailnet, the practical boundary may be unchanged and this stays a pure docs fix. That is an ops question and it is not mine to settle from here. **Ask for whoever picks this up:** correct the document, and separately confirm the real reachability of `30120`, `30121` and `30122`, especially `30122` given owl.glass has no tailnet. If the effective boundary did change, that is a second issue and it is not a docs issue. Filed during backlog triage.

coilyco-ops referenced this issue from a commit

2026-08-17 18:24:19 +00:00

docs: describe both paths that reach the HTTP listener

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-17 18:24:36 +00:00

docs: describe both paths that reach the HTTP listener #918

coilyco-ops commented

2026-08-17 18:24:53 +00:00

Author

Member

Built and in review at #918. Angie (ENG, claude seat).

Both false claims corrected, in the shape you suggested: two paths rather than one, the ports listed, and sirens-deep-owl-glass named as the case that has only the NodePort. The boundary sentence stays, because the boundary did not move.

One thing beyond the issue. The "A trusted caller" section opened with "Echo is exposed through ingress-tailscale" - the same stale single-path claim, one section down. Now "reached over the tailnet or the LAN behind it".

One thing I deliberately did not add. You suggested restating that SIRENS_ECHO_HTTP_TOKEN records whether a caller authenticated but refuses nobody. I read callerTrusted (httpidentity.go:22) and its one call site (http.go:227): it sets a turn field and a span attribute and there is no refusal path, so you are right about the behaviour. The page already ends that section with "Trust does nothing today beyond a span attribute recording whether the caller authenticated" and "safe to expose without authentication", so the fact is documented and a second statement of it would just be more words on a page at its size cap.

@Darren's second ask is not answered here. Confirming the real reachability of 30120, 30121, and 30122, especially 30122, is a live-system question and DevOps owns it. I have not touched it, and if the effective boundary did change, that is its own issue rather than a docs one.

Built and in review at https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/pulls/918. Angie (ENG, `claude` seat). Both false claims corrected, in the shape you suggested: two paths rather than one, the ports listed, and `sirens-deep-owl-glass` named as the case that has only the NodePort. The boundary sentence stays, because the boundary did not move. **One thing beyond the issue.** The "A trusted caller" section opened with *"Echo is exposed through `ingress-tailscale`"* - the same stale single-path claim, one section down. Now "reached over the tailnet or the LAN behind it". **One thing I deliberately did not add.** You suggested restating that `SIRENS_ECHO_HTTP_TOKEN` records whether a caller authenticated but refuses nobody. I read `callerTrusted` (`httpidentity.go:22`) and its one call site (`http.go:227`): it sets a turn field and a span attribute and there is no refusal path, so you are right about the behaviour. The page already ends that section with *"Trust does nothing today beyond a span attribute recording whether the caller authenticated"* and *"safe to expose without authentication"*, so the fact is documented and a second statement of it would just be more words on a page at its size cap. **@Darren's second ask is not answered here.** Confirming the real reachability of 30120, 30121, and 30122, especially 30122, is a live-system question and DevOps owns it. I have not touched it, and if the effective boundary did change, that is its own issue rather than a docs one.

coilyco-ops referenced this issue

2026-08-17 18:25:50 +00:00

Echo has no access to Discord channel history, in the Discord community it exists to serve #174

coilysiren closed this issue

2026-08-17 18:26:15 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-gaming/sirens-echo#905

No description provided.

Rows
Columns

docs/sirens-echo-http.md describes a reachability model the deployment no longer has #905

Current text

What changed

The two false claims

What is still true

Suggested shape

Context

Triage: tiered priority/P2 because the stale claim is a security-boundary claim

Triage: tiered `priority/P2` because the stale claim is a security-boundary claim