@checkstack/secrets-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# @checkstack/secrets-common
+
+## 0.1.0
+
+### Minor Changes
+
+- b995afb: Fix the automation Run Script action's `secretEnv` (secret → env mapping) test wiring and tolerate bare secret names.
+
+  - `@checkstack/ui` `ScriptTestPanel` now accepts the script field's declared `secretEnv` and renders an optional per-secret test-override input. The `ScriptTestRenderer` callback (DynamicForm) receives the SIBLING `x-secret-env` mapping value, located by annotation (not by field name), so a testable script field forwards it to the panel. Previously the test path never sent `secretEnv`, so `buildTestSecretEnv` got `undefined` and `process.env.<env>` was undefined in an in-UI test. Now an override-less test injects `__SECRET_<NAME>__` placeholders, and any operator override is masked from the output. Real secret values are still NEVER resolved in the test path.
+  - `@checkstack/automation-frontend` forwards the action's `secretEnv` and the collected overrides to `testScript`.
+  - `@checkstack/secrets-common`: the `secretEnv` mapping VALUE now accepts EITHER a `${{ secrets.NAME }}` template OR a bare secret name, normalizing a bare name to the canonical `${{ secrets.NAME }}` template on parse. This is a forgiving / NARROWING input change (more inputs accepted; stored/output form is unchanged and still the template), not a breaking change. Existing data and YAML shorthand like `secretEnv: { secret: SECRET }` now pass config validation instead of failing with "Must contain a ${{ secrets.NAME }} reference". Partial inline interpolation (e.g. `u:${{ secrets.pw }}@host`) keeps working unchanged; values that are neither a secret reference nor a valid secret name are still rejected.
+  - `@checkstack/ui` `parseSecretName` tolerates a legacy bare secret name for display so the picker shows the same name for both the template and the bare form.
+
+  The healthcheck collector test panel was checked: its config has no `x-secret-env` field, so it needed no secret wiring (only the `onRun` signature change, which is backward compatible).
+
+- 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.
+
+- 270ef29: Secrets platform Phase 2: secret -> env-var mapping with central resolve, inject, and mask.
+
+  - Script consumers declare a least-privilege `secretEnv` allowlist
+    (`{ ENV_NAME: "${{ secrets.NAME }}" }`). The automation `run_script` /
+    `run_shell` actions resolve ONLY the declared secrets via
+    `secretResolverRef.resolveForRun`, inject them into the runner env for
+    that run (memory-only; the ESM runner gained a per-run `env` option), and
+    mask their values out of stdout/stderr/result/error via the run-scoped
+    masking context. A missing required secret fails the run clearly. No
+    ambient secret access.
+  - Test panel: `testScript` / `testCollectorScript` inject named
+    `__SECRET_<NAME>__` placeholders by default, or user-supplied per-secret
+    overrides; real production values are never resolved in the test path,
+    and overrides are masked out of the result.
+  - Healthcheck collectors carry the `secretEnv` field for authoring +
+    the test panel; runtime injection on satellites lands in Phase 3.
+  - Editor UX: a new `@checkstack/ui` `SecretEnvEditor` renders `x-secret-env`
+    record fields with `${{ secrets.* }}` name autocomplete (from
+    `listSecretNames`), wired into the automation action editor and the
+    healthcheck collector editor. New `withConfigMeta` helper +
+    `x-secret-env` config-meta key in `@checkstack/backend-api`.
+
+- 270ef29: Secrets platform Phase 4: HashiCorp Vault backend + backend selection.
+
+  - New `@checkstack/secrets-backend-vault`: a read-through `SecretBackend`
+    against Vault. Token, AppRole, and OIDC/JWT auth (session cached to the
+    lease TTL, capped); KV v2 reads mapped via the backend's own
+    `secret_index` table (name → path/key); read-through value cache with a
+    capped TTL (rotated values re-read). `list()` returns metadata only,
+    never values. Minimal typed HTTP client (no extra dependency), injectable
+    fetch for testing.
+  - Backend selection: the active backend is persisted via `ConfigService`
+    and switchable in Settings → Secrets; switching re-routes resolution.
+    New `setBackendConfig` / `testBackend` RPCs (manage-gated, status-only)
+    and `getBackendConfig` now returns Vault connection metadata
+    (`hasCredential`, never the credential). `SecretBackend` gains optional
+    `test` / `configure` / `getConfigMeta`.
+  - The Vault auth credential is stored as an `x-secret` config field
+    (encrypted at rest with the AES-GCM master key, redacted on read) —
+    bootstrapping it WITHOUT putting it in Vault. It is write-only over the
+    API and never logged.
+  - Admin UI: backend selector + Vault connection form + "Test connection".
+
+  Satellite-direct-Vault (a satellite reading Vault itself) is deferred to a
+  follow-up; core-mediated delivery already routes through the Vault backend.
+
+- 270ef29: Secrets platform Phase 5: internal-secret consolidation (registry token) + connection-credential leak hardening.
+
+  - New `internalSecretsRef`: platform-internal secrets (not user-managed
+    named secrets) stored under a reserved `__internal__:` prefix, ALWAYS on
+    the local (always-writable, AES-GCM) backend so internal writes never
+    break when Vault is the active backend. Excluded from the user-facing
+    Secrets list.
+  - The script-package registry auth token is consolidated onto
+    `internalSecretsRef`. The `authSecretRef` column now holds a stable
+    marker; a one-time, idempotent, parity-verified migration moves legacy
+    inline ciphertext into the platform and only rewrites the column once the
+    platform copy reads back identically (legacy value never dropped early).
+    Resolution stays backward-compatible with legacy ciphertext.
+  - Integration: `createConnection` / `updateConnection` now return the
+    redacted connection preview instead of echoing the submitted credential
+    fields back in the response (leak hardening). Non-breaking — the frontend
+    refetches the redacted list and ignores the returned preview.
+
+  NOTE: integration connection-credential STORAGE is intentionally NOT
+  migrated onto the secrets platform. Connection creds are co-mingled
+  secret/non-secret config stored per-provider via `ConfigService` (which
+  already uses the same AES-GCM crypto + per-field redaction); splitting them
+  out would require per-provider schema-walking and a lossy migration across
+  live integrations for no real gain. The `ConnectionStore` API + storage are
+  unchanged.
+
+- b995afb: Hide secret write controls when the active backend is read-through.
+
+  When a read-through backend (e.g. Vault) was active, the Secrets admin page still showed the "Add a secret", Rotate, and Delete controls even though the backend correctly rejects writes (`set` / `delete` are intentionally unimplemented), so every attempt errored.
+
+  The active backend now reports a capability flag and the UI gates its write affordances on it instead of any hardcoded backend id, so other read-through backends are handled the same way.
+
+  Changes:
+
+  - `@checkstack/secrets-common`: add a `writable: boolean` field to `BackendConfigDto` (returned by `getBackendConfig`). It carries no sensitive data - a capability boolean only.
+  - `@checkstack/secrets-backend`: populate `writable` in the `getBackendConfig` handler by inspecting the resolved active backend (true only when it implements both `set` and `delete`; `false` for read-through backends or an unresolved active id). Exposes a small `isBackendWritable` helper.
+  - `@checkstack/secrets-frontend`: hide the create form, per-row Rotate / Delete buttons, and adjust the empty-state and helper text when the active backend is not writable, plus show a short "read-through" explainer. The local backend stays fully writable.
+
+  State & scale: `writable` is derived on read from the resolved active backend's capabilities (durable config selects the backend), so every pod computes the same answer; no new state is introduced.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@checkstack/secrets-common",
+  "version": "0.1.0",
+  "description": "Shared schemas, contract, and access rules for the Secrets platform",
+  "author": "Checkstack contributors",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "checkstack": {
+    "type": "common",
+    "pluginId": "secrets"
+  },
+  "scripts": {
+    "pack": "bunx @checkstack/scripts plugin-pack",
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "0.12.0",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/tsconfig": "0.0.7",
+    "@types/bun": "^1.3.5",
+    "typescript": "^5.7.2"
+  }
+}

package/src/access.ts

@@ -0,0 +1,26 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Secrets platform.
+ *
+ * `read` lets a user see secret NAMES + metadata (never values), e.g. for
+ * the `${{ secrets.* }}` editor autocomplete. `manage` lets a user create,
+ * rotate, and delete secrets and configure the active backend.
+ */
+export const secretsAccess = {
+  secret: accessPair("secret", {
+    read: {
+      description: "View secret names and metadata (never values)",
+      isDefault: true,
+    },
+    manage: {
+      description: "Create, rotate, delete secrets and configure backends",
+    },
+  }),
+};
+
+/** All access rules for registration with the plugin system. */
+export const secretsAccessRules = [
+  secretsAccess.secret.read,
+  secretsAccess.secret.manage,
+];

package/src/backend-config.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+/**
+ * Vault authentication method. All three are supported:
+ * - `token`: a static Vault token (the `credential`).
+ * - `approle`: AppRole `role_id` (`role`) + `secret_id` (`credential`).
+ * - `oidc`: OIDC/JWT login — `role` is the Vault role, `credential` is the
+ *   JWT/OIDC token presented to Vault's `jwt`/`oidc` auth mount.
+ */
+export const vaultAuthMethodSchema = z.enum(["token", "approle", "oidc"]);
+export type VaultAuthMethod = z.infer<typeof vaultAuthMethodSchema>;
+
+/**
+ * Non-secret Vault connection settings. The auth `credential` itself is
+ * NEVER part of this shape — it is write-only input / encrypted at rest and
+ * never returned to a browser. This is the metadata the admin UI shows.
+ */
+export const vaultConfigMetaSchema = z.object({
+  /** Vault address, e.g. "https://vault.example.com:8200". */
+  address: z.string().url(),
+  /** KV v2 mount path, e.g. "secret". */
+  mount: z.string().min(1).default("secret"),
+  authMethod: vaultAuthMethodSchema,
+  /** AppRole role_id or the OIDC/JWT Vault role name. Unused for `token`. */
+  role: z.string().optional(),
+  /** Auth mount path for approle/oidc (e.g. "approle", "jwt"). */
+  authMount: z.string().optional(),
+  /** Vault namespace (Enterprise), optional. */
+  namespace: z.string().optional(),
+  /** Whether an auth credential is currently stored (never the value). */
+  hasCredential: z.boolean(),
+});
+export type VaultConfigMeta = z.infer<typeof vaultConfigMetaSchema>;
+
+/**
+ * Backend configuration as exposed to the browser: the active backend, the
+ * available backend ids, whether the active backend accepts writes, and
+ * (when configured) the Vault connection metadata. NEVER carries the Vault
+ * auth credential or any secret value.
+ */
+export const backendConfigDtoSchema = z.object({
+  activeBackend: z.string(),
+  availableBackends: z.array(z.string()),
+  /**
+   * Whether the active backend supports creating, rotating, and deleting
+   * secret values from this UI. Read-through backends (e.g. Vault) report
+   * `false`: secret values are managed in the external store, so the UI hides
+   * its write controls. The local backend reports `true`.
+   */
+  writable: z.boolean(),
+  vault: vaultConfigMetaSchema.optional(),
+});
+export type BackendConfigDto = z.infer<typeof backendConfigDtoSchema>;
+
+/**
+ * Input for `setBackendConfig`. The Vault `credential` is write-only: it is
+ * accepted here, stored encrypted, and never returned. Omit `credential` on
+ * update to keep the existing one.
+ */
+export const setBackendConfigInputSchema = z.object({
+  activeBackend: z.string().min(1),
+  vault: z
+    .object({
+      address: z.string().url(),
+      mount: z.string().min(1).default("secret"),
+      authMethod: vaultAuthMethodSchema,
+      role: z.string().optional(),
+      authMount: z.string().optional(),
+      namespace: z.string().optional(),
+      /** Write-only auth credential (token / secret_id / OIDC JWT). */
+      credential: z.string().optional(),
+    })
+    .optional(),
+});
+export type SetBackendConfigInput = z.infer<typeof setBackendConfigInputSchema>;
+
+/** Result of `testBackend` — status only, never a secret value. */
+export const testBackendResultSchema = z.object({
+  ok: z.boolean(),
+  /** Human-readable detail (auth failure reason, etc.). Never a value. */
+  message: z.string(),
+});
+export type TestBackendResult = z.infer<typeof testBackendResultSchema>;

package/src/env-mapping.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import {
+  secretEnvValueSchema,
+  secretEnvMappingSchema,
+  normalizeSecretEnvValue,
+  toSecretTemplate,
+} from "./env-mapping";
+
+// The value schema is a plain union (NO transform — it must stay
+// JSON-Schema-representable for the plugin config UI). It ACCEPTS both a
+// canonical template and a bare secret name, returning the value unchanged;
+// normalization to the canonical template is done separately by
+// `normalizeSecretEnvValue` at the consumption boundary.
+describe("secretEnvValueSchema", () => {
+  it("accepts a canonical template unchanged", () => {
+    expect(secretEnvValueSchema.parse("${{ secrets.jira_token }}")).toBe(
+      "${{ secrets.jira_token }}",
+    );
+    expect(secretEnvValueSchema.parse("${{secrets.x}}")).toBe("${{secrets.x}}");
+  });
+
+  it("accepts a bare secret name unchanged (no transform on parse)", () => {
+    expect(secretEnvValueSchema.parse("SECRET")).toBe("SECRET");
+    expect(secretEnvValueSchema.parse("jira_token")).toBe("jira_token");
+    // Hyphens are allowed in secret names.
+    expect(secretEnvValueSchema.parse("my-secret")).toBe("my-secret");
+  });
+
+  it("is representable in JSON Schema (no transform — guards plugin load)", () => {
+    // The plugin manager renders config schemas to JSON Schema at load time;
+    // a zod `.transform()` here throws "Transforms cannot be represented in
+    // JSON Schema" and crashes plugin load. Assert generation succeeds.
+    expect(() => z.toJSONSchema(secretEnvValueSchema)).not.toThrow();
+    expect(() => z.toJSONSchema(secretEnvMappingSchema)).not.toThrow();
+  });
+
+  it("rejects an invalid secret name", () => {
+    expect(() => secretEnvValueSchema.parse("1secret")).toThrow();
+    expect(() => secretEnvValueSchema.parse("not a name")).toThrow();
+    expect(() => secretEnvValueSchema.parse("")).toThrow();
+  });
+
+  it("accepts existing partial-template (inline) interpolation", () => {
+    expect(secretEnvValueSchema.parse("u:${{ secrets.pw }}@host")).toBe(
+      "u:${{ secrets.pw }}@host",
+    );
+  });
+
+  it("rejects a value with no secret reference and no valid bare name", () => {
+    expect(() => secretEnvValueSchema.parse("${{ env.FOO }}")).toThrow();
+  });
+});
+
+describe("normalizeSecretEnvValue", () => {
+  it("wraps a bare secret name in the canonical template", () => {
+    expect(normalizeSecretEnvValue("SECRET")).toBe("${{ secrets.SECRET }}");
+    expect(normalizeSecretEnvValue("my-secret")).toBe(
+      "${{ secrets.my-secret }}",
+    );
+  });
+
+  it("leaves a template (or any value containing one) unchanged", () => {
+    expect(normalizeSecretEnvValue("${{ secrets.jira_token }}")).toBe(
+      "${{ secrets.jira_token }}",
+    );
+    expect(normalizeSecretEnvValue("u:${{ secrets.pw }}@host")).toBe(
+      "u:${{ secrets.pw }}@host",
+    );
+  });
+});
+
+describe("secretEnvMappingSchema", () => {
+  it("accepts a bare-name value (unchanged on parse)", () => {
+    expect(secretEnvMappingSchema.parse({ secret: "SECRET" })).toEqual({
+      secret: "SECRET",
+    });
+  });
+
+  it("accepts a mix of template and bare-name values unchanged", () => {
+    expect(
+      secretEnvMappingSchema.parse({
+        API_TOKEN: "${{ secrets.jira_token }}",
+        DB: "db_pass",
+      }),
+    ).toEqual({
+      API_TOKEN: "${{ secrets.jira_token }}",
+      DB: "db_pass",
+    });
+  });
+
+  it("rejects an invalid env-var key", () => {
+    expect(() =>
+      secretEnvMappingSchema.parse({ "1BAD": "SECRET" }),
+    ).toThrow();
+  });
+});
+
+describe("toSecretTemplate", () => {
+  it("wraps a name in the canonical template", () => {
+    expect(toSecretTemplate("api")).toBe("${{ secrets.api }}");
+  });
+});

package/src/env-mapping.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import {
+  SECRET_NAME_REGEX,
+  secretNameSchema,
+  secretTemplateSchema,
+} from "./secret-field";
+
+/**
+ * Valid POSIX-ish environment variable name: starts with a letter or
+ * underscore, then letters, digits, underscores. Upper-case is the
+ * convention but not enforced (shells are case-sensitive).
+ */
+export const ENV_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export const envNameSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(
+    ENV_NAME_REGEX,
+    "Environment variable names must start with a letter or underscore and contain only letters, digits, or underscores",
+  );
+
+/**
+ * Render a bare secret name as its canonical `${{ secrets.NAME }}` template.
+ * Shared with the UI serializer so both produce identical canonical output.
+ */
+export function toSecretTemplate(secretName: string): string {
+  return `\${{ secrets.${secretName} }}`;
+}
+
+/**
+ * A single secret→env mapping VALUE. The canonical (stored / serialized)
+ * form is the `${{ secrets.NAME }}` template, but a bare secret name (e.g.
+ * `"jira_token"`, as a YAML / GitOps shorthand or legacy data) is TOLERATED
+ * on input. Only a pure secret reference (a whole-value template) or a pure
+ * bare secret name is accepted — arbitrary interpolation or partial templates
+ * are not.
+ *
+ * IMPORTANT: this is a plain union with NO `.transform()`. This schema is
+ * embedded (via `secretEnvMappingSchema`) in plugin action/collector CONFIG
+ * schemas, which the plugin manager renders to JSON Schema for the UI — and a
+ * zod transform "cannot be represented in JSON Schema" (it throws at load
+ * time). Normalization of a bare name to the canonical template therefore
+ * happens at the CONSUMPTION boundary instead, via
+ * {@link normalizeSecretEnvValue} (called by the run resolver and the test
+ * placeholder builder), not on parse.
+ */
+export const secretEnvValueSchema = z.union([
+  secretTemplateSchema,
+  secretNameSchema,
+]);
+
+/**
+ * Normalize a single `secretEnv` mapping value to its canonical
+ * `${{ secrets.NAME }}` template form: a bare secret name is wrapped, an
+ * already-canonical template (or any value containing a `${{ … }}`) is
+ * returned unchanged. Apply this at every point that parses the value as a
+ * template, so a tolerated bare name resolves / placeholder-builds correctly.
+ */
+export function normalizeSecretEnvValue(value: string): string {
+  return SECRET_NAME_REGEX.test(value) ? toSecretTemplate(value) : value;
+}
+
+/**
+ * A consumer's explicit secret→env allowlist:
+ * `{ API_TOKEN: "${{ secrets.jira_token }}" }`.
+ *
+ * Each key is the env var the consumer's run sees; each value is a
+ * `${{ secrets.NAME }}` template resolved against the active backend (a bare
+ * secret name is tolerated on input and normalized to the template — see
+ * {@link secretEnvValueSchema}). This is the least-privilege contract: only
+ * the secrets named here are resolved and injected for the consumer's runs
+ * (no ambient access).
+ */
+export const secretEnvMappingSchema = z.record(
+  envNameSchema,
+  secretEnvValueSchema,
+);
+
+export type SecretEnvMapping = z.infer<typeof secretEnvMappingSchema>;

package/src/hooks.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/**
+ * Hook id fired when a secret is created, rotated, or deleted. The actual
+ * `Hook` object is created in `@checkstack/secrets-backend` (via
+ * `createHook` from `@checkstack/backend-api`); only the id + payload
+ * shape live here so consumers can reference them without a backend dep.
+ *
+ * Consumers (e.g. gitops) subscribe to re-reconcile entities that
+ * reference the changed secret.
+ */
+export const SECRETS_CHANGED_HOOK_ID = "secrets.changed";
+
+export const secretsChangedPayloadSchema = z.object({
+  /** Name of the secret that changed. */
+  name: z.string(),
+  /** What happened to it. */
+  change: z.enum(["created", "rotated", "deleted"]),
+});
+
+export type SecretsChangedPayload = z.infer<typeof secretsChangedPayloadSchema>;

package/src/index.ts

@@ -0,0 +1,62 @@
+export { pluginMetadata } from "./plugin-metadata";
+export { secretsAccess, secretsAccessRules } from "./access";
+export { secretsRoutes } from "./routes";
+export {
+  SECRET_NAME_REGEX,
+  SECRET_TEMPLATE_REGEX,
+  secretNameSchema,
+  secretTemplateSchema,
+  collectSecretNames,
+  type SecretName,
+} from "./secret-field";
+export {
+  ENV_NAME_REGEX,
+  envNameSchema,
+  secretEnvMappingSchema,
+  secretEnvValueSchema,
+  normalizeSecretEnvValue,
+  toSecretTemplate,
+  type SecretEnvMapping,
+} from "./env-mapping";
+export { secretMetadataSchema, type SecretMetadata } from "./metadata";
+export {
+  vaultAuthMethodSchema,
+  vaultConfigMetaSchema,
+  backendConfigDtoSchema,
+  setBackendConfigInputSchema,
+  testBackendResultSchema,
+  type VaultAuthMethod,
+  type VaultConfigMeta,
+  type BackendConfigDto,
+  type SetBackendConfigInput,
+  type TestBackendResult,
+} from "./backend-config";
+export {
+  maskSecrets,
+  maskSecretsDeep,
+  DEFAULT_MASK_TOKEN,
+  MIN_MASKABLE_LENGTH,
+} from "./masking";
+export {
+  maskScriptRunOutput,
+  type ScriptRunOutput,
+} from "./mask-run-result";
+export {
+  buildTestSecretEnv,
+  secretTestPlaceholder,
+} from "./test-secret-env";
+export {
+  INTERNAL_SECRET_PREFIX,
+  internalSecretName,
+  isInternalSecretName,
+} from "./internal-secrets";
+export {
+  SECRETS_CHANGED_HOOK_ID,
+  secretsChangedPayloadSchema,
+  type SecretsChangedPayload,
+} from "./hooks";
+export {
+  secretsContract,
+  SecretsApi,
+  type SecretsContract,
+} from "./rpc-contract";

package/src/internal-secrets.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "bun:test";
+import {
+  INTERNAL_SECRET_PREFIX,
+  internalSecretName,
+  isInternalSecretName,
+} from "./internal-secrets";
+
+describe("internal secret names", () => {
+  it("builds a prefixed colon-joined name", () => {
+    expect(internalSecretName("script-packages", "registry-auth-token")).toBe(
+      `${INTERNAL_SECRET_PREFIX}script-packages:registry-auth-token`,
+    );
+  });
+
+  it("recognizes internal names and rejects ordinary ones", () => {
+    expect(isInternalSecretName(internalSecretName("a", "b"))).toBe(true);
+    expect(isInternalSecretName("jira_token")).toBe(false);
+    expect(isInternalSecretName("")).toBe(false);
+  });
+});

package/src/internal-secrets.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal (platform-managed) secrets.
+ *
+ * Some platform secrets are not user-managed named secrets — they back a
+ * specific feature (e.g. the script-package registry auth token, or a
+ * connection's credential fields). These are stored under a reserved name
+ * prefix so they are:
+ *
+ *  - hidden from the user-facing Secrets UI (`listSecrets` / `listSecretNames`
+ *    exclude them — they aren't `${{ secrets.NAME }}`-referenceable names);
+ *  - always kept on the local (always-writable, AES-GCM) backend, never the
+ *    active external backend (Vault is read-through and has no `set`), so
+ *    writing them never breaks when Vault is the active backend.
+ */
+export const INTERNAL_SECRET_PREFIX = "__internal__:";
+
+/** Build a reserved internal secret name from a namespace + key parts. */
+export function internalSecretName(...parts: string[]): string {
+  return `${INTERNAL_SECRET_PREFIX}${parts.join(":")}`;
+}
+
+/** Whether a secret name is a reserved internal name (excluded from the UI). */
+export function isInternalSecretName(name: string): boolean {
+  return name.startsWith(INTERNAL_SECRET_PREFIX);
+}

package/src/mask-run-result.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "bun:test";
+import { maskScriptRunOutput } from "./mask-run-result";
+
+describe("maskScriptRunOutput", () => {
+  it("redacts secret values from stdout, stderr, error, and result", () => {
+    const masked = maskScriptRunOutput({
+      output: {
+        result: { token: "gh_secretToken123", nested: ["gh_secretToken123"] },
+        stdout: "printing gh_secretToken123 to stdout",
+        stderr: "error referencing db-password-456",
+        error: "failed with db-password-456",
+      },
+      values: ["gh_secretToken123", "db-password-456"],
+    });
+    expect(masked.stdout).toBe("printing **** to stdout");
+    expect(masked.stderr).toBe("error referencing ****");
+    expect(masked.error).toBe("failed with ****");
+    expect(masked.result).toEqual({ token: "****", nested: ["****"] });
+  });
+
+  it("is a no-op with an empty value set", () => {
+    const output = {
+      result: { token: "gh_secretToken123" },
+      stdout: "gh_secretToken123",
+      stderr: "",
+    };
+    const masked = maskScriptRunOutput({ output, values: [] });
+    expect(masked).toBe(output);
+  });
+
+  it("leaves result/error absent when not provided", () => {
+    const masked = maskScriptRunOutput({
+      output: { stdout: "has topsecretvalue", stderr: "clean" },
+      values: ["topsecretvalue"],
+    });
+    expect(masked.stdout).toBe("has ****");
+    expect("result" in masked).toBe(false);
+    expect("error" in masked).toBe(false);
+  });
+});

package/src/mask-run-result.ts

@@ -0,0 +1,50 @@
+import { maskSecrets, maskSecretsDeep } from "./masking";
+
+/**
+ * The captured output of a script/shell run — the central shape produced
+ * by the script runners and surfaced to users (automation
+ * `run_script`/`run_shell` artifacts, the in-UI test panel, healthcheck
+ * collectors). Masking is applied to EVERY field that can carry a secret
+ * the run was given.
+ */
+export interface ScriptRunOutput {
+  result?: unknown;
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+
+/**
+ * Redact every literal occurrence of the run's resolved secret `values`
+ * out of a script run's output before it is persisted or returned. This is
+ * the central, reusable leak-masking seam: callers pass the run-scoped,
+ * least-privilege value set (only that run's resolved secrets).
+ *
+ * `result` (an arbitrary JSON value) is masked deeply (keys + string
+ * leaves); `stdout`/`stderr`/`error` are masked as text. With an empty
+ * `values` set the output is returned unchanged (no resolved secrets to
+ * redact).
+ */
+export function maskScriptRunOutput<T extends ScriptRunOutput>({
+  output,
+  values,
+}: {
+  output: T;
+  values: Iterable<string>;
+}): T {
+  const valueArray = [...values];
+  if (valueArray.length === 0) {
+    return output;
+  }
+  return {
+    ...output,
+    ...(output.result === undefined
+      ? {}
+      : { result: maskSecretsDeep({ value: output.result, values: valueArray }) }),
+    stdout: maskSecrets({ text: output.stdout, values: valueArray }),
+    stderr: maskSecrets({ text: output.stderr, values: valueArray }),
+    ...(output.error === undefined
+      ? {}
+      : { error: maskSecrets({ text: output.error, values: valueArray }) }),
+  };
+}