@ninedeploy/schemas 0.10.6 → 0.16.1

package/src/backupPolicy.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+
+// ── Per-database backup policy (0.12) ──────────────────────────────────────
+/** Bounds for both retention counts. At least one dump is always kept, so a
+ *  policy can never prune a database's last good backup. */
+export const BACKUP_RETAIN_MIN = 1;
+export const BACKUP_RETAIN_MAX = 365;
+/** What a database WITHOUT a policy gets: the built-in schedule. */
+export const DEFAULT_BACKUP_RETAIN_COUNT = 7;
+
+const retain = z.number().int().min(BACKUP_RETAIN_MIN).max(BACKUP_RETAIN_MAX);
+
+/**
+ * PUT /v1/databases/:id/backup-policy — the whole policy (PUT replaces).
+ * The cron expression is validated with croner (5-part) at the route, the
+ * same rule scheduled jobs use; the schema package has no cron dependency.
+ */
+export const backupPolicyInput = z
+  .object({
+    enabled: z.boolean().default(true),
+    cron: z.string().trim().min(1).max(120),
+    retainCount: retain,
+    /** Remote copies kept; null/omitted = the remote copies of the newest `retainCount` dumps. */
+    retainRemoteCount: retain.nullable().optional().transform((v) => v ?? null),
+    /** A `backup_destinations` id; null/omitted = the active destination. */
+    destinationId: z.number().int().positive().nullable().optional().transform((v) => v ?? null),
+    /** true = keep this database's scheduled dumps on the panel host only. */
+    localOnly: z.boolean().optional().transform((v) => v ?? false),
+  })
+  .refine((p) => !(p.localOnly && p.destinationId != null), {
+    message: 'localOnly and destinationId are mutually exclusive',
+    path: ['destinationId'],
+  })
+  .refine((p) => !(p.localOnly && p.retainRemoteCount != null), {
+    message: 'retainRemoteCount has no effect on a local-only policy',
+    path: ['retainRemoteCount'],
+  });
+export type BackupPolicyInput = z.input<typeof backupPolicyInput>;
+
+/** GET/PUT response. `configured: false` = no policy row: the built-in
+ *  schedule (daily, 7 kept, active destination) applies and `cron` is null. */
+export const backupPolicy = z.object({
+  databaseId: z.number().int(),
+  configured: z.boolean(),
+  enabled: z.boolean(),
+  cron: z.string().nullable(),
+  retainCount: z.number().int(),
+  retainRemoteCount: z.number().int().nullable(),
+  destinationId: z.number().int().nullable(),
+  localOnly: z.boolean(),
+  /** Next scheduled run for a configured, enabled policy (ISO); null otherwise. */
+  nextRunAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+});
+export type BackupPolicy = z.infer<typeof backupPolicy>;

package/src/common.ts

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+
+/** URL-safe slug used for projects, services, routes. */
+export const slug = z
+  .string()
+  .min(2)
+  .max(63)
+  .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, 'lowercase letters, digits and hyphens');
+
+/**
+ * POSIX environment-variable name, as accepted by `docker run --env-file` and
+ * shells: letters, digits and underscores, starting with a letter or
+ * underscore. Surrounding whitespace is trimmed so sloppy input is normalized;
+ * anything else (e.g. `MY VAR`) is rejected — such a key would otherwise break
+ * the deploy at `docker run --env-file` time.
+ */
+export const envVarName = z
+  .string()
+  .trim()
+  .regex(
+    /^[A-Za-z_][A-Za-z0-9_]*$/,
+    'must be a valid environment variable name (letters, digits, underscore; cannot start with a digit)',
+  );
+
+export const id = z.number().int().positive();
+
+/**
+ * An absolute HTTP path (health checks, probe targets).
+ *
+ * Health paths are concatenated onto `http://host:port` before the result is
+ * parsed as a URL, so an unconstrained string can rewrite the authority: the
+ * value `@evil.example.com/` turns `http://127.0.0.1:3000@evil.example.com/`
+ * into a request to evil.example.com with `127.0.0.1:3000` as userinfo. The
+ * leading slash plus the character allowlist (no `@`, no `\`) removes that.
+ */
+export const httpPath = z
+  .string()
+  .max(200)
+  .regex(
+    /^\/[A-Za-z0-9\-._~!$&'()*+,;=:%/?[\]]*$/,
+    'must be an absolute path beginning with "/" (no host, no "@")',
+  );
+
+/**
+ * A git remote URL restricted to transports we actually support.
+ *
+ * `z.url()` alone accepts any parseable URL, including `file://` (local
+ * repository disclosure) and `ext::sh -c …`, git's arbitrary-command
+ * transport. Modern git refuses `ext::` on its own and simple-git blocks
+ * several related options, but neither is this application's control — so the
+ * scheme is pinned here rather than relying on the toolchain to stay strict.
+ */
+export const gitRepoUrl = z
+  .url()
+  .refine((value) => /^(?:https?|ssh):\/\//i.test(value), {
+    message: 'repoUrl must be an http(s) or ssh URL',
+  });
+
+/**
+ * 0.13: the base URL of an operator-supplied git provider API or web UI
+ * (a Gitea instance, GitHub Enterprise Server, `https://github.com`).
+ *
+ * `http:` is accepted HERE on purpose: whether plain http is allowed depends on
+ * the server's `NINEDEPLOY_ALLOW_PRIVATE_EGRESS` escape hatch, which this
+ * package cannot see. The server refuses `http:` unless that flag is set, and
+ * every call still goes through its egress guard. Rejecting http in the schema
+ * would make the documented escape hatch (an internal http-only Gitea)
+ * unusable. Userinfo, query and fragment are refused — a base URL never needs
+ * them, and userinfo would smuggle credentials into a URL that gets logged.
+ * Trailing slashes are dropped so `${base}/api/v1/…` joins cleanly.
+ */
+export const providerBaseUrl = z
+  .string()
+  .trim()
+  .max(2048)
+  .pipe(z.url({ protocol: /^https?$/, message: 'must be an http(s) URL' }))
+  // Everything after the scheme: no `@` (userinfo), `?` or `#`.
+  .refine((value) => !/[@?#]/.test(value.slice(value.indexOf(':') + 3)), {
+    message: 'must be a base URL without credentials, query or fragment',
+  })
+  .transform((value) => value.replace(/\/+$/, ''));
+
+/**
+ * A git branch/ref name. Reaches `git checkout` / `git pull` as an argv
+ * element, so a value starting with `-` would be read as an option rather
+ * than a ref; the allowlist also rules out the `..` and whitespace forms git
+ * itself rejects in `check-ref-format`.
+ */
+export const gitBranch = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z0-9._][A-Za-z0-9._/-]*$/, 'invalid branch name')
+  .refine((v) => !v.includes('..') && !v.endsWith('.lock'), { message: 'invalid branch name' });
+
+/**
+ * A path interpreted relative to the checked-out repository.
+ *
+ * A LEADING SLASH IS ALLOWED and means "from the repo root" — that is the
+ * existing convention for `baseDir` (`/`, `/app`), so rejecting it here would
+ * break real configurations. What is rejected is anything that could climb out
+ * of the checkout once resolved: `..` segments, NUL, and Windows drive
+ * letters.
+ *
+ * This is a usability guard, not the security boundary. The sinks
+ * (`docker build -f` / its build context, `docker compose -f`) resolve these
+ * values against the work dir, so they re-anchor the path themselves — see
+ * `lib/repoPath.ts`.
+ */
+const insideRepo = (value: string): boolean =>
+  !/^[A-Za-z]:/.test(value) &&
+  !value.includes('\0') &&
+  !value.split(/[\\/]/).includes('..');
+
+export const repoRelativePath = z
+  .string()
+  .trim()
+  .max(400)
+  .refine(insideRepo, { message: 'must be a path inside the repository (no "..")' });
+
+/** Same rules as {@link repoRelativePath}; named for the build-context field. */
+export const repoBaseDir = repoRelativePath;
+
+/**
+ * Absolute path inside a container (e.g. `/data`, `/var/lib/uploads`).
+ * Rejected: empty, relative, paths containing NUL, parent-relative segments,
+ * or a leading double slash (Docker treats `//` as the named-volume named
+ * bind-mount form which is not what we want here).
+ */
+export const containerPath = z
+  .string()
+  .min(1)
+  .max(1024)
+  // Anchored on both ends: the old `^\/[^/].*` prefix-match let `/a/../b`,
+  // embedded NUL/newline and interior `//` through. Segments are non-empty,
+  // slash-free and control-char-free; a lone `/` stays valid.
+  .regex(/^\/(?:[^/\0\n\r]+\/?)*$/, 'must be an absolute path starting with a single "/"')
+  .refine((v) => !v.split('/').includes('..'), { message: 'must not contain ".." segments' });
+
+/**
+ * Docker named-volume name: letters (BOTH cases — the `i` flag is deliberate,
+ * r474: docker itself accepts uppercase volume names, and rejecting them
+ * would break attach flows against pre-existing out-of-band volumes), digits,
+ * underscores, hyphens and dots; must start with alnum; max 64 chars (the
+ * volume driver limit on most filesystems). The managed prefixes `nd-svc-` /
+ * `nd-db-` are lowercased by construction; a non-managed name attaches a
+ * pre-existing volume the client created out-of-band.
+ */
+export const dockerVolumeName = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9][a-z0-9_.-]*$/i, 'invalid docker volume name');
+
+/** Cursor-style pagination params. */
+export const pagination = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(25),
+  cursor: z.coerce.number().int().positive().optional(),
+});
+export type Pagination = z.infer<typeof pagination>;
+
+/** Standard error envelope returned by the API. */
+export const errorResponse = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.unknown().optional(),
+  }),
+});
+export type ErrorResponse = z.infer<typeof errorResponse>;
+
+/** A page of results. */
+export function page<T extends z.ZodTypeAny>(item: T) {
+  return z.object({
+    items: z.array(item),
+    nextCursor: z.number().int().positive().nullable(),
+    total: z.number().int().nonnegative().optional(),
+  });
+}

package/src/databaseImport.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { id } from './common.js';
+
+// ── Database dump import (0.14) ────────────────────────────────────────────
+// Request and response shapes for `/v1/databases/:id/imports` and
+// `/v1/backup-destinations/:id/objects`. Uploads are chunked and resumable
+// (Traefik's 60s read timeout would cut a single multi-GB request). The
+// server detects the format by magic bytes, refuses engines and options that
+// do not apply, and enforces size, disk and role rules. Design: DESIGN.md §3.
+
+/** 8 MiB. Advertised by the server on every import; chunks arrive in order. */
+export const DATABASE_IMPORT_CHUNK_SIZE = 8 * 1024 * 1024;
+
+/** Mirrors `databaseImportSource` in `@ninedeploy/db`. */
+export const databaseImportSource = z.enum(['upload', 's3']);
+export type DatabaseImportSource = z.infer<typeof databaseImportSource>;
+
+/** Mirrors `databaseImportStatus` in `@ninedeploy/db`. */
+export const databaseImportStatus = z.enum([
+  'uploading',
+  'pending',
+  'running',
+  'completed',
+  'completed_with_warnings',
+  'failed',
+  'cancelled',
+  'expired',
+]);
+export type DatabaseImportStatus = z.infer<typeof databaseImportStatus>;
+
+/** Mirrors `databaseImportFormat` in `@ninedeploy/db`. */
+export const databaseImportFormat = z.enum(['pg_custom', 'pg_plain', 'mysql_sql', 'mongo_archive', 'rdb']);
+export type DatabaseImportFormat = z.infer<typeof databaseImportFormat>;
+
+/**
+ * Import options. Strict: an unknown key is refused, not dropped. The server
+ * further refuses keys that do not apply to the database's engine, and
+ * applies `singleTransaction: true` when it is omitted (postgres).
+ */
+export const databaseImportOptions = z
+  .object({
+    /** postgres custom format: `--clean --if-exists`. */
+    clean: z.boolean().optional(),
+    /** postgres: wrap the restore in one transaction (server default true). */
+    singleTransaction: z.boolean().optional(),
+    /** mongo: `--drop`. */
+    drop: z.boolean().optional(),
+    /** redis/valkey/keydb/dragonfly: required, the RDB replaces the whole dataset. */
+    confirmReplace: z.boolean().optional(),
+    /** Operator, or a database initialised in the last 10 minutes, only. */
+    skipSafetyBackup: z.boolean().optional(),
+  })
+  .strict();
+export type DatabaseImportOptions = z.infer<typeof databaseImportOptions>;
+
+/**
+ * The engines an import accepts, and the option keys each one applies. The
+ * server refuses (422) any other engine, and any key not listed for the
+ * database's engine. clickhouse, meilisearch and rabbitmq have no import.
+ */
+export const DATABASE_IMPORT_ENGINE_OPTIONS = {
+  postgres: ['clean', 'singleTransaction', 'skipSafetyBackup'],
+  mysql: ['skipSafetyBackup'],
+  mariadb: ['skipSafetyBackup'],
+  mongo: ['drop', 'skipSafetyBackup'],
+  redis: ['confirmReplace', 'skipSafetyBackup'],
+  valkey: ['confirmReplace', 'skipSafetyBackup'],
+  keydb: ['confirmReplace', 'skipSafetyBackup'],
+  dragonfly: ['confirmReplace', 'skipSafetyBackup'],
+} as const satisfies Record<string, ReadonlyArray<keyof DatabaseImportOptions>>;
+export type DatabaseImportEngine = keyof typeof DATABASE_IMPORT_ENGINE_OPTIONS;
+
+const sha256Hex = z
+  .string()
+  .trim()
+  .regex(/^[A-Fa-f0-9]{64}$/, 'sha256 must be 64 hex characters')
+  .transform((v) => v.toLowerCase());
+
+/** Display only; the staging path is always chosen by the server. */
+const importFilename = z.string().trim().min(1).max(255);
+
+const uploadSource = z.object({
+  source: z.literal('upload'),
+  sizeBytes: z.number().int().positive(),
+  sha256: sha256Hex.optional(),
+  filename: importFilename.optional(),
+  options: databaseImportOptions.default({}),
+});
+
+/** S3 imports are operator only (checked in the handler). */
+const s3Source = z.object({
+  source: z.literal('s3'),
+  destinationId: id,
+  key: z.string().min(1).max(1024),
+  options: databaseImportOptions.default({}),
+});
+
+/** POST /v1/databases/:id/imports. */
+export const databaseImportCreate = z.discriminatedUnion('source', [uploadSource, s3Source]);
+export type DatabaseImportCreate = z.input<typeof databaseImportCreate>;
+
+/** One import row as the API returns it. */
+export const databaseImport = z.object({
+  id: z.number().int(),
+  databaseId: z.number().int(),
+  source: databaseImportSource,
+  status: databaseImportStatus,
+  format: databaseImportFormat.nullable(),
+  sizeBytes: z.number().int(),
+  receivedBytes: z.number().int(),
+  chunkSize: z.number().int(),
+  sha256: z.string().nullable(),
+  filename: z.string().nullable(),
+  destinationId: z.number().int().nullable(),
+  objectKey: z.string().nullable(),
+  options: databaseImportOptions,
+  safetyBackupId: z.number().int().nullable(),
+  error: z.string().nullable(),
+  createdByUserId: z.number().int().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  startedAt: z.string().nullable(),
+  completedAt: z.string().nullable(),
+});
+export type DatabaseImport = z.infer<typeof databaseImport>;
+
+/** GET /v1/backup-destinations/:id/objects?prefix= (operator). */
+export const backupDestinationObjectsQuery = z.object({
+  prefix: z.string().max(1024).optional(),
+});
+export type BackupDestinationObjectsQuery = z.infer<typeof backupDestinationObjectsQuery>;
+
+export const backupDestinationObject = z.object({
+  key: z.string(),
+  sizeBytes: z.number().int(),
+  lastModified: z.string().nullable(),
+});
+export type BackupDestinationObject = z.infer<typeof backupDestinationObject>;

package/src/doctor.ts

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+
+/** One actionable observation from a Doctor scan. `id` is deterministic
+ *  (`kind:target`) so a fix request can re-scan, re-locate the finding against
+ *  FRESH state and only then execute — a stale report can never drive a
+ *  destructive action against a target that stopped qualifying in between. */
+export const doctorSeverity = z.enum(['info', 'warn', 'critical']);
+export type DoctorSeverity = z.infer<typeof doctorSeverity>;
+
+export const doctorTargetType = z.enum([
+  'container',
+  'volume',
+  'network',
+  'image',
+  'database',
+  'service',
+  'deployment',
+  'host',
+  // Rows identified by a stored `slug` (see the invalid_slug finding).
+  'project',
+  'workspace',
+  'tunnel',
+  'oidc_provider',
+]);
+export type DoctorTargetType = z.infer<typeof doctorTargetType>;
+
+export const doctorFindingKind = z.enum([
+  /** A Hub-family container sat exited with no live row claiming it. */
+  'exited_container',
+  /** A managed volume (nd-svc-/nd-db-) no row owns any more. */
+  'orphan_volume',
+  /** A per-slug bridge or compose-project network nothing uses any more. */
+  'orphan_network',
+  /** Dangling `<none>` images (safe, uncontroversial reclaim). */
+  'dangling_images',
+  /** Builder cache beyond the noise threshold. */
+  'build_cache',
+  /** Disk usage crossed the warning / critical line. */
+  'disk_pressure',
+  /** Database row says running, the container disagrees. */
+  'database_down',
+  /** Database stuck in `creating` — provisioning never finished. */
+  'database_stuck',
+  /** Service row says running, its runtime container is gone or exited. */
+  'service_runtime_desync',
+  /** A deploy row stuck in queued/building far past any live window. */
+  'stuck_deployment',
+  /**
+   * A stored `slug` that violates the canonical `slug` contract — legacy rows
+   * written before slugify was fixed (r028 stranded a trailing hyphen, r029 a
+   * one-character slug), or a hand-written `input.slug` the create route stored
+   * without re-validating. Such a row is a record its own API rejects on PATCH.
+   */
+  'invalid_slug',
+  /**
+   * r575: the panel's own port listens on a non-loopback address over plain
+   * HTTP (bare-metal default 0.0.0.0:3000) — logins and API tokens crossing
+   * it are readable on the network. Advisory: changing the bind is the
+   * operator's call (it cuts off whoever reaches the panel at http://ip:3000).
+   */
+  'panel_plaintext_exposure',
+  /**
+   * r600: enabled sandbox plugins on a Node whose permission model has no
+   * network scope (< 25) — their code can reach anything the host can.
+   * Advisory: they keep loading (upgrade-safe); upgrading Node closes it.
+   */
+  'sandbox_plugin_network',
+  /**
+   * r620: a stored repository analysis holds a nodeVersion that is not a
+   * version — host file content captured through a symlinked .nvmrc before
+   * 0.10.41. Critical: the exposed secrets must be rotated.
+   */
+  'repo_insights_leak',
+  /**
+   * r655: the Hub's remote template registry is fetched over plain http, so
+   * anyone on the path can swap the catalog (images, env defaults). Advisory:
+   * the source keeps loading (upgrade-safe); new http sources are refused.
+   */
+  'templates_source_plaintext',
+]);
+export type DoctorFindingKind = z.infer<typeof doctorFindingKind>;
+
+/** Executable repair actions. Every one re-validates its precondition against
+ *  current state inside the fix path; the enum is the full surface. */
+export const doctorActionKind = z.enum([
+  'remove_container',
+  'delete_volume',
+  'remove_network',
+  'prune_dangling_images',
+  'prune_build_cache',
+  'run_autoprune',
+  'start_database',
+  'mark_database_error',
+  'sync_service',
+  'cancel_deployment',
+  /**
+   * Rewrite a stored `slug` that violates the canonical contract. Only offered
+   * for tables whose slug is NOT also a live Docker identity — renaming a
+   * service/database/tunnel row alone would desync it from its bridge,
+   * container and volume, so those findings stay advisory with a manual step.
+   */
+  'repair_slug',
+]);
+export type DoctorActionKind = z.infer<typeof doctorActionKind>;
+
+export const doctorFinding = z.object({
+  id: z.string(),
+  kind: doctorFindingKind,
+  severity: doctorSeverity,
+  title: z.string(),
+  detail: z.string(),
+  target: z.object({
+    type: doctorTargetType,
+    name: z.string().nullable(),
+    id: z.number().nullable(),
+  }),
+  /** Null when the finding is advisory only (no automated repair). */
+  action: doctorActionKind.nullable(),
+  sizeBytes: z.number().nullable(),
+});
+export type DoctorFinding = z.infer<typeof doctorFinding>;
+
+export const doctorHostFacts = z.object({
+  diskUsedPercent: z.number(),
+  diskTotalBytes: z.number(),
+  diskFreeBytes: z.number(),
+  dockerImagesBytes: z.number().nullable(),
+  dockerVolumesBytes: z.number().nullable(),
+  dockerBuildCacheBytes: z.number().nullable(),
+});
+export type DoctorHostFacts = z.infer<typeof doctorHostFacts>;
+
+export const doctorReport = z.object({
+  generatedAt: z.string().datetime(),
+  healthy: z.boolean(),
+  totals: z.object({
+    findings: z.number(),
+    critical: z.number(),
+    warn: z.number(),
+    info: z.number(),
+    reclaimableBytes: z.number(),
+  }),
+  host: doctorHostFacts,
+  findings: z.array(doctorFinding),
+});
+export type DoctorReport = z.infer<typeof doctorReport>;
+
+export const doctorFixRequest = z.object({
+  findingId: z.string().min(1),
+});
+export type DoctorFixRequest = z.infer<typeof doctorFixRequest>;
+export type DoctorFixRequestInput = DoctorFixRequest;
+
+export const doctorFixResponse = z.object({
+  fixed: z.boolean(),
+  id: z.string(),
+  action: doctorActionKind,
+  log: z.array(z.string()),
+  report: doctorReport,
+});
+export type DoctorFixResponse = z.infer<typeof doctorFixResponse>;

package/src/environments.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+/**
+ * Environment = a named deployment lane (production / staging / development)
+ * inside a workspace. Services opt in via `services.environment_id`; the
+ * promote flow builds on this grouping.
+ */
+export const environment = z.object({
+  id: z.number().int(),
+  workspaceId: z.number().int(),
+  name: z.string(),
+  slug: z.string(),
+  serviceCount: z.number().int(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+export type Environment = z.infer<typeof environment>;
+
+export const environmentCreate = z.object({
+  workspaceId: z.number().int().positive(),
+  name: z.string().min(1).max(80),
+});
+export type EnvironmentCreateInput = z.infer<typeof environmentCreate>;