@ninedeploy/schemas 0.10.6 → 0.16.1

package/src/publicAccess.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+// ── Public database access (0.14) ──────────────────────────────────────────
+// Request and response shapes for `/v1/databases/:id/public-access`. A
+// per-database Traefik TCP sidecar (`nd-dbpub-<slug>`) publishes one host
+// port, gated by a required IP allow-list. These are SHAPE checks only: the
+// server validates every allow-list entry with `node:net` (and refuses `/0`),
+// checks the port against reserved and in-use host ports, and refuses engines
+// and TLS modes the sidecar cannot serve. Design: DESIGN.md §1.
+
+export const PUBLIC_ACCESS_PORT_MIN = 1024;
+export const PUBLIC_ACCESS_PORT_MAX = 65535;
+export const PUBLIC_ACCESS_ALLOWLIST_MAX = 100;
+
+/** Engines a TCP sidecar can expose. Every other engine is refused with 422. */
+export const publicAccessEngines = ['postgres', 'mysql', 'mariadb', 'redis', 'valkey', 'mongo', 'keydb', 'dragonfly'] as const;
+
+/** Mirrors `databasePublicTlsMode` in `@ninedeploy/db`. */
+export const publicAccessTlsMode = z.enum(['none', 'terminate']);
+export type PublicAccessTlsMode = z.infer<typeof publicAccessTlsMode>;
+
+export const publicAccessPort = z.number().int().min(PUBLIC_ACCESS_PORT_MIN).max(PUBLIC_ACCESS_PORT_MAX);
+
+/** One allow-list entry as typed (an address or CIDR); the server parses it. */
+export const publicAccessAllowlistEntry = z.string().trim().min(1).max(64);
+
+/** 1–100 entries. An empty allow-list is never "allow everyone". */
+export const publicAccessAllowlist = z.array(publicAccessAllowlistEntry).min(1).max(PUBLIC_ACCESS_ALLOWLIST_MAX);
+
+/** The hostname clients connect to (and, in terminate mode, the TLS name). */
+export const publicAccessHostname = z
+  .string()
+  .trim()
+  .min(1)
+  .max(253)
+  .regex(
+    /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)(?:\.(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?))*$/,
+    'must be a valid hostname',
+  );
+
+/**
+ * PUT /v1/databases/:id/public-access (operator). Applies synchronously and
+ * answers with the GET shape. Disabling is DELETE, so `enabled` is pinned to
+ * `true` here.
+ */
+export const publicAccessPut = z.object({
+  enabled: z.literal(true),
+  port: publicAccessPort,
+  ipAllowlist: publicAccessAllowlist,
+  tlsMode: publicAccessTlsMode.default('none'),
+  tlsHostname: publicAccessHostname.optional(),
+});
+export type PublicAccessPut = z.input<typeof publicAccessPut>;
+
+/** GET (db admin) and PUT response. `configured: false` = no row. */
+export const publicAccessStatus = z.object({
+  /** false for engines a TCP sidecar cannot expose. */
+  supported: z.boolean(),
+  configured: z.boolean(),
+  enabled: z.boolean(),
+  port: z.number().int().nullable(),
+  tlsMode: publicAccessTlsMode,
+  tlsHostname: z.string().nullable(),
+  ipAllowlist: z.array(z.string()),
+  status: z.enum(['off', 'running', 'error']),
+  lastError: z.string().nullable(),
+  appliedAt: z.string().nullable(),
+  /** `tlsHostname`, else the panel domain, else the host of the public URL. */
+  publicHost: z.string().nullable(),
+});
+export type PublicAccessStatus = z.infer<typeof publicAccessStatus>;
+
+/** The `publicAccess` field added to the database serializer; null when unconfigured. */
+export const databasePublicAccessSummary = z
+  .object({
+    enabled: z.boolean(),
+    port: z.number().int(),
+  })
+  .nullable();
+export type DatabasePublicAccessSummary = z.infer<typeof databasePublicAccessSummary>;

package/src/runtimeVersions.ts

@@ -0,0 +1,232 @@
+/**
+ * Curated runtime version catalog — the single source of truth for every
+ * language version NineDeploy suggests anywhere in the product (Manifest
+ * Creator presets, the CLI's `starterManifest`, the runtime version picker).
+ *
+ * Why this file exists: these versions used to be hand-written literals
+ * duplicated across `apps/web` and `packages/sdk`. Nobody owned them, so
+ * they drifted until the shipped defaults pinned runtimes that had gone
+ * end-of-life. Everything now derives from this one table.
+ *
+ * The catalog is *advisory*, never a constraint. `runtime.version` in the
+ * manifest schema stays free-form (`^\d+(?:\.\d+){0,2}$`), so an operator
+ * can pin any version their build needs — including an EOL one. What the
+ * catalog buys us is a sensible default plus an honest warning when the
+ * pinned version is no longer supported upstream.
+ *
+ * ── Maintaining this file ────────────────────────────────────────────────
+ * Bump `RUNTIME_CATALOG_REVIEWED` whenever you touch the table, and check
+ * it against upstream release schedules:
+ *   Node    https://nodejs.org/en/about/previous-releases
+ *   Python  https://devguide.python.org/versions/
+ *   Go      https://go.dev/doc/devel/release
+ *   Ruby    https://www.ruby-lang.org/en/downloads/branches/
+ *   PHP     https://www.php.net/supported-versions.php
+ *   Java    https://adoptium.net/support/
+ *   Rust    https://www.rust-lang.org/
+ */
+import type { RuntimeType } from './ninedeployManifest.js';
+
+/**
+ * ISO date the table below was last checked against upstream schedules.
+ * Surfaced in the UI so a stale catalog is visible rather than silent.
+ */
+export const RUNTIME_CATALOG_REVIEWED = '2026-08-26';
+
+/**
+ * Upstream support state of a version, ordered from healthiest to worst.
+ *
+ * - `current`     — newest stable release; ahead of the recommended pin.
+ * - `lts`         — long-term-support line; the safe production choice.
+ * - `maintenance` — still supported, but no longer the primary line.
+ * - `security`    — security fixes only; no bug fixes.
+ * - `eol`         — unsupported upstream. Usable, but nothing gets patched.
+ */
+export type RuntimeSupport = 'current' | 'lts' | 'maintenance' | 'security' | 'eol';
+
+export interface RuntimeVersionOption {
+  /** Value written into `runtime.version` — matches the manifest regex. */
+  version: string;
+  /** Human label for the picker, e.g. "24 — Active LTS". */
+  label: string;
+  support: RuntimeSupport;
+  /** ISO date support ends (or ended). Omitted when upstream has not set one. */
+  eol?: string;
+}
+
+export interface RuntimeVersionCatalogEntry {
+  /** Display name used in advisory messages, e.g. "Node.js". */
+  name: string;
+  /** The version presets and the "recommended" hint use. Must appear in `options`. */
+  recommended: string;
+  /** Newest first — the picker renders them in this order. */
+  options: readonly RuntimeVersionOption[];
+}
+
+/**
+ * Versions offered per runtime. Only runtimes we can meaningfully pin appear
+ * here; `auto` and `static` have no version axis and are absent by design.
+ *
+ * Each list keeps a couple of EOL entries on purpose: teams migrating an
+ * existing app need to reproduce their current runtime before they can move
+ * off it, and an undocumented version they have to guess at is worse than a
+ * documented one carrying a warning.
+ */
+export const RUNTIME_VERSION_CATALOG: Partial<Record<RuntimeType, RuntimeVersionCatalogEntry>> = {
+  node: {
+    name: 'Node.js',
+    recommended: '24',
+    options: [
+      { version: '26', label: '26 — Current', support: 'current', eol: '2029-04-30' },
+      { version: '24', label: '24 — Active LTS', support: 'lts', eol: '2028-04-30' },
+      { version: '22', label: '22 — Maintenance LTS', support: 'maintenance', eol: '2027-04-30' },
+      { version: '20', label: '20 — end-of-life', support: 'eol', eol: '2026-04-30' },
+      { version: '18', label: '18 — end-of-life', support: 'eol', eol: '2025-04-30' },
+    ],
+  },
+  python: {
+    name: 'Python',
+    recommended: '3.14',
+    options: [
+      { version: '3.14', label: '3.14 — latest stable', support: 'current', eol: '2030-10-31' },
+      { version: '3.13', label: '3.13 — bugfix', support: 'maintenance', eol: '2029-10-31' },
+      { version: '3.12', label: '3.12 — security fixes only', support: 'security', eol: '2028-10-31' },
+      { version: '3.11', label: '3.11 — security fixes only', support: 'security', eol: '2027-10-31' },
+    ],
+  },
+  go: {
+    name: 'Go',
+    recommended: '1.27',
+    options: [
+      { version: '1.27', label: '1.27 — latest stable', support: 'current' },
+      { version: '1.26', label: '1.26 — supported', support: 'maintenance' },
+      { version: '1.25', label: '1.25 — end-of-life', support: 'eol' },
+      { version: '1.24', label: '1.24 — end-of-life', support: 'eol' },
+    ],
+  },
+  ruby: {
+    name: 'Ruby',
+    recommended: '3.4',
+    options: [
+      { version: '4.0', label: '4.0 — latest stable', support: 'current' },
+      { version: '3.4', label: '3.4 — normal maintenance', support: 'maintenance' },
+      { version: '3.3', label: '3.3 — security fixes only', support: 'security', eol: '2027-03-31' },
+      { version: '3.2', label: '3.2 — end-of-life', support: 'eol', eol: '2026-04-01' },
+    ],
+  },
+  php: {
+    name: 'PHP',
+    recommended: '8.4',
+    options: [
+      { version: '8.5', label: '8.5 — active support', support: 'current', eol: '2029-12-31' },
+      { version: '8.4', label: '8.4 — active support', support: 'maintenance', eol: '2028-12-31' },
+      { version: '8.3', label: '8.3 — security fixes only', support: 'security', eol: '2027-12-31' },
+      { version: '8.2', label: '8.2 — security fixes only', support: 'security', eol: '2026-12-31' },
+      { version: '8.1', label: '8.1 — end-of-life', support: 'eol', eol: '2025-12-31' },
+    ],
+  },
+  java: {
+    name: 'Java',
+    recommended: '25',
+    options: [
+      { version: '26', label: '26 — latest feature release (non-LTS)', support: 'current' },
+      { version: '25', label: '25 — LTS', support: 'lts', eol: '2031-09-30' },
+      { version: '21', label: '21 — LTS', support: 'lts', eol: '2029-12-31' },
+      { version: '17', label: '17 — LTS', support: 'maintenance', eol: '2027-10-31' },
+    ],
+  },
+  rust: {
+    name: 'Rust',
+    // Rust ships a new stable every six weeks and backports nothing, so any
+    // version below the newest stable is unsupported by definition. Expect
+    // this list to need a bump more often than the others.
+    recommended: '1.98',
+    options: [
+      { version: '1.98', label: '1.98 — latest stable', support: 'current' },
+      { version: '1.97', label: '1.97 — superseded', support: 'eol' },
+      { version: '1.96', label: '1.96 — superseded', support: 'eol' },
+      { version: '1.95', label: '1.95 — superseded', support: 'eol' },
+    ],
+  },
+};
+
+/** Versions offered for a runtime type. Empty for types with no version axis. */
+export function runtimeVersionOptions(type: RuntimeType): readonly RuntimeVersionOption[] {
+  return RUNTIME_VERSION_CATALOG[type]?.options ?? [];
+}
+
+/**
+ * The version presets pin for a runtime, or `undefined` when the type has no
+ * version axis (`auto`, `static`) — in which case the manifest should omit
+ * `runtime.version` entirely and let Nixpacks decide.
+ */
+export function recommendedRuntimeVersion(type: RuntimeType): string | undefined {
+  return RUNTIME_VERSION_CATALOG[type]?.recommended;
+}
+
+/**
+ * Resolve an operator-typed version to its catalog entry.
+ *
+ * Matching is longest-prefix on dot boundaries, so `20.18.1` resolves to
+ * Node's `20` entry and `3.12.4` to Python's `3.12` — pinning a patch
+ * release still yields the right support status. The dot boundary is what
+ * keeps `2` from matching `20`.
+ */
+export function findRuntimeVersion(
+  type: RuntimeType,
+  version: string,
+): RuntimeVersionOption | undefined {
+  return [...runtimeVersionOptions(type)]
+    .sort((a, b) => b.version.length - a.version.length)
+    .find((o) => version === o.version || version.startsWith(`${o.version}.`));
+}
+
+/** A note to show next to the version field. `error` is not a blocker — only a warning. */
+export interface RuntimeVersionAdvisory {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+}
+
+/**
+ * Describe the health of a pinned version, or `null` when there is nothing
+ * worth saying (supported version, no version pinned, runtime with no
+ * version axis).
+ *
+ * Deliberately never rejects: an EOL pin is a warning, not an error, because
+ * reproducing a legacy runtime is a legitimate reason to deploy one.
+ */
+export function runtimeVersionAdvisory(
+  type: RuntimeType,
+  version: string | undefined,
+): RuntimeVersionAdvisory | null {
+  const entry = RUNTIME_VERSION_CATALOG[type];
+  if (!entry || !version) return null;
+
+  const match = findRuntimeVersion(type, version);
+  if (!match) {
+    return {
+      level: 'info',
+      message: `${entry.name} ${version} is not in NineDeploy's catalog (last reviewed ${RUNTIME_CATALOG_REVIEWED}). The build will still try it — Nixpacks resolves the version itself.`,
+    };
+  }
+
+  // One shared clause for both levels: upstream dates are a label, not a
+  // tense, so the same wording works whether the date is past or future.
+  const support = match.eol ? ` Upstream support: ${match.eol}.` : '';
+
+  if (match.support === 'eol') {
+    return {
+      level: 'error',
+      message: `${entry.name} ${match.version} is end-of-life and no longer receives security patches. You can still deploy it — ${entry.recommended} is the recommended pin.${support}`,
+    };
+  }
+
+  if (match.support === 'security') {
+    return {
+      level: 'warn',
+      message: `${entry.name} ${match.version} receives security fixes only — no bug fixes. Recommended pin: ${entry.recommended}.${support}`,
+    };
+  }
+
+  return null;
+}

package/src/secretProviders.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { providerBaseUrl } from './common.js';
+
+// ── Secret managers (0.14) ─────────────────────────────────────────────────
+// Request and response shapes for `/v1/settings/secret-providers`. HashiCorp
+// Vault / OpenBao (KV v2) and AWS Secrets Manager run alongside the existing
+// settings-based Infisical / Doppler provider, which is untouched. Credentials
+// only ever appear in REQUEST shapes; on update an omitted credential field
+// keeps the stored value. The server enforces https (http only with private
+// egress) and proves the settings with a test call. Design: DESIGN.md §4.
+
+/** Mirrors `secretProviderKind` in `@ninedeploy/db`. */
+export const secretProviderKind = z.enum(['vault', 'aws']);
+export type SecretProviderKind = z.infer<typeof secretProviderKind>;
+
+// ── Reference grammar pieces (DESIGN §4.1) ─────────────────────────────────
+
+/**
+ * A Vault path relative to the KV v2 mount: segments of `[A-Za-z0-9_.-]+`
+ * joined by `/`, no leading or trailing `/`, and no `.` or `..` segment.
+ */
+export const VAULT_PATH_RE = /^(?!\.\.?(?:\/|$))[A-Za-z0-9_.-]+(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9_.-]+)*$/;
+/** A KV v2 field name. */
+export const VAULT_FIELD_RE = /^[A-Za-z0-9_.-]+$/;
+/** An AWS secret name or full ARN. */
+export const AWS_SECRET_ID_RE = /^[A-Za-z0-9/_+=.@:-]{1,2048}$/;
+export const AWS_REGION_RE = /^[a-z]{2}(-gov)?-[a-z]+-\d$/;
+export const AWS_ACCESS_KEY_ID_RE = /^(AKIA|ASIA)[A-Z0-9]{16}$/;
+
+export const vaultPath = z.string().max(1024).regex(VAULT_PATH_RE, 'invalid Vault path');
+export const awsSecretId = z.string().regex(AWS_SECRET_ID_RE, 'invalid AWS secret id');
+
+// ── HashiCorp Vault / OpenBao ──────────────────────────────────────────────
+
+export const vaultAuthMethod = z.enum(['token', 'approle']);
+export type VaultAuthMethod = z.infer<typeof vaultAuthMethod>;
+
+export const vaultProviderConfig = z
+  .object({
+    address: providerBaseUrl,
+    /** Vault Enterprise / OpenBao namespace (`X-Vault-Namespace`). */
+    namespace: vaultPath.optional(),
+    mount: vaultPath.default('secret'),
+    authMethod: vaultAuthMethod,
+    approleMount: vaultPath.default('approle'),
+  })
+  .strict();
+export type VaultProviderConfig = z.input<typeof vaultProviderConfig>;
+
+const vaultSecret = z.string().min(1).max(4096);
+
+export const vaultProviderCredentials = z
+  .object({
+    token: vaultSecret.optional(),
+    roleId: vaultSecret.optional(),
+    secretId: vaultSecret.optional(),
+  })
+  .strict();
+export type VaultProviderCredentials = z.infer<typeof vaultProviderCredentials>;
+
+/** PUT /v1/settings/secret-providers/vault. */
+export const vaultProviderPut = z
+  .object({
+    enabled: z.boolean().optional(),
+    config: vaultProviderConfig,
+    credentials: vaultProviderCredentials.optional(),
+  })
+  .strict()
+  .refine((v) => v.config.authMethod !== 'token' || (v.credentials?.roleId === undefined && v.credentials?.secretId === undefined), {
+    message: 'roleId and secretId belong to authMethod "approle"',
+    path: ['credentials'],
+  })
+  .refine((v) => v.config.authMethod !== 'approle' || v.credentials?.token === undefined, {
+    message: 'token belongs to authMethod "token"',
+    path: ['credentials', 'token'],
+  });
+export type VaultProviderPut = z.input<typeof vaultProviderPut>;
+
+// ── AWS Secrets Manager ────────────────────────────────────────────────────
+
+export const awsProviderConfig = z
+  .object({
+    region: z.string().regex(AWS_REGION_RE, 'invalid AWS region'),
+    /** VPC endpoint or compatible service; https. */
+    endpoint: providerBaseUrl.optional(),
+    roleArn: z
+      .string()
+      .max(2048)
+      .regex(/^arn:aws[a-z-]*:iam::\d{12}:role\/[\w+=,.@/-]{1,512}$/, 'invalid IAM role ARN')
+      .optional(),
+    externalId: z
+      .string()
+      .min(2)
+      .max(1224)
+      .regex(/^[\w+=,.@:/-]+$/, 'invalid external id')
+      .optional(),
+    roleSessionName: z
+      .string()
+      .regex(/^[\w+=,.@-]{2,64}$/, 'invalid role session name')
+      .default('ninedeploy'),
+  })
+  .strict()
+  .refine((v) => v.externalId === undefined || v.roleArn !== undefined, {
+    message: 'externalId needs roleArn',
+    path: ['externalId'],
+  });
+export type AwsProviderConfig = z.input<typeof awsProviderConfig>;
+
+export const awsProviderCredentials = z
+  .object({
+    accessKeyId: z.string().regex(AWS_ACCESS_KEY_ID_RE, 'invalid access key id').optional(),
+    secretAccessKey: z.string().min(1).max(256).optional(),
+    sessionToken: z.string().min(1).max(4096).optional(),
+  })
+  .strict();
+export type AwsProviderCredentials = z.infer<typeof awsProviderCredentials>;
+
+/** PUT /v1/settings/secret-providers/aws. */
+export const awsProviderPut = z
+  .object({
+    enabled: z.boolean().optional(),
+    config: awsProviderConfig,
+    credentials: awsProviderCredentials.optional(),
+  })
+  .strict();
+export type AwsProviderPut = z.input<typeof awsProviderPut>;
+
+// ── Test and views ─────────────────────────────────────────────────────────
+
+/** POST /v1/settings/secret-providers/:kind/test. Both probes are optional. */
+export const secretProviderTestRequest = z
+  .object({
+    /** vault: also read this path (relative to the mount). */
+    probePath: vaultPath.optional(),
+    /** aws: also read this secret. */
+    probeSecretId: awsSecretId.optional(),
+  })
+  .strict();
+export type SecretProviderTestRequest = z.infer<typeof secretProviderTestRequest>;
+
+export const secretProviderTestResult = z.object({
+  ok: z.boolean(),
+  /** Redacted; response bodies cut to 200 characters. */
+  detail: z.string(),
+});
+export type SecretProviderTestResult = z.infer<typeof secretProviderTestResult>;
+
+/** One element of GET /v1/settings/secret-providers. Never carries a credential. */
+export const secretProviderView = z.object({
+  kind: secretProviderKind,
+  configured: z.boolean(),
+  enabled: z.boolean(),
+  /** Non-secret settings; `{}` when unconfigured. */
+  config: z.record(z.string(), z.unknown()),
+  hasCredential: z.boolean(),
+  lastTestedAt: z.string().nullable(),
+  lastTestError: z.string().nullable(),
+});
+export type SecretProviderView = z.infer<typeof secretProviderView>;

package/src/secretScan.ts

@@ -0,0 +1,169 @@
+/**
+ * Secret-pattern scanner for `.ninedeploy` manifests.
+ *
+ * The manifest is committed to the repo, so it must NEVER carry real
+ * credentials, tokens or connection strings. This module is a defensive net:
+ * patterns are matched against the raw text, and any hit fails the load.
+ *
+ * The list is intentionally explicit (named patterns) rather than a generic
+ * entropy heuristic — false positives are user-hostile (legitimate values
+ * that look credential-like should pass). Every regex is also bounded to
+ * avoid runaway matching on long inputs.
+ *
+ * Lives in `@ninedeploy/schemas` (not in `@ninedeploy/server`) because the
+ * CLI also needs to run the scan in `ninedeploy manifest validate`. Anything
+ * that loads a manifest — server, CLI, future MCP tool — should reuse this.
+ */
+
+/** A single rule: a human-readable name plus a regex that MUST match the
+ *  *beginning* of a credential — anchoring left keeps the regex from firing
+ *  on substrings inside longer strings. */
+export interface SecretPattern {
+  readonly id: string;
+  readonly description: string;
+  readonly regex: RegExp;
+}
+
+export const SECRET_PATTERNS: ReadonlyArray<SecretPattern> = [
+  {
+    id: 'aws-access-key',
+    description: 'AWS access key id (AKIA…)',
+    regex: /AKIA[0-9A-Z]{16}\b/,
+  },
+  {
+    id: 'github-pat-classic',
+    description: 'GitHub personal access token (ghp_…)',
+    regex: /\bghp_[A-Za-z0-9]{36}\b/,
+  },
+  {
+    id: 'github-pat-fine-grained',
+    description: 'GitHub fine-grained PAT (github_pat_…)',
+    regex: /\bgithub_pat_[A-Za-z0-9_]{82}\b/,
+  },
+  {
+    id: 'gitlab-pat',
+    description: 'GitLab personal access token (glpat-…)',
+    regex: /\bglpat-[A-Za-z0-9_-]{20,}\b/,
+  },
+  {
+    id: 'slack-token',
+    description: 'Slack token (xox[baprs]-…)',
+    regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+  },
+  {
+    id: 'stripe-live-secret',
+    description: 'Stripe live secret key (sk_live_…)',
+    regex: /\bsk_live_[A-Za-z0-9]{24,}\b/,
+  },
+  {
+    id: 'stripe-live-restricted',
+    description: 'Stripe live restricted key (rk_live_…)',
+    regex: /\brk_live_[A-Za-z0-9]{24,}\b/,
+  },
+  {
+    id: 'openai-secret',
+    description: 'OpenAI API key (sk-… / sk-proj-…)',
+    // `(?!ant-)` keeps Anthropic keys single-matched under the anthropic-key
+    // rule; `proj-` is the current project-key prefix whose character set
+    // includes `-`/`_`.
+    regex: /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{40,}\b/,
+  },
+  {
+    id: 'anthropic-key',
+    description: 'Anthropic API key (sk-ant-…)',
+    regex: /\bsk-ant-[A-Za-z0-9_-]{40,}\b/,
+  },
+  {
+    id: 'discord-webhook',
+    description: 'Discord webhook URL (discord…/api/webhooks/…)',
+    regex: /https?:\/\/(?:[A-Za-z0-9-]+\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+/,
+  },
+  {
+    id: 'database-url-credentials',
+    description: 'Database URL with embedded credentials (scheme://user:pass@…)',
+    // The password class accepts either non-special chars or `%XX` percent-
+    // encoded triplets: a literal '@' in the password cannot appear (it is
+    // the user/host delimiter), but the URL-encoded form `%40` can — and
+    // tools that build connection strings from user input routinely emit
+    // `%40` instead of escaping it themselves. The `{3,}` minimum is
+    // measured in raw characters (not encoded triplets) to keep the
+    // "obviously not a secret" guardrail a real password still satisfies.
+    regex: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqps?|mssql):\/\/[^\s:@'"]+:(?:[^\s@'"]|%[0-9A-Fa-f]{2}){3,}@/i,
+  },
+  {
+    id: 'private-key',
+    description: 'PEM private key block',
+    regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  },
+  {
+    id: 'jwt-bearer',
+    description: 'Bearer JWT in a literal value',
+    regex: /\bBearer\s+eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+  },
+];
+
+/** A single secret-pattern hit in scanned text. */
+export interface SecretHit {
+  patternId: string;
+  description: string;
+  /** Index in the original text where the match starts. */
+  start: number;
+  /** Index in the original text where the match ends. */
+  end: number;
+  /** A redacted preview of the matched text (first 4 chars + … + last 2). */
+  redacted: string;
+}
+
+// The scan appends the `g` flag to every pattern — a pattern that already
+// declared it would produce `gg` and throw Invalid flag at scan time. Fail
+// at import instead, where a developer sees it immediately.
+for (const p of SECRET_PATTERNS) {
+  /* v8 ignore next 3 — developer-error guard, not reachable via valid patterns */
+  if (p.regex.flags.includes('g')) {
+    throw new Error(`secret pattern "${p.id}" must not declare the g flag (the scanner adds it)`);
+  }
+}
+
+/**
+ * Run every secret pattern across `text` and return every hit.
+ *
+ * The scan is non-overlapping and bounded — each regex is `\b`-anchored or
+ * scheme-anchored, so a single credential can never span more than one match.
+ */
+export function scanForSecrets(text: string): SecretHit[] {
+  const hits: SecretHit[] = [];
+  for (const pattern of SECRET_PATTERNS) {
+    // matchAll requires the `g` flag; build a per-call global copy so the
+    // module-level regexes never carry stateful lastIndex between scans,
+    // and so EVERY occurrence is reported (the contract says "every hit").
+    const global = new RegExp(pattern.regex.source, `${pattern.regex.flags}g`);
+    for (const match of text.matchAll(global)) {
+      const start = match.index;
+      const end = start + match[0].length;
+      hits.push({
+        patternId: pattern.id,
+        description: pattern.description,
+        start,
+        end,
+        redacted: redact(match[0]),
+      });
+    }
+  }
+  // Sort by start position so the redacted-log line reads in document order.
+  return hits.sort((a, b) => a.start - b.start);
+}
+
+/** Returns true if the text contains anything that looks like a secret. */
+export function hasSecret(text: string): boolean {
+  return scanForSecrets(text).length > 0;
+}
+
+/**
+ * Replace the middle of a string with `…` for safe logging. Keeps the first
+ * 4 and last 2 characters when the input is long enough; otherwise just
+ * emits `<redacted:N>` so the length is still visible.
+ */
+export function redact(value: string): string {
+  if (value.length <= 8) return `<redacted:${value.length}>`;
+  return `${value.slice(0, 4)}…${value.slice(-2)} (len=${value.length})`;
+}