Proposal: a local authenticated API proxy (datumctl api proxy)

[scotwells]

What this is

An enhancement proposal for datumctl api proxy — a local, loopback-only HTTP proxy that forwards every request to the Datum Cloud API endpoint of the user's datumctl session, injecting a valid bearer token and transparently refreshing it. Any local tool can then talk to the platform with zero token plumbing:

$ datumctl api proxy --port 8001
$ curl http://127.0.0.1:8001/apis/resourcemanager.miloapis.com/v1alpha1/organizations

This PR contains only the design document (docs/proposals/datumctl-api-proxy/README.md), following the same proposal conventions as the plugin-marketplace enhancement.

Why it exists

• Cloud-portal local development — the portal dev server needs a platform bearer token per request today; with the proxy, API_URL=http://127.0.0.1:8001 and datumctl owns auth and refresh for the whole dev session.
• The portal's plugin-registry watch client — watches CRDs on a control plane through the proxy, so unbuffered streaming passthrough (Kubernetes-style watch / SSE / chunked transfer) is a hard requirement of the design.
• E2E test harnesses — start a proxy on a random free port, read the URL from stdout as the readiness signal, and never distribute credentials into test processes.
• Scripting and exploration — curl against localhost instead of copy-pasting tokens that expire mid-investigation.

Key design positions the doc takes

• Pure passthrough by default, explicit scoping on request — a bare proxy serves the full endpoint so dev paths match production paths exactly; --project/--organization re-base the proxy at one control plane for short URLs. Scope is never silently inherited from the active context.
• Conservative security posture — loopback-only with no override flag, Host-header validation (DNS-rebinding defense), no CORS headers, inbound Authorization always stripped, tokens never logged, raw tokens never served over HTTP.
• Predictable lifecycle — session pinned at startup (datumctl auth switch never repoints a running proxy), machine-readable readiness contract, actionable 502s (never a fake 401) when the local session dies.
• A product-level design: session and endpoint resolution identical to the rest of the CLI, a streaming design with a deterministic watch integration test, prior-art analysis (kubectl proxy, cloud-sql-proxy, gh api, aws-vault), open questions, and a v1 milestone cut.

Review focus

The design decisions most worth reviewer eyes — a bare invocation never inherits the active context (production-path parity wins), 127.0.0.1-only binding, Unix-socket mode as the first fast-follow, and never retrying an upstream 401 — are each stated with their rationale in the section they belong to.

Companion implementation PR: #247.

🤖 Generated with Claude Code