@tulipes/cli 0.1.1 → 0.2.0-rc.1

package/templates/app/modules/security/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@app/security",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "sys",
+    "priority": 10,
+    "dependsOn": [
+      "core"
+    ]
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "cors": "^2",
+    "express": "^5",
+    "helmet": "^8",
+    "ioredis": "^5",
+    "ipaddr.js": "^2.2.0",
+    "pino-http": "^10"
+  },
+  "devDependencies": {
+    "@types/cors": "^2"
+  }
+}

package/templates/app/modules/security/routes/security.routes.ts

@@ -0,0 +1,42 @@
+import express from "express";
+import cors from "cors";
+import helmet from "helmet";
+import { pinoHttp } from "pino-http";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { lazy, logger } from "@app/core";
+
+import { corsOptions, helmetOptions } from "../helpers/hardening.ts";
+import { trustedProxies } from "../helpers/proxy.ts";
+import { configuredRateLimits } from "../helpers/rate-limit.ts";
+
+/**
+ * Every piece here is configured from `ctx.config.security`, which is live:
+ * helmet, CORS and the body parser are built on each request from the
+ * current values (cheap, and a write lands at once), the proxy policy is
+ * set here and again by module.config's onChange, and the rate limiter is
+ * rebuilt there, so the handlers below always delegate to the current set.
+ * The logger reads the environment, which inspection does not resolve, so
+ * it is built on its first request.
+ */
+export default function securityRoutes(ctx: BackendCtx): void {
+  const { app, Environment, mode, config } = ctx;
+  const prefix = String(config.api?.prefix ?? "");
+  const security = () => config.security!;
+
+  app.set("trust proxy", trustedProxies(security().trustProxyCidrs));
+  app.use((req, res, next) => helmet(helmetOptions(security()))(req, res, next));
+  app.use((req, res, next) => cors(corsOptions(security()))(req, res, next));
+  app.use(lazy(() => pinoHttp({
+    logger: logger(Environment, mode),
+    customLogLevel: (_req, res, err) =>
+      err || res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info",
+    genReqId: (_req, res) => String(res.getHeader("X-Request-Id") ?? ""),
+    serializers: {
+      req: (req: { method: string; url: string }) => ({ method: req.method, url: req.url }),
+      res: (res: { statusCode: number }) => ({ status: res.statusCode }),
+    },
+  })));
+  app.use(`${prefix}/auth`, (req, res, next) => configuredRateLimits(ctx).auth(req, res, next));
+  app.use([`${prefix}/config`, `${prefix}/settings`], (req, res, next) => configuredRateLimits(ctx).config(req, res, next));
+  app.use((req, res, next) => express.json({ limit: security().bodyLimit })(req, res, next));
+}

package/templates/app/modules/security/tests/security.test.ts

@@ -0,0 +1,174 @@
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { afterAll, beforeAll, expect, test, vi } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { useTestApp } from "@tulipes/testing";
+
+import { testEnv, testSettings } from "../../../tests/support.ts";
+
+const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
+const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+
+const tokens = z.object({
+  data: z.object({ access_token: z.string(), refresh_token: z.string() }),
+});
+
+async function post(path: string, body: unknown, token?: string) {
+  return fetch(app.base + path, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(token ? { authorization: "Bearer " + token } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+async function account() {
+  const credentials = {
+    email: randomBytes(12).toString("hex") + "@example.test",
+    password: randomBytes(24).toString("hex"),
+  };
+
+  const response = await post("/api/v1/auth/register", credentials);
+
+  expect(response.status).toBe(201);
+
+  const body = await response.json();
+
+  const { user } = z
+    .object({ data: z.object({ user: z.object({ id: z.string() }) }) })
+    .parse(body).data;
+
+  return { ...tokens.parse(body).data, ...credentials, userId: user.id };
+}
+
+async function get(path: string, token: string) {
+  return fetch(app.base + path, { headers: { authorization: "Bearer " + token } });
+}
+
+async function sysadmin() {
+  const user = await account();
+
+  await app.handle.ctx
+    .models!.get("User")
+    .updateOne({ _id: user.userId }, { role: "sysadmin" });
+
+  return user;
+}
+
+test("CORS permits explicit Bearer headers without enabling cookie credentials", async () => {
+  const origin = "https://console.example.test";
+  const endpoint = app.base + "/api/v1/auth/me";
+
+  const preflight = await fetch(endpoint, {
+    method: "OPTIONS",
+    headers: {
+      origin,
+      "access-control-request-method": "GET",
+      "access-control-request-headers": "authorization",
+    },
+  });
+
+  expect(preflight.status).toBe(204);
+  expect(preflight.headers.get("access-control-allow-origin")).toBe(origin);
+
+  expect(preflight.headers.get("access-control-allow-headers")).toBe(
+    "authorization",
+  );
+
+  expect(preflight.headers.has("access-control-allow-credentials")).toBe(false);
+
+  const initial = await account();
+
+  const allowed = await fetch(endpoint, {
+    headers: { origin, authorization: "Bearer " + initial.access_token },
+  });
+
+  expect(allowed.status).toBe(200);
+  expect(allowed.headers.get("access-control-allow-origin")).toBe(origin);
+  expect(allowed.headers.has("access-control-allow-credentials")).toBe(false);
+
+  // Node does not enforce CORS. This proves CORS is not server authorization:
+  // a valid Bearer token still works, while the origin gets no read permission.
+  const unlisted = await fetch(endpoint, {
+    headers: {
+      origin: "https://unlisted.example.test",
+      authorization: "Bearer " + initial.access_token,
+    },
+  });
+
+  expect(unlisted.status).toBe(200);
+  expect(unlisted.headers.has("access-control-allow-origin")).toBe(false);
+});
+
+test("configured proxy trust supplies the same client IP to sessions and durable audits", async () => {
+  const user = await sysadmin();
+  const headers = { "X-Forwarded-For": "203.0.113.200, 198.51.100.19" };
+
+  const login = await fetch(app.base + "/api/v1/auth/login", {
+    method: "POST",
+    headers: { ...headers, "content-type": "application/json" },
+    body: JSON.stringify({ email: user.email, password: user.password }),
+  });
+
+  expect(login.status).toBe(200);
+
+  const pair = tokens.parse(await login.json()).data;
+  const identity = await get("/api/v1/auth/me", pair.access_token);
+
+  expect(await identity.json()).toMatchObject({
+    data: { session: { ip: "198.51.100.19" } },
+  });
+
+  const changed = await fetch(app.base + "/api/v1/config/hello", {
+    method: "PATCH",
+    headers: { ...headers, "content-type": "application/json", authorization: "Bearer " + pair.access_token },
+    body: JSON.stringify({ values: { greeting: "Hello" } }),
+  });
+
+  expect(changed.status).toBe(200);
+
+  expect(
+    await app.handle.ctx
+      .models!.get("ConfigAudit")
+      .findOne({ actor: user.userId })
+      .lean(),
+  ).toMatchObject({ ip: "198.51.100.19", module: "hello", keys: ["greeting"] });
+});
+
+test.each(["auth/login", "config"])(
+  "%s limits attempts before parsing or authentication",
+  async (path) => {
+    const responses = await Promise.all(
+      Array.from({ length: 201 }, (_, index) =>
+        fetch(app.base + "/api/v1/" + path, {
+          method: path.startsWith("auth") ? "POST" : "GET",
+          headers: {
+            "X-Forwarded-For":
+              "203.0.113." + ((index % 250) + 1) + ", 198.51.100.88",
+            "content-type": "application/json",
+          },
+          ...(path.startsWith("auth") ? { body: "{" } : {}),
+        }),
+      ),
+    );
+
+    expect(
+      responses.filter((response) => response.status === 429),
+    ).toHaveLength(1);
+
+    const blocked = responses.find((response) => response.status === 429)!;
+
+    expect(Number(blocked.headers.get("retry-after"))).toBeGreaterThan(0);
+
+    expect(await blocked.json()).toMatchObject({
+      success: false,
+      errors: [{ code: "TOO_MANY_REQUESTS" }],
+    });
+
+    expect((await fetch(app.base + "/api/v1/hello")).status).toBe(200);
+  },
+);

package/templates/app/modules/settings/bootstrap/log-streams.bootstrap.ts

@@ -0,0 +1,12 @@
+import type { RuntimeCtx } from "@tulipes/core/boot";
+
+import { configuredLogStreams } from "../helpers/log-stream.ts";
+
+/**
+ * An open log stream is a response that never ends on its own. `ctx.signal`
+ * aborts the moment shutdown begins, before HTTP stops accepting, so the
+ * streams end while the server is still draining ordinary requests.
+ */
+export default function logStreams({ Environment, signal }: RuntimeCtx): void {
+  signal.addEventListener("abort", () => configuredLogStreams(Environment).drain(), { once: true });
+}

package/templates/app/modules/settings/controllers/settings.controllers.ts

@@ -0,0 +1,58 @@
+import { createAccessCheck } from "@app/auth";
+import { LOG_FILES } from "@app/core";
+import type { Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+import { configuredLogStreams, type LogStreams } from "../helpers/log-stream.ts";
+
+/**
+ * A live view of the logs — the one thing an operator needs from the
+ * running process that the console (the `config` module) cannot give
+ * them. Reachable only by `sysadmin` — see module.acl.ts — and re-checked
+ * while the stream is open, since a stream outlives the request that
+ * opened it.
+ */
+export class SettingsController {
+  readonly #logStreams: LogStreams;
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+
+    this.#ctx = ctx;
+    this.#logStreams = configuredLogStreams(ctx.Environment);
+  }
+
+  logStream(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      if (!Boolean(this.#ctx.Environment.get("LOG_FILE"))) {
+        throw new HttpError(409, "fileLoggingDisabled", {
+          code: "FILE_LOGGING_DISABLED",
+          defaultMessage: "LOG_FILE is off — there are no log files to stream",
+        });
+      }
+
+      const which = req.query.process === "worker" ? "worker" : "backend";
+      const level =
+        typeof req.query.level === "string" ? req.query.level : undefined;
+      const tail = Math.min(Number(req.query.tail ?? 200) || 0, 1000);
+
+      const session = req.auth.session;
+      await this.#logStreams.open(res, {
+        authorize: createAccessCheck(this.#ctx, req.auth, "settings:logs"),
+        userId: req.auth.user ? String(req.auth.user._id) : "",
+        expiresAt: session
+          ? Math.min(
+              session.access_expires_at.getTime(),
+              session.expires_at.getTime(),
+            )
+          : 0,
+        dir: String(this.#ctx.Environment.get("LOG_DIR")),
+        prefix: `${LOG_FILES.basename}-${which}`,
+        process: which,
+        tail,
+        ...(level ? { level } : {}),
+      });
+    };
+  }
+}

package/templates/app/modules/settings/helpers/access-lease.ts

@@ -0,0 +1,99 @@
+import { HttpError } from "@tulipes/core/http";
+
+/** Recheck one authorization at a time and expire permission from its start time. */
+export class AccessLease {
+  #closed = false;
+  #expiresAt = 0;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  #pending: Promise<boolean> | undefined;
+  #abort: AbortController | undefined;
+
+  readonly #authorize: (signal: AbortSignal) => Promise<boolean>;
+  readonly #intervalMs: number;
+  readonly #timeoutMs: number;
+  readonly #onInvalid: () => void;
+
+  constructor(
+    authorize: (signal: AbortSignal) => Promise<boolean>,
+    intervalMs: number,
+    timeoutMs: number,
+    onInvalid: () => void,
+  ) {
+    this.#authorize = authorize;
+    this.#intervalMs = intervalMs;
+    this.#timeoutMs = timeoutMs;
+    this.#onInvalid = onInvalid;
+  }
+
+  get valid(): boolean {
+    return !this.#closed && Date.now() < this.#expiresAt;
+  }
+
+  async start(): Promise<void> {
+    await this.#check();
+  }
+
+  /** Keep capacity reserved until even an uncooperative pending check settles. */
+  async close(): Promise<void> {
+    this.#closed = true;
+    clearTimeout(this.#timer);
+    this.#abort?.abort();
+    await this.#pending?.catch(() => {});
+  }
+
+  async #check(): Promise<void> {
+    if (this.#closed) return;
+
+    const started = Date.now();
+    const deadline = Math.min(
+      this.#expiresAt || Infinity,
+      started + this.#timeoutMs,
+    );
+    const abort = new AbortController();
+    this.#abort = abort;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let cancelled: () => void = () => {};
+
+    // The race bounds the response wait; close() also tracks the underlying work.
+    // Abort stops cooperative callbacks but is not proof a driver query stopped.
+    this.#pending = Promise.resolve().then(() => this.#authorize(abort.signal));
+    const stopped = new Promise<never>((_resolve, reject) => {
+      cancelled = () => reject(new Error("Authorization check stopped"));
+      abort.signal.addEventListener("abort", cancelled, { once: true });
+      timer = setTimeout(() => abort.abort(), Math.max(0, deadline - Date.now()));
+      timer.unref();
+    });
+
+    try {
+      const allowed = await Promise.race([this.#pending, stopped]);
+      if (this.#closed) return;
+
+      if (Date.now() >= deadline) throw new Error("Authorization check expired");
+      if (!allowed) throw new HttpError(403, "forbidden");
+
+      // A slow successful query must not extend a stale decision's lifetime.
+      this.#expiresAt = started + this.#intervalMs + this.#timeoutMs;
+      this.#timer = setTimeout(() => {
+        if (!this.valid) {
+          this.#onInvalid();
+          return;
+        }
+
+        void this.#check().catch(() => this.#onInvalid());
+      }, Math.max(0, started + this.#intervalMs - Date.now()));
+      this.#timer.unref();
+    } catch (error) {
+      if (this.#closed) return;
+      if (error instanceof HttpError) throw error;
+
+      throw new HttpError(503, "streamAuthorizationUnavailable", {
+        code: "STREAM_AUTHORIZATION_UNAVAILABLE",
+        defaultMessage: "Log stream authorization could not be verified",
+      });
+    } finally {
+      clearTimeout(timer);
+      abort.signal.removeEventListener("abort", cancelled);
+    }
+  }
+}

package/templates/app/modules/settings/helpers/log-stream.ts

@@ -0,0 +1,272 @@
+import type { Response } from "express";
+import type { Environment } from "@tulipes/core/env";
+import { HttpError } from "@tulipes/core/http";
+import { AccessLease } from "./access-lease.ts";
+import { tailLogs, type Tail } from "./log-tail.ts";
+
+export const LOG_STREAM_LIMITS = Object.freeze({
+  connections: 4,
+  perUser: 2,
+  durationMs: 60_000,
+  outputBytes: 1024 * 1024,
+  bufferBytes: 64 * 1024,
+  heartbeatMs: 15_000,
+  authorizationIntervalMs: 1000,
+  authorizationTimeoutMs: 1000,
+});
+
+type StreamLimits = { [K in keyof typeof LOG_STREAM_LIMITS]: number };
+
+interface StreamOptions {
+  authorize: (signal: AbortSignal) => Promise<boolean>;
+  userId: string;
+  expiresAt: number;
+  dir: string;
+  prefix: string;
+  process: "backend" | "worker";
+  tail: number;
+  level?: string;
+}
+
+const LEVELS: Record<string, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+const instances = new WeakMap<Environment, LogStreams>();
+
+/** Keep the stopped instance until the boot is collected; late requests cannot reopen it. */
+export function configuredLogStreams(environment: Environment): LogStreams {
+  let streams = instances.get(environment);
+  if (!streams) {
+    streams = new LogStreams();
+    instances.set(environment, streams);
+  }
+  return streams;
+}
+
+/** One boot owns its slots. Replicas each enforce this local resource cap. */
+export class LogStreams {
+  readonly #active = new Map<string, number>();
+  readonly #closeStreams = new Set<() => void>();
+  #draining = false;
+  #count = 0;
+  readonly #limits: StreamLimits;
+
+  constructor(limits: Partial<StreamLimits> = {}) {
+    this.#limits = { ...LOG_STREAM_LIMITS, ...limits };
+
+    if (
+      Object.values(this.#limits).some(
+        (value) =>
+          !Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647,
+      )
+    ) {
+      throw new Error(
+        "Log stream limits must be positive integers no greater than 2147483647",
+      );
+    }
+  }
+
+  /** Stop admission and output now; never wait for an uncooperative authorization query. */
+  drain(): void {
+    this.#draining = true;
+    for (const close of this.#closeStreams) close();
+  }
+
+  async open(res: Response, options: StreamOptions): Promise<void> {
+    const unavailable = () => new HttpError(503, "logStreamsDraining", {
+      code: "LOG_STREAMS_DRAINING",
+      defaultMessage: "Log streams are unavailable during shutdown",
+    });
+    if (this.#draining) throw unavailable();
+    // The credential's expiry is absolute; the stream's own duration starts
+    // once it is ready, so a slow authorization round trip or file open cannot
+    // eat into it and turn a valid credential into a refusal.
+    let expiresAt = options.expiresAt;
+    if (!options.userId || !Number.isFinite(expiresAt) || Date.now() >= expiresAt) {
+      throw new HttpError(401, "unauthorized");
+    }
+
+    const owned = this.#active.get(options.userId) ?? 0;
+
+    if (
+      owned >= this.#limits.perUser ||
+      this.#count >= this.#limits.connections
+    ) {
+      res.setHeader("Retry-After", "1");
+      throw new HttpError(429, "tooManyLogStreams", {
+        code: "TOO_MANY_LOG_STREAMS",
+        defaultMessage: "Too many open log streams",
+      });
+    }
+
+    // Reserve capacity before opening files or committing the SSE response.
+    this.#count++;
+    this.#active.set(options.userId, owned + 1);
+
+    let closed = false;
+    let sent = 0;
+    let tail: Tail | undefined;
+    let deadline: ReturnType<typeof setTimeout> | undefined;
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+
+    const authorization = new AccessLease(
+      options.authorize,
+      this.#limits.authorizationIntervalMs,
+      this.#limits.authorizationTimeoutMs,
+      () => close(),
+    );
+
+    const releaseSlot = () => {
+      this.#count--;
+      const remaining = (this.#active.get(options.userId) ?? 1) - 1;
+      if (remaining) this.#active.set(options.userId, remaining);
+      else this.#active.delete(options.userId);
+    };
+
+    // All termination paths converge here; repeated events cannot release twice.
+    const close = (destroy = false) => {
+      if (closed) return;
+
+      closed = true;
+      this.#closeStreams.delete(close);
+      clearTimeout(deadline);
+      clearInterval(heartbeat);
+      tail?.close();
+
+      // A timed-out query may still run. Hold its slot until it settles so
+      // reconnects cannot create an unbounded queue of authorization work.
+      void authorization.close().then(releaseSlot);
+
+      res.off("close", disconnected);
+      res.off("error", disconnected);
+
+      if (destroy) res.destroy();
+      else if (res.headersSent && !res.destroyed && !res.writableEnded) {
+        res.end();
+
+        // A peer may stop draining even below write()'s high-water mark.
+        const finish = setTimeout(() => {
+          if (!res.writableFinished) res.destroy();
+        }, 1000);
+        finish.unref();
+        res.once("finish", () => clearTimeout(finish));
+        res.once("close", () => clearTimeout(finish));
+      }
+    };
+
+    const disconnected = () => close();
+
+    // Bound application output before handing another frame to Node's buffer.
+    const write = (frame: string): boolean => {
+      if (closed) return false;
+
+      if (Date.now() >= expiresAt || !authorization.valid) {
+        close();
+        return false;
+      }
+
+      const bytes = Buffer.byteLength(frame);
+
+      if (sent + bytes > this.#limits.outputBytes) {
+        close();
+        return false;
+      }
+      if (
+        res.destroyed ||
+        res.writableLength + bytes > this.#limits.bufferBytes
+      ) {
+        close(true);
+        return false;
+      }
+
+      sent += bytes;
+
+      try {
+        if (!res.write(frame)) {
+          close(true);
+          return false;
+        }
+      } catch {
+        close(true);
+        return false;
+      }
+      return true;
+    };
+
+    const send = (event: string, data: unknown) =>
+      write("event: " + event + "\ndata: " + JSON.stringify(data) + "\n\n");
+
+    res.once("close", disconnected);
+    res.once("error", disconnected);
+    this.#closeStreams.add(close);
+
+    try {
+      // Recheck before file access or SSE headers, closing the opening-request gap.
+      await authorization.start();
+      if (this.#draining && !res.destroyed && !res.headersSent) throw unavailable();
+      if (closed) return;
+
+      tail = tailLogs({
+        dir: options.dir,
+        prefix: options.prefix,
+        tail: options.tail,
+        onLine: (line) => {
+          let entry: unknown;
+          try {
+            entry = JSON.parse(line);
+          } catch {
+            entry = { msg: line };
+          }
+
+          const level =
+            entry &&
+            typeof entry === "object" &&
+            "level" in entry &&
+            typeof entry.level === "number"
+              ? entry.level
+              : 0;
+          if (level < (LEVELS[options.level ?? ""] ?? 0)) return true;
+          return send("log", entry);
+        },
+        onError: (code) => {
+          send("error", { code });
+          close();
+        },
+      });
+      if (Date.now() >= expiresAt) throw new HttpError(401, "unauthorized");
+      expiresAt = Math.min(expiresAt, Date.now() + this.#limits.durationMs);
+
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+      });
+      if (
+        !send("ready", {
+          process: options.process,
+          tail: options.tail,
+          level: options.level ?? "all",
+        })
+      )
+        return;
+
+      deadline = setTimeout(() => close(), Math.max(1, expiresAt - Date.now()));
+      heartbeat = setInterval(
+        () => write(": keep-alive\n\n"),
+        this.#limits.heartbeatMs,
+      );
+      deadline.unref();
+      heartbeat.unref();
+    } catch (error) {
+      close();
+      throw error;
+    }
+  }
+}