Skip to content

P1: security and deployment items (CORS, default JWT secret, WS auth and Origin, server timeouts) - #7

Merged
TyperBody merged 3 commits into
feat/project-review-and-pr-qafrom
feat/p1-security-cors-ws-timeouts
Nov 7, 2026
Merged

TyperBody merged 3 commits into
feat/project-review-and-pr-qafrom
feat/p1-security-cors-ws-timeouts

Conversation

@TyperBody

@TyperBody TyperBody commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Closes the four P1 security/deployment items from the functional review (M2, M3, M4, M15). Stacked on feat/project-review-and-pr-qa (PR #3) as the issue asked; nothing else in PR #3 is touched.

What changed

  • internal/middleware/origin.go (new) — one OriginPolicy built at startup from server.allowed_origins and consumed by both CORS and every CheckOrigin. The decision is shared (AllowsRequest), so the REST and socket surfaces cannot disagree.
  • internal/middleware/middleware.go — CORS(policy) echoes the caller's origin when it is allowed instead of sending a literal *, and only then sends Access-Control-Allow-Credentials: true. Vary: Origin always.
  • internal/middleware/auth.go — WSTokenRequired() validates a JWT before the upgrade: ?token= first (the only header a browser WebSocket can carry), Authorization: Bearer as the non-browser fallback. Bad token → 401.
  • internal/middleware/body.go (new) — MaxBodyBytes wraps the body in http.MaxBytesReader; BodyTooLarge turns the resulting bind error into 413 instead of a misleading 400.
  • internal/handler/websocket.go — the package-level upgrader with CheckOrigin: return true is now wsUpgrader(policy); both handlers take the policy.
  • internal/server/server.go — the two /ws routes go behind WSTokenRequired; http.Server gets ReadHeaderTimeout / ReadTimeout / WriteTimeout / IdleTimeout from config.
  • internal/config/config.go — server.allowed_origins and the four timeout knobs plus max_body_bytes, all with defaults; PlaceholderJWTSecret and JWTSecretWarning.
  • main.go — logs the placeholder-secret WARN after logger.Init.
  • internal/adaptergateway/gateway.go — GatewayConfig.CheckOrigin, so the custom per-adapter listen paths inherit the same list.
  • 19 handler bind sites route through BodyTooLarge.
  • adapters/{taobao,xianyu}/esp_bridge.py — append a quoted ?token= to the WS URL. Without this a bridge with a token configured fails a handshake it used to pass.

Why

M2 — Access-Control-Allow-Origin: * was sent together with Access-Control-Allow-Credentials: true. A browser ignores the credentials flag on a wildcard origin, so the pair was a no-op. The issue offered "echo a whitelist" or "delete the credentials header"; echoed origin is the choice because it makes the pair true, and the front end sending a Bearer header does not mean it always will. The allow-list is shared with M4 so the two cannot drift.

M4 — CheckOrigin returned true and both /ws routes hung no middleware, so knowing an instance_id/app_id was enough to open a socket from anywhere. Now the handshake is authenticated (401) and origin-checked (403) before the upgrade.

One subtlety worth flagging: browsers send Origin on every handshake, same-origin included. A bare allow-list would therefore break the embedded desktop build, which serves UI and API from one port. CheckOrigin also accepts a request whose Origin host equals the request Host; CORS reads the same predicate. A different port is still cross-origin, and http://localhost:3000.evil.example does not pass for http://localhost:3000.

M3 — the shipped secret was used with no check. Startup now WARNs while it is the placeholder or empty. WARN rather than refuse to start, so a fresh clone still runs. The check is a pure function called after logger.Init because config.Load runs before the logger exists.

M15 — the server had only Addr and Handler. All four timeouts and the body cap are wired from config with defaults. Sockets are unaffected: the upgrade hijacks the conn and clears the deadlines.

How it was verified

All commands from the repository root, CGO_ENABLED=1 (cgo is required for the SQLite driver, see pr-qa.md):

  • go test ./... — pass, including the new tests.
  • go vet ./... — clean (only go-sqlite3's C warning).
  • gofmt -l . — no output.
  • golangci-lint run (v2.1.6, the CI pin) — 0 issues.
  • python3 scripts/check_generated.py matrix.json — unchanged, generator not touched.

New tests, and each fails on the base commit:

  • main_test.go::TestStartupWarnsOnPlaceholderSecret — builds and starts the real binary, asserts the WARN reaches the log. TestStartupIsSilentWithRealSecret is the control, so a build that always warns cannot pass.
  • internal/config/config_test.go — the predicate and the empty-secret case; the loader really returns the placeholder; the hardening defaults are non-zero.
  • internal/server/security_test.go — real router behind httptest: handshake without a token → 401, garbage token → 401, valid token from an untrusted origin → 403, valid token from a listed origin → accepted, same-origin accepted, app route authenticated too, preflight echo, 3 MiB body → 413.
  • internal/server/server_test.go — the timeouts land on the built http.Server, a configured 0 maps to "disabled", and CORS and the upgrader share one policy.
  • internal/middleware/middleware_test.go — CORS allow/deny/wildcard/preflight, WSTokenRequired matrix, body cap.

Live evidence against a built binary (PORT=18082, throwaway DB), before → after:

CORS preflight from https://evil.example:

before: 204, Access-Control-Allow-Origin: *          + Allow-Credentials: true
after:  204, (no Allow-Origin, no Allow-Credentials) + Vary: Origin

Same preflight from http://localhost:3000:

before: Allow-Origin: *        + Allow-Credentials: true
after:  Allow-Origin: http://localhost:3000 + Allow-Credentials: true

WS handshake, /ws/adapter:

no token / garbage token                -> 401   (before: accepted)
valid token, Origin https://evil.example -> 403  (before: accepted)
valid token, listed or same origin       -> accepted

Timeouts, partial header block and a trickled body:

partial headers: before still open after 20.0s -> after closed at 5.0s (read_header_timeout)
trickled body:   before still writable after 75.9s -> after closed at 58.7s (read_timeout)

Body cap (default 8 MiB): 1 MiB → 401 (business), 8 MiB → 413, 9 MiB → 413.

Docs affected

docs/developer-guide/api-reference.md (CORS and origins, server limits table, 413, handshake token, same-origin rule), .github/SECURITY.md (the two stale "not there yet" bullets become shipped behaviour; the residual ownership gap is stated), docs/developer-guide/bridge-protocol.md, docs/developer-guide/inactive-fields.md, docs/user-guide/troubleshooting.md, both READMEs.

Protocol v3 impact

No. The envelope, chain, signing and message-fields.md are untouched. The handshake credential is transport-level.

Risk and rollback

  • The WS token requirement is the breaking change for third-party bridges. A bridge that connected to /ws/adapter with only ?instance_id= now gets 401. Both bundled adapters are updated; a custom bridge needs &token=<JWT>. Rollback is the reverse.
  • An unlisted origin now fails the handshake with 403 instead of being accepted. Same-origin is unaffected by design, so a normal reverse-proxy deployment needs no config.
  • CORS stops answering *. A cross-origin caller must be listed. Same-origin is unaffected.
  • A body over 8 MiB gets 413. Adapter configs are JSON blobs, comfortably under it; server.max_body_bytes raises it.
  • Timeouts assume responses fit in 60 s. Nothing streams today.
  • Forward path: the allow-list, timeouts and cap are config keys with defaults, so a rollback that keeps config/config.yaml still starts — the new keys are simply ignored by the older binary.

Checklist

  • One concern per PR, based on feat/project-review-and-pr-qa (PR Add a PR QA pipeline and re-verified functional review #3) as asked
  • Tests cover the change — each new test fails on the base commit
  • No unit test calls a real Taobao/Xianyu endpoint
  • No secret, cookie, token or default JWT secret in the diff or pasted logs (the placeholder is quoted as the subject of the warning)
  • No new user-facing strings in web/, so no locale keys touched
  • Commits follow Conventional Commits; no force-push yet
  • do-not-merge — not added; ready for review

TyperBody and others added 3 commits November 7, 2026 20:09
`server.allowed_origins` is the single list CORS and the WebSocket
handshake will both read, so the two cannot drift apart. Matching is exact
(scheme + host + port): a prefix match would accept
`http://localhost:3000.evil.example` for `http://localhost:3000`.

`server.read_header_timeout` / `read_timeout` / `write_timeout` /
`idle_timeout` / `max_body_bytes` carry defaults, so a deployment that never
edits config.yaml is also hardened rather than only the one that does.

`PlaceholderJWTSecret` names the shipped secret in one place, and
`JWTSecretWarning` returns the startup warning for it. It is a pure function
rather than a log call inside Load because Load runs before logger.Init; a
nil zap logger there would drop the warning silently.

The empty-string case warns too: exporting an empty JWT.SECRET signs with an
empty key, which is not the placeholder but is just as forgeable.

Co-authored-by: multica-agent <github@multica.ai>
M2 — CORS echoed a literal `*` together with
`Access-Control-Allow-Credentials: true`. A browser ignores the credentials
flag when the origin is a star, so the pair was incoherent even though the
current Bearer-header session does not depend on it. The allowed origin is
now echoed, which makes the pair true — and keeps the front door open for a
later Cookie-carried session instead of quietly breaking it.

M4 — `/ws/adapter` and `/ws/app` hang no middleware at all and their
upgrader returned `true` from CheckOrigin. Either route therefore accepted
any site for whatever `instance_id` / `app_id` the caller typed. Both now
sit behind WSTokenRequired (JWT from `?token=`, or an Authorization header
for non-browser clients) and share the CORS allow-list through one
OriginPolicy; a bad token answers 401 and a bad origin answers 403 before
the upgrade, so a client can tell those apart from a network failure.

Browsers send Origin on *every* handshake, same-origin included, so
CheckOrigin also accepts a request whose Origin host equals its Host. Without
that the embedded desktop build, which serves UI and API from one port,
would have to list its own URL. CORS reads the same predicate.

M15 — the http.Server had a bare Addr and Handler: no header deadline, no
read/write/idle budget, and no cap on the body `ShouldBindJSON` slurps into
memory. All four timeouts are set, and MaxBodyBytes wraps the body in
http.MaxBytesReader; handlers answer 413 instead of the misleading 400 for
"unexpected end of JSON input". WebSockets are unaffected because the
upgrade hijacks the conn and clears the deadlines.

M3 — main logs the placeholder-secret warning after logger.Init.

Co-authored-by: multica-agent <github@multica.ai>
API reference gains the origin allow-list, the server limits table, the 413
code, and the WebSocket handshake token — a changed endpoint updates the doc
under the same commit, per pr-qa. SECURITY.md stops describing the `*` plus
credentials pair and the any-origin upgrader as outstanding, and now states
the residual gap: the handshake proves a valid token, not ownership of the
`instance_id` behind it.

The two bridge adapters append `?token=` to their WS URL, quoting it.
Without that a bridge with a token configured still fails the handshake it
used to pass. READMEs, bridge-protocol, inactive-fields and the
troubleshooting snippet follow.

Handlers route bind failures through middleware.BodyTooLarge so an over-size
body is 413, not a parse error. The adapter gateway gets the same CheckOrigin
hook for its custom listen paths.

Co-authored-by: multica-agent <github@multica.ai>
@TyperBody
TyperBody merged commit fa4a45b into feat/project-review-and-pr-qa Nov 7, 2026
4 checks passed
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