@checkstack/secrets-backend-local 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @checkstack/secrets-backend-local
+
+## 0.1.0
+
+### Minor Changes
+
+- 270ef29: Add the Secrets platform (Phase 1): a central, plugin-agnostic secret manager with a pluggable backend extension point, a cross-plugin resolver service, and a universal Jenkins-style masking layer.
+
+  - New packages: `secrets-common` (schemas, contract, `secrets.read`/`secrets.manage`, masking utils), `secrets-backend` (`SecretBackend` extension point, `secretResolverRef`/`secretAdminRef` services, run-scoped masking context, RPC router), `secrets-backend-local` (default AES-256-GCM backend, owns the `secrets` table promoted from gitops), `secrets-frontend` (admin Settings page).
+  - Resolution machinery (`resolveSecretsBySchema`, `SecretStore`, `${{ secrets.NAME }}` / `x-secret`) is promoted out of `gitops-backend` into `secrets-backend`. GitOps now resolves and manages secrets through the platform's service refs (single source of truth); its secret table is migrated without loss.
+  - Universal masking seam wired at the central script-output boundaries: automation `run_script` / `run_shell` artifacts and the in-UI test panel redact run-scoped secret values from `result`/`stdout`/`stderr`/`error` before persist/return. Phase 1 resolves no run-scoped secrets yet, so masking is a no-op until Phase 2; the seam guarantees the boundary exists.
+  - No endpoint returns a secret value to a browser: DTOs expose only name/metadata/`hasValue`.
+
+  BREAKING CHANGES: `gitops-backend` now depends on `secrets-backend` and resolves/manages secrets through it. The `secrets` table is owned by `secrets-backend-local`; the gitops `secrets` table is retained as a migration source but is no longer the source of truth.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/secrets-backend@0.1.0
+  - @checkstack/secrets-common@0.1.0

package/drizzle/0000_dusty_sandman.sql

@@ -0,0 +1,10 @@
+CREATE TABLE "secrets" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"encrypted_value" text NOT NULL,
+	"description" text,
+	"created_by" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "secrets_name_unique" UNIQUE("name")
+);

package/drizzle/0001_promote_gitops_secrets.sql

@@ -0,0 +1,20 @@
+-- Promote existing GitOps secrets into the central local secret backend.
+--
+-- The legacy GitOps `secrets` table lives in the `plugin_gitops` Postgres
+-- schema (see getPluginSchemaName). This copies its rows into this
+-- backend's `secrets` table WITHOUT loss: it is guarded by to_regclass so a
+-- fresh install (no gitops table) is a no-op, and ON CONFLICT (name) keeps
+-- any already-present row. The source table is intentionally NOT dropped —
+-- gitops switches to reading via the secretResolverRef, and leaving its
+-- table in place means no rows can be lost if plugin migration order ever
+-- runs gitops after this one.
+DO $$
+BEGIN
+  IF to_regclass('"plugin_gitops".secrets') IS NOT NULL THEN
+    INSERT INTO secrets (id, name, encrypted_value, description, created_by, created_at, updated_at)
+    SELECT id, name, encrypted_value, description, created_by, created_at, updated_at
+    FROM "plugin_gitops".secrets
+    ON CONFLICT (name) DO NOTHING;
+  END IF;
+END
+$$;

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,84 @@
+{
+  "id": "262e0256-7c2f-4736-a72a-0e7e00d9d057",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.secrets": {
+      "name": "secrets",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "encrypted_value": {
+          "name": "encrypted_value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "secrets_name_unique": {
+          "name": "secrets_name_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "name"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,84 @@
+{
+  "id": "f2d2e3ed-c3e7-488b-b34b-1cacfcf43ac0",
+  "prevId": "262e0256-7c2f-4736-a72a-0e7e00d9d057",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.secrets": {
+      "name": "secrets",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "encrypted_value": {
+          "name": "encrypted_value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "secrets_name_unique": {
+          "name": "secrets_name_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "name"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1780163271755,
+      "tag": "0000_dusty_sandman",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1780163349834,
+      "tag": "0001_promote_gitops_secrets",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@checkstack/secrets-backend-local",
+  "version": "0.1.0",
+  "description": "Default local secret backend: AES-256-GCM values in Postgres",
+  "author": "Checkstack contributors",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "checkstack": {
+    "type": "backend",
+    "pluginId": "secrets-backend-local"
+  },
+  "scripts": {
+    "dev": "checkstack-dev",
+    "pack": "bunx @checkstack/scripts plugin-pack",
+    "typecheck": "tsgo -b",
+    "generate": "drizzle-kit generate",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/secrets-common": "0.0.1",
+    "@checkstack/secrets-backend": "0.0.1",
+    "drizzle-orm": "^0.45.0",
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/dev-server": "2.0.0",
+    "@checkstack/backend": "0.11.0",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/test-utils-backend": "0.1.31",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^20.0.0",
+    "drizzle-kit": "^0.31.10",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import { secretBackendExtensionPoint } from "@checkstack/secrets-backend";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  createLocalSecretBackend,
+  LOCAL_SECRET_BACKEND_ID,
+} from "./store";
+import * as schema from "./schema";
+
+/**
+ * Default secret backend: AES-256-GCM values in Postgres. Always
+ * available; the active backend when no external backend (Vault) is
+ * configured.
+ *
+ * Owns the `secrets` table (promoted from gitops — see ./drizzle). The
+ * backend is built in `init()` (where `database` is injected) and
+ * registered with the host's `secretBackendExtensionPoint`. The host runs
+ * its `register()` first (dep ordering), so the extension point exists by
+ * the time this init runs.
+ */
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+      },
+      init: async ({ logger, database }) => {
+        const backend = createLocalSecretBackend({ db: database });
+        env
+          .getExtensionPoint(secretBackendExtensionPoint)
+          .registerSecretBackend(backend, pluginMetadata);
+        logger.debug(
+          `🔐 Registered "${LOCAL_SECRET_BACKEND_ID}" secret backend.`,
+        );
+      },
+    });
+  },
+});
+
+export {
+  createLocalSecretBackend,
+  LOCAL_SECRET_BACKEND_ID,
+} from "./store";
+export * as schema from "./schema";

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "secrets-backend-local",
+});

package/src/schema.ts

@@ -0,0 +1,20 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+/**
+ * Local secret store: AES-256-GCM encrypted values keyed by unique name.
+ * Promoted from the GitOps `secrets` table — the gitops migration copies
+ * existing rows into this table (see ./drizzle migrations).
+ *
+ * NEVER expose `encryptedValue` or a decrypted value through any RPC/DTO.
+ */
+export const secrets = pgTable("secrets", {
+  id: text("id").primaryKey(),
+  /** Unique name referenced via `${{ secrets.NAME }}`. */
+  name: text("name").notNull().unique(),
+  /** AES-256-GCM encrypted value (iv:authTag:ciphertext). */
+  encryptedValue: text("encrypted_value").notNull(),
+  description: text("description"),
+  createdBy: text("created_by"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});

package/src/store.test.ts

@@ -0,0 +1,56 @@
+// AES-256 needs a 32-byte (64 hex char) key. Set before importing the
+// encryption module so module-eval-time encrypt() calls succeed.
+process.env.ENCRYPTION_MASTER_KEY = "11".repeat(32);
+
+import { describe, it, expect } from "bun:test";
+import { encrypt, decrypt } from "@checkstack/backend-api";
+import { toSecretMetadata, LOCAL_SECRET_BACKEND_ID } from "./store";
+import type * as schema from "./schema";
+
+describe("local backend encryption round-trip", () => {
+  it("encrypts then decrypts a value back to the original", () => {
+    const value = "gh_aBcDeF123456-with-special/chars=&";
+    const stored = encrypt(value);
+    expect(stored).not.toContain(value);
+    expect(decrypt(stored)).toBe(value);
+  });
+
+  it("produces a different ciphertext per encrypt (random IV)", () => {
+    const a = encrypt("same-plaintext-value");
+    const b = encrypt("same-plaintext-value");
+    expect(a).not.toBe(b);
+    expect(decrypt(a)).toBe("same-plaintext-value");
+    expect(decrypt(b)).toBe("same-plaintext-value");
+  });
+});
+
+describe("toSecretMetadata (no-value-leak guarantee)", () => {
+  const baseRow: typeof schema.secrets.$inferSelect = {
+    id: "id-1",
+    name: "api_key",
+    encryptedValue: encrypt("supersecretvalue"),
+    description: "An API key",
+    createdBy: "user-1",
+    createdAt: new Date("2026-01-01T00:00:00Z"),
+    updatedAt: new Date("2026-01-02T00:00:00Z"),
+  };
+
+  it("exposes metadata + hasValue but never the value", () => {
+    const meta = toSecretMetadata(baseRow);
+    expect(meta.name).toBe("api_key");
+    expect(meta.hasValue).toBe(true);
+    expect(meta.backend).toBe(LOCAL_SECRET_BACKEND_ID);
+    // The serialized DTO must not contain the value or the ciphertext.
+    const serialized = JSON.stringify(meta);
+    expect(serialized).not.toContain("supersecretvalue");
+    expect(serialized).not.toContain(baseRow.encryptedValue);
+    // The metadata shape has no `value` / `encryptedValue` keys.
+    expect("value" in meta).toBe(false);
+    expect("encryptedValue" in meta).toBe(false);
+  });
+
+  it("reports hasValue=false for an empty stored value", () => {
+    const meta = toSecretMetadata({ ...baseRow, encryptedValue: "" });
+    expect(meta.hasValue).toBe(false);
+  });
+});

package/src/store.ts

@@ -0,0 +1,90 @@
+import { encrypt, decrypt, type SafeDatabase } from "@checkstack/backend-api";
+import type { SecretBackend } from "@checkstack/secrets-backend";
+import type { SecretMetadata } from "@checkstack/secrets-common";
+import { eq } from "drizzle-orm";
+import { v4 as uuidv4 } from "uuid";
+import * as schema from "./schema";
+
+/** Stable id for the default local backend. */
+export const LOCAL_SECRET_BACKEND_ID = "local";
+
+type Db = SafeDatabase<typeof schema>;
+
+type SecretRow = typeof schema.secrets.$inferSelect;
+
+/**
+ * Map a stored row to its public metadata. Pure + exported so the
+ * no-value-leak guarantee is unit-testable: the result carries `hasValue`
+ * but never the encrypted/decrypted value.
+ */
+export function toSecretMetadata(row: SecretRow): SecretMetadata {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    hasValue: row.encryptedValue.length > 0,
+    backend: LOCAL_SECRET_BACKEND_ID,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/**
+ * Build the default local {@link SecretBackend}: AES-256-GCM values in the
+ * `secrets` table. `set`/`delete` are supported (read-write); `get`
+ * decrypts a single value; `list` returns metadata only (never values).
+ */
+export function createLocalSecretBackend({ db }: { db: Db }): SecretBackend {
+  return {
+    id: LOCAL_SECRET_BACKEND_ID,
+
+    async get({ name }) {
+      const rows = await db
+        .select()
+        .from(schema.secrets)
+        .where(eq(schema.secrets.name, name));
+      const row = rows[0];
+      if (!row) return;
+      return decrypt(row.encryptedValue);
+    },
+
+    async set({ name, value, description, createdBy }) {
+      const encryptedValue = encrypt(value);
+      const existing = await db
+        .select()
+        .from(schema.secrets)
+        .where(eq(schema.secrets.name, name));
+
+      if (existing[0]) {
+        await db
+          .update(schema.secrets)
+          .set({
+            encryptedValue,
+            // Only overwrite description when explicitly provided.
+            ...(description === undefined ? {} : { description }),
+            updatedAt: new Date(),
+          })
+          .where(eq(schema.secrets.name, name));
+        return;
+      }
+
+      await db.insert(schema.secrets).values({
+        id: uuidv4(),
+        name,
+        encryptedValue,
+        description: description ?? null,
+        createdBy: createdBy ?? null,
+      });
+    },
+
+    async delete({ name }) {
+      await db.delete(schema.secrets).where(eq(schema.secrets.name, name));
+    },
+
+    async list(): Promise<SecretMetadata[]> {
+      const rows = await db.select().from(schema.secrets);
+      return rows.map((row) => toSecretMetadata(row));
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../backend"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../dev-server"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../secrets-backend"
+    },
+    {
+      "path": "../secrets-common"
+    },
+    {
+      "path": "../test-utils-backend"
+    }
+  ]
+}