improvement(api): declare OAuth scopes in OpenAPI, JSON 404s for unknown API paths, and root MCP resource metadata

[waleedlatif1]

Summary

• OpenAPI oauthBearer is now a standard oauth2 authorization-code scheme (authorize/token/refresh URLs, api:read / api:write / offline_access scopes) instead of http bearer with scopes only in prose
• Every generated operation's security names its least-privilege scope (oauthBearer: ["api:read"]), derived from the application operation's oauthScope — the same single source as x-oauth-scope
• Generator validation keys on scheme type oauth2 (not the oauthBearer name) and fails if an operation's scope isn't declared by the scheme's flow
• Docs code samples render an oauth2 scheme as Authorization: Bearer; the playground keeps its manual token field
• Dedicated MCP host serves its RFC 9728 metadata at the root /.well-known/oauth-protected-resource too — the fallback MCP clients try after the path-inserted URL (MCP authorization spec, Protected Resource Metadata Discovery). resource stays the MCP URL; the app host still has no root document
• New app/api/[[...segments]] returns a JSON 404 for unknown /api/* paths instead of the HTML not-found page, mirroring the existing /api/v2 fallback

Compatibility

• Wire behavior is unchanged: OAuth tokens still go in Authorization: Bearer, x-oauth-scope and the document-level security are kept, the anonymous alternative on workflow execute is kept
• The declared OAuth flow matches what the authorization server issues today: authorization code + PKCE S256, unbound tokens (no resource), which is what /api/v2 accepts
• Docs: the API playground is disabled, so the oauth2 type adds no Authorize UI; code samples still lead with the API key
• Unknown /api/* paths stay 404, now as JSON; every existing route, the /api/v2 and /api/auth catch-alls, and next.config /api header rules are unaffected (Next only routes here when nothing more specific matches)
• Root metadata exists only on the dedicated MCP host, where that path was a 404; its resource is the MCP URL, same document as the path-inserted one

Type of Change

• Improvement

Testing

• scripts/openapi tests (generator + documents), host-routing.test.ts; confirmed the per-operation scope assertion fails with the derivation removed, and generation fails with a scope dropped from the scheme
• generate:openapi --check, check:api-validation:strict, check-api-contract-routes, docs tsc, lint
• Extended test-mcp-host-e2e.ts (CI cli group): no root metadata on the app host, JSON 404 for unknown /api GET/POST. The MCP-host metadata mapping is covered by host-routing.test.ts, not E2E: that group runs next dev, where proxy rewrites on the dedicated host 404 for every rewritten path (the existing /mcp → /api/mcp included; reproduced locally). Production serves the existing path-inserted URL through the same rewrite target
• check-openapi-specs, generate:cli-api --check (CLI client unchanged), check-unused-exports
• Full type-check, check:audits, and test suites left to CI

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing (new tests pass the test-audit authoring gate)
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 14, 2026 5:50pm UTC

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no blocking issues were found.

Summary

This PR declares OAuth flows and per-operation scopes in OpenAPI, adds JSON 404s for unknown API paths, and serves root resource metadata on the dedicated MCP host.

• API docs show which OAuth scope each operation needs.
• Unknown API paths return a JSON 404 instead of an HTML page.
• The dedicated MCP host serves protected-resource metadata at its root URL.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Application operation scope] --> B[OpenAPI generator]
  B --> C[Check scope exists in OAuth flow]
  C --> D[Emit per-operation security]
  E[Unknown API path] --> F[JSON 404 fallback]
  G[Root metadata request] --> H{Dedicated MCP host?}
  H -->|Yes| I[Existing MCP metadata route]
  H -->|No| J[Normal app routing]
  I --> K[Canonical MCP resource URL]

Loading

_{Reviews (2) · Last reviewed commit: "fix(api): shrink the unused-exports base..." · Reviewed by Greptile}

[cubic-dev-ai]

No issues found across 18 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Turn on auto-fix | Re-trigger cubic}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 19 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Turn on auto-fix | Re-trigger cubic}