@tulipes/cli 0.1.0 → 0.2.0-rc.1

package/templates/app/ecosystem.config.cjs

@@ -0,0 +1,60 @@
+// PM2 definitions for both Tulipes processes in all three modes.
+//
+//   pnpm pm2:start              development
+//   pnpm pm2:start:staging      staging
+//   pnpm pm2:start:production   production
+//   pnpm pm2:stop | pm2:restart | pm2:delete | pm2:logs | pm2:status
+//
+// CommonJS on purpose: this app is an ESM package, and PM2 reads its
+// config with require().
+
+/**
+ * Each block repeats both variables rather than relying on PM2 merging
+ * env_<name> over env: a half-applied environment (right APP_ENV, wrong
+ * PROCESS_MODE) would start the wrong process against the wrong config,
+ * and the repetition is cheap insurance against that.
+ */
+const modes = (processMode) => ({
+  env: { APP_ENV: "development", PROCESS_MODE: processMode },
+  env_staging: { APP_ENV: "staging", PROCESS_MODE: processMode },
+  env_production: { APP_ENV: "production", PROCESS_MODE: processMode },
+});
+
+/** Shared by both apps. */
+const common = {
+  cwd: __dirname,
+  // Node 24 strips types natively, so PM2 runs the TypeScript entrypoints
+  // with node itself: no loader, no build step, nothing to point elsewhere.
+  interpreter: "node",
+  // Fork, not cluster: Socket.IO needs sticky sessions or the Redis
+  // adapter before a second instance is safe, and bootstrap tasks would
+  // run once per instance. Scale out only after wiring the adapter.
+  exec_mode: "fork",
+  instances: 1,
+  autorestart: true,
+  max_memory_restart: "512M",
+  // Graceful shutdown drains queues and closes mongo and redis. PM2's
+  // default 1.6s SIGKILL would cut that short and lose in-flight jobs.
+  kill_timeout: 10000,
+};
+
+module.exports = {
+  apps: [
+    {
+      ...common,
+      name: "tulipes-example",
+      script: "app.ts",
+      error_file: "logs/backend-error.log",
+      out_file: "logs/backend-out.log",
+      ...modes("backend"),
+    },
+    {
+      ...common,
+      name: "tulipes-example-worker",
+      script: "worker.ts",
+      error_file: "logs/worker-error.log",
+      out_file: "logs/worker-out.log",
+      ...modes("worker"),
+    },
+  ],
+};

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

@@ -0,0 +1,31 @@
+import type { Request, RequestHandler, Response } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { roleOf } from "@tulipes/core/http";
+
+/**
+ * The HTTP transport over `ctx.agent`: the manifest a role may call, and
+ * the action endpoint. Route tools are not invoked here — the manifest
+ * gives their method and path, and an agent calls them like any client,
+ * through the same middleware.
+ */
+export class AgentController {
+  readonly #ctx: BackendCtx;
+
+  constructor(ctx: BackendCtx) {
+    this.#ctx = ctx;
+  }
+
+  tools(): RequestHandler {
+    return (req: Request, res: Response) => {
+      res.respond({ data: this.#ctx.agent.manifest(roleOf(req)) });
+    };
+  }
+
+  invoke(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const name = String(req.params.name);
+      const actor = { ...req.auth, role: roleOf(req) };
+      res.respond({ data: await this.#ctx.agent.invoke(name, req.body, actor, req) });
+    };
+  }
+}

package/templates/app/modules/agent/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "noSuchTool": "No tool named \"{{name}}\"",
+  "routeTool": "\"{{name}}\" is an endpoint — call {{method}} {{path}}",
+  "invalidToolName": "Tool names are letters, digits, _ and -"
+}

package/templates/app/modules/agent/i18n/fr.json

@@ -0,0 +1,5 @@
+{
+  "noSuchTool": "Aucun outil nommé « {{name}} »",
+  "routeTool": "« {{name}} » est un point d'accès — appelez {{method}} {{path}}",
+  "invalidToolName": "Un nom d'outil contient des lettres, des chiffres, _ et -"
+}

package/templates/app/modules/agent/module.acl.ts

@@ -0,0 +1,14 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+
+/**
+ * The agent door is open to every role, including guest: the manifest is
+ * filtered to what the caller's role may call, and an action checks its
+ * own permission before running, so these grants reveal and allow nothing
+ * the ACL does not already.
+ */
+export default function agentAcl(acl: AclBuilder): void {
+  acl.allow("guest", "agent:*");
+  acl.allow("user", "agent:*");
+  acl.allow("admin", "agent:*");
+  acl.allow("sysadmin", "agent:*");
+}

package/templates/app/modules/agent/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@app/agent",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "app",
+    "priority": 950,
+    "dependsOn": [
+      "auth",
+      "core"
+    ]
+  },
+  "dependencies": {
+    "@app/auth": "workspace:*",
+    "@app/core": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "express": "^5",
+    "zod": "^3.25"
+  }
+}

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

@@ -0,0 +1,29 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+
+import { AgentController } from "../controllers/agent.controllers.ts";
+import { toolInput, toolName } from "../schemas/agent.schemas.ts";
+
+export default function agentRoutes(ctx: BackendCtx): void {
+  const { rai, routes, config } = ctx;
+  const router = Router();
+  const agent = new AgentController(ctx);
+
+  router.get("/tools", rai({
+      id: "agent:tools",
+      name: "List the tools an agent may call",
+      description: "The manifest filtered to the caller's role: route tools with their method and path, actions with their input schema",
+      agent: false,
+    }), agent.tools());
+
+  router.post("/tools/:name", rai({
+      id: "agent:invoke",
+      name: "Run a declared action",
+      description: "Runs an action from a module's agent declaration; the action's own permission and input schema apply",
+      params: toolName,
+      body: toolInput,
+      agent: false,
+    }), agent.invoke());
+
+  routes.mount(router, `${config.api!.prefix}/agent`);
+}

package/templates/app/modules/agent/schemas/agent.schemas.ts

@@ -0,0 +1,9 @@
+import { z } from "zod/v4";
+
+/** The tool name as the manifest lists it. */
+export const toolName = z.object({
+  name: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/, "invalidToolName"),
+});
+
+/** The tool's input — the action's own schema validates it next. */
+export const toolInput = z.looseObject({});

package/templates/app/modules/auth/bootstrap/credentials.bootstrap.ts

@@ -0,0 +1,26 @@
+import type { RuntimeCtx } from "@tulipes/core/boot";
+
+/**
+ * Outside development the seeded credentials and signing keys must not be
+ * the scaffold's placeholders, and the two keys must differ so leaking one
+ * cannot mint the other. Sorted before seed-admin so the admin is never
+ * seeded with a refused password.
+ */
+export default function credentials({ Environment }: RuntimeCtx): void {
+  if (Environment.appEnv !== "production" && Environment.appEnv !== "staging") return;
+  const invalid: string[] = [];
+  const defaults = [
+    ["JWT_ACCESS_SECRET", "dev-only-access-secret-change-me"],
+    ["JWT_REFRESH_SECRET", "dev-only-refresh-secret-change-me"],
+    ["AUTH_ADMIN_PASSWORD", "dev-admin-password"],
+    ["AUTH_ADMIN_EMAIL", "admin@example.com"],
+  ] as const;
+  for (const [name, developmentValue] of defaults) {
+    const value = String(Environment.get(name)).trim();
+    if (!value || value === developmentValue) invalid.push(name);
+  }
+  if (Environment.get("JWT_ACCESS_SECRET") === Environment.get("JWT_REFRESH_SECRET")) {
+    invalid.push("JWT_ACCESS_SECRET / JWT_REFRESH_SECRET (use distinct keys)");
+  }
+  if (invalid.length) throw new Error("Unsafe production credentials: configure " + invalid.join(", "));
+}

package/templates/app/modules/auth/bootstrap/seed-admin.bootstrap.ts

@@ -0,0 +1,44 @@
+import type { DatabaseCtx } from "@tulipes/core/boot";
+
+import { setPassword } from "../helpers/passwords.ts";
+import type { UserDoc } from "../helpers/documents.ts";
+
+/**
+ * Seeds the first admin: the account and its credential together.
+ *
+ * It lives in auth rather than users because only auth knows how to store
+ * a password — which is the whole reason credentials are a separate model.
+ * Auth reaches the User model through the model store by name, not by
+ * importing the users module: auth is sys-tier and users is app-tier, and
+ * a sys module may not depend on an app module.
+ */
+export default async function seedAdmin(ctx: DatabaseCtx): Promise<void> {
+  // Bootstrap runs in every mode; a one-off script has no business seeding.
+  if (ctx.mode === "script") return;
+  const email = String(ctx.Environment.get("AUTH_ADMIN_EMAIL")).toLowerCase();
+  const User = ctx.models.get<UserDoc>("User");
+
+  let user: Pick<UserDoc, "_id"> | null = await User.findOne({ email }).lean();
+
+  if (!user) {
+    try {
+      user = await User.create({ email, role: "admin" });
+    } catch (error) {
+      // Backend and worker boot together, so both may reach this at once.
+      // The loser of that race just reads the row the winner inserted.
+      if ((error as { code?: number }).code !== 11000) throw error;
+      user = await User.findOne({ email }).lean();
+    }
+  }
+
+  // Only set the password when there is no credential yet, so a rotated
+  // admin password is not silently reset to the seed value on next boot.
+  const existing = await ctx.models
+    .get("Credential")
+    .countDocuments({ user: user!._id })
+    .limit(1);
+
+  if (existing === 0) {
+    await setPassword(ctx, String(user!._id), String(ctx.Environment.get("AUTH_ADMIN_PASSWORD")));
+  }
+}

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

@@ -0,0 +1,312 @@
+import passport from "passport";
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import {
+  HttpError,
+  ValidationError,
+  type FieldIssue,
+} from "@tulipes/core/http";
+
+import { auth } from "../helpers/auth.ts";
+import type { PasswordIdentity, UserDoc } from "../helpers/documents.ts";
+import { setPassword } from "../helpers/passwords.ts";
+import {
+  endSession,
+  listSessions,
+  originOf,
+  rotateSession,
+  startSession,
+  revokeAccess,
+  verify,
+  type TokenClaims,
+} from "../helpers/tokens.ts";
+
+interface Credentials {
+  email?: string;
+  password?: string;
+}
+
+/**
+ * One class per controller, holding the context.
+ *
+ * Each method *returns* a handler rather than being one, so the routes
+ * file reads as a table of contents — `auth.login()` — and the class can
+ * keep private helpers beside the handlers that use them without
+ * threading ctx through every signature.
+ *
+ * Every response goes through `res.respond`; failures are thrown and the
+ * framework's terminal handler builds the same envelope from them.
+ *
+ * Thrown messages are i18n KEYS — the handler translates them in this
+ * module's namespace and derives the code from the key, so
+ * "invalidCredentials" becomes INVALID_CREDENTIALS with a translated
+ * message and there is no second string to keep in step.
+ */
+export class AuthController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  /** Creates the account and its credential. */
+  register(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { email, password } = (req.body ?? {}) as Credentials;
+
+      // Both fields are checked before answering: a form wrong in two
+      // places should say so once, not across two round trips.
+      const issues: FieldIssue[] = [];
+      if (!email) issues.push({ field: "email", message: "emailRequired" });
+      if (!password || password.length < 8) {
+        issues.push({ field: "password", message: "passwordTooShort" });
+      }
+      if (issues.length > 0) throw new ValidationError(issues);
+      // The guards above threw unless both are present — a narrowing
+      // TypeScript cannot make through the issues array.
+
+      if (this.#ctx.config.users?.signupMode !== "open") {
+        const mode = this.#ctx.config.users?.signupMode ?? "closed";
+        throw new HttpError(403, req.t("registrationClosed", { mode }), {
+          code: "REGISTRATION_CLOSED",
+        });
+      }
+
+      const User = this.#ctx.models!.get<UserDoc>("User");
+      const normalised = email!.toLowerCase();
+      if (await User.countDocuments({ email: normalised }).limit(1)) {
+        // Deliberately the same shape as any other validation failure: a
+        // distinct message would turn registration into an oracle for
+        // which addresses already have accounts.
+        throw new HttpError(422, "emailUnavailable", { field: "email" });
+      }
+
+      const user = await User.create({ email: normalised, role: "user" });
+      const credentialVersion = await setPassword(
+        this.#ctx,
+        String(user._id),
+        password!,
+      );
+
+      const tokens = await startSession(
+        this.#ctx,
+        String(user._id),
+        credentialVersion,
+        originOf(req),
+      );
+      res.respond({
+        status: 201,
+        data: {
+          user: { id: String(user._id), email: normalised, role: "user" },
+          ...tokens,
+        },
+      });
+    };
+  }
+
+  /** passport-local checks the password; this mints the pair. */
+  login(): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction) => {
+      passport.authenticate(
+        "local",
+        { session: false },
+        async (error: unknown, identity: PasswordIdentity | false) => {
+          if (error) return next(error);
+          // One message for "no such user" and "wrong password" alike.
+          if (!identity) return next(new HttpError(401, "invalidCredentials"));
+          const { user, credentialVersion } = identity;
+
+          try {
+            const tokens = await startSession(
+              this.#ctx,
+              String(user._id),
+              credentialVersion,
+              originOf(req),
+            );
+            res.respond({
+              data: {
+                user: {
+                  id: String(user._id),
+                  email: user.email,
+                  role: user.role,
+                },
+                ...tokens,
+              },
+            });
+          } catch (issueError) {
+            next(issueError);
+          }
+        },
+      )(req, res, next);
+    };
+  }
+
+  /** Rotates the pair, consuming the refresh token presented. */
+  refresh(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { refresh_token } = (req.body ?? {}) as { refresh_token?: string };
+      if (!refresh_token) {
+        throw new HttpError(422, "refreshRequired", { field: "refresh_token" });
+      }
+
+      const claims = verify(this.#ctx, refresh_token, "refresh");
+      if (!claims)
+        throw new HttpError(401, "refreshInvalid", { field: "refresh_token" });
+
+      const user = await this.#ctx
+        .models!.get<UserDoc>("User")
+        .findById(claims.sub)
+        .lean();
+      if (!user) throw new HttpError(401, "accountGone");
+
+      // Rotation also detects reuse and expires this device's token family.
+      // A duplicate client request has the same consequence as token theft.
+      const tokens = await rotateSession(this.#ctx, claims);
+      if (!tokens)
+        throw new HttpError(401, "refreshUsed", { field: "refresh_token" });
+
+      res.respond({ data: tokens });
+    };
+  }
+
+  /** Ends this session immediately — both halves of it. */
+  logout(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { user, session } = auth(req);
+
+      // Deleting the row kills the refresh half: no session, no rotation,
+      // and the next request carrying this access token resolves to guest.
+      if (session) await endSession(this.#ctx, session.sid);
+
+      // Blacklisting the access token is what makes logout take effect
+      // now, rather than whenever the token would have expired.
+      const access = this.#accessClaims(req);
+      if (access) await revokeAccess(this.#ctx, access);
+
+      res.respond({
+        data: {
+          message: req.t("loggedOut"),
+          logged_out: true,
+          user: user ? String(user._id) : null,
+        },
+      });
+    };
+  }
+
+  /** Whoever the request pipeline resolved, and the session behind it. */
+  me(): RequestHandler {
+    return (req: Request, res: Response) => {
+      const { isAuthenticated, user, session } = req.auth;
+
+      res.respond({
+        data: {
+          is_authenticated: isAuthenticated,
+          locale: req.locale,
+          user: user && {
+            id: String(user._id),
+            email: user.email,
+            role: user.role,
+          },
+          session: session && {
+            sid: session.sid,
+            ip: session.ip,
+            user_agent: session.user_agent,
+            started_at: session.created_at,
+            last_seen_at: session.last_seen_at,
+            expires_at: session.expires_at,
+            access_expires_at: session.access_expires_at,
+          },
+        },
+      });
+    };
+  }
+
+  /** Every device this account is signed in on. */
+  sessions(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { user, session } = req.auth;
+      const rows = await listSessions(this.#ctx, String(user!._id));
+
+      res.respond({
+        data: rows.map((row) => ({
+          sid: row.sid,
+          current: row.sid === session?.sid,
+          ip: row.ip,
+          user_agent: row.user_agent,
+          started_at: row.created_at,
+          last_seen_at: row.last_seen_at,
+        })),
+        meta: { total_items: rows.length },
+      });
+    };
+  }
+
+  /** Sign one other device out, by the sid from `sessions()`. */
+  revokeSession(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { user } = req.auth;
+      const { sid } = req.params;
+
+      // Scoped to the caller's own sessions: a sid is guessable enough
+      // that ending anyone else's must not be one request away.
+      const owned = await listSessions(this.#ctx, String(user!._id));
+      if (!owned.some((row) => row.sid === sid)) {
+        throw new HttpError(404, "noSuchSession", { field: "sid" });
+      }
+
+      await endSession(this.#ctx, String(sid));
+      res.respond({ data: { message: req.t("sessionEnded"), sid } });
+    };
+  }
+
+  /** Changes own password, ending every other session. */
+  changePassword(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const userId = String(req.auth.user!._id);
+      const { password } = (req.body ?? {}) as { password?: string };
+      this.#assertPassword(password);
+
+      // Capture the version written by this change, even if another change races.
+      const expectedVersion = req.auth.session?.credential_version;
+      if (!expectedVersion) throw new HttpError(401, "invalidCredentials");
+      const credentialVersion = await setPassword(
+        this.#ctx,
+        userId,
+        password!,
+        expectedVersion,
+      );
+
+      // Every earlier token is dead now, including the one that made this
+      // request — a fresh session keeps this client signed in while the
+      // other devices are signed out.
+      const tokens = await startSession(
+        this.#ctx,
+        userId,
+        credentialVersion,
+        originOf(req),
+      );
+      res.respond({
+        data: {
+          message: req.t("passwordChanged"),
+          changed: true,
+          sessions_revoked: true,
+          ...tokens,
+        },
+      });
+    };
+  }
+
+  // Takes the request only to reach `req.t`: a rule the user broke has to
+  // be explained in the language they asked for.
+  #assertPassword(password: string | undefined): asserts password is string {
+    if (!password || password.length < 8) {
+      throw new HttpError(422, "passwordTooShort", { field: "password" });
+    }
+  }
+
+  #accessClaims(req: Request): TokenClaims | undefined {
+    const header = req.header("authorization") ?? "";
+    if (!header.startsWith("Bearer ")) return undefined;
+    return verify(this.#ctx, header.slice(7), "access");
+  }
+}

package/templates/app/modules/auth/helpers/access-check.ts

@@ -0,0 +1,42 @@
+import type { Ctx } from "@tulipes/core/boot";
+import type { Auth } from "@tulipes/core/http";
+import type { UserDoc } from "./documents.ts";
+import { isRevoked, loadSession } from "./tokens.ts";
+
+/** Capture the authenticated token identity, then reload its authority on demand. */
+export function createAccessCheck(
+  ctx: Ctx,
+  auth: Auth,
+  permission: string,
+): (signal: AbortSignal) => Promise<boolean> {
+  // Copy scalars; do not retain a mutable request/user document as authorization.
+  const userId = auth.user ? String(auth.user._id) : "";
+  const sid = auth.session?.sid;
+  const jti = auth.session?.access_jti;
+  const version = auth.session?.credential_version;
+  const expiresAt = auth.session?.access_expires_at.getTime() ?? 0;
+
+  return async (signal) => {
+    signal.throwIfAborted();
+    if (!userId || !sid || !jti || !version || Date.now() >= expiresAt) {
+      return false;
+    }
+
+    // loadSession checks owner, current credential version and live expiration.
+    // It also rejects a family expired by refresh-token reuse.
+    const session = await loadSession(ctx, sid, userId);
+    signal.throwIfAborted();
+    if (!session || session.credential_version !== version) return false;
+
+    const revoked = await isRevoked(ctx, jti);
+    signal.throwIfAborted();
+    if (revoked) return false;
+
+    const user = await ctx.models!.get<UserDoc>("User").findById(userId);
+    signal.throwIfAborted();
+
+    return Boolean(
+      user && Date.now() < expiresAt && ctx.acl?.can(user.role, permission),
+    );
+  };
+}

package/templates/app/modules/auth/helpers/auth.ts

@@ -0,0 +1,48 @@
+import type { Request } from "express";
+import { ANONYMOUS, type Auth } from "@tulipes/core/http";
+
+import type { SessionDoc, UserDoc } from "./documents.ts";
+
+/**
+ * Core owns the `Auth` shape and reads `req.auth`; this module's only job
+ * is putting one there. That is the whole contract between an auth
+ * implementation and the framework — swap JWT for sessions or mTLS and
+ * nothing else changes.
+ *
+ * Core declares `user` and `session` as empty interfaces on purpose: it
+ * knows the shape of the contract, and the app says what fills it. These
+ * augmentations are what make `req.auth.user.email` and
+ * `req.auth.session.last_seen_at` typed at every call site.
+ */
+declare module "@tulipes/core/http" {
+  interface AuthUser extends UserDoc {}
+
+  interface AuthSession extends SessionDoc {
+    /**
+     * This request's ACCESS token, added to the session row rather than
+     * stored on it: the row outlives any single token, and these three
+     * are what let a handler revoke exactly the token in its hand.
+     */
+    access_jti: string;
+    access_issued_at: Date;
+    access_expires_at: Date;
+  }
+}
+
+export type { Auth };
+export { ANONYMOUS as GUEST };
+
+/**
+ * Never undefined inside a declared route: the auth middleware sets it,
+ * and `rai()` falls back to the guest value. This helper exists for code
+ * that runs BEFORE any rai() — middleware in another sys module.
+ */
+export function auth(req: Request): Auth {
+  if (!req.auth || req.auth === ANONYMOUS) req.auth = { ...ANONYMOUS };
+  return req.auth;
+}
+
+/** The signed-in user, or undefined for a guest. Saves an `if` at call sites. */
+export function currentUser(req: Request) {
+  return auth(req).user ?? undefined;
+}