@checkstack/secrets-backend 0.1.0

package/src/resolver-service.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { configString } from "@checkstack/backend-api";
+import { createSecretResolverService } from "./resolver-service";
+import type { SecretStore } from "./secret-resolver";
+
+const store: SecretStore = {
+  resolve: async (name) => {
+    const values: Record<string, string> = {
+      jira_token: "jira-secret-value",
+      DB_PASS: "db-secret-value",
+      missing: "", // present-but-empty, distinct from absent
+    };
+    if (!(name in values)) throw new Error(`Secret not found: ${name}`);
+    return values[name];
+  },
+};
+
+describe("SecretResolverService.resolveBySchema", () => {
+  it("resolves ${{ secrets.NAME }} only in x-secret fields", async () => {
+    const service = createSecretResolverService({ secretStore: store });
+    const schema = z.object({
+      host: z.string(),
+      password: configString({ "x-secret": true }),
+    });
+    const { resolved, warnings } = await service.resolveBySchema({
+      value: { host: "h", password: "${{ secrets.DB_PASS }}" },
+      schema,
+    });
+    expect(resolved).toEqual({ host: "h", password: "db-secret-value" });
+    expect(warnings).toEqual([]);
+  });
+});
+
+describe("SecretResolverService.resolveForRun", () => {
+  it("resolves a least-privilege env allowlist + masking context", async () => {
+    const service = createSecretResolverService({ secretStore: store });
+    const { env, masking } = await service.resolveForRun({
+      secretEnv: {
+        API_TOKEN: "${{ secrets.jira_token }}",
+        DATABASE_PASSWORD: "${{ secrets.DB_PASS }}",
+      },
+    });
+    expect(env).toEqual({
+      API_TOKEN: "jira-secret-value",
+      DATABASE_PASSWORD: "db-secret-value",
+    });
+    expect(masking.size).toBe(2);
+    // The masking context redacts the resolved values out of output.
+    expect(masking.maskText("token=jira-secret-value")).toBe("token=****");
+  });
+
+  it("supports inline interpolation in a mapping value", async () => {
+    const service = createSecretResolverService({ secretStore: store });
+    const { env } = await service.resolveForRun({
+      secretEnv: { CONN: "user:${{ secrets.DB_PASS }}@host" },
+    });
+    expect(env.CONN).toBe("user:db-secret-value@host");
+  });
+
+  it("throws when a referenced secret cannot be resolved", async () => {
+    const service = createSecretResolverService({ secretStore: store });
+    await expect(
+      service.resolveForRun({ secretEnv: { X: "${{ secrets.absent }}" } }),
+    ).rejects.toThrow("Secret not found: absent");
+  });
+
+  it("resolves each distinct secret once even when reused", async () => {
+    let calls = 0;
+    const counting: SecretStore = {
+      resolve: async (name) => {
+        calls++;
+        return `val-${name}`;
+      },
+    };
+    const service = createSecretResolverService({ secretStore: counting });
+    await service.resolveForRun({
+      secretEnv: {
+        A: "${{ secrets.same }}",
+        B: "${{ secrets.same }}",
+        C: "${{ secrets.other }}",
+      },
+    });
+    // "same" + "other" → 2 distinct resolutions despite 3 references.
+    expect(calls).toBe(2);
+  });
+});

package/src/resolver-service.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import {
+  collectSecretNames,
+  normalizeSecretEnvValue,
+  type SecretEnvMapping,
+} from "@checkstack/secrets-common";
+import {
+  resolveSecretsBySchema,
+  type SecretResolutionResult,
+  type SecretStore,
+} from "./secret-resolver";
+import {
+  createMaskingContext,
+  type SecretMaskingContext,
+} from "./masking-context";
+
+/**
+ * Cross-plugin secret resolution service, exposed via `secretResolverRef`.
+ *
+ * Wraps the promoted `resolveSecretsBySchema` so any consumer plugin
+ * (gitops, automation, healthcheck) resolves `${{ secrets.NAME }}` in
+ * `x-secret` fields on demand against the active backend, and can resolve
+ * a run's least-privilege env-mapping allowlist into values + a masking
+ * context.
+ *
+ * NOTE: every method here returns secret VALUES. It is a service-typed,
+ * backend-to-backend interface only — it MUST NOT be exposed to a browser
+ * client. Output produced from these values must pass through the
+ * returned `SecretMaskingContext` before it is persisted or returned.
+ */
+export interface SecretResolverService {
+  /** Resolve a single secret value by name. Throws if not found. */
+  resolveSecret(input: { name: string }): Promise<string>;
+
+  /**
+   * Resolve `${{ secrets.NAME }}` templates in `x-secret`-annotated fields
+   * of `value`, per `schema`. Promoted from gitops-backend.
+   */
+  resolveBySchema<T>(input: {
+    value: T;
+    schema: z.ZodTypeAny;
+  }): Promise<SecretResolutionResult<T>>;
+
+  /**
+   * Resolve a consumer's least-privilege secret→env allowlist into the
+   * concrete env vars for a run, plus a run-scoped masking context holding
+   * exactly those values. If any referenced secret is missing, this throws
+   * (the run must fail clearly rather than run without a required secret).
+   */
+  resolveForRun(input: {
+    secretEnv: SecretEnvMapping;
+  }): Promise<{ env: Record<string, string>; masking: SecretMaskingContext }>;
+}
+
+/**
+ * Build the resolver service over a {@link SecretStore} (typically backed
+ * by the active backend's `get`).
+ */
+export function createSecretResolverService({
+  secretStore,
+}: {
+  secretStore: SecretStore;
+}): SecretResolverService {
+  return {
+    resolveSecret({ name }) {
+      return secretStore.resolve(name);
+    },
+
+    resolveBySchema({ value, schema }) {
+      return resolveSecretsBySchema({ value, schema, secretStore });
+    },
+
+    async resolveForRun({ secretEnv }) {
+      // Normalize tolerated bare secret names to the canonical template
+      // (the value schema no longer transforms — see `secretEnvValueSchema`),
+      // so collection + substitution below see only `${{ secrets.NAME }}`.
+      const normalized: Record<string, string> = {};
+      for (const [envName, value] of Object.entries(secretEnv)) {
+        normalized[envName] = normalizeSecretEnvValue(value);
+      }
+
+      // Collect every distinct secret name referenced by the mapping, so
+      // we resolve each once even if reused across multiple env vars.
+      const names = new Set(
+        collectSecretNames({ value: Object.values(normalized) }),
+      );
+
+      const resolved = new Map<string, string>();
+      for (const name of names) {
+        resolved.set(name, await secretStore.resolve(name));
+      }
+
+      // Build the env by substituting templates in each mapping value.
+      const env: Record<string, string> = {};
+      for (const [envName, template] of Object.entries(normalized)) {
+        env[envName] = substituteTemplate({ template, resolved });
+      }
+
+      const masking = createMaskingContext({ values: resolved.values() });
+      return { env, masking };
+    },
+  };
+}
+
+const TEMPLATE_RE = /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+
+function substituteTemplate({
+  template,
+  resolved,
+}: {
+  template: string;
+  resolved: Map<string, string>;
+}): string {
+  TEMPLATE_RE.lastIndex = 0;
+  return template.replaceAll(TEMPLATE_RE, (_full, name: string) => {
+    const value = resolved.get(name);
+    if (value === undefined) {
+      throw new Error(`Required secret not available: ${name}`);
+    }
+    return value;
+  });
+}

package/src/router.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "bun:test";
+import { call } from "@orpc/server";
+import { createMockRpcContext } from "@checkstack/backend-api";
+import { createSecretsRouter } from "./router";
+import { createSecretBackendRegistry } from "./secret-backend-registry";
+import type { SecretBackend } from "./secret-backend";
+
+const mockUser = {
+  type: "user" as const,
+  id: "test-user",
+  accessRules: ["*"],
+  roles: ["admin"],
+};
+
+/** Fully writable backend (local): implements both `set` and `delete`. */
+function localBackend(): SecretBackend {
+  return {
+    id: "local",
+    get: async () => undefined,
+    set: async () => {},
+    delete: async () => {},
+    list: async () => [],
+  };
+}
+
+/** Read-through backend (vault): implements neither `set` nor `delete`. */
+function vaultBackend(): SecretBackend {
+  return {
+    id: "vault",
+    get: async () => undefined,
+    list: async () => [],
+  };
+}
+
+function makeRouter(active: string, backends: SecretBackend[]) {
+  const registry = createSecretBackendRegistry();
+  for (const b of backends) registry.register(b);
+  return createSecretsRouter({
+    backends: registry,
+    getActiveBackendId: async () => active,
+    setActiveBackendId: async () => {},
+    emitChanged: async () => {},
+  });
+}
+
+describe("getBackendConfig — writable capability flag", () => {
+  it("reports writable: true when the local backend is active", async () => {
+    const router = makeRouter("local", [localBackend(), vaultBackend()]);
+    const context = createMockRpcContext({ user: mockUser });
+
+    const dto = await call(router.getBackendConfig, undefined, { context });
+
+    expect(dto.activeBackend).toBe("local");
+    expect(dto.writable).toBe(true);
+  });
+
+  it("reports writable: false when a read-through (Vault) backend is active", async () => {
+    const router = makeRouter("vault", [localBackend(), vaultBackend()]);
+    const context = createMockRpcContext({ user: mockUser });
+
+    const dto = await call(router.getBackendConfig, undefined, { context });
+
+    expect(dto.activeBackend).toBe("vault");
+    expect(dto.writable).toBe(false);
+  });
+
+  it("reports writable: false when the active backend is unresolved", async () => {
+    // Active id points at a backend that is not registered.
+    const router = makeRouter("missing", [localBackend()]);
+    const context = createMockRpcContext({ user: mockUser });
+
+    const dto = await call(router.getBackendConfig, undefined, { context });
+
+    expect(dto.writable).toBe(false);
+  });
+});

package/src/router.ts

@@ -0,0 +1,167 @@
+import { implement, ORPCError } from "@orpc/server";
+import {
+  autoAuthMiddleware,
+  correlationMiddleware,
+  type Logger,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import {
+  secretsContract,
+  type BackendConfigDto,
+  type SetBackendConfigInput,
+} from "@checkstack/secrets-common";
+import { extractErrorMessage } from "@checkstack/common";
+import type { SecretBackendRegistry } from "./secret-backend-registry";
+import { createSecretAdminService } from "./admin-service";
+import { isBackendWritable } from "./secret-backend";
+
+const os = implement(secretsContract)
+  .$context<RpcContext>()
+  .use(correlationMiddleware)
+  .use(autoAuthMiddleware);
+
+export interface SecretsRouterDeps {
+  backends: SecretBackendRegistry;
+  /** Resolve the currently active backend id. */
+  getActiveBackendId: () => Promise<string>;
+  /** Persist the active backend id. */
+  setActiveBackendId: (id: string) => Promise<void>;
+  /** Notify consumers (e.g. gitops) that a secret changed. */
+  emitChanged: (input: {
+    name: string;
+    change: "created" | "rotated" | "deleted";
+  }) => Promise<void>;
+  /** Logger for the admin service's short-secret warning. */
+  logger?: Logger;
+}
+
+export function createSecretsRouter({
+  backends,
+  getActiveBackendId,
+  setActiveBackendId,
+  emitChanged,
+  logger,
+}: SecretsRouterDeps) {
+  // The router shares the admin service so write semantics + change events
+  // stay identical whether a secret is managed via the central UI or via a
+  // consumer plugin (e.g. gitops) delegating to secretAdminRef.
+  const admin = createSecretAdminService({
+    getActiveBackend: async () => backends.get(await getActiveBackendId()),
+    onChanged: emitChanged,
+    logger,
+  });
+
+  const listSecrets = os.listSecrets.handler(async () => {
+    // Metadata only — never values.
+    return admin.list();
+  });
+
+  const listSecretNames = os.listSecretNames.handler(async () => {
+    const metadata = await admin.list();
+    return metadata.map((m) => m.name);
+  });
+
+  const setSecret = os.setSecret.handler(async ({ input, context }) => {
+    const actor = context.user;
+    const createdBy =
+      actor && actor.type !== "service" ? actor.id : undefined;
+
+    try {
+      await admin.setSecret({
+        name: input.name,
+        value: input.value,
+        description: input.description,
+        createdBy,
+      });
+    } catch (error) {
+      throw new ORPCError("NOT_IMPLEMENTED", {
+        message: extractErrorMessage(error),
+      });
+    }
+
+    const after = await admin.list();
+    const meta = after.find((m) => m.name === input.name);
+    return { id: meta?.id ?? input.name, name: input.name };
+  });
+
+  const deleteSecret = os.deleteSecret.handler(async ({ input }) => {
+    try {
+      await admin.deleteSecret({ name: input.name });
+    } catch (error) {
+      throw new ORPCError("NOT_IMPLEMENTED", {
+        message: extractErrorMessage(error),
+      });
+    }
+    return { success: true };
+  });
+
+  const getBackendConfig = os.getBackendConfig.handler(async () => {
+    const activeBackend = await getActiveBackendId();
+    // Surface the active backend's connection metadata (never credentials).
+    const active = backends.has(activeBackend)
+      ? backends.get(activeBackend)
+      : undefined;
+    const dto: BackendConfigDto = {
+      activeBackend,
+      availableBackends: backends.ids(),
+      // Capability flag the UI uses to hide write controls for read-through
+      // backends. False when the active backend is unresolved/read-only.
+      writable: active ? isBackendWritable({ backend: active }) : false,
+    };
+    if (active?.getConfigMeta) {
+      dto.vault = await active.getConfigMeta();
+    }
+    return dto;
+  });
+
+  const setBackendConfig = os.setBackendConfig.handler(async ({ input }) => {
+    // Configure the target backend (e.g. Vault address/auth/credential)
+    // BEFORE switching to it, so we never activate an unconfigured backend.
+    if (input.vault) {
+      const target = backends.has(input.activeBackend)
+        ? backends.get(input.activeBackend)
+        : undefined;
+      if (!target?.configure) {
+        throw new ORPCError("BAD_REQUEST", {
+          message: `Backend "${input.activeBackend}" is not configurable.`,
+        });
+      }
+      const vault: NonNullable<SetBackendConfigInput["vault"]> = input.vault;
+      await target.configure(vault);
+    }
+    if (!backends.has(input.activeBackend)) {
+      throw new ORPCError("BAD_REQUEST", {
+        message: `Backend "${input.activeBackend}" is not registered.`,
+      });
+    }
+    await setActiveBackendId(input.activeBackend);
+    return { success: true };
+  });
+
+  const testBackend = os.testBackend.handler(async ({ input }) => {
+    const id = input.backend ?? (await getActiveBackendId());
+    if (!backends.has(id)) {
+      return { ok: false, message: `Backend "${id}" is not registered.` };
+    }
+    const backend = backends.get(id);
+    // A backend with no external connectivity (e.g. local) is always ok.
+    if (!backend.test) {
+      return { ok: true, message: `Backend "${id}" requires no connectivity.` };
+    }
+    try {
+      return await backend.test();
+    } catch (error) {
+      return { ok: false, message: extractErrorMessage(error) };
+    }
+  });
+
+  return os.router({
+    listSecrets,
+    listSecretNames,
+    setSecret,
+    deleteSecret,
+    getBackendConfig,
+    setBackendConfig,
+    testBackend,
+  });
+}

package/src/secret-backend-registry.ts

@@ -0,0 +1,45 @@
+import type { SecretBackend } from "./secret-backend";
+
+/**
+ * Collects every registered {@link SecretBackend} (one per backend
+ * plugin) and resolves the active one by id. Mirrors the script-packages
+ * blob-store registry.
+ */
+export interface SecretBackendRegistry {
+  register(backend: SecretBackend): void;
+  /** All registered backend ids (for the admin backend selector). */
+  ids(): string[];
+  has(id: string): boolean;
+  /** Resolve a specific backend by id. Throws if not registered. */
+  get(id: string): SecretBackend;
+}
+
+export function createSecretBackendRegistry(): SecretBackendRegistry {
+  const backends = new Map<string, SecretBackend>();
+
+  return {
+    register(backend) {
+      backends.set(backend.id, backend);
+    },
+
+    ids() {
+      return [...backends.keys()];
+    },
+
+    has(id) {
+      return backends.has(id);
+    },
+
+    get(id) {
+      const backend = backends.get(id);
+      if (!backend) {
+        throw new Error(
+          `Secret backend "${id}" is not registered. Available: ${
+            [...backends.keys()].join(", ") || "(none)"
+          }`,
+        );
+      }
+      return backend;
+    },
+  };
+}

package/src/secret-backend.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "bun:test";
+import { isBackendWritable } from "./secret-backend";
+
+describe("isBackendWritable", () => {
+  it("is true only when BOTH set and delete are implemented", () => {
+    expect(
+      isBackendWritable({ backend: { set: async () => {}, delete: async () => {} } }),
+    ).toBe(true);
+  });
+
+  it("is false for a read-through backend (neither set nor delete)", () => {
+    expect(isBackendWritable({ backend: {} })).toBe(false);
+  });
+
+  it("is false when only one of set / delete is implemented", () => {
+    expect(isBackendWritable({ backend: { set: async () => {} } })).toBe(false);
+    expect(isBackendWritable({ backend: { delete: async () => {} } })).toBe(
+      false,
+    );
+  });
+});

package/src/secret-backend.ts

@@ -0,0 +1,94 @@
+import { createExtensionPoint } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import type {
+  SecretMetadata,
+  SetBackendConfigInput,
+  BackendConfigDto,
+} from "@checkstack/secrets-common";
+
+/** Public Vault connection metadata (never the credential). */
+type VaultConfigMeta = NonNullable<BackendConfigDto["vault"]>;
+
+/**
+ * A pluggable secret store. Built-ins: `secrets-backend-local` (default,
+ * AES-256-GCM in the `secrets` table) and `secrets-backend-vault` (Phase
+ * 4). The active backend is config-selected; local is the default when no
+ * external backend is configured.
+ *
+ * `list` returns metadata only and NEVER values. `get` resolves a single
+ * value and is service-internal — its result must not cross to a browser.
+ * Read-through backends (Vault) implement only `get`/`list`; the local
+ * backend additionally implements `set`/`delete`.
+ */
+export interface SecretBackend {
+  /** Stable backend id recorded in `secrets.backend`. */
+  readonly id: string;
+
+  /** Resolve a single secret value by name, or undefined if absent. */
+  get(input: { name: string }): Promise<string | undefined>;
+
+  /** Create or rotate a secret value. Local backend only. */
+  set?(input: {
+    name: string;
+    value: string;
+    description?: string;
+    createdBy?: string;
+  }): Promise<void>;
+
+  /** Delete a secret by name. Local backend only. Idempotent. */
+  delete?(input: { name: string }): Promise<void>;
+
+  /** Metadata for every secret this backend holds. NEVER returns values. */
+  list(): Promise<SecretMetadata[]>;
+
+  /**
+   * Validate connectivity / auth for this backend. Returns status only and
+   * NEVER a secret value. Optional — a backend that needs no external
+   * connectivity (e.g. local) may omit it (treated as always-ok).
+   */
+  test?(): Promise<{ ok: boolean; message: string }>;
+
+  /**
+   * Persist this backend's connection config (e.g. Vault address / auth /
+   * credential). Implemented by externally-configured backends; the backend
+   * owns its own config storage (its plugin-scoped `ConfigService`). The
+   * write-only `credential` is encrypted at rest and never returned.
+   * Local-style backends omit this.
+   */
+  configure?(input: NonNullable<SetBackendConfigInput["vault"]>): Promise<void>;
+
+  /**
+   * Public connection metadata for the admin UI (NEVER the credential).
+   * Omitted by backends with no external connection.
+   */
+  getConfigMeta?(): Promise<VaultConfigMeta | undefined>;
+}
+
+/**
+ * Whether a backend accepts secret-value writes (create / rotate / delete)
+ * from the admin UI. True only when it implements BOTH `set` and `delete`;
+ * read-through backends (e.g. Vault) implement neither, so this is `false`
+ * and the UI hides its write controls. Capability boolean only — leaks
+ * nothing sensitive.
+ */
+export function isBackendWritable({
+  backend,
+}: {
+  backend: Pick<SecretBackend, "set" | "delete">;
+}): boolean {
+  return typeof backend.set === "function" && typeof backend.delete === "function";
+}
+
+/**
+ * Extension point a secret-backend plugin registers its implementation
+ * with. The active backend is selected via config; the resolver resolves
+ * the registered backend by id.
+ */
+export interface SecretBackendExtensionPoint {
+  registerSecretBackend(backend: SecretBackend, metadata: PluginMetadata): void;
+}
+
+export const secretBackendExtensionPoint =
+  createExtensionPoint<SecretBackendExtensionPoint>(
+    "secrets.secretBackendExtensionPoint",
+  );