@powerhousedao/switchboard 6.0.0-dev.21 → 6.0.0-dev.211

package/dist/server.d.mts

@@ -0,0 +1,93 @@
+import { ILogger } from "document-model";
+import { MeterProvider } from "@opentelemetry/api";
+import { IReactorClient } from "@powerhousedao/reactor";
+import { DriveInput } from "@powerhousedao/shared/document-drive";
+import { IRenown } from "@renown/sdk";
+
+//#region src/types.d.ts
+type StorageOptions = {
+  type: "filesystem" | "memory" | "postgres" | "browser";
+  filesystemPath?: string;
+  postgresUrl?: string;
+};
+type IdentityOptions = {
+  /** Path to the keypair file. Defaults to ~/.ph/keypair.json */keypairPath?: string;
+  /**
+   * If true, won't start without an existing keypair.
+   * Use this to ensure the switchboard only runs with an authenticated identity.
+   */
+  requireExisting?: boolean; /** Base url of the Renown instance to use */
+  baseUrl?: string; /** If true, unsigned actions will be rejected */
+  requireSignatures?: boolean;
+};
+type StartServerOptions = {
+  configFile?: string;
+  port?: number;
+  /**
+   * If true, fail immediately when the requested port is in use instead of
+   * falling back to the next free port. Matches the semantics of Vite's
+   * `--strictPort` flag that flows through the `ph vetra` command.
+   */
+  strictPort?: boolean;
+  dev?: boolean;
+  dbPath?: string;
+  drive?: DriveInput;
+  packages?: string[];
+  remoteDrives?: string[];
+  https?: {
+    keyPath: string;
+    certPath: string;
+  } | boolean | undefined;
+  auth?: {
+    enabled: boolean;
+    guests: string[];
+    users: string[];
+    admins: string[];
+  };
+  /**
+   * Identity options for Renown.
+   * When configured, the switchboard will load the keypair from `ph login`
+   * and can authenticate with remote services on behalf of the user.
+   */
+  identity?: IdentityOptions;
+  mcp?: boolean;
+  processorConfig?: Map<string, unknown>;
+  disableLocalPackages?: boolean;
+  enableDocumentModelSubgraphs?: boolean;
+  /**
+   * When true, enables dynamic loading of document models from the registry
+   * when an unknown document type is encountered during sync.
+   * Disabled by default — enable with DYNAMIC_MODEL_LOADING=true env var.
+   */
+  dynamicModelLoading?: boolean;
+  logger?: ILogger;
+  /**
+   * OpenTelemetry MeterProvider to register as the global provider before
+   * ReactorInstrumentation starts. Must be provided here rather than set
+   * externally to guarantee the registration happens before
+   * instrumentation.start() reads the global provider via metrics.getMeter().
+   */
+  meterProvider?: MeterProvider;
+};
+type SwitchboardReactor = {
+  defaultDriveUrl: string | undefined;
+  reactor: IReactorClient; /** The Renown instance if identity was initialized */
+  renown: IRenown | null;
+  /**
+   * Port the HTTP server actually bound to. May differ from the requested
+   * port when the requested port was in use and fallback kicked in.
+   */
+  port: number;
+};
+//#endregion
+//#region src/server.d.mts
+/**
+ * Attempt to bind a throwaway TCP server to the given port. Resolves true if
+ * the port is free, false if the OS reports it in use. Any other error is
+ * surfaced so we don't silently mask real issues (permissions, bad host, …).
+ */
+declare function isPortAvailable(port: number): Promise<boolean>;
+declare const startSwitchboard: (options?: StartServerOptions) => Promise<SwitchboardReactor>;
+//#endregion
+export { IdentityOptions, StartServerOptions, StorageOptions, SwitchboardReactor, isPortAvailable, startSwitchboard };
+//# sourceMappingURL=server.d.mts.map

package/dist/server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.mts","names":[],"sources":["../src/types.ts","../src/server.mts"],"mappings":";;;;;;;KAMY,cAAA;EACV,IAAA;EACA,cAAA;EACA,WAAA;AAAA;AAAA,KAGU,eAAA;EALV,+DAOA,WAAA;EALA;;;AAGF;EAOE,eAAA;EAGA,OAAA,WARA;EAWA,iBAAA;AAAA;AAAA,KAGU,kBAAA;EACV,UAAA;EACA,IAAA;EAFU;;;;;EAQV,UAAA;EACA,GAAA;EACA,MAAA;EACA,KAAA,GAAQ,UAAA;EACR,QAAA;EACA,YAAA;EACA,KAAA;IAEM,OAAA;IACA,QAAA;EAAA;EAIN,IAAA;IACE,OAAA;IACA,MAAA;IACA,KAAA;IACA,MAAA;EAAA;EARI;;;;;EAeN,QAAA,GAAW,eAAA;EACX,GAAA;EACA,eAAA,GAAkB,GAAA;EAClB,oBAAA;EACA,4BAAA;EAFkB;;;;;EAQlB,mBAAA;EACA,MAAA,GAAS,OAAA;EAOO;;;AAGlB;;;EAHE,aAAA,GAAgB,aAAA;AAAA;AAAA,KAGN,kBAAA;EACV,eAAA;EACA,OAAA,EAAS,cAAA,EAED;EAAR,MAAA,EAAQ,OAAA;EAKJ;;;;EAAJ,IAAA;AAAA;;;;;;;;iBCKc,eAAA,CAAgB,IAAA,WAAe,OAAA;AAAA,cA+TlC,gBAAA,GACX,OAAA,GAAS,kBAAA,KACR,OAAA,CAAQ,kBAAA"}

package/dist/server.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { n as startSwitchboard, t as isPortAvailable } from "./server-8U7q7B7r.mjs";
+import "./utils-DFl0ezBT.mjs";
+export { isPortAvailable, startSwitchboard };

package/dist/utils-DFl0ezBT.mjs

@@ -0,0 +1,44 @@
+import { driveCreateDocument, driveCreateState } from "@powerhousedao/shared/document-drive";
+import "@powerhousedao/shared/document-model";
+//#region src/utils.mts
+async function addDefaultDrive(client, drive, serverPort) {
+	let driveId = drive.id;
+	if (!driveId || driveId.length === 0) driveId = drive.slug;
+	if (!driveId || driveId.length === 0) throw new Error("Invalid Drive Id");
+	let existingDrive;
+	try {
+		existingDrive = await client.get(driveId);
+	} catch {}
+	if (existingDrive) return `http://localhost:${serverPort}/d/${driveId}`;
+	const { global } = driveCreateState();
+	const document = driveCreateDocument({
+		global: {
+			...global,
+			name: drive.global.name,
+			icon: drive.global.icon ?? global.icon
+		},
+		local: {
+			availableOffline: drive.local?.availableOffline ?? false,
+			sharingType: drive.local?.sharingType ?? "public",
+			listeners: drive.local?.listeners ?? [],
+			triggers: drive.local?.triggers ?? []
+		}
+	});
+	if (drive.id && drive.id.length > 0) document.header.id = drive.id;
+	if (drive.slug && drive.slug.length > 0) document.header.slug = drive.slug;
+	if (drive.global.name) document.header.name = drive.global.name;
+	if (drive.preferredEditor) document.header.meta = { preferredEditor: drive.preferredEditor };
+	try {
+		await client.create(document);
+	} catch (e) {
+		if (!(e instanceof Error ? e.message : String(e)).includes("already exists")) throw e;
+	}
+	return `http://localhost:${serverPort}/d/${driveId}`;
+}
+function isPostgresUrl(url) {
+	return url.startsWith("postgresql") || url.startsWith("postgres");
+}
+//#endregion
+export { isPostgresUrl as n, addDefaultDrive as t };
+
+//# sourceMappingURL=utils-DFl0ezBT.mjs.map

package/dist/utils-DFl0ezBT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils-DFl0ezBT.mjs","names":[],"sources":["../src/utils.mts"],"sourcesContent":["import type { IReactorClient } from \"@powerhousedao/reactor\";\nimport type { DocumentDriveDocument } from \"@powerhousedao/shared/document-drive\";\nimport {\n  driveCreateDocument,\n  driveCreateState,\n} from \"@powerhousedao/shared/document-drive\";\nimport type { DriveInput } from \"@powerhousedao/shared/document-drive\";\nimport { generateId } from \"@powerhousedao/shared/document-model\";\n\nexport async function addDefaultDrive(\n  client: IReactorClient,\n  drive: DriveInput,\n  serverPort: number,\n) {\n  let driveId = drive.id;\n  if (!driveId || driveId.length === 0) {\n    driveId = drive.slug;\n  }\n\n  if (!driveId || driveId.length === 0) {\n    throw new Error(\"Invalid Drive Id\");\n  }\n\n  // check if the drive already exists\n  let existingDrive;\n  try {\n    existingDrive = await client.get(driveId);\n  } catch {\n    //\n  }\n\n  // already exists, return the existing drive url\n  if (existingDrive) {\n    return `http://localhost:${serverPort}/d/${driveId}`;\n  }\n\n  const { global } = driveCreateState();\n  const document = driveCreateDocument({\n    global: {\n      ...global,\n      name: drive.global.name,\n      icon: drive.global.icon ?? global.icon,\n    },\n    local: {\n      availableOffline: drive.local?.availableOffline ?? false,\n      sharingType: drive.local?.sharingType ?? \"public\",\n      listeners: drive.local?.listeners ?? [],\n      triggers: drive.local?.triggers ?? [],\n    },\n  });\n\n  if (drive.id && drive.id.length > 0) {\n    document.header.id = drive.id;\n  }\n  if (drive.slug && drive.slug.length > 0) {\n    document.header.slug = drive.slug;\n  }\n  if (drive.global.name) {\n    document.header.name = drive.global.name;\n  }\n  if (drive.preferredEditor) {\n    document.header.meta = { preferredEditor: drive.preferredEditor };\n  }\n\n  try {\n    await client.create(document);\n  } catch (e) {\n    const errorMessage = e instanceof Error ? e.message : String(e);\n    if (!errorMessage.includes(\"already exists\")) {\n      throw e;\n    }\n  }\n\n  return `http://localhost:${serverPort}/d/${driveId}`;\n}\n\nexport function isPostgresUrl(url: string) {\n  return url.startsWith(\"postgresql\") || url.startsWith(\"postgres\");\n}\n"],"mappings":";;;AASA,eAAsB,gBACpB,QACA,OACA,YACA;CACA,IAAI,UAAU,MAAM;AACpB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,WAAU,MAAM;AAGlB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,OAAM,IAAI,MAAM,mBAAmB;CAIrC,IAAI;AACJ,KAAI;AACF,kBAAgB,MAAM,OAAO,IAAI,QAAQ;SACnC;AAKR,KAAI,cACF,QAAO,oBAAoB,WAAW,KAAK;CAG7C,MAAM,EAAE,WAAW,kBAAkB;CACrC,MAAM,WAAW,oBAAoB;EACnC,QAAQ;GACN,GAAG;GACH,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO,QAAQ,OAAO;GACnC;EACD,OAAO;GACL,kBAAkB,MAAM,OAAO,oBAAoB;GACnD,aAAa,MAAM,OAAO,eAAe;GACzC,WAAW,MAAM,OAAO,aAAa,EAAE;GACvC,UAAU,MAAM,OAAO,YAAY,EAAE;GACtC;EACF,CAAC;AAEF,KAAI,MAAM,MAAM,MAAM,GAAG,SAAS,EAChC,UAAS,OAAO,KAAK,MAAM;AAE7B,KAAI,MAAM,QAAQ,MAAM,KAAK,SAAS,EACpC,UAAS,OAAO,OAAO,MAAM;AAE/B,KAAI,MAAM,OAAO,KACf,UAAS,OAAO,OAAO,MAAM,OAAO;AAEtC,KAAI,MAAM,gBACR,UAAS,OAAO,OAAO,EAAE,iBAAiB,MAAM,iBAAiB;AAGnE,KAAI;AACF,QAAM,OAAO,OAAO,SAAS;UACtB,GAAG;AAEV,MAAI,EADiB,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,EAC7C,SAAS,iBAAiB,CAC1C,OAAM;;AAIV,QAAO,oBAAoB,WAAW,KAAK;;AAG7C,SAAgB,cAAc,KAAa;AACzC,QAAO,IAAI,WAAW,aAAa,IAAI,IAAI,WAAW,WAAW"}

package/dist/utils.d.mts

@@ -0,0 +1,9 @@
+import { IReactorClient } from "@powerhousedao/reactor";
+import { DriveInput } from "@powerhousedao/shared/document-drive";
+
+//#region src/utils.d.mts
+declare function addDefaultDrive(client: IReactorClient, drive: DriveInput, serverPort: number): Promise<string>;
+declare function isPostgresUrl(url: string): boolean;
+//#endregion
+export { addDefaultDrive, isPostgresUrl };
+//# sourceMappingURL=utils.d.mts.map

package/dist/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.mts"],"mappings":";;;;iBASsB,eAAA,CACpB,MAAA,EAAQ,cAAA,EACR,KAAA,EAAO,UAAA,EACP,UAAA,WAAkB,OAAA;AAAA,iBAgEJ,aAAA,CAAc,GAAA"}

package/dist/utils.mjs

@@ -0,0 +1,2 @@
+import { n as isPostgresUrl, t as addDefaultDrive } from "./utils-DFl0ezBT.mjs";
+export { addDefaultDrive, isPostgresUrl };

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.0.0-dev.21",
-  "main": "dist/src/index.js",
+  "version": "6.0.0-dev.211",
+  "main": "dist/index.mjs",
   "exports": {
     ".": {
-      "import": "./dist/src/index.js",
-      "types": "./dist/src/index.d.ts"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
     "./server": {
-      "import": "./dist/src/server.js",
-      "types": "./dist/src/server.d.ts"
+      "types": "./dist/server.d.mts",
+      "import": "./dist/server.mjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.mts",
+      "import": "./dist/utils.mjs"
     }
   },
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "bin": {
-    "switchboard": "dist/src/index.js"
+    "switchboard": "dist/index.mjs"
   },
   "repository": {
     "type": "git",
@@ -24,48 +31,56 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "@electric-sql/pglite": "0.2.17",
-    "@openfeature/core": "^1.9.1",
-    "@openfeature/env-var-provider": "^0.3.1",
-    "@openfeature/server-sdk": "^1.19.0",
-    "@powerhousedao/analytics-engine-core": "^0.5.0",
-    "@powerhousedao/analytics-engine-knex": "^0.6.0",
+    "@electric-sql/pglite": "0.3.15",
+    "@openfeature/core": "1.9.1",
+    "@openfeature/env-var-provider": "0.3.1",
+    "@openfeature/server-sdk": "1.19.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.57.2",
+    "@opentelemetry/resources": "^1.29.0",
+    "@opentelemetry/sdk-metrics": "^1.29.0",
     "@pyroscope/nodejs": "^0.4.5",
     "@sentry/node": "^9.6.1",
-    "body-parser": "^1.20.3",
-    "cors": "^2.8.5",
     "dotenv": "^16.4.7",
-    "exponential-backoff": "^3.1.1",
     "express": "^4.21.2",
-    "graphql": "^16.11.0",
-    "kysely": "^0.28.2",
-    "kysely-pglite-dialect": "^1.1.1",
-    "pg": "^8.13.0",
-    "redis": "^4.7.0",
-    "@powerhousedao/config": "6.0.0-dev.21",
-    "@powerhousedao/reactor": "6.0.0-dev.21",
-    "@powerhousedao/reactor-api": "6.0.0-dev.21",
-    "document-drive": "6.0.0-dev.21",
-    "@renown/sdk": "6.0.0-dev.21",
-    "document-model": "6.0.0-dev.21"
+    "kysely": "0.28.16",
+    "kysely-pglite-dialect": "1.2.0",
+    "pg": "8.18.0",
+    "vite": "8.0.8",
+    "@powerhousedao/config": "6.0.0-dev.211",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.0.0-dev.211",
+    "@powerhousedao/reactor": "6.0.0-dev.211",
+    "@powerhousedao/vetra": "6.0.0-dev.211",
+    "@powerhousedao/shared": "6.0.0-dev.211",
+    "@powerhousedao/reactor-api": "6.0.0-dev.211",
+    "@powerhousedao/reactor-attachments": "6.0.0-dev.211",
+    "@renown/sdk": "6.0.0-dev.211",
+    "document-model": "6.0.0-dev.211"
   },
   "devDependencies": {
     "@types/express": "^4.17.25",
-    "@types/node": "^24.6.1",
-    "@types/pg": "^8.11.10",
-    "concurrently": "^9.1.2",
-    "nodemon": "^3.1.9"
+    "@types/node": "25.2.3",
+    "@types/pg": "8.16.0",
+    "tsdown": "0.21.1",
+    "concurrently": "9.2.1",
+    "nodemon": "3.1.11",
+    "react": "19.2.4",
+    "vitest": "4.1.1"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
   },
   "scripts": {
     "tsc": "tsc",
+    "test": "vitest run",
     "lint": "eslint",
-    "build": "pnpm run install-packages",
-    "start": "node dist/src/index.js",
-    "start:profile": "mkdir -p .prof && node --cpu-prof --cpu-prof-dir=.prof dist/src/index.js",
-    "start:profile:bun": "mkdir -p .prof && bun --cpu-prof --cpu-prof-dir=.prof dist/src/index.js",
-    "dev": "concurrently -P 'pnpm -w run tsc --watch' 'nodemon --trace-warnings --watch \"../..\" -e ts,tsx,js,json dist/src/index.js -- {@}' --",
-    "install-packages": "node dist/src/install-packages.js",
-    "migrate": "node dist/src/migrate.js",
-    "migrate:status": "node dist/src/migrate.js status"
+    "build": "tsdown && pnpm run install-packages",
+    "start": "node dist/index.mjs",
+    "start:profile": "mkdir -p .prof && node --cpu-prof --cpu-prof-dir=.prof dist/index.mjs",
+    "start:profile:bun": "mkdir -p .prof && bun --cpu-prof --cpu-prof-dir=.prof dist/index.mjs",
+    "dev": "concurrently -P 'pnpm -w run tsc --watch' 'nodemon --trace-warnings --watch \"../..\" -e ts,tsx,js,json dist/index.mjs -- {@}' --",
+    "install-packages": "node dist/install-packages.mjs",
+    "migrate": "node dist/migrate.mjs",
+    "migrate:status": "node dist/migrate.mjs status"
   }
 }

package/test/attachments/auth.test.ts

@@ -0,0 +1,219 @@
+import type { AuthService } from "@powerhousedao/reactor-api";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { describe, expect, it, vi } from "vitest";
+import { requireAuth, type NodeHandler } from "../../src/attachments/auth.js";
+
+type CapturedRes = ServerResponse & {
+  _headers: Record<string, string>;
+  _body: string;
+  _ended: boolean;
+};
+
+function makeReq(opts: {
+  method?: string;
+  url?: string;
+  headers?: Record<string, string>;
+}): IncomingMessage {
+  return {
+    method: opts.method ?? "POST",
+    url: opts.url ?? "/attachments/reservations/abc",
+    headers: opts.headers ?? {},
+  } as unknown as IncomingMessage;
+}
+
+function makeRes(): CapturedRes {
+  const headers: Record<string, string> = {};
+  let body = "";
+  let ended = false;
+  const res = {
+    statusCode: 200,
+    setHeader(name: string, value: string | number | readonly string[]) {
+      headers[name.toLowerCase()] = String(value);
+    },
+    getHeader(name: string) {
+      return headers[name.toLowerCase()];
+    },
+    end(chunk?: string | Buffer) {
+      if (chunk !== undefined) {
+        body += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      }
+      ended = true;
+    },
+  } as unknown as CapturedRes;
+  Object.defineProperty(res, "_headers", { get: () => headers });
+  Object.defineProperty(res, "_body", { get: () => body });
+  Object.defineProperty(res, "_ended", { get: () => ended });
+  return res;
+}
+
+function makeAuthService(
+  impl: (authorization: string | undefined) => Promise<unknown>,
+): {
+  service: AuthService;
+  spy: ReturnType<typeof vi.fn>;
+} {
+  const spy = vi.fn(
+    impl as (authorization: string | undefined) => Promise<unknown>,
+  );
+  const service = { verifyBearer: spy } as unknown as AuthService;
+  return { service, spy };
+}
+
+describe("requireAuth", () => {
+  it("returns the original handler unchanged when authService is undefined", async () => {
+    const handler: NodeHandler = vi.fn();
+    const wrapped = requireAuth(undefined, handler);
+    expect(wrapped).toBe(handler);
+  });
+
+  it("invokes the handler when authService is undefined (auth disabled path)", async () => {
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(undefined, handler);
+    const req = makeReq({});
+    const res = makeRes();
+    await wrapped(req, res);
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(req, res);
+  });
+
+  it("returns 401 with { error: 'Authentication required' } when Authorization header is missing", async () => {
+    const { service, spy } = makeAuthService(async () => ({
+      user: undefined,
+      admins: [],
+      auth_enabled: true,
+    }));
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(service, handler);
+
+    const res = makeRes();
+    await wrapped(makeReq({ headers: {} }), res);
+
+    expect(res.statusCode).toBe(401);
+    expect(res._headers["content-type"]).toBe("application/json");
+    expect(JSON.parse(res._body)).toEqual({ error: "Authentication required" });
+    expect(handler).not.toHaveBeenCalled();
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards a Response from AuthService (status, content-type, body) for an invalid bearer token", async () => {
+    const { service } = makeAuthService(
+      async () =>
+        new Response(JSON.stringify({ error: "Verification failed" }), {
+          status: 401,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(service, handler);
+
+    const res = makeRes();
+    await wrapped(
+      makeReq({ headers: { authorization: "Bearer bad-token" } }),
+      res,
+    );
+
+    expect(res.statusCode).toBe(401);
+    expect(res._headers["content-type"]).toBe("application/json");
+    expect(JSON.parse(res._body)).toEqual({ error: "Verification failed" });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("forwards a Response with a non-JSON content-type verbatim", async () => {
+    const { service } = makeAuthService(
+      async () =>
+        new Response("nope", {
+          status: 403,
+          headers: { "content-type": "text/plain" },
+        }),
+    );
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(service, handler);
+
+    const res = makeRes();
+    await wrapped(
+      makeReq({ headers: { authorization: "Bearer bad-token" } }),
+      res,
+    );
+
+    expect(res.statusCode).toBe(403);
+    expect(res._headers["content-type"]).toBe("text/plain");
+    expect(res._body).toBe("nope");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("invokes the handler and leaves the response untouched on a valid bearer token", async () => {
+    const { service } = makeAuthService(async () => ({
+      user: { address: "0x123", chainId: 1, networkId: "mainnet" },
+      admins: [],
+      auth_enabled: true,
+    }));
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(service, handler);
+
+    const req = makeReq({
+      headers: { authorization: "Bearer good-token" },
+    });
+    const res = makeRes();
+    await wrapped(req, res);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(req, res);
+    expect(res.statusCode).toBe(200);
+    expect(res._body).toBe("");
+    expect(res._ended).toBe(false);
+    expect(res._headers["content-type"]).toBeUndefined();
+  });
+
+  it("returns 500 with a sanitized body when AuthService throws", async () => {
+    const { service } = makeAuthService(async () => {
+      throw new Error("transient Renown failure: secret-internal-detail");
+    });
+    const handler = vi.fn<NodeHandler>();
+    const wrapped = requireAuth(service, handler);
+
+    const res = makeRes();
+    await wrapped(
+      makeReq({ headers: { authorization: "Bearer good-token" } }),
+      res,
+    );
+
+    expect(res.statusCode).toBe(500);
+    expect(res._headers["content-type"]).toBe("application/json");
+    const parsed = JSON.parse(res._body) as { error: string };
+    expect(parsed.error).toBe("Internal authentication error");
+    expect(res._body).not.toContain("secret-internal-detail");
+    expect(res._body).not.toContain("Renown");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("calls authService.verifyBearer with the incoming authorization header", async () => {
+    const { service, spy } = makeAuthService(async () => ({
+      user: { address: "0x1", chainId: 1, networkId: "mainnet" },
+      admins: [],
+      auth_enabled: true,
+    }));
+    const wrapped = requireAuth(service, vi.fn());
+
+    await wrapped(
+      makeReq({ headers: { authorization: "Bearer t" } }),
+      makeRes(),
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith("Bearer t");
+  });
+
+  it("calls verifyBearer with undefined when no authorization header is present", async () => {
+    const { service, spy } = makeAuthService(async () => ({
+      user: undefined,
+      admins: [],
+      auth_enabled: true,
+    }));
+    const wrapped = requireAuth(service, vi.fn());
+
+    await wrapped(makeReq({ headers: {} }), makeRes());
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(undefined);
+  });
+});

package/test/attachments/index.test.ts

@@ -0,0 +1,119 @@
+import type { API, AuthService } from "@powerhousedao/reactor-api";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { describe, expect, it, vi } from "vitest";
+import { mountAuthenticatedNodeRoute } from "../../src/attachments/mount-auth.js";
+
+type Captured = {
+  method: string;
+  path: string;
+  handler: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    body?: unknown,
+  ) => void | Promise<void>;
+};
+
+function makeFakeApi(authService: AuthService | undefined): {
+  api: Pick<API, "httpAdapter" | "authService">;
+  captured: Captured[];
+} {
+  const captured: Captured[] = [];
+  const api = {
+    httpAdapter: {
+      mountNodeRoute: (
+        method: string,
+        path: string,
+        handler: Captured["handler"],
+      ) => {
+        captured.push({ method, path, handler });
+      },
+    },
+    authService,
+  } as unknown as Pick<API, "httpAdapter" | "authService">;
+  return { api, captured };
+}
+
+function makeReq(headers: Record<string, string> = {}): IncomingMessage {
+  return { method: "POST", url: "/x", headers } as unknown as IncomingMessage;
+}
+
+function makeRes() {
+  const headers: Record<string, string> = {};
+  let body = "";
+  const res = {
+    statusCode: 200,
+    setHeader(name: string, value: string | number | readonly string[]) {
+      headers[name.toLowerCase()] = String(value);
+    },
+    end(chunk?: string | Buffer) {
+      if (chunk !== undefined) {
+        body += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      }
+    },
+  } as unknown as ServerResponse;
+  Object.defineProperty(res, "_headers", { get: () => headers });
+  Object.defineProperty(res, "_body", { get: () => body });
+  return res as ServerResponse & {
+    readonly _headers: Record<string, string>;
+    readonly _body: string;
+  };
+}
+
+describe("mountAuthenticatedNodeRoute", () => {
+  it("wraps the handler with auth enforcement when authService is defined", async () => {
+    const verifyBearer = vi.fn(async () => ({
+      user: undefined,
+      admins: [],
+      auth_enabled: true,
+    }));
+    const authService = { verifyBearer } as unknown as AuthService;
+    const { api, captured } = makeFakeApi(authService);
+    const inner = vi.fn();
+
+    mountAuthenticatedNodeRoute(api, "POST", "/x", inner);
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0].method).toBe("POST");
+    expect(captured[0].path).toBe("/x");
+    // The mounted handler must NOT be the raw inner handler — it must be wrapped.
+    expect(captured[0].handler).not.toBe(inner);
+
+    const res = makeRes();
+    await captured[0].handler(makeReq(), res);
+
+    expect(verifyBearer).toHaveBeenCalledTimes(1);
+    expect(inner).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(JSON.parse(res._body)).toEqual({ error: "Authentication required" });
+  });
+
+  it("invokes the inner handler when verifyBearer returns a valid user", async () => {
+    const verifyBearer = vi.fn(async () => ({
+      user: { address: "0x1", chainId: 1, networkId: "mainnet" },
+      admins: [],
+      auth_enabled: true,
+    }));
+    const authService = { verifyBearer } as unknown as AuthService;
+    const { api, captured } = makeFakeApi(authService);
+    const inner = vi.fn();
+
+    mountAuthenticatedNodeRoute(api, "GET", "/x", inner);
+
+    await captured[0].handler(
+      makeReq({ authorization: "Bearer t" }),
+      makeRes(),
+    );
+
+    expect(inner).toHaveBeenCalledTimes(1);
+  });
+
+  it("mounts the inner handler unwrapped when authService is undefined", () => {
+    const { api, captured } = makeFakeApi(undefined);
+    const inner = vi.fn();
+
+    mountAuthenticatedNodeRoute(api, "PUT", "/x", inner);
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0].handler).toBe(inner);
+  });
+});