feat(auth): invite-only / capped signup gate (#3715)

* feat(users): add exact count() for signup cap enforcement

* feat(auth): scaffold signup invitation model, schema, and CASL policy

* fix(auth): drop duplicate token unique index on Invitation (keep explicit index)

* feat(auth): invitation repository + service (token gen, validation, consume)

* feat(auth): admin invitation CRUD + public verify endpoint + email template

* fix(auth): inline invitation routes into auth.routes (single reg, before :strategy wildcard)

Removes auth.invitation.routes.js so the glob auto-loader never picks it
up, eliminating the double-registration bug (two DB hits per DELETE,
duplicate app.param binding). Invitation routes are now declared once
inside auth.routes.js, before the greedy /api/auth/:strategy wildcard.

* feat(auth): gate local signup by cap + invite token, consume on success

Two AND-ed guards on POST /api/auth/signup: (1) capacity ceiling
(config.sign.cap, invited users count toward the cap) blocks everyone
when total >= cap; (2) eligibility requires config.sign.up OR a valid
inviteToken query param (token consumed after account is fully
provisioned). Config gains sign.cap and sign.inviteExpiresInDays.

* feat(auth): gate OAuth signup by cap + email-matched invite, consume on success

* docs(auth): document signup access control (cap + invitations) in README + OpenAPI

* chore(auth): verify fixups for invitation signup gate

- fix: optional chain req.query?.inviteToken to guard against missing query
  object (broke analytics unit tests that inject req without a query key)
- fix: mock InvitationService + add UserService.count mock in
  analytics.identify.unit.tests to prevent MissingSchemaError on lazy
  mongoose.model('Invitation') call at repository import time
- test: extend auth.invitation.unit.tests — email-send branch, findValidByEmail
  null-guard, list/get/revoke delegation, invitationAbilities admin/non-admin
  paths, invitationSubjectRegistration predicate (policy 100% coverage)

* fix(auth): enforce invite email-pin on no-email signup; hide token from admin list

* fix(auth): address CodeRabbit/Copilot review findings on invite gate

- email template: add non-empty <title> to signup-invite.html
- auth.controller: short-circuit UserService.count() when cap is null
- auth.controller: coerce sign.cap to Number + guard non-finite at gate
- auth.controller: only consume invite when it actually opened the gate
  (sign.up=true = invite not required, burning it would be wrong)
- auth.invitation.controller: add full JSDoc (@param/@returns) to all
  controller functions per project standard
- auth.invitations.yml: add InvitationListItem schema (token omitted);
  admin list endpoint now references it instead of Invitation
- auth.invitation.model.mongoose.js: add JSDoc to addID virtual getter
- auth.invitation.integration.tests.js: add @returns to test helpers;
  fix cap test to create admin before setting cap (was order-dependent)
- auth.signout.controller.unit.tests.js: complete InvitationService mock
- auth.silent.catch.unit.tests.js: complete InvitationService mock

* fix(auth): canonicalize invited signup email to invite (single-use under concurrent case-variants)

* test(users): isolate count unit test from Organization model (deterministic CI)

Add repository-level mocks for organizations.repository.js and
organizations.membership.repository.js so mongoose.model('Organization')
is never evaluated at module-link time with --maxWorkers=2.

Service-level mocks intercept call paths but ESM static imports on the
real service files are still resolved by the V8 VM module linker in CI,
causing MissingSchemaError when the Organization schema hasn't been
registered yet in that worker's context.

* fix(auth): require verified provider email before OAuth invite matching (gate bypass)

Author: PierreBrisorgueil

README.md

@@ -36,6 +36,7 @@ Designed to be cloned into downstream projects and kept up-to-date via `git merg
 - **User data privacy** : delete all - get all - send all by mail
 - **Admin** : list users - get user - edit user - delete user
 - **Organizations** : multi-tenant organization management - create, update, delete orgs - member invite, role management (owner/admin/member) - platform admin org listing
+- **Signup access control** : invite-only signup (single-use token links) + hard account cap (beta gating) - admin-managed invitations, public signup auto-locks at the cap
 - **CASL v2 Authorization** : document-level permission checks via [@casl/ability](https://casl.js.org/) - replaces route-level role rules with per-document conditions (ownership, org scope)
 - **Migration System** : automatic database migrations at boot - tracks executed scripts in MongoDB - idempotent reruns
 
@@ -197,6 +198,33 @@ Both file types are optional and can be used independently or together. Per-modu
 
 > See [MIGRATIONS.md](MIGRATIONS.md) for the full migration guide from route-level CASL to document-level CASL v2.
 
+## :lock: Signup Access Control (cap + invitations)
+
+Signup is governed by two AND-ed gates in `auth.controller.js`:
+
+- **Capacity** — `config.sign.cap` is a hard ceiling on the **total** number of accounts (invited users included). Once reached, *all* signup is locked.
+- **Eligibility** — `config.sign.up` (public self-serve) **OR** a valid invitation re-opens signup for a specific email.
+
+Invitations are **single-use** and **expiring** (`config.sign.inviteExpiresInDays`, default 14). Local signup carries the token as a query param (`/signup?inviteToken=…`); OAuth signup matches the invite on the provider's verified email.
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `sign.up` | `true` | Public self-serve signup enabled |
+| `sign.cap` | `null` | `null` = unlimited; integer = hard ceiling on total accounts (invited included) |
+| `sign.inviteExpiresInDays` | `14` | Invite link validity (days) |
+
+Common setups:
+- **Invite-only:** `sign.up = false` → only invitation holders can sign up.
+- **Beta cap (e.g. 50):** `sign.cap = 50` → open self-serve until 50 accounts, then locked.
+
+| Method   | Endpoint                                  | Auth      | Description                          |
+| -------- | ----------------------------------------- | --------- | ------------------------------------ |
+| `POST`   | `/api/auth/invitations`                   | JWT+Admin | Create + email a signup invitation   |
+| `GET`    | `/api/auth/invitations`                   | JWT+Admin | List invitations                     |
+| `DELETE` | `/api/auth/invitations/:invitationId`     | JWT+Admin | Revoke an invitation                 |
+| `GET`    | `/api/auth/invitations/verify/:token`     | Public    | Check a token → `{ valid, email }`   |
+| `POST`   | `/api/auth/signup?inviteToken=…`          | Public    | Signup; a valid token bypasses closed signup |
+
 ## :credit_card: Billing — Version Namespace Contract
 
 When `meterMode` is enabled, three values must be aligned so `getPlanByVersion` resolves correctly and plan ratios are applied (not the ratio=1 fallback):

config/templates/signup-invite.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>You've been invited — complete your signup</title>
+  </head>
+  <body>
+    <p>Hello,</p>
+    <p>You've been invited to join <b>{{appName}}</b>.</p>
+    <p>Click here to create your account: <a href="{{url}}">{{url}}</a></p>
+    <p>The <b>{{appName}}</b> Team.</p>
+    <br />
+    <i style="color: #9b9b9b"
+      >If you weren't expecting this invitation you can ignore this email. Please
+      do not reply to this email, you can contact us
+      <a href="mailto:{{appContact}}">here</a>.</i
+    >
+  </body>
+</html>

lib/services/tests/analytics.identify.unit.tests.js

@@ -43,6 +43,19 @@ describe('Analytics identify on auth events:', () => {
           getBrut: jest.fn().mockResolvedValue({ ...mockUser }),
           update: jest.fn().mockResolvedValue(mockUser),
           remove: jest.fn(),
+          count: jest.fn().mockResolvedValue(0),
+        },
+      }));
+
+      jest.unstable_mockModule('../../../modules/auth/services/auth.invitation.service.js', () => ({
+        default: {
+          findValid: jest.fn().mockResolvedValue(null),
+          findValidByEmail: jest.fn().mockResolvedValue(null),
+          consume: jest.fn().mockResolvedValue(null),
+          create: jest.fn(),
+          list: jest.fn(),
+          get: jest.fn(),
+          revoke: jest.fn(),
         },
       }));
 
@@ -227,7 +240,19 @@ describe('Analytics identify on auth events:', () => {
       };
 
       jest.unstable_mockModule('../../../modules/users/services/users.service.js', () => ({
-        default: { getBrut: jest.fn(), update: jest.fn() },
+        default: { getBrut: jest.fn(), update: jest.fn(), count: jest.fn().mockResolvedValue(0) },
+      }));
+
+      jest.unstable_mockModule('../../../modules/auth/services/auth.invitation.service.js', () => ({
+        default: {
+          findValid: jest.fn().mockResolvedValue(null),
+          findValidByEmail: jest.fn().mockResolvedValue(null),
+          consume: jest.fn().mockResolvedValue(null),
+          create: jest.fn(),
+          list: jest.fn(),
+          get: jest.fn(),
+          revoke: jest.fn(),
+        },
       }));
 
       jest.unstable_mockModule('../../../modules/organizations/services/organizations.service.js', () => ({
@@ -331,7 +356,19 @@ describe('Analytics identify on auth events:', () => {
       };
 
       jest.unstable_mockModule('../../../modules/users/services/users.service.js', () => ({
-        default: { getBrut: jest.fn(), update: jest.fn() },
+        default: { getBrut: jest.fn(), update: jest.fn(), count: jest.fn().mockResolvedValue(0) },
+      }));
+
+      jest.unstable_mockModule('../../../modules/auth/services/auth.invitation.service.js', () => ({
+        default: {
+          findValid: jest.fn().mockResolvedValue(null),
+          findValidByEmail: jest.fn().mockResolvedValue(null),
+          consume: jest.fn().mockResolvedValue(null),
+          create: jest.fn(),
+          list: jest.fn(),
+          get: jest.fn(),
+          revoke: jest.fn(),
+        },
       }));
 
       jest.unstable_mockModule('../../../modules/organizations/services/organizations.service.js', () => ({

modules/auth/config/auth.development.config.js

@@ -13,6 +13,8 @@ const config = {
   sign: {
     in: true, // disable signin
     up: true, // disable signup
+    cap: null, // null = unlimited; integer = hard ceiling on TOTAL accounts (invited included)
+    inviteExpiresInDays: 14, // signup invite link validity
   },
   // jwt is for token authentication
   jwt: {

modules/auth/controllers/auth.controller.js

@@ -6,6 +6,7 @@ import passport from 'passport';
 import jwt from 'jsonwebtoken';
 
 import UserService from '../../users/services/users.service.js';
+import InvitationService from '../services/auth.invitation.service.js';
 import config from '../../../config/index.js';
 import model from '../../../lib/middlewares/model.js';
 import mails from '../../../lib/helpers/mailer/index.js';
@@ -64,9 +65,31 @@ const sendVerificationEmail = async (user, verificationToken) => {
  */
 const signup = async (req, res) => {
   try {
-    if (!config.sign.up) return responses.error(res, 404, 'Signup error', 'Registration is currently deactivated')();
+    // Two AND-ed gates: (1) capacity — a hard ceiling on total accounts,
+    // invited users included; (2) eligibility — public signup open OR a valid
+    // invite token (read from query: model.isValid strips unknown body keys).
+    // Short-circuit count() when cap is not set (null = unlimited) to avoid a
+    // collection-wide count on every signup request for uncapped deployments.
+    const cap = config.sign.cap != null ? Number(config.sign.cap) : null;
+    const capReached = cap != null && Number.isFinite(cap) && (await UserService.count()) >= cap;
+    let invite = null;
+    if (req.query?.inviteToken) {
+      invite = await InvitationService.findValid(req.query.inviteToken, req.body.email);
+      // An invite is bound to its email; never honor it for a signup that supplies
+      // no email to match. findValid stays lenient on a falsy email because the
+      // public verify endpoint reuses it, so enforce the pin here.
+      if (invite && invite.email && !req.body.email) invite = null;
+    }
+    if (capReached || (!config.sign.up && !invite)) {
+      return responses.error(res, 404, 'Signup error', 'Registration is currently deactivated')();
+    }
     // Force default role on public signup — clients must not self-assign admin
     const safeBody = { ...req.body, roles: ['user'] };
+    // Invite-gated signup: canonicalize the account email to the invite's pinned
+    // (lowercased) email. Enforces the pin exactly AND makes the case-sensitive
+    // unique-email index a reliable single-use backstop — concurrent case-variant
+    // signups on the same invite collide on the index instead of creating two accounts.
+    if (invite) safeBody.email = invite.email;
     const user = await UserService.create(safeBody);
 
     // Handle email verification — rollback user on failure to avoid orphaned accounts
@@ -122,6 +145,11 @@ const signup = async (req, res) => {
       });
     } catch (_) { /* analytics must not break auth */ }
 
+    // Single-use: consume only when the invite actually opened the gate (signup
+    // was closed, so the invite was required). When signup is open, a token can
+    // be presented but is not required — consuming it would silently burn it.
+    if (invite && !config.sign.up) await InvitationService.consume(invite.id);
+
     const token = jwt.sign({ userId: user.id }, config.jwt.secret, {
       expiresIn: config.jwt.expiresIn,
     });
@@ -404,7 +432,17 @@ const checkOAuthUserProfile = async (profil, key, provider) => {
   }
   // 4. No match → create new user
   try {
-    if (!config.sign.up) {
+    // Same two gates as local signup. OAuth can't carry an invite token through
+    // the redirect, so the invite is matched on the provider's verified email.
+    // Short-circuit count() when cap is not set (null = unlimited).
+    const oauthCap = config.sign.cap != null ? Number(config.sign.cap) : null;
+    const capReached = oauthCap != null && Number.isFinite(oauthCap) && (await UserService.count()) >= oauthCap;
+    // Only honor an OAuth invite when the provider verified the email — otherwise a
+    // provider returning an arbitrary unverified email could open the gate on an
+    // invite meant for someone else.
+    const hasVerifiedProviderEmail = !!(profil.email && profil.emailVerifiedByProvider);
+    const oauthInvite = config.sign.up || !hasVerifiedProviderEmail ? null : await InvitationService.findValidByEmail(profil.email);
+    if (capReached || (!config.sign.up && !oauthInvite)) {
       // Mirror the local signup endpoint's error shape so clients see the same
       // `message`/`description` regardless of signup method (see `signup` above).
       throw new AppError('Signup error', {
@@ -426,7 +464,10 @@ const checkOAuthUserProfile = async (profil, key, provider) => {
     const error = model.checkError(result);
     if (error) throw new AppError('Schema validation error', { code: 'VALIDATION_ERROR', details: { message: error } });
     // else return req.body with the data after Zod validation
-    return await UserService.create(result.value);
+    if (oauthInvite) result.value.email = oauthInvite.email;
+    const createdUser = await UserService.create(result.value);
+    if (oauthInvite) await InvitationService.consume(oauthInvite.id);
+    return createdUser;
   } catch (err) {
     if (err instanceof AppError) throw err;
     throw new AppError('oAuth', { code: 'CONTROLLER_ERROR', details: err.details || err });

modules/auth/controllers/auth.invitation.controller.js

@@ -0,0 +1,92 @@
+/**
+ * Module dependencies
+ */
+import errors from '../../../lib/helpers/errors.js';
+import responses from '../../../lib/helpers/responses.js';
+import InvitationService from '../services/auth.invitation.service.js';
+
+/**
+ * @desc Admin: create + email a signup invitation
+ * @param {Object} req - Express request object
+ * @param {string} req.body.email - Email address to invite
+ * @param {Object} req.user - Authenticated admin user
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>} Sends HTTP 200 with created invitation or 422 on error
+ */
+const create = async (req, res) => {
+  try {
+    const invitation = await InvitationService.create(req.body.email, req.user);
+    responses.success(res, 'invitation created')(invitation);
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', errors.getMessage(err))(err);
+  }
+};
+
+/**
+ * @desc Admin: list all signup invitations
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>} Sends HTTP 200 with invitation array or 422 on error
+ */
+const list = async (req, res) => {
+  try {
+    const invitations = await InvitationService.list();
+    responses.success(res, 'invitation list')(invitations);
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', errors.getMessage(err))(err);
+  }
+};
+
+/**
+ * @desc Admin: revoke an invitation
+ * @param {Object} req - Express request object
+ * @param {Object} req.invitation - Loaded invitation document (set by invitationByID middleware)
+ * @param {string} req.invitation.id - Invitation id
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>} Sends HTTP 200 with deleted id or 422 on error
+ */
+const remove = async (req, res) => {
+  try {
+    await InvitationService.revoke(req.invitation.id);
+    responses.success(res, 'invitation deleted')({ id: req.invitation.id });
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', errors.getMessage(err))(err);
+  }
+};
+
+/**
+ * @desc Public: report whether a token is a valid invite (+ prefill email)
+ * @param {Object} req - Express request object
+ * @param {string} req.params.token - Invitation token to verify
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>} Sends HTTP 200 with { valid, email } or 422 on error
+ */
+const verify = async (req, res) => {
+  try {
+    const invite = await InvitationService.findValid(req.params.token);
+    responses.success(res, 'invitation verify')({ valid: !!invite, email: invite ? invite.email : null });
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', errors.getMessage(err))(err);
+  }
+};
+
+/**
+ * @desc Middleware to load an invitation into req.invitation by id param
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @param {string} id - Invitation id from URL param
+ * @returns {Promise<void>} Calls next() with invitation on req, or sends 404
+ */
+const invitationByID = async (req, res, next, id) => {
+  try {
+    const invitation = await InvitationService.get(id);
+    if (!invitation) return responses.error(res, 404, 'Not Found', 'No invitation with that identifier has been found')();
+    req.invitation = invitation;
+    next();
+  } catch (err) {
+    next(err);
+  }
+};
+
+export default { create, list, remove, verify, invitationByID };