@checkstack/secrets-backend 0.1.0

package/src/index.ts

@@ -0,0 +1,236 @@
+import {
+  createBackendPlugin,
+  coreServices,
+  createServiceRef,
+} from "@checkstack/backend-api";
+import {
+  pluginMetadata,
+  secretsAccessRules,
+  secretsContract,
+} from "@checkstack/secrets-common";
+import type { PluginMetadata } from "@checkstack/common";
+import {
+  secretBackendExtensionPoint,
+  type SecretBackend,
+} from "./secret-backend";
+import {
+  createSecretBackendRegistry,
+  type SecretBackendRegistry,
+} from "./secret-backend-registry";
+import {
+  createSecretResolverService,
+  type SecretResolverService,
+} from "./resolver-service";
+import {
+  createSecretAdminService,
+  type SecretAdminService,
+} from "./admin-service";
+import {
+  createInternalSecretsService,
+  type InternalSecretsService,
+} from "./internal-secrets-service";
+import {
+  createBackendConfigStore,
+  type BackendConfigStore,
+} from "./backend-config-store";
+import { createActiveBackendStore } from "./active-backend";
+import { createSecretsRouter } from "./router";
+import { secretsChangedHook } from "./hooks";
+
+/** Built-in default backend id. The local backend plugin registers under this. */
+const DEFAULT_BACKEND_ID = "local";
+
+/**
+ * Cross-plugin secret resolution service. Consumer plugins (gitops,
+ * automation, healthcheck) inject this to resolve `${{ secrets.NAME }}`
+ * templates and a run's least-privilege env allowlist against the active
+ * backend. Service-typed and backend-only — never exposed to a browser.
+ */
+export const secretResolverRef = createServiceRef<SecretResolverService>(
+  "secrets.resolver",
+);
+
+/**
+ * Cross-plugin secret administration service. Consumers (e.g. gitops)
+ * inject this to manage secrets through the active backend so there is a
+ * single source of truth. Metadata/write only — never returns a value.
+ */
+export const secretAdminRef = createServiceRef<SecretAdminService>(
+  "secrets.admin",
+);
+
+/**
+ * Cross-plugin service for platform-INTERNAL secrets (registry token,
+ * connection credentials, …). Always backed by the local backend (never
+ * Vault, which is read-through), so internal writes never break when an
+ * external backend is active. Hidden from the user-facing Secrets UI.
+ * Backend-only — never exposed to a browser.
+ */
+export const internalSecretsRef = createServiceRef<InternalSecretsService>(
+  "secrets.internal",
+);
+
+interface EnvStash {
+  backends: SecretBackendRegistry;
+  configStore?: BackendConfigStore;
+  emitChanged?: (input: {
+    name: string;
+    change: "created" | "rotated" | "deleted";
+  }) => Promise<void>;
+}
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    const backends = createSecretBackendRegistry();
+    (env as unknown as EnvStash).backends = backends;
+
+    env.registerAccessRules(secretsAccessRules);
+
+    env.registerExtensionPoint(secretBackendExtensionPoint, {
+      registerSecretBackend: (
+        backend: SecretBackend,
+        _metadata: PluginMetadata,
+      ) => {
+        backends.register(backend);
+      },
+    });
+
+    // The active backend id is config-selected (persisted via the config
+    // store, set in `init`). Falls back to the local backend when no choice
+    // is persisted or the persisted choice is not currently registered.
+    const fallbackBackendId = (): string => {
+      if (backends.has(DEFAULT_BACKEND_ID)) return DEFAULT_BACKEND_ID;
+      const ids = backends.ids();
+      if (ids.length === 0) {
+        throw new Error(
+          "No secret backend is registered. Ensure secrets-backend-local is installed.",
+        );
+      }
+      return ids[0];
+    };
+
+    const getActiveBackendId = async (): Promise<string> => {
+      const store = (env as unknown as EnvStash).configStore;
+      const redacted = await store?.loadRedacted();
+      const persisted = redacted?.activeBackend;
+      if (persisted && backends.has(persisted)) return persisted;
+      return fallbackBackendId();
+    };
+
+    const setActiveBackendId = async (id: string): Promise<void> => {
+      const store = (env as unknown as EnvStash).configStore;
+      if (!store) {
+        throw new Error("Backend config store is not initialized yet.");
+      }
+      const current = (await store.load()) ?? { activeBackend: id };
+      await store.save({ ...current, activeBackend: id });
+    };
+
+    // SecretStore backed by whichever backend is active — switching the
+    // active backend (local → vault) re-routes resolution with no other
+    // change. Throws on a missing secret so a required reference fails clearly.
+    const secretStore = createActiveBackendStore({
+      backends,
+      getActiveBackendId,
+    });
+
+    const resolver = createSecretResolverService({ secretStore });
+    env.registerService(secretResolverRef, resolver);
+
+    const emitChanged = async (input: {
+      name: string;
+      change: "created" | "rotated" | "deleted";
+    }): Promise<void> => {
+      await (env as unknown as EnvStash).emitChanged?.(input);
+    };
+
+    const getActiveBackend = async (): Promise<SecretBackend> =>
+      backends.get(await getActiveBackendId());
+
+    const adminService = createSecretAdminService({
+      getActiveBackend,
+      onChanged: emitChanged,
+      // No logger in the register() phase; the short-secret warning is
+      // surfaced on the user-facing setSecret RPC (router, which has one).
+    });
+    env.registerService(secretAdminRef, adminService);
+
+    // Internal secrets always use the local backend (always-writable),
+    // never the active external backend.
+    const internalSecrets = createInternalSecretsService({
+      getLocalBackend: () => backends.get(DEFAULT_BACKEND_ID),
+    });
+    env.registerService(internalSecretsRef, internalSecrets);
+
+    env.registerInit({
+      deps: {
+        logger: coreServices.logger,
+        rpc: coreServices.rpc,
+        config: coreServices.config,
+      },
+      init: async ({ logger, rpc, config }) => {
+        logger.debug("🔐 Initializing Secrets Backend...");
+
+        (env as unknown as EnvStash).configStore = createBackendConfigStore({
+          config,
+        });
+
+        const router = createSecretsRouter({
+          backends,
+          getActiveBackendId,
+          setActiveBackendId,
+          emitChanged,
+          logger,
+        });
+        rpc.registerRouter(router, secretsContract);
+
+        logger.debug("✅ Secrets Backend initialized.");
+      },
+
+      afterPluginsReady: async ({ logger, emitHook }) => {
+        (env as unknown as EnvStash).emitChanged = async (input) => {
+          await emitHook(secretsChangedHook, input);
+        };
+        logger.debug("✅ Secrets Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});
+
+// ─── Public surface ──────────────────────────────────────────────────────
+
+export {
+  secretBackendExtensionPoint,
+  type SecretBackend,
+  type SecretBackendExtensionPoint,
+} from "./secret-backend";
+export {
+  createSecretBackendRegistry,
+  type SecretBackendRegistry,
+} from "./secret-backend-registry";
+export {
+  resolveSecretsBySchema,
+  type SecretStore,
+  type SecretResolutionResult,
+} from "./secret-resolver";
+export { walkSecretFields } from "./walk-secret-fields";
+export {
+  createSecretResolverService,
+  type SecretResolverService,
+} from "./resolver-service";
+export {
+  createSecretAdminService,
+  type SecretAdminService,
+} from "./admin-service";
+export {
+  createInternalSecretsService,
+  type InternalSecretsService,
+} from "./internal-secrets-service";
+export {
+  createMaskingContext,
+  EMPTY_MASKING_CONTEXT,
+  type SecretMaskingContext,
+} from "./masking-context";
+export { secretsChangedHook } from "./hooks";

package/src/internal-secrets-service.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "bun:test";
+import { internalSecretName } from "@checkstack/secrets-common";
+import { createInternalSecretsService } from "./internal-secrets-service";
+import { createSecretAdminService } from "./admin-service";
+import type { SecretBackend } from "./secret-backend";
+
+/** In-memory local-style backend (writable). */
+function memoryBackend(): SecretBackend & { store: Map<string, string> } {
+  const store = new Map<string, string>();
+  return {
+    id: "local",
+    store,
+    get: async ({ name }) => store.get(name),
+    set: async ({ name, value }) => {
+      store.set(name, value);
+    },
+    delete: async ({ name }) => {
+      store.delete(name);
+    },
+    list: async () =>
+      [...store.keys()].map((name) => ({
+        id: name,
+        name,
+        description: null,
+        hasValue: true,
+        backend: "local",
+        createdBy: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      })),
+  };
+}
+
+describe("InternalSecretsService", () => {
+  it("round-trips an internal secret on the local backend under the reserved prefix", async () => {
+    const local = memoryBackend();
+    const internal = createInternalSecretsService({
+      getLocalBackend: () => local,
+    });
+
+    await internal.set({
+      parts: ["script-packages", "registry-auth-token"],
+      value: "npm_token_value",
+    });
+    expect(
+      await internal.get({ parts: ["script-packages", "registry-auth-token"] }),
+    ).toBe("npm_token_value");
+    // Stored under the reserved internal name.
+    expect(
+      local.store.get(
+        internalSecretName("script-packages", "registry-auth-token"),
+      ),
+    ).toBe("npm_token_value");
+  });
+
+  it("delete is idempotent", async () => {
+    const internal = createInternalSecretsService({
+      getLocalBackend: memoryBackend,
+    });
+    await internal.delete({ parts: ["x", "y"] });
+    expect(await internal.get({ parts: ["x", "y"] })).toBeUndefined();
+  });
+});
+
+describe("admin list hides internal secrets", () => {
+  it("excludes reserved internal names from the user-facing list", async () => {
+    const local = memoryBackend();
+    const internal = createInternalSecretsService({
+      getLocalBackend: () => local,
+    });
+    const admin = createSecretAdminService({
+      getActiveBackend: async () => local,
+      onChanged: async () => {},
+    });
+
+    // A user-managed secret + an internal one.
+    await admin.setSecret({ name: "jira_token", value: "user-value" });
+    await internal.set({ parts: ["connection", "c1", "apiToken"], value: "v" });
+
+    const listed = await admin.list();
+    const names = listed.map((m) => m.name);
+    expect(names).toContain("jira_token");
+    expect(names.some((n) => n.startsWith("__internal__:"))).toBe(false);
+  });
+});

package/src/internal-secrets-service.ts

@@ -0,0 +1,54 @@
+import { internalSecretName } from "@checkstack/secrets-common";
+import type { SecretBackend } from "./secret-backend";
+
+/**
+ * Cross-plugin service for platform-internal secrets (exposed via
+ * `internalSecretsRef`). These are NOT user-managed named secrets — they
+ * back a specific feature (e.g. the script-package registry token, or a
+ * connection's credential fields).
+ *
+ * Internal secrets ALWAYS live on the local (always-writable, AES-GCM)
+ * backend, never the active external backend: Vault is read-through with no
+ * `set`, so routing internal writes through the active backend would break
+ * when Vault is selected. They are stored under a reserved name prefix so
+ * the user-facing Secrets UI never shows them.
+ *
+ * No method returns a value to a browser — this is a backend-only service.
+ */
+export interface InternalSecretsService {
+  /** Store / rotate an internal secret value under `namespace:key...`. */
+  set(input: { parts: string[]; value: string }): Promise<void>;
+  /** Resolve an internal secret value, or undefined if absent. */
+  get(input: { parts: string[] }): Promise<string | undefined>;
+  /** Delete an internal secret. Idempotent. */
+  delete(input: { parts: string[] }): Promise<void>;
+}
+
+export function createInternalSecretsService({
+  getLocalBackend,
+}: {
+  /** Resolve the local (always-writable) backend. Throws if unavailable. */
+  getLocalBackend: () => SecretBackend;
+}): InternalSecretsService {
+  return {
+    async set({ parts, value }) {
+      const backend = getLocalBackend();
+      if (!backend.set) {
+        throw new Error("Local secret backend does not support writes.");
+      }
+      await backend.set({ name: internalSecretName(...parts), value });
+    },
+
+    async get({ parts }) {
+      const backend = getLocalBackend();
+      return backend.get({ name: internalSecretName(...parts) });
+    },
+
+    async delete({ parts }) {
+      const backend = getLocalBackend();
+      if (backend.delete) {
+        await backend.delete({ name: internalSecretName(...parts) });
+      }
+    },
+  };
+}

package/src/leak-guard.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Platform-wide leak-guard suite.
+ *
+ * One focused, explicit place asserting the core guarantee end-to-end: a
+ * secret VALUE never crosses any DTO / persisted-record / user-facing
+ * surface, across every path the platform exposes. Individual path tests
+ * live with their features; this suite is the cross-cutting regression net
+ * that wires the real services together and proves the invariant holds.
+ *
+ * The single canonical secret value used throughout; if it appears in any
+ * surface output below, the test fails.
+ */
+import { describe, it, expect } from "bun:test";
+import { z, configString } from "@checkstack/backend-api";
+import { createSecretBackendRegistry } from "./secret-backend-registry";
+import { createActiveBackendStore } from "./active-backend";
+import { createSecretResolverService } from "./resolver-service";
+import { createSecretAdminService } from "./admin-service";
+import { createInternalSecretsService } from "./internal-secrets-service";
+import { createMaskingContext } from "./masking-context";
+import type { SecretBackend } from "./secret-backend";
+import type { SecretMetadata } from "@checkstack/secrets-common";
+
+const SECRET = "gh_TOPSECRET_value_9999";
+
+/** In-memory local-style backend (writable). */
+function localBackend(seed: Record<string, string> = {}): SecretBackend {
+  const store = new Map<string, string>(Object.entries(seed));
+  return {
+    id: "local",
+    get: async ({ name }) => store.get(name),
+    set: async ({ name, value }) => {
+      store.set(name, value);
+    },
+    delete: async ({ name }) => {
+      store.delete(name);
+    },
+    list: async (): Promise<SecretMetadata[]> =>
+      [...store.entries()].map(([name]) => ({
+        id: name,
+        name,
+        description: null,
+        hasValue: true,
+        backend: "local",
+        createdBy: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      })),
+  };
+}
+
+/** Fake read-through Vault-style backend (no set/delete). */
+function vaultBackend(seed: Record<string, string>): SecretBackend {
+  const store = new Map<string, string>(Object.entries(seed));
+  return {
+    id: "vault",
+    get: async ({ name }) => store.get(name),
+    list: async (): Promise<SecretMetadata[]> =>
+      [...store.keys()].map((name) => ({
+        id: name,
+        name,
+        description: null,
+        hasValue: true,
+        backend: "vault",
+        createdBy: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      })),
+  };
+}
+
+describe("leak guard: list / get DTO surfaces", () => {
+  it("listSecrets metadata never contains the value (local backend)", async () => {
+    const local = localBackend({ db_pass: SECRET });
+    const admin = createSecretAdminService({
+      getActiveBackend: async () => local,
+      onChanged: async () => {},
+    });
+    const list = await admin.list();
+    expect(JSON.stringify(list)).not.toContain(SECRET);
+    expect(list.every((m) => !("value" in m))).toBe(true);
+  });
+
+  it("listSecrets metadata never contains the value (Vault backend)", async () => {
+    const admin = createSecretAdminService({
+      getActiveBackend: async () => vaultBackend({ db_pass: SECRET }),
+      onChanged: async () => {},
+    });
+    expect(JSON.stringify(await admin.list())).not.toContain(SECRET);
+  });
+
+  it("internal secrets are excluded from the user-facing list", async () => {
+    const local = localBackend();
+    const admin = createSecretAdminService({
+      getActiveBackend: async () => local,
+      onChanged: async () => {},
+    });
+    const internal = createInternalSecretsService({
+      getLocalBackend: () => local,
+    });
+    await admin.setSecret({ name: "jira_token", value: "user-secret-aaa" });
+    await internal.set({ parts: ["connection", "c1", "apiToken"], value: SECRET });
+    const names = (await admin.list()).map((m) => m.name);
+    expect(names).toContain("jira_token");
+    expect(names.some((n) => n.startsWith("__internal__:"))).toBe(false);
+  });
+});
+
+describe("leak guard: run output masking (central + satellite)", () => {
+  // The same maskScriptRunOutput path backs the central action runner, the
+  // satellite collector, and the automation step result. resolveForRun
+  // yields the run-scoped masking context that redacts the value.
+  it("a script run that echoes its injected secret is fully masked", async () => {
+    const local = localBackend({ jira_token: SECRET });
+    const resolver = createSecretResolverService({
+      secretStore: createActiveBackendStore({
+        backends: registryWith(local),
+        getActiveBackendId: async () => "local",
+      }),
+    });
+    const { env, masking } = await resolver.resolveForRun({
+      secretEnv: { API_TOKEN: "${{ secrets.jira_token }}" },
+    });
+    // The env carries the real value (it must, to inject into the run)...
+    expect(env.API_TOKEN).toBe(SECRET);
+    // ...but every output surface masked with the run context is redacted.
+    const stdout = masking.maskText(`echo ${SECRET}`);
+    const result = masking.maskDeep({ token: SECRET, nested: [SECRET] });
+    expect(stdout).toBe("echo ****");
+    expect(result).toEqual({ token: "****", nested: ["****"] });
+    expect(JSON.stringify({ stdout, result })).not.toContain(SECRET);
+  });
+
+  it("an automation step result payload is masked deeply", async () => {
+    const masking = createMaskingContext({ values: [SECRET] });
+    const stepResult = masking.maskDeep({
+      externalId: "x",
+      detail: { auth: `Bearer ${SECRET}` },
+      lines: [`logged ${SECRET}`],
+    });
+    expect(JSON.stringify(stepResult)).not.toContain(SECRET);
+  });
+});
+
+describe("leak guard: Vault-backed resolution routes + masks", () => {
+  it("resolving through the active Vault backend yields a masking context that redacts the value", async () => {
+    const backends = createSecretBackendRegistry();
+    backends.register(localBackend());
+    backends.register(vaultBackend({ vault_secret: SECRET }));
+    const resolver = createSecretResolverService({
+      secretStore: createActiveBackendStore({
+        backends,
+        getActiveBackendId: async () => "vault", // active = vault
+      }),
+    });
+    const { env, masking } = await resolver.resolveForRun({
+      secretEnv: { TOKEN: "${{ secrets.vault_secret }}" },
+    });
+    expect(env.TOKEN).toBe(SECRET);
+    expect(masking.maskText(`x=${SECRET}`)).toBe("x=****");
+  });
+
+  it("gitops/connection-style x-secret field resolves a ${{ secrets.NAME }} reference through the active Vault backend", async () => {
+    // Mirrors how gitops descriptors and connection credentials resolve:
+    // resolveBySchema walks x-secret fields and resolves the template
+    // through whichever backend is active. With Vault active, a referenced
+    // secret originating from Vault resolves through the ONE channel.
+    const backends = createSecretBackendRegistry();
+    backends.register(localBackend());
+    backends.register(vaultBackend({ db_pass: SECRET }));
+    const resolver = createSecretResolverService({
+      secretStore: createActiveBackendStore({
+        backends,
+        getActiveBackendId: async () => "vault",
+      }),
+    });
+    const schema = z.object({
+      host: z.string(),
+      // configString({ "x-secret": true }) marks this resolvable.
+      password: configString({ "x-secret": true }),
+    });
+    const { resolved } = await resolver.resolveBySchema({
+      value: { host: "db.internal", password: "${{ secrets.db_pass }}" },
+      schema,
+    });
+    expect(resolved).toEqual({ host: "db.internal", password: SECRET });
+  });
+});
+
+function registryWith(backend: SecretBackend) {
+  const r = createSecretBackendRegistry();
+  r.register(backend);
+  return r;
+}

package/src/masking-context.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "bun:test";
+import { createMaskingContext, EMPTY_MASKING_CONTEXT } from "./masking-context";
+
+describe("SecretMaskingContext", () => {
+  it("redacts held values in text and deep payloads", () => {
+    const ctx = createMaskingContext({
+      values: ["token-abc-123", "db-pass-456"],
+    });
+    expect(ctx.size).toBe(2);
+    expect(ctx.maskText("Authorization: token-abc-123")).toBe(
+      "Authorization: ****",
+    );
+    expect(
+      ctx.maskDeep({ stdout: "pw=db-pass-456", meta: { n: 1 } }),
+    ).toEqual({ stdout: "pw=****", meta: { n: 1 } });
+  });
+
+  it("is a no-op when it holds no values", () => {
+    expect(EMPTY_MASKING_CONTEXT.size).toBe(0);
+    const text = "nothing to mask token-abc-123";
+    expect(EMPTY_MASKING_CONTEXT.maskText(text)).toBe(text);
+    const payload = { a: "token-abc-123" };
+    expect(EMPTY_MASKING_CONTEXT.maskDeep(payload)).toBe(payload);
+  });
+
+  it("masks a script echoing its own injected secret", () => {
+    const ctx = createMaskingContext({ values: ["gh_injectedSecret999"] });
+    const stdout = "echo: gh_injectedSecret999\nexit 0";
+    expect(ctx.maskText(stdout)).toBe("echo: ****\nexit 0");
+  });
+});

package/src/masking-context.ts

@@ -0,0 +1,50 @@
+import { maskSecrets, maskSecretsDeep } from "@checkstack/secrets-common";
+
+/**
+ * Run-scoped masking context: holds the resolved secret VALUES for a
+ * single run (the consumer's least-privilege allowlist only) and applies
+ * Jenkins-style by-value redaction at every output boundary before the
+ * output is persisted or returned.
+ *
+ * The value set is the run's resolved secrets, NOT the whole secret store
+ * — this is both least-privilege and avoids masking unrelated coincidental
+ * strings. Create one per run, register the run's resolved values, and
+ * pass the result of `mask*` through to persistence/RPC.
+ */
+export interface SecretMaskingContext {
+  /** Number of distinct values held (for diagnostics, never the values). */
+  readonly size: number;
+  /** Redact every literal occurrence of a held value in `text`. */
+  maskText(text: string): string;
+  /** Recursively redact held values in a JSON-like payload (keys + leaves). */
+  maskDeep(value: unknown): unknown;
+}
+
+/**
+ * Build a masking context from a run's resolved secret values.
+ */
+export function createMaskingContext({
+  values,
+}: {
+  values: Iterable<string>;
+}): SecretMaskingContext {
+  const valueSet = new Set<string>(values);
+  return {
+    get size() {
+      return valueSet.size;
+    },
+    maskText(text) {
+      if (valueSet.size === 0) return text;
+      return maskSecrets({ text, values: valueSet });
+    },
+    maskDeep(value) {
+      if (valueSet.size === 0) return value;
+      return maskSecretsDeep({ value, values: valueSet });
+    },
+  };
+}
+
+/** A no-op context (no values) for paths with no resolved secrets. */
+export const EMPTY_MASKING_CONTEXT: SecretMaskingContext = createMaskingContext(
+  { values: [] },
+);