feat: improve cookie chunk handling via base64url+length encoding (#90)

Improves cookie chunk handling by introducing a new cookie encoding
scheme that includes the length of the encoded Base64 value. It will
prevent reconstructing data from stale cookies.

Due to bad uses of this package, some cookie chunks are not being
properly deleted. Meaning that if a session was encoded in 3 chunks now
suddenly goes down to 2 chunks, the last chunk is not being deleted.
When it gets reconstructed, all the 3 chunks get concatenated and
parsed. In some situations this leads to an invalid UTF-8 sequence
(mainly because Base64 packs 6 bits into 8).

This PR addresses this by implementing a different Base64 encoding of
the chunks. Instead of just splitting up a Base64 string into chunks,
the first chunk will now contain the length of the string that follows.
This will prevent a leftover chunk from being parsed as valid.

The encoding is as follows:

```base64l-<length of base64 encoded string as base 36>-<base64 encoding>```

The library now checks for these conditions and emits warnings to let the developer know that they have a bug in their integration.

Author: hf

src/__snapshots__/createServerClient.spec.ts.snap

@@ -3,7 +3,11 @@ import { describe, expect, it, beforeEach, afterEach } from "vitest";
 import { isBrowser, DEFAULT_COOKIE_OPTIONS, MAX_CHUNK_SIZE } from "./utils";
 import { CookieOptions } from "./types";
 
-import { createStorageFromOptions, applyServerStorage } from "./cookies";
+import {
+  createStorageFromOptions,
+  applyServerStorage,
+  decodeCookie,
+} from "./cookies";
 
 describe("createStorageFromOptions in browser without cookie methods", () => {
   beforeEach(() => {
@@ -1070,3 +1074,81 @@ describe("applyServerStorage", () => {
     ]);
   });
 });
+
+describe("decodeCookie", () => {
+  let warnings: any[][] = [];
+  let originalWarn: any;
+
+  beforeEach(() => {
+    warnings = [];
+
+    originalWarn = console.warn;
+    console.warn = (...args: any[]) => {
+      warnings.push(structuredClone(args));
+    };
+  });
+
+  afterEach(() => {
+    console.warn = originalWarn;
+  });
+
+  it("should decode base64url+length encoded value", () => {
+    const value = JSON.stringify({ a: "b" });
+    const valueB64 = Buffer.from(value).toString("base64url");
+
+    expect(
+      decodeCookie(`base64l-${valueB64.length.toString(36)}-${valueB64}`),
+    ).toEqual(value);
+    expect(
+      decodeCookie(
+        `base64l-${valueB64.length.toString(36)}-${valueB64}padding_that_is_ignored`,
+      ),
+    ).toEqual(value);
+    expect(
+      decodeCookie(
+        `base64l-${valueB64.length.toString(36)}-${valueB64.substring(0, valueB64.length - 1)}`,
+      ),
+    ).toBeNull();
+    expect(decodeCookie(`base64l-0-${valueB64}`)).toBeNull();
+    expect(decodeCookie(`base64l-${valueB64}`)).toBeNull();
+    expect(warnings).toMatchInlineSnapshot(`
+      [
+        [
+          "@supabase/ssr: Detected stale cookie data. Please check your integration with Supabase for bugs. This can cause your users to loose the session.",
+        ],
+        [
+          "@supabase/ssr: Detected stale cookie data. Please check your integration with Supabase for bugs. This can cause your users to loose the session.",
+        ],
+      ]
+    `);
+  });
+
+  it("should decode base64url encoded value", () => {
+    const value = JSON.stringify({ a: "b" });
+    const valueB64 = Buffer.from(value).toString("base64url");
+
+    expect(decodeCookie(`base64-${valueB64}`)).toEqual(value);
+    expect(warnings).toMatchInlineSnapshot(`[]`);
+  });
+
+  it("should not decode base64url encoded value with invalid UTF-8", () => {
+    const valueB64 = Buffer.from([0xff, 0xff, 0xff, 0xff]).toString(
+      "base64url",
+    );
+
+    expect(decodeCookie(`base64-${valueB64}`)).toBeNull();
+    expect(
+      decodeCookie(`base64l-${valueB64.length.toString(36)}-${valueB64}`),
+    ).toBeNull();
+    expect(warnings).toMatchInlineSnapshot(`
+      [
+        [
+          "@supabase/ssr: Detected stale cookie data that does not decode to a UTF-8 string. Please check your integration with Supabase for bugs. This can cause your users to loose session access.",
+        ],
+        [
+          "@supabase/ssr: Detected stale cookie data that does not decode to a UTF-8 string. Please check your integration with Supabase for bugs. This can cause your users to loose session access.",
+        ],
+      ]
+    `);
+  });
+});

src/cookies.spec.ts

@@ -22,6 +22,55 @@ import type {
 } from "./types";
 
 const BASE64_PREFIX = "base64-";
+const BASE64_LENGTH_PREFIX = "base64l-";
+const BASE64_LENGTH_PATTERN = /^base64l-([0-9a-z]+)-(.+)$/;
+
+export function decodeBase64Cookie(value: string) {
+  try {
+    return stringFromBase64URL(value);
+  } catch (e: any) {
+    // if an invalid UTF-8 sequence is encountered, it means that reconstructing the chunkedCookie failed and the cookies don't contain useful information
+    console.warn(
+      "@supabase/ssr: Detected stale cookie data that does not decode to a UTF-8 string. Please check your integration with Supabase for bugs. This can cause your users to loose session access.",
+    );
+    return null;
+  }
+}
+
+export function decodeCookie(chunkedCookie: string) {
+  let decoded = chunkedCookie;
+
+  if (chunkedCookie.startsWith(BASE64_PREFIX)) {
+    return decodeBase64Cookie(decoded.substring(BASE64_PREFIX.length));
+  } else if (chunkedCookie.startsWith(BASE64_LENGTH_PREFIX)) {
+    const match = chunkedCookie.match(BASE64_LENGTH_PATTERN);
+
+    if (!match) {
+      return null;
+    }
+
+    const expectedLength = parseInt(match[1], 36);
+
+    if (expectedLength === 0) {
+      return null;
+    }
+
+    if (match[2].length !== expectedLength) {
+      console.warn(
+        "@supabase/ssr: Detected stale cookie data. Please check your integration with Supabase for bugs. This can cause your users to loose the session.",
+      );
+    }
+
+    if (expectedLength <= match[2].length) {
+      return decodeBase64Cookie(match[2].substring(0, expectedLength));
+    } else {
+      // data is missing, cannot decode cookie
+      return null;
+    }
+  }
+
+  return decoded;
+}
 
 /**
  * Creates a storage client that handles cookies correctly for browser and
@@ -33,7 +82,7 @@ const BASE64_PREFIX = "base64-";
  */
 export function createStorageFromOptions(
   options: {
-    cookieEncoding: "raw" | "base64url";
+    cookieEncoding: "raw" | "base64url" | "base64url+length";
     cookies?:
       | CookieMethodsBrowser
       | CookieMethodsBrowserDeprecated
@@ -203,15 +252,7 @@ export function createStorageFromOptions(
             return null;
           }
 
-          let decoded = chunkedCookie;
-
-          if (chunkedCookie.startsWith(BASE64_PREFIX)) {
-            decoded = stringFromBase64URL(
-              chunkedCookie.substring(BASE64_PREFIX.length),
-            );
-          }
-
-          return decoded;
+          return decodeCookie(chunkedCookie);
         },
         setItem: async (key: string, value: string) => {
           const allCookies = await getAll([key]);
@@ -225,6 +266,13 @@ export function createStorageFromOptions(
 
           if (cookieEncoding === "base64url") {
             encoded = BASE64_PREFIX + stringToBase64URL(value);
+          } else if (cookieEncoding === "base64url+length") {
+            encoded = [
+              BASE64_LENGTH_PREFIX,
+              value.length.toString(36),
+              "-",
+              value,
+            ].join("");
           }
 
           const setCookies = createChunks(key, encoded);
@@ -342,18 +390,7 @@ export function createStorageFromOptions(
           return null;
         }
 
-        let decoded = chunkedCookie;
-
-        if (
-          typeof chunkedCookie === "string" &&
-          chunkedCookie.startsWith(BASE64_PREFIX)
-        ) {
-          decoded = stringFromBase64URL(
-            chunkedCookie.substring(BASE64_PREFIX.length),
-          );
-        }
-
-        return decoded;
+        return decodeCookie(chunkedCookie);
       },
       setItem: async (key: string, value: string) => {
         // We don't have an `onAuthStateChange` event that can let us know that
@@ -411,7 +448,7 @@ export async function applyServerStorage(
     removedItems: { [name: string]: boolean };
   },
   options: {
-    cookieEncoding: "raw" | "base64url";
+    cookieEncoding: "raw" | "base64url" | "base64url+length";
     cookieOptions?: CookieOptions | null;
   },
 ) {
@@ -439,6 +476,13 @@ export async function applyServerStorage(
 
     if (cookieEncoding === "base64url") {
       encoded = BASE64_PREFIX + stringToBase64URL(encoded);
+    } else if (cookieEncoding === "base64url+length") {
+      encoded = [
+        BASE64_LENGTH_PREFIX,
+        encoded.length.toString(36),
+        "-",
+        stringToBase64URL(encoded),
+      ].join("");
     }
 
     const chunks = createChunks(itemName, encoded);

src/cookies.ts

@@ -4,7 +4,7 @@ import { MAX_CHUNK_SIZE, stringToBase64URL } from "./utils";
 import { CookieOptions } from "./types";
 import { createBrowserClient } from "./createBrowserClient";
 
-describe("createServerClient", () => {
+describe("createBrowserClient", () => {
   describe("validation", () => {
     it("should throw an error on empty URL and anon key", async () => {
       expect(() => {

src/createBrowserClient.spec.ts

@@ -48,7 +48,7 @@ export function createBrowserClient<
   options?: SupabaseClientOptions<SchemaName> & {
     cookies?: CookieMethodsBrowser;
     cookieOptions?: CookieOptionsWithName;
-    cookieEncoding?: "raw" | "base64url";
+    cookieEncoding?: "raw" | "base64url" | "base64url+length";
     isSingleton?: boolean;
   },
 ): SupabaseClient<Database, SchemaName, Schema>;
@@ -72,7 +72,7 @@ export function createBrowserClient<
   options?: SupabaseClientOptions<SchemaName> & {
     cookies: CookieMethodsBrowserDeprecated;
     cookieOptions?: CookieOptionsWithName;
-    cookieEncoding?: "raw" | "base64url";
+    cookieEncoding?: "raw" | "base64url" | "base64url+length";
     isSingleton?: boolean;
   },
 ): SupabaseClient<Database, SchemaName, Schema>;
@@ -91,7 +91,7 @@ export function createBrowserClient<
   options?: SupabaseClientOptions<SchemaName> & {
     cookies?: CookieMethodsBrowser | CookieMethodsBrowserDeprecated;
     cookieOptions?: CookieOptionsWithName;
-    cookieEncoding?: "raw" | "base64url";
+    cookieEncoding?: "raw" | "base64url" | "base64url+length";
     isSingleton?: boolean;
   },
 ): SupabaseClient<Database, SchemaName, Schema> {
@@ -113,7 +113,7 @@ export function createBrowserClient<
   const { storage } = createStorageFromOptions(
     {
       ...options,
-      cookieEncoding: options?.cookieEncoding ?? "base64url",
+      cookieEncoding: options?.cookieEncoding ?? "base64url+length",
     },
     false,
   );