@ninedeploy/schemas 0.10.6 → 0.16.1

package/src/ninedeployManifest.ts

@@ -0,0 +1,363 @@
+import { z } from 'zod';
+import { envVarName, httpPath, repoBaseDir, repoRelativePath, slug } from './common.js';
+
+/**
+ * `.ninedeploy` manifest schema — project-side declarative config for how
+ * NineDeploy should build, run and route a service. Committed to the repo,
+ * so it must NEVER carry secrets, tokens or connection strings; the loader
+ * enforces that with a regex scan (see apps/server/src/lib/secretScan.ts).
+ *
+ * Merge precedence at apply time: panel/DB > manifest > auto-detect. The
+ * manifest fills empty panel fields; an operator who explicitly set something
+ * in the panel wins.
+ */
+
+// ── Runtime ────────────────────────────────────────────────────────────────
+export const runtimeType = z.enum([
+  'auto',
+  'node',
+  'python',
+  'go',
+  'ruby',
+  'php',
+  'java',
+  'rust',
+  'static',
+]);
+export type RuntimeType = z.infer<typeof runtimeType>;
+
+export const runtime = z
+  .object({
+    type: runtimeType.default('auto'),
+    /**
+     * Pinned language version. Format `<major>` or `<major>.<minor>` or
+     * `<major>.<minor>.<patch>`. For example `20`, `20.18`, `3.12`.
+     */
+    version: z
+      .string()
+      .regex(/^\d+(?:\.\d+){0,2}$/, 'must be a numeric version like 20 or 3.12')
+      .max(20)
+      .optional(),
+  })
+  .strict();
+export type Runtime = z.infer<typeof runtime>;
+
+// ── Build ──────────────────────────────────────────────────────────────────
+export const build = z
+  .object({
+    install: z.string().min(1).max(500).optional(),
+    build: z.string().min(1).max(500).optional(),
+    start: z.string().min(1).max(500).optional(),
+    baseDir: repoBaseDir.optional(),
+    // F928: same "inside the repository" rule as baseDir above and the panel's
+    // service.build.dockerfilePath — a repo-committed `../../x` must not pass.
+    dockerfile: repoRelativePath.min(1).max(200).optional(),
+  })
+  .strict();
+export type Build = z.infer<typeof build>;
+
+// ── Run ────────────────────────────────────────────────────────────────────
+export const restartPolicy = z
+  .union([
+    z.enum(['no', 'always', 'unless-stopped']),
+    z
+      .string()
+      .regex(
+        /^on-failure(?::[1-9]\d{0,2})?$/,
+        'must be on-failure or on-failure:N (1-999, no leading zero)',
+      ),
+  ])
+  .optional();
+/** Inferred type for the `run.restart` field, exported for consumers. */
+export type RestartPolicy = z.infer<typeof restartPolicy>;
+
+export const run = z
+  .object({
+    port: z.number().int().min(1).max(65535).optional(),
+    healthcheck: httpPath.optional(),
+    restart: restartPolicy,
+  })
+  .strict();
+export type Run = z.infer<typeof run>;
+
+// ── Static ─────────────────────────────────────────────────────────────────
+const noTraversalSegments = (value: string): boolean =>
+  !value.split('/').some((segment) => segment === '..' || segment === '.');
+
+const isRelativePath = (value: string): boolean => !value.startsWith('/');
+
+export const staticConfig = z
+  .object({
+    spa: z.boolean().default(false),
+    root: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^[A-Za-z0-9._/-]+$/, 'must be a relative path with allowed characters')
+      .refine(noTraversalSegments, { message: 'path must not contain . or .. segments' })
+      .refine(isRelativePath, { message: 'path must be relative (no leading "/")' })
+      .optional(),
+  })
+  .strict();
+export type StaticConfig = z.infer<typeof staticConfig>;
+
+// ── Env ────────────────────────────────────────────────────────────────────
+export const env = z
+  .object({
+    /** Required env var names. Values stay in the panel's env vault. */
+    required: z.array(envVarName.max(100)).max(100).default([]),
+    /** Managed-DB attach alias: env-key → attachment-env-key. The KEY side is
+     *  validated too: free-form keys (`'MY VAR'`, `''`) could never be
+     *  referenced by an attachment and corrupt the emitted YAML. */
+    aliases: z.record(envVarName, envVarName).optional(),
+  })
+  .strict();
+export type Env = z.infer<typeof env>;
+
+// ── Phases (Nixpacks ince ayar) ────────────────────────────────────────────
+export const phases = z
+  .object({
+    setup: z
+      .object({
+        pkgs: z.array(z.string().min(1).max(100)).max(50).default([]),
+      })
+      .strict()
+      .optional(),
+    build: z
+      .object({
+        cmds: z.array(z.string().min(1).max(500)).max(20).default([]),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type Phases = z.infer<typeof phases>;
+
+// ── Resources ──────────────────────────────────────────────────────────────
+export const resources = z
+  .object({
+    cpuShares: z.number().int().min(0).max(262144).optional(),
+    /** Hard CPU cap in millicores (500 = 0.5 cores); maps to docker --cpus. */
+    cpuLimitMilli: z.number().int().min(0).max(512_000).optional(),
+    memMb: z.number().int().min(0).max(1_048_576).optional(),
+    /** Horizontal replicas for docker services (Traefik load-balances). */
+    replicas: z.number().int().min(1).max(10).optional(),
+  })
+  .strict();
+export type Resources = z.infer<typeof resources>;
+
+// ── Hooks ──────────────────────────────────────────────────────────────────
+export const hooks = z
+  .object({
+    preBuild: z.string().min(1).max(500).optional(),
+    postBuild: z.string().min(1).max(500).optional(),
+    preStop: z.string().min(1).max(500).optional(),
+  })
+  .strict();
+export type Hooks = z.infer<typeof hooks>;
+
+// ── Watch (monorepo) ──────────────────────────────────────────────────────
+export const watch = z
+  .object({
+    paths: z.array(z.string().min(1).max(200)).max(50).default([]),
+  })
+  .strict();
+export type Watch = z.infer<typeof watch>;
+
+// ── Routes ─────────────────────────────────────────────────────────────────
+export const rateLimit = z
+  .object({
+    average: z.number().int().min(0).max(100_000),
+    burst: z.number().int().min(0).max(100_000),
+  })
+  .strict();
+export type RateLimit = z.infer<typeof rateLimit>;
+
+export const route = z
+  .object({
+    host: z
+      .string()
+      .min(3)
+      .max(253)
+      .regex(
+        /^(?=.{1,253}$)(?:[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',
+      ),
+    path: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^\/.*$/, 'must start with "/"')
+      .default('/'),
+    ssl: z.boolean().default(true),
+    redirectWww: z.boolean().optional(),
+    headers: z.record(z.string().min(1).max(200), z.string().min(1).max(2000)).optional(),
+    ipAllowlist: z
+      .array(
+        z
+          .string()
+          .min(1)
+          .max(64)
+          .regex(/^[\d./]+$/, 'must be a CIDR like 1.2.3.4/32'),
+      )
+      .max(50)
+      .optional(),
+    rateLimit: rateLimit.optional(),
+  })
+  .strict();
+export type Route = z.infer<typeof route>;
+
+// ── Previews ──────────────────────────────────────────────────────────────
+export const previews = z
+  .object({
+    enabled: z.boolean().default(false),
+    /**
+     * Hostname template. `{n}` is replaced by the PR number. Example:
+     * `pr-{n}-{{slug}}.{{domain}}` (the panel also requires `{{slug}}` and its own
+     * wildcard zone, r511). Must contain `{n}` when enabled.
+     */
+    pattern: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(
+        /^[A-Za-z0-9._/{}*-]+$/,
+        'must be a hostname template (letters, digits, dot, dash, underscore, slash, brace, asterisk)',
+      )
+      .refine(noTraversalSegments, { message: 'pattern must not contain . or .. segments' })
+      .optional(),
+    maxActive: z.number().int().min(1).max(50).default(5),
+    autoDestroyOnClose: z.boolean().default(true),
+  })
+  .strict()
+  .refine((p) => !p.enabled || (p.pattern != null && p.pattern.includes('{n}')), {
+    message: 'previews.pattern must contain {n} when previews.enabled is true',
+    path: ['pattern'],
+  });
+export type Previews = z.infer<typeof previews>;
+
+// ── Volume ────────────────────────────────────────────────────────────────
+export const volumeBackups = z
+  .object({
+    schedule: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        /^[\d*/,\-A-Za-z\s]+$/,
+        'must look like a cron expression (digits, *, /, comma, dash, letters, space)',
+      ),
+    retention: z.number().int().min(1).max(365).default(7),
+  })
+  .strict();
+export type VolumeBackups = z.infer<typeof volumeBackups>;
+
+export const volume = z
+  .object({
+    mount: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^[A-Za-z0-9._/-]+$/, 'must be a path inside the container')
+      .refine(noTraversalSegments, { message: 'mount must not contain . or .. segments' })
+      .optional(),
+    backups: volumeBackups.optional(),
+  })
+  .strict();
+export type Volume = z.infer<typeof volume>;
+
+// ── Database (managed DB attach hint) ─────────────────────────────────────
+export const database = z
+  .object({
+    ref: slug,
+    env: envVarName,
+  })
+  .strict();
+export type Database = z.infer<typeof database>;
+
+// ── Network ───────────────────────────────────────────────────────────────
+export const network = z
+  .object({
+    publishPort: z.number().int().min(1).max(65535).optional(),
+    aliases: z.array(z.string().min(1).max(100).regex(/^[A-Za-z0-9._-]+$/)).max(20).default([]),
+  })
+  .strict();
+export type Network = z.infer<typeof network>;
+
+// ── Notifications (channel-name references) ──────────────────────────────
+export const notifications = z
+  .object({
+    onDeploy: z.array(z.string().min(1).max(100)).max(20).default([]),
+    onFailure: z.array(z.string().min(1).max(100)).max(20).default([]),
+    onAlert: z.array(z.string().min(1).max(100)).max(20).default([]),
+  })
+  .strict();
+export type Notifications = z.infer<typeof notifications>;
+
+// ── Alerts ────────────────────────────────────────────────────────────────
+export const alertWhen = z.enum([
+  'deployFailed',
+  'restartLoop',
+  'highMemory',
+  'highCpu',
+  'certExpiry',
+]);
+/** Inferred type for the `alerts[].when` field, exported for consumers. */
+export type AlertWhen = z.infer<typeof alertWhen>;
+
+export const alert = z
+  .object({
+    when: alertWhen,
+    channel: z.string().min(1).max(100),
+    thresholdPct: z.number().int().min(1).max(100).optional(),
+  })
+  .strict()
+  .refine(
+    (a) =>
+      a.when !== 'highMemory' && a.when !== 'highCpu' ? true : a.thresholdPct != null,
+    {
+      message: 'thresholdPct is required for highMemory/highCpu alerts',
+      path: ['thresholdPct'],
+    },
+  );
+export type Alert = z.infer<typeof alert>;
+
+// ── Top-level manifest ────────────────────────────────────────────────────
+export const ninedeployManifest = z
+  .object({
+    version: z.literal('1'),
+    runtime: runtime.optional(),
+    build: build.optional(),
+    run: run.optional(),
+    static: staticConfig.optional(),
+    env: env.optional(),
+    phases: phases.optional(),
+    resources: resources.optional(),
+    hooks: hooks.optional(),
+    watch: watch.optional(),
+    routes: z.array(route).max(50).optional(),
+    previews: previews.optional(),
+    volume: volume.optional(),
+    database: database.optional(),
+    network: network.optional(),
+    notifications: notifications.optional(),
+    alerts: z.array(alert).max(20).optional(),
+  })
+  .strict();
+export type NinedeployManifest = z.infer<typeof ninedeployManifest>;
+
+/**
+ * The list of filenames the loader checks, in priority order. The first one
+ * found in the repo root is used.
+ */
+export const NINEDEPLOY_MANIFEST_FILENAMES = [
+  '.ninedeploy',
+  '.ninedeploy.yml',
+  '.ninedeploy.yaml',
+  'ninedeploy.yml',
+  'ninedeploy.yaml',
+] as const;
+export type NinedeployManifestFilename = (typeof NINEDEPLOY_MANIFEST_FILENAMES)[number];
+
+/** Maximum allowed size of a `.ninedeploy` file (bytes). Larger files are refused. */
+export const NINEDEPLOY_MANIFEST_MAX_BYTES = 16 * 1024;

package/src/panelBackup.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+
+// ── Panel self-backup (0.12) ───────────────────────────────────────────────
+/** The recovery passphrase seals every panel backup; it is the ONE secret an
+ *  operator must keep off this server to restore on a new one. */
+export const PANEL_BACKUP_PASSPHRASE_MIN = 12;
+export const PANEL_BACKUP_RETAIN_MIN = 1;
+export const PANEL_BACKUP_RETAIN_MAX = 365;
+export const PANEL_BACKUP_DEFAULT_CRON = '0 3 * * *';
+export const PANEL_BACKUP_DEFAULT_RETAIN = 7;
+
+/**
+ * PUT /v1/system/panel-backup — every field optional; omitted keeps the stored
+ * value. `passphrase` is write-only (omitted = keep the stored one). 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 panelBackupSettingsPatch = z
+  .object({
+    enabled: z.boolean().optional(),
+    cron: z.string().trim().min(1).max(120).optional(),
+    /** A `backup_destinations` id; null clears it (and requires enabled=false). */
+    destinationId: z.number().int().positive().nullable().optional(),
+    retain: z.number().int().min(PANEL_BACKUP_RETAIN_MIN).max(PANEL_BACKUP_RETAIN_MAX).optional(),
+    passphrase: z
+      .string()
+      .min(PANEL_BACKUP_PASSPHRASE_MIN, `The recovery passphrase needs at least ${PANEL_BACKUP_PASSPHRASE_MIN} characters`)
+      .max(1024)
+      .optional(),
+  })
+  .strict();
+export type PanelBackupSettingsPatch = z.infer<typeof panelBackupSettingsPatch>;
+
+/**
+ * POST /v1/system/panel-backup/restore — destructive: replaces this panel's
+ * database, master key, .env and Traefik config. `confirm` must repeat the
+ * object's file name (the part of `key` after the last `/`).
+ */
+export const panelBackupRestore = z
+  .object({
+    /** Destination to read from; omitted = the configured one. On a fresh
+     *  install, add the old bucket as a destination and name it here. */
+    destinationId: z.number().int().positive().optional(),
+    key: z.string().min(1).max(1024),
+    passphrase: z.string().min(1).max(1024),
+    confirm: z.string().max(1024),
+  })
+  .strict();
+export type PanelBackupRestore = z.infer<typeof panelBackupRestore>;
+
+/** Outcome of the latest run, as `GET /v1/system/panel-backup` reports it. */
+export interface PanelBackupRunState {
+  status: 'running' | 'completed' | 'failed';
+  trigger: 'schedule' | 'manual';
+  startedAt: string;
+  finishedAt: string | null;
+  key: string | null;
+  sizeBytes: number | null;
+  error: string | null;
+  /** Retention problems that did not fail the run (the new backup is safe). */
+  warning: string | null;
+}
+
+/** `GET /v1/system/panel-backup`. */
+export interface PanelBackupStatus {
+  settings: {
+    enabled: boolean;
+    cron: string;
+    destinationId: number | null;
+    retain: number;
+    hasPassphrase: boolean;
+  };
+  /** True while a run (or a restore) is executing in this process. */
+  running: boolean;
+  lastRun: PanelBackupRunState | null;
+  lastSuccessAt: string | null;
+  /** Next scheduled run (ISO) when enabled and the cron is valid. */
+  nextRunAt: string | null;
+  /** The master key comes from NINEDEPLOY_MASTER_KEY(S), not the master.key
+   *  file — backups then do NOT contain it and it must be kept separately. */
+  masterKeyFromEnv: boolean;
+}
+
+/** One panel backup object in the destination bucket. */
+export interface PanelBackupObject {
+  key: string;
+  name: string;
+  sizeBytes: number;
+  lastModified: string;
+}

package/src/project.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { slug } from './common.js';
+
+/**
+ * Project contracts — the single-level grouping layer over services and
+ * databases (Easypanel-style). Projects own nothing directly; deleting one
+ * detaches its resources (projectId → null), it never cascades.
+ */
+
+export const createProject = z.object({
+  name: z.string().trim().min(2).max(63),
+  slug: slug.optional(),
+  description: z.string().trim().max(500).nullable().optional(),
+  workspaceId: z.number().int().positive().nullable().optional(),
+});
+export type CreateProject = z.infer<typeof createProject>;
+export type CreateProjectInput = CreateProject;
+
+export const projectPatch = z
+  .object({
+    name: z.string().trim().min(2).max(63).optional(),
+    description: z.string().trim().max(500).nullable().optional(),
+    workspaceId: z.number().int().positive().nullable().optional(),
+  })
+  .refine((v) => Object.keys(v).length > 0, { message: 'nothing to update' });
+export type ProjectPatch = z.infer<typeof projectPatch>;
+export type ProjectPatchInput = ProjectPatch;
+
+/** Serialized project as returned by /v1/projects. */
+export interface ProjectEntry {
+  id: number;
+  workspaceId?: number | null;
+  /** Display name of the owning workspace. Resolved server-side. */
+  workspaceName?: string | null;
+  name: string;
+  slug: string;
+  description: string | null;
+  serviceCount: number;
+  databaseCount: number;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/proxyConfig.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+
+// ── Proxy management (0.14) ────────────────────────────────────────────────
+// Request and response shapes for `/v1/traefik/custom-config` and
+// `/v1/traefik/certificates/custom`. Operator only. These are SHAPE checks:
+// the YAML rules (allowed sections, `custom-` names, entry points, refused
+// keys) and the certificate proof (key matches leaf, key type, expiry) run on
+// the server. No response shape carries a private key. Design: DESIGN.md §2.
+
+/** 256 KiB. Measured in UTF-8 bytes on the server; this caps the string. */
+export const TRAEFIK_CUSTOM_CONFIG_MAX_BYTES = 256 * 1024;
+export const CUSTOM_CERTIFICATE_CHAIN_MAX_BYTES = 64 * 1024;
+export const CUSTOM_CERTIFICATE_KEY_MAX_BYTES = 16 * 1024;
+export const CUSTOM_CERTIFICATES_MAX = 100;
+
+// ── Custom dynamic config ──────────────────────────────────────────────────
+
+/** PUT /v1/traefik/custom-config and POST …/validate. */
+export const traefikCustomConfigInput = z.object({
+  content: z.string().min(1).max(TRAEFIK_CUSTOM_CONFIG_MAX_BYTES),
+});
+export type TraefikCustomConfigInput = z.infer<typeof traefikCustomConfigInput>;
+
+/** One validation finding; `path` is a dotted YAML path (`http.routers.custom-a.rule`). */
+export const traefikCustomConfigIssue = z.object({
+  path: z.string(),
+  message: z.string(),
+});
+export type TraefikCustomConfigIssue = z.infer<typeof traefikCustomConfigIssue>;
+
+/** POST /v1/traefik/custom-config/validate. No state change. */
+export const traefikCustomConfigValidation = z.object({
+  ok: z.boolean(),
+  errors: z.array(traefikCustomConfigIssue),
+  warnings: z.array(traefikCustomConfigIssue),
+});
+export type TraefikCustomConfigValidation = z.infer<typeof traefikCustomConfigValidation>;
+
+export const traefikCustomConfigState = z.enum(['none', 'applied', 'rejected']);
+export type TraefikCustomConfigState = z.infer<typeof traefikCustomConfigState>;
+
+/** GET /v1/traefik/custom-config. `content: null` = none saved. */
+export const traefikCustomConfig = z.object({
+  content: z.string().nullable(),
+  sha256: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  /** User id of the last saver. */
+  updatedBy: z.number().int().nullable(),
+  status: traefikCustomConfigState,
+  lastError: z.string().nullable(),
+});
+export type TraefikCustomConfig = z.infer<typeof traefikCustomConfig>;
+
+// ── Custom certificates ────────────────────────────────────────────────────
+
+const certificatePem = z
+  .string()
+  .trim()
+  .min(1)
+  .max(CUSTOM_CERTIFICATE_CHAIN_MAX_BYTES)
+  .regex(/-----BEGIN CERTIFICATE-----[\s\S]+-----END CERTIFICATE-----/, 'certPem must be a PEM certificate chain');
+
+/** Unencrypted PKCS#8, PKCS#1 or SEC1 key. Passphrase-protected keys are refused. */
+const privateKeyPem = z
+  .string()
+  .trim()
+  .min(1)
+  .max(CUSTOM_CERTIFICATE_KEY_MAX_BYTES)
+  .regex(
+    /^-----BEGIN (RSA |EC )?PRIVATE KEY-----\r?\n[\s\S]+\r?\n-----END \1PRIVATE KEY-----$/,
+    'keyPem must be an unencrypted PEM private key',
+  );
+
+const certificateName = z.string().trim().min(1).max(100);
+
+/** POST /v1/traefik/certificates/custom → 201. */
+export const customCertificateUpload = z.object({
+  name: certificateName,
+  certPem: certificatePem,
+  keyPem: privateKeyPem,
+});
+export type CustomCertificateUpload = z.infer<typeof customCertificateUpload>;
+
+/** PUT /v1/traefik/certificates/custom/:certId. An omitted name keeps the stored one. */
+export const customCertificateReplace = z.object({
+  name: certificateName.optional(),
+  certPem: certificatePem,
+  keyPem: privateKeyPem,
+});
+export type CustomCertificateReplace = z.infer<typeof customCertificateReplace>;
+
+/** One element of GET /v1/traefik/certificates/custom. */
+export const customCertificate = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  hostnames: z.array(z.string()),
+  subject: z.string().nullable(),
+  issuer: z.string().nullable(),
+  notBefore: z.string(),
+  notAfter: z.string(),
+  fingerprint: z.string(),
+  expired: z.boolean(),
+  coveredDomains: z.array(
+    z.object({
+      id: z.number().int(),
+      hostname: z.string(),
+      serviceId: z.number().int(),
+    }),
+  ),
+});
+export type CustomCertificate = z.infer<typeof customCertificate>;
+
+// ── Write results (0.14 T2, additive) ──────────────────────────────────────
+
+/** PUT /v1/traefik/custom-config → 200. Router-level findings come back as warnings. */
+export const traefikCustomConfigApplied = z.object({
+  ok: z.literal(true),
+  status: z.literal('applied'),
+  sha256: z.string(),
+  warnings: z.array(traefikCustomConfigIssue),
+});
+export type TraefikCustomConfigApplied = z.infer<typeof traefikCustomConfigApplied>;
+
+/**
+ * The 400 / 422 body of PUT /v1/traefik/custom-config: the error envelope
+ * plus the findings (`errors` empty only on a 503).
+ */
+export const traefikCustomConfigRefusal = z.object({
+  error: z.object({ code: z.string(), message: z.string() }),
+  errors: z.array(traefikCustomConfigIssue).default([]),
+  warnings: z.array(traefikCustomConfigIssue).default([]),
+});
+export type TraefikCustomConfigRefusal = z.infer<typeof traefikCustomConfigRefusal>;
+
+/** POST (201) and PUT of /v1/traefik/certificates/custom: the listing entry plus size warnings. */
+export const customCertificateSaved = customCertificate.extend({
+  warnings: z.array(z.string()),
+});
+export type CustomCertificateSaved = z.infer<typeof customCertificateSaved>;