@pithy-sh/secrets 0.1.0

package/src/dev/devSecretsFile.ts

@@ -0,0 +1,167 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { VersionedValue } from "../crypto/versionedValue";
+
+/**
+ * The dev secrets file — the one hand-edited input for **local dev** secret values, and the format
+ * of the file the CLI seeds from.
+ *
+ * `.dev.vars` is what wrangler says it is: env bindings, `UPPER_SNAKE`, in the worker's directory
+ * because wrangler reads it there. Secrets live here instead, keyed by the **registry secret name
+ * verbatim** — `<capability>-<what>`, kebab — because that name is the join key into the registry,
+ * and a mapping table between the two would be one more thing to rot.
+ *
+ * **Nothing in this file names a destination.** The registry already knows each secret's `backend`,
+ * so the seeder derives where a value goes, and the file and the registry can never disagree.
+ *
+ * **And nothing here names its location, either.** Since #156 the file is machine-local, at
+ * `<config>/<project>/secrets.jsonc` — outside every checkout, resolved by the CLI. This package is
+ * Workers-runtime code with no `node:` imports and no filesystem: it parses text and returns what
+ * should be written. The path a caller passes is for error messages, and is always absolute in
+ * practice; {@link DEV_SECRETS_FILE} is only what an error says when a caller named nothing.
+ */
+
+/** The file's bare name, for an error raised by a caller that passed no path. Mode `0600`. */
+export const DEV_SECRETS_FILE = "secrets.jsonc";
+
+/**
+ * The envelope, spelled out, so every error can show the shape rather than describe it.
+ *
+ * Here rather than in one reader, because two readers now say it — the loader and the payload reader —
+ * and a shape quoted twice is a shape that will be quoted two ways.
+ */
+export const ENVELOPE_SHAPE = '{ "currentVersion": "1", "versions": { "1": <value> } }';
+
+/**
+ * The committed example — the one artifact about secrets that stays in an adopter's repository, and
+ * documentation only. It is never copied to a working file: `pithy add` writes the real one, outside
+ * the checkout, and there is nothing in the project for it to sit beside.
+ */
+export const DEV_SECRETS_EXAMPLE_FILE = ".dev.secrets.example.jsonc";
+
+/**
+ * ## The rule, stated once (#323)
+ *
+ * **A secret's entry in this file is the precise payload its destination receives. Nothing wraps it,
+ * nothing unwraps it, and no secret is an exception.**
+ *
+ * The registry says what that payload is, per secret, and `devSecretPayload` (`./seedDevSecrets`) is
+ * the one reading of it:
+ *
+ * | secret | destination | payload |
+ * |---|---|---|
+ * | any ordinary secret | a D1 row, a `.dev.vars` line, a Secrets Store entry | a {@link DevSecretEnvelope} |
+ * | a `bootstrap` secret | its binding, read before any decoder exists | the value itself |
+ *
+ * There is one widening, for the person hand-editing the file: a `json` value is written as its own
+ * structure rather than as an escaped string inside a string, and the reader serializes it on the way
+ * out. That is a JSON-in-JSON concession, not a wrapper — nothing is added and nothing is removed.
+ *
+ * **Why `bootstrap` is not an exception to the rule but an instance of it.** `SECRETS_ENCRYPTION_KEYS`
+ * is what the envelope decoder needs in order to exist, so its binding has always carried a bare
+ * `EncryptionConfig` and `resolveEncryptionConfig` has always parsed one. The file used to state an
+ * envelope around it and the seeder used to take that envelope off again — a `currentVersion` for one
+ * concept written twice, carrying no information, and reported as file corruption by two readers in a
+ * row. Now the file states what the binding gets.
+ */
+
+/**
+ * One secret's value in the file, for **every secret whose destination receives an envelope** — which
+ * is every secret that is not `bootstrap`. Always full, even for a single-version text secret.
+ *
+ * **This is the whole reason the format is unambiguous, not ceremony — do not "simplify" it away.**
+ * With optional envelopes a JSON-valued secret's own object cannot be told apart from an envelope
+ * without a marker or a heuristic: `{ "clientId": …, "clientSecret": … }` and
+ * `{ "currentVersion": …, "versions": … }` are both just objects. Requiring the envelope wherever the
+ * destination takes one means the outer object is *always* the envelope, and a JSON secret's own
+ * object sits unambiguously inside `versions`. It also matches what is actually stored, so dev stops
+ * being a shape production never sees — and `pithy secrets rotate --env dev` exercises the real
+ * rotation path. **The registry, not a heuristic, is what says which secrets those are.**
+ *
+ * The shape is {@link VersionedValue}'s, widened in exactly one place: a stored version is a string
+ * (a `json` secret stores its serialized form), while a hand-written one is the value itself, so that
+ * an adopter writes real structure rather than an escaped string inside a string. The seeder converts,
+ * validating each version against the registry entry's schema on the way.
+ *
+ * **Strict, and that is what makes the guarantee above true (#323).** Stripping unknown keys instead
+ * of refusing them is the same permissiveness the doc argues against, arriving by the back door: an
+ * `EncryptionConfig` is `{ currentVersion, versions, lastRotatedAt }`, a structural *superset* of an
+ * envelope, so a stripping parser accepted `SECRETS_ENCRYPTION_KEYS`' own value written bare, dropped
+ * `lastRotatedAt`, and left a base64 string where a nested object belongs. The failure then surfaced
+ * three frames later, naming neither the file nor the secret. Refusing here says it once, in place.
+ */
+export const DevSecretEnvelope = VersionedValue.extend({
+  versions: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "Every still-valid version: version key (a stringified integer) → the value itself — a string for a `text` secret, its own object for a `json` one. Always at least one entry.",
+    ),
+})
+  .strict()
+  .describe(
+    "One secret's value in the dev secrets file, for every secret whose destination receives an envelope: an explicit current-version pointer plus every still-valid version, and nothing else. Always full, never partial.",
+  );
+export type DevSecretEnvelope = z.output<typeof DevSecretEnvelope>;
+
+/**
+ * What was found where an envelope belongs, as one clause for the caller's sentence — `it carries
+ * lastRotatedAt …`, `it is a string`, `it has no versions`.
+ *
+ * **Keys and types only, never a value.** The reason a shape error is worth saying at all is that the
+ * adopter is looking at a file they hand-wrote; the reason it must say this much and no more is that
+ * the same file holds OAuth client secrets, and this sentence reaches a terminal and a log.
+ */
+export function describeNotEnvelope(value: unknown, error: z.ZodError): string {
+  if (value === null) return "it is null";
+  if (Array.isArray(value)) return "it is an array";
+  if (typeof value !== "object") return `it is a ${typeof value}`;
+  const unrecognized = error.issues.flatMap(unrecognizedKeys).sort();
+  if (unrecognized.length > 0) {
+    return `it carries ${unrecognized.join(", ")} beside currentVersion and versions, so it is a value's own object rather than an envelope around one`;
+  }
+  const absent = ["currentVersion", "versions"].filter((key) => !Object.hasOwn(value, key));
+  if (absent.length > 0) return `it has no ${absent.join(" and no ")}`;
+  return "currentVersion must be a string and versions a map of version key to value";
+}
+
+/** The keys one `unrecognized_keys` issue names, or none — narrowed rather than cast (no `any`). */
+function unrecognizedKeys(issue: z.core.$ZodIssue): string[] {
+  if (issue.code !== "unrecognized_keys") return [];
+  return issue.keys.filter((key): key is string => typeof key === "string");
+}
+
+/**
+ * The whole file: registry secret name → **payload**. A record rather than a fixed object, because the
+ * declared set is whatever capabilities the project composes — the registry is the authority on that,
+ * not this schema.
+ *
+ * **The value is `unknown` here, and that is the shape of the rule rather than a gap in it (#323).**
+ * Which payload a name takes is the registry's answer, not this schema's: an ordinary secret's is a
+ * {@link DevSecretEnvelope}, a `bootstrap` secret's is its own value. A schema that named one of them
+ * for every entry would be the wrapper this issue removed, written as a type. `devSecretPayload`
+ * (`./seedDevSecrets`) is where a name and a registry entry meet, and it is the kit's only payload reader.
+ */
+export const DevSecretsFile = z
+  .record(z.string(), z.unknown())
+  .describe(
+    "The parsed dev secrets file: registry secret name (`<capability>-<what>`) → the exact payload its destination receives. The registry decides which shape that is, and where the value is seeded.",
+  );
+export type DevSecretsFile = z.output<typeof DevSecretsFile>;
+
+/**
+ * The entry a freshly-minted dev value is written into the file as — **the payload its destination
+ * receives**, and nothing around it.
+ *
+ * For an ordinary secret that is a one-version envelope, the counterpart of `initialVersionedValue`
+ * over the file's wider version type. For a `bootstrap` secret it is the value, because the value is
+ * what its binding carries.
+ *
+ * **Every writer goes through here.** `pithy add secrets`, the provisioners and the seeder's own mint
+ * all call it, so there is one statement of what a fresh entry looks like. A second
+ * writer composing the envelope inline is how #323 got two shapes for one file.
+ */
+export function initialDevSecret(entry: { bootstrap?: boolean }, value: unknown): unknown {
+  return entry.bootstrap === true ? value : { currentVersion: "1", versions: { "1": value } };
+}

package/src/dev/loadDevSecrets.ts

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { parse } from "comment-json";
+import type { SecretRegistry } from "../registry";
+import { DEV_SECRETS_FILE, DevSecretsFile, ENVELOPE_SHAPE } from "./devSecretsFile";
+import { devSecretPayload } from "./seedDevSecrets";
+
+/**
+ * The dev secrets file boundary. Text in, a validated {@link DevSecretsFile} out — and every way
+ * the text can be wrong comes back as a `ValidationError` that names **which secret** and what to do.
+ * A Zod dump is not an answer to "my app will not start": the adopter hand-writes this file, so the
+ * error has to read like the fix.
+ *
+ * **JSONC**, parsed with `comment-json`, so the comments that say what a secret is for and the
+ * trailing comma left behind by deleting a line both survive. The parse is comment-stripping: this
+ * returns data. A caller writing minted values back re-parses with `comment-json` and edits that
+ * tree, which is how an adopter's comments survive a write.
+ *
+ * **Bytes are the caller's problem.** This package is Workers-runtime code and holds no `node:`
+ * imports; the CLI reads the file (and owns its `0600` mode, and its absence meaning "no secrets
+ * yet"). The same rule the seeder follows for `.dev.vars`: return what should be written, never write.
+ *
+ * **The registry is optional here, and what it buys is exactly the shape check (#323).** Which payload
+ * a name takes — an envelope, or the value itself for a `bootstrap` secret — is the registry's answer,
+ * so a loader without one cannot judge a slot and does not pretend to: it establishes that the text is
+ * a JSONC object of secret names, and `devSecretPayload` judges each value where the registry is in
+ * hand. Given a registry, it asks that same function per declared name, so a bad shape is caught at
+ * the boundary and in one wording. A name the registry does not declare is left alone either way —
+ * a removed capability must not brick dev, and `seedDevSecrets` reports it as undeclared.
+ */
+
+/** Options for {@link loadDevSecrets}. */
+export interface LoadDevSecretsOptions {
+  /**
+   * The path to name in errors — the one the caller read, so a message points at a real file in a
+   * multi-project checkout. Defaults to {@link DEV_SECRETS_FILE}.
+   */
+  path?: string;
+  /**
+   * The project's registry, when the caller has one. Every declared name's value is then checked
+   * against the payload its destination takes, which is the only way that question has an answer.
+   *
+   * Absent for a caller that has no project loaded — `pithy secrets edit` on a project whose config
+   * will not load is the case that matters, and it is the command an adopter reaches for to *fix* that.
+   */
+  registry?: SecretRegistry;
+}
+
+/**
+ * Parse and validate the dev secrets file. Throws `validation/invalid_input` naming the offending
+ * secret. Nothing thrown from here carries a value: `message`, `action` and `detail` all reach a
+ * terminal or a log, and the file holds OAuth client secrets.
+ */
+export function loadDevSecrets(source: string, options: LoadDevSecretsOptions = {}): DevSecretsFile {
+  const path = options.path ?? DEV_SECRETS_FILE;
+
+  // A file with nothing in it is a project with no secrets yet — the same answer an absent file gets,
+  // and the same one the write path already gives when it merges a mint into empty content. A
+  // `touch`ed file used to fail `pithy add` outright, which is one state with two answers.
+  if (source.trim().length === 0) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = parse(source, undefined, true);
+  } catch (cause) {
+    // **No `cause`, deliberately.** `comment-json`'s `SyntaxError` reads `Unexpected token '"', "{ …
+    // the entire file … }" is not valid JSON` — it embeds the source, so attaching it would carry
+    // every OAuth client secret in the file into whatever logs or prints the error chain. The
+    // position is kept, because a line and a column are not a value.
+    throw new ValidationError({
+      message: `${path} is not valid JSONC.`,
+      // **No command named here.** It said "run pithy seed", and the seed is rarely what failed —
+      // `pithy dev`, `pithy add` and `pithy secrets edit` all read this file, and the last of those
+      // printed advice to run itself while the adopter was inside it (#157). This function does not
+      // know which command is running, so it says what is wrong and leaves the command to the caller.
+      // The path is in `message`, which is what an adopter actually needs: the file is outside the
+      // checkout (#156), so naming it is the difference between a fixable fault and a hunt.
+      action: "Fix the syntax and try again. Comments and trailing commas are fine; unquoted keys are not.",
+      detail: `dev secrets file '${path}' failed to parse${position(cause)}`,
+    });
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ValidationError({
+      message: `${path} must be an object of secret name to value.`,
+      action: `Write each secret as "<capability>-<what>": the payload its destination receives — ${ENVELOPE_SHAPE} for an ordinary secret.`,
+      detail: `dev secrets file '${path}' top level is ${Array.isArray(parsed) ? "an array" : typeof parsed}`,
+    });
+  }
+
+  const file: DevSecretsFile = {};
+  const registry = options.registry;
+  for (const [name, value] of Object.entries(parsed as Record<string, unknown>)) {
+    // The registry entry, or nothing. `Object.hasOwn`, never `in`: `in` walks the prototype chain, so a
+    // secret named `toString` would be judged against an `Object.prototype` member.
+    const entry = registry && Object.hasOwn(registry, name) ? registry[name] : undefined;
+    // A name with no value at all, which is knowable without a registry and is the one shape check left
+    // here. `comment-json` parses `{ "a-b": }` to `undefined` rather than refusing it, so a half-deleted
+    // line reached the seeder as a declared secret holding nothing.
+    if (value === undefined) {
+      throw new ValidationError({
+        message: `Secret '${name}' in ${path} has no value.`,
+        action: `Give it one, or delete the line. An ordinary secret's is ${ENVELOPE_SHAPE}.`,
+        detail: `dev secrets file '${path}': '${name}' has no value`,
+      });
+    }
+    // Judged, and then discarded: what this returns is the file's own values, not the converted ones.
+    // A keyspace is not judged at all — it has no single value, and `seedDevSecrets` owns that refusal.
+    if (entry && !entry.keyed) devSecretPayload(entry, name, value, path);
+    file[name] = value;
+  }
+  return DevSecretsFile.parse(file);
+}
+
+/**
+ * The parse error's position, as ` at line L column C`, or nothing when the parser did not give one.
+ *
+ * The only part of a `SyntaxError` from `comment-json` that is safe to repeat. Its `message` quotes
+ * the source it choked on — the whole file — so nothing else from it is carried anywhere.
+ */
+function position(cause: unknown): string {
+  if (typeof cause !== "object" || cause === null) return "";
+  const { line, column } = cause as { line?: unknown; column?: unknown };
+  if (typeof line !== "number" || typeof column !== "number") return "";
+  return ` at line ${line} column ${column}`;
+}