@ninedeploy/schemas 0.10.5 → 0.16.0

package/src/accessGrants.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { id } from './common.js';
+
+// ── Project and environment access grants (0.15) ────────────────────────────
+// Request and response shapes for `/v1/workspaces/:wid/access-grants`,
+// `/v1/projects/:id/access` and `/v1/access/me`. Grants are raise-only (owner
+// decision O5): a user's effective role on a resource is the higher of their
+// seat role and any matching, non-suspended grant; `owner` is never grantable.
+// The role cap (no higher than the granter's own role) and the workspace
+// consistency checks are enforced by the server. Design: DESIGN.md §4.
+
+/** Mirrors `accessGrantRole` in `@ninedeploy/db`. */
+export const accessGrantRole = z.enum(['viewer', 'member', 'admin']);
+export type AccessGrantRole = z.infer<typeof accessGrantRole>;
+
+/**
+ * The uniqueness key stored in `access_grants.target_key`: `p:<project>`,
+ * `e:<environment>` or `pe:<project>:<environment>`. SQLite unique indexes
+ * treat NULLs as distinct, so the pair alone could not be unique.
+ */
+export function accessGrantTargetKey(target: { projectId?: number | null; environmentId?: number | null }): string {
+  const p = target.projectId ?? null;
+  const e = target.environmentId ?? null;
+  if (p !== null && e !== null) return `pe:${p}:${e}`;
+  if (p !== null) return `p:${p}`;
+  if (e !== null) return `e:${e}`;
+  throw new Error('an access grant needs a project or an environment');
+}
+
+const hasTarget = (v: { projectId?: number | null; environmentId?: number | null }) =>
+  v.projectId != null || v.environmentId != null;
+const hasSubject = (v: { email?: string; userId?: number }) => (v.email === undefined) !== (v.userId === undefined);
+
+/**
+ * POST /v1/workspaces/:wid/access-grants (workspace admin). Name the user by
+ * exactly one of `email` or `userId`, and target a project, an environment, or
+ * both (services linked to the project AND in the environment).
+ */
+export const accessGrantCreate = z
+  .object({
+    email: z.string().trim().toLowerCase().email().max(254).optional(),
+    userId: id.optional(),
+    projectId: id.optional(),
+    environmentId: id.optional(),
+    role: accessGrantRole,
+  })
+  .strict()
+  .refine(hasSubject, { message: 'name the user by exactly one of email or userId', path: ['email'] })
+  .refine(hasTarget, { message: 'a grant needs a projectId, an environmentId, or both', path: ['projectId'] });
+export type AccessGrantCreate = z.infer<typeof accessGrantCreate>;
+
+/**
+ * PATCH /v1/workspaces/:wid/access-grants/:grantId: change the role, suspend
+ * or reinstate the grant, or both. `{role}` alone is the 0.15.0 contract and
+ * still means exactly that. `suspended: true` stops the grant counting (it
+ * stays listed, like a SCIM suspension); `false` makes it count again. The
+ * target and the user never change: revoke and grant again instead.
+ */
+export const accessGrantUpdate = z
+  .object({ role: accessGrantRole.optional(), suspended: z.boolean().optional() })
+  .strict()
+  .refine((v) => v.role !== undefined || v.suspended !== undefined, {
+    message: 'change the role, suspended, or both',
+    path: ['role'],
+  });
+export type AccessGrantUpdate = z.infer<typeof accessGrantUpdate>;
+
+/** GET /v1/workspaces/:wid/access-grants query. Query strings arrive as text. */
+export const accessGrantListQuery = z
+  .object({
+    userId: z.coerce.number().int().positive().optional(),
+    projectId: z.coerce.number().int().positive().optional(),
+    environmentId: z.coerce.number().int().positive().optional(),
+  })
+  .strict();
+export type AccessGrantListQuery = z.infer<typeof accessGrantListQuery>;
+
+const namedRef = z.object({ id, name: z.string() });
+/** `users.name` is optional; the API sends `null` when it is unset. */
+const userRef = z.object({ id, email: z.string(), name: z.string().nullable() });
+
+/** One grant as the workspace admin sees it. */
+export const accessGrant = z.object({
+  id,
+  workspaceId: id,
+  user: userRef,
+  project: namedRef.nullable(),
+  environment: namedRef.nullable(),
+  role: accessGrantRole,
+  suspended: z.boolean(),
+  createdAt: z.string(),
+  createdBy: z.object({ id, email: z.string() }).nullable(),
+  /** The user has no seat in the grant's workspace: they see only what grants cover. */
+  isGuest: z.boolean(),
+});
+export type AccessGrant = z.infer<typeof accessGrant>;
+
+/** How a user reaches a project, as GET /v1/projects/:id/access explains it. */
+export const projectAccessVia = z.enum(['operator', 'seat', 'grant', 'creator']);
+export type ProjectAccessVia = z.infer<typeof projectAccessVia>;
+
+/** GET /v1/projects/:id/access (project admin). */
+export const projectAccessEntry = z.object({
+  user: userRef,
+  /** Effective role on the project (operators are `owner`). */
+  role: z.enum(['owner', 'admin', 'member', 'viewer']),
+  via: z.array(projectAccessVia).min(1),
+});
+export type ProjectAccessEntry = z.infer<typeof projectAccessEntry>;
+
+/** GET /v1/access/me (self): the caller's own grants and guest workspaces. */
+export const accessMe = z.object({
+  grants: z.array(accessGrant),
+  /** Workspaces the caller reaches only through grants (no seat). */
+  guestWorkspaces: z.array(z.object({ id, name: z.string(), slug: z.string() })),
+});
+export type AccessMe = z.infer<typeof accessMe>;

package/src/agentCommand.ts

@@ -0,0 +1,67 @@
+/**
+ * The one `docker run` line that starts a NineDeploy node agent (r175).
+ *
+ * It used to be written out three times — SSH bootstrap, the register API
+ * and the Servers page — and all three were wrong in different ways: the
+ * API/web copies named an image that does not exist
+ * (`ghcr.io/ninedeploy/server`), none of them told the image to run the
+ * agent instead of the panel, the auto-join copy had no enrolment token
+ * (so `/announce` always refused it), and the in-container agent could
+ * neither reach the docker socket (non-root image user) nor hand Traefik
+ * bind mounts that exist on the host.
+ *
+ * The agent keeps all state relative to its working directory, so it runs
+ * in AGENT_HOME, bind-mounted at the SAME path on the host: every `-v`
+ * the agent passes to the host daemon (Traefik config, acme.json, env files)
+ * then names a real host path, and a generated auto-join token survives a
+ * container re-create. It runs as root because docker-socket access is
+ * root-equivalent anyway and the socket is `root:docker 0660`.
+ */
+export const AGENT_HOME = '/var/lib/ninedeploy-agent';
+export const AGENT_CONTAINER_PORT = 4600;
+export const AGENT_IMAGE_REPO = 'ghcr.io/ninedeploy/ninedeploy';
+
+export interface AgentCommandOptions {
+  /** Host port the agent is published on. */
+  hostPort: number;
+  /** Image tag, e.g. `v0.10.0`; `latest` when the caller cannot pin it. */
+  imageTag: string;
+  /** Manual registration: sha256 of the shared token the core holds. */
+  tokenSha256?: string;
+  /** Auto-join: the core's public URL to announce to. */
+  masterUrl?: string;
+  /** Auto-join: the admin-issued enrolment secret (or a placeholder to fill in). */
+  enrolmentToken?: string;
+}
+
+/** Render a value for the copy-paste shell line (r473): bare when it is
+ *  provably shell-safe (the common case — numbers, hex tokens, plain URLs),
+ *  double-quoted otherwise. Unquoted, a panel URL carrying `&` would
+ *  background the pasted command and mangle the rest of the line. */
+function shellValue(value: string): string {
+  return /^[\w.:/=-]+$/.test(value) ? value : `"${value.replace(/(["$`\\])/g, '\\$1')}"`;
+}
+
+export function agentDockerRunCommand(opts: AgentCommandOptions): string {
+  const env: string[] = [
+    'NINEDEPLOY_AGENT=1',
+    `NINEDEPLOY_AGENT_PORT=${AGENT_CONTAINER_PORT}`,
+  ];
+  if (opts.tokenSha256) env.push(`NINEDEPLOY_AGENT_TOKEN=${opts.tokenSha256}`);
+  if (opts.masterUrl) env.push(`NINEDEPLOY_MASTER_URL=${opts.masterUrl}`);
+  if (opts.enrolmentToken) env.push(`NINEDEPLOY_ENROLMENT_TOKEN=${opts.enrolmentToken}`);
+  return [
+    'docker run -d --name ninedeploy-agent --restart unless-stopped',
+    '--user 0:0',
+    `-p ${opts.hostPort}:${AGENT_CONTAINER_PORT}`,
+    '-v /var/run/docker.sock:/var/run/docker.sock',
+    `-v ${AGENT_HOME}:${AGENT_HOME}`,
+    `-w ${AGENT_HOME}`,
+    ...env.map((e) => {
+      const eq = e.indexOf('=');
+      return `-e ${e.slice(0, eq)}=${shellValue(e.slice(eq + 1))}`;
+    }),
+    `${AGENT_IMAGE_REPO}:${opts.imageTag}`,
+    'node /app/apps/server/dist/agent.js',
+  ].join(' ');
+}

package/src/ai.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * AI failure diagnosis (BYO-key) configuration. The API key never lives
+ * here — it is stored separately, encrypted at rest — and this shape only
+ * carries the OpenAI-compatible endpoint and model to call.
+ */
+export const aiConfig = z.object({
+  /** OpenAI-compatible chat-completions base URL (e.g. https://api.openai.com/v1). */
+  baseUrl: z.string().trim().url().max(300),
+  /** Model name as the upstream expects it (e.g. gpt-4o-mini, llama3.1). */
+  model: z.string().trim().min(1).max(120),
+});
+
+export type AiConfig = z.infer<typeof aiConfig>;
+
+/** PUT /v1/ai/config body — the key is optional so base URL/model can change without re-entering it. */
+export const aiConfigUpdate = aiConfig.extend({
+  apiKey: z.string().trim().min(8).max(400).optional(),
+});
+
+export type AiConfigUpdate = z.infer<typeof aiConfigUpdate>;
+
+/** GET /v1/ai/config response — never carries key material. */
+export const aiConfigStatus = z.object({
+  configured: z.boolean(),
+  baseUrl: z.string().nullable(),
+  model: z.string().nullable(),
+  hasApiKey: z.boolean(),
+});
+
+export type AiConfigStatus = z.infer<typeof aiConfigStatus>;

package/src/auth.ts

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+
+export const register = z.object({
+  email: z.email().max(255),
+  password: z.string().min(8).max(128),
+  name: z.string().min(1).max(100).optional(),
+  /** First-run setup token (0.16): required by the bootstrap of an empty production instance. */
+  setupToken: z.string().max(200).optional(),
+});
+export type Register = z.infer<typeof register>;
+
+/** Initial bootstrap — same shape as register, only works when no users exist. */
+export const setup = register;
+export type Setup = Register;
+
+export const login = z.object({
+  email: z.email(),
+  password: z.string().min(1),
+  /** Required when the account has 2FA enabled. */
+  totpCode: z.string().regex(/^\d{6}$/).optional(),
+});
+export type Login = z.infer<typeof login>;
+
+/** Verifying a two-factor action (enable / disable companion). */
+export const twoFactorCode = z.object({ code: z.string().regex(/^\d{6}$/) });
+export type TwoFactorCode = z.infer<typeof twoFactorCode>;
+
+/** Regenerating the 2FA secret: password required when 2FA is already enabled. */
+export const twoFactorSetup = z.object({ password: z.string().min(1) });
+export type TwoFactorSetup = z.infer<typeof twoFactorSetup>;
+
+/**
+ * Step-up proof for credential-planting actions (r502): the current password.
+ * Optional on the wire — an account without a usable password (SSO-only) may
+ * instead prove a FRESH sign-in (session younger than 10 minutes); the server
+ * decides which applies.
+ */
+export const stepUp = z.object({ password: z.string().min(1).max(1024).optional() });
+export type StepUp = z.infer<typeof stepUp>;
+
+/** Turning 2FA on: the code from the authenticator + the step-up proof (r502). */
+export const twoFactorEnable = twoFactorCode.extend({ password: z.string().min(1).max(1024).optional() });
+export type TwoFactorEnable = z.infer<typeof twoFactorEnable>;
+
+export const twoFactorDisable = z.object({
+  password: z.string().min(1),
+  code: z.string().regex(/^\d{6}$/),
+});
+export type TwoFactorDisable = z.infer<typeof twoFactorDisable>;
+
+/** Self-service password change: requires the current password. */
+export const passwordChange = z.object({
+  currentPassword: z.string().min(1),
+  newPassword: z.string().min(8).max(128),
+});
+export type PasswordChange = z.infer<typeof passwordChange>;
+
+/** Admin-initiated password reset for another user. */
+/**
+ * Admin-created user — same shape as register, no global role.
+ * A new user has no workspace memberships until an existing owner/admin
+ * invites them; the first user on a fresh install is auto-promoted to owner
+ * of a personal workspace by the auth module.
+ */
+export const userCreate = z.object({
+  email: z.email().max(255),
+  password: z.string().min(8).max(128),
+  name: z.string().min(1).max(100).optional(),
+});
+export type UserCreate = z.infer<typeof userCreate>;
+
+export const passwordReset = z.object({
+  newPassword: z.string().min(8).max(128),
+});
+export type PasswordReset = z.infer<typeof passwordReset>;
+
+/**
+ * API-token scopes.
+ *
+ * Until 0.3.5 the `api_tokens.scopes` column existed but was never written
+ * (always `[]`) and never read, so every token carried its owner's FULL
+ * authority — including the instance-operator flag, which gates host-privileged
+ * deploys. A CI or MCP token was therefore an instance-root credential.
+ *
+ * The vocabulary is deliberately tiny and method-based, so it can be enforced
+ * in one place (`plugins/auth.ts`) instead of being annotated onto 51 route
+ * modules:
+ *
+ *   read      → safe methods only (GET / HEAD / OPTIONS)
+ *   write     → every method, but the request runs as a NON-operator even if
+ *               the owner is one
+ *   operator  → no restriction beyond the owner's own authority
+ *
+ * An EMPTY scope list means "unrestricted" and is what every pre-0.3.5 token
+ * has. That is deliberate back-compat: silently downgrading tokens already
+ * deployed in someone's CI would break their pipeline on upgrade. New tokens
+ * should always be created with an explicit scope.
+ */
+// ── API-token scopes (G-08 fine-grained) ──────────────────────────────────
+// The pre-0.3.5 enum (`read` | `write` | `operator`) was a coarse
+// binary/ternary. G-08 adds per-resource URI scopes
+// (`nd://scope/{read,write,admin}/<resource>`) so an MCP / CI token
+// can be limited to, say, `nd://scope/read/services +
+// nd://scope/read/databases` and nothing else.
+//
+// The two forms are accepted in the same array; the old enum
+// continues to be a valid shorthand (a `write` token expands to
+// "any write" at the auth plugin, which is the pre-0.3.5
+// behaviour for backwards compat).
+const LEGACY_SCOPE = z.enum(['read', 'write', 'operator']);
+const RESOURCE_SCOPE = z.string().regex(
+  /^nd:\/\/scope\/(read|write|admin)\/[a-z][a-z0-9_]{0,63}$/,
+  'expected nd://scope/{read,write,admin}/<resource>',
+);
+export const apiTokenScope = z.union([LEGACY_SCOPE, RESOURCE_SCOPE]);
+export type ApiTokenScope = z.infer<typeof apiTokenScope>;
+
+/** All known resource names. The auth plugin checks these
+ *  literally — adding a new resource is a one-line change
+ *  in the auth plugin's resource map. Listed here so the
+ *  CLI can suggest completions and the Zod regex can
+ *  cross-check. */
+export const KNOWN_SCOPE_RESOURCES = [
+  'services',
+  'databases',
+  'domains',
+  'deploys',
+  'alerts',
+  'webhooks',
+  'env',
+  'backups',
+  'volumes',
+  'projects',
+  'users',
+  'tokens',
+  'notifications',
+  'config',
+  'topology',
+  'health',
+  'settings',
+  'manifests',
+  'domains_transfer',
+  'backup_drill',
+  'images',
+  'audit',
+  'firewall',
+  'sso',
+  'egress',
+  'orchestrators',
+  'housekeeping',
+] as const;
+export type ScopeResource = (typeof KNOWN_SCOPE_RESOURCES)[number];
+
+/**
+ * Grant or revoke the INSTANCE-operator flag (`PATCH /v1/users/:id/operator`).
+ *
+ * This is not a workspace role. It gates the operator-only routes and the
+ * host-privilege boundary (PM2/compose deploys, lifecycle hooks, docker-socket
+ * templates), so it can only be changed by an existing operator, and the last
+ * one cannot revoke itself.
+ */
+export const operatorGrant = z.object({
+  isOperator: z.boolean(),
+});
+export type OperatorGrant = z.infer<typeof operatorGrant>;
+
+/** Forgot-password request. Always answers 200 (no user enumeration). */
+export const forgotPassword = z.object({
+  email: z.email(),
+});
+export type ForgotPassword = z.infer<typeof forgotPassword>;
+
+/** Complete a reset with the token from the email / admin-issued link. */
+export const passwordResetWithToken = z.object({
+  token: z.string().min(20).max(128),
+  newPassword: z.string().min(8).max(128),
+});
+export type PasswordResetWithToken = z.infer<typeof passwordResetWithToken>;
+
+/** Tokens issued after a successful login/refresh. */
+export const tokenPair = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresIn: z.number().int().positive(),
+});
+export type TokenPair = z.infer<typeof tokenPair>;
+
+export const refresh = z.object({
+  refreshToken: z.string().min(1),
+});
+export type Refresh = z.infer<typeof refresh>;
+
+/**
+ * Public user representation (never includes passwordHash).
+ * The legacy global `role` field was removed; authorization is per-workspace
+ * now. The effective "is operator" check is computed by joining
+ * `workspace_members` and asking whether the user holds owner/admin in any
+ * workspace.
+ */
+export const publicUser = z.object({
+  id: z.number().int(),
+  email: z.email(),
+  name: z.string().nullable(),
+  /** True iff the user holds owner/admin in at least one workspace. */
+  isOperator: z.boolean(),
+  /** Number of workspaces the user belongs to. Computed by the server. */
+  workspaceCount: z.number().int().nonnegative(),
+  /**
+   * r540: workspaces this user owns — the ones deleting the account hands to
+   * the operator (or `transferTo`). Only `GET /v1/users` fills it.
+   */
+  ownedWorkspaces: z.array(z.object({ id: z.number().int(), name: z.string() })).optional(),
+  createdAt: z.string().datetime(),
+});
+export type PublicUser = z.infer<typeof publicUser>;
+
+export const session = z.object({
+  user: publicUser,
+  tokens: tokenPair,
+});
+export type Session = z.infer<typeof session>;
+
+/**
+ * r603: `POST /auth/password` — a session plus how many passkeys still sign in
+ * to the account (a change keeps them; a reset deletes them). Optional so a
+ * client talking to an older server keeps working.
+ */
+export const passwordChangeResult = session.extend({
+  passkeysRemaining: z.number().int().nonnegative().optional(),
+});
+export type PasswordChangeResult = z.infer<typeof passwordChangeResult>;
+
+// ── API tokens (for the CLI / CI) ─────────────────────────────────────────
+export const createApiToken = z.object({
+  // Lenient on purpose: this endpoint historically accepted any string, sliced
+  // it to 100 chars and fell back to "cli" when empty. Rejecting outright would
+  // break CLI/CI callers on upgrade.
+  name: z
+    .string()
+    .optional()
+    .transform((v) => (v ?? '').slice(0, 100) || 'cli'),
+  /**
+   * Defaults to `['read']` — a NEW token without explicit scopes is a
+   * read-only token, not an unrestricted one. The unrestricted meaning of an
+   * EMPTY list survives only for legacy rows created before 0.3.5 (the
+   * resolver still maps `[]` → unrestricted); new tokens are never handed
+   * their owner's full authority by default — and an explicit `[]` is
+   * refused, since it would be stored as exactly that legacy unrestricted row.
+   */
+  scopes: z.array(apiTokenScope).min(1).max(3).default(['read']),
+  /**
+   * Defaults to a one-year lifetime. A standing credential that never expires
+   * was the pre-0.3.5 behaviour and is what made a leaked CI token
+   * effectively permanent; an operator who wants that must now say so
+   * explicitly (3650).
+   */
+  expiresInDays: z.number().int().min(1).max(3650).default(365),
+});
+/** Parsed shape (post-defaults) — what the route handler works with. */
+export type CreateApiToken = z.infer<typeof createApiToken>;
+/**
+ * Caller-facing shape: `name` and `scopes` are optional on the wire and filled
+ * in by the schema's defaults. The SDK takes this so `tokens.create()` and
+ * `tokens.create({ name: 'ci' })` both stay valid.
+ */
+export type CreateApiTokenInput = z.input<typeof createApiToken>;
+
+export const apiToken = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  /** Empty array = a legacy, unrestricted token. The UI should flag those. */
+  scopes: z.array(z.string()),
+  lastUsedAt: z.string().datetime().nullable(),
+  expiresAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+});
+export type ApiToken = z.infer<typeof apiToken>;
+
+/** Returned once at creation time — the raw token is never retrievable again. */
+export const createdApiToken = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  token: z.string(),
+  scopes: z.array(z.string()),
+  expiresAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+});
+export type CreatedApiToken = z.infer<typeof createdApiToken>;
+
+// ── passkeys (WebAuthn) ────────────────────────────────────────────────────
+/** Registration verification: label for the new credential + the browser's response payload. */
+export const passkeyRegisterVerify = z.object({
+  name: z.string().min(1).max(100),
+  response: z.record(z.string(), z.unknown()),
+  /** r502: step-up proof — see `stepUp`. */
+  password: z.string().min(1).max(1024).optional(),
+});
+export type PasskeyRegisterVerify = z.infer<typeof passkeyRegisterVerify>;
+
+/** Login verification: just the browser's authentication response (discoverable credentials). */
+export const passkeyLoginVerify = z.object({
+  response: z.record(z.string(), z.unknown()),
+});
+export type PasskeyLoginVerify = z.infer<typeof passkeyLoginVerify>;
+
+export const passkeyCredential = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+});
+export type PasskeyCredential = z.infer<typeof passkeyCredential>;
+
+// ── sessions (refresh-token backing store) ─────────────────────────────────
+export const activeSession = z.object({
+  id: z.number().int(),
+  ip: z.string().nullable(),
+  userAgent: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  lastUsedAt: z.string().datetime().nullable(),
+  current: z.boolean(),
+});
+export type ActiveSession = z.infer<typeof activeSession>;
+

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>;