feat(@vercel/blob): Allow custom headers in client uploads (#857)

Fixes #796 #420

Author: vvo

.changeset/add-headers-to-blob-upload.md

@@ -0,0 +1,7 @@
+---
+"@vercel/blob": minor
+---
+
+feat(blob): Add support for custom headers in client upload method
+
+This change adds the ability to pass custom headers to the `upload` method in the client, which will be forwarded to the server endpoint specified by `handleUploadUrl`. This is particularly useful for sending authorization headers and solves issues like [#796](https://github.com/vercel/storage/issues/796) and [#420](https://github.com/vercel/storage/issues/420).

packages/blob/src/client.ts

@@ -234,6 +234,11 @@ export interface CommonUploadOptions {
    * Additional data which will be sent to your `handleUpload` route.
    */
   clientPayload?: string;
+  /**
+   * Additional headers to be sent when making the request to your `handleUpload` route.
+   * This is useful for sending authorization headers or any other custom headers.
+   */
+  headers?: Record<string, string>;
 }
 
 /**
@@ -255,6 +260,7 @@ export type UploadOptions = ClientCommonPutOptions & CommonUploadOptions;
  *   - access - (Required) Must be 'public' as blobs are publicly accessible.
  *   - handleUploadUrl - (Required) A string specifying the route to call for generating client tokens for client uploads.
  *   - clientPayload - (Optional) A string to be sent to your handleUpload server code. Example use-case: attaching the post id an image relates to.
+ *   - headers - (Optional) An object containing custom headers to be sent with the request to your handleUpload route. Example use-case: sending Authorization headers.
  *   - contentType - (Optional) A string indicating the media type. By default, it's extracted from the pathname's extension.
  *   - multipart - (Optional) Whether to use multipart upload for large files. It will split the file into multiple parts, upload them in parallel and retry failed parts.
  *   - abortSignal - (Optional) AbortSignal to cancel the operation.
@@ -290,6 +296,7 @@ export const upload = createPutMethod<UploadOptions>({
       pathname,
       clientPayload: options.clientPayload ?? null,
       multipart: options.multipart ?? false,
+      headers: options.headers,
     });
   },
 });
@@ -643,6 +650,7 @@ async function retrieveClientToken(options: {
   clientPayload: string | null;
   multipart: boolean;
   abortSignal?: AbortSignal;
+  headers?: Record<string, string>;
 }): Promise<string> {
   const { handleUploadUrl, pathname } = options;
   const url = isAbsoluteUrl(handleUploadUrl)
@@ -664,6 +672,7 @@ async function retrieveClientToken(options: {
     body: JSON.stringify(event),
     headers: {
       'content-type': 'application/json',
+      ...options.headers,
     },
     signal: options.abortSignal,
   });

test/next/src/app/vercel/blob/app/client/page.tsx

@@ -33,6 +33,11 @@ export default function AppClientUpload(): React.JSX.Element {
               access: 'public',
               multipart: searchParams?.get('multipart') === '1',
               handleUploadUrl: `/vercel/blob/api/app/handle-blob-upload/serverless`,
+              // Example of using the new headers parameter to send an authorization header
+              headers: {
+                Authorization: 'Bearer your-token-here',
+                'X-Custom-Header': 'Custom Value',
+              },
               onUploadProgress(progressEvent) {
                 setProgressEvents((prev) => [
                   ...prev,

test/next/src/app/vercel/blob/app/test/client/page.tsx

@@ -21,6 +21,11 @@ export default function AppBodyClient(props: {
         access: 'public',
         handleUploadUrl: callback,
         multipart: multipart === '1',
+        // Example of using the new headers parameter to send an authorization header
+        headers: {
+          Authorization: 'Bearer test-token',
+          'X-Test-Header': 'Test Value',
+        },
       });
       setBlob(blobResult);
       setContent(await fetch(blobResult.url).then((r) => r.text()));

test/next/src/app/vercel/blob/handle-blob-upload.ts

@@ -26,6 +26,13 @@ export async function handleUploadHandler(
   request: Request,
 ): Promise<NextResponse> {
   const body = (await request.json()) as HandleUploadBody;
+
+  // Log all headers received
+  console.log('Request headers:');
+  request.headers.forEach((value, key) => {
+    console.log(`${key}: ${value}`);
+  });
+
   try {
     const jsonResponse = await handleUpload({
       body,
@@ -38,10 +45,17 @@ export async function handleUploadHandler(
           throw new Error('Not authorized');
         }
 
+        // You can now access headers in the authorization logic
+        const customHeader =
+          request.headers.get('X-Custom-Header') ||
+          request.headers.get('X-Test-Header');
+        console.log('Custom header received:', customHeader);
+
         return {
           addRandomSuffix: true,
           tokenPayload: JSON.stringify({
             userId: user?.id,
+            customHeader,
           }),
         };
       },

test/next/src/app/vercel/blob/validate-upload-token.ts

@@ -4,6 +4,21 @@ export function validateUploadToken(
   request: IncomingMessage | Request,
 ): boolean {
   if (process.env.NODE_ENV === 'development') return true;
+
+  // Check for authorization header
+  const authHeader =
+    'credentials' in request
+      ? (request.headers.get('authorization') ?? '')
+      : (request.headers.authorization ?? '');
+
+  // Validate Bearer token if present
+  if (authHeader && authHeader.startsWith('Bearer ')) {
+    const token = authHeader.split(' ')[1];
+    // Example validation - in real app, you'd validate against your auth system
+    return token === 'your-token-here' || token === 'test-token';
+  }
+
+  // Fall back to cookie validation
   const cookie =
     'credentials' in request
       ? (request.headers.get('cookie') ?? '')