Improve secret parameter support for firebase functions. (#9335)

* Improve secret parameter support for firebase functions.

Key changes:
- Added --format flag to functions:secrets:set command
- Auto-detect JSON format from .json file extensions
- Added format field to SecretParam interface for deploy-time handling
- Use visible input() prompt for JSON secrets vs password() for regular secrets
- Validate JSON format before storing in Secret Manager
- Improved error messages with actionable commands for developers
- Added non-interactive mode check with helpful error for missing secrets

Example usage:
  firebase functions:secrets:set STRIPE_CONFIG --format=json --data-file config.json
  cat config.json | firebase functions:secrets:set STRIPE_CONFIG --format=json

* Address code review feedback for functions-secrets-set command

- Include parse error message in JSON validation errors for better debugging
- Remove redundant --format=json flag from error suggestions (auto-detected from .json extension)
- Use consistent <file.json> placeholder instead of config.json in examples
- Implement custom secret reading logic to handle file/stdin/interactive input
- Keep all interactive secrets hidden using password() for security (including JSON)

* Address code review feedback for deploy-time secret params

- Include parse error message in JSON validation errors for better debugging
- Remove redundant --format=json flag from error suggestions (auto-detected from .json extension)
- Use consistent <file.json> placeholder instead of config.json in examples
- Keep all interactive secrets hidden using password() for security (including JSON)

* Formatting.

* Add CHANGELOG entry for JSON secrets support

* Extract JSON secret validation to shared function

Move validateJsonSecret to src/functions/secrets.ts to adhere to DRY principle and improve maintainability. This avoids duplicating the same validation logic and error messages across multiple files.

* formatting.

* make better use of existing utiliyt.

* nit: organize import.

Author: taeold

CHANGELOG.md

@@ -1 +1,2 @@
+- Add JSON format support for Cloud Functions secrets with `--format json` flag and auto-detection from file extensions (#1745)
 - `firebase dataconnect:sdk:generate` will run `init dataconnect:sdk` automatically if no SDKs are configured (#9325).

src/commands/functions-secrets-set.ts

@@ -1,7 +1,9 @@
 import * as clc from "colorette";
+import * as tty from "tty";
 
 import { logger } from "../logger";
-import { ensureValidKey, ensureSecret } from "../functions/secrets";
+import { FirebaseError } from "../error";
+import { ensureValidKey, ensureSecret, validateJsonSecret } from "../functions/secrets";
 import { Command } from "../command";
 import { requirePermissions } from "../requirePermissions";
 import { Options } from "../options";
@@ -36,15 +38,37 @@ export const command = new Command("functions:secrets:set <KEY>")
     "--data-file <dataFile>",
     'file path from which to read secret data. Set to "-" to read the secret data from stdin',
   )
+  .option("--format <format>", "format of the secret value. 'string' (default) or 'json'")
   .action(async (unvalidatedKey: string, options: Options) => {
     const projectId = needProjectId(options);
     const projectNumber = await needProjectNumber(options);
     const key = await ensureValidKey(unvalidatedKey, options);
     const secret = await ensureSecret(projectId, key, options);
-    const secretValue = await readSecretValue(
-      `Enter a value for ${key}`,
-      options.dataFile as string | undefined,
-    );
+
+    // Determine format using priority order: explicit flag > file extension > default to string
+    let format = options.format as string | undefined;
+    const dataFile = options.dataFile as string | undefined;
+    if (!format && dataFile && dataFile !== "-") {
+      // Auto-detect from file extension
+      if (dataFile.endsWith(".json")) {
+        format = "json";
+      }
+    }
+
+    // Only error if there's no input source (no file and no piped stdin)
+    if (!dataFile && tty.isatty(0) && options.nonInteractive) {
+      throw new FirebaseError(
+        `Cannot prompt for secret value in non-interactive mode.\n` +
+          `Use --data-file to provide the secret value from a file.`,
+      );
+    }
+
+    const promptSuffix = format === "json" ? " (JSON format)" : "";
+    const secretValue = await readSecretValue(`Enter a value for ${key}${promptSuffix}:`, dataFile);
+
+    if (format === "json") {
+      validateJsonSecret(key, secretValue);
+    }
     const secretVersion = await addVersion(projectId, key, secretValue);
     logSuccess(`Created a new secret version ${toSecretVersionResourceName(secretVersion)}`);
 

src/deploy/functions/params.ts

@@ -1,6 +1,7 @@
 import { logger } from "../../logger";
 import { FirebaseError } from "../../error";
 import { checkbox, input, password, select } from "../../prompt";
+import { validateJsonSecret } from "../../functions/secrets";
 import * as build from "./build";
 import { assertExhaustive, partition } from "../../functional";
 import * as secretManager from "../../gcp/secretManager";
@@ -224,6 +225,9 @@ interface SecretParam {
   // A long description of the parameter's purpose and allowed values. If omitted, UX will not
   // provide a description of the parameter
   description?: string;
+
+  // The format of the secret, e.g. "json"
+  format?: string;
 }
 
 export type Param = StringParam | IntParam | BooleanParam | ListParam | SecretParam;
@@ -390,6 +394,23 @@ export async function resolveParams(
   }
 
   const [needSecret, needPrompt] = partition(outstanding, (param) => param.type === "secret");
+
+  // Check for missing secrets in non-interactive mode
+  if (nonInteractive && needSecret.length > 0) {
+    const secretNames = needSecret.map((p) => p.name).join(", ");
+    const commands = needSecret
+      .map(
+        (p) =>
+          `\tfirebase functions:secrets:set ${p.name}${(p as SecretParam).format === "json" ? " --format=json --data-file <file.json>" : ""}`,
+      )
+      .join("\n");
+    throw new FirebaseError(
+      `In non-interactive mode but have no value for the following secrets: ${secretNames}\n\n` +
+        "Set these secrets before deploying:\n" +
+        commands,
+    );
+  }
+
   // The functions emulator will handle secrets
   if (!isEmulator) {
     for (const param of needSecret) {
@@ -398,7 +419,7 @@ export async function resolveParams(
   }
 
   if (nonInteractive && needPrompt.length > 0) {
-    const envNames = outstanding.map((p) => p.name).join(", ");
+    const envNames = needPrompt.map((p) => p.name).join(", ");
     throw new FirebaseError(
       `In non-interactive mode but have no value for the following environment variables: ${envNames}\n` +
         "To continue, either run `firebase deploy` with an interactive terminal, or add values to a dotenv file. " +
@@ -460,17 +481,24 @@ function populateDefaultParams(config: FirebaseConfig): Record<string, ParamValu
  * to read its environment variables. They are instead provided through GCF's own
  * Secret Manager integration.
  */
-async function handleSecret(secretParam: SecretParam, projectId: string) {
+async function handleSecret(secretParam: SecretParam, projectId: string): Promise<void> {
   const metadata = await secretManager.getSecretMetadata(projectId, secretParam.name, "latest");
   if (!metadata.secret) {
+    const promptMessage = `This secret will be stored in Cloud Secret Manager (https://cloud.google.com/secret-manager/pricing) as ${
+      secretParam.name
+    }. Enter ${secretParam.format === "json" ? "a JSON value" : "a value"} for ${
+      secretParam.label || secretParam.name
+    }:`;
+
     const secretValue = await password({
-      message: `This secret will be stored in Cloud Secret Manager (https://cloud.google.com/secret-manager/pricing) as ${
-        secretParam.name
-      }. Enter a value for ${secretParam.label || secretParam.name}:`,
+      message: promptMessage,
     });
+    if (secretParam.format === "json") {
+      validateJsonSecret(secretParam.name, secretValue);
+    }
     await secretManager.createSecret(projectId, secretParam.name, secretLabels());
     await secretManager.addVersion(projectId, secretParam.name, secretValue);
-    return secretValue;
+    return;
   } else if (!metadata.secretVersion) {
     throw new FirebaseError(
       `Cloud Secret Manager has no latest version of the secret defined by param ${

src/functions/secrets.ts

@@ -87,6 +87,26 @@ export async function ensureValidKey(key: string, options: Options): Promise<str
   return transformedKey;
 }
 
+/**
+ * Validates that a secret value is valid JSON and throws a helpful error if not.
+ * @param secretName The name of the secret being validated
+ * @param secretValue The value to validate
+ * @throws FirebaseError if the value is not valid JSON
+ */
+export function validateJsonSecret(secretName: string, secretValue: string): void {
+  try {
+    JSON.parse(secretValue);
+  } catch (e: any) {
+    throw new FirebaseError(
+      `Provided value for ${secretName} is not valid JSON: ${e.message}\n\n` +
+        `For complex JSON values, use:\n` +
+        `  firebase functions:secrets:set ${secretName} --data-file <file.json>\n` +
+        `Or pipe from stdin:\n` +
+        `  cat <file.json> | firebase functions:secrets:set ${secretName} --format=json`,
+    );
+  }
+}
+
 /**
  * Ensure secret exists. Optionally prompt user to have non-Firebase managed keys be managed by Firebase.
  */

src/utils.ts

@@ -890,7 +890,7 @@ export function generatePassword(n = 20): string {
 
 /**
  * Reads a secret value from either a file or a prompt.
- * If dataFile is falsy and this is a tty, uses prompty. Otherwise reads from dataFile.
+ * If dataFile is falsy and this is a tty, uses prompt. Otherwise reads from dataFile.
  * If dataFile is - or falsy, this means reading from file descriptor 0 (e.g. pipe in)
  */
 export function readSecretValue(prompt: string, dataFile?: string): Promise<string> {