🍪 Cookie API: Async Function to Rotate Secrets

[SpencerDuball]

This proposal is to update the Cookie API to accept secrets: string[] | (() => Promise<string[]>) as an option instead of only secrets: string[]. This would allow for programmatically retrieving the secrets used for signing and signature verification.

Problem

In my app, I would like to automatically rotate the secrets that sessions are signed with. I can rotate these secrets without issue, but to my knowledge there is no way to update the secrets that the cookie factory uses to sign/verify cookies. In the example below from the Singing cookies documentation we can see that the cookie factory is imported and used as a variable:

// app/cookies.server.ts
export const cookie = createCookie("user-prefs", {
  secrets: ["n3wsecr3t", "olds3cret"],
});

// app/routes/route.tsx
import { cookie } from "~/cookies.server";

export async function loader({
  request,
}: LoaderFunctionArgs) {
  const oldCookie = request.headers.get("Cookie");
  // oldCookie may have been signed with "olds3cret", but still parses ok
  const value = await cookie.parse(oldCookie);

  new Response("...", {
    headers: {
      // Set-Cookie is signed with "n3wsecr3t"
      "Set-Cookie": await cookie.serialize(value),
    },
  });
}

The secrets are statically passed upon the initialization of the cookie factory, however even if using an environment variable these strings would be passed by value into the secrets array, ex: secrets: [ENV.SECRET_1, ENV.SECRET_2].

Proposal

This proposal is to update the Cookie API to also allow accepting an async function for the secrets option. This would allow users to supply any logic to retrieve the secrets they wish. This should have pretty minimal impact to the Cookie API as well, we already use async methods to .parse and .serialize (which use the secrets). There is one more method that accesses the secrets parameter, get isSigned() that might need a breaking change or could just assume the cookie is signed if a custom secrets function is passed. If we assume isSigned when a function is passed it would be good to raise an error if the secrets function did not return a secret to sign the cookie with.

Here is a sample of the majority of the API changes, reference the current implementation to compare/constrast. Search for // <-- CHANGE HERE to see the changes, there are only 4 and they are relatively minimal.

// .... SNIP ....

export interface CookieSignatureOptions {
  /**
   * An array of secrets that may be used to sign/unsign the value of a cookie.
   *
   * The array makes it easy to rotate secrets. New secrets should be added to
   * the beginning of the array. `cookie.serialize()` will always use the first
   * value in the array, but `cookie.parse()` may use any of them so that
   * cookies that were signed with older secrets still work.
   */
  secrets?: string[] | (() => Promise<string[]>);  // <-- CHANGE HERE
}

// .... SNIP ....

/**
 * Creates a logical container for managing a browser cookie from the server.
 *
 * @see https://remix.run/utils/cookies#createcookie
 */
export const createCookieFactory =
  ({ sign, unsign }: { sign: SignFunction; unsign: UnsignFunction }): CreateCookieFunction =>
  (name, cookieOptions = {}) => {
    let { secrets = [], ...options } = {
      path: "/",
      sameSite: "lax" as const,
      ...cookieOptions,
    };

    warnOnceAboutExpiresCookie(name, options.expires);

    return {
      get name() {
        return name;
      },
      get isSigned() {
        return typeof secrets === "function" || secrets.length > 0;  // <-- CHANGE HERE
      },
      get expires() {
        // Max-Age takes precedence over Expires
        return typeof options.maxAge !== "undefined" ? new Date(Date.now() + options.maxAge * 1000) : options.expires;
      },
      async parse(cookieHeader, parseOptions) {
        if (!cookieHeader) return null;
        let cookies = parse(cookieHeader, { ...options, ...parseOptions });

        let _secrets: string[] = [];  // <-- CHANGE HERE
        if (typeof secrets === "function") {
          _secrets = await secrets();
          if (_secrets.length < 1)
            throw new Error("When using a function to supply secrets, the function must supply at least one secret.");
        } else _secrets = secrets;

        return name in cookies
          ? cookies[name] === ""
            ? ""
            : await decodeCookieValue(unsign, cookies[name], _secrets)
          : null;
      },
      async serialize(value, serializeOptions) {
        let _secrets: string[] = [];  // <-- CHANGE HERE
        if (typeof secrets === "function") {
          _secrets = await secrets();
          if (_secrets.length < 1)
            throw new Error("When using a function to supply secrets, the function must supply at least one secret.");
        } else _secrets = secrets;

        return serialize(name, value === "" ? "" : await encodeCookieValue(sign, value, _secrets), {
          ...options,
          ...serializeOptions,
        });
      },
    };
  };

// .... SNIP ....

Workarounds

• I looked into the createCookieFactory to potentially supply custom functions for the sign and unsign. This could technically be done, but you would need to pass in dummy values for the secrets when creating a cookie factory. You would also be discarding the passed secret to the sign and unsign functions when doing so, see the node example here for reference: remix-node/implementations.ts.
• You could update the variable holding the cookie factory. For example, we have a cookie factory declared and anytime your secrets are rotated you could update this factory variable. This really doesn't work if the cookie is passed anywhere else in the code, for example being used in a Session - AKA this is a pretty poor workaround:

export let cookie = createCookie("user-prefs", {
  secrets: ["n3wsecr3t", "olds3cret"],
});

import { cookie } from "~/cookie.server";

function updateOnRotation(newSecrets: string[]) {
  if (newSecrets) cookie = createCookie("user-prefs", {
    secrets: newSecrets
  });
}