feat(core): declarative auth descriptors — ADR 0020

[rejifald]

Implements ADR 0020 — auth accepts a declarative AuthDescriptor alongside the strategy factories — across all three proposed rollout steps, as three commits.

What changed

1 · Core (feat(core): declarative auth descriptors)

• StitchConfig.auth now accepts AuthStrategy | AuthDescriptor (exported as AuthConfig). A descriptor is a flat discriminated union on strategy: { strategy: 'apiKey', in: 'cookie', name: 'sid', value: env('KEY') } resolves to exactly what apiKey({ … }) builds — same wire behaviour, no factory import. Both forms are first-class and permanent.
• Detection (Q6): apply fn ⇒ live strategy (wins even alongside strategy); else strategy key ⇒ descriptor; else throw at construction.
• Atomic extends slot (Q7): auth stops flowing through deepMerge (which would blend two strategies field-by-field — a latent bug) and becomes last-writer-wins like store/kind; the winner is normalized once, after extends resolves and before __config is built, so a descriptor's secret leaves never reach the strict-JSON __config.
• Folded in refactor(auth)!: apiKey — symmetric name+in triad (header/query/cookie) #485's symmetric apiKey: the ADR builds on apiKey({ in: 'header'|'query'|'cookie', name, value }), but refactor(auth)!: apiKey — symmetric name+in triad (header/query/cookie) #485 wasn't merged — so this extends the factory to that shape (incl. in: 'cookie'), keeping the legacy header alias working. If refactor(auth)!: apiKey — symmetric name+in triad (header/query/cookie) #485 lands separately, the two need reconciling.

2 · Docs (docs(auth): …) — a descriptor variant beside the factory snippet in every auth guide, a "Declarative descriptors" section in the reference, and the symmetric/cookie apiKey shape documented. All ts twoslash blocks type-check against the real exports.

3 · from-curl (feat(core): from-curl scaffolds auth as a declarative descriptor) — stitch from-curl emits auth: { strategy: '…', … } (pure data; imports only stitch + env, no strategy factory). export --openapi already emits descriptor-shaped JSON, and no OpenAPI→source gen command exists yet, so from-curl is the only source emitter to switch.

Bundle (the load-bearing design decision)

Naively importing the resolver into stitch.ts dragged all five factories (incl. heavy oauth2/cookieSession) into the lean import { stitch } path — for every consumer, even no-auth ones. Fix: a resolver seam (packages/core/src/auth-registry.ts) holding the detection + a resolver slot; auth.ts keeps fromDescriptor (which references the factories) and arms the seam from the secret resolvers (env/secretsFile/secretFrom) — which a real descriptor's credential runs eagerly — not as a module-load side effect (esbuild would keep that and re-bloat the path). A bare import { stitch } with no auth therefore tree-shakes the factories away; only the small on-core-path detection seam remains. A literal-secret descriptor with no auth import throws a clear construction error (pinned by auth-descriptor-unarmed.spec.ts).

Budget bumped in bundle-size.mjs — the factories' weight does not hit import { stitch }:

scenario	before (main)	after	Δ	old budget → new
import { stitch }	19.82 KB	20.04 KB	+0.22 KB	20.00 → 20.25
whole entry	24.62 KB	25.07 KB	+0.45 KB	24.80 → 25.30

(A naive in-core resolver would have been +2.45 KB / 22.27 KB on import { stitch } — 2.27 KB over. The seam avoids that.) Advertised sizes stay ~25/~20 KB, so the yakir advertised-size tether is unaffected. AuthConfig joins the P3 *Config carve-out (it's the config-slot union, not an options bag).

Deliberate deviation from the ADR

ADR Q1's belt-and-suspenders "add value/token/clientSecret to the trace secret stems" — not done for value. token/secret (→clientSecret) are already stems; but the shared stem set also drives redactSecretsDeep over request bodies on every start frame, so a value stem would redact legitimate body fields for no gain — a descriptor is config.auth, never body data, and redactConfig strips auth wholesale regardless. Reasoned in a code comment near AuthConfig.

Validation

Local: full core suite (1236 passing), check:types + check:types-d (tsd), eslint, prettier, check:contract, check:exports, check:size (within budget), and fumadocs-mdx twoslash over every edited doc block. build:typed-deps builds all 7 integration packages against the new AuthConfig (non-breaking, monorepo-wide). The full pre-push/CI gate (whole-tree pnpm test + build-docs) runs here.

Note: this branch's worktree had two pre-existing, unrelated environmental gaps — a stale packages/core/lib/ (fixed by a rebuild) and a missing twoslash devDep (fixed by pnpm install); neither is caused by these changes.

🤖 Generated with Claude Code