feat(ax): config-declared entry auth — tell agents where to authenticate

[arielshulman29]

What

Site owners can declare where agents authenticate, ax init asks for it (prefilled when the source tree already states it), and the build report gets a structured auth section. Designed around the realistic maturity ladder: most apps' agent lane is an API key behind their existing login; OAuth is the spec-track upgrade for those whose auth provider already offers it.

1. Config-declared entry auth

An entry override in ax.config can declare a first-class auth descriptor (exactly Ora's secret-free EntryAuth shape):

entries: [{
  identifier: 'urn:air:example.com:mcp-server',
  auth: { status: 'api_key', docsUrl: 'https://example.com/docs/api-access' },
  // or status: 'oauth2' with oauth.authorizationEndpoint / tokenEndpoint
}]

Declared once, it flows to the catalog entry, the MCP server card's authentication block, and the generated /auth.md. For withMcpAuth-wrapped MCP mounts — which detection can only describe as "requires auth, scheme unknown" — the declaration is routed into the mount itself, so all three surfaces agree.

• config-schema: auth typed + validated by a closed sub-schema (status enum, absolute http(s) URLs ≤256 chars, capped lists, unknown keys fail loudly).
• auth: sanitizeDeclaredAuth() applies the same secret-guard as detected descriptors (safeHttpUrl, caps, whitelist-only fields).
• detect-mcp: applyDeclaredMountAuth() routes declarations into mounts pre-gating (declaring auth marks the mount gated + reviewed); a declared "none" can't un-gate a detected wrapper.
• entries: overrides sanitized once up front; declared-vs-detected status conflicts warn (declared wins).

2. ax init asks how agents authenticate

For each gated MCP server, a scheme select then targeted follow-ups:

• API key / bearer (the realistic common case): declares status "api_key", asks only for the docs URL where a human obtains a key.
• OAuth 2.0: asks authorization + token endpoints — prefilled when a committed RFC 8414 oauth-authorization-server document states them (new detect-auth-metadata detector; also surfaces authServerUrls literals from protectedResourceHandler routes — including under app/.well-known/, which the route walker skips as hidden — and RFC 9728 documents as context).
• Skip: asks nothing.

The default is OAuth only when the source tree shows OAuth evidence; otherwise skip — Enter-through never steers a basic-auth user into questions they can't answer, and never writes a declaration that wasn't an active choice. Answers are validated with the schema's own URL rule, so init can't write a config the next build rejects.

3. Report auth section

.ora/report.json gains a structured auth block: one entry per published gated surface (path, scheme, declared-vs-derived, endpoints present, docsUrl, and an actionable note when something's missing) plus the detected auth provider (@clerk/nextjs, better-auth, @auth0/nextjs-auth0, next-auth/@auth/core) with a durable note on what it means for agent auth. Deliberately no wiring snippets — provider APIs drift; the notes state stable facts and name the provider's own docs. next-auth's note steers to the api_key lane, since it signs humans in but exposes no authorization server agents can use.

Testing

• 48 new tests (712 total, all passing): sanitizer, override merge + conflict warnings, mount routing, schema loud-failures, end-to-end generateCatalog (catalog/card/auth.md/report.auth), auth-metadata detector (incl. comment scrubbing + hidden-dir route), provider detector, config rendering round-tripped through the real schema gate, and scripted-prompter init flows (oauth collect, prefill-approve, api_key, skip, docs-only, invalid-URL re-prompt, nothing-gated, evidence-based default).
• Verified with real CLI runs against a copy of the demo app: the wizard defaults to skip (no OAuth evidence), an active api_key choice + docs URL lands in ax.config, and the next build publishes it to the catalog, the server card, auth.md, and report.auth.

🤖 Generated with Claude Code