@portaidentity/server 1.7.0

package/dist/routes/user-roles.js

@@ -0,0 +1,129 @@
+/**
+ * User-role assignment API routes.
+ *
+ * All routes are under `/api/admin/organizations/:orgId/users/:userId/roles`
+ * and require admin authorization with granular permissions. Provides
+ * endpoints for managing role assignments on a per-user basis and
+ * resolving effective permissions.
+ *
+ * Route structure:
+ *   GET    /              — List roles for a user
+ *   PUT    /              — Assign roles to a user
+ *   DELETE /              — Remove roles from a user
+ *   GET    /permissions   — List resolved permissions for a user
+ *
+ * Error mapping:
+ *   RoleNotFoundError → 404
+ *   RbacValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+import { z } from 'zod';
+import { requireAdminAuth } from '../middleware/admin-auth.js';
+import { requirePermission } from '../middleware/require-permission.js';
+import { requireUserOrganization } from '../middleware/require-user-organization.js';
+import { ADMIN_PERMISSIONS } from '../lib/admin-permissions.js';
+import { guardSuperAdmin } from '../lib/super-admin-protection.js';
+import * as userRoleService from '../rbac/user-role-service.js';
+import { RoleNotFoundError, RbacValidationError } from '../rbac/errors.js';
+// ---------------------------------------------------------------------------
+// Validation schemas
+// ---------------------------------------------------------------------------
+/** Schema for assigning/removing roles (array of UUIDs) */
+const roleIdsSchema = z.object({
+    roleIds: z.array(z.string().uuid()).min(1),
+});
+// ---------------------------------------------------------------------------
+// Error handler helper
+// ---------------------------------------------------------------------------
+/**
+ * Handle domain errors and map them to HTTP responses.
+ * Unknown errors are re-thrown for the global error handler.
+ */
+function handleError(ctx, err) {
+    if (err instanceof RoleNotFoundError) {
+        ctx.throw(404, 'Role not found');
+    }
+    if (err instanceof RbacValidationError) {
+        ctx.throw(400, 'Role assignment request is invalid');
+    }
+    if (err instanceof z.ZodError) {
+        ctx.status = 400;
+        ctx.body = { error: 'Role assignment request is invalid' };
+        return undefined;
+    }
+    throw err;
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the user-role assignment router.
+ *
+ * All routes require admin authorization with granular permissions.
+ * User-role assignments are scoped to a user within an organization
+ * via :orgId and :userId URL parameters.
+ *
+ * Prefix: /api/admin/organizations/:orgId/users/:userId/roles
+ *
+ * @returns Configured Koa Router
+ */
+export function createUserRoleRouter() {
+    const router = new Router({ prefix: '/api/admin/organizations/:orgId/users/:userId/roles' });
+    // All routes require admin authentication
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // GET / — List roles for user
+    // -------------------------------------------------------------------------
+    router.get('/', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), requireUserOrganization(), async (ctx) => {
+        try {
+            const roles = await userRoleService.getUserRoles(ctx.params.userId);
+            ctx.body = { data: roles };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // PUT / — Assign roles to user
+    // -------------------------------------------------------------------------
+    router.put('/', requirePermission(ADMIN_PERMISSIONS.ROLE_ASSIGN), requireUserOrganization(), async (ctx) => {
+        try {
+            const body = roleIdsSchema.parse(ctx.request.body);
+            await userRoleService.assignRolesToUser(ctx.params.userId, body.roleIds);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // DELETE / — Remove roles from user
+    // -------------------------------------------------------------------------
+    router.delete('/', requirePermission(ADMIN_PERMISSIONS.ROLE_ASSIGN), requireUserOrganization(), async (ctx) => {
+        try {
+            const body = roleIdsSchema.parse(ctx.request.body);
+            await guardSuperAdmin(ctx.params.userId, 'remove-super-admin-role');
+            await userRoleService.removeRolesFromUser(ctx.params.userId, body.roleIds);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /permissions — List resolved permissions for user
+    // Resolves all permissions across all assigned roles (deduplicated)
+    // -------------------------------------------------------------------------
+    router.get('/permissions', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), requireUserOrganization(), async (ctx) => {
+        try {
+            const permissions = await userRoleService.getUserPermissions(ctx.params.userId);
+            ctx.body = { data: permissions };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=user-roles.js.map

package/dist/routes/user-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-roles.js","sourceRoot":"","sources":["../../src/routes/user-roles.ts"],"names":[],"mappings":"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"}

package/dist/routes/users.d.ts

@@ -0,0 +1,61 @@
+/**
+ * User management API routes.
+ *
+ * All routes are under `/api/admin/organizations/:orgId/users` and
+ * require admin authorization with granular permissions. User routes
+ * are nested under an organization context because users are always
+ * scoped to an org.
+ *
+ * Route structure:
+ *   POST   /                     — Create a user in the organization
+ *   GET    /                     — List users (paginated, searchable)
+ *   GET    /:userId              — Get user by ID
+ *   PUT    /:userId              — Update user profile
+ *   POST   /:userId/deactivate   — Deactivate (active → inactive)
+ *   POST   /:userId/reactivate   — Reactivate (inactive → active)
+ *   POST   /:userId/suspend      — Suspend (active → suspended)
+ *   POST   /:userId/unsuspend    — Unsuspend (suspended → active)
+ *   POST   /:userId/lock         — Lock (active → locked)
+ *   POST   /:userId/unlock       — Unlock (locked → active)
+ *   POST   /:userId/password     — Set/change password
+ *   DELETE /:userId/password     — Clear password (passwordless)
+ *   POST   /:userId/verify-email — Mark email as verified
+ *   GET    /:userId/export       — GDPR data export (Article 20)
+ *   POST   /:userId/purge        — GDPR data purge (Article 17)
+ *
+ * Error mapping:
+ *   UserNotFoundError → 404
+ *   UserValidationError → 400
+ *   SuperAdminProtectionError → 403
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+/**
+ * Create the user management router.
+ *
+ * All routes require admin authorization with granular permissions.
+ * Users are always scoped to an organization via the :orgId URL parameter.
+ * Destructive operations on the super-admin user are blocked by
+ * guardSuperAdmin() checks.
+ *
+ * Prefix: /api/admin/organizations/:orgId/users
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createUserRouter(): Router;
+/**
+ * Create a standalone user admin router.
+ *
+ * Provides direct user access by userId at `/api/admin/users/:userId/*`
+ * without requiring the organizationId in the URL path. This is used by
+ * the Admin GUI SPA for user detail views and mutations where the user
+ * detail page only has the userId (from the URL) and not the orgId.
+ *
+ * The handlers delegate to the same user service functions as the
+ * org-scoped router. All routes require admin authentication and
+ * granular permissions.
+ *
+ * Prefix: /api/admin/users
+ */
+export declare function createStandaloneUserRouter(): Router;
+//# sourceMappingURL=users.d.ts.map

package/dist/routes/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/routes/users.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAmKjC;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAgiBzC;AA4HD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAoLnD"}