@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/access/access-mutation.service.ts

@@ -49,7 +49,7 @@ import { WorkflowDomainError } from '../workflow/workflow.errors.js';
 /** Whether the dialog target is a folder (edit folder access.md) or a file (edit node frontmatter). */
 export type TargetKind = 'folder' | 'file';
 
-/** Bad-request-class mutation failure (invalid principal, unknown group, lockout). */
+/** Bad-request-class mutation failure (invalid principal, unknown plugin, lockout). */
 export class AccessMutationError extends WorkflowDomainError {
   constructor(message: string, status = 400, payload?: Record<string, unknown>) {
     super(message, status, payload);
@@ -305,7 +305,7 @@ export class AccessMutationService {
    * access — not just "is there a removable file entry."
    *
    * For a USER, that distinction matters: effective access includes admin-rescue
-   * on `access.md`/`roles.yaml`, group membership, and the built-in `everyone` —
+   * on `access.md`/`roles.yaml`, plugin membership, and the built-in `everyone` —
    * none of which `grantSources` reports (it is MECE over file-backed
    * direct/ancestor entries only). So we ask the same `canRead/canWrite/
    * canDownload/canOwner` resolver every real access decision uses; if the
@@ -351,7 +351,7 @@ export class AccessMutationService {
    * asynchronously in the route (it needs the roles model). Here we only run the
    * cheap injection/shape validation so a malformed principal never reaches the
    * splice. Role-exists-in-roles.yaml is the route's job (so it can offer
-   * "Create Group" for an unknown group, an admin-only flow).
+   * "Create Plugin" for an unknown plugin, an admin-only flow).
    */
   private assertPrincipalSafe(principal: Principal): void {
     try {

package/src/modules/access/access-splice.ts

@@ -122,7 +122,7 @@ export function validatePrincipal(p: Principal): Principal {
   }
   const role = p.role.trim();
   const canonical = canonicalRoleName(role);
-  if (!canonical) throw new AccessSpliceError('group grant needs a name');
+  if (!canonical) throw new AccessSpliceError('plugin grant needs a name');
   if (
     CONTROL_CHARS.test(role) ||
     role.includes('<') ||
@@ -130,16 +130,16 @@ export function validatePrincipal(p: Principal): Principal {
     role.includes(':') ||
     role.includes('#')
   ) {
-    throw new AccessSpliceError(`invalid group name: ${JSON.stringify(p.role)}`);
+    throw new AccessSpliceError(`invalid plugin name: ${JSON.stringify(p.role)}`);
   }
   // `deny` is never a grantee — it's the denial prefix. `everyone` IS grantable
   // (the built-in public role); the access route restricts it to the read verb.
   if (canonical === 'deny') {
-    throw new AccessSpliceError(`'${role}' is a reserved name and cannot be granted as a group`);
+    throw new AccessSpliceError(`'${role}' is a reserved name and cannot be granted as a plugin`);
   }
   const round = parseAccessEntry(role);
   if (!round.ok || round.entry.kind !== 'role' || round.entry.deny) {
-    throw new AccessSpliceError(`group grant does not round-trip: ${JSON.stringify(p)}`);
+    throw new AccessSpliceError(`plugin grant does not round-trip: ${JSON.stringify(p)}`);
   }
   return { kind: 'role', role };
 }

package/src/modules/access/access.routes.ts

@@ -61,6 +61,8 @@ export function createAccessRoutes(
   eventBus: WorkflowEventBus,
   db: Database,
   kbDirName: string,
+  /** This deployment's configured admins — the break-glass recovery roster. */
+  recoveryAdmins: readonly string[] = [],
 ): express.Router {
   const router = express.Router({ mergeParams: true });
   const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
@@ -69,19 +71,20 @@ export function createAccessRoutes(
     workflowService,
     accessControl,
     kbDirName,
-    DEFAULT_BRANCH,
+    () => DEFAULT_BRANCH,
     eventBus,
+    recoveryAdmins,
   );
 
-  // Roles (groups) are authoritative on the DEFAULT branch — the Roles admin
-  // screen only ever edits roles.yaml there. Resolve the group list from the
+  // Roles (plugins) are authoritative on the DEFAULT branch — the Roles admin
+  // screen only ever edits roles.yaml there. Resolve the plugin list from the
   // default-branch workspace so the share dialog suggests (and the grant route
   // accepts) the same roles the Roles screen manages, regardless of which branch
   // the caller is viewing. People stay branch-local (the caller's own workspace).
-  const defaultBranchGroups = async (): Promise<string[]> => {
+  const defaultBranchPlugins = async (): Promise<string[]> => {
     await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-    const { groups } = await accessControl.kbPrincipals(workspaceIdForBranch(DEFAULT_BRANCH));
-    return groups;
+    const { plugins } = await accessControl.kbPrincipals(workspaceIdForBranch(DEFAULT_BRANCH));
+    return plugins;
   };
 
   // Authentication gate only. Per PLAN §3 the workspace `:id` is a branch
@@ -177,7 +180,7 @@ export function createAccessRoutes(
    *
    * Every access declaration living INSIDE a folder — the descendant
    * `access.md` files and the node frontmatter that override the folder's own
-   * rules for the principals they name. Display-only: the group access surface
+   * rules for the principals they name. Display-only: the plugin access surface
    * shows it so nobody reads a folder's share list as the whole story.
    *
    * Gating is stricter than the sibling `GET /access`, which hands its eligible
@@ -267,9 +270,9 @@ export function createAccessRoutes(
 
   /**
    * GET /api/workspace/:id/access/suggest?q=<query>
-   * Autocomplete for the share dialog. Returns matching groups (roles.yaml role
+   * Autocomplete for the share dialog. Returns matching plugins (roles.yaml role
    * names — resolved from the DEFAULT branch, the authoritative roles source)
-   * and people (branch-local to `:id`). Groups are small + non-sensitive so they
+   * and people (branch-local to `:id`). Plugins are small + non-sensitive so they
    * always show;
    * PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query can't dump the
    * whole directory (email-harvesting guard). People are the union of the
@@ -283,10 +286,10 @@ export function createAccessRoutes(
     const q = (typeof req.query.q === 'string' ? req.query.q : '').trim().toLowerCase();
     const CAP = 15;
     try {
-      const groups = await defaultBranchGroups();
+      const plugins = await defaultBranchPlugins();
       const { people: kbPeople } = await accessControl.kbPrincipals(req.params.id);
 
-      const matchedGroups = groups
+      const matchedPlugins = plugins
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
@@ -311,7 +314,7 @@ export function createAccessRoutes(
           .slice(0, CAP);
       }
 
-      res.json({ groups: matchedGroups, people, peopleWithheld: q.length < 2 });
+      res.json({ plugins: matchedPlugins, people, peopleWithheld: q.length < 2 });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);
@@ -542,19 +545,19 @@ export function createAccessRoutes(
       }
       const { repoRelTarget, kind, principal } = parseMutationBody(req.body);
 
-      // For a group grant, the role must exist in roles.yaml (Slice 1 grants
-      // existing groups only; Create Group is Slice 2). Reject loudly otherwise.
+      // For a plugin grant, the role must exist in roles.yaml (Slice 1 grants
+      // existing plugins only; Create Plugin is Slice 2). Reject loudly otherwise.
       // Validate against the DEFAULT-branch roles (same authoritative source the
       // suggest autocomplete uses) so a default-branch role can't be suggested
       // then rejected here on a feature branch whose roles.yaml has diverged.
       if (principal.kind === 'role') {
-        const groups = await defaultBranchGroups();
-        const known = groups.some((g) => canonicalRoleName(g) === canonicalRoleName(principal.role));
+        const plugins = await defaultBranchPlugins();
+        const known = plugins.some((g) => canonicalRoleName(g) === canonicalRoleName(principal.role));
         if (!known) {
           throw new AccessMutationError(
-            `No group named "${principal.role}". Pick an existing group, or ask an admin to create it.`,
+            `No plugin named "${principal.role}". Pick an existing plugin, or ask an admin to create it.`,
             404,
-            { kind: 'unknown-group', role: principal.role },
+            { kind: 'unknown-plugin', role: principal.role },
           );
         }
         // The built-in `everyone` role is grantable from the share UI for READ
@@ -563,7 +566,7 @@ export function createAccessRoutes(
         // access.md edit.
         if (canonicalRoleName(principal.role) === EVERYONE_CANONICAL && verb !== 'read') {
           throw new AccessMutationError(
-            '"Everyone" can only be granted read access (public). Grant other access levels to specific people or groups.',
+            '"Everyone" can only be granted read access (public). Grant other access levels to specific people or plugins.',
           );
         }
       }
@@ -735,7 +738,7 @@ export function createAccessRoutes(
       // any source left is an `ancestor`. Distinguish "inherited" (still named in
       // an ancestor access.md — offer cascade/deny) from "no removable source
       // here" (nothing named in any file we can edit — a genuine no-op). A
-      // principal who only RESOLVES via a group / everyone / admin-rescue has no
+      // principal who only RESOLVES via a plugin / everyone / admin-rescue has no
       // source at all (it's not their own file entry) and so is correctly a 200
       // no-op: there is nothing to remove here and no Remove was ever offered for
       // them in the dialog. NEVER a silent unchanged-success when there IS a

package/src/modules/access/creator-access.ts

@@ -88,8 +88,8 @@ export interface ICreatorAccess {
 }
 
 /**
- * The splice-safe principal for a creator — exported because group
- * provisioning (`GroupProvisionService`) writes the same `Name <email>`
+ * The splice-safe principal for a creator — exported because plugin
+ * provisioning (`PluginProvisionService`) writes the same `Name <email>`
  * entries into the access.md files it seeds, and two spellings of the same
  * person would read as two people.
  */
@@ -169,9 +169,9 @@ export class CreatorAccessService implements ICreatorAccess {
           warnSkipped(rel, err);
           return null;
         }
-        // NOTE: a direct group folder (`Groups/<Name>`) is no longer special
-        // here. Groups — and personal folders — are made by the dedicated
-        // provisioning endpoint (`GroupProvisionService`), which writes the
+        // NOTE: a direct plugin folder (`Plugins/<Name>`) is no longer special
+        // here. Plugins — and personal folders — are made by the dedicated
+        // provisioning endpoint (`PluginProvisionService`), which writes the
         // full ownership template itself; this generic read-grant only covers
         // ad-hoc folder creation elsewhere in the tree.
         return {

package/src/modules/access/render-roles-yaml.ts

@@ -0,0 +1,65 @@
+import { parseRolesYaml } from './access-control.service.js';
+
+/**
+ * Render a `roles.yaml` granting Admin to each email — the ONE renderer every
+ * generated roles.yaml goes through (empty-remote seeding, the startup
+ * top-up, and the break-glass recovery), so none of them can drift on
+ * validation and each fails with the same actionable message.
+ *
+ * Each email is validated first, because a malformed one renders a file with
+ * no working Admin — SILENTLY: a leading `#` turns the entry into a YAML
+ * comment, an embedded newline breaks the list, an all-whitespace value
+ * renders an empty entry. A bad ADMIN_EMAIL is operator error, and the
+ * callers' fail-closed contracts want a message naming the fix instead of an
+ * un-administrable knowledge base (or a write-validator rejection deep in the
+ * recovery path).
+ */
+export function renderRolesYaml(
+  adminEmails: readonly string[],
+  /**
+   * Provenance comment appended to the header. The seed/top-up default names
+   * where the file came from; recovery passes `null` — claiming "generated at
+   * KB-seed time" on a recovery-restored file would mislead whoever reads it.
+   */
+  provenance: string | null = 'Generated by the Bevel platform at KB-seed time from ADMIN_EMAIL.',
+): string {
+  const emails = adminEmails.map((raw) => {
+    const email = raw.trim();
+    if (email === '') {
+      throw new Error('Seed admin email is empty — set ADMIN_EMAIL to a real address.');
+    }
+    if (email.startsWith('#')) {
+      throw new Error(
+        `Seed admin email ${JSON.stringify(raw)} starts with "#", which YAML reads as a comment — fix ADMIN_EMAIL.`,
+      );
+    }
+    if (/\s/.test(email)) {
+      throw new Error(
+        `Seed admin email ${JSON.stringify(raw)} contains whitespace, which would corrupt roles.yaml — fix ADMIN_EMAIL.`,
+      );
+    }
+    return email;
+  });
+  const lines = emails.map((e) => `    - ${e}`).join('\n');
+  const text =
+    '# Identity → role mapping for access control.\n' +
+    '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
+    '# only Admins may edit this file, and at least one Admin must always exist.\n' +
+    (provenance !== null ? `#\n# ${provenance}\n` : '') +
+    'roles:\n' +
+    '  Admin:\n' +
+    `${lines}\n`;
+  // Validate by PARSING with the real access parser, not by re-implementing
+  // its email grammar: whatever the parser would reject (a `<Name <email>`
+  // shape, a non-email string, tomorrow's new rule) must fail here, before an
+  // un-administrable roles.yaml gets committed. The checks above exist only
+  // to give the common mistakes sharper messages.
+  const parsed = parseRolesYaml(text);
+  if (!parsed.ok) {
+    throw new Error(
+      `Generated roles.yaml from ADMIN_EMAIL would not parse — fix the configured address(es). ` +
+        parsed.errors.join('; '),
+    );
+  }
+  return text;
+}

package/src/modules/access/roles-admin.service.ts

@@ -54,6 +54,7 @@ import {
   parseAccessEntry,
 } from './access-control.service.js';
 import { makeRolesYamlWriteValidator } from './roles-yaml-guard.js';
+import { renderRolesYaml } from './render-roles-yaml.js';
 import {
   parseRolesModel,
   createRole as editCreateRole,
@@ -92,20 +93,21 @@ const ROLES_YAML = 'roles.yaml';
 const OLD_ROLES_YAML = 'old-roles.yaml';
 
 /**
- * The known-good `roles.yaml` the break-glass recovery restores. Mirrors the
- * canonical Bevel roster — it is the ONLY content recovery ever writes, so it
- * MUST parse (the post-recovery resolver loads it immediately). Keep the Admin
- * list in sync with the canonical `osapiens-kb/roles.yaml`.
+ * The known-good `roles.yaml` the break-glass recovery restores — generated
+ * from THIS deployment's configured admins, exactly like ordinary seeding
+ * (`ADMIN_EMAIL`), never a roster baked into the build: hard-coded emails
+ * would land one company's admins in every customer's recovered file. It is
+ * the ONLY content recovery ever writes, so it MUST parse (the post-recovery
+ * resolver loads it immediately) — guaranteed by delegating to the shared
+ * validated renderer, which parse-backs its output and throws an actionable
+ * message on a malformed ADMIN_EMAIL (instead of the write-validator
+ * rejecting the finished file deep in the write path). `null` provenance:
+ * the seed-time "generated at KB-seed time" comment would mislead on a
+ * recovery-restored file.
  */
-const RECOVERY_DEFAULT_ROLES_YAML = `# Identity → role mapping for access control.
-# Role names are case- and whitespace-insensitive. The \`Admin\` role is special:
-# only Admins may edit this file, and at least one Admin must always exist.
-roles:
-  Admin:
-    - razvan.radulescu@bevel.software
-    - ali.raza@bevel.software
-    - juan@bevel.software
-`;
+function renderRecoveryRolesYaml(admins: readonly string[]): string {
+  return renderRolesYaml(admins, null);
+}
 
 /** Health of the default-branch roles.yaml: does the resolver's parser accept it? */
 export interface RolesConfigHealth {
@@ -119,8 +121,14 @@ export class RolesAdminService {
     private readonly workflowService: IWorkflowService,
     private readonly accessControl: IAccessControl,
     private readonly kbDirName: string,
-    /** The branch whose roles.yaml is authoritative for admin status. */
-    private readonly defaultBranch: string,
+    /**
+     * The branch whose roles.yaml is authoritative for admin status, read
+     * through a thunk rather than taken by value. `DEFAULT_BRANCH` is an ES
+     * module live binding that stays empty until `configureBranchModel()` runs
+     * at boot; a service constructed before that would freeze the empty string
+     * and every roles route would fail branch validation until a restart.
+     */
+    private readonly defaultBranchOf: () => string,
     /**
      * Optional so existing tests can construct the service without an event
      * bus. When present, every committed write announces itself so already-open
@@ -129,8 +137,20 @@ export class RolesAdminService {
      * open tab keeps a now-stale read verdict until a manual reload.
      */
     private readonly eventBus?: WorkflowEventBus,
+    /**
+     * This deployment's configured admins (`ADMIN_EMAIL`), the roster the
+     * break-glass recovery restores. Recovery refuses outright when empty: a
+     * recovered roles.yaml with no Admin is exactly the unusable state
+     * recovery exists to escape.
+     */
+    private readonly recoveryAdmins: readonly string[] = [],
   ) {}
 
+  /** Resolved per call — see the constructor note on `defaultBranchOf`. */
+  private get defaultBranch(): string {
+    return this.defaultBranchOf();
+  }
+
   private get workspaceId(): string {
     return workspaceIdForBranch(this.defaultBranch);
   }
@@ -329,6 +349,15 @@ export class RolesAdminService {
       );
     }
 
+    if (this.recoveryAdmins.length === 0) {
+      throw new RolesAdminError(
+        'Recovery needs a configured admin (ADMIN_EMAIL) to restore — a roles.yaml ' +
+          'with no Admin is exactly the unusable state recovery exists to escape.',
+        500,
+        { kind: 'no-recovery-admins' },
+      );
+    }
+
     await this.assertRolesUnlocked(workspaceId, actor);
 
     // Back up the corrupted bytes and restore the good default atomically. The
@@ -338,7 +367,7 @@ export class RolesAdminService {
       fsys.writeFiles(
         [
           { path: `${this.kbDirName}/${OLD_ROLES_YAML}`, content: current },
-          { path: `${this.kbDirName}/${ROLES_YAML}`, content: RECOVERY_DEFAULT_ROLES_YAML },
+          { path: `${this.kbDirName}/${ROLES_YAML}`, content: renderRecoveryRolesYaml(this.recoveryAdmins) },
         ],
         'Bevel recovery: reset corrupted roles.yaml',
       ),

package/src/modules/admin/admin-access.routes.ts

@@ -1,29 +1,29 @@
-import express from 'express';
-import type { IAdminAccessService } from './admin.interface.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
-
-/**
- * The CORE slice of the admin surface: just the admin-status resolver the
- * frontend branches on (AdminMenu's "Admin only" section, the roles-recovery
- * banner). The full admin router (feedback inbox, user administration /
- * GDPR erasure) is an enterprise extension mounted via
- * `ServerExtensions.authed`.
- *
- * NOTE (core split): in bevel-platform this endpoint lives in the enterprise
- * `admin.routes.ts`; core serves it itself so a core-only deployment can
- * resolve admin status. Express keeps first-match-wins, so an enterprise
- * overlay's own `/admin/access` (mounted later) never shadows this one —
- * both resolve through the same {@link IAdminAccessService}.
- */
-export function createAdminAccessRoutes(adminAccess: IAdminAccessService): express.Router {
-  const router = express.Router();
-
-  // Open to any authenticated user — returns `false` for non-admins instead of
-  // 403 so the frontend can branch on the answer without treating a normal
-  // user as an error case.
-  router.get('/admin/access', async (req, res) => {
-    res.json({ isAdmin: await adminAccess.isAdmin(req.userEmail) });
-  });
-
-  return router;
-}
+import express from 'express';
+import type { IAdminAccessService } from './admin.interface.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+/**
+ * The CORE slice of the admin surface: just the admin-status resolver the
+ * frontend branches on (AdminMenu's "Admin only" section, the roles-recovery
+ * banner). The full admin router (feedback inbox, user administration /
+ * GDPR erasure) is an enterprise extension mounted via
+ * `ServerExtensions.authed`.
+ *
+ * NOTE (core split): in bevel-platform this endpoint lives in the enterprise
+ * `admin.routes.ts`; core serves it itself so a core-only deployment can
+ * resolve admin status. Express keeps first-match-wins, so an enterprise
+ * overlay's own `/admin/access` (mounted later) never shadows this one —
+ * both resolve through the same {@link IAdminAccessService}.
+ */
+export function createAdminAccessRoutes(adminAccess: IAdminAccessService): express.Router {
+  const router = express.Router();
+
+  // Open to any authenticated user — returns `false` for non-admins instead of
+  // 403 so the frontend can branch on the answer without treating a normal
+  // user as an error case.
+  router.get('/admin/access', async (req, res) => {
+    res.json({ isAdmin: await adminAccess.isAdmin(req.userEmail) });
+  });
+
+  return router;
+}

package/src/modules/auth/__tests__/auth.routes.test.ts

@@ -1,91 +1,91 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import express from 'express';
-import type { Server } from 'node:http';
-import { createAuthRoutes } from '../auth.routes.js';
-import type { AuthService } from '../auth.service.js';
-
-const authService = {
-  loginWithPassword: vi.fn(async () => {
-    throw new Error('Invalid credentials');
-  }),
-  changePassword: vi.fn(async () => {
-    throw new Error('Current password is incorrect');
-  }),
-  getUserById: vi.fn(async () => null),
-} as unknown as AuthService;
-
-const fakeAuthMiddleware: express.RequestHandler = (req, _res, next) => {
-  req.userId = 'user-1';
-  req.userEmail = 'alice@example.com';
-  next();
-};
-
-let server: Server;
-beforeEach(() => {
-  vi.mocked(authService.loginWithPassword).mockClear();
-});
-afterEach(() => {
-  server?.close();
-});
-
-async function listen(): Promise<string> {
-  const app = express();
-  app.use(express.json());
-  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
-  await new Promise<void>((resolve) => {
-    server = app.listen(0, resolve);
-  });
-  const address = server.address();
-  if (typeof address === 'string' || !address) throw new Error('no port');
-  return `http://127.0.0.1:${address.port}`;
-}
-
-function postLogin(base: string, email: string, password = 'wrong') {
-  return fetch(`${base}/api/auth/login`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email, password }),
-  });
-}
-
-describe('auth routes — rate limiting', () => {
-  it('429s login for an (ip, email) pair after repeated failures; other emails unaffected', async () => {
-    const base = await listen();
-    for (let i = 0; i < 10; i++) {
-      expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
-    }
-    const limited = await postLogin(base, 'alice@example.com');
-    expect(limited.status).toBe(429);
-    // The service is not even consulted once the limit is hit.
-    expect(authService.loginWithPassword).toHaveBeenCalledTimes(10);
-    // A different email from the same address still has pair budget (the
-    // wider per-ip budget is 50).
-    expect((await postLogin(base, 'bob@example.com')).status).toBe(401);
-  });
-
-  it('a successful login resets the pair budget', async () => {
-    const base = await listen();
-    for (let i = 0; i < 9; i++) await postLogin(base, 'alice@example.com');
-    vi.mocked(authService.loginWithPassword).mockResolvedValueOnce({
-      token: 'jwt',
-      user: { id: 'user-1', email: 'alice@example.com', name: 'Alice' },
-    });
-    expect((await postLogin(base, 'alice@example.com', 'right')).status).toBe(200);
-    // Budget is fresh again — failures start counting from zero.
-    expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
-  });
-
-  it('429s change-password per account after repeated failures', async () => {
-    const base = await listen();
-    const post = () =>
-      fetch(`${base}/api/auth/change-password`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ currentPassword: 'wrong', newPassword: 'new-password-1' }),
-      });
-    for (let i = 0; i < 10; i++) {
-      expect((await post()).status).toBe(400);
-    }
-    expect((await post()).status).toBe(429);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAuthRoutes } from '../auth.routes.js';
+import type { AuthService } from '../auth.service.js';
+
+const authService = {
+  loginWithPassword: vi.fn(async () => {
+    throw new Error('Invalid credentials');
+  }),
+  changePassword: vi.fn(async () => {
+    throw new Error('Current password is incorrect');
+  }),
+  getUserById: vi.fn(async () => null),
+} as unknown as AuthService;
+
+const fakeAuthMiddleware: express.RequestHandler = (req, _res, next) => {
+  req.userId = 'user-1';
+  req.userEmail = 'alice@example.com';
+  next();
+};
+
+let server: Server;
+beforeEach(() => {
+  vi.mocked(authService.loginWithPassword).mockClear();
+});
+afterEach(() => {
+  server?.close();
+});
+
+async function listen(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+function postLogin(base: string, email: string, password = 'wrong') {
+  return fetch(`${base}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+}
+
+describe('auth routes — rate limiting', () => {
+  it('429s login for an (ip, email) pair after repeated failures; other emails unaffected', async () => {
+    const base = await listen();
+    for (let i = 0; i < 10; i++) {
+      expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+    }
+    const limited = await postLogin(base, 'alice@example.com');
+    expect(limited.status).toBe(429);
+    // The service is not even consulted once the limit is hit.
+    expect(authService.loginWithPassword).toHaveBeenCalledTimes(10);
+    // A different email from the same address still has pair budget (the
+    // wider per-ip budget is 50).
+    expect((await postLogin(base, 'bob@example.com')).status).toBe(401);
+  });
+
+  it('a successful login resets the pair budget', async () => {
+    const base = await listen();
+    for (let i = 0; i < 9; i++) await postLogin(base, 'alice@example.com');
+    vi.mocked(authService.loginWithPassword).mockResolvedValueOnce({
+      token: 'jwt',
+      user: { id: 'user-1', email: 'alice@example.com', name: 'Alice' },
+    });
+    expect((await postLogin(base, 'alice@example.com', 'right')).status).toBe(200);
+    // Budget is fresh again — failures start counting from zero.
+    expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+  });
+
+  it('429s change-password per account after repeated failures', async () => {
+    const base = await listen();
+    const post = () =>
+      fetch(`${base}/api/auth/change-password`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ currentPassword: 'wrong', newPassword: 'new-password-1' }),
+      });
+    for (let i = 0; i < 10; i++) {
+      expect((await post()).status).toBe(400);
+    }
+    expect((await post()).status).toBe(429);
+  });
+});