Skip to content

P1: CORS/WS origin allowlist, handshake auth, server timeouts - #5

Closed
TyperBody wants to merge 1 commit into
feat/project-review-and-pr-qafrom
agent/qjy/espl-20-p1-security
Closed

TyperBody wants to merge 1 commit into
feat/project-review-and-pr-qafrom
agent/qjy/espl-20-p1-security

Conversation

@TyperBody

@TyperBody TyperBody commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

P1 security/deployability set from docs/developer-guide/functional-review.md (M2, M3, M4, M15). Base is feat/project-review-and-pr-qa (PR #3), per the task; nothing from #3 is merged in, this is one commit on top of it.

What changed

M2 — CORS (internal/middleware/middleware.go)
Allow-Origin: * + Allow-Credentials: true is a contradiction: a wildcard origin forbids credentials, and the front end would silently lose them the day it uses Cookies. The middleware now echoes the request Origin back only when it is in the allowlist, keeps Allow-Credentials: true, and adds Vary: Origin so a shared cache cannot serve one client's CORS headers to another. Requests with no Origin (curl, the Python bridges, health checks) get no CORS headers and are otherwise untouched.

M4 — WebSocket handshake (internal/handler/websocket.go, internal/adaptergateway/gateway.go)
The two /ws handlers sat behind no middleware and CheckOrigin returned true, so anyone who knew an instance_id / app_id could open a socket. Now:

  • the token is validated before the upgrade; missing or invalid gets a plain 401, not a socket that closes instantly;
  • a foreign Origin is refused with 403 by the upgrader, checked against the same list CORS uses;
  • the adapter gateway upgrader takes that list through GatewayConfig.AllowedOrigin, so all three socket surfaces agree;
  • a request with no Origin is a non-browser client and passes.

Tokens are accepted via ?token= (the Python bridges — updated here), Authorization: Bearer, or Sec-WebSocket-Protocol: espl, <jwt> (the only header a browser can set on WebSocket).

M3 — placeholder JWT secret (internal/config/config.go, internal/server/server.go)
Startup logs a WARN while the shipped value (or an empty secret) is in place, with a fix hint. WARN rather than refuse-to-boot so existing deployments keep running. UsingPlaceholderJWTSecret requires an exact match: a secret that merely contains the placeholder text is a real rotation and must not warn.

M15 — server limits (internal/server/server.go, internal/middleware/middleware.go)
All four timeouts (ReadHeaderTimeout/ReadTimeout/WriteTimeout/IdleTimeout) are wired from server.* config, default 10s/60s/120s/120s, 0 = disabled. A global MaxBodyBytes middleware enforces server.max_body_bytes (default 4 MiB): a declared oversize is refused with 413 up front, an undeclared one is caught by http.MaxBytesReader.

One allowlist. security.allowed_origins drives CORS, both socket upgraders and the gateway, so they cannot drift; ESP_SECURITY_ALLOWED_ORIGINS (comma-separated) overrides it without editing the file.

Verification

Every item has tests that fail on the old code, including the cases that used to pass silently (garbage token accepted, cross-origin accepted, no timeout):

go test ./internal/middleware/ ./internal/handler/ ./internal/config/ ./internal/server/   # pass
CGO_ENABLED=1 go test ./...      # pass
go vet ./...                     # clean
gofmt -l .                       # empty
golangci-lint run (v2.1.6)       # 0 issues

End-to-end, real server on a temp port (CGO_ENABLED=1 build), before → after:

Probe Before After
OPTIONS, allowlisted Origin Allow-Origin: * 204, Allow-Origin: http://allowed.example, Allow-Credentials: true, Vary: Origin
OPTIONS, foreign Origin Allow-Origin: * 204, no Allow-Origin
GET /ws/app?app_id=… no token 101 401
…&token=total-garbage 101 401
cross-origin handshake, valid token 101 403
allowlisted origin, valid token 101 101
8 KB body (limit 4 KB) read as-is 413
half a request head, then stall held open dropped at 2.0s (configured ReadHeaderTimeout)

Notes for review

  • This is authentication, not authorization. The handshake now proves the token is valid; which token may touch which instance_id is M1 and still open.
  • The bridges are updated because ?token= is now required — without it they would 401-loop. Only the URL builder and one import changed.
  • security.allowed_origins defaults to localhost only. A real deployment must add its front-end origin; documented in SECURITY.md and CONTRIBUTING.md rather than left to fail at runtime.
  • The review doc's M2/M3/M4/M15 sections and its fix-order list are marked fixed, so the next reader does not re-do them.

Rebase note

The base moved while this was open: 8e764e7 (ci: run on stacked PRs…) landed the same
CI-trigger fix I had also written, so my duplicate commit was dropped and this is now one
commit on current feat/project-review-and-pr-qa. Nothing from #3 is merged in.

That trigger fix is also what makes the checks below run at all — before it, a PR into a
feature branch got zero checks because branches matches the base.

CI

All four checks green on 1101d87: backend (vet, build, test), frontend (tsc, vite build),
generated artifacts, format and lint.

Closes the review's P1 set (M2, M3, M4, M15) on top of the PR QA branch.

M2 — CORS echoed a fixed `*` alongside `Allow-Credentials: true`, which is
unusable: a wildcard origin forbids credentials. The configured Origin is now
echoed back (plus `Vary: Origin`), and only when it is in the allowlist, so
`Allow-Credentials` becomes meaningful and a future Cookie session keeps
working.

M4 — the WebSocket upgraders accepted any origin and the two /ws routes sat
behind no middleware at all, so knowing an instance_id or app_id was enough to
open a socket. Handshakes now require a valid JWT before the upgrade (401
otherwise) and check the same Origin allowlist as CORS (403 for a foreign
origin). The adapter gateway upgrader takes the list through
GatewayConfig.AllowedOrigin. Tokens are accepted via ?token= (Python bridges,
updated here), Authorization: Bearer, or the `espl` subprotocol, which is the
only header a browser can set on a WebSocket. Requests without an Origin are
non-browser clients and pass.

M3 — the shipped JWT secret was used with no check. Startup now WARNs while the
placeholder (or an empty secret) is in place, with a fix hint. A prefix
comparison would misfire, so a secret that merely contains the placeholder text
still counts as rotated.

M15 — http.Server had only Addr and Handler. All four timeouts are wired from
config, and a global MaxBodyBytes middleware caps request bodies: a declared
oversize is refused with 413 up front, an undeclared one is caught by
http.MaxBytesReader.

One `security.allowed_origins` list drives CORS, both socket upgraders and the
gateway, so they cannot drift; ESP_SECURITY_ALLOWED_ORIGINS overrides it
without editing the file. Every item has a test, including the cases that used
to pass silently (garbage token accepted, foreign origin accepted).

Docs touched: api-reference (WS auth table, CORS, limits, 413),
SECURITY, CONTRIBUTING, and the review's own status marks.

Co-authored-by: multica-agent <github@multica.ai>
@TyperBody
TyperBody force-pushed the agent/qjy/espl-20-p1-security branch from 5beee1c to 1101d87 Compare November 7, 2026 11:47
TyperBody added a commit that referenced this pull request Nov 7, 2026
Third stacked PR; P1 (#5) and P0 (#6) both touch websocket.go and its
test, so the pair only merges with resolution. Same treatment as the P2
merge: union the two sides rather than pick.

- websocket.go: both imports (P0 needs message, P1 needs middleware);
  both sockets keep the pre-upgrade authenticateWS check
- websocket_test.go: keep P0's hub fixtures and P1's handshake-auth and
  Origin cases in one file, with P1's helper renamed to dialPlain to
  avoid the method-name collision, and one TestMain
- P0's fixture dials now carry a token, since the handshake refuses an
  unauthenticated upgrade; the separator is & because the path already
  has a query string
- functional-review.md: combine the P2 and P1 fix-list annotations

Verified on one build with all three PRs: three keyless ingests 201/201/
201, duplicate register 409, delete-missing 404, cross-origin preflight
without Allow-Origin, 8 MB body 413, WS without token 401.
go vet, gofmt (0), golangci-lint (0 issues) and the full suite pass.
@TyperBody TyperBody closed this Nov 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant