feat(admin): bulk user import for migrations (#340)

* feat(admin): bulk user import for migrations

Adds POST /admin/users/import and the user_external_ids table. Rows are
matched on the source system id and then on email, applied one at a time,
and only ever add roles and memberships. Admin roles are refused and an
existing account's email is never changed.

Closes #336

* fix(admin): do not link an external id to an existing administrator on import

* chore(deps): bump @seamless-auth/types to 0.24.0

---------

Co-authored-by: Brandon Corbett <Bccorb@users.noreply.github.com>

Author: Bccorb

.changeset/admin-user-import.md

@@ -0,0 +1,9 @@
+---
+'seamless-auth-api': minor
+---
+
+Add `POST /admin/users/import` for moving users across from another identity system. It takes up to 200 rows per request, matches each on the source system's id and then on email, and applies each row on its own so one rejected row does not stop the batch. `dryRun` reports the outcome without writing.
+
+Imports carry no credentials: an imported user stays unverified until they register with the imported email. Roles and organization memberships are only ever added, an existing account's email is never changed, admin roles are refused, and an external id is never linked to an existing account that holds an admin role. Each created or updated account is recorded as `admin_user_imported` and each batch as `admin_user_import_completed`, against the acting admin.
+
+Adds the `user_external_ids` table (migration `20261005120000`). Requires `@seamless-auth/types` 0.24.0.

openapi.json

@@ -52,7 +52,7 @@
     "@seamless-auth/messaging": "^0.1.0",
     "@seamless-auth/messaging-aws": "^0.1.0",
     "@seamless-auth/messaging-twilio": "^0.1.0",
-    "@seamless-auth/types": "^0.22.0",
+    "@seamless-auth/types": "^0.24.0",
     "@simplewebauthn/server": "^13.3.3",
     "base64url": "^3.0.1",
     "bcrypt-ts": "^9.0.2",

package-lock.json

@@ -19,6 +19,7 @@ import { AdminUserListQuerySchema } from '../schemas/admin.query.js';
 import {
   CreateUserSchema,
   DeviceReplacementRecoverySchema,
+  ImportUsersRequestSchema,
   UpdateUserSchema,
 } from '../schemas/admin.requests.js';
 import { authEventTypesFor, SUSPICIOUS_EVENT_TYPES } from '../schemas/authEvent.types.js';
@@ -31,6 +32,7 @@ import {
 import { serializeAuthEvents } from '../services/authEventSerialization.js';
 import { AuthEventService } from '../services/authEventService.js';
 import { hardRevokeSession } from '../services/sessionService.js';
+import { importUsers as runUserImport } from '../services/userImportService.js';
 import type { AuthenticatedRequest } from '../types/types.js';
 import { RouteRequest, ServiceRequest } from '../types/types.js';
 import getLogger from '../utils/logger.js';
@@ -179,6 +181,42 @@ export const createUser = async (req: Request, res: Response) => {
   }
 };
 
+export const importUsers = async (req: Request, res: Response) => {
+  const request = ImportUsersRequestSchema.parse(req.body);
+  const response = await runUserImport(request);
+
+  if (!response.dryRun) {
+    const actorUserId = actingAdminId(req);
+
+    for (const result of response.results) {
+      if (result.status !== 'created' && result.status !== 'updated') continue;
+
+      await AuthEventService.log({
+        userId: result.userId ?? null,
+        actorUserId,
+        subjectEmail: result.email,
+        type: 'admin_user_imported',
+        req,
+        metadata: {
+          source: response.source,
+          status: result.status,
+          changes: result.changes ?? [],
+          ...(result.externalId ? { externalId: result.externalId } : {}),
+        },
+      });
+    }
+
+    await AuthEventService.log({
+      actorUserId,
+      type: 'admin_user_import_completed',
+      req,
+      metadata: { source: response.source, summary: response.summary },
+    });
+  }
+
+  return res.status(200).json(response);
+};
+
 export const deleteUser = async (req: ServiceRequest, res: Response) => {
   logger.info('Internal deletion call made.');
   const { userId } = req.body ?? {};