fix(api): expose pagination headers via CORS

[mishushakov]

The API set AllowAllOrigins and AllowHeaders but never ExposeHeaders, so it sent no Access-Control-Expose-Headers — browsers hand JS only the CORS-safelisted response headers, so X-Next-Token was dropped before the SDK could read it and its paginator saw an empty cursor, making every page look like the last. This exposes every custom response header the API sets (X-Next-Token, X-Total-Running, RateLimit-Limit/Remaining/Reset, Retry-After) and moves the CORS config out of main.go into internal/middleware/cors.go so it can be tested. The new tests assert that every response header declared in the OpenAPI spec is exposed, and that the middleware actually emits the header on a cross-origin request. X-Next-Token was previously declared only on GET /v2/templates even though all four paginated endpoints emit it, so the spec now declares it on all of them (plus X-Total-Running on GET /v2/sandboxes) via a reusable components/headers entry; api.gen.go is regenerated with the embedded-spec blob only, no type changes.

Verified with go test ./packages/api/..., golangci-lint run packages/api/..., make fmt, and make lint.

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
CORS configuration and documentation changes only; no auth or business-logic changes beyond making existing response headers visible to cross-origin JavaScript.

Overview
Browser clients could not read pagination and rate-limit response headers because CORS never exposed them, so SDK paginators treated every page as the last. The API now lists those headers in Access-Control-Expose-Headers via dedicated CORS middleware, and the OpenAPI spec documents X-Next-Token (and X-Total-Running on sandbox list) on every paginated endpoint so spec and behavior stay aligned. Tests guard against future drift between declared response headers and what CORS exposes.

^{Reviewed by Cursor Bugbot for commit bdb45e5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 1 line in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/api/main.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[claude]

LGTM, straightforward CORS config fix with test coverage.

What was reviewed: the new middleware.CORS() extraction from main.go (no behavior change beyond adding ExposeHeaders), the new test asserting every OpenAPI-declared response header is exposed, and the openapi.yml header refactor into a reusable components/headers entry. Confirmed X-Total-Running and rate-limit/Retry-After headers referenced in exposedResponseHeaders are actually set by existing handlers/middleware, so the list isn't exposing anything speculative.

Extended reasoning...

Overview

This PR fixes a bug where the API never set Access-Control-Expose-Headers, causing browser SDKs to silently lose pagination (X-Next-Token) and rate-limit headers on cross-origin requests. It extracts the existing CORS config from main.go into a new, tested internal/middleware/cors.go, adds ExposeHeaders, and updates spec/openapi.yml to declare X-Next-Token/X-Total-Running consistently across the four paginated endpoints via a shared components/headers ref. api.gen.go changes are just the regenerated embedded spec blob.

Security risks

None identified. AllowAllOrigins: true and the request-header allowlist are unchanged from before; the only functional addition is exposing response headers to JS, which are non-sensitive (pagination cursor, running-sandbox count, rate-limit metadata). No auth, crypto, or permission logic is touched.

Level of scrutiny

Low-to-medium. This is a config/plumbing fix with a clear bug motivation, moved into a well-isolated, newly-tested middleware file. The diff is mostly mechanical (relocating existing code, generated spec blob, additive OpenAPI header declarations).

Other factors

New unit tests directly cover the fix's intent: one asserts every OpenAPI-declared response header is in the exposed list (guards against future drift), the other asserts the middleware actually emits Access-Control-Expose-Headers on a cross-origin request. I spot-checked that the headers listed in exposedResponseHeaders (rate-limit headers, X-Total-Running) are genuinely set by existing handlers, so the change is consistent with actual server behavior.