@spinajs/rbac-http-admin 2.0.485 → 2.0.487

package/lib/mjs/controllers/Users/Security.js

@@ -10,13 +10,17 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { BaseController, BasePath, Body, Get, Ok, Patch, Policy } from '@spinajs/http';
+import { AutoinjectService } from '@spinajs/configuration';
+import { BaseController, BasePath, Body, Del, Get, NotFound, Ok, Param, Patch, Policy, Post } from '@spinajs/http';
+import { activate, ban, changePassword, deactivate, expirePassword, hashSessionId, passwordChangeRequest, SessionProvider, unban, User, USER_COMMON_METADATA } from '@spinajs/rbac';
+import { AuthorizedPolicy, Permission, Resource, User as CurrentUser } from '@spinajs/rbac-http';
 import { FromModel } from '@spinajs/orm-http';
-import { activate, changePassword, deactivate, SessionProvider, User } from '@spinajs/rbac';
-import { AuthorizedPolicy, Permission, Resource } from "@spinajs/rbac-http";
 import { Schema } from '@spinajs/validation';
-import { resetUser2Fa } from '@spinajs/rbac-http-user';
-import { Autoinject } from '@spinajs/di';
+import { disableUser2Fa, enableUser2Fa, resetUser2Fa } from '@spinajs/rbac-http-user';
+import { Log, Logger } from '@spinajs/log';
+import { RoleGuard } from '../../interfaces.js';
+// Side effect only — see the note in Users.ts.
+import '../../services/RoleGuard.js';
 let ChangePasswordDto = class ChangePasswordDto {
     constructor(data) {
         Object.assign(this, data);
@@ -36,30 +40,53 @@ ChangePasswordDto = __decorate([
                 if: {
                     properties: {
                         password: { type: 'string' },
-                        confirmPassword: { type: 'string' }
-                    }
+                        confirmPassword: { type: 'string' },
+                    },
                 },
                 then: {
                     properties: {
-                        confirmPassword: { const: { $data: '1/password' } }
-                    }
-                }
-            }
-        ]
+                        confirmPassword: { const: { $data: '1/password' } },
+                    },
+                },
+            },
+        ],
     }),
     __metadata("design:paramtypes", [Object])
 ], ChangePasswordDto);
+export { ChangePasswordDto };
+let BanUserDto = class BanUserDto {
+    constructor(data) {
+        Object.assign(this, data);
+    }
+};
+BanUserDto = __decorate([
+    Schema({
+        type: 'object',
+        $id: 'arrow.common.banUserDTO',
+        properties: {
+            reason: { type: 'string', maxLength: 255, description: 'Why the account is banned. Stored in user metadata.' },
+            duration: { type: 'number', minimum: 1, description: 'Ban duration in seconds. Defaults to 24h.' },
+        },
+    }),
+    __metadata("design:paramtypes", [Object])
+], BanUserDto);
+export { BanUserDto };
 /**
  * User account security management (admin).
- * Administrative controls for user account security: password changes, 2FA reset,
- * account activation/deactivation, and forced session logout.
+ * Administrative controls for user account security: passwords, 2FA, account
+ * activation, bans, login lockouts and live sessions.
+ *
+ * Every route that takes an account out of service goes through the configured
+ * {@link RoleGuard} first — an administrator must not be able to lock themselves,
+ * or the installation, out through this API.
  * @tags Admin Users
  */
 let Security = class Security extends BaseController {
     /**
      * Change user password (admin)
      * Sets a new password for the specified user. Both password and confirmPassword must match.
-     * Minimum length is 8 characters.
+     * Minimum length is 8 characters. Every session of that user is destroyed — the credential
+     * they were opened with no longer exists.
      * @security cookieAuth
      * @param user User UUID path parameter
      * @response 200 Password changed successfully
@@ -72,6 +99,40 @@ let Security = class Security extends BaseController {
         await changePassword(dto.password)(user);
         return new Ok();
     }
+    /**
+     * Send a password reset link (admin)
+     * Issues a single-use reset token into the user's metadata and emits
+     * `UserPasswordChangeRequest` so the application can deliver it. The token itself is never
+     * returned. This is how a freshly created account is handed over to its owner — the
+     * temporary password generated at creation is deliberately discarded.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Reset token issued
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    async requestPasswordReset(user) {
+        await passwordChangeRequest(user);
+        return new Ok();
+    }
+    /**
+     * Expire a user password (admin)
+     * Marks the password as expired, which deactivates the account until a new one is set.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Password expired
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteAny permission required, or refused by the role guard
+     * @response 404 User not found
+     */
+    async expireUserPassword(actor, user) {
+        // Expiry deactivates the account, so it is guarded like every other way
+        // of taking an account out of service.
+        await this.RoleGuard.assertCanDisableAccount(actor, user, 'deactivate');
+        await expirePassword(user);
+        return new Ok();
+    }
     /**
      * Reset user two-factor authentication (admin)
      * Clears the TOTP secret and disables 2FA for the specified user.
@@ -87,17 +148,48 @@ let Security = class Security extends BaseController {
         await resetUser2Fa(user);
         return new Ok();
     }
+    /**
+     * Enable two-factor authentication for a user (admin)
+     * Initializes a TOTP secret for the account. Returns whatever the configured
+     * two-factor provider produces for enrolment (an otpauth url for the default provider) —
+     * deliver it to the user over a channel you trust.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 2FA enabled
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    async enable2Fa(user) {
+        return new Ok(await enableUser2Fa(user));
+    }
+    /**
+     * Disable two-factor authentication for a user (admin)
+     * Removes the TOTP secret and turns the second factor off for the account.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 2FA disabled
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    async disable2Fa(user) {
+        await disableUser2Fa(user);
+        return new Ok();
+    }
     /**
      * Deactivate user account (admin)
-     * Marks the user account as inactive, preventing login without deleting the record.
+     * Marks the user account as inactive and destroys its sessions, preventing login without
+     * deleting the record.
      * @security cookieAuth
      * @param user User UUID path parameter
      * @response 200 Account deactivated successfully
      * @response 401 Unauthorized — valid session required
-     * @response 403 Forbidden — deleteAny permission required on users resource
+     * @response 403 Forbidden — deleteAny permission required, or refused by the role guard
      * @response 404 User not found
      */
-    async deactivateUser(user) {
+    async deactivateUser(actor, user) {
+        await this.RoleGuard.assertCanDisableAccount(actor, user, 'deactivate');
         await deactivate(user);
         return new Ok();
     }
@@ -108,13 +200,101 @@ let Security = class Security extends BaseController {
      * @param user User UUID path parameter
      * @response 200 Account activated successfully
      * @response 401 Unauthorized — valid session required
-     * @response 403 Forbidden — deleteAny permission required on users resource
+     * @response 403 Forbidden — updateAny permission required on users resource
      * @response 404 User not found
      */
     async activateUser(user) {
         await activate(user);
         return new Ok();
     }
+    /**
+     * Ban a user (admin)
+     * Bans the account for `duration` seconds (24h when omitted), records the reason, and
+     * destroys every session it holds.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Account banned
+     * @response 400 Account is already banned
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteAny permission required, or refused by the role guard
+     * @response 404 User not found
+     */
+    async banUser(actor, user, dto) {
+        await this.RoleGuard.assertCanDisableAccount(actor, user, 'ban');
+        await ban(user, dto?.reason, dto?.duration);
+        return new Ok();
+    }
+    /**
+     * Unban a user (admin)
+     * Clears the ban metadata from the account.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Account unbanned
+     * @response 400 Account is not banned
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    async unbanUser(user) {
+        await unban(user);
+        return new Ok();
+    }
+    /**
+     * Clear a login lockout (admin)
+     * Removes the failed-attempt counter and the lockout window opened by the login throttle,
+     * letting the user try again immediately. Without this the only remedy is waiting out
+     * `rbac.password.lockoutTime`.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Lockout cleared
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    async unlockUser(user) {
+        await user.Metadata.delete(USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS);
+        await user.Metadata.delete(USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL);
+        this.Log.info(`Login lockout cleared`, { User: user.Uuid });
+        return new Ok();
+    }
+    /**
+     * List sessions of a user (admin)
+     * Returns every live session of the account, newest first, identified by an opaque handle.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @returns {IAdminSessionEntry[]} Live sessions of the user
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
+    async listSessions(user) {
+        const sessions = await this.SessionProvider.listByUser(user.Id);
+        const entries = sessions.map((s) => this.toEntry(s)).sort((a, b) => (a.Created < b.Created ? 1 : -1));
+        return new Ok(entries, { Headers: [{ Name: 'Cache-Control', Value: 'no-store' }] });
+    }
+    /**
+     * Revoke one session of a user (admin)
+     * Ends a single session, addressed by the handle returned from the listing.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param handle Session handle as returned by `GET /users/security/sessions/:user`
+     * @response 200 Session revoked
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 No such session for this user
+     */
+    async revokeSession(user, handle) {
+        // Resolved through THIS user's session list, so a handle belonging to
+        // somebody else cannot be revoked through their uuid.
+        const sessions = await this.SessionProvider.listByUser(user.Id);
+        const match = sessions.find((s) => hashSessionId(s.SessionId) === handle);
+        if (!match) {
+            return new NotFound({ error: { code: 'E_SESSION_NOT_FOUND', message: 'No such session' } });
+        }
+        await this.SessionProvider.delete(match.SessionId);
+        this.Log.info(`Session revoked by administrator`, { Session: handle, User: user.Uuid });
+        return new Ok(null, { Headers: [{ Name: 'Cache-Control', Value: 'no-store' }] });
+    }
     /**
      * Force logout user (admin)
      * Invalidates all active sessions for the specified user, immediately ending any current logins.
@@ -127,50 +307,143 @@ let Security = class Security extends BaseController {
      */
     async logoutUser(user) {
         await this.SessionProvider.deleteByUser(user.Id);
-        return new Ok();
+        this.Log.info(`All sessions revoked by administrator`, { User: user.Uuid });
+        return new Ok(null, { Headers: [{ Name: 'Cache-Control', Value: 'no-store' }] });
+    }
+    toEntry(session) {
+        return {
+            Handle: hashSessionId(session.SessionId),
+            Created: session.Creation?.toISO() ?? '',
+            Expires: session.Expiration?.toISO() ?? null,
+        };
     }
 };
 __decorate([
-    Autoinject(SessionProvider),
+    Logger('rbac-admin'),
+    __metadata("design:type", Log)
+], Security.prototype, "Log", void 0);
+__decorate([
+    AutoinjectService('rbac.session'),
     __metadata("design:type", SessionProvider)
 ], Security.prototype, "SessionProvider", void 0);
+__decorate([
+    AutoinjectService('rbac.admin.roleGuard'),
+    __metadata("design:type", RoleGuard)
+], Security.prototype, "RoleGuard", void 0);
 __decorate([
     Patch('changePassword/:user'),
     Permission(['updateAny']),
-    __param(0, FromModel({ queryField: "Uuid" })),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
     __param(1, Body()),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [User, ChangePasswordDto]),
     __metadata("design:returntype", Promise)
 ], Security.prototype, "changeUserPassword", null);
+__decorate([
+    Post('password-reset-request/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "requestPasswordReset", null);
+__decorate([
+    Post('expire-password/:user'),
+    Permission(['deleteAny']),
+    __param(0, CurrentUser()),
+    __param(1, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User, User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "expireUserPassword", null);
 __decorate([
     Patch('reset2fa/:user'),
     Permission(['updateAny']),
-    __param(0, FromModel({ queryField: "Uuid" })),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [User]),
     __metadata("design:returntype", Promise)
 ], Security.prototype, "reset2faToken", null);
 __decorate([
-    Get('deactivate/:user'),
-    Permission(['deleteAny']),
-    __param(0, FromModel({ queryField: "Uuid" })),
+    Post('2fa/enable/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [User]),
     __metadata("design:returntype", Promise)
-], Security.prototype, "deactivateUser", null);
+], Security.prototype, "enable2Fa", null);
 __decorate([
-    Get('activate/:user'),
+    Post('2fa/disable/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "disable2Fa", null);
+__decorate([
+    Post('deactivate/:user'),
     Permission(['deleteAny']),
-    __param(0, FromModel({ queryField: "Uuid" })),
+    __param(0, CurrentUser()),
+    __param(1, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User, User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "deactivateUser", null);
+__decorate([
+    Post('activate/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [User]),
     __metadata("design:returntype", Promise)
 ], Security.prototype, "activateUser", null);
 __decorate([
-    Get('logout/:user'),
+    Post('ban/:user'),
+    Permission(['deleteAny']),
+    __param(0, CurrentUser()),
+    __param(1, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __param(2, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User, User, BanUserDto]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "banUser", null);
+__decorate([
+    Post('unban/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "unbanUser", null);
+__decorate([
+    Post('unlock/:user'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid', include: ['Metadata'] })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "unlockUser", null);
+__decorate([
+    Get('sessions/:user'),
+    Permission(['readAny']),
+    __param(0, FromModel({ queryField: 'Uuid' })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "listSessions", null);
+__decorate([
+    Del('sessions/:user/:handle'),
+    Permission(['updateAny']),
+    __param(0, FromModel({ queryField: 'Uuid' })),
+    __param(1, Param()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [User, String]),
+    __metadata("design:returntype", Promise)
+], Security.prototype, "revokeSession", null);
+__decorate([
+    Del('sessions/:user'),
     Permission(['updateAny']),
-    __param(0, FromModel({ queryField: "Uuid" })),
+    __param(0, FromModel({ queryField: 'Uuid' })),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [User]),
     __metadata("design:returntype", Promise)

package/lib/mjs/controllers/Users/Security.js.map

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

package/lib/mjs/controllers/Users/Users.d.ts

@@ -1,14 +1,32 @@
 import { BaseController, Ok } from '@spinajs/http';
 import { IFilterRequest, OrderDTO, PaginationDTO } from '@spinajs/orm-http';
 import { PasswordProvider, User } from '@spinajs/rbac';
-declare class UserDto {
+import { RoleGuard } from '../../interfaces.js';
+import '../../services/RoleGuard.js';
+export declare class CreateUserDto {
     Login: string;
     Email: string;
     Role: string;
     Metadata?: {
         [key: string]: any;
     };
-    constructor(data: Partial<UserDto>);
+    constructor(data: Partial<CreateUserDto>);
+}
+/**
+ * PATCH body. Separate from {@link CreateUserDto} because the two have opposite
+ * requirements: creation needs all three fields, an update needs none of them.
+ * Sharing one schema made every documented partial update fail validation with
+ * a 400 before the handler ever ran.
+ *
+ * Metadata is deliberately absent — it is managed through the dedicated
+ * `/user/:uuid/metadata` routes, which validate one entry at a time and can
+ * refuse the keys that decide account access.
+ */
+export declare class UpdateUserDto {
+    Login?: string;
+    Email?: string;
+    Role?: string;
+    constructor(data: Partial<UpdateUserDto>);
 }
 /**
  * User account management (admin).
@@ -18,6 +36,7 @@ declare class UserDto {
  */
 export declare class Users extends BaseController {
     protected PasswordProvider: PasswordProvider;
+    protected RoleGuard: RoleGuard;
     /**
      * List users (admin)
      * Returns a paginated, sortable, filterable list of all users. Supports optional inclusion
@@ -28,15 +47,27 @@ export declare class Users extends BaseController {
      * user:niceName metadata (eq, neq, like).
      * @security cookieAuth
      * @param pagination.page Page number (zero-based)
-     * @param pagination.limit Number of users per page (default: 10)
-     * @param order.column Column to sort by (default: CreatedAt)
+     * @param pagination.limit Number of users per page (default: 10, max: 100)
+     * @param order.column Column to sort by (default: CreatedAt). One of Uuid, Login, Email, Role, IsActive, CreatedAt, LastLoginAt, DeletedAt
      * @param order.order Sort direction: ASC or DESC (default: DESC)
      * @param include Relations to include — currently supports: Metadata
      * @returns {IUserData[]} Paginated list of user accounts, each with optional Metadata relation
+     * @response 400 Sort column is not sortable
      * @response 401 Unauthorized — valid session required
      * @response 403 Forbidden — readAny permission required on users resource
      */
     list(pagination?: PaginationDTO, order?: OrderDTO, include?: string[], filter?: IFilterRequest): Promise<Ok<import("@spinajs/orm").ModelDataWithRelationData<User>[]>>;
+    /**
+     * List assignable roles (admin)
+     * Returns the roles the calling administrator is allowed to grant, as decided by the
+     * configured role guard — the system role and anything granting more than the caller
+     * holds are left out, so a UI cannot offer an operation the guard will refuse.
+     * @security cookieAuth
+     * @returns {string[]} Role names the caller may assign
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     */
+    assignableRoles(actor: User): Promise<Ok<string[]>>;
     /**
      * Get user by UUID (admin)
      * Retrieves a single user record by UUID. Supports optional inclusion of related Metadata.
@@ -63,30 +94,82 @@ export declare class Users extends BaseController {
     getByLogin(user: User, include?: string[]): Promise<Ok<import("@spinajs/orm").ModelDataWithRelationData<User>>>;
     /**
      * Create user (admin)
-     * Creates a new user account with a system-generated temporary password.
-     * The temporary password is not returned — it should be delivered to the user via email or other channel.
+     * Creates a new user account with a system-generated temporary password. The account is
+     * created inactive and the temporary password is never returned — issue a reset link with
+     * `POST /users/security/password-reset-request/:user` and activate the account once the
+     * user has set their own password.
      * @security cookieAuth
      * @returns {IUserData} Created user account
-     * @response 400 Validation error — missing required fields or invalid format
+     * @response 400 Validation error — missing required fields, invalid format, unknown role or a protected metadata key
      * @response 401 Unauthorized — valid session required
-     * @response 403 Forbidden — createAny permission required on users resource
+     * @response 403 Forbidden — createAny permission required, or the requested role grants more than the caller holds
      * @response 409 Login or email already in use
      */
-    addUser(data: UserDto): Promise<Ok<import("@spinajs/orm").ModelDataWithRelationData<User>>>;
+    addUser(actor: User, data: CreateUserDto): Promise<Ok<import("@spinajs/orm").ModelDataWithRelationData<User>>>;
     /**
      * Update user (admin)
      * Partially updates a user account. All fields are optional — only provided fields are changed.
-     * Metadata is merged: existing keys are updated, new keys are added, unlisted keys are preserved.
+     * Metadata is NOT handled here; use the `/user/:uuid/metadata` routes.
      * @security cookieAuth
      * @param user User UUID path parameter
      * @response 200 User updated successfully
-     * @response 400 Validation error — invalid field format
+     * @response 400 Validation error — invalid field format or unknown role
      * @response 401 Unauthorized — valid session required
-     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 403 Forbidden — updateAny permission required, or the role change is refused by the role guard
      * @response 404 User not found
      * @response 409 Login or email already in use by another account
      */
-    updateUser(user: User, data: UserDto): Promise<Ok<any>>;
+    updateUser(actor: User, user: User, data: UpdateUserDto): Promise<Ok<any>>;
+    /**
+     * Delete user (admin)
+     * Soft-deletes the account (`DeletedAt` is stamped, the row is kept) and destroys every
+     * session it holds, so a deleted user stops acting immediately rather than when their
+     * cookie happens to expire.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 User deleted
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteAny permission required, or the deletion is refused by the role guard
+     * @response 404 User not found
+     */
+    removeUser(actor: User, user: User): Promise<Ok<any>>;
+    /**
+     * Restore a deleted user (admin)
+     * Clears `DeletedAt` on a soft-deleted account. The account keeps its previous
+     * `IsActive` state — restoring is not activating.
+     * @security cookieAuth
+     * @param uuid User UUID path parameter
+     * @response 200 User restored
+     * @response 400 User is not deleted
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteAny permission required on users resource
+     * @response 404 User not found
+     */
+    restoreUser(uuid: string): Promise<Ok<any>>;
+    /**
+     * The requested sort column, or the default. Rejects anything outside
+     * {@link SORTABLE_COLUMNS}.
+     */
+    protected sortColumn(order?: OrderDTO): string;
+    /**
+     * Refuses metadata keys that decide account access.
+     *
+     * `user:pwd_reset:token` is a bearer credential for the public reset endpoint
+     * and `user:2fa:*` is the second factor itself — writing either through a
+     * generic key-value merge hands out an account rather than annotating one.
+     * Ban and lockout keys are refused for the same reason bans have their own
+     * route: written directly they skip the event, the email and the session
+     * revocation that make a ban mean something.
+     */
+    protected assertNoProtectedMetadata(metadata?: {
+        [key: string]: any;
+    }): void;
+    /**
+     * Rejects a login / email already taken by another account.
+     *
+     * Soft-deleted rows are included on purpose: they still occupy the unique
+     * indexes, so ignoring them would trade this 409 for a driver error and a 500.
+     */
+    protected assertUnique(login?: string, email?: string, exceptUserId?: number): Promise<void>;
 }
-export {};
 //# sourceMappingURL=Users.d.ts.map

package/lib/mjs/controllers/Users/Users.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Users.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Users.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAuB,EAAE,EAA8B,MAAM,eAAe,CAAC;AAEpG,OAAO,EAAyD,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnI,OAAO,EAAU,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAI/D,cAoBM,OAAO;IACJ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;gBAE7B,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;CAGnC;AA4ED;;;;;GAKG;AACH,qBAGa,KAAM,SAAQ,cAAc;IAGvC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAA;IAE5C;;;;;;;;;;;;;;;;;OAiBG;IAGU,IAAI,CACN,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAQzB,OAAO,CAAC,EAAE,MAAM,EAAE,EAElB,MAAM,CAAC,EAAE,cAAc;IAqCzB;;;;;;;;;;OAUG;IAEU,aAAa,CAAoC,IAAI,EAAE,IAAI,EAOxE,OAAO,CAAC,EAAE,MAAM,EAAE;IAMlB;;;;;;;;;;OAUG;IAEU,UAAU,CAAqC,IAAI,EAAE,IAAI,EAOtE,OAAO,CAAC,EAAE,MAAM,EAAE;IAOlB;;;;;;;;;;OAUG;IAGU,OAAO,CACV,IAAI,EAAE,OAAO;IAavB;;;;;;;;;;;;OAYG;IAGU,UAAU,CACc,IAAI,EAAE,IAAI,EACrC,IAAI,EAAE,OAAO;CAuBxB"}
+{"version":3,"file":"Users.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Users.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAA4B,EAAE,EAAqC,MAAM,eAAe,CAAC;AAGhH,OAAO,EAAyD,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnI,OAAO,EAAsB,gBAAgB,EAAE,IAAI,EAA6C,MAAM,eAAe,CAAC;AAItH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAOhD,OAAO,6BAA6B,CAAC;AAqBrC,qBAgBa,aAAa;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;gBAE7B,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC;CAGzC;AAED;;;;;;;;;GASG;AACH,qBAUa,aAAa;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;gBAET,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC;CAGzC;AA2ED;;;;;GAKG;AACH,qBAGa,KAAM,SAAQ,cAAc;IAEvC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAG7C,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IAGU,IAAI,CACN,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAQzB,OAAO,CAAC,EAAE,MAAM,EAAE,EAElB,MAAM,CAAC,EAAE,cAAc;IAgDzB;;;;;;;;;OASG;IAGU,eAAe,CAAgB,KAAK,EAAE,IAAI;IAIvD;;;;;;;;;;OAUG;IAGU,aAAa,CACW,IAAI,EAAE,IAAI,EAQ7C,OAAO,CAAC,EAAE,MAAM,EAAE;IAOpB;;;;;;;;;;OAUG;IAGU,UAAU,CACe,IAAI,EAAE,IAAI,EAQ9C,OAAO,CAAC,EAAE,MAAM,EAAE;IAOpB;;;;;;;;;;;;OAYG;IAGU,OAAO,CAAgB,KAAK,EAAE,IAAI,EAAU,IAAI,EAAE,aAAa;IAc5E;;;;;;;;;;;;OAYG;IAGU,UAAU,CAAgB,KAAK,EAAE,IAAI,EAA4D,IAAI,EAAE,IAAI,EAAU,IAAI,EAAE,aAAa;IA6BrJ;;;;;;;;;;;OAWG;IAGU,UAAU,CAAgB,KAAK,EAAE,IAAI,EAA4D,IAAI,EAAE,IAAI;IAOxH;;;;;;;;;;;OAWG;IAGU,WAAW,CAAU,IAAI,EAAE,MAAM;IAmB9C;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM;IAc9C;;;;;;;;;OASG;IACH,SAAS,CAAC,yBAAyB,CAAC,QAAQ,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,GAAG,IAAI;IAqB5E;;;;;OAKG;cACa,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBnG"}