overmux 0.0.4 → 0.0.6

package/src/internal/server/auth/instance-control.ts

@@ -1,17 +1,14 @@
 import { createHash, randomBytes } from "node:crypto";
-import { chmod, mkdir, readdir, rm } from "node:fs/promises";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, readdir, rm } from "node:fs/promises";
 import { createConnection, createServer, type Socket } from "node:net";
-import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
 
 import { instanceIdSchema } from "@overmux/shared";
 
 import { getOvermuxPaths } from "../paths";
-import {
-  readPrivateJson,
-  replacePrivateJsonAtomically,
-} from "../notifications/private-json-file";
+import { replacePrivateJsonAtomically } from "../notifications/private-json-file";
 import type { AuthService } from "./auth-service";
 
 const maxControlMessageBytes = 16_384;
@@ -94,9 +91,20 @@ type ControlResponseByType = {
   >;
 };
 
-const runtimeDirectory = () => {
-  const paths = getOvermuxPaths();
-  const preferred = paths.runtimeDir ?? join(paths.stateDir, "runtime");
+const currentUid = () => {
+  if (!process.getuid) {
+    throw new Error("Overmux instance control requires a Unix user ID");
+  }
+  return process.getuid();
+};
+
+export const runtimeDirectory = () => {
+  const fallback = `/tmp/overmux-${currentUid()}`;
+  const preferred = getOvermuxPaths().runtimeDir;
+  if (!preferred) {
+    return fallback;
+  }
+  // Leave room for the slash, 16-character ID and .sock on macOS and Linux.
   if (Buffer.byteLength(preferred) <= 80) {
     return preferred;
   }
@@ -104,7 +112,51 @@ const runtimeDirectory = () => {
     .update(preferred)
     .digest("hex")
     .slice(0, 12);
-  return join(tmpdir(), `overmux-${process.getuid?.() ?? "user"}-${suffix}`);
+  return `${fallback}-${suffix}`;
+};
+
+const secureRuntimeDirectory = async (directory: string) => {
+  // Only the final component must not be a symlink: macOS /tmp is a symlink.
+  // Validate and chmod the same inode, never a path that could be swapped
+  // between checking ownership and changing permissions. The sticky /tmp
+  // parent (or user-controlled XDG parent) then protects our owned directory
+  // from replacement by other users. Same-user processes are already trusted.
+  const handle = await open(
+    directory,
+    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+  );
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isDirectory() || metadata.uid !== currentUid()) {
+      throw new Error(`Unsafe Overmux runtime directory: ${directory}`);
+    }
+    await handle.chmod(0o700);
+  } finally {
+    await handle.close();
+  }
+};
+
+const readRegistration = async (path: string) => {
+  // An existing directory may have been writable before we secured it. Do not
+  // trust planted symlinks, foreign-owned files or publicly writable records.
+  // O_NONBLOCK also prevents a planted FIFO from hanging discovery on open.
+  const handle = await open(
+    path,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+  );
+  try {
+    const metadata = await handle.stat();
+    if (
+      !metadata.isFile() ||
+      metadata.uid !== currentUid() ||
+      (metadata.mode & 0o077) !== 0
+    ) {
+      return undefined;
+    }
+    return registrationSchema.parse(JSON.parse(await handle.readFile("utf8")));
+  } finally {
+    await handle.close();
+  }
 };
 
 const readNewlineFrame = ({
@@ -245,7 +297,7 @@ export const startInstanceControl = async ({
 }): Promise<InstanceControl> => {
   const directory = runtimeDirectory();
   await mkdir(directory, { mode: 0o700, recursive: true });
-  await chmod(directory, 0o700);
+  await secureRuntimeDirectory(directory);
   const id = randomBytes(8).toString("hex");
   const socketPath = join(directory, `${id}.sock`);
   const registrationPath = join(directory, `${id}.json`);
@@ -310,6 +362,7 @@ export const discoverInstance = async (
   const directory = runtimeDirectory();
   let names: string[];
   try {
+    await secureRuntimeDirectory(directory);
     names = await readdir(directory);
   } catch (cause) {
     if ((cause as NodeJS.ErrnoException).code === "ENOENT") {
@@ -322,9 +375,7 @@ export const discoverInstance = async (
       names
         .filter((name) => name.endsWith(".json"))
         .map((name) =>
-          readPrivateJson(join(directory, name), registrationSchema).catch(
-            () => undefined,
-          ),
+          readRegistration(join(directory, name)).catch(() => undefined),
         ),
     )
   ).filter((registration): registration is InstanceRegistration =>

package/src/internal/server/coordinator/ipc-protocol.ts

@@ -9,7 +9,6 @@ const childOptionsSchema = z.object({
   debug: z.boolean().optional(),
   developmentWebTarget: z.url().optional(),
   host: z.string().optional(),
-  logFile: z.string().optional(),
   port: z.number().int().min(0).max(65_535).optional(),
   productionWebAssetsDir: z.string().optional(),
   watch: z.boolean().optional(),

package/src/internal/server/runtime/create-runtime.ts

@@ -7,7 +7,7 @@ import type {
   InstanceIdentity,
   Notifications,
 } from "../../../public/index";
-import { createRuntimeInstance } from "./runtime-instance";
+import { createRuntimeInstance, defaultInstanceId } from "./runtime-instance";
 import { protocolVersion, type RuntimeManifest } from "../../shared/index";
 
 import { createRuntimeLifecycle } from "./runtime-lifecycle";
@@ -46,12 +46,14 @@ type CreateRuntimeOptions = {
 
 export const createRuntime = async ({
   config,
-  debug = false,
+  debug = true,
   notifications = { send: async () => undefined },
   signal,
 }: CreateRuntimeOptions): Promise<Runtime> => {
   const lifecycle = createRuntimeLifecycle(signal);
-  const instance = createRuntimeInstance(config.instanceId);
+  const instance = createRuntimeInstance(
+    config.instanceId ?? defaultInstanceId,
+  );
   try {
     const resources = createRuntimeResources({
       definitions: (config.server.resources ??

package/src/internal/server/runtime/runtime-instance.ts

@@ -6,10 +6,13 @@ import {
 } from "../../shared/index";
 import type { InstanceContext } from "../../../public/config";
 
+export const defaultInstanceId = ({ port }: { port: number }) =>
+  `${hostname()}-${port}`;
+
 // The scope exists during preparation, but identity is immutable once the listener
 // binds. No handler or connection may observe it before establishment.
 export const createRuntimeInstance = (
-  configured: RuntimeConfigDefinition["instanceId"],
+  configured: NonNullable<RuntimeConfigDefinition["instanceId"]>,
 ) => {
   let identity: InstanceIdentity | undefined;
   const get = () => {
@@ -30,9 +33,7 @@ export const createRuntimeInstance = (
       }
       try {
         identity = createInstanceIdentity(
-          typeof configured === "function"
-            ? configured({ port })
-            : (configured ?? `${hostname()}-${port}`),
+          typeof configured === "function" ? configured({ port }) : configured,
         );
       } catch (cause) {
         throw new Error(

package/src/internal/server/runtime/runtime-operations.ts

@@ -2,12 +2,14 @@
 // Lookup metadata stays aligned with the names published in the runtime manifest.
 
 import type {
-  HandlerContext,
+  OperationContext,
   OperationDefinition,
 } from "../../../public/index";
 import type { Notifications } from "../../../public/index";
 import { z } from "zod";
 
+import type { RuntimeHandlerContext } from "./runtime-resources";
+
 export class OperationValidationError extends Error {
   constructor(
     readonly phase: "input" | "output",
@@ -27,14 +29,18 @@ export type RuntimeOperations = {
   names: readonly string[];
 };
 
-type AnyOperation = OperationDefinition<z.ZodTypeAny, z.ZodTypeAny>;
+type AnyOperation = OperationDefinition<
+  z.ZodTypeAny,
+  z.ZodTypeAny,
+  OperationContext<Record<string, unknown>>
+>;
 
 export type RuntimeOperationDefinitions = Readonly<
   Record<string, AnyOperation>
 >;
 
 type CreateRuntimeOperationsOptions = {
-  context: (signal?: AbortSignal) => HandlerContext;
+  context: (signal?: AbortSignal) => RuntimeHandlerContext;
   definitions: RuntimeOperationDefinitions;
   notifications: Notifications;
 };

package/src/internal/server/runtime/runtime-resources.ts

@@ -5,7 +5,6 @@ import {
   type ResourceDefinition,
   type RuntimeDisposer,
 } from "../../../public/index";
-import type { ResourceContract } from "../../../public/index";
 import { isDeepStrictEqual } from "node:util";
 
 import {
@@ -27,10 +26,12 @@ export type RuntimeResourceDefinitions = Readonly<
   Record<string, ResourceDefinition>
 >;
 
+export type RuntimeHandlerContext = HandlerContext<Record<string, unknown>>;
+
 export type RuntimeResources = {
-  context: (signal?: AbortSignal) => HandlerContext;
+  context: (signal?: AbortSignal) => RuntimeHandlerContext;
   get: (name: string) => RuntimeResource | undefined;
-  invalidate: (contract: ResourceContract, input?: unknown) => void;
+  invalidate: RuntimeHandlerContext["invalidate"];
   names: readonly string[];
 };
 
@@ -53,16 +54,8 @@ export const createRuntimeResources = ({
 }: CreateRuntimeResourcesOptions): RuntimeResources => {
   const graph = createResourceDependencyGraph(definitions);
   const invalidationListeners = new Set<InvalidationListener>();
-  const contracts = new Map<ResourceContract, string[]>();
   const resources = new Map<string, RuntimeResource>();
 
-  Object.entries(definitions).forEach(([id, definition]) => {
-    contracts.set(definition.contract, [
-      ...(contracts.get(definition.contract) ?? []),
-      id,
-    ]);
-  });
-
   const invalidateResource = (
     id: string,
     input: unknown,
@@ -82,30 +75,17 @@ export const createRuntimeResources = ({
     });
   };
 
-  const invalidate = (contract: ResourceContract, input?: unknown) => {
-    const ids =
-      contracts.get(contract) ??
-      Object.entries(definitions)
-        .filter(
-          ([, definition]) =>
-            definition.contract.input === contract.input &&
-            definition.contract.output === contract.output,
-        )
-        .map(([id]) => id);
-    if (!ids.length) {
-      throw new Error("Cannot invalidate a resource outside this runtime");
+  const invalidate = (resourceId: string, input?: unknown) => {
+    if (!resources.has(resourceId)) {
+      throw new Error(`Unknown resource ID: ${resourceId}`);
     }
-    ids.forEach((id) => {
-      const definition = definitions[id]!;
-      const parsedInput =
-        input === undefined
-          ? undefined
-          : definition.contract.input.parse(input);
-      invalidateResource(id, parsedInput, input === undefined);
-    });
+    const definition = definitions[resourceId]!;
+    const parsedInput =
+      input === undefined ? undefined : definition.contract.input.parse(input);
+    invalidateResource(resourceId, parsedInput, input === undefined);
   };
 
-  const context = (signal?: AbortSignal): HandlerContext => ({
+  const context = (signal?: AbortSignal): RuntimeHandlerContext => ({
     instance,
     invalidate,
     signal: lifecycle.requestSignal(signal),

package/src/internal/server/runtime/runtime-streams.ts

@@ -1,13 +1,11 @@
 // Owns named stream registration and ordered, validated session messaging.
 // Session abort, failure, and disposal remain exactly-once across every close path.
 
-import type {
-  HandlerContext,
-  StreamHandlerDefinition,
-} from "../../../public/index";
+import type { StreamHandlerDefinition } from "../../../public/index";
 import { z } from "zod";
 
 import type { RuntimeLifecycle } from "./runtime-lifecycle";
+import type { RuntimeHandlerContext } from "./runtime-resources";
 
 export type RuntimeStreamSession = {
   dispose: () => Promise<void>;
@@ -31,13 +29,14 @@ export type RuntimeStreams = {
 type AnyStream = StreamHandlerDefinition<
   z.ZodTypeAny,
   z.ZodTypeAny,
-  z.ZodTypeAny
+  z.ZodTypeAny,
+  RuntimeHandlerContext
 >;
 
 export type RuntimeStreamDefinitions = Readonly<Record<string, AnyStream>>;
 
 type CreateRuntimeStreamsOptions = {
-  context: (signal?: AbortSignal) => HandlerContext;
+  context: (signal?: AbortSignal) => RuntimeHandlerContext;
   definitions: RuntimeStreamDefinitions;
   lifecycle: RuntimeLifecycle;
 };

package/src/internal/server/server-logger.ts

@@ -26,7 +26,6 @@ export type ServerLogger = {
 
 type ConfigurableServerLogger = ServerLogger & {
   setEnabled: (enabled: boolean) => void;
-  setLogFile: (logFile: string) => void;
 };
 
 const lifecycleEvents = new Set([
@@ -38,7 +37,7 @@ const lifecycleEvents = new Set([
   "websocket-open",
 ]);
 
-export const getDefaultServerLogFile = ({
+export const getServerLogFile = ({
   homeDir,
   xdgStateHome,
 }: {
@@ -62,12 +61,11 @@ const safeJson = (value: unknown) => {
 
 export const createServerLogger = ({
   enabled,
-  logFile = getDefaultServerLogFile(),
+  logFile,
 }: {
   enabled: boolean;
-  logFile?: string;
+  logFile: string;
 }): ConfigurableServerLogger => {
-  let activeLogFile = logFile;
   let debugEnabled = enabled;
   return {
     get enabled() {
@@ -88,16 +86,13 @@ export const createServerLogger = ({
         source: entry.source ?? "server",
         ...entry,
       });
-      mkdirSync(dirname(activeLogFile), { recursive: true });
-      appendFileSync(activeLogFile, `${record}\n`, "utf8");
+      mkdirSync(dirname(logFile), { recursive: true });
+      appendFileSync(logFile, `${record}\n`, "utf8");
       process.stderr.write(`[overmux:debug] ${record}\n`);
     },
     setEnabled: (nextEnabled) => {
       debugEnabled = nextEnabled;
     },
-    setLogFile: (nextLogFile) => {
-      activeLogFile = nextLogFile;
-    },
   };
 };
 

package/src/internal/server/server-startup-options.ts

@@ -10,13 +10,14 @@ import type { ServerConfigDefinition } from "../../public/index";
 const serverStartupOverridesRuntimeSchema = serverConfigRuntimeSchema
   .omit({ port: true })
   .extend({
+    debug: z.boolean().optional(),
     // Port 0 asks the OS for a free port for internal listeners and tests; it must not leak into user config.
     port: z.number().int().min(0).max(65_535).optional(),
   });
 
 export type ResolvedServerStartupOptions = {
+  debug: boolean;
   host: string;
-  logFile?: string;
   port: number;
   productionWebAssetsDir?: string;
   watch: boolean;
@@ -29,16 +30,10 @@ export const resolveServerStartupOptions = ({
 }: {
   config: RuntimeConfigDefinition;
   configPath: string;
-  overrides?: ServerConfigDefinition;
+  overrides?: ServerConfigDefinition & { debug?: boolean };
 }): ResolvedServerStartupOptions => {
   const validatedOverrides =
     serverStartupOverridesRuntimeSchema.parse(overrides);
-  const configuredLogFile = config.logFile
-    ? resolve(dirname(configPath), config.logFile)
-    : undefined;
-  const logFile = validatedOverrides.logFile
-    ? resolve(validatedOverrides.logFile)
-    : configuredLogFile;
   const configuredWebAssetsDir = config.productionWebAssetsDir
     ? resolve(dirname(configPath), config.productionWebAssetsDir)
     : undefined;
@@ -47,9 +42,9 @@ export const resolveServerStartupOptions = ({
     : configuredWebAssetsDir;
 
   return {
+    debug: validatedOverrides.debug ?? config.debug ?? true,
     host: validatedOverrides.host ?? config.host ?? "localhost",
-    ...(logFile === undefined ? {} : { logFile }),
-    port: validatedOverrides.port ?? config.port ?? 4200,
+    port: validatedOverrides.port ?? config.port ?? 4242,
     ...(productionWebAssetsDir === undefined ? {} : { productionWebAssetsDir }),
     watch: validatedOverrides.watch ?? config.watch ?? true,
   };

package/src/internal/server/start-application-server.ts

@@ -29,6 +29,7 @@ import { createRuntime, type Runtime } from "./runtime/create-runtime";
 import {
   createServerLogger,
   errorDetails,
+  getServerLogFile,
   type ServerLogger,
 } from "./server-logger";
 import {
@@ -40,7 +41,6 @@ import type { OvermuxServerOptions } from "./start-overmux-server";
 type ResourceCleanup = () => void | Promise<void>;
 type ServerResources = ReturnType<typeof createResources>;
 type NotificationService = ReturnType<typeof createNotificationService>;
-type ApplicationLogger = ReturnType<typeof createServerLogger>;
 type StartApplicationServerOptions = {
   onRestartRequested: () => void;
   options: OvermuxServerOptions;
@@ -361,8 +361,8 @@ export const startApplicationServer = async ({
   options,
 }: StartApplicationServerOptions): Promise<ApplicationServer> => {
   const logger = createServerLogger({
-    enabled: options.debug ?? false,
-    logFile: options.logFile ? resolve(options.logFile) : undefined,
+    enabled: options.debug ?? true,
+    logFile: getServerLogFile(),
   });
   const resources = createResources();
   resources.add(registerProcessErrorLogging(logger));
@@ -374,10 +374,7 @@ export const startApplicationServer = async ({
       configPath,
       options,
     });
-    logger.setEnabled(Boolean(options.debug || config.debug));
-    if (startup.logFile) {
-      logger.setLogFile(startup.logFile);
-    }
+    logger.setEnabled(startup.debug);
     const {
       auth,
       authOrigins,

package/src/public/ai-context.ts

@@ -1,38 +1,16 @@
 import {
-  packageSourceSnippet,
-  techStackRecommendationsSnippet,
-  type AiContextSnippet,
-} from "@overmux/shared";
+  aiContextContentBySnippet,
+  type AiContextSnippetDefinition,
+} from "@overmux/ai-context";
 
 export {
+  coreAiContextSnippets,
+  defaultAiContextSnippets,
   packageSourceSnippet,
   techStackRecommendationsSnippet,
   type AiContextSnippet,
-};
-export type AiContextSnippetDefinition = readonly AiContextSnippet[];
-
-export const coreAiContextSnippets = [
-  packageSourceSnippet,
-] as const satisfies AiContextSnippetDefinition;
-export const defaultAiContextSnippets = [
-  ...coreAiContextSnippets,
-  techStackRecommendationsSnippet,
-] as const satisfies AiContextSnippetDefinition;
-
-const packageSourceSnippetContent = `Overmux ships with documentation and TypeScript source.
-
-Run \`overmux docs\` to find the installed documentation and source for the overmux cli.
-
-E.g. \`node_modules/overmux\` and \`node_modules/@overmux/xterm\`.
-
-Inspect these files so guidance matches the versions used by the application.`;
-
-const techStackRecommendationsSnippetContent = `Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.`;
-
-const aiContextContentBySnippet: Record<AiContextSnippet, string> = {
-  [packageSourceSnippet]: packageSourceSnippetContent,
-  [techStackRecommendationsSnippet]: techStackRecommendationsSnippetContent,
-};
+  type AiContextSnippetDefinition,
+} from "@overmux/ai-context";
 
 export const composeAiContext = (snippets: AiContextSnippetDefinition) =>
   snippets.length === 0

package/src/public/client.ts

@@ -28,15 +28,9 @@ export type {
   OvermuxThemeToken,
 } from "../internal/client/theme-scope";
 export {
-  chordPrefixSchema,
-  commandBindingSchema,
   defineCommandRegistry,
   defineOvermuxClient,
-  formatKeyBinding,
   formatShortcutBinding,
-  keyBindingSchema,
-  matchesKeyBinding,
-  shortcutBindingSchema,
 } from "../internal/client/client-definition";
 export {
   skipToken,