feat: add withRequiredClaims user-mode auth gate

[mandarini]

Adds withRequiredClaims, the user-mode auth gate. Implements SDK-1614.

What

• New defineMiddleware entry at @supabase/server/middleware/required-claims. It verifies the Bearer token against the project JWKS (the same core as withSupabase's user mode) and contributes non-nulljwtClaims: JWTClaims.
• Missing token, or an sb_* API key in the Authorization slot: 401 INVALID_CREDENTIALS, handler never runs. Invalid token: the same 401. Token present but no JWKS: 500 ENV_ERROR. The token check runs before JWKS resolution, so a token-less request 401s even on a misconfigured project.
• Keyed on jwtClaims, so composing it with withClaims, or inside withSupabase's middleware: array, is a compile-time conflict. Type tests pin both, plus pipeline([withRequiredClaims(), withPostgresClient()], h) compiling with non-null ctx.jwtClaims.
• Docs: new api-reference section; the gate callouts from docs: state that withClaims is not an auth gate #125 (withClaims docstring, api-reference, postgres.md) now point at this entry instead of the hand-wrapped withSupabase workaround.

Why

• withClaims is not a gate: token-less requests proceed as anonymous (SDK-1604). Migrating an auth-gated endpoint to [withClaims(), withSupabaseClient()] compiles, passes a logged-in smoke test, and silently accepts anonymous callers. This entry closes that trap on the user-JWT side.
• A required: true flag on withClaims cannot deliver non-null types because a middleware's contribution type is fixed, and the hand-wrapped withSupabase entry infers Entry<string, object, unknown>, which poisons pipeline typing for every entry after it. A separate typed entry is the fix.
• Naming: withRequiredClaims reads against withClaims as "claims required" vs "claims if present". withAuth stays free for the post-launch multi-mode gate (SDK-1596), which contributes a different shape.

[pkg-pr-new]

Open in StackBlitz

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

commit: 4a88731