@spinajs/rbac-http-admin 2.0.470 → 2.0.471

package/lib/cjs/controllers/Users/Profile.d.ts

@@ -1,7 +1,23 @@
 import { BaseController, Ok } from '@spinajs/http';
 import { UserProfileProvider } from '@spinajs/rbac';
+/**
+ * User profile management (admin).
+ * Provides administrative access to user profile data via the configured UserProfileProvider.
+ * @tags Admin Users
+ */
 export declare class Roles extends BaseController {
     protected ProfileService: UserProfileProvider;
-    getUserProfile(login: string): Promise<Ok>;
+    /**
+     * Get user profile by login (admin)
+     * Retrieves extended profile data for the specified user via the configured UserProfileProvider.
+     * The shape of the returned profile depends on the active provider implementation.
+     * @security cookieAuth
+     * @param login User login name
+     * @returns {IUserProfile} User profile data as returned by the configured UserProfileProvider
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
+    getUserProfile(login: string): Promise<Ok<import("@spinajs/rbac").UserProfile<unknown>>>;
 }
 //# sourceMappingURL=Profile.d.ts.map

package/lib/cjs/controllers/Users/Profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Profile.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Profile.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAiB,EAAE,EAAiB,MAAM,eAAe,CAAC;AACjF,OAAO,EAAS,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAI3D,qBAGa,KAAM,SAAQ,cAAc;IAIrC,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAIjC,cAAc,CAAU,KAAK,EAAE,MAAM;CAGrD"}
+{"version":3,"file":"Profile.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Profile.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAiB,EAAE,EAAiB,MAAM,eAAe,CAAC;AACjF,OAAO,EAAS,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAI3D;;;;GAIG;AACH,qBAGa,KAAM,SAAQ,cAAc;IAIrC,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAE9C;;;;;;;;;;OAUG;IAGU,cAAc,CAAU,KAAK,EAAE,MAAM;CAGrD"}

package/lib/cjs/controllers/Users/Profile.js

@@ -17,7 +17,23 @@ const configuration_1 = require("@spinajs/configuration");
 const http_1 = require("@spinajs/http");
 const rbac_1 = require("@spinajs/rbac");
 const rbac_http_1 = require("@spinajs/rbac-http");
+/**
+ * User profile management (admin).
+ * Provides administrative access to user profile data via the configured UserProfileProvider.
+ * @tags Admin Users
+ */
 let Roles = class Roles extends http_1.BaseController {
+    /**
+     * Get user profile by login (admin)
+     * Retrieves extended profile data for the specified user via the configured UserProfileProvider.
+     * The shape of the returned profile depends on the active provider implementation.
+     * @security cookieAuth
+     * @param login User login name
+     * @returns {IUserProfile} User profile data as returned by the configured UserProfileProvider
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
     async getUserProfile(login) {
         return new http_1.Ok(this.ProfileService.retrieve(login));
     }

package/lib/cjs/controllers/Users/Profile.js.map

@@ -1 +1 @@
-{"version":3,"file":"Profile.js","sourceRoot":"","sources":["../../../../src/controllers/Users/Profile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,0DAA2D;AAC3D,wCAAiF;AACjF,wCAA2D;AAC3D,kDAA4E;AAMrE,IAAM,KAAK,GAAX,MAAM,KAAM,SAAQ,qBAAc;IAQxB,AAAN,KAAK,CAAC,cAAc,CAAU,KAAa;QAC7C,OAAO,IAAI,SAAE,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;CACJ,CAAA;AAXY,sBAAK;AAIJ;IADT,IAAA,iCAAiB,EAAC,cAAc,CAAC;8BACR,0BAAmB;6CAAC;AAIjC;IAFZ,IAAA,UAAG,EAAC,QAAQ,CAAC;IACb,IAAA,sBAAU,EAAC,CAAC,SAAS,CAAC,CAAC;IACK,WAAA,IAAA,YAAK,GAAE,CAAA;;;;2CAEnC;gBAVQ,KAAK;IAHjB,IAAA,eAAQ,EAAC,eAAe,CAAC;IACzB,IAAA,aAAM,EAAC,4BAAgB,CAAC;IACxB,IAAA,oBAAQ,EAAC,OAAO,CAAC;GACL,KAAK,CAWjB"}
+{"version":3,"file":"Profile.js","sourceRoot":"","sources":["../../../../src/controllers/Users/Profile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,0DAA2D;AAC3D,wCAAiF;AACjF,wCAA2D;AAC3D,kDAA4E;AAG5E;;;;GAIG;AAII,IAAM,KAAK,GAAX,MAAM,KAAM,SAAQ,qBAAc;IAMrC;;;;;;;;;;OAUG;IAGU,AAAN,KAAK,CAAC,cAAc,CAAU,KAAa;QAC7C,OAAO,IAAI,SAAE,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;CACJ,CAAA;AAtBY,sBAAK;AAIJ;IADT,IAAA,iCAAiB,EAAC,cAAc,CAAC;8BACR,0BAAmB;6CAAC;AAejC;IAFZ,IAAA,UAAG,EAAC,QAAQ,CAAC;IACb,IAAA,sBAAU,EAAC,CAAC,SAAS,CAAC,CAAC;IACK,WAAA,IAAA,YAAK,GAAE,CAAA;;;;2CAEnC;gBArBQ,KAAK;IAHjB,IAAA,eAAQ,EAAC,eAAe,CAAC;IACzB,IAAA,aAAM,EAAC,4BAAgB,CAAC;IACxB,IAAA,oBAAQ,EAAC,OAAO,CAAC;GACL,KAAK,CAsBjB"}

package/lib/cjs/controllers/Users/Roles.d.ts

@@ -3,8 +3,35 @@ export declare class RoleDto {
     role: string;
     constructor(data: Partial<RoleDto>);
 }
+/**
+ * User role management (admin).
+ * Grants and revokes RBAC roles for user accounts.
+ * @tags Admin Users
+ */
 export declare class Roles extends BaseController {
-    addRole(login: string, roleDto: RoleDto): Promise<Ok>;
-    revokeRole(login: string, roleDto: RoleDto): Promise<Ok>;
+    /**
+     * Grant role to user (admin)
+     * Assigns the specified RBAC role to the user identified by login name.
+     * @security cookieAuth
+     * @param login User login name
+     * @response 200 Role granted successfully
+     * @response 400 Invalid role name
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    addRole(login: string, roleDto: RoleDto): Promise<Ok<any>>;
+    /**
+     * Revoke role from user (admin)
+     * Removes the specified RBAC role from the user identified by login name.
+     * @security cookieAuth
+     * @param login User login name
+     * @response 200 Role revoked successfully
+     * @response 400 Invalid role name
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    revokeRole(login: string, roleDto: RoleDto): Promise<Ok<any>>;
 }
 //# sourceMappingURL=Roles.d.ts.map

package/lib/cjs/controllers/Users/Roles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Roles.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAkB,EAAE,EAAwB,MAAM,eAAe,CAAC;AAMzF,qBAOa,OAAO;IACT,IAAI,EAAE,MAAM,CAAC;gBAER,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;CAGrC;AAGD,qBAGa,KAAM,SAAQ,cAAc;IAGxB,OAAO,CAAU,KAAK,EAAE,MAAM,EAAU,OAAO,EAAE,OAAO;IAOxD,UAAU,CAAU,KAAK,EAAE,MAAM,EAAU,OAAO,EAAE,OAAO;CAI3E"}
+{"version":3,"file":"Roles.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAkB,EAAE,EAAwB,MAAM,eAAe,CAAC;AAMzF,qBAQa,OAAO;IACT,IAAI,EAAE,MAAM,CAAC;gBAER,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;CAGrC;AAGD;;;;GAIG;AACH,qBAGa,KAAM,SAAQ,cAAc;IACrC;;;;;;;;;;OAUG;IAGU,OAAO,CAAU,KAAK,EAAE,MAAM,EAAU,OAAO,EAAE,OAAO;IAKrE;;;;;;;;;;OAUG;IAGU,UAAU,CAAU,KAAK,EAAE,MAAM,EAAU,OAAO,EAAE,OAAO;CAI3E"}

package/lib/cjs/controllers/Users/Roles.js

@@ -28,16 +28,44 @@ exports.RoleDto = RoleDto = __decorate([
         type: 'object',
         $id: 'arrow.common.roleDTO',
         properties: {
-            role: { type: 'string', minimum: 0, maximum: 32 },
+            role: { type: 'string', minLength: 1, maxLength: 32, description: 'RBAC role name to grant or revoke' },
         },
+        required: ['role'],
     }),
     __metadata("design:paramtypes", [Object])
 ], RoleDto);
+/**
+ * User role management (admin).
+ * Grants and revokes RBAC roles for user accounts.
+ * @tags Admin Users
+ */
 let Roles = class Roles extends http_1.BaseController {
+    /**
+     * Grant role to user (admin)
+     * Assigns the specified RBAC role to the user identified by login name.
+     * @security cookieAuth
+     * @param login User login name
+     * @response 200 Role granted successfully
+     * @response 400 Invalid role name
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
     async addRole(login, roleDto) {
         await (0, rbac_1.grant)(login, roleDto.role);
         return new http_1.Ok();
     }
+    /**
+     * Revoke role from user (admin)
+     * Removes the specified RBAC role from the user identified by login name.
+     * @security cookieAuth
+     * @param login User login name
+     * @response 200 Role revoked successfully
+     * @response 400 Invalid role name
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
     async revokeRole(login, roleDto) {
         await (0, rbac_1.revoke)(login, roleDto.role);
         return new http_1.Ok();

package/lib/cjs/controllers/Users/Roles.js.map

@@ -1 +1 @@
-{"version":3,"file":"Roles.js","sourceRoot":"","sources":["../../../../src/controllers/Users/Roles.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,wCAAyF;AACzF,wCAAqD;AACrD,kDAA4E;AAC5E,oDAA6C;AAUtC,IAAM,OAAO,GAAb,MAAM,OAAO;IAGhB,YAAY,IAAsB;QAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAA;AANY,0BAAO;kBAAP,OAAO;IAPnB,IAAA,mBAAM,EAAC;QACJ,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,sBAAsB;QAC3B,UAAU,EAAE;YACR,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;SACpD;KACJ,CAAC;;GACW,OAAO,CAMnB;AAMM,IAAM,KAAK,GAAX,MAAM,KAAM,SAAQ,qBAAc;IAGxB,AAAN,KAAK,CAAC,OAAO,CAAU,KAAa,EAAU,OAAgB;QACjE,MAAM,IAAA,YAAK,EAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,SAAE,EAAE,CAAA;IACnB,CAAC;IAIY,AAAN,KAAK,CAAC,UAAU,CAAU,KAAa,EAAU,OAAgB;QACpE,MAAM,IAAA,aAAM,EAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,IAAI,SAAE,EAAE,CAAA;IACnB,CAAC;CACJ,CAAA;AAdY,sBAAK;AAGD;IAFZ,IAAA,YAAK,EAAC,YAAY,CAAC;IACnB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACJ,WAAA,IAAA,YAAK,GAAE,CAAA;IAAiB,WAAA,IAAA,WAAI,GAAE,CAAA;;6CAAU,OAAO;;oCAGpE;AAIY;IAFZ,IAAA,YAAK,EAAC,eAAe,CAAC;IACtB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACD,WAAA,IAAA,YAAK,GAAE,CAAA;IAAiB,WAAA,IAAA,WAAI,GAAE,CAAA;;6CAAU,OAAO;;uCAGvE;gBAbQ,KAAK;IAHjB,IAAA,eAAQ,EAAC,YAAY,CAAC;IACtB,IAAA,aAAM,EAAC,4BAAgB,CAAC;IACxB,IAAA,oBAAQ,EAAC,OAAO,CAAC;GACL,KAAK,CAcjB"}
+{"version":3,"file":"Roles.js","sourceRoot":"","sources":["../../../../src/controllers/Users/Roles.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,wCAAyF;AACzF,wCAAqD;AACrD,kDAA4E;AAC5E,oDAA6C;AAWtC,IAAM,OAAO,GAAb,MAAM,OAAO;IAGhB,YAAY,IAAsB;QAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAA;AANY,0BAAO;kBAAP,OAAO;IARnB,IAAA,mBAAM,EAAC;QACJ,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,sBAAsB;QAC3B,UAAU,EAAE;YACR,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,EAAE,mCAAmC,EAAE;SAC1G;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACrB,CAAC;;GACW,OAAO,CAMnB;AAGD;;;;GAIG;AAII,IAAM,KAAK,GAAX,MAAM,KAAM,SAAQ,qBAAc;IACrC;;;;;;;;;;OAUG;IAGU,AAAN,KAAK,CAAC,OAAO,CAAU,KAAa,EAAU,OAAgB;QACjE,MAAM,IAAA,YAAK,EAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,SAAE,EAAE,CAAA;IACnB,CAAC;IAED;;;;;;;;;;OAUG;IAGU,AAAN,KAAK,CAAC,UAAU,CAAU,KAAa,EAAU,OAAgB;QACpE,MAAM,IAAA,aAAM,EAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,IAAI,SAAE,EAAE,CAAA;IACnB,CAAC;CACJ,CAAA;AApCY,sBAAK;AAcD;IAFZ,IAAA,YAAK,EAAC,YAAY,CAAC;IACnB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACJ,WAAA,IAAA,YAAK,GAAE,CAAA;IAAiB,WAAA,IAAA,WAAI,GAAE,CAAA;;6CAAU,OAAO;;oCAGpE;AAeY;IAFZ,IAAA,YAAK,EAAC,eAAe,CAAC;IACtB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACD,WAAA,IAAA,YAAK,GAAE,CAAA;IAAiB,WAAA,IAAA,WAAI,GAAE,CAAA;;6CAAU,OAAO;;uCAGvE;gBAnCQ,KAAK;IAHjB,IAAA,eAAQ,EAAC,YAAY,CAAC;IACtB,IAAA,aAAM,EAAC,4BAAgB,CAAC;IACxB,IAAA,oBAAQ,EAAC,OAAO,CAAC;GACL,KAAK,CAoCjB"}

package/lib/cjs/controllers/Users/Security.d.ts

@@ -5,13 +5,72 @@ declare class ChangePasswordDto {
     confirmPassword: string;
     constructor(data: any);
 }
+/**
+ * User account security management (admin).
+ * Administrative controls for user account security: password changes, 2FA reset,
+ * account activation/deactivation, and forced session logout.
+ * @tags Admin Users
+ */
 export declare class Security extends BaseController {
     protected SessionProvider: SessionProvider;
-    changeUserPassword(user: User, dto: ChangePasswordDto): Promise<Ok>;
-    reset2faToken(user: User): Promise<Ok>;
-    deactivateUser(user: User): Promise<Ok>;
-    activateUser(user: User): Promise<Ok>;
-    logoutUser(user: User): Promise<Ok>;
+    /**
+     * Change user password (admin)
+     * Sets a new password for the specified user. Both password and confirmPassword must match.
+     * Minimum length is 8 characters.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Password changed successfully
+     * @response 400 Passwords do not match or fail validation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    changeUserPassword(user: User, dto: ChangePasswordDto): Promise<Ok<any>>;
+    /**
+     * Reset user two-factor authentication (admin)
+     * Clears the TOTP secret and disables 2FA for the specified user.
+     * Use this to help a user regain access when they lose their authenticator device.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 2FA reset successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    reset2faToken(user: User): Promise<Ok<any>>;
+    /**
+     * Deactivate user account (admin)
+     * Marks the user account as inactive, 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 404 User not found
+     */
+    deactivateUser(user: User): Promise<Ok<any>>;
+    /**
+     * Activate user account (admin)
+     * Marks a previously deactivated user account as active, restoring login access.
+     * @security cookieAuth
+     * @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 404 User not found
+     */
+    activateUser(user: User): Promise<Ok<any>>;
+    /**
+     * Force logout user (admin)
+     * Invalidates all active sessions for the specified user, immediately ending any current logins.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 All sessions invalidated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
+    logoutUser(user: User): Promise<Ok<any>>;
 }
 export {};
 //# sourceMappingURL=Security.d.ts.map

package/lib/cjs/controllers/Users/Security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Security.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,EAAE,EAAiB,MAAM,eAAe,CAAC;AAEvF,OAAO,EAA+C,eAAe,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAMnG,cAwBM,iBAAiB;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;gBAEnB,IAAI,EAAE,GAAG;CAGxB;AAGD,qBAGa,QAAS,SAAQ,cAAc;IAGxC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAI9B,kBAAkB,CAAoC,IAAI,EAAE,IAAI,EAAU,GAAG,EAAE,iBAAiB;IAOhG,aAAa,CAAoC,IAAI,EAAE,IAAI;IAO3D,cAAc,CAAoC,IAAI,EAAE,IAAI;IAO5D,YAAY,CAAoC,IAAI,EAAE,IAAI;IAO1D,UAAU,CAAoC,IAAI,EAAE,IAAI;CAIxE"}
+{"version":3,"file":"Security.d.ts","sourceRoot":"","sources":["../../../../src/controllers/Users/Security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,EAAE,EAAiB,MAAM,eAAe,CAAC;AAEvF,OAAO,EAA+C,eAAe,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAMnG,cAwBM,iBAAiB;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;gBAEnB,IAAI,EAAE,GAAG;CAGxB;AAGD;;;;;GAKG;AACH,qBAGa,QAAS,SAAQ,cAAc;IAGxC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAE3C;;;;;;;;;;;OAWG;IAGU,kBAAkB,CAAoC,IAAI,EAAE,IAAI,EAAU,GAAG,EAAE,iBAAiB;IAK7G;;;;;;;;;;OAUG;IAGU,aAAa,CAAoC,IAAI,EAAE,IAAI;IAKxE;;;;;;;;;OASG;IAGU,cAAc,CAAoC,IAAI,EAAE,IAAI;IAKzE;;;;;;;;;OASG;IAGU,YAAY,CAAoC,IAAI,EAAE,IAAI;IAKvE;;;;;;;;;OASG;IAGU,UAAU,CAAoC,IAAI,EAAE,IAAI;CAIxE"}

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

@@ -30,8 +30,8 @@ ChangePasswordDto = __decorate([
         type: 'object',
         $id: 'arrow.common.changePasswordDTO',
         properties: {
-            password: { type: 'string', minLength: 8, maxLength: 128 },
-            confirmPassword: { type: 'string', minLength: 8, maxLength: 128 }
+            password: { type: 'string', minLength: 8, maxLength: 128, description: 'New password (8–128 characters)' },
+            confirmPassword: { type: 'string', minLength: 8, maxLength: 128, description: 'Must match password' },
         },
         required: ['password', 'confirmPassword'],
         allOf: [
@@ -52,23 +52,82 @@ ChangePasswordDto = __decorate([
     }),
     __metadata("design:paramtypes", [Object])
 ], ChangePasswordDto);
+/**
+ * User account security management (admin).
+ * Administrative controls for user account security: password changes, 2FA reset,
+ * account activation/deactivation, and forced session logout.
+ * @tags Admin Users
+ */
 let Security = class Security extends http_1.BaseController {
+    /**
+     * Change user password (admin)
+     * Sets a new password for the specified user. Both password and confirmPassword must match.
+     * Minimum length is 8 characters.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Password changed successfully
+     * @response 400 Passwords do not match or fail validation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
     async changeUserPassword(user, dto) {
         await (0, rbac_1.changePassword)(dto.password)(user);
         return new http_1.Ok();
     }
+    /**
+     * Reset user two-factor authentication (admin)
+     * Clears the TOTP secret and disables 2FA for the specified user.
+     * Use this to help a user regain access when they lose their authenticator device.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 2FA reset successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
     async reset2faToken(user) {
         await (0, rbac_http_user_1.resetUser2Fa)(user);
         return new http_1.Ok();
     }
+    /**
+     * Deactivate user account (admin)
+     * Marks the user account as inactive, 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 404 User not found
+     */
     async deactivateUser(user) {
         await (0, rbac_1.deactivate)(user);
         return new http_1.Ok();
     }
+    /**
+     * Activate user account (admin)
+     * Marks a previously deactivated user account as active, restoring login access.
+     * @security cookieAuth
+     * @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 404 User not found
+     */
     async activateUser(user) {
         await (0, rbac_1.activate)(user);
         return new http_1.Ok();
     }
+    /**
+     * Force logout user (admin)
+     * Invalidates all active sessions for the specified user, immediately ending any current logins.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 All sessions invalidated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     */
     async logoutUser(user) {
         await this.SessionProvider.logsOut(user);
         return new http_1.Ok();

package/lib/cjs/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":";;;;;;;;;;;;;;;AAAA,wCAAuF;AACvF,gDAA8C;AAC9C,wCAAmG;AACnG,kDAA4E;AAC5E,oDAA6C;AAC7C,4DAAuD;AACvD,oCAAyC;AAEzC,IAwBM,iBAAiB,GAxBvB,MAwBM,iBAAiB;IAInB,YAAY,IAAS;QACjB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;CACJ,CAAA;AAPK,iBAAiB;IAxBtB,IAAA,mBAAM,EAAC;QACJ,IAAI,EAAE,QAAQ;QACd,GAAG,EAAE,gCAAgC;QACrC,UAAU,EAAE;YACR,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,iCAAiC,EAAE;YAC1G,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,qBAAqB,EAAE;SACxG;QACD,QAAQ,EAAE,CAAC,UAAU,EAAE,iBAAiB,CAAC;QACzC,KAAK,EAAE;YACH;gBACI,EAAE,EAAE;oBACA,UAAU,EAAE;wBACR,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC5B,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBACtC;iBACJ;gBACD,IAAI,EAAE;oBACF,UAAU,EAAE;wBACR,eAAe,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE;qBACtD;iBACJ;aACJ;SACJ;KACJ,CAAC;;GACI,iBAAiB,CAOtB;AAGD;;;;;GAKG;AAII,IAAM,QAAQ,GAAd,MAAM,QAAS,SAAQ,qBAAc;IAKxC;;;;;;;;;;;OAWG;IAGU,AAAN,KAAK,CAAC,kBAAkB,CAAoC,IAAU,EAAU,GAAsB;QACzG,MAAM,IAAA,qBAAc,EAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,IAAI,SAAE,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IAGU,AAAN,KAAK,CAAC,aAAa,CAAoC,IAAU;QACpE,MAAM,IAAA,6BAAY,EAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,SAAE,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;;;;OASG;IAGU,AAAN,KAAK,CAAC,cAAc,CAAoC,IAAU;QACrE,MAAM,IAAA,iBAAU,EAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,SAAE,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;;;;OASG;IAGU,AAAN,KAAK,CAAC,YAAY,CAAoC,IAAU;QACnE,MAAM,IAAA,eAAQ,EAAC,IAAI,CAAC,CAAC;QACrB,OAAO,IAAI,SAAE,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;;;;OASG;IAGU,AAAN,KAAK,CAAC,UAAU,CAAoC,IAAU;QACjE,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,IAAI,SAAE,EAAE,CAAC;IACpB,CAAC;CACJ,CAAA;AA5FY,4BAAQ;AAGP;IADT,IAAA,eAAU,EAAC,sBAAe,CAAC;8BACD,sBAAe;iDAAC;AAgB9B;IAFZ,IAAA,YAAK,EAAC,sBAAsB,CAAC;IAC7B,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACO,WAAA,IAAA,oBAAS,EAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;IAAc,WAAA,IAAA,WAAI,GAAE,CAAA;;qCAAb,WAAI,EAAe,iBAAiB;;kDAG5G;AAeY;IAFZ,IAAA,YAAK,EAAC,gBAAgB,CAAC;IACvB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACE,WAAA,IAAA,oBAAS,EAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;;qCAAO,WAAI;;6CAGvE;AAcY;IAFZ,IAAA,UAAG,EAAC,kBAAkB,CAAC;IACvB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACG,WAAA,IAAA,oBAAS,EAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;;qCAAO,WAAI;;8CAGxE;AAcY;IAFZ,IAAA,UAAG,EAAC,gBAAgB,CAAC;IACrB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACC,WAAA,IAAA,oBAAS,EAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;;qCAAO,WAAI;;4CAGtE;AAcY;IAFZ,IAAA,UAAG,EAAC,cAAc,CAAC;IACnB,IAAA,sBAAU,EAAC,CAAC,WAAW,CAAC,CAAC;IACD,WAAA,IAAA,oBAAS,EAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;;qCAAO,WAAI;;0CAGpE;mBA3FQ,QAAQ;IAHpB,IAAA,eAAQ,EAAC,gBAAgB,CAAC;IAC1B,IAAA,aAAM,EAAC,4BAAgB,CAAC;IACxB,IAAA,oBAAQ,EAAC,OAAO,CAAC;GACL,QAAQ,CA4FpB"}

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

@@ -10,13 +10,86 @@ declare class UserDto {
     };
     constructor(data: Partial<UserDto>);
 }
+/**
+ * User account management (admin).
+ * Full CRUD operations for user accounts. Supports pagination, sorting, filtering,
+ * and optional relation loading. All write operations require full authorization.
+ * @tags Admin Users
+ */
 export declare class Users extends BaseController {
     protected PasswordProvider: PasswordProvider;
-    list(pagination?: PaginationDTO, order?: OrderDTO, include?: string[], filter?: IFilterRequest): Promise<Ok>;
-    getSingleUser(user: User, include?: string[]): Promise<Ok>;
-    getByLogin(user: User, include?: string[]): Promise<Ok>;
-    addUser(data: UserDto): Promise<Ok>;
-    updateUser(user: User, data: UserDto): Promise<Ok>;
+    /**
+     * List users (admin)
+     * Returns a paginated, sortable, filterable list of all users. Supports optional inclusion
+     * of related Metadata. The total user count (matching current filters) is returned in the
+     * X-Total-Count response header.
+     * Filterable fields: Uuid (eq), Email (eq, like), Login (eq, like), CreatedAt, LastLoginAt,
+     * DeletedAt (eq, gte, lte, lt, gt, isnull, notnull), IsActive (eq), Role (eq, neq),
+     * 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 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 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>[]>>;
+    /**
+     * Get user by UUID (admin)
+     * Retrieves a single user record by UUID. Supports optional inclusion of related Metadata.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param include Relations to include — currently supports: Metadata
+     * @returns {IUserData} User account with optional Metadata relation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
+    getSingleUser(user: User, include?: string[]): Promise<Ok<import("@spinajs/orm").ModelDataWithRelationData<User>>>;
+    /**
+     * Get user by login (admin)
+     * Retrieves a single user record by login name. Supports optional inclusion of related Metadata.
+     * @security cookieAuth
+     * @param user User login name path parameter
+     * @param include Relations to include — currently supports: Metadata
+     * @returns {IUserData} User account with optional Metadata relation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
+    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.
+     * @security cookieAuth
+     * @returns {IUserData} Created user account
+     * @response 400 Validation error — missing required fields or invalid format
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — createAny permission required on users resource
+     * @response 409 Login or email already in use
+     */
+    addUser(data: UserDto): Promise<Ok<{
+        User: User;
+        Password: string;
+    }>>;
+    /**
+     * 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.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 User updated successfully
+     * @response 400 Validation error — invalid field format
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     * @response 409 Login or email already in use by another account
+     */
+    updateUser(user: User, data: UserDto): Promise<Ok<any>>;
 }
 export {};
 //# sourceMappingURL=Users.d.ts.map

package/lib/cjs/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;AAqED,qBAGa,KAAM,SAAQ,cAAc;IAGvC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAA;IAI/B,IAAI,CACN,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAQzB,OAAO,CAAC,EAAE,MAAM,EAAE,EAElB,MAAM,CAAC,EAAE,cAAc;IAsCZ,aAAa,CAAoC,IAAI,EAAE,IAAI,EAOxE,OAAO,CAAC,EAAE,MAAM,EAAE;IAOL,UAAU,CAAqC,IAAI,EAAE,IAAI,EAOtE,OAAO,CAAC,EAAE,MAAM,EAAE;IASL,OAAO,CACV,IAAI,EAAE,OAAO;IAWV,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":"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;AAqED;;;;;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;;;;IASvB;;;;;;;;;;;;OAYG;IAGU,UAAU,CACc,IAAI,EAAE,IAAI,EACrC,IAAI,EAAE,OAAO;CAuBxB"}

package/lib/cjs/controllers/Users/Users.js

@@ -30,18 +30,18 @@ UserDto = __decorate([
         type: 'object',
         $id: 'arrow.common.userDto',
         properties: {
-            Login: { type: 'string', minLength: 3, maxLength: 32 },
-            Email: { type: 'string', format: 'email' },
-            Role: { type: 'string', minLength: 1, maxLength: 32 },
+            Login: { type: 'string', minLength: 3, maxLength: 32, description: 'Unique login name (3–32 characters)' },
+            Email: { type: 'string', format: 'email', description: 'Unique email address' },
+            Role: { type: 'string', minLength: 1, maxLength: 32, description: 'RBAC role to assign to the user' },
             Metadata: {
                 type: 'object',
                 $id: 'arrow.common.userMetadata',
                 properties: {
-                    Key: { type: 'string', minLength: 1, maxLength: 64 },
-                    Value: { type: 'string', minLength: 0, maxLength: 256 },
+                    Key: { type: 'string', minLength: 1, maxLength: 64, description: 'Metadata key' },
+                    Value: { type: 'string', minLength: 0, maxLength: 256, description: 'Metadata value' },
                 },
                 additionalProperties: true,
-                description: 'Additional metadata for the user, can be used to store custom data',
+                description: 'Optional key-value metadata to attach to the user account',
             },
         },
         required: ['Login', 'Email', 'Role'],
@@ -113,7 +113,31 @@ const USER_FILTER = [
         }
     }
 ];
+/**
+ * User account management (admin).
+ * Full CRUD operations for user accounts. Supports pagination, sorting, filtering,
+ * and optional relation loading. All write operations require full authorization.
+ * @tags Admin Users
+ */
 let Users = class Users extends http_1.BaseController {
+    /**
+     * List users (admin)
+     * Returns a paginated, sortable, filterable list of all users. Supports optional inclusion
+     * of related Metadata. The total user count (matching current filters) is returned in the
+     * X-Total-Count response header.
+     * Filterable fields: Uuid (eq), Email (eq, like), Login (eq, like), CreatedAt, LastLoginAt,
+     * DeletedAt (eq, gte, lte, lt, gt, isnull, notnull), IsActive (eq), Role (eq, neq),
+     * 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 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 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     */
     async list(pagination, order, include, filter) {
         const result = await rbac_1.User.select()
             .leftJoin("Metadata", function () {
@@ -124,12 +148,12 @@ let Users = class Users extends http_1.BaseController {
         }, function () {
             this.select('Value', "user:niceName");
         })
-            .populate(include)
+            .populate(include ?? [])
             .take(pagination?.limit ?? 10)
-            .skip(pagination?.limit * pagination?.page)
+            .skip((pagination?.limit ?? 0) * (pagination?.page ?? 0))
             .order(order?.column ?? 'CreatedAt', order?.order ?? orm_1.SortOrder.DESC)
-            .filter(filter?.filters, filter?.op, USER_FILTER);
-        const count = await rbac_1.User.query().filter(filter?.filters, filter?.op, USER_FILTER).selectCount();
+            .filter(filter?.filters ?? [], filter?.op, USER_FILTER);
+        const count = await rbac_1.User.query().filter(filter?.filters ?? [], filter?.op, USER_FILTER).selectCount();
         return new http_1.Ok(result.map((x) => x.dehydrateWithRelations({
             dateTimeFormat: "iso"
         })), {
@@ -141,21 +165,67 @@ let Users = class Users extends http_1.BaseController {
             ],
         });
     }
+    /**
+     * Get user by UUID (admin)
+     * Retrieves a single user record by UUID. Supports optional inclusion of related Metadata.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param include Relations to include — currently supports: Metadata
+     * @returns {IUserData} User account with optional Metadata relation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
     async getSingleUser(user, include) {
         // linter hack, to alow incldue param,it is used by FromModel qery arg
         include;
         return new http_1.Ok(user.dehydrateWithRelations({ dateTimeFormat: 'iso' }));
     }
+    /**
+     * Get user by login (admin)
+     * Retrieves a single user record by login name. Supports optional inclusion of related Metadata.
+     * @security cookieAuth
+     * @param user User login name path parameter
+     * @param include Relations to include — currently supports: Metadata
+     * @returns {IUserData} User account with optional Metadata relation
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     * @response 404 User not found
+     */
     async getByLogin(user, include) {
         // linter hack, to alow incldue param,it is used by FromModel qery arg
         include;
         return new http_1.Ok(user.dehydrateWithRelations({ dateTimeFormat: 'iso' }));
     }
+    /**
+     * 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.
+     * @security cookieAuth
+     * @returns {IUserData} Created user account
+     * @response 400 Validation error — missing required fields or invalid format
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — createAny permission required on users resource
+     * @response 409 Login or email already in use
+     */
     async addUser(data) {
         const temporaryPassword = this.PasswordProvider.generate();
         const u = await (0, rbac_1.create)(data.Email, data.Login, temporaryPassword, [data.Role], undefined, data.Metadata);
         return new http_1.Ok(u);
     }
+    /**
+     * 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.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 User updated successfully
+     * @response 400 Validation error — invalid field format
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required on users resource
+     * @response 404 User not found
+     * @response 409 Login or email already in use by another account
+     */
     async updateUser(user, data) {
         user.Login = data.Login ?? user.Login;
         user.Email = data.Email ?? user.Email;
@@ -175,7 +245,26 @@ let Users = class Users extends http_1.BaseController {
 exports.Users = Users;
 __decorate([
     (0, di_1.Autoinject)(),
-    __metadata("design:type", rbac_1.PasswordProvider)
+    __metadata("design:type", rbac_1.PasswordProvider
+    /**
+     * List users (admin)
+     * Returns a paginated, sortable, filterable list of all users. Supports optional inclusion
+     * of related Metadata. The total user count (matching current filters) is returned in the
+     * X-Total-Count response header.
+     * Filterable fields: Uuid (eq), Email (eq, like), Login (eq, like), CreatedAt, LastLoginAt,
+     * DeletedAt (eq, gte, lte, lt, gt, isnull, notnull), IsActive (eq), Role (eq, neq),
+     * 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 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 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required on users resource
+     */
+    )
 ], Users.prototype, "PasswordProvider", void 0);
 __decorate([
     (0, http_1.Get)("/"),