@tulipes/core 0.1.14 → 0.2.0

package/dist/cli/init.js

@@ -320,6 +320,12 @@ function renderProject(name, coreVersion) {
                 `# script refuses until this is a real domain.`,
                 `PUBLIC_DOMAIN=localhost`,
                 ``,
+                `# Auth. Separate keys, so leaking one cannot mint the other.`,
+                `JWT_ACCESS_SECRET=dev-only-access-secret-change-me`,
+                `JWT_REFRESH_SECRET=dev-only-refresh-secret-change-me`,
+                `AUTH_ADMIN_EMAIL=admin@example.com`,
+                `AUTH_ADMIN_PASSWORD=dev-admin-password`,
+                ``,
             ].join("\n")],
         [".envs/.env.staging", [
                 `# Staging. Committed like the development file: it holds structure and`,
@@ -341,6 +347,10 @@ function renderProject(name, coreVersion) {
                 ``,
                 `# MONGO_URI=`,
                 `# REDIS_URL=`,
+                `# JWT_ACCESS_SECRET=`,
+                `# JWT_REFRESH_SECRET=`,
+                `# AUTH_ADMIN_EMAIL=`,
+                `# AUTH_ADMIN_PASSWORD=`,
                 ``,
             ].join("\n")],
         [".envs/.env.production", [
@@ -363,6 +373,10 @@ function renderProject(name, coreVersion) {
                 ``,
                 `# MONGO_URI=`,
                 `# REDIS_URL=`,
+                `# JWT_ACCESS_SECRET=`,
+                `# JWT_REFRESH_SECRET=`,
+                `# AUTH_ADMIN_EMAIL=`,
+                `# AUTH_ADMIN_PASSWORD=`,
                 ``,
             ].join("\n")],
         ["nginx/development.conf", [
@@ -697,6 +711,901 @@ function renderProject(name, coreVersion) {
                 `}`,
                 ``,
             ].join("\n")],
+        ["modules/auth/meta.variables.json", [
+                `{`,
+                `  "variables": [`,
+                `    {`,
+                `      "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": "JWT_ACCESS_TTL",`,
+                `      "type": "string",`,
+                `      "group": "auth",`,
+                `      "description": "Access token lifetime, as an ms/jsonwebtoken duration. Keep it short: a revoked user keeps their role until it expires",`,
+                `      "default": "15m"`,
+                `    },`,
+                `    {`,
+                `      "name": "JWT_REFRESH_TTL",`,
+                `      "type": "string",`,
+                `      "group": "auth",`,
+                `      "description": "Refresh token lifetime; also the TTL on its database record",`,
+                `      "default": "30d"`,
+                `    },`,
+                `    {`,
+                `      "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"`,
+                `    }`,
+                `  ]`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/module.acl.ts", [
+                `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");`,
+                ``,
+                `  // 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.`,
+                `  acl.allow("user", "auth:logout", "auth:me", "auth:password");`,
+                `  acl.allow("admin", "*");`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/module.config.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `export default function authConfig({ Environment }: Ctx) {`,
+                `  return {`,
+                `    accessTtl: Environment.get("JWT_ACCESS_TTL"),`,
+                `    refreshTtl: Environment.get("JWT_REFRESH_TTL"),`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/index.ts", [
+                `/**`,
+                ` * What the auth module offers other modules. Imported by package name:`,
+                ` *`,
+                ` *   import { requireAuth, requirePermission } from "@app/auth";`,
+                ` */`,
+                `export { requireAuth, requirePermission } from "./helpers/guards.js";`,
+                `export { principal, GUEST, type Principal } from "./helpers/principal.js";`,
+                `export { hashPassword, setPassword, verifyPassword } from "./helpers/passwords.js";`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/documents.ts", [
+                `import type { Types } from "mongoose";`,
+                ``,
+                `/**`,
+                ` * The shapes auth reads through the model store.`,
+                ` *`,
+                ` * \`models.get()\` is generic precisely so a consumer can say what it`,
+                ` * expects — the store cannot know, since models are registered by name`,
+                ` * from other modules. Declaring them here keeps the casts in one file`,
+                ` * instead of scattered through the handlers.`,
+                ` */`,
+                `export interface UserDoc {`,
+                `  _id: Types.ObjectId;`,
+                `  email: string;`,
+                `  role: string;`,
+                `  tokensValidFrom?: Date;`,
+                `}`,
+                ``,
+                `export interface CredentialDoc {`,
+                `  _id: Types.ObjectId;`,
+                `  user: Types.ObjectId;`,
+                `  passwordHash: string;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/principal.ts", [
+                `import type { Request } from "express";`,
+                ``,
+                `/**`,
+                ` * Who is making this request.`,
+                ` *`,
+                ` * There is always one — a request with no valid token is the \`guest\``,
+                ` * principal rather than an absent user. That is what lets a public`,
+                ` * endpoint be an ordinary ACL grant (\`allow("guest", "auth:login")\`)`,
+                ` * instead of a second, parallel allowlist mechanism.`,
+                ` */`,
+                `export interface Principal {`,
+                `  id?: string;`,
+                `  email?: string;`,
+                `  role: string;`,
+                `  /** jti of the access token, so logout can revoke this exact session. */`,
+                `  jti?: string;`,
+                `  authenticated: boolean;`,
+                `}`,
+                ``,
+                `export const GUEST: Principal = { role: "guest", authenticated: false };`,
+                ``,
+                `declare global {`,
+                `  // eslint-disable-next-line @typescript-eslint/no-namespace`,
+                `  namespace Express {`,
+                `    interface Request {`,
+                `      principal: Principal;`,
+                `    }`,
+                `  }`,
+                `}`,
+                ``,
+                `/** Never undefined: middleware assigns GUEST before any route runs. */`,
+                `export function principal(req: Request): Principal {`,
+                `  return req.principal ?? GUEST;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/tokens.ts", [
+                `import { randomUUID } from "node:crypto";`,
+                `import jwt from "jsonwebtoken";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `/** What a verified token tells us. Roles are never trusted from here. */`,
+                `export interface TokenClaims {`,
+                `  sub: string;`,
+                `  jti: string;`,
+                `  typ: "access" | "refresh";`,
+                `  iat: number;`,
+                `  exp: number;`,
+                `}`,
+                ``,
+                `export interface TokenPair {`,
+                `  accessToken: string;`,
+                `  refreshToken: string;`,
+                `  expiresIn: string;`,
+                `}`,
+                ``,
+                `const secret = (ctx: Ctx, typ: "access" | "refresh"): string =>`,
+                `  String(ctx.Environment.get(typ === "access" ? "JWT_ACCESS_SECRET" : "JWT_REFRESH_SECRET"));`,
+                ``,
+                `const ttl = (ctx: Ctx, typ: "access" | "refresh"): string =>`,
+                `  String(ctx.Environment.get(typ === "access" ? "JWT_ACCESS_TTL" : "JWT_REFRESH_TTL"));`,
+                ``,
+                `/**`,
+                ` * Issue a pair and record the refresh token so it can be revoked.`,
+                ` *`,
+                ` * The access token deliberately carries no role. Roles change, tokens do`,
+                ` * not, and a stale role in a signed token is a privilege bug waiting to`,
+                ` * happen — the request pipeline reloads the user instead.`,
+                ` */`,
+                `export async function issuePair(ctx: Ctx, userId: string): Promise<TokenPair> {`,
+                `  const accessJti = randomUUID();`,
+                `  const refreshJti = randomUUID();`,
+                ``,
+                `  const accessToken = jwt.sign({ typ: "access" }, secret(ctx, "access"), {`,
+                `    subject: userId,`,
+                `    jwtid: accessJti,`,
+                `    expiresIn: ttl(ctx, "access") as jwt.SignOptions["expiresIn"],`,
+                `  });`,
+                ``,
+                `  const refreshToken = jwt.sign({ typ: "refresh" }, secret(ctx, "refresh"), {`,
+                `    subject: userId,`,
+                `    jwtid: refreshJti,`,
+                `    expiresIn: ttl(ctx, "refresh") as jwt.SignOptions["expiresIn"],`,
+                `  });`,
+                ``,
+                `  const { exp } = jwt.decode(refreshToken) as { exp: number };`,
+                `  await ctx.models!.get("RefreshToken").create({`,
+                `    jti: refreshJti,`,
+                `    user: userId,`,
+                `    expiresAt: new Date(exp * 1000),`,
+                `  });`,
+                ``,
+                `  return { accessToken, refreshToken, expiresIn: ttl(ctx, "access") };`,
+                `}`,
+                ``,
+                `/** Verify signature and type. Returns undefined rather than throwing. */`,
+                `export function verify(`,
+                `  ctx: Ctx,`,
+                `  token: string,`,
+                `  typ: "access" | "refresh",`,
+                `): TokenClaims | undefined {`,
+                `  try {`,
+                `    const claims = jwt.verify(token, secret(ctx, typ)) as TokenClaims;`,
+                `    return claims.typ === typ ? claims : undefined;`,
+                `  } catch {`,
+                `    return undefined;`,
+                `  }`,
+                `}`,
+                ``,
+                `/** Consume a refresh token: valid only if its row still exists. */`,
+                `export async function consumeRefresh(ctx: Ctx, jti: string): Promise<boolean> {`,
+                `  const result = await ctx.models!.get("RefreshToken").deleteOne({ jti });`,
+                `  return result.deletedCount === 1;`,
+                `}`,
+                ``,
+                `/** Blacklist an access token for whatever is left of its lifetime. */`,
+                `export async function revokeAccess(ctx: Ctx, claims: TokenClaims): Promise<void> {`,
+                `  await ctx.models!.get("RevokedToken").updateOne(`,
+                `    { jti: claims.jti },`,
+                `    { $setOnInsert: { jti: claims.jti, expiresAt: new Date(claims.exp * 1000) } },`,
+                `    { upsert: true },`,
+                `  );`,
+                `}`,
+                ``,
+                `export async function isRevoked(ctx: Ctx, jti: string): Promise<boolean> {`,
+                `  return (await ctx.models!.get("RevokedToken").countDocuments({ jti }).limit(1)) > 0;`,
+                `}`,
+                ``,
+                `/** Drop every refresh token a user holds — used after a password change. */`,
+                `export async function revokeAllForUser(ctx: Ctx, userId: string): Promise<void> {`,
+                `  await ctx.models!.get("RefreshToken").deleteMany({ user: userId });`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/passwords.ts", [
+                `import bcrypt from "bcryptjs";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `/**`,
+                ` * bcryptjs — pure JavaScript, so installs never need a native toolchain.`,
+                ` * The cost factor comes from config rather than a literal: raising it is`,
+                ` * how you keep pace with hardware, and it should not require a code change.`,
+                ` */`,
+                `const rounds = (ctx: Ctx): number => Number(ctx.config.security?.passwordRounds ?? 12);`,
+                ``,
+                `export async function hashPassword(ctx: Ctx, plain: string): Promise<string> {`,
+                `  return bcrypt.hash(plain, rounds(ctx));`,
+                `}`,
+                ``,
+                `export async function verifyPassword(plain: string, hash: string): Promise<boolean> {`,
+                `  return bcrypt.compare(plain, hash);`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Set or replace a user's password and invalidate every session they have.`,
+                ` *`,
+                ` * Revoking here is the whole point of changing a password after a suspected`,
+                ` * compromise: leaving other devices signed in would defeat it.`,
+                ` */`,
+                `export async function setPassword(ctx: Ctx, userId: string, plain: string): Promise<void> {`,
+                `  const passwordHash = await hashPassword(ctx, plain);`,
+                ``,
+                `  await ctx.models!.get("Credential").updateOne(`,
+                `    { user: userId },`,
+                `    { $set: { passwordHash } },`,
+                `    { upsert: true },`,
+                `  );`,
+                ``,
+                `  // Bumps the epoch that the request pipeline compares every access token`,
+                `  // against, so tokens issued before this moment stop being accepted.`,
+                `  await ctx.models!.get("User").updateOne(`,
+                `    { _id: userId },`,
+                `    { $set: { tokensValidFrom: new Date() } },`,
+                `  );`,
+                ``,
+                `  const { revokeAllForUser } = await import("./tokens.js");`,
+                `  await revokeAllForUser(ctx, userId);`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/passport.ts", [
+                `import passport from "passport";`,
+                `import { Strategy as JwtStrategy, ExtractJwt } from "passport-jwt";`,
+                `import { Strategy as LocalStrategy } from "passport-local";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `import { verifyPassword } from "./passwords.js";`,
+                `import { isRevoked, type TokenClaims } from "./tokens.js";`,
+                `import { GUEST, type Principal } from "./principal.js";`,
+                `import type { CredentialDoc, UserDoc } from "./documents.js";`,
+                ``,
+                `/**`,
+                ` * Two strategies, both stateless (\`session: false\`):`,
+                ` *`,
+                ` *   local  runs once, at login, to check an email and password`,
+                ` *   jwt    runs on every request, to turn a Bearer token into a principal`,
+                ` *`,
+                ` * The jwt strategy reloads the user on each request rather than trusting`,
+                ` * the token's claims. It costs a query, and it is what makes a demotion or`,
+                ` * a ban take effect immediately instead of whenever the token expires.`,
+                ` */`,
+                `export function configurePassport(ctx: Ctx): void {`,
+                `  passport.use(`,
+                `    new LocalStrategy(`,
+                `      { usernameField: "email", passwordField: "password", session: false },`,
+                `      async (email, password, done) => {`,
+                `        try {`,
+                `          const user = await ctx.models!`,
+                `            .get<UserDoc>("User")`,
+                `            .findOne({ email: String(email).toLowerCase() })`,
+                `            .lean();`,
+                `          if (!user) return done(null, false);`,
+                ``,
+                `          // The hash is select:false, so it has to be asked for by name.`,
+                `          const credential = await ctx.models!`,
+                `            .get<CredentialDoc>("Credential")`,
+                `            .findOne({ user: user._id })`,
+                `            .select("+passwordHash")`,
+                `            .lean();`,
+                `          if (!credential) return done(null, false);`,
+                ``,
+                `          const ok = await verifyPassword(password, credential.passwordHash);`,
+                `          return done(null, ok ? (user as Express.User) : false);`,
+                `        } catch (error) {`,
+                `          return done(error as Error);`,
+                `        }`,
+                `      },`,
+                `    ),`,
+                `  );`,
+                ``,
+                `  passport.use(`,
+                `    new JwtStrategy(`,
+                `      {`,
+                `        jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),`,
+                `        secretOrKey: String(ctx.Environment.get("JWT_ACCESS_SECRET")),`,
+                `        passReqToCallback: false,`,
+                `      },`,
+                `      async (claims: TokenClaims, done) => {`,
+                `        try {`,
+                `          if (claims.typ !== "access") return done(null, false);`,
+                ``,
+                `          // Logout blacklists the jti; without this check a "logged out"`,
+                `          // token keeps working until it expires.`,
+                `          if (await isRevoked(ctx, claims.jti)) return done(null, false);`,
+                ``,
+                `          const record = await ctx.models!.get<UserDoc>("User").findById(claims.sub).lean();`,
+                `          if (!record) return done(null, false);`,
+                ``,
+                `          // A password change moves this epoch forward, which invalidates`,
+                `          // every token issued before it — on every device at once.`,
+                `          //`,
+                `          // Compared at second precision, because \`iat\` only has seconds:`,
+                `          // a token minted milliseconds *after* the epoch would otherwise`,
+                `          // look older than it and reject itself the moment it was issued.`,
+                `          if (record.tokensValidFrom) {`,
+                `            const epochSeconds = Math.floor(record.tokensValidFrom.getTime() / 1000);`,
+                `            if (claims.iat < epochSeconds) return done(null, false);`,
+                `          }`,
+                ``,
+                `          const resolved: Principal = {`,
+                `            id: String(record._id),`,
+                `            email: record.email,`,
+                `            role: record.role,`,
+                `            jti: claims.jti,`,
+                `            authenticated: true,`,
+                `          };`,
+                `          return done(null, resolved as Express.User);`,
+                `        } catch (error) {`,
+                `          return done(error as Error);`,
+                `        }`,
+                `      },`,
+                `    ),`,
+                `  );`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Runs on every request. Populates \`req.principal\`, and never rejects:`,
+                ` * an unauthenticated caller becomes GUEST, and the ACL decides from there.`,
+                ` */`,
+                `export function authenticate(): import("express").RequestHandler {`,
+                `  return (req, res, next) => {`,
+                `    passport.authenticate("jwt", { session: false }, (_err: unknown, user: Principal | false) => {`,
+                `      req.principal = user || GUEST;`,
+                `      next();`,
+                `    })(req, res, next);`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/helpers/guards.ts", [
+                `import type { RequestHandler } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { HttpError } from "@tulipes/core/http";`,
+                ``,
+                `import { principal } from "./principal.js";`,
+                ``,
+                `/**`,
+                ` * Guards other modules import from \`@app/auth\`.`,
+                ` *`,
+                ` * Both distinguish "you are not signed in" (401 — logging in would help)`,
+                ` * from "you are signed in and still may not" (403 — it would not). A`,
+                ` * client can act on that difference; a blanket 403 makes it guess.`,
+                ` */`,
+                ``,
+                `/** Requires any signed-in principal, without naming a permission. */`,
+                `export function requireAuth(): RequestHandler {`,
+                `  return (req, _res, next) => {`,
+                `    if (!principal(req).authenticated) {`,
+                `      throw new HttpError(401, "authentication required");`,
+                `    }`,
+                `    next();`,
+                `  };`,
+                `}`,
+                ``,
+                `/**`,
+                ` * Requires a permission, checked against the module ACL.`,
+                ` *`,
+                ` * Guests are subject to the same check as anyone else, which is what makes`,
+                ` * a public route just a grant to \`guest\` rather than a special case.`,
+                ` */`,
+                `export function requirePermission(ctx: Ctx, permission: string): RequestHandler {`,
+                `  return (req, _res, next) => {`,
+                `    const who = principal(req);`,
+                `    if (ctx.acl!.can(who.role, permission)) return next();`,
+                ``,
+                `    throw who.authenticated`,
+                `      ? new HttpError(403, \`role "\${who.role}" may not \${permission}\`)`,
+                `      : new HttpError(401, "authentication required");`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/controllers/auth.controllers.ts", [
+                `import passport from "passport";`,
+                `import type { Request, RequestHandler, Response } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { HttpError } from "@tulipes/core/http";`,
+                ``,
+                `import { principal } from "../helpers/principal.js";`,
+                `import type { UserDoc } from "../helpers/documents.js";`,
+                `import { setPassword } from "../helpers/passwords.js";`,
+                `import {`,
+                `  consumeRefresh,`,
+                `  issuePair,`,
+                `  revokeAccess,`,
+                `  verify,`,
+                `  type TokenClaims,`,
+                `} from "../helpers/tokens.js";`,
+                ``,
+                `interface Credentials {`,
+                `  email?: string;`,
+                `  password?: string;`,
+                `}`,
+                ``,
+                `/** POST /auth/register — creates the account and its credential. */`,
+                `export function register(ctx: Ctx): RequestHandler {`,
+                `  return async (req: Request, res: Response) => {`,
+                `    const { email, password } = (req.body ?? {}) as Credentials;`,
+                `    if (!email || !password) {`,
+                `      throw new HttpError(422, "email and password are required");`,
+                `    }`,
+                `    if (password.length < 8) {`,
+                `      throw new HttpError(422, "password must be at least 8 characters");`,
+                `    }`,
+                `    if (ctx.config.users?.signupMode !== "open") {`,
+                `      throw new HttpError(403, \`registration is \${ctx.config.users?.signupMode ?? "closed"}\`);`,
+                `    }`,
+                ``,
+                `    const User = 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`,
+                `      // different message here would turn registration into an oracle for`,
+                `      // which addresses have accounts.`,
+                `      throw new HttpError(422, "that email cannot be registered");`,
+                `    }`,
+                ``,
+                `    const user = await User.create({ email: normalised, role: "user" });`,
+                `    await setPassword(ctx, String(user._id), password);`,
+                ``,
+                `    const tokens = await issuePair(ctx, String(user._id));`,
+                `    res.status(201).json({ user: { id: String(user._id), email: normalised, role: "user" }, ...tokens });`,
+                `  };`,
+                `}`,
+                ``,
+                `/** POST /auth/login — passport-local checks the password, then we mint. */`,
+                `export function login(ctx: Ctx): RequestHandler {`,
+                `  return (req, res, next) => {`,
+                `    passport.authenticate(`,
+                `      "local",`,
+                `      { session: false },`,
+                `      async (error: unknown, user: { _id: unknown; email: string; role: string } | false) => {`,
+                `        if (error) return next(error);`,
+                `        // One message for "no such user" and "wrong password" alike.`,
+                `        if (!user) return next(new HttpError(401, "invalid email or password"));`,
+                ``,
+                `        try {`,
+                `          const tokens = await issuePair(ctx, String(user._id));`,
+                `          res.json({`,
+                `            user: { id: String(user._id), email: user.email, role: user.role },`,
+                `            ...tokens,`,
+                `          });`,
+                `        } catch (issueError) {`,
+                `          next(issueError);`,
+                `        }`,
+                `      },`,
+                `    )(req, res, next);`,
+                `  };`,
+                `}`,
+                ``,
+                `/** POST /auth/refresh — rotates the pair. */`,
+                `export function refresh(ctx: Ctx): RequestHandler {`,
+                `  return async (req, res) => {`,
+                `    const { refreshToken } = (req.body ?? {}) as { refreshToken?: string };`,
+                `    if (!refreshToken) throw new HttpError(422, "refreshToken is required");`,
+                ``,
+                `    const claims = verify(ctx, refreshToken, "refresh");`,
+                `    if (!claims) throw new HttpError(401, "invalid refresh token");`,
+                ``,
+                `    // Rotation: the old jti is consumed here, so the same refresh token`,
+                `    // cannot be exchanged twice.`,
+                `    if (!(await consumeRefresh(ctx, claims.jti))) {`,
+                `      throw new HttpError(401, "refresh token already used or revoked");`,
+                `    }`,
+                ``,
+                `    const user = await ctx.models!.get<UserDoc>("User").findById(claims.sub).lean();`,
+                `    if (!user) throw new HttpError(401, "account no longer exists");`,
+                ``,
+                `    res.json(await issuePair(ctx, claims.sub));`,
+                `  };`,
+                `}`,
+                ``,
+                `/** POST /auth/logout — ends this session immediately. */`,
+                `export function logout(ctx: Ctx): RequestHandler {`,
+                `  return async (req, res) => {`,
+                `    const who = principal(req);`,
+                `    const { refreshToken } = (req.body ?? {}) as { refreshToken?: string };`,
+                ``,
+                `    // Drop the refresh token so it cannot be rotated…`,
+                `    if (refreshToken) {`,
+                `      const claims = verify(ctx, refreshToken, "refresh");`,
+                `      if (claims) await consumeRefresh(ctx, claims.jti);`,
+                `    }`,
+                ``,
+                `    // …and blacklist the access token, so it stops working now rather than`,
+                `    // when it expires.`,
+                `    const header = req.header("authorization") ?? "";`,
+                `    const bearer = header.startsWith("Bearer ") ? header.slice(7) : undefined;`,
+                `    const access = bearer ? (verify(ctx, bearer, "access") as TokenClaims | undefined) : undefined;`,
+                `    if (access) await revokeAccess(ctx, access);`,
+                ``,
+                `    res.json({ loggedOut: true, user: who.id });`,
+                `  };`,
+                `}`,
+                ``,
+                `/** GET /auth/me — the principal the request pipeline resolved. */`,
+                `export function me(): RequestHandler {`,
+                `  return (req, res) => {`,
+                `    const { id, email, role } = principal(req);`,
+                `    res.json({ id, email, role });`,
+                `  };`,
+                `}`,
+                ``,
+                `/** POST /auth/password — change own password, ending every other session. */`,
+                `export function changePassword(ctx: Ctx): RequestHandler {`,
+                `  return async (req, res) => {`,
+                `    const who = principal(req);`,
+                `    const { password } = (req.body ?? {}) as { password?: string };`,
+                `    if (!password || password.length < 8) {`,
+                `      throw new HttpError(422, "password must be at least 8 characters");`,
+                `    }`,
+                ``,
+                `    await setPassword(ctx, who.id!, password);`,
+                ``,
+                `    // Every previous token is now dead, including the one that made this`,
+                `    // request. Handing back a fresh pair keeps the client that just`,
+                `    // changed its password signed in, while every other device is out.`,
+                `    const tokens = await issuePair(ctx, who.id!);`,
+                `    res.json({ changed: true, sessionsRevoked: true, ...tokens });`,
+                `  };`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/routes/auth.routes.ts", [
+                `import { Router } from "express";`,
+                `import passport from "passport";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `import {`,
+                `  changePassword,`,
+                `  login,`,
+                `  logout,`,
+                `  me,`,
+                `  refresh,`,
+                `  register,`,
+                `} from "../controllers/auth.controllers.js";`,
+                `import { authenticate, configurePassport } from "../helpers/passport.js";`,
+                `import { requirePermission } from "../helpers/guards.js";`,
+                ``,
+                `/**`,
+                ` * Auth is a sys-tier module, so this runs before every feature router.`,
+                ` * It does two things:`,
+                ` *`,
+                ` *   1. mounts the global principal resolver on ctx.app — every request`,
+                ` *      downstream has a \`req.principal\`, \`guest\` when unauthenticated`,
+                ` *   2. returns its own endpoints as a Router, like any other module`,
+                ` *`,
+                ` * Each endpoint names a permission rather than being implicitly public.`,
+                ` * Login is reachable because \`guest\` is granted \`auth:login\` in`,
+                ` * module.acl.ts — one mechanism, visible in one place.`,
+                ` */`,
+                `export default function authRoutes(ctx: Ctx): Router {`,
+                `  configurePassport(ctx);`,
+                ``,
+                `  ctx.app!.use(passport.initialize());`,
+                `  ctx.app!.use(authenticate());`,
+                ``,
+                `  const router = Router();`,
+                `  const base = \`\${String(ctx.config.api?.prefix ?? "")}/auth\`;`,
+                `  const may = (permission: string) => requirePermission(ctx, permission);`,
+                ``,
+                `  router.post(\`\${base}/register\`, may("auth:register"), register(ctx));`,
+                `  router.post(\`\${base}/login\`, may("auth:login"), login(ctx));`,
+                `  router.post(\`\${base}/refresh\`, may("auth:refresh"), refresh(ctx));`,
+                `  router.post(\`\${base}/logout\`, may("auth:logout"), logout(ctx));`,
+                `  router.get(\`\${base}/me\`, may("auth:me"), me());`,
+                `  router.post(\`\${base}/password\`, may("auth:password"), changePassword(ctx));`,
+                ``,
+                `  return router;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/models/credential.model.ts", [
+                `import { Schema } from "mongoose";`,
+                `import type { ModelDef } from "@tulipes/core/db";`,
+                `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,`,
+                `    },`,
+                `    passwordHash: { type: String, required: true, select: false },`,
+                `  },`,
+                `  baseSchemaOptions,`,
+                `);`,
+                ``,
+                `export default { name: "Credential", schema: credentialSchema } satisfies ModelDef;`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/models/refresh-token.model.ts", [
+                `import { Schema } from "mongoose";`,
+                `import type { ModelDef } from "@tulipes/core/db";`,
+                ``,
+                `/**`,
+                ` * One row per issued refresh token, keyed by its jti.`,
+                ` *`,
+                ` * Refresh tokens rotate: using one deletes its row and issues a new pair,`,
+                ` * so a token that is not in this collection is not usable — which is what`,
+                ` * makes logout and expiry mean something for an otherwise stateless JWT.`,
+                ` *`,
+                ` * \`expiresAt\` carries a TTL index, so mongo removes the rows itself and`,
+                ` * the collection cannot grow without bound.`,
+                ` */`,
+                `const refreshTokenSchema = new Schema({`,
+                `  jti: { type: String, required: true, unique: true, index: true },`,
+                `  user: { type: Schema.Types.ObjectId, ref: "User", required: true, index: true },`,
+                `  expiresAt: { type: Date, required: true, expires: 0 },`,
+                `  createdAt: { type: Date, default: Date.now },`,
+                `});`,
+                ``,
+                `export default { name: "RefreshToken", schema: refreshTokenSchema } satisfies ModelDef;`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/models/revoked-token.model.ts", [
+                `import { Schema } from "mongoose";`,
+                `import type { ModelDef } from "@tulipes/core/db";`,
+                ``,
+                `/**`,
+                ` * 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 },`,
+                `  expiresAt: { type: Date, required: true, expires: 0 },`,
+                `});`,
+                ``,
+                `export default { name: "RevokedToken", schema: revokedTokenSchema } satisfies ModelDef;`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/bootstrap/seed-admin.bootstrap.ts", [
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                ``,
+                `import { setPassword } from "../helpers/passwords.js";`,
+                `import type { UserDoc } from "../helpers/documents.js";`,
+                ``,
+                `/**`,
+                ` * 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: Ctx): Promise<void> {`,
+                `  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")));`,
+                `  }`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/auth/package.json", json({
+                name: `@app/auth`,
+                version: "0.0.0",
+                private: true,
+                type: "module",
+                exports: { ".": "./index.ts" },
+                // sys tier: the principal resolver must run before any feature
+                // router, and the roles it defines must exist before modules grant.
+                tulipes: { tier: "sys", priority: 20 },
+                dependencies: {
+                    "@tulipes/core": core,
+                    "@app/core": "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",
+                },
+            })],
+        ["modules/users/models/user.model.ts", [
+                `import { Schema } from "mongoose";`,
+                `import type { ModelDef } from "@tulipes/core/db";`,
+                `import { baseSchemaOptions } from "@app/core";`,
+                ``,
+                `/**`,
+                ` * The account record — and nothing secret.`,
+                ` *`,
+                ` * Passwords and keys live in the auth module's Credential model. Keeping`,
+                ` * them out of this document means a route that serialises a user cannot`,
+                ` * leak one by accident.`,
+                ` */`,
+                `const userSchema = new Schema(`,
+                `  {`,
+                `    email: { type: String, required: true, unique: true, lowercase: true, trim: true },`,
+                `    role: { type: String, required: true, default: "user" },`,
+                `    // Every access token issued before this instant is rejected. Auth`,
+                `    // moves it forward on a password change, which is how one action signs`,
+                `    // the account out everywhere. Not a secret.`,
+                `    tokensValidFrom: { type: Date },`,
+                `  },`,
+                `  baseSchemaOptions,`,
+                `);`,
+                ``,
+                `export default { name: "User", schema: userSchema } satisfies ModelDef;`,
+                ``,
+            ].join("\n")],
+        ["modules/users/routes/users.routes.ts", [
+                `import { Router } from "express";`,
+                `import type { Ctx } from "@tulipes/core/boot";`,
+                `import { requirePermission } from "@app/auth";`,
+                ``,
+                `export default function usersRoutes(ctx: Ctx): Router {`,
+                `  const router = Router();`,
+                `  const base = String(ctx.config.api?.prefix ?? "");`,
+                ``,
+                `  // Every route names a permission. A route without one is reachable by`,
+                `  // \`guest\`, because the pipeline authenticates rather than rejects — so`,
+                `  // "I forgot the guard" and "I meant this to be public" must never look`,
+                `  // the same. Naming one always is what keeps that honest.`,
+                `  const may = (permission: string) => requirePermission(ctx, permission);`,
+                ``,
+                `  router.get(\`\${base}/users\`, may("users:read"), async (req, res) => {`,
+                `    const { defaultLimit = 20, maxLimit = 100 } = ctx.config.pagination ?? {};`,
+                `    const asked = Number(req.query.limit ?? defaultLimit);`,
+                `    const limit = Math.min(Number.isFinite(asked) ? asked : defaultLimit, maxLimit);`,
+                ``,
+                `    const users = await ctx.models!`,
+                `      .get("User")`,
+                `      .find()`,
+                `      .select("email role -_id")`,
+                `      .limit(limit)`,
+                `      .lean();`,
+                ``,
+                `    res.json({ count: users.length, limit, users });`,
+                `  });`,
+                ``,
+                `  return router;`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/users/module.acl.ts", [
+                `import type { AclBuilder } from "@tulipes/core/acl";`,
+                ``,
+                `/**`,
+                ` * Roles are defined by the auth module; features only attach grants, on`,
+                ` * resources namespaced by their own name.`,
+                ` */`,
+                `export default function usersAcl(acl: AclBuilder): void {`,
+                `  acl.allow("user", "users:read");`,
+                `  // writes stay with admin, which already holds "*"`,
+                `}`,
+                ``,
+            ].join("\n")],
+        ["modules/users/package.json", json({
+                name: `@app/users`,
+                version: "0.0.0",
+                private: true,
+                type: "module",
+                tulipes: { tier: "app", priority: 10, dependsOn: ["auth", "core"] },
+                dependencies: {
+                    "@tulipes/core": core,
+                    "@app/auth": "workspace:*",
+                    "@app/core": "workspace:*",
+                    express: "^5",
+                    mongoose: "^8",
+                },
+            })],
         // ── modules/core — sys tier, priority 0: the very first router ─────────
         ["modules/core/package.json", json({
                 name: `@app/core`,
@@ -1413,21 +2322,6 @@ function renderProject(name, coreVersion) {
                 `}`,
                 ``,
             ].join("\n")],
-        ["modules/core/module.acl.ts", [
-                `import type { AclBuilder } from "@tulipes/core/acl";`,
-                ``,
-                `/**`,
-                ` * The sys core module owns the global role vocabulary. Business modules`,
-                ` * never define roles — they attach grants to these.`,
-                ` */`,
-                `export default function coreAcl(acl: AclBuilder): void {`,
-                `  acl.defineRole("admin").defineRole("user");`,
-                ``,
-                `  // admin can do everything, per resource-namespace wildcard rules.`,
-                `  acl.allow("admin", "*");`,
-                `}`,
-                ``,
-            ].join("\n")],
         ["modules/core/routes/core.routes.ts", [
                 `import { randomUUID } from "node:crypto";`,
                 `import type { Ctx } from "@tulipes/core/boot";`,
@@ -1612,9 +2506,10 @@ function renderProject(name, coreVersion) {
                 version: "0.0.0",
                 private: true,
                 type: "module",
-                tulipes: { tier: "app", priority: 100, dependsOn: ["core"] },
+                tulipes: { tier: "app", priority: 100, dependsOn: ["auth", "core"] },
                 dependencies: {
                     "@tulipes/core": core,
+                    "@app/auth": "workspace:*",
                     "@app/core": "workspace:*",
                     express: "^5",
                     mongoose: "^8",
@@ -1713,12 +2608,13 @@ function renderProject(name, coreVersion) {
                 `import { Router } from "express";`,
                 `import type { Ctx } from "@tulipes/core/boot";`,
                 `import { HttpError } from "@tulipes/core/http";`,
+                `import { requirePermission } from "@app/auth";`,
                 ``,
                 `import { greet } from "../controllers/hello.controllers.js";`,
                 ``,
                 `export default function helloRoutes(ctx: Ctx): Router {`,
                 `  const router = Router();`,
-                `  const { acl, config } = ctx;`,
+                `  const { config } = ctx;`,
                 ``,
                 `  // Built from the shared prefix, so versioning the whole API is a`,
                 `  // one-line change in config/app.config.ts.`,
@@ -1728,13 +2624,10 @@ function renderProject(name, coreVersion) {
                 ``,
                 `  // Literal paths must be registered before parameterised ones, or`,
                 `  // "/hello/:name" would swallow this.`,
-                `  router.get(\`\${base}/hello/secret\`, (req, res) => {`,
-                `    // A real app resolves the role in an auth module and puts it on the`,
-                `    // request; this reads a header purely so the demo is curl-able.`,
-                `    const role = String(req.header("x-demo-role") ?? "guest");`,
-                `    if (!acl!.can(role, "hello:read")) {`,
-                `      throw new HttpError(403, \`role "\${role}" may not read hello\`);`,
-                `    }`,
+                `  // requirePermission checks the caller against module.acl.ts. An`,
+                `  // unauthenticated request carries the "guest" role, so a stranger`,
+                `  // gets 401 and someone signed in without the grant gets 403.`,
+                `  router.get(\`\${base}/hello/secret\`, requirePermission(ctx, "hello:read"), (_req, res) => {`,
                 `    res.json({ secret: "only roles granted hello:read see this" });`,
                 `  });`,
                 ``,
@@ -1953,6 +2846,47 @@ function renderProject(name, coreVersion) {
             `| \`yarn tulipes new module <name>\` | scaffold a module |`,
             `| \`yarn tulipes update\` | upgrade the framework everywhere it is declared |`,
             ``,
+            `## Authentication`,
+            ``,
+            `\`modules/auth\` is sys tier, so it resolves the caller before any`,
+            `feature route runs. A request with no valid token is not rejected \u2014 it`,
+            `becomes the **guest** principal, which is what makes a public endpoint`,
+            `an ordinary ACL grant instead of a second mechanism:`,
+            ``,
+            "```ts",
+            `acl.allow("guest", "auth:login");   // that is why login is reachable`,
+            "```",
+            ``,
+            `Guard a route with the permission it needs. 401 means "sign in"; 403`,
+            `means "signed in, still not allowed":`,
+            ``,
+            "```ts",
+            `import { requirePermission } from "@app/auth";`,
+            ``,
+            `router.get(\`\${base}/invoices\`, requirePermission(ctx, "invoices:read"), handler);`,
+            "```",
+            ``,
+            `**A route with no permission check is public**, since the pipeline`,
+            `authenticates rather than rejects. Name one on every route.`,
+            ``,
+            `Try it \u2014 the admin comes from AUTH_ADMIN_EMAIL / AUTH_ADMIN_PASSWORD:`,
+            ``,
+            "```sh",
+            `curl -X POST localhost:3000/api/v1/auth/login \\`,
+            `  -H 'content-type: application/json' \\`,
+            `  -d '{"email":"admin@example.com","password":"dev-admin-password"}'`,
+            ``,
+            `curl localhost:3000/api/v1/auth/me -H "authorization: Bearer <accessToken>"`,
+            "```",
+            ``,
+            `Passwords never touch the User document: the hash lives in the auth`,
+            `module's \`Credential\` model, \`select: false\`, so a route that`,
+            `serialises a user cannot leak one. Refresh tokens rotate on use;`,
+            `logout deletes the refresh row and blacklists the access token's jti`,
+            `until it expires; a password change moves a per-user epoch that`,
+            `invalidates every token issued before it. Both token collections carry`,
+            `TTL indexes.`,
+            ``,
             `## Logging`,
             ``,
             `The logger lives in the core module and is shared by every other one:`,