@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/http/routes/ipc-runtime-proxy.test.ts

@@ -46,6 +46,9 @@ const ipcCallAssistantMock = mock(() =>
       endpoint: "apps/:appId/dist/:filename",
       method: "GET",
     },
+    // Policy-enforced routes (policies resolved gateway-side)
+    { operationId: "settings_get", endpoint: "settings", method: "GET" },
+    { operationId: "calls_start", endpoint: "calls/start", method: "POST" },
   ]),
 );
 
@@ -70,13 +73,32 @@ const validateEdgeTokenMock = mock(
   (
     _token: string,
   ):
-    | { ok: true; claims: Record<string, string> }
+    | { ok: true; claims: Record<string, string | number> }
     | { ok: false; reason: string } => ({
     ok: true,
     claims: { sub: "test", scope_profile: "test" },
   }),
 );
 
+// Mock gateway-side policy registry
+const testPolicies: Record<
+  string,
+  { requiredScopes: string[]; allowedPrincipalTypes: string[] }
+> = {
+  settings_get: {
+    requiredScopes: ["settings.read"],
+    allowedPrincipalTypes: ["actor", "svc_gateway"],
+  },
+  calls_start: {
+    requiredScopes: ["calls.write"],
+    allowedPrincipalTypes: ["actor"],
+  },
+};
+
+mock.module("../../auth/ipc-route-policy.js", () => ({
+  getIpcRoutePolicy: (operationId: string) => testPolicies[operationId],
+}));
+
 mock.module("../../auth/token-exchange.js", () => ({
   validateEdgeToken: validateEdgeTokenMock,
 }));
@@ -318,3 +340,177 @@ describe("tryIpcProxy", () => {
     expect(params.queryParams).toEqual({ limit: "10", offset: "5" });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests: policy enforcement
+// ---------------------------------------------------------------------------
+
+describe("policy enforcement", () => {
+  beforeEach(() => {
+    ipcCallAssistantStrictMock.mockReset();
+    ipcCallAssistantStrictMock.mockImplementation(() =>
+      Promise.resolve({ ok: true }),
+    );
+    validateEdgeTokenMock.mockReset();
+  });
+
+  test("allows request when token has required scope", async () => {
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "actor:asst_1:user_1",
+        scope_profile: "actor_client_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/settings", {
+      headers: { authorization: "Bearer valid" },
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(200);
+  });
+
+  test("returns 403 when token is missing required scope", async () => {
+    // ui_page_v1 only has settings.read — not calls.write
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "actor:asst_1:user_1",
+        scope_profile: "ui_page_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/calls/start", {
+      method: "POST",
+      headers: {
+        authorization: "Bearer valid",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({}),
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(403);
+
+    const body = (await result!.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("FORBIDDEN");
+  });
+
+  test("returns 403 when principal type is not allowed", async () => {
+    // calls/start only allows "actor" — svc_daemon should be denied.
+    // Use actor_client_v1 so it has the required calls.write scope;
+    // the denial should come from the principal type check, not scope.
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "svc:daemon:asst_1",
+        scope_profile: "actor_client_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/calls/start", {
+      method: "POST",
+      headers: {
+        authorization: "Bearer valid",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({}),
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(403);
+
+    const body = (await result!.json()) as { error: { message: string } };
+    expect(body.error.message).toContain("Principal type");
+  });
+
+  test("skips policy enforcement when auth is disabled", async () => {
+    // Policy-enforced route, no auth required → should pass
+    const config = makeConfig({ runtimeProxyRequireAuth: false });
+    const req = makeRequest("/v1/settings");
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(200);
+  });
+
+  test("allows policy-enforced route when principal type matches", async () => {
+    // settings allows both "actor" and "svc_gateway"
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "svc:gateway:asst_1",
+        scope_profile: "gateway_service_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/settings", {
+      headers: { authorization: "Bearer valid" },
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(200);
+  });
+
+  test("no-policy routes are unaffected by auth context", async () => {
+    // health has no policy — should always pass when authed
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "actor:asst_1:user_1",
+        scope_profile: "ui_page_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/health", {
+      headers: { authorization: "Bearer valid" },
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(200);
+  });
+
+  test("returns 403 when sub claim is malformed", async () => {
+    // A valid JWT with a garbage sub should be denied, not silently bypass
+    validateEdgeTokenMock.mockImplementation(() => ({
+      ok: true,
+      claims: {
+        iss: "vellum-auth",
+        aud: "vellum-gateway",
+        sub: "garbage",
+        scope_profile: "actor_client_v1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        policy_epoch: 1,
+      },
+    }));
+
+    const config = makeConfig({ runtimeProxyRequireAuth: true });
+    const req = makeRequest("/v1/settings", {
+      headers: { authorization: "Bearer valid" },
+    });
+    const result = await tryIpcProxy(req, config);
+    expect(result!.status).toBe(403);
+
+    const body = (await result!.json()) as { error: { message: string } };
+    expect(body.error.message).toContain("Unable to determine principal type");
+  });
+});

package/src/http/routes/ipc-runtime-proxy.ts

@@ -12,7 +12,14 @@
  * IPC, and converts the result back into an HTTP Response.
  */
 
+import {
+  getIpcRoutePolicy,
+  type IpcRoutePolicy,
+} from "../../auth/ipc-route-policy.js";
+import { resolveScopeProfile } from "../../auth/scopes.js";
+import { parseSub } from "../../auth/subject.js";
 import { validateEdgeToken } from "../../auth/token-exchange.js";
+import type { TokenClaims } from "../../auth/types.js";
 import type { GatewayConfig } from "../../config.js";
 import {
   ipcCallAssistantStrict,
@@ -47,6 +54,8 @@ export async function tryIpcProxy(
   }
 
   // --- Auth: replicate the gateway's JWT validation -----------------------
+  let claims: TokenClaims | undefined;
+
   if (config.runtimeProxyRequireAuth && req.method !== "OPTIONS") {
     const authHeader = req.headers.get("authorization");
     if (!authHeader || !authHeader.toLowerCase().startsWith("bearer ")) {
@@ -65,6 +74,7 @@ export async function tryIpcProxy(
       );
       return Response.json({ error: "Unauthorized" }, { status: 401 });
     }
+    claims = result.claims;
   }
 
   // --- Route matching -----------------------------------------------------
@@ -87,6 +97,11 @@ export async function tryIpcProxy(
     );
   }
 
+  // --- Policy enforcement --------------------------------------------------
+  const policy = getIpcRoutePolicy(match.operationId);
+  const policyDenied = enforceRoutePolicy(policy, claims, pathname);
+  if (policyDenied) return policyDenied;
+
   const start = performance.now();
 
   // --- Build structured IPC params ----------------------------------------
@@ -197,3 +212,83 @@ export async function tryIpcProxy(
     return Response.json({ error: "Internal Server Error" }, { status: 500 });
   }
 }
+
+// ---------------------------------------------------------------------------
+// Policy enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforce the route's scope/principal policy against the caller's token.
+ * Returns a 403 Response when denied, null when allowed.
+ */
+function enforceRoutePolicy(
+  policy: IpcRoutePolicy | undefined,
+  claims: TokenClaims | undefined,
+  path: string,
+): Response | null {
+  if (!policy) return null;
+
+  // When auth is disabled (dev mode), no claims → skip enforcement.
+  if (!claims) return null;
+
+  // Check principal type.
+  if (policy.allowedPrincipalTypes.length > 0) {
+    const subResult = parseSub(claims.sub);
+    if (!subResult.ok) {
+      log.warn(
+        { path, sub: claims.sub, reason: subResult.reason },
+        "IPC proxy policy denied: failed to parse sub claim",
+      );
+      return Response.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: "Unable to determine principal type",
+          },
+        },
+        { status: 403 },
+      );
+    }
+    if (!policy.allowedPrincipalTypes.includes(subResult.principalType)) {
+      log.warn(
+        {
+          path,
+          principalType: subResult.principalType,
+          allowed: policy.allowedPrincipalTypes,
+        },
+        "IPC proxy policy denied: principal type not allowed",
+      );
+      return Response.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: "Principal type not permitted for this endpoint",
+          },
+        },
+        { status: 403 },
+      );
+    }
+  }
+
+  // Check required scopes.
+  const scopes = resolveScopeProfile(claims.scope_profile);
+  for (const required of policy.requiredScopes) {
+    if (!scopes.has(required)) {
+      log.warn(
+        { path, missingScope: required },
+        "IPC proxy policy denied: missing required scope",
+      );
+      return Response.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: `Missing required scope: ${required}`,
+          },
+        },
+        { status: 403 },
+      );
+    }
+  }
+
+  return null;
+}

package/src/http/routes/log-export.test.ts

@@ -110,7 +110,6 @@ const baseConfig: GatewayConfig = {
   routingEntries: [],
   runtimeInitialBackoffMs: 500,
   runtimeMaxRetries: 2,
-  runtimeProxyEnabled: false,
   runtimeProxyRequireAuth: true,
   runtimeTimeoutMs: 30000,
   shutdownDrainMs: 5000,

package/src/http/routes/log-tail.test.ts

@@ -0,0 +1,336 @@
+/**
+ * Tests for the gateway log tail handler.
+ *
+ * Verifies:
+ * - Returns empty result when logFile.dir is undefined
+ * - Returns empty result when dir path doesn't exist
+ * - Returns empty result when no files match the log pattern
+ * - Returns last N entries in chronological order
+ * - Filters by minimum log level
+ * - Filters by module
+ * - Skips malformed JSON lines
+ * - Sets truncated: true when more entries exist than n
+ * - Sets truncated: false when fewer entries exist than n
+ * - Spans multiple log files for multi-day queries
+ * - Clamps n=1001 to 1000
+ * - Returns 400 for invalid level param
+ * - Handles filesystem errors gracefully
+ */
+
+import { describe, test, expect, afterEach, mock } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { GatewayConfig } from "../../config.js";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be registered before importing the handler
+// ---------------------------------------------------------------------------
+
+mock.module("../../logger.js", () => {
+  const noop = () => {};
+  const noopLogger = {
+    info: noop,
+    warn: noop,
+    error: noop,
+    debug: noop,
+    trace: noop,
+    fatal: noop,
+    child: () => noopLogger,
+  };
+  return {
+    getLogger: () => noopLogger,
+    initLogger: noop,
+    LOG_FILE_PATTERN: /^gateway-(\d{4}-\d{2}-\d{2})\.log$/,
+  };
+});
+
+// Import handler after mocks
+const { createLogTailHandler } = await import("./log-tail.js");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let tmpDir: string;
+
+function makeReq(url: string): Request {
+  return new Request(url);
+}
+
+function makeConfig(dir: string | undefined): GatewayConfig {
+  return {
+    assistantRuntimeBaseUrl: "http://localhost:7821",
+    defaultAssistantId: undefined,
+    gatewayInternalBaseUrl: "http://127.0.0.1:7830",
+    logFile: { dir, retentionDays: 30 },
+    maxAttachmentBytes: {
+      telegram: 20 * 1024 * 1024,
+      slack: 100 * 1024 * 1024,
+      whatsapp: 16 * 1024 * 1024,
+      default: 100 * 1024 * 1024,
+    },
+    maxAttachmentConcurrency: 3,
+    maxWebhookPayloadBytes: 1024 * 1024,
+    port: 7830,
+    routingEntries: [],
+    runtimeInitialBackoffMs: 500,
+    runtimeMaxRetries: 2,
+    runtimeProxyRequireAuth: true,
+    runtimeTimeoutMs: 30000,
+    shutdownDrainMs: 5000,
+    unmappedPolicy: "default",
+    trustProxy: false,
+  } as GatewayConfig;
+}
+
+function makeLogLine(level: number, msg: string, extras?: Record<string, unknown>): string {
+  return JSON.stringify({ level, msg, time: Date.now(), ...extras });
+}
+
+afterEach(() => {
+  if (tmpDir) {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("log-tail handler", () => {
+  test("config.logFile.dir is undefined → returns { lines: [], truncated: false }", async () => {
+    const config = makeConfig(undefined);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail"));
+    const body = await res.json();
+    expect(body).toEqual({ lines: [], truncated: false });
+  });
+
+  test("dir path doesn't exist → returns { lines: [], truncated: false }", async () => {
+    const config = makeConfig("/nonexistent/path/that/does/not/exist");
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail"));
+    const body = await res.json();
+    expect(body).toEqual({ lines: [], truncated: false });
+  });
+
+  test("dir exists but no files matching pattern → returns { lines: [], truncated: false }", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+    writeFileSync(join(tmpDir, "other.log"), "some content\n");
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail"));
+    const body = await res.json();
+    expect(body).toEqual({ lines: [], truncated: false });
+  });
+
+  test("single file with 5 entries, n=3 → returns last 3 in chronological order, truncated: true", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      makeLogLine(30, "entry 1"),
+      makeLogLine(30, "entry 2"),
+      makeLogLine(30, "entry 3"),
+      makeLogLine(30, "entry 4"),
+      makeLogLine(30, "entry 5"),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?n=3"));
+    const body = await res.json() as { lines: { msg: string }[]; truncated: boolean };
+
+    expect(body.truncated).toBe(true);
+    expect(body.lines).toHaveLength(3);
+    // Chronological order: entries 3, 4, 5
+    expect(body.lines[0].msg).toBe("entry 3");
+    expect(body.lines[1].msg).toBe("entry 4");
+    expect(body.lines[2].msg).toBe("entry 5");
+  });
+
+  test("level=error query param filters to levels >= 50", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      makeLogLine(20, "debug msg"),
+      makeLogLine(30, "info msg"),
+      makeLogLine(50, "error msg"),
+      makeLogLine(60, "fatal msg"),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?level=error"));
+    const body = await res.json() as { lines: { msg: string }[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(2);
+    const msgs = body.lines.map((l) => l.msg);
+    expect(msgs).toContain("error msg");
+    expect(msgs).toContain("fatal msg");
+    expect(msgs).not.toContain("debug msg");
+    expect(msgs).not.toContain("info msg");
+  });
+
+  test("module=mcp query param: only mcp entries returned", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      makeLogLine(30, "mcp message", { module: "mcp" }),
+      makeLogLine(30, "trust message", { module: "trust" }),
+      makeLogLine(30, "another mcp", { module: "mcp" }),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?module=mcp"));
+    const body = await res.json() as { lines: { msg: string; module: string }[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(2);
+    for (const line of body.lines) {
+      expect(line.module).toBe("mcp");
+    }
+  });
+
+  test("malformed JSON lines are silently skipped", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      "not json",
+      makeLogLine(30, "valid entry"),
+      "{broken json",
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail"));
+    const body = await res.json() as { lines: { msg: string }[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(1);
+    expect(body.lines[0].msg).toBe("valid entry");
+  });
+
+  test("n=2 with 4 matching entries → truncated: true", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      makeLogLine(30, "entry 1"),
+      makeLogLine(30, "entry 2"),
+      makeLogLine(30, "entry 3"),
+      makeLogLine(30, "entry 4"),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?n=2"));
+    const body = await res.json() as { lines: unknown[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(2);
+    expect(body.truncated).toBe(true);
+  });
+
+  test("n=10 with 3 matching entries → truncated: false", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const lines = [
+      makeLogLine(30, "entry 1"),
+      makeLogLine(30, "entry 2"),
+      makeLogLine(30, "entry 3"),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), lines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?n=10"));
+    const body = await res.json() as { lines: unknown[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(3);
+    expect(body.truncated).toBe(false);
+  });
+
+  test("multi-day: spans two files, returns 3 in chronological order", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    // Yesterday file: 3 entries
+    const yesterdayLines = [
+      makeLogLine(30, "yesterday 1"),
+      makeLogLine(30, "yesterday 2"),
+      makeLogLine(30, "yesterday 3"),
+    ];
+    writeFileSync(join(tmpDir, "gateway-2026-05-03.log"), yesterdayLines.join("\n"));
+
+    // Today file: 1 entry
+    const todayLines = [makeLogLine(30, "today 1")];
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), todayLines.join("\n"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?n=3"));
+    const body = await res.json() as { lines: { msg: string }[]; truncated: boolean };
+
+    expect(body.lines).toHaveLength(3);
+    // Should span both files — newest-first collection, then reversed to chronological
+    // With n=3, we want the 3 most recent: yesterday 3, yesterday 3... wait:
+    // Files sorted newest-first: today (1 entry), yesterday (3 entries)
+    // Collect reverse order: today 1, yesterday 3, yesterday 2 → stop at n+1=4
+    // Actually we collect up to n+1=4 entries before stopping
+    // today has 1 entry, then yesterday has 3 entries → total 4 → break after 4
+    // truncated = 4 > 3 = true? Let's check the logic...
+    // Actually we collect until collected.length >= n+1, so we need n+1=4 entries
+    // today: 1 entry (total=1), yesterday: yesterday3(total=2), yesterday2(total=3), yesterday1(total=4) → break
+    // truncated = 4 > 3 = true
+    // lines = collected.slice(0,3) = [today1, yesterday3, yesterday2].reverse() = [yesterday2, yesterday3, today1]
+    // Chronological: yesterday 2, yesterday 3, today 1
+    expect(body.lines[0].msg).toBe("yesterday 2");
+    expect(body.lines[1].msg).toBe("yesterday 3");
+    expect(body.lines[2].msg).toBe("today 1");
+  });
+
+  test("n=1001 in querystring → returns successfully (clamped to 1000)", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    writeFileSync(join(tmpDir, "gateway-2026-05-04.log"), makeLogLine(30, "entry"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?n=1001"));
+
+    expect(res.status).toBe(200);
+    const body = await res.json() as { lines: unknown[]; truncated: boolean };
+    expect(body.lines).toHaveLength(1);
+  });
+
+  test("invalid level=INVALID → response status 400", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+
+    const config = makeConfig(tmpDir);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail?level=INVALID"));
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toBe("Invalid level");
+  });
+
+  test("filesystem error: config.logFile.dir is a file path not a dir → returns gracefully", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gw-log-tail-test-"));
+    const filePath = join(tmpDir, "not-a-directory.txt");
+    writeFileSync(filePath, "I am a file");
+
+    // Point dir at a file path — readdirSync will throw ENOTDIR
+    const config = makeConfig(filePath);
+    const handler = createLogTailHandler(config);
+    const res = await handler(makeReq("http://localhost:7830/v1/logs/tail"));
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ lines: [], truncated: false });
+  });
+});