feat(http): HTTP transport + OAuth 2.1 + PKCE for remote MCP hosts (0.2.0)

[govindkavaturi-art]

Stage C of the multi-key-per-user sprint. Ships the remote MCP transport that lets Claude.ai Custom Connectors (and any other HTTP-speaking MCP host) authenticate via OAuth and talk MCP over HTTP.

Depends on Stage B (cueapi #275) being live, since /callback/cueapi calls POST /v1/auth/mcp-exchange to mint the per-connection CueAPI api_key.

What lands

Dual-transport entry (backward compat preserved). src/index.ts routes to stdio-entry.ts (default, same as 0.1.x) or http-entry.ts (new) based on --transport flag or MCP_TRANSPORT env var. Existing Claude Desktop / Code / Cursor / Zed configs keep working with zero changes.

HTTP server with six endpoints:

Endpoint	Purpose
GET /health	Liveness
GET /.well-known/oauth-authorization-server	RFC 8414 metadata
GET /authorize	OAuth entry — PKCE mandatory, S256 only
GET /callback/cueapi	Post magic-link — calls /v1/auth/mcp-exchange, mints 60s auth_code
POST /token	authorization_code + refresh_token grants, PKCE verified, auth_code single-use
POST /mcp	MCP protocol via StreamableHTTPServerTransport, bearer-auth'd

Token store — abstract TokenStore interface; SQLiteTokenStore default backend. Three tables: auth_codes (60s TTL), access_tokens (24h), refresh_tokens (30d). CueAPI api_key encrypted at rest with AES-256-GCM, key derived from OAUTH_SIGNING_SECRET via scrypt.

State-signing helpers — signState / verifyState HMAC-SHA256 a JSON envelope so the PKCE challenge + Anthropic's state round-trip through cueapi.ai's magic-link flow tamper-proof.

Client refactor — CueAPIClient constructor apiKey is now optional; request() accepts a trailing override. Stdio mode continues to use the env-var key once at boot; HTTP mode creates a per-request client scoped to the OAuth access_token's stored api_key.

Security properties (asserted by tests)

• PKCE mandatory on /authorize — rejects absent code_challenge, rejects plain method
• State envelope signed HMAC-SHA256; tampered states rejected at /callback/cueapi with no side effects
• Auth codes single-use; replay after exchange returns invalid_grant
• Access tokens never expose the underlying CueAPI api_key
• api_key encrypted at rest via AES-256-GCM — asserted by raw-DB-file scan confirming the plaintext is NOT present on disk
• OAUTH_SIGNING_SECRET minimum 32 chars enforced at SQLiteTokenStore construction

Config (HTTP mode)

Required:

MCP_PUBLIC_URL                   e.g. https://mcp.cueapi.ai
OAUTH_SIGNING_SECRET             >=32 chars, random
ALLOWED_CLAUDE_AI_CLIENT_IDS     comma-separated Anthropic client_ids
CUEAPI_MCP_CLIENT_ID             this deployment's registered client_id on cueapi.ai

Optional:

MCP_PORT=3000
CUEAPI_BASE_URL=https://api.cueapi.ai
CUEAPI_MCP_EXCHANGE_ENDPOINT=<override>
SQLITE_PATH=./mcp-tokens.db

Stdio mode (existing): CUEAPI_API_KEY + optional CUEAPI_BASE_URL. Unchanged.

Tests

npm test → 45 passed, 0 failures across 4 files:

• tests/pkce.test.ts (8) — S256 RFC vector, tamper rejection, length bounds, base64url round-trip
• tests/tools.test.ts (9) — existing, untouched
• tests/token-store.test.ts (15) — encryption + IV randomization + GCM tamper + wrong-secret + state signing + SQLite CRUD + TTL + cleanup + at-rest scan
• tests/oauth-flow.test.ts (13) — supertest end-to-end with mocked fetchApiKeyFromSession. Happy path /authorize → /callback/cueapi → /token → POST /mcp bearer-check, plus PKCE rejection, auth-code replay rejection, tampered state rejection

What's NOT in this PR (deferred)

• RedisTokenStore — SQLite default works for single-instance Railway deploy. Interface is factored so a Redis backend can drop in later with no call-site changes.
• Dockerfile + railway.json — Phase 7 of the sprint is a deployment doc for mcp.cueapi.ai setup; the Dockerfile lands alongside it.
• HTTP transport client-SDK smoke tests — the three security tests in oauth-flow.test.ts cover the main paths; exhaustive coverage is a follow-up.

Version bump

package.json → 0.2.0 (new capability, minor bump). Not yet published — publish after #275 (Stage B) lands in prod.

Commits

• e6ccdca refactor(transport): dual-transport router + stdio extracted + per-request apiKey
• cdb0aba feat(http): HTTP transport with OAuth 2.1 + PKCE + SQLite token store
• d75604c test(http): 36 new tests for pkce, token-store, OAuth flow end-to-end

Test plan

• npm run build clean (confirmed locally — zero TS errors)
• npm test → 45/45 green (confirmed locally)
• Stdio mode still works — smoke test a local Claude Desktop pointing at this branch
• After merge: publish 0.2.0 to npm, then start Stage D deploy

[argus-qa-ai]

Argus review — LGTM. Security design is sound: PKCE mandatory (S256 only), HMAC-SHA256 state signing with timing-safe comparison, AES-256-GCM at-rest encryption with scrypt-derived key + randomized IV, auth codes single-use, appropriate TTLs (60s/24h/30d), 32-char secret minimum enforced at construction. Stateless StreamableHTTPServerTransport is the right pattern. One non-blocking flag: userId from mcp-exchange is discarded in /callback/cueapi — access_token and refresh_token store userId:"". Not a security issue, but worth wiring up for future features. 45/45 tests pass. Stage B (#275) is live. Approved.