fix(core): refuse a Blob token that names no store, at boot

BLOB_READ_WRITE_TOKEN was typed as any non-empty string, so a truncated,
stale or wrong-kind value passed validation, satisfied the FILESTORE_DRIVER
derivation, and then threw from storeIdFrom on the first request that
touched an upload — a 500 on a live board, long after the deploy went green.
That is the boot-then-fail-on-first-upload shape this branch exists to
remove, reintroduced through the token path, and on a linked project it
turns a board that BLOB_STORE_ID alone would have served into a broken one.

The shape check the driver already applied now lives in the schema, so it
fires at boot next to every other configuration error and `community
env:check` reports it. Nothing new is being judged: storeIdFrom rejected
exactly these tokens already, and both callers now share one parser so the
two cannot drift.

Treating an unparseable token as absent whenever a store id is present was
the alternative. It loses on two counts: it cannot help a board with only a
bad token, where nothing else would ever catch it, and where it does apply
it silently ignores a credential the operator typed — while a stale token
for the right store and a garbage one are indistinguishable to us, so it
would quietly write to a store the operator may not have meant.

Four smaller things from the same review. A store id is trimmed before the
SDK or url() sees it, so a pasted value with whitespace cannot produce a
malformed host or fall to the token path on a mismatched comparison. The
intercepted no-credentials message is raised only on the store-id path,
since the token path never asked OIDC for anything. del hands the SDK a copy
of the auth options rather than the driver's own object. And the sentence
the driver matches on is now one exported constant, with a test asserting
the installed @vercel/blob still contains it, so a reword upstream fails
rather than silently costing a good error message.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015WBLHKvRatuUufybYpgER1

Author: claude

docs/vercel.md

@@ -251,7 +251,8 @@ Both work, and the board is the same either way. The difference is what
 happens on the day you leave.
 
 A **Vercel Blob store** is the cheapest thing to set up: attach one to the
-project, and `BLOB_READ_WRITE_TOKEN` appears by itself. That replaces four
+project, and `BLOB_STORE_ID` appears by itself — see [how the Blob store
+authenticates](#how-the-blob-store-authenticates). That replaces four
 values that each had exactly one correct setting and each of which was a
 typo away from a board that booted and then failed at the first upload. It
 is what the one-click template in `templates/vercel` defaults to, and what
@@ -307,6 +308,15 @@ Two consequences worth knowing:
   own machine — `community backup` against a Blob store is the case that
   matters — has no OIDC token, so it needs `BLOB_READ_WRITE_TOKEN`. Create
   one on the store under **Storage**. The deployment never needs it.
+- **A token that names no store is refused at boot**, whether or not
+  `BLOB_STORE_ID` is set beside it. A read-write token reads
+  `vercel_blob_rw_<store>_<secret>` and the board takes the store out of the
+  middle of it, so a truncated, stale or wrong-kind value has no store to
+  name. The board will not quietly fall back to the store id and write
+  somewhere the operator did not ask for, and it will not carry the bad value
+  as far as the first upload: the environment refuses it by name, next to
+  every other configuration error, and says the store id alone would have
+  done. Remove the variable or fix it.
 
 Two things here are **reasoned from the SDK's source and not confirmed
 against a live deploy**, because nobody has run this yet:
@@ -687,10 +697,17 @@ store over the network:
 DATABASE_URL=…            # the pooled string
 DIRECT_DATABASE_URL=…     # the direct string, for the dump
 FILESTORE_DRIVER=blob
-BLOB_READ_WRITE_TOKEN=…   # copy it out of the project's environment settings
+BLOB_READ_WRITE_TOKEN=…   # create one on the store — see below
 community backup --uploads include
 ```
 
+That token is the one value here you make by hand. On the deployment the
+board reaches the store with `BLOB_STORE_ID` and the deployment's OIDC
+identity, and a command on your own machine has no such identity — so open
+the store under **Storage**, create a read-write token, and use it for the
+backup. [How the Blob store authenticates](#how-the-blob-store-authenticates)
+has the whole of it.
+
 Copy the bundle somewhere that is none of the four vendors.
 
 ### 2. Stand up the destination

packages/core/src/env.test.ts

@@ -580,9 +580,49 @@ describe('what the platform publishes, and what the board makes of it', () => {
 
     it('asks for no OIDC token of its own, which a build would not have', () => {
       const env = parseEnv({ ...bare, ...INJECTED })
-
       expect(env.FILESTORE_DRIVER).toBe('blob')
-      expect(Object.keys(env)).not.toContain('VERCEL_OIDC_TOKEN')
+
+      let refusal = ''
+      try {
+        parseEnv(noStore)
+      } catch (error) {
+        refusal = (error as Error).message
+      }
+
+      expect(refusal).toMatch(/BLOB_STORE_ID/)
+      expect(refusal).not.toMatch(/OIDC_TOKEN/)
+    })
+
+    it('refuses a token that names no store, at boot rather than at the first upload', () => {
+      expect(() =>
+        parseEnv({ ...bare, ...INJECTED, BLOB_READ_WRITE_TOKEN: 'vercel_blob_rw_' }),
+      ).toThrow(/BLOB_READ_WRITE_TOKEN.*vercel_blob_rw_<store>_<secret>/s)
+    })
+
+    it('refuses it with no store id either, where nothing else would ever catch it', () => {
+      expect(() =>
+        parseEnv({ ...bare, ...INJECTED, BLOB_STORE_ID: undefined, BLOB_READ_WRITE_TOKEN: 'nope' }),
+      ).toThrow(/BLOB_READ_WRITE_TOKEN/)
+    })
+
+    it('says the store id is credential enough, for an operator who can just drop it', () => {
+      expect(() => parseEnv({ ...bare, ...INJECTED, BLOB_READ_WRITE_TOKEN: 'nope' })).toThrow(
+        /BLOB_STORE_ID, which is credential enough by itself/,
+      )
+    })
+
+    it('leaves a good token alone, on or off the platform', () => {
+      const token = 'vercel_blob_rw_store123_secret'
+
+      expect(
+        parseEnv({ ...bare, ...INJECTED, BLOB_READ_WRITE_TOKEN: token }).BLOB_READ_WRITE_TOKEN,
+      ).toBe(token)
+      expect(
+        parseEnv({
+          NODE_ENV: 'development',
+          BLOB_READ_WRITE_TOKEN: token,
+        }).BLOB_READ_WRITE_TOKEN,
+      ).toBe(token)
     })
 
     it('names both database candidates when neither is published', () => {

packages/core/src/env.ts

@@ -18,6 +18,20 @@ const databaseUrl = z.string().refine(isPostgresUrl, {
 
 const secret = z.string().min(32, 'must be at least 32 characters of high-entropy random data')
 
+export function blobStoreIdFromToken(token: string): string | undefined {
+  const [vendor, product, scope, storeId] = token.split('_')
+  const shaped = vendor === 'vercel' && product === 'blob' && scope === 'rw'
+  return shaped && storeId !== undefined && storeId !== '' ? storeId : undefined
+}
+
+const blobReadWriteToken = z.string().refine((value) => blobStoreIdFromToken(value) !== undefined, {
+  message:
+    'is not a Vercel Blob read-write token. One reads vercel_blob_rw_<store>_<secret>, ' +
+    'and the board takes the store it writes to out of the middle of it. Copy the value ' +
+    'the Blob store published, or remove this variable: on Vercel a linked store also ' +
+    'publishes BLOB_STORE_ID, which is credential enough by itself.',
+})
+
 const redisUrl = z.string().refine(isRedisUrl, {
   message: 'must be a redis:// or rediss:// connection string',
 })
@@ -75,7 +89,7 @@ const envSchema = z
     S3_ENDPOINT: z.string().url().optional(),
     S3_PUBLIC_BASE_URL: z.string().url().optional(),
 
-    BLOB_READ_WRITE_TOKEN: nonEmpty.optional(),
+    BLOB_READ_WRITE_TOKEN: blobReadWriteToken.optional(),
     BLOB_STORE_ID: nonEmpty.optional(),
 
     MAIL_FROM: z.string().email().optional(),

packages/core/src/index.ts

@@ -25,6 +25,7 @@ export { timingSafeEqualString } from './crypto'
 export {
   assertEnv,
   assertRuntimeEnv,
+  blobStoreIdFromToken,
   type Env,
   env,
   isDemoMode,

packages/drivers/src/files/blob-file-store.ts

@@ -1,4 +1,5 @@
 import {
+  blobStoreIdFromToken,
   ConfigurationError,
   type FileStore,
   type PutFileOptions,
@@ -54,18 +55,21 @@ function isNotFound(error: unknown): boolean {
   return named === 'BlobNotFoundError' || message.includes('The requested blob does not exist')
 }
 
+export const BLOB_NO_CREDENTIALS = 'No blob credentials found'
+
 function normalizeStoreId(storeId: string): string {
-  return storeId.startsWith('store_') ? storeId.slice('store_'.length) : storeId
+  const trimmed = storeId.trim()
+  return trimmed.startsWith('store_') ? trimmed.slice('store_'.length) : trimmed
 }
 
 function needsCredentials(error: unknown): boolean {
   const message = (error as { message?: string } | null)?.message ?? ''
-  return message.includes('No blob credentials found')
+  return message.includes(BLOB_NO_CREDENTIALS)
 }
 
 function storeIdFrom(token: string): string {
-  const [vendor, product, scope, storeId] = token.split('_')
-  if (vendor !== 'vercel' || product !== 'blob' || scope !== 'rw' || !storeId) {
+  const storeId = blobStoreIdFromToken(token)
+  if (storeId === undefined) {
     throw new ConfigurationError(
       'BLOB_READ_WRITE_TOKEN is not a Vercel Blob read-write token. Copy the ' +
         'value the Blob store published, which starts with vercel_blob_rw_.',
@@ -84,7 +88,8 @@ export class BlobFileStore implements FileStore {
   private loading: Promise<BlobLike> | undefined
 
   constructor(config: BlobFileStoreConfig, blob?: BlobLike) {
-    this.auth = config.token === undefined ? { storeId: config.storeId } : { token: config.token }
+    this.auth =
+      config.token === undefined ? { storeId: config.storeId.trim() } : { token: config.token }
     this.storeId =
       config.token === undefined ? normalizeStoreId(config.storeId) : storeIdFrom(config.token)
     this.load =
@@ -125,7 +130,7 @@ export class BlobFileStore implements FileStore {
     try {
       return await operation()
     } catch (error) {
-      if (!needsCredentials(error)) throw error
+      if (!needsCredentials(error) || !('storeId' in this.auth)) throw error
       throw new ConfigurationError(
         `The Blob store ${this.storeId} was reached with no usable credential. ` +
           'BLOB_STORE_ID is set, so the board asked the Vercel SDK to authenticate ' +
@@ -191,7 +196,7 @@ export class BlobFileStore implements FileStore {
 
     const blob = await this.blob()
     try {
-      await this.attempt(() => blob.del(key, this.auth))
+      await this.attempt(() => blob.del(key, { ...this.auth }))
     } catch (error) {
       if (isNotFound(error)) return
       throw error

packages/testkit/src/blob-file-store.test.ts

@@ -1,6 +1,14 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
 import { describe, expect, it } from 'vitest'
 
-import { BlobFileStore, type BlobLike } from '@meith/drivers/files/blob-file-store'
+import {
+  BLOB_NO_CREDENTIALS,
+  BlobFileStore,
+  type BlobLike,
+} from '@meith/drivers/files/blob-file-store'
 
 import { fileStoreContract } from './driver-contracts'
 
@@ -11,7 +19,7 @@ const STORE_ID = 'store_store123'
 class FakeNoCredentialsError extends Error {
   constructor() {
     super(
-      'Vercel Blob: No blob credentials found. Pass a `token` option, set ' +
+      `Vercel Blob: ${BLOB_NO_CREDENTIALS}. Pass a \`token\` option, set ` +
         'BLOB_READ_WRITE_TOKEN, or use `oidcToken` (or `VERCEL_OIDC_TOKEN`) with ' +
         '`storeId` or `BLOB_STORE_ID`.',
     )
@@ -318,3 +326,83 @@ describe('fromEnv, against what the integration actually publishes', () => {
     )
   })
 })
+
+describe('the sentence the SDK throws, which the driver matches on', () => {
+  it('is still in the installed @vercel/blob, so a reword cannot pass unnoticed', () => {
+    const from = createRequire(
+      new URL('../../drivers/src/files/blob-file-store.ts', import.meta.url),
+    )
+    const dist = dirname(from.resolve('@vercel/blob'))
+    const sources = readdirSync(dist)
+      .filter((entry) => entry.endsWith('.js'))
+      .map((entry) => readFileSync(join(dist, entry), 'utf8'))
+
+    expect(sources.some((source) => source.includes(BLOB_NO_CREDENTIALS))).toBe(true)
+  })
+
+  it('is matched loosely enough to survive the prefix the SDK puts in front of it', () => {
+    expect(new FakeNoCredentialsError().message).toContain(BLOB_NO_CREDENTIALS)
+  })
+})
+
+describe('a token that names no store', () => {
+  const store = () => BlobFileStore.fromEnv({ BLOB_READ_WRITE_TOKEN: 'vercel_blob_rw_' })
+
+  it('is refused rather than taken for one', () => {
+    expect(store).toThrow(/vercel_blob_rw_/)
+  })
+
+  it('is refused even with a store id beside it, because it was typed on purpose', () => {
+    expect(() =>
+      BlobFileStore.fromEnv({ BLOB_STORE_ID: STORE_ID, BLOB_READ_WRITE_TOKEN: 'garbage' }),
+    ).toThrow(/vercel_blob_rw_/)
+  })
+})
+
+describe('a store id with whitespace around it', () => {
+  it('names the same store as the trimmed one', () => {
+    const padded = new BlobFileStore({ storeId: `  ${STORE_ID}  ` }, fakeBlob())
+    expect(padded.url('a.png')).toBe(
+      new BlobFileStore({ storeId: STORE_ID }, fakeBlob()).url('a.png'),
+    )
+  })
+
+  it('is trimmed before the SDK ever sees it', async () => {
+    const blob = fakeBlob()
+    const store = new BlobFileStore({ storeId: `  ${STORE_ID}  ` }, blob)
+
+    await store.delete('a.png')
+
+    expect(blob.storeIds).toEqual([STORE_ID])
+  })
+
+  it('still matches a token for the same store, rather than falling to the token path', async () => {
+    const blob = fakeBlob()
+    const store = BlobFileStore.fromEnv({
+      BLOB_STORE_ID: `  ${STORE_ID}  `,
+      BLOB_READ_WRITE_TOKEN: TOKEN,
+    })
+    Object.assign(store as unknown as { loading: Promise<BlobLike> }, {
+      loading: Promise.resolve(blob),
+    })
+
+    await store.delete('a.png')
+
+    expect(blob.tokens).toEqual([undefined])
+  })
+})
+
+describe('the OIDC explanation', () => {
+  it('is not offered on the token path, which never asked OIDC for anything', async () => {
+    const blob = fakeBlob()
+    blob.put = () => Promise.reject(new FakeNoCredentialsError())
+    const store = new BlobFileStore({ token: TOKEN }, blob)
+
+    await expect(
+      store.put('a.png', new TextEncoder().encode('x'), {
+        contentType: 'image/png',
+        visibility: 'private',
+      }),
+    ).rejects.toThrow(BLOB_NO_CREDENTIALS)
+  })
+})