Skip to content

fix: validate JWT audience and issuer claims#41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alanzabihi wants to merge 1 commit into
base:main
Choose a base branch
from
Open

fix: validate JWT audience and issuer claims #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 20 additions & 14 deletions docs/environment-variables.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,25 +2,29 @@

On Supabase Platform and Local Development (CLI), all variables are auto-provisioned — no configuration needed

| Variable | Format | Description | Available in |
| --------------------------- | ---------------------------------- | -------------------------------------------- | --------------------------------- |
| `SUPABASE_URL` | `https://<ref>.supabase.co` | Your Supabase project URL | All |
| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object | All |
| `SUPABASE_SECRET_KEYS` | `{"default":"sb_secret_..."}` | Named secret keys as JSON object | All |
| `SUPABASE_JWKS` | `{"keys":[...]}` or `[...]` | Inline JSON Web Key Set for JWT verification | All |
| `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key (fallback) | Self-hosted, if manually exported |
| `SUPABASE_SECRET_KEY` | `sb_secret_...` | Single secret key (fallback) | Self-hosted, if manually exported |
| Variable | Format | Description | Available in |
| --------------------------- | ----------------------------------- | -------------------------------------------- | --------------------------------- |
| `SUPABASE_URL` | `https://<ref>.supabase.co` | Your Supabase project URL | All |
| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object | All |
| `SUPABASE_SECRET_KEYS` | `{"default":"sb_secret_..."}` | Named secret keys as JSON object | All |
| `SUPABASE_JWKS` | `{"keys":[...]}` or `[...]` | Inline JSON Web Key Set for JWT verification | All |
| `SUPABASE_JWT_AUDIENCE` | `https://<ref>.supabase.co` | Expected JWT `aud` claim (optional) | All |
| `SUPABASE_JWT_ISSUER` | `https://<ref>.supabase.co/auth/v1` | Expected JWT `iss` claim (optional) | All |
Comment on lines +11 to +12

@kallebysantoskallebysantosMay 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better keep it as non-default Supabase available.
Users need to manually supply it from env property when working in a Supabase Environment.

cc @tomaspozo, This envs are blockers if you consider merging it, like we discussed before I don't plan to expose it at Platform / any other Supabase environment.

@kallebysantoskallebysantosMay 16, 2026•
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be fine to merge without coupling this envs, so the feature JWT audience will be optional and requires manual setup.

@alanzabihi, are u okay with manual setup using env property? like I described in the comment above, the requirement of theses envs are blocking this PR.

@mandarinimandariniAug 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alanzabihi Agree with @kallebysantos. Audience and issuer should stay config-only, not auto-read from SUPABASE_JWT_AUDIENCE / SUPABASE_JWT_ISSUER. Those names sit next to Platform-provisioned vars. If Platform ever sets one, verification behavior would change with no code change on the user's end.

The overrides path in resolve-env.ts already covers this. Can you drop the getEnvVar fallbacks for both vars (and the matching wiring test), and update the docs so audience/issuer are only set through the env override?

Rest of the PR looks good. Can you also please rebase again, this shows conflicts.

| `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key (fallback) | Self-hosted, if manually exported |
| `SUPABASE_SECRET_KEY` | `sb_secret_...` | Single secret key (fallback) | Self-hosted, if manually exported |

## Non-Supabase environments (Node.js, Bun, Cloudflare, self-hosted)

Set these based on which auth modes your app uses:

| Variable | Required when |
| -------------------------------------- | ----------------------------------------- |
| `SUPABASE_URL` | Always |
| `SUPABASE_SECRET_KEY` | `auth: 'secret'` or using `supabaseAdmin` |
| `SUPABASE_PUBLISHABLE_KEY` | `auth: 'publishable'` |
| `SUPABASE_JWKS` or `SUPABASE_JWKS_URL` | `auth: 'user'` (JWT verification) |
| Variable | Required when |
| -------------------------------------- | ------------------------------------------ |
| `SUPABASE_URL` | Always |
| `SUPABASE_SECRET_KEY` | `auth: 'secret'` or using `supabaseAdmin` |
| `SUPABASE_PUBLISHABLE_KEY` | `auth: 'publishable'` |
| `SUPABASE_JWKS` or `SUPABASE_JWKS_URL` | `auth: 'user'` (JWT verification) |
| `SUPABASE_JWT_AUDIENCE` | Optional - restricts accepted JWT audience |
| `SUPABASE_JWT_ISSUER` | Optional - restricts accepted JWT issuer |

### Minimal `.env` example

Expand DownExpand Up@@ -193,6 +197,8 @@ interface SupabaseEnv {
secretKeys: Record<string, string>
// `URL` when SUPABASE_JWKS is a remote endpoint, `JsonWebKeySet` for inline keys
jwks: JsonWebKeySet | URL | null
audience?: string
issuer?: string
}
```

Expand Down
8 changes: 6 additions & 2 deletions docs/security.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -55,11 +55,15 @@ JWT verification in `user` mode works as follows:
1. The `Authorization: Bearer <token>` header is extracted from the request
2. The token is verified against the JWKS from the `SUPABASE_JWKS` environment variable
3. Verification uses `jose`'s `jwtVerify` with a **local** key set — there are no network calls to a JWKS endpoint
4. The token must contain a `sub` (subject) claim to be considered valid
5. On success, the decoded claims are available as `ctx.userClaims` and `ctx.jwtClaims`
4. If `SUPABASE_JWT_AUDIENCE` is set, the token's `aud` claim must match
5. If `SUPABASE_JWT_ISSUER` is set, the token's `iss` claim must match
6. The token must contain a `sub` (subject) claim to be considered valid
7. On success, the decoded claims are available as `ctx.userClaims` and `ctx.jwtClaims`

If JWKS is not configured (`SUPABASE_JWKS` is missing or malformed), `user` mode is unavailable and will always reject requests.

**Audience and issuer validation.** In setups where multiple services share the same signing keys, a JWT minted by one service could be accepted by another. Setting `SUPABASE_JWT_AUDIENCE` and `SUPABASE_JWT_ISSUER` prevents this by rejecting tokens that weren't issued for your specific service. Both are optional for backward compatibility but recommended in multi-service deployments.

**No silent downgrade.** When `user` is combined with other modes (e.g. `auth: ['user', 'publishable']`), a JWT that is present but fails verification rejects the request with `InvalidCredentialsError` — it does not fall through to the next mode. This prevents a bad token paired with a valid `apikey` (or with `'none'`) from being silently downgraded to a less-privileged auth mode. Requests that simply omit the `Authorization` header still fall through as expected.

## CORS handling
Expand Down
12 changes: 12 additions & 0 deletions src/core/resolve-env.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -22,6 +22,18 @@ describe('resolveEnv', () => {
expect(result.data!.url).toBe('https://test.supabase.co')
})

it('reads optional JWT audience and issuer from process.env', () => {
vi.stubEnv('SUPABASE_URL', 'https://test.supabase.co')
vi.stubEnv('SUPABASE_JWT_AUDIENCE', 'https://test.supabase.co')
vi.stubEnv('SUPABASE_JWT_ISSUER', 'https://test.supabase.co/auth/v1')

const result = resolveEnv()

expect(result.error).toBeNull()
expect(result.data!.audience).toBe('https://test.supabase.co')
expect(result.data!.issuer).toBe('https://test.supabase.co/auth/v1')
})

it('parses JSON publishable keys', () => {
vi.stubEnv('SUPABASE_URL', 'https://test.supabase.co')
vi.stubEnv(
Expand Down
2 changes: 2 additions & 0 deletions src/core/resolve-env.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -177,6 +177,8 @@ export function resolveEnv(
overrides?.secretKeys ??
resolveKeys('SUPABASE_SECRET_KEY', 'SUPABASE_SECRET_KEYS'),
jwks: overrides?.jwks ?? resolveJwks(),
audience: overrides?.audience ?? getEnvVar('SUPABASE_JWT_AUDIENCE'),
issuer: overrides?.issuer ?? getEnvVar('SUPABASE_JWT_ISSUER'),
}

return { data, error: null }
Expand Down
69 changes: 67 additions & 2 deletions src/core/verify-credentials.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -277,11 +277,13 @@ describe('verifyCredentials', () => {

describe('user mode', () => {
let jwks: JsonWebKeySet
let privateKey: CryptoKey
let validToken: string

beforeAll(async () => {
const { privateKey, publicKey } = await generateKeyPair('RS256')
const publicJwk = await exportJWK(publicKey)
const keyPair = await generateKeyPair('RS256')
privateKey = keyPair.privateKey
const publicJwk = await exportJWK(keyPair.publicKey)
publicJwk.alg = 'RS256'
publicJwk.use = 'sig'
jwks = { keys: [publicJwk] }
Expand DownExpand Up@@ -312,6 +314,69 @@ describe('verifyCredentials', () => {
expect(result.data!.token).toBe(validToken)
})

it('succeeds when JWT audience and issuer match configured values', async () => {
const token = await new SignJWT({ sub: 'user-123' })
.setProtectedHeader({ alg: 'RS256' })
.setAudience('https://test.supabase.co')
.setIssuer('https://test.supabase.co/auth/v1')
.setIssuedAt()
.setExpirationTime('1h')
.sign(privateKey)

const result = await verifyCredentials(
{ token, apikey: null },
{
auth: 'user',
env: makeEnv({
jwks,
audience: 'https://test.supabase.co',
issuer: 'https://test.supabase.co/auth/v1',
}),
},
)

expect(result.error).toBeNull()
expect(result.data!.jwtClaims!.aud).toBe('https://test.supabase.co')
expect(result.data!.jwtClaims!.iss).toBe(
'https://test.supabase.co/auth/v1',
)
})

it.each([
[
'audience',
'https://wrong.supabase.co',
'https://test.supabase.co/auth/v1',
],
[
'issuer',
'https://test.supabase.co',
'https://wrong.supabase.co/auth/v1',
],
])(
'fails when configured JWT %s does not match',
async (_label, audience, issuer) => {
const token = await new SignJWT({ sub: 'user-123' })
.setProtectedHeader({ alg: 'RS256' })
.setAudience('https://test.supabase.co')
.setIssuer('https://test.supabase.co/auth/v1')
.setIssuedAt()
.setExpirationTime('1h')
.sign(privateKey)

const result = await verifyCredentials(
{ token, apikey: null },
{
auth: 'user',
env: makeEnv({ jwks, audience, issuer }),
},
)

expect(result.error).not.toBeNull()
expect(result.error!.code).toBe(InvalidCredentialsError)
},
)

it('fails with invalid JWT', async () => {
const creds: Credentials = { token: 'invalid.jwt.token', apikey: null }
const result = await verifyCredentials(creds, {
Expand Down
6 changes: 5 additions & 1 deletion src/core/verify-credentials.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import {
createRemoteJWKSet,
jwtVerify,
type JWTVerifyGetKey,
type JWTVerifyOptions,
} from 'jose'

import { AuthError, Errors, InvalidCredentialsError } from '../errors.js'
Expand DownExpand Up@@ -211,7 +212,10 @@ async function tryMode(
if (!env.jwks) return null
try {
const jwkSet = getJwksResolver(env.jwks)
const { payload } = await jwtVerify(credentials.token, jwkSet)
const options: JWTVerifyOptions = {}
if (env.audience) options.audience = env.audience
if (env.issuer) options.issuer = env.issuer
const { payload } = await jwtVerify(credentials.token, jwkSet, options)
if (typeof payload.sub !== 'string') {
return INVALID
}
Expand Down
12 changes: 12 additions & 0 deletions src/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -101,6 +101,18 @@ export interface SupabaseEnv {
* `null` rather than falling through to the other variable.
*/
jwks: JsonWebKeySet | URL | null

/**
* Expected JWT audience (`aud` claim). When set, tokens with a different
* audience are rejected. Sourced from `SUPABASE_JWT_AUDIENCE`.
*/
audience?: string

/**
* Expected JWT issuer (`iss` claim). When set, tokens from a different
* issuer are rejected. Sourced from `SUPABASE_JWT_ISSUER`.
*/
issuer?: string
}

/**
Expand Down