docs: clarify bare auth mode matches only the default key

[tomaspozo]

What

Makes key resolution explicit across the docs:

• Bare auth: 'publishable' / auth: 'secret' match only the default key in SUPABASE_PUBLISHABLE_KEYS / SUPABASE_SECRET_KEYS. Use secret:<name> to target another key, or the wildcard secret:* to accept any key.
• createAdminClient() / createContextClient() follow a different rule — documented here for the first time.

Why

This behavior was documented inconsistently. Two spots were factually wrong — they claimed bare secret accepts any key — and most tables/TSDoc omitted the detail entirely, so auth: 'secret' reads as "any secret key" unless you dig into src/core/verify-credentials.ts (const name = keyName ?? 'default').

An audit for the same class of gap then surfaced a second one: the client factories resolve keys differently from the auth modes, and no doc or TSDoc said so.

Changes (docs/TSDoc only — no runtime change)

Auth modes

• Fix incorrect statements claiming bare secret accepts any key: docs/security.md, skills/supabase-server/SKILL.md.
• Name the default key in every auth-mode table: README.md, docs/auth-modes.md, docs/security.md, src/index.ts TSDoc.
• Close the publishable/secret asymmetry: the Secret mode section gained the default-key sentence Publishable already had; the Publishable section now mentions publishable:*, mirroring Secret's secret:*.
• Clarify type TSDoc: AuthMode / AuthModeWithKey in src/types.ts now state the bare form resolves default.

Client factories

• Document which key createAdminClient / createContextClient use (src/core/create-admin-client.ts, src/core/create-context-client.ts, docs/core-primitives.md):

  • auth.keyName set → that named key (throws if missing)
  • keyName omitted → the default key, falling back to the first key in the set when no default exists

  This deliberately differs from the secret / publishable auth modes, which match default only and never fall back. It's intentional, tested behavior (create-admin-client.test.ts:105, create-context-client.test.ts:123) that no doc mentioned — each new note calls out the contrast explicitly.

Verification

• pnpm typecheck, pnpm lint clean; all 196 tests pass.
• pnpm run docs (TypeDoc) resolves all links — the only remaining warning is a pre-existing env highlight-language one in environment-variables.md.
• No "any key" phrasing remains attached to a bare mode — all such wording now sits under the :* wildcard.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@104

commit: 3808f17

[mandarini]

LGTM overall. One small asymmetry that's still open, given the PR's own goal of reconciling the publishable/secret docs: in docs/auth-modes.md, the new sentence under Secret mode now calls out the wildcard

Use named key syntax to target a specific key or secret:* to accept any key (see below).

but the parallel sentence under Publishable mode (line 82, not touched by this PR) still doesn't mention publishable:*:

Use named key syntax to target a specific key (see below).

Since publishable:* is equally valid (per src/types.ts and docs/security.md), and this PR exists specifically to close this kind of gap, could we add the same wildcard callout there too? Non-blocking for sure.