@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/cli/instanceModel.ts

@@ -0,0 +1,275 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { normalizeBasePath } from "../lib/basePath";
+import { MANAGED_INSTANCE_CONTROL_PATH } from "../lib/managedInstance";
+import { CaptureModeSchema, type CaptureMode } from "../lib/runtimeConfig";
+
+export const INSTANCE_RECORD_SCHEMA_VERSION = 1;
+export const INSTANCE_OUTPUT_SCHEMA_VERSION = 1;
+export const MAX_INSTANCE_NAME_LENGTH = 64;
+
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/u;
+const INSTANCE_NAME_CHARACTERS = /^[a-z0-9._-]+$/u;
+
+export type InstanceRegistryErrorCode =
+  | "data_dir_conflict"
+  | "data_dir_invalid"
+  | "lock_not_owned"
+  | "lock_timeout"
+  | "name_invalid"
+  | "port_conflict"
+  | "port_exhausted"
+  | "port_invalid"
+  | "record_invalid"
+  | "registry_io";
+
+export type InstanceRegistryError = {
+  code: InstanceRegistryErrorCode;
+  message: string;
+};
+
+export type InstanceRegistryResult<T> =
+  | { kind: "success"; value: T }
+  | { kind: "error"; error: InstanceRegistryError };
+
+export function instanceRegistrySuccess<T>(value: T): InstanceRegistryResult<T> {
+  return { kind: "success", value };
+}
+
+export function instanceRegistryError<T>(
+  code: InstanceRegistryErrorCode,
+  message: string,
+): InstanceRegistryResult<T> {
+  return { kind: "error", error: { code, message } };
+}
+
+/**
+ * Normalize a user-facing instance name to its case-insensitive Windows key.
+ * Validation happens before callers create a registry directory.
+ */
+export function validateInstanceName(rawName: string): InstanceRegistryResult<string> {
+  const normalized = rawName.toLowerCase();
+  const invalid =
+    rawName.length === 0 ||
+    rawName !== rawName.trim() ||
+    normalized.length > MAX_INSTANCE_NAME_LENGTH ||
+    normalized === "." ||
+    normalized === ".." ||
+    normalized === "default" ||
+    normalized.endsWith(".") ||
+    normalized.endsWith(" ") ||
+    !INSTANCE_NAME_CHARACTERS.test(normalized) ||
+    WINDOWS_DEVICE_NAME.test(normalized);
+
+  return invalid
+    ? instanceRegistryError(
+        "name_invalid",
+        `Invalid instance name ${JSON.stringify(rawName)}. Use 1-${String(MAX_INSTANCE_NAME_LENGTH)} letters, digits, dots, hyphens, or underscores; "default" and Windows device names are reserved.`,
+      )
+    : instanceRegistrySuccess(normalized);
+}
+
+export function normalizeInstanceBasePath(
+  rawBasePath: string | undefined,
+): InstanceRegistryResult<string> {
+  const value = rawBasePath ?? "";
+  const trimmed = value.trim();
+  const hasControlCharacter = [...trimmed].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint < 32 || codePoint === 127;
+  });
+  if (
+    trimmed.length > 0 &&
+    (!trimmed.startsWith("/") ||
+      trimmed.includes("?") ||
+      trimmed.includes("#") ||
+      trimmed.includes("\\") ||
+      hasControlCharacter)
+  ) {
+    return instanceRegistryError(
+      "record_invalid",
+      "Instance Base Path must be an absolute URL path without a query, hash, backslash, or control character.",
+    );
+  }
+  const normalized = normalizeBasePath(trimmed);
+  const reservedControlRoot = MANAGED_INSTANCE_CONTROL_PATH.replace(/\/instance$/u, "");
+  if (normalized === reservedControlRoot || normalized.startsWith(`${reservedControlRoot}/`)) {
+    return instanceRegistryError(
+      "record_invalid",
+      `Instance Base Path ${normalized} collides with the reserved Agent Inspector control namespace.`,
+    );
+  }
+  return instanceRegistrySuccess(normalized);
+}
+
+const NormalizedInstanceNameSchema = z.string().refine((name) => {
+  const result = validateInstanceName(name);
+  return result.kind === "success" && result.value === name;
+});
+
+const NormalizedBasePathSchema = z.string().refine((basePath) => {
+  const result = normalizeInstanceBasePath(basePath);
+  return result.kind === "success" && result.value === basePath;
+});
+
+const PortSchema = z.number().int().min(1).max(65_535);
+const TimestampSchema = z.string().datetime();
+const IdentifierSchema = z.string().min(8).max(128);
+
+export const InstanceLaunchSchema = z
+  .object({
+    launchId: IdentifierSchema,
+    controlToken: z.string().min(32).max(256),
+    startedAt: TimestampSchema,
+  })
+  .strict();
+
+export const InstanceRecordSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_RECORD_SCHEMA_VERSION),
+    name: NormalizedInstanceNameSchema,
+    instanceId: IdentifierSchema,
+    createdAt: TimestampSchema,
+    updatedAt: TimestampSchema,
+    host: z.string().trim().min(1).max(255),
+    publicPort: PortSchema,
+    upstreamPort: PortSchema,
+    basePath: NormalizedBasePathSchema,
+    captureMode: CaptureModeSchema,
+    dataDir: z
+      .string()
+      .min(1)
+      .refine((path) => isAbsolute(path)),
+    launch: InstanceLaunchSchema,
+  })
+  .strict()
+  .superRefine((record, context) => {
+    if (record.publicPort === record.upstreamPort) {
+      context.addIssue({
+        code: "custom",
+        message: "Public and upstream ports must be different.",
+        path: ["upstreamPort"],
+      });
+    }
+  });
+
+export type InstanceLaunch = z.infer<typeof InstanceLaunchSchema>;
+export type InstanceRecord = z.infer<typeof InstanceRecordSchema>;
+
+export type InstanceRecordOutput = {
+  schemaVersion: typeof INSTANCE_OUTPUT_SCHEMA_VERSION;
+  name: string;
+  instanceId: string;
+  createdAt: string;
+  updatedAt: string;
+  host: string;
+  publicPort: number;
+  upstreamPort: number;
+  basePath: string;
+  captureMode: CaptureMode;
+  dataDir: string;
+  launch: {
+    launchId: string;
+    startedAt: string;
+  };
+};
+
+export type CreateInstanceRecordInput = {
+  name: string;
+  host: string;
+  publicPort: number;
+  upstreamPort: number;
+  basePath?: string;
+  captureMode: CaptureMode;
+  dataDir: string;
+};
+
+export type InstanceIdentityFactory = {
+  now?: () => Date;
+  createInstanceId?: () => string;
+  createLaunchId?: () => string;
+  createControlToken?: () => string;
+};
+
+function createLaunch(factory: InstanceIdentityFactory, now: Date): InstanceLaunch {
+  return {
+    launchId: factory.createLaunchId?.() ?? randomUUID(),
+    controlToken: factory.createControlToken?.() ?? randomBytes(32).toString("base64url"),
+    startedAt: now.toISOString(),
+  };
+}
+
+export function createInstanceRecord(
+  input: CreateInstanceRecordInput,
+  factory: InstanceIdentityFactory = {},
+): InstanceRegistryResult<InstanceRecord> {
+  const name = validateInstanceName(input.name);
+  if (name.kind === "error") return name;
+  const basePath = normalizeInstanceBasePath(input.basePath);
+  if (basePath.kind === "error") return basePath;
+
+  const now = factory.now?.() ?? new Date();
+  const timestamp = now.toISOString();
+  const candidate: unknown = {
+    schemaVersion: INSTANCE_RECORD_SCHEMA_VERSION,
+    name: name.value,
+    instanceId: factory.createInstanceId?.() ?? randomUUID(),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    host: input.host.trim(),
+    publicPort: input.publicPort,
+    upstreamPort: input.upstreamPort,
+    basePath: basePath.value,
+    captureMode: input.captureMode,
+    dataDir: input.dataDir,
+    launch: createLaunch(factory, now),
+  };
+  const parsed = InstanceRecordSchema.safeParse(candidate);
+  return parsed.success
+    ? instanceRegistrySuccess(parsed.data)
+    : instanceRegistryError(
+        "record_invalid",
+        `Cannot create instance record: ${parsed.error.issues[0]?.message ?? "invalid saved configuration"}`,
+      );
+}
+
+export function rotateInstanceLaunch(
+  record: InstanceRecord,
+  factory: InstanceIdentityFactory = {},
+): InstanceRegistryResult<InstanceRecord> {
+  const now = factory.now?.() ?? new Date();
+  const candidate: unknown = {
+    ...record,
+    updatedAt: now.toISOString(),
+    launch: createLaunch(factory, now),
+  };
+  const parsed = InstanceRecordSchema.safeParse(candidate);
+  return parsed.success
+    ? instanceRegistrySuccess(parsed.data)
+    : instanceRegistryError(
+        "record_invalid",
+        `Cannot rotate instance launch: ${parsed.error.issues[0]?.message ?? "invalid saved configuration"}`,
+      );
+}
+
+/** A deliberate allow-list prevents control credentials from reaching CLI JSON output. */
+export function toInstanceRecordOutput(record: InstanceRecord): InstanceRecordOutput {
+  return {
+    schemaVersion: INSTANCE_OUTPUT_SCHEMA_VERSION,
+    name: record.name,
+    instanceId: record.instanceId,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    host: record.host,
+    publicPort: record.publicPort,
+    upstreamPort: record.upstreamPort,
+    basePath: record.basePath,
+    captureMode: record.captureMode,
+    dataDir: record.dataDir,
+    launch: {
+      launchId: record.launch.launchId,
+      startedAt: record.launch.startedAt,
+    },
+  };
+}