04_managing_cloudflare_secrets

Managing Secrets in Cloudflare

This document outlines the technical procedures for handling secrets for our OpenNext applications on Cloudflare. For the high-level company policy on secrets, please see the Secrets Management Policy.

The Golden Rule: Never store secrets in your Git repository or as plain text environment variables.

Storing Secrets for Cloudflare Workers/Pages

For functions running on the Cloudflare network (which includes the server-side part of our OpenNext apps), we use Wrangler secrets.

Adding a Secret (via command line)

The recommended way to add a secret is using the wrangler CLI. This encrypts the secret and associates it with your Worker/Pages function.

1. Install Wrangler:

   npm install -g wrangler

2. Authenticate Wrangler:

   wrangler login

3. Add the Secret:

   • From your project directory, run the following command:

     wrangler secret put SECRET_NAME

   • Wrangler will prompt you to enter the secret value in your terminal. This prevents the secret from being saved in your shell history.
   • This command needs to be run for each environment (e.g., preview, production).

Accessing Secrets in Code

• Once a secret is added, it becomes available on the env object in your Worker/Pages function, just like a regular environment variable.

• For example, in your Next.js API route (which runs as a Worker):

  // pages/api/some-route.ts
  import { NextApiRequest, NextApiResponse } from 'next';
   
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    // The context object is extended by OpenNext/Cloudflare
    const { env } = (req as any).context;
   
    const apiKey = env.MY_API_KEY;
   
    // Use the apiKey...
    res.status(200).json({ message: 'Success' });
  }

  (Note: The exact method to access env might vary slightly based on OpenNext version and context. Refer to the latest OpenNext documentation for accessing runtime context.)

Managing Secrets in the Cloudflare Dashboard

While using the CLI is preferred for its security benefits, you can also manage secrets in the UI.

1. Navigate to your Pages Project:
   • Go to Workers & Pages > Select your project.
2. Settings:
   • Go to Settings > Functions.
3. Secrets:
   • Under the “Secrets” section, you can add, edit, or remove secrets for your production and preview environments.

Local Development (using .env files)

For local development, we use .env files to store secrets.

• Create a .env file: Copy .env.example to .env.
• Add your secrets:

  # .env
  MY_API_KEY="your_local_or_test_api_key"
  DATABASE_URL="your_local_db_connection_string"
  

• .gitignore: The .env file must be listed in your .gitignore file to prevent it from ever being committed.
• Next.js automatically loads variables from .env into process.env for local development.

Summary of Environments

• Production: Secrets are managed via wrangler secret or the Cloudflare Pages dashboard.
• Preview (Staging): Secrets are managed separately for the preview environment, also via wrangler secret or the dashboard. This allows you to use different keys for staging and production.
• Local: Secrets are managed in an untracked .env file.

By following this process, we ensure that our secrets are kept secure and are never exposed in our codebase.