@checkstack/secrets-common 0.1.0

package/src/masking.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "bun:test";
+import {
+  maskSecrets,
+  maskSecretsDeep,
+  DEFAULT_MASK_TOKEN,
+  MIN_MASKABLE_LENGTH,
+} from "./masking";
+
+describe("maskSecrets", () => {
+  it("redacts a literal secret value anywhere in the text", () => {
+    const out = maskSecrets({
+      text: "connecting with token=s3cret-token-value done",
+      values: ["s3cret-token-value"],
+    });
+    expect(out).toBe(`connecting with token=${DEFAULT_MASK_TOKEN} done`);
+    expect(out).not.toContain("s3cret-token-value");
+  });
+
+  it("redacts every occurrence, not just the first", () => {
+    const out = maskSecrets({
+      text: "a=topsecret b=topsecret c=topsecret",
+      values: ["topsecret"],
+    });
+    expect(out).toBe("a=**** b=**** c=****");
+  });
+
+  it("masks a script echoing its own injected secret (leak guard)", () => {
+    // Simulates a user script that does `console.log(process.env.API_TOKEN)`.
+    const stdout = "API_TOKEN is gh_aBcDeF123456 and nothing else";
+    const out = maskSecrets({ text: stdout, values: ["gh_aBcDeF123456"] });
+    expect(out).not.toContain("gh_aBcDeF123456");
+    expect(out).toContain("API_TOKEN is **** and nothing else");
+  });
+
+  it("skips trivially-short values to avoid over-masking", () => {
+    const shortValue = "ab"; // below MIN_MASKABLE_LENGTH
+    expect(shortValue.length).toBeLessThan(MIN_MASKABLE_LENGTH);
+    const out = maskSecrets({
+      text: "absolutely fabulous tabular",
+      values: [shortValue],
+    });
+    expect(out).toBe("absolutely fabulous tabular");
+  });
+
+  it("masks a value at exactly the minimum length boundary", () => {
+    const value = "a".repeat(MIN_MASKABLE_LENGTH); // exactly 4 chars -> masked
+    const out = maskSecrets({ text: `x=${value}`, values: [value] });
+    expect(out).toBe("x=****");
+    const tooShort = "a".repeat(MIN_MASKABLE_LENGTH - 1); // 3 chars -> skipped
+    expect(maskSecrets({ text: `y=${tooShort}`, values: [tooShort] })).toBe(
+      `y=${tooShort}`,
+    );
+  });
+
+  it("redacts a value embedded mid-string with no surrounding whitespace", () => {
+    const out = maskSecrets({
+      text: "prefix" + "tok-abcdef" + "suffix",
+      values: ["tok-abcdef"],
+    });
+    expect(out).toBe("prefix****suffix");
+  });
+
+  it("redacts a value across multiple lines of output", () => {
+    const out = maskSecrets({
+      text: "line1 sk-live-9999\nline2 sk-live-9999\nclean",
+      values: ["sk-live-9999"],
+    });
+    expect(out).toBe("line1 ****\nline2 ****\nclean");
+  });
+
+  it("DOCUMENTED LIMIT: an encoded/transformed form of a secret is NOT masked", () => {
+    const secret = "topsecretvalue";
+    const base64 = Buffer.from(secret).toString("base64");
+    // Masking is by literal occurrence only. A script that base64-encodes a
+    // secret before printing it defeats masking — this is the documented
+    // limitation, asserted here so the contract is explicit + regression-safe.
+    const out = maskSecrets({
+      text: `encoded=${base64} raw=${secret}`,
+      values: [secret],
+    });
+    expect(out).toContain(base64); // encoded form survives (NOT masked)
+    expect(out).toContain("raw=****"); // literal form IS masked
+    expect(out).not.toContain(`raw=${secret}`);
+  });
+
+  it("masks longer values before shorter overlapping ones", () => {
+    // "supersecret" contains "secret"; both are secrets. The whole long
+    // value must be redacted as one unit, not partially by the short one.
+    const out = maskSecrets({
+      text: "value=supersecret",
+      values: ["secret", "supersecret"],
+    });
+    expect(out).toBe("value=****");
+  });
+
+  it("supports a custom token", () => {
+    const out = maskSecrets({
+      text: "pw=hunter2pw",
+      values: ["hunter2pw"],
+      token: "[REDACTED]",
+    });
+    expect(out).toBe("pw=[REDACTED]");
+  });
+
+  it("returns text unchanged when no secret occurs", () => {
+    const out = maskSecrets({ text: "nothing here", values: ["absent-value"] });
+    expect(out).toBe("nothing here");
+  });
+
+  it("dedupes values without error", () => {
+    const out = maskSecrets({
+      text: "x=dup-value-here y=dup-value-here",
+      values: ["dup-value-here", "dup-value-here"],
+    });
+    expect(out).toBe("x=**** y=****");
+  });
+});
+
+describe("maskSecretsDeep", () => {
+  it("masks strings in nested objects and arrays", () => {
+    const out = maskSecretsDeep({
+      value: {
+        log: ["line with topsecretvalue", "clean line"],
+        nested: { token: "topsecretvalue" },
+        count: 3,
+      },
+      values: ["topsecretvalue"],
+    });
+    expect(out).toEqual({
+      log: ["line with ****", "clean line"],
+      nested: { token: "****" },
+      count: 3,
+    });
+  });
+
+  it("masks object keys too", () => {
+    const out = maskSecretsDeep({
+      value: { topsecretvalue: 1 },
+      values: ["topsecretvalue"],
+    });
+    expect(out).toEqual({ "****": 1 });
+  });
+
+  it("returns the value unchanged when no maskable values are given", () => {
+    const value = { a: "short", b: ["x"] };
+    expect(maskSecretsDeep({ value, values: ["ab"] })).toBe(value);
+  });
+
+  it("leaves non-string leaves untouched", () => {
+    const out = maskSecretsDeep({
+      value: { n: 42, b: true, z: null },
+      values: ["topsecretvalue"],
+    });
+    expect(out).toEqual({ n: 42, b: true, z: null });
+  });
+});

package/src/masking.ts

@@ -0,0 +1,111 @@
+/**
+ * Jenkins-style by-value secret masking.
+ *
+ * This is the platform's non-negotiable leak guarantee: any text returned
+ * to a user or persisted is scanned for known secret values and every
+ * literal occurrence is replaced with a redaction token.
+ *
+ * Documented limit: only LITERAL occurrences are masked. Encoded or
+ * transformed forms of a secret (base64, hashed, URL-encoded, split
+ * across lines) cannot be detected — scripts must not transform-then-print
+ * a secret they were given.
+ */
+
+/** Default redaction token. */
+export const DEFAULT_MASK_TOKEN = "****";
+
+/**
+ * Values shorter than this are NOT masked. Trivially short secrets (e.g.
+ * a 1-3 char value) would over-mask unrelated coincidental substrings of
+ * normal output, corrupting it. Anything below the threshold is skipped.
+ */
+export const MIN_MASKABLE_LENGTH = 4;
+
+/**
+ * Replace every literal occurrence of each known secret value in `text`
+ * with `token`. Pure and synchronous.
+ *
+ * - Skips values shorter than {@link MIN_MASKABLE_LENGTH}.
+ * - Longer values are masked first, so a secret that contains a shorter
+ *   secret as a substring is fully redacted before the shorter one runs.
+ * - `values` is the run-scoped, least-privilege set — only the consumer's
+ *   resolved secrets, never the whole secret store.
+ *
+ * @returns The text with all qualifying secret values redacted.
+ */
+export function maskSecrets({
+  text,
+  values,
+  token = DEFAULT_MASK_TOKEN,
+}: {
+  text: string;
+  values: Iterable<string>;
+  token?: string;
+}): string {
+  return maskString(text, toMaskable(values), token);
+}
+
+/**
+ * Dedupe + drop trivially-short values, then sort longest-first so a value
+ * that embeds a shorter value is redacted as a whole. Shared by both the
+ * text and deep entry points so the maskable-set policy lives in one place.
+ */
+function toMaskable(values: Iterable<string>): string[] {
+  return [...new Set(values)]
+    .filter((value) => value.length >= MIN_MASKABLE_LENGTH)
+    .toSorted((a, b) => b.length - a.length);
+}
+
+/**
+ * Recursively mask secret values in an arbitrary JSON-like payload. Walks
+ * strings, arrays, and plain objects; non-string leaves are returned
+ * unchanged. Used to redact structured result payloads (e.g. an
+ * automation run step's `result_payload`) before persist/return.
+ *
+ * Object KEYS are masked too — a script that returns `{ "<secret>": 1 }`
+ * would otherwise leak the value through the key.
+ */
+export function maskSecretsDeep({
+  value,
+  values,
+  token = DEFAULT_MASK_TOKEN,
+}: {
+  value: unknown;
+  values: Iterable<string>;
+  token?: string;
+}): unknown {
+  const maskable = toMaskable(values);
+
+  if (maskable.length === 0) {
+    return value;
+  }
+
+  return walk(value, maskable, token);
+}
+
+function walk(value: unknown, maskable: string[], token: string): unknown {
+  if (typeof value === "string") {
+    return maskString(value, maskable, token);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => walk(item, maskable, token));
+  }
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[maskString(key, maskable, token)] = walk(val, maskable, token);
+    }
+    return result;
+  }
+  return value;
+}
+
+function maskString(text: string, maskable: string[], token: string): string {
+  let result = text;
+  for (const value of maskable) {
+    if (result.includes(value)) {
+      result = result.split(value).join(token);
+    }
+  }
+  return result;
+}

package/src/metadata.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/**
+ * Public metadata for a secret. NEVER carries the value — only the name,
+ * a human description, provenance, and `hasValue` (whether a value is
+ * currently stored). This is the only shape that crosses to a browser.
+ */
+export const secretMetadataSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  /** Whether a value is currently stored for this secret. */
+  hasValue: z.boolean(),
+  /** Backend id that owns this secret (e.g. "local", "vault"). */
+  backend: z.string(),
+  createdBy: z.string().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+export type SecretMetadata = z.infer<typeof secretMetadataSchema>;

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Secrets platform. Exported from common so both
+ * backend and frontend reference the same `pluginId`.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "secrets",
+});

package/src/routes.ts

@@ -0,0 +1,8 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the Secrets admin UI (Settings → Secrets).
+ */
+export const secretsRoutes = createRoutes("secrets", {
+  home: "/",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,108 @@
+import { createClientDefinition, proc } from "@checkstack/common";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+import { secretsAccess } from "./access";
+import { secretNameSchema } from "./secret-field";
+import { secretMetadataSchema } from "./metadata";
+import {
+  backendConfigDtoSchema,
+  setBackendConfigInputSchema,
+  testBackendResultSchema,
+} from "./backend-config";
+
+/**
+ * Secrets platform RPC contract.
+ *
+ * Hard rule: NO endpoint ever returns a secret VALUE to a browser client.
+ * `listSecrets` returns metadata only (`hasValue`, never the value);
+ * `listSecretNames` returns names only. Resolution to values is a
+ * service-typed, internal `secretResolverRef` method, not part of this
+ * contract.
+ */
+export const secretsContract = {
+  /** List secrets as metadata only (names, descriptions, `hasValue`). */
+  listSecrets: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [secretsAccess.secret.read],
+  }).output(z.array(secretMetadataSchema)),
+
+  /**
+   * List secret names only. Used by the editor `${{ secrets.* }}`
+   * autocomplete and the secret→env mapping UI. Never returns values.
+   */
+  listSecretNames: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [secretsAccess.secret.read],
+  }).output(z.array(z.string())),
+
+  /**
+   * Create or rotate a secret. Write-only: the value is accepted as input
+   * and stored encrypted; it is never returned by any endpoint. If a
+   * secret with `name` already exists its value is rotated.
+   */
+  setSecret: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [secretsAccess.secret.manage],
+  })
+    .input(
+      z.object({
+        name: secretNameSchema,
+        value: z.string().min(1),
+        description: z.string().optional(),
+      }),
+    )
+    .output(z.object({ id: z.string(), name: z.string() })),
+
+  /** Delete a secret by name. */
+  deleteSecret: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [secretsAccess.secret.manage],
+  })
+    .route({ method: "DELETE" })
+    .input(z.object({ name: secretNameSchema }))
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * Active backend configuration (metadata only). Never returns backend
+   * auth credentials or any secret value.
+   */
+  getBackendConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [secretsAccess.secret.read],
+  }).output(backendConfigDtoSchema),
+
+  /**
+   * Select the active backend and (for Vault) configure the connection.
+   * The Vault auth credential is write-only — accepted here, stored
+   * encrypted, never returned. `manage`-gated.
+   */
+  setBackendConfig: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [secretsAccess.secret.manage],
+  })
+    .input(setBackendConfigInputSchema)
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * Validate connectivity / auth for a backend (the active one, or the id
+   * given). Returns status only — never a secret value.
+   */
+  testBackend: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [secretsAccess.secret.manage],
+  })
+    .input(z.object({ backend: z.string().optional() }))
+    .output(testBackendResultSchema),
+};
+
+export type SecretsContract = typeof secretsContract;
+
+/** Type-safe client definition for `forPlugin` usage. */
+export const SecretsApi = createClientDefinition(secretsContract, pluginMetadata);

package/src/secret-field.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "bun:test";
+import {
+  secretNameSchema,
+  secretTemplateSchema,
+  collectSecretNames,
+} from "./secret-field";
+import { secretEnvMappingSchema } from "./env-mapping";
+
+describe("secretNameSchema", () => {
+  it("accepts valid names", () => {
+    for (const name of ["jira_token", "API-KEY", "a", "Db1"]) {
+      expect(secretNameSchema.safeParse(name).success).toBe(true);
+    }
+  });
+
+  it("rejects names not starting with a letter or with bad chars", () => {
+    for (const name of ["1token", "_x", "has space", "dot.name", ""]) {
+      expect(secretNameSchema.safeParse(name).success).toBe(false);
+    }
+  });
+});
+
+describe("secretTemplateSchema", () => {
+  it("accepts a ${{ secrets.NAME }} reference", () => {
+    expect(secretTemplateSchema.safeParse("${{ secrets.DB_PASS }}").success).toBe(
+      true,
+    );
+    expect(
+      secretTemplateSchema.safeParse("prefix-${{ secrets.X }}-suffix").success,
+    ).toBe(true);
+  });
+
+  it("rejects strings without a reference", () => {
+    expect(secretTemplateSchema.safeParse("plain").success).toBe(false);
+  });
+});
+
+describe("collectSecretNames", () => {
+  it("collects unique names from a nested value tree", () => {
+    const names = collectSecretNames({
+      value: {
+        a: "${{ secrets.ONE }}",
+        b: ["x", "${{ secrets.TWO }}"],
+        c: { d: "u:${{ secrets.ONE }}@${{ secrets.THREE }}" },
+      },
+    });
+    expect([...names].sort()).toEqual(["ONE", "THREE", "TWO"]);
+  });
+});
+
+describe("secretEnvMappingSchema", () => {
+  it("accepts env→template maps", () => {
+    const res = secretEnvMappingSchema.safeParse({
+      API_TOKEN: "${{ secrets.jira_token }}",
+      _PRIVATE: "${{ secrets.x }}",
+    });
+    expect(res.success).toBe(true);
+  });
+
+  it("rejects bad env names", () => {
+    expect(
+      secretEnvMappingSchema.safeParse({ "bad name": "${{ secrets.x }}" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("tolerates a bare secret name (accepted unchanged; normalized at use)", () => {
+    // A bare name (e.g. authored via YAML shorthand or legacy data) is now
+    // accepted. The schema is a plain union with NO transform (so it stays
+    // representable in JSON Schema for the plugin config UI); the bare name is
+    // normalized to `${{ secrets.NAME }}` later, at the consumption boundary
+    // (`normalizeSecretEnvValue`), not on parse.
+    const res = secretEnvMappingSchema.safeParse({ TOKEN: "not-a-template" });
+    expect(res.success).toBe(true);
+    if (res.success) {
+      expect(res.data).toEqual({ TOKEN: "not-a-template" });
+    }
+  });
+
+  it("rejects a value that is neither a template nor a valid secret name", () => {
+    // Spaces / leading digit are not a valid bare name and not a template.
+    expect(
+      secretEnvMappingSchema.safeParse({ TOKEN: "not a template" }).success,
+    ).toBe(false);
+    expect(
+      secretEnvMappingSchema.safeParse({ TOKEN: "1bad" }).success,
+    ).toBe(false);
+  });
+});

package/src/secret-field.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+/**
+ * Valid characters for a secret name: must start with a letter, then
+ * letters, digits, underscores, and hyphens. This is the canonical
+ * definition for the whole platform — the legacy copy in
+ * `@checkstack/gitops-common` mirrors this regex (kept in sync).
+ *
+ * Must stay in sync with the capture group in {@link SECRET_TEMPLATE_REGEX}.
+ */
+export const SECRET_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+/**
+ * Zod schema for validating secret names at creation time.
+ * Ensures the name can be referenced via `${{ secrets.NAME }}`.
+ */
+export const secretNameSchema = z
+  .string()
+  .min(1)
+  .max(63)
+  .regex(
+    SECRET_NAME_REGEX,
+    "Secret names must start with a letter and contain only letters, digits, underscores, or hyphens",
+  );
+
+export type SecretName = z.infer<typeof secretNameSchema>;
+
+/**
+ * Regex matching `${{ secrets.NAME }}` template expressions in strings.
+ * Captures the secret name in group 1. Global so multiple occurrences in
+ * a single string are matched.
+ *
+ * @example
+ * "${{ secrets.DB_PASS }}" → captures "DB_PASS"
+ * "postgres://u:${{ secrets.PASS }}@${{ secrets.HOST }}/db" → "PASS", "HOST"
+ */
+export const SECRET_TEMPLATE_REGEX =
+  /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+
+/**
+ * Zod schema for validating secret template strings.
+ * Matches strings containing at least one `${{ secrets.NAME }}` pattern.
+ */
+export const secretTemplateSchema = z.string().regex(
+  /\$\{\{\s*secrets\.[a-zA-Z0-9_-]+\s*\}\}/,
+  "Must contain a ${{ secrets.NAME }} reference",
+);
+
+/**
+ * Recursively walks a value and collects all unique secret names
+ * referenced via `${{ secrets.NAME }}` patterns in string values.
+ *
+ * @returns Deduplicated array of secret names found in the value tree.
+ */
+export function collectSecretNames({ value }: { value: unknown }): string[] {
+  const names = new Set<string>();
+  collectFromValue(value, names);
+  return [...names];
+}
+
+function collectFromValue(value: unknown, names: Set<string>): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  if (typeof value === "string") {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = SECRET_TEMPLATE_REGEX.exec(value)) !== null) {
+      names.add(match[1]);
+    }
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectFromValue(item, names);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const val of Object.values(value)) {
+      collectFromValue(val, names);
+    }
+  }
+}

package/src/test-secret-env.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "bun:test";
+import { buildTestSecretEnv, secretTestPlaceholder } from "./test-secret-env";
+import { secretEnvMappingSchema } from "./env-mapping";
+
+describe("secretTestPlaceholder", () => {
+  it("formats a stable named placeholder", () => {
+    expect(secretTestPlaceholder("jira_token")).toBe("__SECRET_jira_token__");
+  });
+});
+
+describe("buildTestSecretEnv", () => {
+  it("uses placeholders by default and never resolves a real value", () => {
+    const { env, maskValues } = buildTestSecretEnv({
+      secretEnv: { API_TOKEN: "${{ secrets.jira_token }}" },
+    });
+    expect(env).toEqual({ API_TOKEN: "__SECRET_jira_token__" });
+    expect(maskValues).toEqual([]);
+  });
+
+  it("injects a user override and marks it for masking", () => {
+    const { env, maskValues } = buildTestSecretEnv({
+      secretEnv: { A: "${{ secrets.alpha }}", B: "${{ secrets.beta }}" },
+      secretOverrides: { beta: "real-override" },
+    });
+    expect(env).toEqual({ A: "__SECRET_alpha__", B: "real-override" });
+    expect(maskValues).toEqual(["real-override"]);
+  });
+
+  it("returns empty when no secretEnv is declared (least-privilege)", () => {
+    expect(buildTestSecretEnv({})).toEqual({ env: {}, maskValues: [] });
+    expect(buildTestSecretEnv({ secretOverrides: { x: "y" } })).toEqual({
+      env: {},
+      maskValues: [],
+    });
+  });
+
+  it("handles inline interpolation by using the first referenced secret", () => {
+    const { env } = buildTestSecretEnv({
+      secretEnv: { CONN: "user:${{ secrets.pw }}@host" },
+    });
+    expect(env.CONN).toBe("__SECRET_pw__");
+  });
+
+  it("injects placeholders for a bare-name mapping once normalized", () => {
+    // A `secretEnv` authored with a bare name (e.g. via YAML) is normalized
+    // to a template by the schema, then yields a `__SECRET_<NAME>__`
+    // placeholder in an override-less test (so `process.env.<env>` is set).
+    const normalized = secretEnvMappingSchema.parse({ secret: "SECRET" });
+    const noOverride = buildTestSecretEnv({ secretEnv: normalized });
+    expect(noOverride.env).toEqual({ secret: "__SECRET_SECRET__" });
+    expect(noOverride.maskValues).toEqual([]);
+
+    // With an explicit override, the override is injected and masked.
+    const withOverride = buildTestSecretEnv({
+      secretEnv: normalized,
+      secretOverrides: { SECRET: "test-value" },
+    });
+    expect(withOverride.env).toEqual({ secret: "test-value" });
+    expect(withOverride.maskValues).toEqual(["test-value"]);
+  });
+});