* fix: reject invalid JWTs immediately instead of falling through to next auth mode
Introduce an INVALID sentinel so tryMode can distinguish "credential
present but failed" from "credential absent." The main loop now short-
circuits on INVALID instead of silently trying the next allowed mode.
Also covers the case where a JWT verifies cryptographically but has no
sub claim (or sub isn't a string) -- previously returned null (fallthrough),
now returns INVALID (reject).
BREAKING CHANGE: when multiple auth modes are allowed, a present-but-invalid
JWT is now rejected with InvalidCredentialsError instead of falling through
to the next mode. Clients that previously relied on silent fallthrough
(e.g., stale token + valid apikey) must now either omit the Authorization
header or refresh the token.
* docs: clarify invalid-JWT no-fallthrough semantics
Align documentation with the behavior introduced in the fix!: commit on
this branch. Make clear across user-facing docs, TSDoc, and SKILL that:
- A mode is "tried" only when its credential is actually present, so a
request with no Authorization header still falls through.
- A JWT that is present but fails verification (malformed, expired, wrong
signature, missing sub) rejects with InvalidCredentialsError — it does
not silently fall through to another allowed mode.
Touches README, docs/auth-modes, docs/security, docs/error-handling,
docs/api-reference, skills/supabase-server/SKILL, and TSDoc on the Allow
type, WithSupabaseConfig.allow, and verifyCredentials.
---------
Co-authored-by: Tomas Pozo <tomaspozogarzon@gmail.com>
* docs: add initial documentation and skills.md
* docs: apply formatting
* docs: update SKILL.md to resolve docs from package location and ship docs with npm
SKILL.md now instructs agents to find documentation in the installed
@supabase/server package (node_modules or repo root) instead of using
relative paths. Added docs/ and SKILL.md to package.json files array
so they ship with npm installs.
* docs: add missing HTTPException import in error-handling example
* docs: fix strictNullChecks issues, duplicate variables, and missing context in examples
- Add non-null assertions (!) after error guards where TS can't narrow
destructured result tuples
- Split duplicate variable declarations into separate code blocks
- Add missing imports and show where variables like `auth` come from
- Keep { data, error } destructuring pattern consistent with SDK convention
* docs: reframe as runtime-agnostic and add env auto-injection details
- getting-started: replace Edge Function framing with runtime-neutral
language, explain module worker pattern works across Deno/Bun/Workers,
add Runtimes section covering all supported environments
- webhooks: replace Deno.env with process.env for portable examples
- environment-variables: add "Auto-injected in" column distinguishing
Platform vs Local CLI, reframe section headers
- auth-modes: clean up example key values
- core-primitives: clarify "Integration with frameworks" wording
- types: simplify TSDoc for publishable/secret key descriptions
* docs: add SSR frameworks guide and update references
Add docs/ssr-frameworks.md covering the pattern for using core
primitives in Next.js, SvelteKit, Nuxt, and Remix — cookie extraction,
env bridging, JWKS caching, and a complete Next.js adapter example.
Replace the basic SSR example in core-primitives.md with a pointer
to the new dedicated doc. Add SSR row to SKILL.md routing table.
* docs: add disclaimer of new package
* docs: extend explanation on keys env vars
* docs: add platform-specific quick starts to SKILL.md
Split the single generic example into per-platform sections
(Edge Functions, Cloudflare Workers, Hono, SSR Frameworks) so
AI agents pick the correct import specifier for each runtime.
Adds npm: prefix to all Deno examples and a Deno column to the
entry points table. Also adds createSupabaseContext examples.
* docs: add server-to-server quick starts and allow:always guardrails
Add secret key auth and webhook signature verification quick starts
to SKILL.md. Add explicit decision tree for allow:'always' so AI
agents confirm with the user before leaving endpoints unprotected.
* docs: add legacy keys warning, skills install, remove webhook docs
- Add legacy keys warning to SKILL.md (avoid anon/service_role keys)
- Add AI coding skills install section to README
- Add server-to-server quick start with caller code to README
- Add runtimes, documentation table, and named secret keys to README
- Remove verifyWebhookSignature references from all docs
- Delete docs/webhooks.md (code removal in separate PR)
* docs: add verify_jwt = false note for non-user auth modes
Edge Functions require verify_jwt = false in config.toml when
using allow: public, secret, or always — otherwise the platform
rejects requests before the handler runs.
* docs: add edge function recipes and refactor env vars doc
Add recipes for function-to-function calls, pg_net from database,
Stripe webhooks, and generic webhook signature verification.
Document the @supabase/server/wrappers entry point.
Refactor environment-variables.md into Supabase vs non-Supabase sections.
* docs: add security doc covering timing-safe comparison, auth model, CORS
* docs: link auth-modes timing-safe mentions to security.md
* docs: adding 'local cli' to secrets table
This envs will be injected from cli too
* docs: setting Deno as first installation choice
* docs: adding 'verify_jwt=false' disclaimer for non-user auth
* docs: split Deno/Supabase runtime section, merge Deno/Node/Bun
* docs(skills): adding legacy code migration example
* docs(skills): explaining why legacy code should be migrated
* docs: rewrite migration section, improve skill description triggers
---------
Co-authored-by: Kalleby Santos <kalleby_santos@hotmail.com>
Ismail Pelaseyed