[luismeyer]

Stacked on #587 (luismeyer/kms-signed-overrides). Once #587 merges, this will be retargeted to main.

What / why

Lets v4 apps serve /.well-known/vercel/flags to Vercel without FLAGS_SECRET. verifyAccess now also accepts a short-lived JWS that Vercel KMS signs. The existing FLAGS_SECRET JWE proof path still works the same way.

• verifyAccess(authHeader, secret = process.env.FLAGS_SECRET): the signature is unchanged. It strips Bearer as before. If isVercelSignedToken says the token is a JWS the app can verify, the token goes to the KMS discovery verifier, whether or not FLAGS_SECRET is set. Any other token goes to verifyAccessProof as before.
• Without a secret, verifyAccess now returns false instead of throwing.
• vercel-platform.ts: the shared verifier verifyVercelSignedToken(token, issuer, policy) (with isVercelSignedToken, the per-issuer JWKS caches, header checks and isInScope). flag-overrides-platform.ts ([flags] accept Vercel-signed override tokens #587) calls it with FLAG_OVERRIDES_POLICY; the new flags-discovery-platform.ts holds VERCEL_FLAGS_DISCOVERY_ISSUER and FLAGS_DISCOVERY_POLICY, which verifyAccess passes in. Overrides behave the same as before: they still use the flags-explorer-issuer.
• Separate issuer for discovery: discovery tokens are verified against the new flags-keys-issuer (VERCEL_FLAGS_DISCOVERY_ISSUER). Both the toolbar and the internal flags-keys endpoint sign with it. There is one cached JWKS loader per issuer (${issuer}/jwks.json), so one issuer's keys never verify the other's tokens, and the iss claim must match exactly.
• SvelteKit createHandle: removed the if (!secret) return 401 guard in front of verifyAccess, so a no-secret app can serve discovery. The Next and SvelteKit createFlagsDiscoveryEndpoint needed no change. No other caller requires FLAGS_SECRET on the discovery path.

Token contract

• JWS, ES256, issuer flags-keys-issuer (VERCEL_FLAGS_DISCOVERY_ISSUER = https://kms.vercel.com/d0efbb30-566d-48b6-b173-0062e54ec49c). Overrides stay on flags-explorer-issuer https://kms.vercel.com/64af96a2-ba60-42ef-91af-459fcef6f864. The kid header is required. Tokens with jku, jwk, x5u or crit are rejected.
• iss, iat and exp are required, with aud: 'vercel:flags-discovery', pur: 'flags-discovery' and ver: 1.
• scope: { teamId, projectIds, environments } uses the same isInScope as overrides. The app's project must be in projectIds. The team must match when it is known (see teamId below). The app's environment must be in environments. Unknown keys are rejected.
• Max lifetime is 300s (exp - iat <= 300 and maxTokenAge 300), with 5s clock tolerance and a max token length of 16 KiB.
• Purpose binding: the discovery verifier rejects overrides tokens and the overrides verifier rejects discovery tokens. Both directions are tested.
• v5 (standard, src/overrides/vercel.ts), checked by reading the code: it rejects discovery tokens. jose checks audience: 'vercel:flag-overrides' exactly, pur === 'flag-overrides' is required, and an overrides object is required.

teamId cannot be enforced on deployments

isInScope only checks scope.teamId when the team is known. The only source is VERCEL_OIDC_TOKEN in process.env, which exists locally after vercel env pull and during builds. On a deployment at runtime, the OIDC token is only a per-request x-vercel-oidc-token header, not an env var. None of the Vercel system env vars (VERCEL_PROJECT_ID, VERCEL_ENV, VERCEL_TARGET_ENV, VERCEL_DEPLOYMENT_ID, VERCEL_URL, VERCEL_GIT_*, …) contains the team id. So on deployments the team is not checked. The project id is globally unique and comes from the host, never from the token. The project id and the environment still bind the token, and both are enforced. This is now documented in code at isInScope, and nothing was weakened: the team is still enforced whenever it is known.

Tests

packages/flags:

• pnpm type-check: ok
• pnpm check (biome): no issues
• pnpm test: 15 files, 228 tests passed
• pnpm build: ok
• pnpm attw: no problems found

New verify-access.test.ts (the JWKS fetch is mocked with a locally generated ES256 key):

• A valid token is accepted, both without and with a secret.
• Rejected tokens: expired, lifetime over 300s, wrong iss/aud/pur/ver, wrong key, HS256, jwk/jku header, overrides token, wrong project/env/team, extra scope key, unknown project.
• The overrides verifier rejects a discovery token.
• Issuer separation: a discovery token from the overrides issuer is rejected by verifyAccess, and an overrides token from the flags-keys issuer is rejected by verifyFlagOverridesFromPlatform, even when both JWKS serve the same key. Each issuer's keys are fetched from its own JWKS URL.
• Empty or malformed issuers reject everything and fetch no keys. Tests mock VERCEL_FLAGS_DISCOVERY_ISSUER with a test UUID issuer.
• The JWE proof works as before, with a secret passed in or from env; a proof made with a different secret is rejected.
• No secret with a JWE returns false without throwing.
• The Next endpoint returns 200/401 without FLAGS_SECRET.

sveltekit/without-secret.test.ts: createHandle and createFlagsDiscoveryEndpoint return 200 for a KMS token and 401 without one, all without a secret.

Open questions

• Should the team be read from the per-request x-vercel-oidc-token header (@vercel/request-context)? It would only add a restriction, but it isn't always present (OIDC can be disabled, and there are no headers at module scope). Its owner_id would also have to match what the signer puts in scope.teamId, for example on Hobby accounts. This PR doesn't do that.

• Behaviour change: verifyAccess without a secret used to throw and now returns false. Custom routes that relied on the throw now get a 401 instead of an error.

• Outside Vercel, without VERCEL/VERCEL_OIDC_TOKEN, a JWS still goes to the JWE path, as in [flags] accept Vercel-signed override tokens #587. That means local next dev without vercel env pull can't use KMS tokens.

• SvelteKit createFlagsDiscoveryEndpoint still falls back to process.env.FLAGS_SECRET rather than $env/static/private. That behaviour was already there and is unchanged.

Snapshot: flags@4.5.0-a5fdf7a-20261109093837, with the real issuer.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
flags-playground	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-dev	Error	v0	Nov 10, 2026 4:48pm UTC
flags-sdk-flagsmith	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-growthbook	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-launchdarkly	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-openfeature	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-posthog	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-reflag	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-snippets	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-statsig	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
flags-sdk-sveltekit-snippets	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
shirt-shop	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC
shirt-shop-api	Ready	Preview, v0	Nov 10, 2026 4:48pm UTC

[chriswdmr]

LGTM, nothing blocks this PR. Things to consider:

• Keep verifyAccess working where there is no process global (the cause is isVercelSignedToken from #587)
• Update the verifyAccess docs for the Vercel-signed token
• Warn one time when there is no secret outside Vercel

The rest are three questions about the tokens and three test nits.

[chriswdmr]

issue (non-blocking): verifyAccess throws when there is no process global

isVercelSignedToken reads process.env before it checks the token. In a runtime with no process global, verifyAccess(header, secret) now throws ReferenceError: process is not defined. On the base branch, the same call returns true for a valid proof. I ran the built package with process removed to confirm this.

The cause is in vercel-platform.ts from #587, so the fix can go there:

return (
  token.split('.').length === 3 &&
  typeof process !== 'undefined' &&
  Boolean(process.env?.VERCEL || process.env?.VERCEL_OIDC_TOKEN)
);

[chriswdmr]

suggestion (non-blocking): Update the verifyAccess docs

apps/docs/content/docs/api-reference/core/core.mdx still says that verifyAccess works "based on encrypted tokens (JWEs)". Can we add these points?

• The token which Vercel signs
• FLAGS_SECRET is optional on Vercel
• The result is false, not an error, when there is no secret

The createFlagsDiscoveryEndpoint section in next.mdx can use the same note. #586 did the same for encryptFlagValues.

[chriswdmr]

suggestion (non-blocking): Warn one time when there is no secret outside Vercel

Before, an app with no FLAGS_SECRET got a clear error. Now the caller gets a 401 with no hint. This applies in these cases:

• A self-hosted app with no FLAGS_SECRET
• Local development with no vercel env pull
• A project that does not expose the system environment variables

A one-time console.warn here would keep the hint. Use it only when there is no secret and the host cannot verify signed tokens (no VERCEL and no VERCEL_OIDC_TOKEN). Then a request with a random header on Vercel does not cause a wrong warning.

[chriswdmr]

question: Apps on an older flags version

An app on an older flags version that has FLAGS_SECRET treats a signed token as an encrypted proof, and responds with 401. Do such apps continue to get the encrypted proof?

[chriswdmr]

question: Is this audience only for discovery tokens?

The PR description says that more than one signer uses this issuer. The verifier keeps tokens apart only by aud, pur and ver. Can you confirm that only discovery tokens get aud: 'vercel:flags-discovery'?

[chriswdmr]

question: Custom environments

The host reads VERCEL_TARGET_ENV before VERCEL_ENV. On a custom environment, for example staging, a token with environments: ['preview'] is rejected, and only ['staging'] is accepted. I confirmed this with a local test. Does the token scope contain the name of the custom environment? If yes, a test case here would record that contract.

[chriswdmr]

nitpick (non-blocking): Use the real issuer

The real issuer id is now set, so this comment is stale. fetch is already stubbed, so the mock is not necessary. I removed the mock locally and used the real constant, and all 31 tests pass. Then the test uses the flags-keys issuer (line 239) can go too, because it only checks a constant. The same applies to sveltekit/without-secret.test.ts:23.

[chriswdmr]

nitpick (non-blocking): Test placement

The createFlagsDiscoveryEndpoint tests for Next.js fit better in src/next/index.test.ts. The test that calls verifyVercelSignedToken with an incorrect issuer (line 248) checks code from #587, so it fits better with the verifier tests there.

[chriswdmr]

nitpick (non-blocking): No test for maxTokenLength

I changed this value to 10 MB locally, and all tests continued to pass. The other values of this policy each have a test. One case with a token above 16 KiB would close the gap.