@tulipes/cli 0.1.0 → 0.2.0-rc.1

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

@@ -0,0 +1,19 @@
+{
+  "refreshUnavailable": "The refresh operation could not be acknowledged; sign in again",
+  "credentialsRequired": "An email address and a password are required",
+  "invalidCredentials": "Invalid email or password",
+  "passwordTooShort": "Password must be at least 8 characters",
+  "registrationClosed": "Registration is {{mode}}",
+  "emailUnavailable": "That email cannot be registered",
+  "refreshRequired": "A refresh token is required",
+  "refreshInvalid": "Invalid refresh token",
+  "refreshUsed": "That refresh token has already been used or revoked",
+  "accountGone": "This account no longer exists",
+  "loggedOut": "Signed out",
+  "passwordChanged": "Password changed — every other session was signed out",
+  "noSuchSession": "No such session",
+  "sessionEnded": "Session ended",
+  "emailRequired": "An email address is required",
+  "emailInvalid": "Must be a valid email address",
+  "passwordRequired": "A password is required"
+}

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

@@ -0,0 +1,19 @@
+{
+  "refreshUnavailable": "Le renouvellement n’a pas pu être confirmé ; reconnectez-vous",
+  "credentialsRequired": "Une adresse email et un mot de passe sont requis",
+  "invalidCredentials": "Email ou mot de passe invalide",
+  "passwordTooShort": "Le mot de passe doit contenir au moins 8 caractères",
+  "registrationClosed": "Les inscriptions sont {{mode}}",
+  "emailUnavailable": "Cette adresse email ne peut pas être enregistrée",
+  "refreshRequired": "Un jeton de rafraîchissement est requis",
+  "refreshInvalid": "Jeton de rafraîchissement invalide",
+  "refreshUsed": "Ce jeton de rafraîchissement a déjà été utilisé ou révoqué",
+  "accountGone": "Ce compte n'existe plus",
+  "loggedOut": "Déconnecté",
+  "passwordChanged": "Mot de passe modifié — toutes les autres sessions ont été fermées",
+  "noSuchSession": "Session introuvable",
+  "sessionEnded": "Session terminée",
+  "emailRequired": "Une adresse email est requise",
+  "emailInvalid": "Doit être une adresse email valide",
+  "passwordRequired": "Un mot de passe est requis"
+}

package/templates/app/modules/auth/lib/index.ts

@@ -0,0 +1,12 @@
+/**
+ * What the auth module offers other modules.
+ *
+ * No guards: routes are gated by `ctx.rai({ id })`, which core enforces at
+ * boot. Auth's contribution is resolving who the caller is — `req.auth`.
+ */
+export { auth, currentUser, GUEST, type Auth } from "../helpers/auth.ts";
+export { hashPassword, setPassword, verifyPassword } from "../helpers/passwords.ts";
+export { endAllSessions, endSession, listSessions } from "../helpers/tokens.ts";
+/** Call after writing a user's role or deleting the user: cached identities carry the old authority. */
+export { forgetSession, forgetUser } from "../helpers/session-cache.ts";
+export { createAccessCheck } from "../helpers/access-check.ts";

package/templates/app/modules/auth/models/credential.model.ts

@@ -0,0 +1,31 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+import { baseSchemaOptions } from "@app/core";
+
+/**
+ * Secrets live here, never on the User document.
+ *
+ * The separation is the point: a route that serialises a user cannot leak
+ * a password hash by accident, because the hash is not in that document at
+ * all. `select: false` is a second layer — even a query against this
+ * collection has to ask for the hash explicitly.
+ *
+ * One row per user, password only. API keys and OAuth links would be their
+ * own models rather than more columns here.
+ */
+const credentialSchema = new Schema(
+  {
+    user: {
+      type: Schema.Types.ObjectId,
+      ref: "User",
+      required: true,
+      unique: true,
+      index: true,
+    },
+    version: { type: String, required: true },
+    password_hash: { type: String, required: true, select: false },
+  },
+  baseSchemaOptions,
+);
+
+export default { name: "Credential", schema: credentialSchema } satisfies ModelDef;

package/templates/app/modules/auth/models/revoked-token.model.ts

@@ -0,0 +1,20 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+
+/**
+ * Access tokens are stateless, so logging out cannot un-issue one. This is
+ * the blacklist that makes logout immediate: the access token's jti is
+ * recorded until its natural expiry, and every authenticated request
+ * checks it.
+ *
+ * Rows carry a TTL index set to the token's own expiry — once the token
+ * would have expired anyway, the row deletes itself and the list stays as
+ * small as the access-token lifetime allows. That is the argument for
+ * keeping JWT_ACCESS_TTL short.
+ */
+const revokedTokenSchema = new Schema({
+  jti: { type: String, required: true, unique: true, index: true },
+  expires_at: { type: Date, required: true, expires: 0 },
+});
+
+export default { name: "RevokedToken", schema: revokedTokenSchema } satisfies ModelDef;

package/templates/app/modules/auth/models/session.model.ts

@@ -0,0 +1,42 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+import { baseSchemaOptions } from "@app/core";
+
+/**
+ * One row per signed-in device — the server-side half of a stateless JWT.
+ *
+ * Both tokens of a pair carry this row's `sid`, which is what lets an
+ * ACCESS token find its own session: the refresh token's jti changes on
+ * every rotation, so it could never serve as the identifier. Keeping the
+ * row across rotations is the point — `last_seen_at`, `ip` and `user_agent`
+ * survive, and "sign out this device" is deleting one document.
+ *
+ * `refresh_jti` holds only the CURRENT refresh token. One atomic update
+ * either rotates that token or expires the family when a superseded one
+ * is reused. All access tokens share this row and lose authorization too.
+ * Each new login receives a separate sid, so other devices remain active.
+ *
+ * `expires_at` carries a TTL index, so mongo prunes dead sessions itself.
+ * `created_at` is not declared here — baseSchemaOptions provides it.
+ */
+const sessionSchema = new Schema(
+  {
+    sid: { type: String, required: true, unique: true, index: true },
+    user: {
+      type: Schema.Types.ObjectId,
+      ref: "User",
+      required: true,
+      index: true,
+    },
+    credential_version: { type: String, required: true },
+    refresh_jti: { type: String, required: true, index: true },
+    /** Recorded at sign-in; a session that moves address keeps its origin. */
+    ip: { type: String },
+    user_agent: { type: String },
+    last_seen_at: { type: Date, default: Date.now },
+    expires_at: { type: Date, required: true, expires: 0 },
+  },
+  baseSchemaOptions,
+);
+
+export default { name: "Session", schema: sessionSchema } satisfies ModelDef;

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

@@ -0,0 +1,41 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+
+/**
+ * The auth module owns the role vocabulary, because roles only mean
+ * anything alongside the thing that assigns them.
+ *
+ * `guest` is the fallback for a request with no valid token. That is what
+ * makes "public endpoint" an ordinary ACL grant rather than a second
+ * mechanism: login is public because guest may do it, not because a path
+ * appears on an allowlist somewhere else.
+ */
+export default function authAcl(acl: AclBuilder): void {
+  acl.defineRole("guest").defineRole("user").defineRole("admin").defineRole("sysadmin");
+
+  // Anyone may attempt to authenticate. Refresh is public because the
+  // refresh token itself is the credential — an expired access token must
+  // not stand in the way of renewing it.
+  acl.allow("guest", "auth:login", "auth:register", "auth:refresh");
+
+  // Signed in: end your session, read yourself, change your own password,
+  // and manage the devices you are signed in on.
+  acl.allow(
+    "user",
+    "auth:logout",
+    "auth:me",
+    "auth:password",
+    "auth:sessions",
+    "auth:session-end",
+  );
+  // `admin` is granted each feature namespace EXPLICITLY rather than "*".
+  // A wildcard would also reach settings:*, and the infrastructure console
+  // is meant to be a boundary an ordinary administrator cannot cross — a
+  // grant that quietly includes everything makes "sysadmin only" a label
+  // rather than a rule. Add your own namespaces here as modules arrive.
+  acl.allow("admin", "auth:*", "users:*", "hello:*");
+
+  // `sysadmin` is an admin who can also administer the deployment. The
+  // settings grant is NOT here: a module grants its own namespace, so
+  // `settings:*` is declared by the settings module itself.
+  acl.allow("sysadmin", "auth:*", "users:*", "hello:*");
+}

package/templates/app/modules/auth/module.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+/**
+ * Token policy is a setting: every deployment wants to tune it, none of it
+ * is secret. The signing keys and the seeded admin credentials stay in the
+ * environment, where secrets belong, and `bootstrap/credentials.bootstrap.ts`
+ * refuses development values outside development.
+ */
+export default defineConfig({
+  schema: z.object({
+    accessTtl: z.string().min(1).default("15m")
+      .describe("Access token lifetime, as an ms/jsonwebtoken duration. Keep it short: a revoked user keeps their role until it expires"),
+    refreshTtl: z.string().min(1).default("30d")
+      .describe("Refresh token lifetime; also the TTL on its database record"),
+    /**
+     * How stale a session's `last_seen_at` may get before a request pays for
+     * the write. One write per request is not an option; one per minute is.
+     */
+    sessionTouchSeconds: z.number().int().positive().default(60)
+      .describe("Seconds between two writes of a session's last_seen_at"),
+    /**
+     * A resolved token is kept in the app cache this long, bounded by
+     * accessTtl; 0 disables the cache. Revocations delete the entry, so
+     * the bound only matters while Redis is unreachable at that moment.
+     */
+    cacheTtlSeconds: z.number().int().min(0).max(3600).default(60)
+      .describe("Seconds a resolved session stays in the cache (0 disables it); never longer than accessTtl"),
+  }),
+});

package/templates/app/modules/auth/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@app/auth",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.ts"
+  },
+  "tulipes": {
+    "tier": "sys",
+    "priority": 20,
+    "env": [
+      {
+        "name": "JWT_ACCESS_SECRET",
+        "type": "secret",
+        "group": "auth",
+        "required": true,
+        "description": "Signing key for short-lived access tokens"
+      },
+      {
+        "name": "JWT_REFRESH_SECRET",
+        "type": "secret",
+        "group": "auth",
+        "required": true,
+        "description": "Signing key for refresh tokens; separate from the access key so leaking one cannot mint the other"
+      },
+      {
+        "name": "AUTH_ADMIN_EMAIL",
+        "type": "string",
+        "group": "auth",
+        "required": true,
+        "description": "Email of the admin account seeded on first boot"
+      },
+      {
+        "name": "AUTH_ADMIN_PASSWORD",
+        "type": "secret",
+        "group": "auth",
+        "required": true,
+        "description": "Password for the seeded admin account; change it after the first login"
+      }
+    ]
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "@tulipes/mongoose": "workspace:*",
+    "bcryptjs": "^3",
+    "express": "^5",
+    "jsonwebtoken": "^9",
+    "mongoose": "^8",
+    "passport": "^0.7",
+    "passport-jwt": "^4",
+    "passport-local": "^1"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9",
+    "@types/passport": "^1",
+    "@types/passport-jwt": "^4",
+    "@types/passport-local": "^1"
+  }
+}

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

@@ -0,0 +1,94 @@
+import { Router } from "express";
+import passport from "passport";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { lazy } from "@app/core";
+
+import { AuthController } from "../controllers/auth.controllers.ts";
+import { authenticate, configurePassport } from "../helpers/passport.ts";
+import {
+  credentials,
+  newPassword,
+  refreshBody,
+  registration,
+  sidParam,
+  tokenPair,
+} from "../schemas/auth.schemas.ts";
+
+export default function authRoutes(ctx: BackendCtx): void {
+  const { app, rai, routes, config } = ctx;
+  const auth = new AuthController(ctx);
+
+  // Passport reads the signing keys when it is configured, so it is
+  // configured on the first request, after which every request is identified
+  // before any feature route runs.
+  app.use(lazy(() => {
+    configurePassport(ctx);
+    return passport.initialize();
+  }));
+  app.use(lazy(() => authenticate()));
+
+  const router = Router();
+
+  router.post("/register", rai({
+      id: "auth:register",
+      status: 201,
+      name: "Register",
+      description: "Create an account and its credential",
+      body: registration,
+    }), auth.register());
+
+  router.post("/login", rai({
+      id: "auth:login",
+      name: "Log in",
+      description: "Exchange email and password for a token pair",
+      body: credentials,
+      returns: tokenPair,
+    }), auth.login());
+
+  router.post("/refresh", rai({
+      id: "auth:refresh",
+      name: "Refresh tokens",
+      description: "Rotate a refresh token for a new pair",
+      body: refreshBody,
+      returns: tokenPair,
+    }), auth.refresh());
+
+  router.post("/logout", rai({
+      id: "auth:logout",
+      name: "Log out",
+      description: "Revoke this session immediately",
+    }), auth.logout());
+
+  router.get("/me", rai({
+      id: "auth:me",
+      name: "Who am I",
+      description: "The caller and the session behind this request",
+    }), auth.me());
+
+  router.get("/sessions", rai({
+      id: "auth:sessions",
+      name: "List sessions",
+      description: "Every device this account is signed in on",
+      // These two are auth's, but they answer a different question from
+      // signing in — `folder` puts them under their own heading in the
+      // generated collection and spec.
+      folder: "sessions",
+    }), auth.sessions());
+
+  router.delete("/sessions/:sid", rai({
+      id: "auth:session-end",
+      name: "End a session",
+      description: "Sign one other device out",
+      folder: "sessions",
+      params: sidParam,
+    }), auth.revokeSession());
+
+  router.post("/password", rai({
+      id: "auth:password",
+      name: "Change password",
+      description: "Set a new password and end every other session",
+      body: newPassword,
+    }), auth.changePassword());
+
+  routes.mount(router, `${config.api!.prefix}/auth`);
+}

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

@@ -0,0 +1,37 @@
+import { z } from "zod/v4";
+
+/**
+ * Request shapes for the auth endpoints, used twice from one declaration:
+ * `rai()` validates against them, and `tulipes spec` describes them.
+ *
+ * Messages are i18n keys — the error handler translates them in this
+ * module's namespace, so a rejected field speaks the caller's language.
+ */
+export const credentials = z.object({
+  email: z.email("emailInvalid"),
+  password: z.string("passwordRequired").min(1, "passwordRequired"),
+});
+
+export const registration = z.object({
+  email: z.email("emailInvalid"),
+  password: z.string("passwordTooShort").min(8, "passwordTooShort"),
+});
+
+// Refresh credentials come from the JSON body, never ambient browser cookies.
+export const refreshBody = z.object({
+  refresh_token: z.string("refreshRequired").min(1, "refreshRequired"),
+});
+
+export const newPassword = z.object({
+  password: z.string("passwordTooShort").min(8, "passwordTooShort"),
+});
+
+export const sidParam = z.object({
+  sid: z.uuid("noSuchSession"),
+});
+
+export const tokenPair = z.object({
+  access_token: z.string(),
+  refresh_token: z.string(),
+  expires_in: z.string(),
+});