feat(auth): jwt signing keys (#531)

Author: larbish

demo/README.md

@@ -6,7 +6,7 @@ Live demo: https://supabase-demo-gamma.vercel.app
 
 - Frontend:
   - [Nuxt 3](https://nuxt.com/) - The Vue Framework for Web Architects
-  - [Nuxt UI Pro](https://ui.nuxt.com/) for components
+  - [Nuxt UI](https://ui.nuxt.com/) for components
   - [TailwindCSS](https://tailwindcss.com/) for styling and layout.
   - [Supabase Module](https://github.com/nuxt-modules/supabase) for user management and supabase data client.
 - Backend:
@@ -72,9 +72,6 @@ pnpm dev
 
 ## Production
 
-> [!WARNING]
-> This project uses [Nuxt UI Pro](https://ui.nuxt.com/pro), you need a license to deploy it in production. However, you can use it for free in development.
-
 Build the application for production:
 
 ```bash

demo/app.config.ts

@@ -11,8 +11,6 @@ export default defineAppConfig({
         },
       },
     },
-  },
-  uiPro: {
     header: {
       slots: {
         root: 'border-none',

demo/assets/css/main.css

@@ -1,8 +1,8 @@
 @import "tailwindcss";
-@import "@nuxt/ui-pro";
+@import "@nuxt/ui";
 
 :root {
   --ui-header-height: 40px;
 
   --ui-container: 100%;
-}
+}

demo/nuxt.config.ts

@@ -1,6 +1,6 @@
 // https://nuxt.com/docs/api/configuration/nuxt-config
 export default defineNuxtConfig({
-  modules: ['@nuxt/eslint', '@nuxt/ui-pro', '@nuxtjs/supabase'],
+  modules: ['@nuxt/eslint', '@nuxt/ui', '@nuxtjs/supabase'],
   devtools: { enabled: true },
   css: ['~/assets/css/main.css'],
   compatibilityDate: '2025-05-15',

docs/content/1.getting-started/1.introduction.md

@@ -31,7 +31,7 @@ Add `SUPABASE_URL` and `SUPABASE_KEY` to the `.env`:
 
 ```bash [env]
 SUPABASE_URL="https://example.supabase.co"
-SUPABASE_KEY="<your_key>"
+SUPABASE_KEY="<your_publishable_key>"
 ```
 
 ::tip
@@ -61,12 +61,30 @@ The unique Supabase URL which is supplied when you create a new project in your
 
 Default: `process.env.SUPABASE_KEY`
 
-Supabase 'anon key', used to bypass the Supabase API gateway and interact with your Supabase database making use of user JWT to apply RLS Policies.
+Supabase `publishable key`, used to verify and decode the JWT. Can bypass the Supabase API gateway and interact with your Supabase database applying RLS Policies.
 
-### `serviceKey`
+::note{to="https://supabase.com/blog/jwt-signing-keys"}
+In `v1.x.x` and earlier, this was referring to the `anon key`. With the introduction of JWT signing keys, Supabase now needs a "publishable key" to decode the JWT and let you interact with your database.
+::
+
+### `secretKey`
+
+Default: `process.env.SUPABASE_SECRET_KEY`
+
+Supabase `secret key`, has super admin rights and can bypass your Row Level Security.
+
+::warning
+This key should be kept secret and never exposed to the client. Keep it in environment variables.
+::
+
+### `serviceKey` :u-badge{label="Deprecated" color="warning"}
 
 Default: `process.env.SUPABASE_SERVICE_KEY`
 
+::warning{to="https://supabase.com/blog/jwt-signing-keys"}
+*Legacy API key* used before signing JWT keys were introduced. Use `secretKey` instead. This option will be removed in a future version.
+::
+
 Supabase 'service role key', has super admin rights and can bypass your Row Level Security.
 
 ### `useSsrCookies`

docs/content/1.getting-started/4.migration.md

@@ -0,0 +1,138 @@
+---
+title: Migration Guide 
+description: Learn how to migrate @nuxtjs/supabase to take advantage of JWT signing keys support
+navigation:
+  title: Migration
+---
+
+This guide will help you migrate from `v1.x` to `v2.x`, which introduces support for Supabase's new JWT signing keys.
+
+## 🔐 What are JWT Signing Keys?
+
+Supabase has introduced a major security improvement by moving from symmetric to asymmetric JWT (JSON Web Token) signing. This change brings security and performance improvements in how your applications handle authentication.
+
+### The Problem with Symmetric Keys
+
+Previously, Supabase used a single shared secret key for both creating and verifying tokens. This meant your app had to constantly call `supabase.auth.getUser()` to check if sessions were valid, creating network delays calling the Supabase Auth server.
+
+### The Solution with Asymmetric JWT Signing Keys
+The new system uses two separate keys: 
+- A private key (kept secure by Supabase) for creating tokens.
+- A public key (safe to share in your application) for verifying them.
+
+Your application can now verify user sessions locally without contacting Supabase servers, making it faster and more reliable. This new key is named as `publishable key` on Supabase.
+
+### Key Benefits
+
+This upgrade eliminates authentication bottlenecks, improves security, and makes your applications work better at the edge (no extra calls to the Supabase Auth server).
+
+::note{to="https://supabase.com/blog/jwt-signing-keys"}
+Read the full technical explanation in the official Supabase blog post.
+::
+
+## 🚨 Breaking changes
+
+### 1. `useSupabaseUser` Type Changes
+
+`useSupabaseUser` now returns **JWT claims** instead of the full **User object**.
+
+- **Before (v1.x):** `useSupabaseUser` returned the full `User` object from [auth.getUser()](https://supabase.com/docs/reference/javascript/auth-getuser)
+- **After (v2.x):** `useSupabaseUser` returns `Claims` object from [auth.getClaims()](https://supabase.com/docs/reference/javascript/auth-getclaims) as a [JWT Payload](https://supabase.com/docs/guides/auth/jwts)
+
+::code-group
+```json [auth.getUser() as .json]
+{
+  id: "11111111-1111-1111-1111-111111111111",
+  aud: "authenticated",
+  role: "authenticated",
+  email: "[email protected]",
+  email_confirmed_at: "2024-01-01T00:00:00Z",
+  phone: "",
+  confirmed_at: "2024-01-01T00:00:00Z",
+  last_sign_in_at: "2024-01-01T00:00:00Z",
+  app_metadata: {},
+  user_metadata: {},
+  identities: []
+}
+```
+
+```json [auth.getClaims().claims as .json]
+{
+  session_id: "11111111-1111-1111-1111-111111111111",
+  sub: "11111111-1111-1111-1111-111111111111",
+  aud: "authenticated",
+  role: "authenticated",
+  email: "[email protected]",
+  aal: "aal1",
+  amr: [],
+  exp: 1715769600,
+  iat: 1715766000,
+  is_anonymous: false,
+  iss: "https://project-id.supabase.co/auth/v1",
+  phone: "+13334445555",
+  app_metadata: {},
+  user_metadata: {},
+  // identities is missing
+  // last_sign_in_at is missing
+  // confirmed_at is missing
+  // email_confirmed_at is missing
+}
+```
+::
+
+::tip
+If you need the full User object, you'll need to explicitly call `auth.getUser()` but if you only need basic info (email, role...) no changes are required.
+::
+
+
+### 2. Environment variables changes
+
+**Remaining key** → **`SUPABASE_KEY`** is now storing the `publishable key` instead of the `anon key`
+
+**New key** → **`SUPABASE_SECRET_KEY`** is now storing the `secret key` of your Supabase project
+
+**Deprecated key** → **`SUPABASE_SERVICE_KEY`** was previously storing the `service_role key` but is now deprecated in favor of `SUPABASE_SECRET_KEY`
+
+## 📋 Migration Steps
+
+### 1. Types changes
+
+The first thing you need to do is to ensure the `useSupabaseUser` changes do not affect your existing code.
+
+::tip
+Once you've updated the types, you can already test your application and it should still work as expected.
+::
+
+### 2. Environment variables changes
+
+The **Good news** ☀️ is that everything will continue to work as-is with your existing `SUPABASE_KEY` (aka `anon key`). 
+
+Same for `SUPABASE_SERVICE_KEY`, if you're using it to bypass Row Level Security, you will face a deprecation warning but it will still work.
+
+::warning{to="https://supabase.com/blog/jwt-signing-keys"}
+However, we highly recommend you to enable JWT signing keys in your Supabase project and use your publishable key as `SUPABASE_KEY` and your secret key as `SUPABASE_SECRET_KEY`.
+::
+
+#### 2.a. Enable JWT Signing Keys in Supabase Dashboard
+
+Before migrating your environment variables, you need to enable JWT signing keys and thus create your JWT and API keys in your Supabase project:
+
+<iframe
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/rwnOal_xRtM"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowfullscreen
+></iframe>
+
+::tip
+**Watch this video tutorial** from **6:20 to 12:20** to understand how to enable JWT signing keys in your Supabase dashboard and get your new secret key.
+::
+
+#### 2.b. Use your new keys in your `.env` file
+
+```bash [.env]
+SUPABASE_KEY=<your_publishable_key>
+SUPABASE_SECRET_KEY=<your_secret_key>
+```

docs/content/3.services/2.serverSupabaseServiceRole.md

@@ -14,7 +14,7 @@ This function is designed to work only in [server routes](https://nuxt.com/docs/
 
 It works similary as the [serverSupabaseClient](/services/serversupabaseclient) but it provides a client with super admin rights that can bypass your [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security).
 
-> The client is initialized with the `SUPABASE_SERVICE_KEY` you must have in your `.env` file. Checkout the doc if you want to know more about [Supabase keys](https://supabase.com/docs/learn/auth-deep-dive/auth-deep-dive-jwts#jwts-in-supabase).
+> The client is initialized with the `SUPABASE_SECRET_KEY` (recommended) or `SUPABASE_SERVICE_KEY` (deprecated) you must have in your `.env` file. We recommend using the new JWT signing keys (`SUPABASE_SECRET_KEY`) as described in the [Supabase blog post](https://supabase.com/blog/jwt-signing-keys).
 
 Define your server route and just import the `serverSupabaseServiceRole` from `#supabase/server`.
 

docs/content/index.md

@@ -10,8 +10,7 @@ seo:
 ---
 orientation: horizontal
 ---
-  :::prose-pre{filename="pages/login.vue"}
-  ```vue
+  ```vue [pages/login.vue]
   <script setup lang="ts">
   const supabase = useSupabaseClient()
   const email = ref('')
@@ -32,7 +31,6 @@ orientation: horizontal
     />
   </template>
   ```
-  :::
 
 #title
 [Nuxt]{.text-primary} Supabase
@@ -61,6 +59,11 @@ A supa simple wrapper around supabase-js to enable usage and integration within
   ---
   Star on GitHub
   :::
+
+#headline
+  :::u-button{size="sm" to="/getting-started/migration" variant="outline"}
+   Nuxt Supabase v2 →
+  :::
 ::
 
 ::u-page-section
@@ -125,10 +128,10 @@ Shipped with many features
   to: /getting-started/authentication
   ---
   #title
-  Authentication support
+  Authentication support with JWT signing keys
 
   #description
-  Secure your applications with authentication support provided by Supabase.
+  Secure your applications with authentication support provided by Supabase with JWT signing keys support.
   :::
 
   :::u-page-feature

docs/package.json

@@ -8,8 +8,8 @@
   },
   "devDependencies": {
     "@nuxtjs/plausible": "2.0.1",
-    "better-sqlite3": "^12.2.0",
-    "docus": "^4.1.2"
+    "better-sqlite3": "^12.4.1",
+    "docus": "^5.0.0"
   },
-  "packageManager": "pnpm@10.15.1"
+  "packageManager": "pnpm@10.17.1"
 }