@fonderie/auth 7.7.4 → 7.8.0

package/brain/outcomes.md

@@ -136,6 +136,13 @@ Raw SQL ships in `node_modules/@fonderie/auth/dist/migrations/sql/` — read it
 
 | Method | Path | Middleware chain (auth / validation / handler) |
 |---|---|---|
+| GET | `/_admin/users` | `async (ctx) => { const email = new URL(ctx.request.url).searchParams.get('email')?.trim().toLowerCase(); if (!email) return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID_PARAMETER', 'email is required'); const user = await users.findByEmail(email); return user ? setApiResponse(HTTP.OK, 'USER', 'User', toAdminUserDTO(user)) : NOT_FOUND(); }` |
+| GET | `/_admin/users/:id` | `async (ctx) => { const user = await users.findById(idOf(ctx)); return user ? setApiResponse(HTTP.OK, 'USER', 'User', toAdminUserDTO(user)) : NOT_FOUND(); }` |
+| GET | `/_admin/users/:id/login-history` | `async (ctx) => { if (!(await users.findById(idOf(ctx)))) return NOT_FOUND(); const params = new URL(ctx.request.url).searchParams; const rawLimit = Number(params.get('limit') ?? 50); const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.trunc(rawLimit), 1), 200) : 50; const cursorParam = params.get('cursor'); const cursor = cursorParam ? decodeLoginCursor(cursorParam) : null; if (cursorParam && !cursor) return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID_PARAMETER', 'Invalid cursor'); const page = await events.listByUser({ userId: idOf(ctx), limit, ...(cursor ? { cursor } : {}), }); return setApiResponse( HTTP.OK, 'LOGIN_HISTORY', 'Login history', toLoginHistoryPageDTO(page), ); }` |
+| DELETE | `/_admin/users/:id/sessions` | `async (ctx) => { if (!(await users.findById(idOf(ctx)))) return NOT_FOUND(); await sessions.deleteByUser(idOf(ctx)); return setApiResponse(HTTP.OK, 'SESSIONS_REVOKED', 'All sessions revoked'); }` |
+| GET | `/_admin/users/:id/sessions` | `async (ctx) => { if (!(await users.findById(idOf(ctx)))) return NOT_FOUND(); const rows = await sessions.listLiveByUser(idOf(ctx)); return setApiResponse( HTTP.OK, 'SESSIONS', 'Live sessions', rows.map((r) => toSessionDTO(r, null)), ); }` |
+| POST | `/_admin/users/:id/suspend` | `setSuspended(true)` |
+| POST | `/_admin/users/:id/unsuspend` | `setSuspended(false)` |
 | GET | `/auth/apple` | `oauth.appleInit` |
 | POST | `/auth/apple/callback` | `ipLimit('login') → oauth.appleCallback` |
 | POST | `/auth/apple/native` | `ipLimit('login') → validate(appleNativeSchema) → oauth.appleNative` |

package/brain/signatures.md

@@ -50,6 +50,7 @@ interface IMfaChallenge {
 
 new AuthModule(store: IStoreAdapter, config: IAuthConfig, bus?: EventBus | undefined): AuthModule
   .name: "@fonderie/auth"
+  .describeAdmin(): IAdminDescription
   .checkReadiness(): IReadinessProblem[]
   .install(app: IFonderieApp): void
 
@@ -216,4 +217,14 @@ interface IAuthRateLimitConfig {
 }
 
 type AuthLimitedRoute = 'login' | 'register' | 'forgot' | 'reset' | 'verify' | 'mfaVerify';
+
+interface IAdminUserDTO extends IUserDTO {
+    suspended: boolean;
+    deletedAt: string | null;
+    createdAt: string;
+}
+
+function describeAuthAdminRoutes(store: IStoreAdapter): IAdminRoute[]
+
+function toAdminUserDTO(user: IUser): IAdminUserDTO
 ```

package/dist/index.cjs

@@ -74,6 +74,7 @@ __export(index_exports, {
   MESSAGE_KEYS: () => MESSAGE_KEYS,
   buildAuthAccountLimiter: () => buildAuthAccountLimiter,
   buildAuthIpLimiter: () => buildAuthIpLimiter,
+  describeAuthAdminRoutes: () => describeAuthAdminRoutes,
   importUser: () => importUser,
   normalizeEmail: () => normalizeEmail,
   normalizeEmailSafe: () => normalizeEmailSafe,
@@ -81,6 +82,7 @@ __export(index_exports, {
   requireAuth: () => import_middlewares3.requireAuth,
   schemas: () => schemas_exports,
   startUserRetention: () => startUserRetention,
+  toAdminUserDTO: () => toAdminUserDTO,
   toUserDTO: () => toUserDTO,
   validate: () => import_middlewares.validate,
   validateAuthConfig: () => validateAuthConfig,
@@ -686,6 +688,15 @@ var UserModel = class {
       [id]
     );
   }
+  // The operator's lock: login, refresh and the session middleware all refuse a
+  // suspended user. Returns false when there is no such user.
+  async setSuspended(id, suspended) {
+    const rows = await this.store.query(
+      `UPDATE fonderie_users SET suspended = $2, updated_at = now() WHERE id = $1 AND deleted_at IS NULL RETURNING id`,
+      [id, suspended]
+    );
+    return rows.length > 0;
+  }
   async softDelete(id) {
     await this.store.query(
       `UPDATE fonderie_users SET deleted_at = now(), updated_at = now() WHERE id = $1`,
@@ -3222,6 +3233,115 @@ function extractToken(request) {
   return match?.[1] ?? null;
 }
 
+// src/admin.ts
+var import_core12 = require("@fonderie/core");
+function toAdminUserDTO(user) {
+  return {
+    ...toUserDTO(user),
+    suspended: Boolean(user.suspended),
+    deletedAt: user.deletedAt ? user.deletedAt.toISOString() : null,
+    createdAt: user.createdAt.toISOString()
+  };
+}
+var ADMIN_PREFIX = "/_admin";
+var idOf = (ctx) => ctx.meta.params?.["id"] ?? "";
+var NOT_FOUND = () => (0, import_core12.setApiResponse)(import_core12.HTTP.NOT_FOUND, "NOT_FOUND", "No such user");
+function adminRouteTable(store) {
+  const users = new UserModel(store);
+  const sessions = new SessionModel(store);
+  const events = new LoginEventModel(store);
+  const setSuspended = (suspended) => async (ctx) => {
+    const ok = await users.setSuspended(idOf(ctx), suspended);
+    if (!ok) return NOT_FOUND();
+    const user = await users.findById(idOf(ctx));
+    return user ? (0, import_core12.setApiResponse)(
+      import_core12.HTTP.OK,
+      suspended ? "USER_SUSPENDED" : "USER_UNSUSPENDED",
+      suspended ? "User suspended" : "User unsuspended",
+      toAdminUserDTO(user)
+    ) : NOT_FOUND();
+  };
+  return [
+    [
+      "GET",
+      "/_admin/users",
+      async (ctx) => {
+        const email2 = new URL(ctx.request.url).searchParams.get("email")?.trim().toLowerCase();
+        if (!email2)
+          return (0, import_core12.setApiResponse)(import_core12.HTTP.UNPROCESSABLE, "INVALID_PARAMETER", "email is required");
+        const user = await users.findByEmail(email2);
+        return user ? (0, import_core12.setApiResponse)(import_core12.HTTP.OK, "USER", "User", toAdminUserDTO(user)) : NOT_FOUND();
+      }
+    ],
+    [
+      "GET",
+      "/_admin/users/:id",
+      async (ctx) => {
+        const user = await users.findById(idOf(ctx));
+        return user ? (0, import_core12.setApiResponse)(import_core12.HTTP.OK, "USER", "User", toAdminUserDTO(user)) : NOT_FOUND();
+      }
+    ],
+    [
+      "GET",
+      "/_admin/users/:id/sessions",
+      async (ctx) => {
+        if (!await users.findById(idOf(ctx))) return NOT_FOUND();
+        const rows = await sessions.listLiveByUser(idOf(ctx));
+        return (0, import_core12.setApiResponse)(
+          import_core12.HTTP.OK,
+          "SESSIONS",
+          "Live sessions",
+          rows.map((r) => toSessionDTO(r, null))
+        );
+      }
+    ],
+    // Signs the user out everywhere. The one write support reaches for first.
+    [
+      "DELETE",
+      "/_admin/users/:id/sessions",
+      async (ctx) => {
+        if (!await users.findById(idOf(ctx))) return NOT_FOUND();
+        await sessions.deleteByUser(idOf(ctx));
+        return (0, import_core12.setApiResponse)(import_core12.HTTP.OK, "SESSIONS_REVOKED", "All sessions revoked");
+      }
+    ],
+    [
+      "GET",
+      "/_admin/users/:id/login-history",
+      async (ctx) => {
+        if (!await users.findById(idOf(ctx))) return NOT_FOUND();
+        const params = new URL(ctx.request.url).searchParams;
+        const rawLimit = Number(params.get("limit") ?? 50);
+        const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.trunc(rawLimit), 1), 200) : 50;
+        const cursorParam = params.get("cursor");
+        const cursor = cursorParam ? decodeLoginCursor(cursorParam) : null;
+        if (cursorParam && !cursor)
+          return (0, import_core12.setApiResponse)(import_core12.HTTP.UNPROCESSABLE, "INVALID_PARAMETER", "Invalid cursor");
+        const page = await events.listByUser({
+          userId: idOf(ctx),
+          limit,
+          ...cursor ? { cursor } : {}
+        });
+        return (0, import_core12.setApiResponse)(
+          import_core12.HTTP.OK,
+          "LOGIN_HISTORY",
+          "Login history",
+          toLoginHistoryPageDTO(page)
+        );
+      }
+    ],
+    ["POST", "/_admin/users/:id/suspend", setSuspended(true)],
+    ["POST", "/_admin/users/:id/unsuspend", setSuspended(false)]
+  ];
+}
+function describeAuthAdminRoutes(store) {
+  return adminRouteTable(store).map(([method, path, h]) => ({
+    method,
+    path: path.slice(ADMIN_PREFIX.length),
+    handlers: [h]
+  }));
+}
+
 // src/module.ts
 var AuthModule = class {
   constructor(store, config, bus) {
@@ -3234,6 +3354,10 @@ var AuthModule = class {
   config;
   bus;
   name = "@fonderie/auth";
+  // Users, sessions, login history, suspend — only through @fonderie/admin.
+  describeAdmin() {
+    return { routes: describeAuthAdminRoutes(this.store) };
+  }
   // Report config problems for app.checkProductionReadiness() (data, not throw).
   checkReadiness() {
     return collectAuthConfigProblems(this.config);
@@ -3501,6 +3625,7 @@ function startUserRetention(store, options) {
   MESSAGE_KEYS,
   buildAuthAccountLimiter,
   buildAuthIpLimiter,
+  describeAuthAdminRoutes,
   importUser,
   normalizeEmail,
   normalizeEmailSafe,
@@ -3508,6 +3633,7 @@ function startUserRetention(store, options) {
   requireAuth,
   schemas,
   startUserRetention,
+  toAdminUserDTO,
   toUserDTO,
   validate,
   validateAuthConfig,