@catladder/cli 0.0.0-next-4e7c6848 → 0.0.0-next-8b9ad5ca

package/src/vault/cache.ts

@@ -0,0 +1,80 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { getProjectRootPath } from "../git/gitProjectInformation";
+
+/**
+ * hierarchical: env -> componentName -> key -> value.
+ * Only the "local" env is ever cached — other envs' secrets have no
+ * business sitting on developer machines.
+ *
+ * `null` records a declared secret that was absent in the vault at the
+ * last refresh (e.g. deploy credentials that intentionally don't exist
+ * for local) — a known miss, so it doesn't force re-contacting the
+ * vault on every run.
+ */
+export type CachedSecrets = {
+  [env: string]: { [componentName: string]: { [key: string]: string | null } };
+};
+
+/**
+ * local, project-scoped cache of the vault secrets, so that frequent
+ * catenv runs don't have to contact the vault (e.g. unlock bitwarden)
+ * every time. Plaintext — like the .env files catenv writes anyway —
+ * but never committed (the folder ignores itself).
+ */
+type SecretsCache = {
+  /** the vault this cache was filled from */
+  vaultId: string;
+  updatedAt: string;
+  secrets: CachedSecrets;
+};
+
+const getCacheFolder = async () =>
+  join(await getProjectRootPath(), ".catladder");
+
+const getCachePath = async () => join(await getCacheFolder(), "secrets.json");
+
+export const readSecretsCache = async (): Promise<SecretsCache | null> => {
+  try {
+    return JSON.parse(await readFile(await getCachePath(), "utf-8"));
+  } catch {
+    return null;
+  }
+};
+
+export const writeSecretsCache = async (
+  vaultId: string,
+  secrets: CachedSecrets,
+): Promise<void> => {
+  const folder = await getCacheFolder();
+  await mkdir(folder, { recursive: true });
+  // the folder ignores itself, so the cache can never be committed
+  await writeFile(join(folder, ".gitignore"), "*\n");
+  const cache: SecretsCache = {
+    vaultId,
+    updatedAt: new Date().toISOString(),
+    secrets,
+  };
+  await writeFile(await getCachePath(), JSON.stringify(cache, null, 2));
+};
+
+/**
+ * merges freshly written secrets of one env/component into the cache
+ * (write-through from config-secrets), so the next catenv run doesn't
+ * need the vault
+ */
+export const updateSecretsCache = async (
+  vaultId: string,
+  env: string,
+  componentName: string,
+  values: Record<string, string>,
+): Promise<void> => {
+  const existing = await readSecretsCache();
+  const secrets: CachedSecrets =
+    existing?.vaultId === vaultId ? existing.secrets : {};
+  secrets[env] = {
+    ...secrets[env],
+    [componentName]: { ...secrets[env]?.[componentName], ...values },
+  };
+  await writeSecretsCache(vaultId, secrets);
+};

package/src/vault/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./VaultManager";
+export { GitlabVault } from "./GitlabVault";
+export { BitwardenVault } from "./BitwardenVault";
+export { updateSecretsCache } from "./cache";

package/src/vault/types.ts

@@ -0,0 +1,42 @@
+import type { IO } from "../core/types";
+
+/**
+ * a secrets vault is the readable source of truth for secret values.
+ * CI backends (gitlab variables, github secrets) only receive mirrored
+ * copies of what is stored here.
+ */
+export type SecretsVault = {
+  /**
+   * identity of the vault (incl. its config), used to invalidate the
+   * local cache when the vault changes
+   */
+  id: string;
+
+  /**
+   * all secrets as a flat map of raw secret variable names
+   * (CL_<ENV>_<COMPONENT>_<KEY>) to values
+   */
+  readAllSecrets(io: IO | null): Promise<Record<string, string>>;
+
+  /**
+   * upserts the secrets of one env and component
+   * (keys as declared in the config, not the raw variable names)
+   */
+  writeSecrets(
+    io: IO,
+    env: string,
+    componentName: string,
+    secrets: Record<string, unknown>,
+  ): Promise<void>;
+};
+
+/**
+ * how secret resolution may interact with the vault:
+ * - auto (default): contact the vault when the local cache is
+ *   incomplete, prompting to unlock if necessary
+ * - no-prompt: contact the vault only if that needs no interaction;
+ *   fail on missing secrets instead of prompting to unlock
+ * - offline: never contact the vault, use only the local cache
+ * - refresh: ignore the local cache once and refresh it from the vault
+ */
+export type SecretsMode = "auto" | "no-prompt" | "offline" | "refresh";