Skip to content

[flags] precompute without FLAGS_SECRET via the deployment key - #597

Draft
luismeyer wants to merge 20 commits into
luismeyer/kms-flags-discoveryfrom
luismeyer/precompute-deployment-key
Draft

luismeyer wants to merge 20 commits into
luismeyer/kms-flags-discoveryfrom
luismeyer/precompute-deployment-key

Conversation

@luismeyer

@luismeyer luismeyer commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Stacked on #589 (luismeyer/kms-flags-discovery).

What / why

Precompute is the last v4 feature which throws without FLAGS_SECRET. With this change, the precompute functions fall back to a key derived from VERCEL_DEPLOYMENT_KEY when there is no secret.

  • New lib/precompute-secret.ts: deploymentPrecomputeSecret() derives 32 bytes with HKDF-SHA-256 (Web Crypto, so it works in the Edge runtime) and the info flags:precompute:v1. The derived key is not the deployment key itself, so precompute does not share a key with other users of VERCEL_DEPLOYMENT_KEY.
  • Order: the secret argument, then FLAGS_SECRET, then FLAGS_PRECOMPUTE_SECRET (new, the name which standard uses), then the deployment key. With a secret argument or a FLAGS_SECRET, nothing changes: FLAGS_PRECOMPUTE_SECRET is only used when there is no FLAGS_SECRET.
  • A secret of the user is before the deployment key, so that the build and the runtime agree when only one of them has the deployment key (e.g. vercel build with --prebuilt).
  • The default of the secret parameters in Next.js is now undefined and not process.env.FLAGS_SECRET. The functions read the variables themselves.
  • Next.js: serialize, deserialize, getPrecomputed, generatePermutations (and thus precompute).
  • SvelteKit: precompute, generatePermutations and the read of a precomputed flag, through getPrecomputeSecret in sveltekit/env.ts. A page reads a code with the secret of the handle (the secret passed to createHandle, or else FLAGS_SECRET), or else with the defaults of precompute. As before this PR, the app must pass the same secret to createHandle, precompute and generatePermutations, or none to all of them.
  • Local development of a Vercel project (next dev, vite dev, a local next build && next start): when there is no secret and no deployment key, the functions use a fixed, public secret, but only when there is a VERCEL_OIDC_TOKEN for the environment development (what vercel env pull writes; the token is only decoded, like in findVercelProject). It is the last in the order. When NODE_ENV is not development, they warn one time, because anyone can create a code with this secret. Without such a token (a custom host, or a project which never ran vercel env pull), they throw as before, and the error says to run vercel env pull or to set FLAGS_PRECOMPUTE_SECRET.
  • On Vercel without a secret and without VERCEL_DEPLOYMENT_KEY, the functions throw the same errors as before. "On Vercel" (isOnVercel in lib/vercel-platform.ts) means that VERCEL is set (a build or a deployment, also vercel build) or that the request context of Vercel exists (every deployment at runtime).

Why a key per deployment is enough

A code is created by the build (generatePermutations) and by the middleware, and read by the pages of the same deployment. Vercel writes VERCEL_DEPLOYMENT_KEY with one value to the build environment and to the runtime environment of a deployment (get-deployment-env-context.ts in vercel/api), so all three use the same key. HS256 is deterministic, so the build and the middleware create the same code for the same values. This is the same reasoning as the build secret of withFlags on standard.

Limits

  • VERCEL_DEPLOYMENT_KEY is only set when the project exposes the system environment variables. A project without them must keep FLAGS_SECRET. This is accepted: the signed overrides and the flags discovery of this stack need them too. The docs (docs: FLAGS_SECRET is optional on Vercel #596) say so. VERCEL is one of these variables too, so such a deployment is detected by the request context: the runtime throws. Verified on a test project: the build of such a project has VERCEL=1 and no key, so it throws.
  • vercel build with --prebuilt is not covered, and this is accepted: the deployment does not exist at build time, so the build has no key and throws. Such projects must keep FLAGS_SECRET. The docs (docs: FLAGS_SECRET is optional on Vercel #596) say so.
  • A custom host without a secret still throws, as before this PR. A build with the development token of vercel env pull signs with the public secret and warns; such a build must not be hosted outside of Vercel. On Vercel the public secret is never used.
  • SvelteKit prerendering (entries with generatePermutations) in a local vite build without FLAGS_SECRET throws: the dynamic environment, which has the VERCEL_OIDC_TOKEN of .env.local, can not be read while prerendering, and the static one is not read for it, so that the token is not put into the server bundle.
  • A code is not valid in another deployment or project. Apps which need that must set FLAGS_SECRET.
  • A build cache which restores the output of another deployment replays its codes. Turborepo on Vercel runs with Remote Cache, and VERCEL_DEPLOYMENT_KEY is passed to the task but not hashed. Reproduced on flags-pr597-turbo-cache: a FULL TURBO deploy serves prerendered pages which never match (404 with dynamicParams = false), and ISR revalidation throws signature verification failed. Next.js with Skew Protection (default on Pro and Enterprise) is not affected, because turbo then hashes VERCEL_DEPLOYMENT_ID. The functions do not warn about it: a warning at build time printed once per build worker, and also for a task which is never cached. The fix is "env": ["VERCEL_DEPLOYMENT_KEY"] in turbo.json or FLAGS_PRECOMPUTE_SECRET. The docs (docs: FLAGS_SECRET is optional on Vercel #596) say so.

Tests

packages/flags: pnpm test (20 files, 310 tests passed), pnpm type-check, pnpm check and pnpm build are ok.

New tests: the derivation (stable, 32 bytes, different per deployment key, not the key itself), Next.js and SvelteKit without FLAGS_SECRET (the build and the middleware create the same code, a page reads it, a code of another deployment is rejected, the order of the secrets, throws on Vercel without any key, the public secret with a development OIDC token, throws without it, the warning, a deployment without VERCEL).

On Vercel: tested on the preview deployments of vercel-site.

By hand: examples/snippets with next dev and an empty FLAGS_SECRET serves the precompute pages (App Router and Pages Router) with 200. With the fallback off, the same request fails with Can not serialize due to missing secret.

🤖 Generated with Claude Code

Co-Authored-By: Claude Code <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

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

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

Co-Authored-By: Claude Code <noreply@anthropic.com>
…ads a code

Co-Authored-By: Claude Code <noreply@anthropic.com>
luismeyer and others added 3 commits November 13, 2026 10:42
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
@vercel-internal-security-reviewer

Copy link
Copy Markdown

Security review details

luismeyer and others added 8 commits November 13, 2026 19:08
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…PUTE_SECRET

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It printed once per build worker, and also when the task is never cached.
The docs describe the fix.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch was successfully deployed

14 active deployments
Preview – flags-sdk-dev — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-reflag — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-sveltekit-snippets — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-openfeature — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – shirt-shop — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-launchdarkly — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-posthog — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-snippets — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-vercel — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-flagsmith — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-statsig — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-growthbook — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-playground — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Preview – shirt-shop-api — d4bffeb9 Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant