@ninedeploy/schemas 0.10.5 → 0.16.0

package/src/terminals.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { id } from './common.js';
+
+// ── Terminals (0.15) ────────────────────────────────────────────────────────
+// Request and response shapes for `/v1/terminals`: interactive shells into a
+// service replica, a managed database, any managed container, or (off by
+// default, owner decision O1) the host of a server. A session is created over
+// HTTP and attached over a WebSocket with a single-use ticket. Metadata only:
+// no transcript is ever recorded (O2). These are SHAPE checks; the server
+// resolves and authorises every target. Design: DESIGN.md §1.
+
+export const TERMINAL_COLS_MIN = 10;
+export const TERMINAL_COLS_MAX = 500;
+export const TERMINAL_ROWS_MIN = 5;
+export const TERMINAL_ROWS_MAX = 200;
+/** Per-frame cap of the attach socket (protocol v1); a larger frame closes 1009. */
+export const TERMINAL_FRAME_MAX_BYTES = 64 * 1024;
+export const TERMINAL_HISTORY_LIMIT_MAX = 200;
+
+/** Mirrors `terminalTargetKind` in `@ninedeploy/db`. */
+export const terminalTargetKind = z.enum(['service', 'database', 'container', 'host']);
+export type TerminalTargetKind = z.infer<typeof terminalTargetKind>;
+
+/** Mirrors `terminalSessionStatus` in `@ninedeploy/db`. */
+export const terminalSessionStatus = z.enum(['pending', 'active', 'ended', 'failed', 'expired']);
+export type TerminalSessionStatus = z.infer<typeof terminalSessionStatus>;
+
+/** A managed container name (`isManagedContainer` is checked server side). */
+export const terminalContainerName = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]{1,127}$/, 'must be a container name');
+
+export const terminalTarget = z.discriminatedUnion('kind', [
+  z
+    .object({
+      kind: z.literal('service'),
+      serviceId: id,
+      /** 1-based replica index; omitted = the primary container. */
+      replica: z.number().int().min(1).max(50).optional(),
+      /** A node the service runs on (primary or fan-out target); omitted = its primary. */
+      serverId: id.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('database'),
+      databaseId: id,
+      /** `client` runs the engine CLI with the stored credentials. */
+      mode: z.enum(['shell', 'client']).default('shell'),
+    })
+    .strict(),
+  z.object({ kind: z.literal('container'), name: terminalContainerName }).strict(),
+  z
+    .object({
+      kind: z.literal('host'),
+      /** null = the panel host. */
+      serverId: id.nullable(),
+    })
+    .strict(),
+]);
+export type TerminalTarget = z.infer<typeof terminalTarget>;
+export type TerminalTargetInput = z.input<typeof terminalTarget>;
+
+export const terminalCols = z.number().int().min(TERMINAL_COLS_MIN).max(TERMINAL_COLS_MAX);
+export const terminalRows = z.number().int().min(TERMINAL_ROWS_MIN).max(TERMINAL_ROWS_MAX);
+
+/** POST /v1/terminals (operator). `password` is the step-up for host shells. */
+export const createTerminalSession = z
+  .object({
+    target: terminalTarget,
+    cols: terminalCols.default(120),
+    rows: terminalRows.default(32),
+    password: z.string().min(1).max(1024).optional(),
+  })
+  .strict();
+export type CreateTerminalSession = z.infer<typeof createTerminalSession>;
+export type CreateTerminalSessionInput = z.input<typeof createTerminalSession>;
+
+/** One session row as the API returns it (history, detail, create). */
+export const terminalSession = z.object({
+  id,
+  status: terminalSessionStatus,
+  targetKind: terminalTargetKind,
+  targetLabel: z.string(),
+  /** null = the panel host. */
+  serverId: id.nullable(),
+  userId: id.nullable(),
+  userEmail: z.string().nullable(),
+  createdAt: z.string(),
+  startedAt: z.string().nullable(),
+  endedAt: z.string().nullable(),
+  durationMs: z.number().int().nonnegative().nullable(),
+  bytesIn: z.number().int().nonnegative(),
+  bytesOut: z.number().int().nonnegative(),
+  endReason: z.string().nullable(),
+  exitCode: z.number().int().nullable(),
+  clientIp: z.string().nullable(),
+});
+export type TerminalSession = z.infer<typeof terminalSession>;
+
+/** 201 answer of POST /v1/terminals. The ticket is single use and valid for 30s. */
+export const terminalSessionCreated = z.object({
+  session: terminalSession,
+  ticket: z.string().min(1),
+  ticketExpiresAt: z.string(),
+  /** `/v1/terminals/:id/attach`. */
+  attachPath: z.string().regex(/^\/v1\/terminals\/\d+\/attach$/),
+});
+export type TerminalSessionCreated = z.infer<typeof terminalSessionCreated>;
+
+/** GET /v1/terminals answer: newest first; `nextBefore` pages further back (null = no more). */
+export const terminalSessionList = z.object({
+  items: z.array(terminalSession),
+  nextBefore: id.nullable(),
+});
+export type TerminalSessionList = z.infer<typeof terminalSessionList>;
+
+/** DELETE /v1/terminals/:id answer. `wasLive`: a running shell was closed (otherwise a pending ticket was revoked). */
+export const terminalTerminateResult = z.object({
+  ok: z.literal(true),
+  wasLive: z.boolean(),
+});
+export type TerminalTerminateResult = z.infer<typeof terminalTerminateResult>;
+
+/** GET /v1/terminals query (history). Query strings arrive as text. */
+export const terminalSessionListQuery = z
+  .object({
+    status: terminalSessionStatus.optional(),
+    userId: z.coerce.number().int().positive().optional(),
+    targetKind: terminalTargetKind.optional(),
+    limit: z.coerce.number().int().min(1).max(TERMINAL_HISTORY_LIMIT_MAX).default(50),
+    /** Page backwards from this session id. */
+    before: z.coerce.number().int().positive().optional(),
+  })
+  .strict();
+export type TerminalSessionListQuery = z.infer<typeof terminalSessionListQuery>;
+
+/**
+ * PUT /v1/terminals/settings (operator). Partial: only the named keys change.
+ * Turning `hostTerminalEnabled` on needs step-up (`password`, or a sign-in
+ * less than 10 minutes old) and an interactive session.
+ */
+export const terminalSettings = z
+  .object({
+    hostTerminalEnabled: z.boolean(),
+    idleTimeoutMinutes: z.number().int().min(1).max(240),
+    maxSessionMinutes: z.number().int().min(5).max(1440),
+    maxConcurrent: z.number().int().min(1).max(50),
+    retentionDays: z.number().int().min(30).max(3650),
+    password: z.string().max(1024).optional(),
+  })
+  .partial()
+  .strict();
+export type TerminalSettingsInput = z.infer<typeof terminalSettings>;
+
+/** GET /v1/terminals/settings: the stored values (defaults when unset). */
+export const terminalSettingsView = z.object({
+  hostTerminalEnabled: z.boolean(),
+  /** `NINEDEPLOY_HOST_TERMINAL=off` forbids host shells whatever the setting says. */
+  hostTerminalForbiddenByEnv: z.boolean(),
+  idleTimeoutMinutes: z.number().int(),
+  maxSessionMinutes: z.number().int(),
+  maxConcurrent: z.number().int(),
+  retentionDays: z.number().int(),
+});
+export type TerminalSettingsView = z.infer<typeof terminalSettingsView>;
+
+/** Defaults applied when a settings key is absent (fresh and upgraded installs alike). */
+export const TERMINAL_SETTINGS_DEFAULTS = {
+  hostTerminalEnabled: false,
+  idleTimeoutMinutes: 15,
+  maxSessionMinutes: 240,
+  maxConcurrent: 10,
+  retentionDays: 180,
+} as const;
+
+// ── attach protocol v1 (`ninedeploy.terminal.v1`) ──────────────────────────
+// Binary frames carry stdin / output. Text frames carry these JSON messages.
+
+/** Client → server text frames. */
+export const terminalClientMessage = z.discriminatedUnion('t', [
+  z.object({ t: z.literal('resize'), cols: terminalCols, rows: terminalRows }).strict(),
+  z.object({ t: z.literal('ping') }).strict(),
+]);
+export type TerminalClientMessage = z.infer<typeof terminalClientMessage>;
+
+/** Server → client text frames. */
+export const terminalServerMessage = z.discriminatedUnion('t', [
+  z.object({
+    t: z.literal('ready'),
+    sessionId: id,
+    target: z.object({ kind: terminalTargetKind, label: z.string(), serverId: id.nullable() }),
+  }),
+  z.object({ t: z.literal('notice'), message: z.string() }),
+  z.object({ t: z.literal('exit'), code: z.number().int().nullable(), reason: z.string() }),
+]);
+export type TerminalServerMessage = z.infer<typeof terminalServerMessage>;
+
+/** WebSocket close codes of the attach socket. */
+export const TERMINAL_CLOSE = {
+  shellExited: 1000,
+  frameTooLarge: 1009,
+  badTicket: 4401,
+  forbidden: 4403,
+  idle: 4408,
+  maxDuration: 4409,
+  terminated: 4410,
+  tooManySessions: 4429,
+  targetUnreachable: 4502,
+} as const;
+
+/** Subprotocols of the attach socket: the protocol name, then the ticket. */
+export const TERMINAL_PROTOCOL = 'ninedeploy.terminal.v1';
+export const TERMINAL_TICKET_PROTOCOL_PREFIX = 'ninedeploy.ticket.';

package/src/traffic.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+// ── Traffic analytics (0.15) ────────────────────────────────────────────────
+// Request and response shapes for `/v1/traffic` and
+// `/v1/services/:id/traffic`. Analytics is opt-in everywhere (owner decision
+// O3): with it off, Traefik's static config is byte-identical to 0.14. Only
+// aggregate counters are kept — no client IP, path, query string or header.
+// Design: DESIGN.md §2.
+
+export const TRAFFIC_RETENTION_DAYS_MIN = 1;
+export const TRAFFIC_RETENTION_DAYS_MAX = 400;
+export const TRAFFIC_RETENTION_DAYS_DEFAULT = 30;
+export const TRAFFIC_TOP_MAX = 50;
+
+/** Bucket widths in seconds: minute rows and hour rows. */
+export const TRAFFIC_GRANULARITIES = [60, 3600] as const;
+export const trafficGranularity = z.union([z.literal(60), z.literal(3600)]);
+export type TrafficGranularity = z.infer<typeof trafficGranularity>;
+
+/** Upper edges (ms) of the latency histogram; one overflow bucket follows. */
+export const TRAFFIC_LATENCY_EDGES_MS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] as const;
+/** Buckets in `latencyHist`: one per edge plus the overflow. */
+export const TRAFFIC_LATENCY_BUCKETS = TRAFFIC_LATENCY_EDGES_MS.length + 1;
+
+export const trafficRange = z.enum(['1h', '24h', '7d', '30d']);
+export type TrafficRange = z.infer<typeof trafficRange>;
+
+/** Minute buckets for 1h/24h, hour buckets for 7d/30d. */
+export function trafficRangeGranularity(range: TrafficRange): TrafficGranularity {
+  return range === '1h' || range === '24h' ? 60 : 3600;
+}
+
+export const trafficStatus = z.enum(['off', 'starting', 'running', 'error']);
+export type TrafficStatus = z.infer<typeof trafficStatus>;
+
+/** PUT /v1/traffic/settings (operator). Enabling or disabling recreates Traefik once. */
+export const trafficSettingsUpdate = z
+  .object({
+    enabled: z.boolean().optional(),
+    retentionDays: z.number().int().min(TRAFFIC_RETENTION_DAYS_MIN).max(TRAFFIC_RETENTION_DAYS_MAX).optional(),
+  })
+  .strict();
+export type TrafficSettingsUpdate = z.infer<typeof trafficSettingsUpdate>;
+
+/** GET /v1/traffic/settings, and the PUT answer. */
+export const trafficSettingsView = z.object({
+  enabled: z.boolean(),
+  retentionDays: z.number().int(),
+  status: trafficStatus,
+  lastError: z.string().nullable(),
+  lastIngestAt: z.string().nullable(),
+  logBytes: z.number().int().nonnegative(),
+  malformedLines: z.number().int().nonnegative(),
+  /** `docker info` LoggingDriver; null when Docker did not answer. */
+  dockerLogDriver: z.string().nullable(),
+});
+export type TrafficSettingsView = z.infer<typeof trafficSettingsView>;
+
+/** GET /v1/traffic/summary and /v1/services/:id/traffic query. */
+export const trafficSummaryQuery = z
+  .object({
+    range: trafficRange.default('24h'),
+    top: z.coerce.number().int().min(1).max(TRAFFIC_TOP_MAX).default(10),
+  })
+  .strict();
+export type TrafficSummaryQuery = z.infer<typeof trafficSummaryQuery>;
+
+/** Counters shared by a bucket, a domain row and the totals. */
+export const trafficCounters = z.object({
+  requests: z.number().int().nonnegative(),
+  status1xx: z.number().int().nonnegative(),
+  status2xx: z.number().int().nonnegative(),
+  status3xx: z.number().int().nonnegative(),
+  status4xx: z.number().int().nonnegative(),
+  status5xx: z.number().int().nonnegative(),
+  statusOther: z.number().int().nonnegative(),
+  bytesOut: z.number().int().nonnegative(),
+  durationSumMs: z.number().int().nonnegative(),
+  durationMaxMs: z.number().int().nonnegative(),
+});
+export type TrafficCounters = z.infer<typeof trafficCounters>;
+
+/** Percentiles estimated from the histogram; null when there were no requests. */
+export const trafficPercentiles = z.object({
+  p50Ms: z.number().nonnegative().nullable(),
+  p95Ms: z.number().nonnegative().nullable(),
+  p99Ms: z.number().nonnegative().nullable(),
+});
+export type TrafficPercentiles = z.infer<typeof trafficPercentiles>;
+
+export const trafficBucket = trafficCounters.extend({
+  /** Bucket start, ISO 8601. */
+  t: z.string(),
+});
+export type TrafficBucket = z.infer<typeof trafficBucket>;
+
+/** One domain (or the panel / custom / other bucket) over the range. */
+export const trafficScopeTotal = trafficCounters.extend(trafficPercentiles.shape).extend({
+  /** `d:<domainId>` | `panel` | `custom` | `other`. */
+  scopeKey: z.string(),
+  domainId: z.number().int().positive().nullable(),
+  serviceId: z.number().int().positive().nullable(),
+  /** The host as recorded, kept after the domain is deleted. */
+  host: z.string().nullable(),
+});
+export type TrafficScopeTotal = z.infer<typeof trafficScopeTotal>;
+
+/** GET /v1/traffic/summary (operator): the whole instance. */
+export const trafficSummary = z.object({
+  enabled: z.boolean(),
+  range: trafficRange,
+  granularity: trafficGranularity,
+  totals: trafficCounters.extend(trafficPercentiles.shape),
+  series: z.array(trafficBucket),
+  topDomains: z.array(trafficScopeTotal),
+  panel: trafficScopeTotal.nullable(),
+  custom: trafficScopeTotal.nullable(),
+});
+export type TrafficSummary = z.infer<typeof trafficSummary>;
+
+/** GET /v1/services/:id/traffic (any seat on the service). Empty series, never 404, without data. */
+export const serviceTrafficSummary = z.object({
+  enabled: z.boolean(),
+  range: trafficRange,
+  granularity: trafficGranularity,
+  totals: trafficCounters.extend(trafficPercentiles.shape),
+  series: z.array(trafficBucket),
+  domains: z.array(trafficScopeTotal),
+});
+export type ServiceTrafficSummary = z.infer<typeof serviceTrafficSummary>;

package/src/workspaces.ts

@@ -0,0 +1,215 @@
+import { z } from 'zod';
+import { slug } from './common.js';
+
+export const workspaceRoleEnum = z.enum(['owner', 'admin', 'member', 'viewer']);
+export type WorkspaceRole = z.infer<typeof workspaceRoleEnum>;
+
+/** Roles that may be GRANTED directly when adding a member or creating an
+ *  invitation. 'owner' is deliberately excluded: the PATCH member route is
+ *  the only place that performs the full ownership transfer (demote the
+ *  current owner, re-key `workspaces.ownerId`) — an owner-rank row inserted
+ *  through add/invite would mint owner authority without that bookkeeping. */
+export const assignableWorkspaceRoleEnum = z.enum(['admin', 'member', 'viewer']);
+export type AssignableWorkspaceRole = z.infer<typeof assignableWorkspaceRoleEnum>;
+
+export const workspaceCreate = z.object({
+  name: z.string().trim().min(2).max(63),
+  slug: slug.optional(),
+  description: z.string().trim().max(500).optional(),
+});
+export type WorkspaceCreate = z.infer<typeof workspaceCreate>;
+export type WorkspaceCreateInput = WorkspaceCreate;
+
+export const workspaceUpdate = z
+  .object({
+    name: z.string().trim().min(2).max(63).optional(),
+    description: z.string().trim().max(500).nullable().optional(),
+  })
+  .refine((v) => Object.keys(v).length > 0, { message: 'nothing to update' });
+export type WorkspaceUpdate = z.infer<typeof workspaceUpdate>;
+export type WorkspaceUpdateInput = WorkspaceUpdate;
+
+export const workspaceMemberAdd = z.object({
+  email: z.string().email(),
+  role: assignableWorkspaceRoleEnum.default('member'),
+});
+export type WorkspaceMemberAdd = z.infer<typeof workspaceMemberAdd>;
+export type WorkspaceMemberAddInput = WorkspaceMemberAdd;
+
+export const workspaceMemberRoleUpdate = z.object({
+  role: workspaceRoleEnum,
+});
+export type WorkspaceMemberRoleUpdate = z.infer<typeof workspaceMemberRoleUpdate>;
+export type WorkspaceMemberRoleUpdateInput = WorkspaceMemberRoleUpdate;
+
+export interface WorkspaceMemberEntry {
+  id: number;
+  workspaceId: number;
+  userId: number;
+  email: string;
+  name: string | null;
+  role: WorkspaceRole;
+  createdAt: string;
+}
+
+/**
+ * Response from POST /v1/workspaces/:id/members when the address is NOT a
+ * registered user yet. The server creates a pending invitation and returns
+ * the accept URL (also emailed when an SMTP channel is configured).
+ */
+export interface WorkspaceMemberInviteEntry {
+  kind: 'invitation';
+  id: number;
+  workspaceId: number;
+  email: string;
+  role: WorkspaceRole;
+  acceptUrl: string;
+  expiresAt: string;
+  createdAt: string;
+}
+
+export interface WorkspaceEntry {
+  id: number;
+  name: string;
+  slug: string;
+  description: string | null;
+  ownerId: number;
+  myRole: WorkspaceRole;
+  memberCount: number;
+  projectCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+export type Workspace = WorkspaceEntry;
+
+export interface WorkspaceDetail extends WorkspaceEntry {
+  members: WorkspaceMemberEntry[];
+}
+
+// ─── Workspace Invitations ──────────────────────────────────────────────────
+// A pending invite lets an owner/admin onboard an address that may or may not
+// have a `users` row yet. While the row is outstanding, the only way the
+// address becomes a workspace member is by visiting the accept URL (or by
+// being promoted by an auto-accept hook on first login / OIDC).
+export const workspaceInvitationCreate = z.object({
+  email: z.string().email().max(254),
+  role: assignableWorkspaceRoleEnum.default('member'),
+});
+export type WorkspaceInvitationCreate = z.infer<typeof workspaceInvitationCreate>;
+export type WorkspaceInvitationCreateInput = WorkspaceInvitationCreate;
+
+export interface WorkspaceInvitationEntry {
+  id: number;
+  workspaceId: number;
+  email: string;
+  role: WorkspaceRole;
+  invitedByUserId: number;
+  invitedByName: string | null;
+  expiresAt: string;
+  acceptedAt: string | null;
+  acceptedByUserId: number | null;
+  revokedAt: string | null;
+  createdAt: string;
+}
+
+/** Public view of an invitation (token is only returned once at create time). */
+export interface WorkspaceInvitationPublic {
+  workspaceId: number;
+  workspaceName: string;
+  workspaceSlug: string;
+  email: string;
+  role: WorkspaceRole;
+  invitedByName: string | null;
+  expiresAt: string;
+}
+
+// ─── OIDC & OAuth2 SSO Schemas ───────────────────────────────────────────────
+/**
+ * r507: one allowed email domain for an SSO provider (`corp.com`; a leading
+ * `@` is tolerated and dropped). Matching is exact — list subdomains you mean.
+ */
+export const oidcAllowedDomain = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .transform((v) => v.replace(/^@/, ''))
+  .pipe(
+    z
+      .string()
+      .min(3)
+      .max(253)
+      .regex(/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/, 'must be a domain like corp.com'),
+  );
+const oidcAllowedDomains = z.array(oidcAllowedDomain).max(50);
+
+export const oidcProviderCreate = z.object({
+  name: z.string().trim().min(2).max(63),
+  slug: slug,
+  issuerUrl: z.string().url().nullable().optional(),
+  clientId: z.string().trim().min(1).max(255),
+  clientSecret: z.string().trim().min(1).max(500),
+  scopes: z.string().trim().default('openid profile email'),
+  enabled: z.boolean().default(true),
+  autoEnroll: z.boolean().default(true),
+  /**
+   * @deprecated F1014: IGNORED for OIDC sign-ins. Since D1/F146 a user an OIDC
+   * provider enrolls always owns their own personal workspace, and an OIDC
+   * provider maps users into no team workspace, so nothing reads this role.
+   * Team seats come from invitations (which carry their own role) or SCIM.
+   * Still accepted and stored so existing clients and rows keep working.
+   */
+  defaultRole: z.enum(['admin', 'member']).default('member'),
+  /** r507: empty (the default) = any verified email the IdP vouches for. */
+  allowedDomains: oidcAllowedDomains.optional(),
+});
+export type OidcProviderCreate = z.infer<typeof oidcProviderCreate>;
+/**
+ * What a client sends: fields with a server-side default are optional (F1014:
+ * so a caller never has to send the deprecated `defaultRole`). Same shape as
+ * the other `*Input` aliases (`z.input`).
+ */
+export type OidcProviderCreateInput = z.input<typeof oidcProviderCreate>;
+
+export const oidcProviderUpdate = z
+  .object({
+    name: z.string().trim().min(2).max(63).optional(),
+    issuerUrl: z.string().url().nullable().optional(),
+    clientId: z.string().trim().min(1).max(255).optional(),
+    clientSecret: z.string().trim().min(1).max(500).optional(),
+    scopes: z.string().trim().optional(),
+    enabled: z.boolean().optional(),
+    autoEnroll: z.boolean().optional(),
+    /** @deprecated F1014: ignored for OIDC sign-ins; see oidcProviderCreate.defaultRole. */
+    defaultRole: z.enum(['admin', 'member']).optional(),
+    allowedDomains: oidcAllowedDomains.optional(),
+  })
+  .refine((v) => Object.keys(v).length > 0, { message: 'nothing to update' });
+export type OidcProviderUpdate = z.infer<typeof oidcProviderUpdate>;
+export type OidcProviderUpdateInput = OidcProviderUpdate;
+
+export interface OidcProviderEntry {
+  id: number;
+  name: string;
+  slug: string;
+  issuerUrl: string | null;
+  clientId: string;
+  scopes: string;
+  enabled: boolean;
+  autoEnroll: boolean;
+  /**
+   * @deprecated F1014: the stored value, echoed for compatibility. It has no
+   * effect on OIDC sign-ins; see oidcProviderCreate.defaultRole.
+   */
+  defaultRole: 'admin' | 'member';
+  /** r507: email domains allowed to sign in / enroll; empty = unrestricted. */
+  allowedDomains: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface OidcPublicProvider {
+  id: number;
+  name: string;
+  slug: string;
+  authUrl: string;
+}