@spinajs/rbac-http-user 2.0.468 → 2.0.471

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

@@ -2,7 +2,14 @@ import { UserLoginDto } from '../dto/userLogin-dto.js';
 import { BaseController, Ok, Unauthorized } from '@spinajs/http';
 import { AuthProvider, SessionProvider, AccessControl } from '@spinajs/rbac';
 import { Configuration } from '@spinajs/configuration';
+import { ILoginResponse } from '@spinajs/rbac-http';
 import { User } from '@spinajs/rbac';
+/**
+ * Authentication endpoints.
+ * Handles user login, logout, and current-session inspection.
+ * All session state is maintained via the signed `ssid` cookie.
+ * @tags Authentication
+ */
 export declare class LoginController extends BaseController {
     protected Configuration: Configuration;
     protected AuthProvider: AuthProvider;
@@ -12,8 +19,33 @@ export declare class LoginController extends BaseController {
     protected TwoFactorAuthForceUser: boolean;
     protected SessionCookieConfig: any;
     protected AC: AccessControl;
-    login(logged: User, ssid: string, credentials: UserLoginDto): Promise<Ok | Unauthorized>;
-    logout(ssid: string): Promise<Ok>;
-    whoami(User: User): Promise<Ok>;
+    /**
+     * Login
+     * Authenticates the user with email and password. On success, sets the signed `ssid` session cookie
+     * and returns user data with their RBAC grants. When two-factor authentication is enabled and
+     * configured for the user, the response instead signals that 2FA verification is required.
+     * If the caller already has an active session it is invalidated before creating a new one.
+     * @security []
+     * @returns {ILoginResponse} On full login: IUserWithGrants. On 2FA required: ITwoFactorAuthRequired. On 2FA setup required: ITwoFactorInitRequired
+     * @response 401 Invalid email or password
+     */
+    login(logged: User, ssid: string, credentials: UserLoginDto): Promise<Ok<ILoginResponse> | Unauthorized>;
+    /**
+     * Logout
+     * Destroys the current session identified by the `ssid` cookie and clears the cookie on the client.
+     * Requires the user to be logged in (session exists), but full authorization (2FA) is not required.
+     * @security cookieAuth
+     * @response 401 No active session
+     */
+    logout(ssid: string): Promise<Ok<any>>;
+    /**
+     * Get current user
+     * Returns the user object associated with the current session.
+     * Requires the user to be logged in (session exists), but full authorization (2FA) is not required.
+     * @security cookieAuth
+     * @returns {IUserProfile} User data from the current session
+     * @response 401 No active session
+     */
+    whoami(User: User): Promise<Ok<User>>;
 }
 //# sourceMappingURL=LoginController.d.ts.map

package/lib/cjs/controllers/LoginController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LoginController.d.ts","sourceRoot":"","sources":["../../../src/controllers/LoginController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAwB,EAAE,EAAe,YAAY,EAAU,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,YAAY,EAAE,eAAe,EAAsB,aAAa,EAAiB,MAAM,eAAe,CAAC;AAEhH,OAAO,EAA6B,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGlF,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC,qBACa,eAAgB,SAAQ,cAAc;IAEjD,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IAGvC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC;IAGrC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAK3C,SAAS,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAKxC,SAAS,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAMxC,SAAS,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAG1C,SAAS,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAGnC,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAGf,KAAK,CAAiB,MAAM,EAAE,IAAI,EAAgB,IAAI,EAAE,MAAM,EAAU,WAAW,EAAE,YAAY;IA8GjG,MAAM,CAAe,IAAI,EAAE,MAAM;IA4BjC,MAAM,CAAiB,IAAI,EAAE,IAAI;CAK/C"}
+{"version":3,"file":"LoginController.d.ts","sourceRoot":"","sources":["../../../src/controllers/LoginController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAwB,EAAE,EAAe,YAAY,EAAU,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,YAAY,EAAE,eAAe,EAAsB,aAAa,EAAiB,MAAM,eAAe,CAAC;AAEhH,OAAO,EAA6B,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAsC,cAAc,EAAmB,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC;;;;;GAKG;AACH,qBACa,eAAgB,SAAQ,cAAc;IAEjD,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IAGvC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC;IAGrC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAK3C,SAAS,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAKxC,SAAS,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAMxC,SAAS,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAG1C,SAAS,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAGnC,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAE5B;;;;;;;;;OASG;IAEU,KAAK,CAAiB,MAAM,EAAE,IAAI,EAAgB,IAAI,EAAE,MAAM,EAAU,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC,cAAc,CAAC,GAAG,YAAY,CAAC;IAwG3J;;;;;;OAMG;IAGU,MAAM,CAAe,IAAI,EAAE,MAAM;IA0B9C;;;;;;;OAOG;IAGU,MAAM,CAAiB,IAAI,EAAE,IAAI;CAK/C"}

package/lib/cjs/controllers/LoginController.js

@@ -20,7 +20,23 @@ const di_1 = require("@spinajs/di");
 const configuration_1 = require("@spinajs/configuration");
 const rbac_http_1 = require("@spinajs/rbac-http");
 const rbac_2 = require("@spinajs/rbac");
+/**
+ * Authentication endpoints.
+ * Handles user login, logout, and current-session inspection.
+ * All session state is maintained via the signed `ssid` cookie.
+ * @tags Authentication
+ */
 let LoginController = class LoginController extends http_1.BaseController {
+    /**
+     * Login
+     * Authenticates the user with email and password. On success, sets the signed `ssid` session cookie
+     * and returns user data with their RBAC grants. When two-factor authentication is enabled and
+     * configured for the user, the response instead signals that 2FA verification is required.
+     * If the caller already has an active session it is invalidated before creating a new one.
+     * @security []
+     * @returns {ILoginResponse} On full login: IUserWithGrants. On 2FA required: ITwoFactorAuthRequired. On 2FA setup required: ITwoFactorInitRequired
+     * @response 401 Invalid email or password
+     */
     async login(logged, ssid, credentials) {
         try {
             // if logged user is already logged in, delete his session
@@ -45,7 +61,7 @@ let LoginController = class LoginController extends http_1.BaseController {
                     },
                 },
             ];
-            let result = {};
+            let result;
             session.Data.set('User', user.Uuid);
             // we have two states for user
             // LOGGED - when user use proper login/password and session is created
@@ -61,9 +77,7 @@ let LoginController = class LoginController extends http_1.BaseController {
                 });
                 session.Data.set('Authorized', false);
                 session.Data.set('TwoFactorAuth', true);
-                result = {
-                    TwoFactorInitRequired: true,
-                };
+                result = { TwoFactorInitRequired: true };
             }
             else if (this.TwoFactorAuthEnabled && user.Metadata['2fa:enabled']) {
                 this._log.trace('User logged in, 2fa required', {
@@ -71,19 +85,17 @@ let LoginController = class LoginController extends http_1.BaseController {
                 });
                 session.Data.set('Authorized', false);
                 session.Data.set('TwoFactorAuth', true);
-                result = {
-                    TwoFactorAuthRequired: true,
-                };
+                result = { TwoFactorAuthRequired: true };
             }
             else {
                 session.Data.set('Authorized', true);
                 const grants = this.AC.getGrants();
                 const userGrants = user.Role.map(r => (0, rbac_1._unwindGrants)(r, grants));
                 const combinedGrants = Object.assign({}, ...userGrants);
+                // dehydrateWithRelations({ dateTimeFormat: 'iso' }) converts DateTime to ISO strings
+                // at runtime — the ORM types don't reflect the dateTimeFormat option in generics
                 result = {
-                    ...user.dehydrateWithRelations({
-                        dateTimeFormat: "iso"
-                    }),
+                    ...user.dehydrateWithRelations({ dateTimeFormat: "iso" }),
                     Grants: combinedGrants,
                 };
             }
@@ -105,6 +117,13 @@ let LoginController = class LoginController extends http_1.BaseController {
             });
         }
     }
+    /**
+     * Logout
+     * Destroys the current session identified by the `ssid` cookie and clears the cookie on the client.
+     * Requires the user to be logged in (session exists), but full authorization (2FA) is not required.
+     * @security cookieAuth
+     * @response 401 No active session
+     */
     async logout(ssid) {
         if (!ssid) {
             return new http_1.Ok();
@@ -127,6 +146,14 @@ let LoginController = class LoginController extends http_1.BaseController {
             ],
         });
     }
+    /**
+     * Get current user
+     * Returns the user object associated with the current session.
+     * Requires the user to be logged in (session exists), but full authorization (2FA) is not required.
+     * @security cookieAuth
+     * @returns {IUserProfile} User data from the current session
+     * @response 401 No active session
+     */
     async whoami(User) {
         // user is taken from session data
         return new http_1.Ok(User);

package/lib/cjs/controllers/LoginController.js.map

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

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

@@ -2,12 +2,48 @@ import { TokenDto } from './../dto/token-dto.js';
 import { BaseController, Ok, ForbiddenResponse } from '@spinajs/http';
 import { ISession, SessionProvider, User as UserModel, AccessControl } from '@spinajs/rbac';
 import { QueueService } from '@spinajs/queue';
+import { IEnable2faResponse, IUserWithGrants } from "@spinajs/rbac-http";
+/**
+ * Two-factor authentication (TOTP) management.
+ * Enables, disables, and verifies TOTP-based two-factor authentication for users.
+ * All routes are only available when 2FA is enabled in the system configuration.
+ * The caller must be logged in but does NOT need to be fully authorized (2FA verified),
+ * allowing these routes to be used during the 2FA verification step itself.
+ * @tags Two-Factor Authentication
+ */
 export declare class TwoFactorAuthController extends BaseController {
     protected Queue: QueueService;
     protected SessionProvider: SessionProvider;
     protected AC: AccessControl;
-    enable2fa(user: UserModel): Promise<Ok>;
-    disable2Fa(user: UserModel): Promise<Ok>;
-    verifyToken(logged: UserModel, token: TokenDto, session: ISession): Promise<Ok | ForbiddenResponse>;
+    /**
+     * Enable two-factor authentication
+     * Generates a TOTP secret for the authenticated user and returns the OTP provisioning URI
+     * to be scanned by an authenticator app. Throws if 2FA is already enabled for the user.
+     * @security cookieAuth
+     * @returns {IEnable2faResponse} OTP provisioning URI to scan with an authenticator app
+     * @response 400 Two-factor authentication is already enabled for this user
+     * @response 401 Unauthorized — valid session required
+     */
+    enable2fa(user: UserModel): Promise<Ok<IEnable2faResponse>>;
+    /**
+     * Disable two-factor authentication
+     * Removes the TOTP secret and disables 2FA for the authenticated user.
+     * Throws if 2FA is not currently enabled for the user.
+     * @security cookieAuth
+     * @response 200 Two-factor authentication disabled successfully
+     * @response 400 Two-factor authentication is not enabled for this user
+     * @response 401 Unauthorized — valid session required
+     */
+    disable2Fa(user: UserModel): Promise<Ok<any>>;
+    /**
+     * Verify TOTP token
+     * Validates the provided TOTP token against the user's 2FA secret. On success, marks the session
+     * as fully authorized and returns the user profile with RBAC grants — identical to a full login response.
+     * @security cookieAuth
+     * @returns {IUserWithGrants} User profile merged with RBAC grants on successful 2FA verification
+     * @response 403 Invalid or expired TOTP token
+     * @response 401 Unauthorized — valid session required
+     */
+    verifyToken(logged: UserModel, token: TokenDto, session: ISession): Promise<Ok<IUserWithGrants> | ForbiddenResponse>;
 }
 //# sourceMappingURL=TwoFactorAuthController.d.ts.map

package/lib/cjs/controllers/TwoFactorAuthController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TwoFactorAuthController.d.ts","sourceRoot":"","sources":["../../../src/controllers/TwoFactorAuthController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAY,EAAE,EAAa,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,IAAI,SAAS,EAAyC,aAAa,EAAE,MAAM,eAAe,CAAC;AAOnI,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAO9C,qBAGa,uBAAwB,SAAQ,cAAc;IAEvD,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC;IAG9B,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAG3C,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAGf,SAAS,CAAS,IAAI,EAAE,SAAS;IAajC,UAAU,CAAS,IAAI,EAAE,SAAS;IAUlC,WAAW,CAAS,MAAM,EAAE,SAAS,EAAU,KAAK,EAAE,QAAQ,EAAa,OAAO,EAAE,QAAQ;CAuC5G"}
+{"version":3,"file":"TwoFactorAuthController.d.ts","sourceRoot":"","sources":["../../../src/controllers/TwoFactorAuthController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAY,EAAE,EAAa,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,IAAI,SAAS,EAAyC,aAAa,EAAE,MAAM,eAAe,CAAC;AAOnI,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAA6B,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKpG;;;;;;;GAOG;AACH,qBAGa,uBAAwB,SAAQ,cAAc;IAEvD,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC;IAG9B,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAG3C,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAE5B;;;;;;;;OAQG;IAEU,SAAS,CAAS,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC;IAYhF;;;;;;;;OAQG;IAEU,UAAU,CAAS,IAAI,EAAE,SAAS;IAS/C;;;;;;;;OAQG;IAEU,WAAW,CAAS,MAAM,EAAE,SAAS,EAAU,KAAK,EAAE,QAAQ,EAAa,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,iBAAiB,CAAC;CA4C/J"}

package/lib/cjs/controllers/TwoFactorAuthController.js

@@ -26,7 +26,24 @@ const rbac_http_2 = require("@spinajs/rbac-http");
 const _2fa_js_1 = require("./../actions/2fa.js");
 const _2fa_js_2 = require("../actions/2fa.js");
 const exceptions_1 = require("@spinajs/exceptions");
+/**
+ * Two-factor authentication (TOTP) management.
+ * Enables, disables, and verifies TOTP-based two-factor authentication for users.
+ * All routes are only available when 2FA is enabled in the system configuration.
+ * The caller must be logged in but does NOT need to be fully authorized (2FA verified),
+ * allowing these routes to be used during the 2FA verification step itself.
+ * @tags Two-Factor Authentication
+ */
 let TwoFactorAuthController = class TwoFactorAuthController extends http_1.BaseController {
+    /**
+     * Enable two-factor authentication
+     * Generates a TOTP secret for the authenticated user and returns the OTP provisioning URI
+     * to be scanned by an authenticator app. Throws if 2FA is already enabled for the user.
+     * @security cookieAuth
+     * @returns {IEnable2faResponse} OTP provisioning URI to scan with an authenticator app
+     * @response 400 Two-factor authentication is already enabled for this user
+     * @response 401 Unauthorized — valid session required
+     */
     async enable2fa(user) {
         if (user.Metadata['2fa:enabled']) {
             throw new exceptions_1.InvalidOperation(`User ${user.Uuid} already has 2fa enabled`);
@@ -36,6 +53,15 @@ let TwoFactorAuthController = class TwoFactorAuthController extends http_1.BaseC
             otp: result
         });
     }
+    /**
+     * Disable two-factor authentication
+     * Removes the TOTP secret and disables 2FA for the authenticated user.
+     * Throws if 2FA is not currently enabled for the user.
+     * @security cookieAuth
+     * @response 200 Two-factor authentication disabled successfully
+     * @response 400 Two-factor authentication is not enabled for this user
+     * @response 401 Unauthorized — valid session required
+     */
     async disable2Fa(user) {
         if (!user.Metadata['2fa:enabled']) {
             throw new exceptions_1.InvalidOperation(`User ${user.Uuid} already has 2fa disabled`);
@@ -43,6 +69,15 @@ let TwoFactorAuthController = class TwoFactorAuthController extends http_1.BaseC
         await (0, _2fa_js_1.disableUser2Fa)(user);
         return new http_1.Ok();
     }
+    /**
+     * Verify TOTP token
+     * Validates the provided TOTP token against the user's 2FA secret. On success, marks the session
+     * as fully authorized and returns the user profile with RBAC grants — identical to a full login response.
+     * @security cookieAuth
+     * @returns {IUserWithGrants} User profile merged with RBAC grants on successful 2FA verification
+     * @response 403 Invalid or expired TOTP token
+     * @response 401 Unauthorized — valid session required
+     */
     async verifyToken(logged, token, session) {
         try {
             await (0, _2fa_js_1.auth2Fa)(logged, token.Token);
@@ -65,7 +100,12 @@ let TwoFactorAuthController = class TwoFactorAuthController extends http_1.BaseC
             });
         }
         catch (err) {
-            this._log.error(err);
+            if (err instanceof Error) {
+                this._log.error(err, "2fa verification failed");
+            }
+            else {
+                this._log.error("2fa verification failed", { error: err });
+            }
             return new http_1.ForbiddenResponse({
                 error: {
                     code: 'E_2FA_FAILED',

package/lib/cjs/controllers/TwoFactorAuthController.js.map

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

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

@@ -1,13 +1,47 @@
 import { PasswordDto } from '../dto/password-dto.js';
 import { User as UserModel, PasswordProvider, SessionProvider, AccessControl } from '@spinajs/rbac';
 import { BaseController, Ok } from '@spinajs/http';
+import { IGrantsMap } from '@spinajs/rbac-http';
+/**
+ * Current user profile management.
+ * Allows an authenticated user to read and modify their own account — refresh profile data,
+ * view their RBAC grants, and change their password.
+ * @tags User
+ */
 export declare class UserController extends BaseController {
     protected PasswordProvider: PasswordProvider;
     protected CoockieSecret: string;
     protected SessionProvider: SessionProvider;
     protected AC: AccessControl;
-    refresh(user: UserModel, ssid: string): Promise<Ok>;
-    getGrants(user: UserModel): Promise<Ok>;
-    newPassword(user: UserModel, pwd: PasswordDto): Promise<Ok>;
+    /**
+     * Refresh current user profile
+     * Reloads the authenticated user's record from the database (including metadata) and
+     * updates the session with the latest data. Returns the refreshed user data.
+     * @security cookieAuth
+     * @returns {IUserProfile} Refreshed user profile data
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
+    refresh(user: UserModel, ssid: string): Promise<Ok<import("@spinajs/orm").ModelData<UserModel>>>;
+    /**
+     * Get current user grants
+     * Returns the flattened RBAC grants for the authenticated user, combining all roles
+     * the user is assigned to into a single permission map keyed by resource.
+     * @security cookieAuth
+     * @returns {IGrantsMap} Combined RBAC grants map: resource → action → permission descriptor
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
+    getGrants(user: UserModel): Promise<Ok<IGrantsMap>>;
+    /**
+     * Change own password
+     * Changes the authenticated user's password. Requires the current (old) password for verification.
+     * The new password and its confirmation must match.
+     * @security cookieAuth
+     * @response 400 Old password is incorrect, or new passwords do not match
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
+    newPassword(user: UserModel, pwd: PasswordDto): Promise<Ok<unknown>>;
 }
 //# sourceMappingURL=UserController.d.ts.map

package/lib/cjs/controllers/UserController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserController.d.ts","sourceRoot":"","sources":["../../../src/controllers/UserController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAgD,aAAa,EAAE,MAAM,eAAe,CAAC;AAClJ,OAAO,EAAE,cAAc,EAAiB,EAAE,EAA+B,MAAM,eAAe,CAAC;AAW/F,qBAGa,cAAe,SAAQ,cAAc;IAEhD,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAG7C,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;IAGhC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAG3C,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAIf,OAAO,CAAS,IAAI,EAAE,SAAS,EAAY,IAAI,EAAE,MAAM;IAmBvD,SAAS,CAAS,IAAI,EAAE,SAAS;IAYjC,WAAW,CAAS,IAAI,EAAE,SAAS,EAAU,GAAG,EAAE,WAAW;CAkB3E"}
+{"version":3,"file":"UserController.d.ts","sourceRoot":"","sources":["../../../src/controllers/UserController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAgD,aAAa,EAAE,MAAM,eAAe,CAAC;AAClJ,OAAO,EAAE,cAAc,EAAiB,EAAE,EAA+B,MAAM,eAAe,CAAC;AAM/F,OAAO,EAAgD,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAK9F;;;;;GAKG;AACH,qBAGa,cAAe,SAAQ,cAAc;IAEhD,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAG7C,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;IAGhC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAG3C,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC;IAE5B;;;;;;;;OAQG;IAGU,OAAO,CAAS,IAAI,EAAE,SAAS,EAAY,IAAI,EAAE,MAAM;IAiBpE;;;;;;;;OAQG;IAGU,SAAS,CAAS,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;IAUxE;;;;;;;;OAQG;IAGU,WAAW,CAAS,IAAI,EAAE,SAAS,EAAU,GAAG,EAAE,WAAW;CAkB3E"}

package/lib/cjs/controllers/UserController.js

@@ -55,7 +55,22 @@ const configuration_1 = require("@spinajs/configuration");
 const cs = __importStar(require("cookie-signature"));
 const rbac_http_1 = require("@spinajs/rbac-http");
 const util_1 = require("@spinajs/util");
+/**
+ * Current user profile management.
+ * Allows an authenticated user to read and modify their own account — refresh profile data,
+ * view their RBAC grants, and change their password.
+ * @tags User
+ */
 let UserController = class UserController extends http_1.BaseController {
+    /**
+     * Refresh current user profile
+     * Reloads the authenticated user's record from the database (including metadata) and
+     * updates the session with the latest data. Returns the refreshed user data.
+     * @security cookieAuth
+     * @returns {IUserProfile} Refreshed user profile data
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
     async refresh(user, ssid) {
         // get user data from db
         await user.refresh();
@@ -70,12 +85,30 @@ let UserController = class UserController extends http_1.BaseController {
         }
         return new http_1.Ok(user.dehydrate());
     }
+    /**
+     * Get current user grants
+     * Returns the flattened RBAC grants for the authenticated user, combining all roles
+     * the user is assigned to into a single permission map keyed by resource.
+     * @security cookieAuth
+     * @returns {IGrantsMap} Combined RBAC grants map: resource → action → permission descriptor
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
     async getGrants(user) {
         const grants = this.AC.getGrants();
         const userGrants = user.Role.map(r => (0, rbac_1._unwindGrants)(r, grants));
         const combinedGrants = Object.assign({}, ...userGrants);
         return new http_1.Ok(combinedGrants);
     }
+    /**
+     * Change own password
+     * Changes the authenticated user's password. Requires the current (old) password for verification.
+     * The new password and its confirmation must match.
+     * @security cookieAuth
+     * @response 400 Old password is incorrect, or new passwords do not match
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — insufficient permissions
+     */
     async newPassword(user, pwd) {
         if (pwd.Password !== pwd.ConfirmPassword) {
             throw new exceptions_1.InvalidArgument('password does not match');

package/lib/cjs/controllers/UserController.js.map

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

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

@@ -2,22 +2,145 @@ import { Ok, BaseController } from '@spinajs/http';
 import { User as UserModel, UserMetadata } from '@spinajs/rbac';
 import { PaginationDTO, OrderDTO, IFilterRequest } from '@spinajs/orm-http';
 import { UserMetadataDto } from '../dto/metadata-dto.js';
+import { FilterableUserMetadata } from '../models/FilterableUserMetadata.js';
+/**
+ * User metadata management.
+ * Provides CRUD operations for key-value metadata entries attached to user accounts.
+ * Admin routes operate on any user (identified by UUID), while own routes operate on the
+ * currently authenticated user's metadata.
+ * @tags User Metadata
+ */
 export declare class UserMetadataController extends BaseController {
     /**
-     *  SPECIFIC USER FUNCTIONS ( ADMIN FUNCTIONS )
+     * List metadata for a specific user (admin)
+     * Returns a paginated, filtered, and ordered list of metadata entries for the given user.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param pagination.page Page number (zero-based)
+     * @param pagination.limit Number of entries per page
+     * @param order.column Column to sort by (default: Id)
+     * @param order.order Sort direction: ASC or DESC (default: DESC)
+     * @returns {IUserMetadataEntry[]} Paginated list of metadata entries for the user
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required
+     * @response 404 User not found
      */
-    readUserMeta(user: UserModel, pagination?: PaginationDTO, order?: OrderDTO, filter?: IFilterRequest): Promise<Ok>;
-    getUserMeta(user: UserModel, key: string): Promise<Ok>;
-    addUserMetadata(user: UserModel, metadata: UserMetadata): Promise<Ok>;
-    updateUserMetadata(meta: UserMetadata, _user: UserModel, data: UserMetadataDto): Promise<Ok>;
-    deleteUserMetadata(user: UserModel, meta: number): Promise<Ok>;
+    readUserMeta(user: UserModel, pagination?: PaginationDTO, order?: OrderDTO, filter?: IFilterRequest): Promise<Ok<import("@spinajs/orm").ISelectQueryBuilder<FilterableUserMetadata[]> & import("@spinajs/orm").QueryScope>>;
     /**
-     * --------------------------------------------------------------------------
+     * Get a single metadata entry for a specific user (admin)
+     * Retrieves one metadata entry by key for the given user.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param key Metadata key to retrieve
+     * @returns {IUserMetadataEntry} Single metadata entry for the user
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readAny permission required
+     * @response 404 User or metadata key not found
+     */
+    getUserMeta(user: UserModel, key: string): Promise<Ok<UserMetadata>>;
+    /**
+     * Add or update metadata for a specific user (admin)
+     * Inserts a new metadata entry for the given user, or updates it if the key already exists.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @response 200 Metadata created or updated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required
+     * @response 404 User not found
+     */
+    addUserMetadata(user: UserModel, metadata: UserMetadata): Promise<Ok<any>>;
+    /**
+     * Update a metadata entry for a specific user (admin)
+     * Updates Key, Value, and Type of an existing metadata entry identified by Id or Key.
+     * @security cookieAuth
+     * @param _user User UUID path parameter (used for authorization scope)
+     * @param meta Metadata Id or Key to update
+
+     * @response 200 Metadata updated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateAny permission required
+     * @response 404 User or metadata entry not found
+     */
+    updateUserMetadata(meta: UserMetadata, _user: UserModel, data: UserMetadataDto): Promise<Ok<any>>;
+    /**
+     * Delete a metadata entry for a specific user (admin)
+     * Permanently removes a metadata entry by Id from the given user's metadata.
+     * @security cookieAuth
+     * @param user User UUID path parameter
+     * @param meta Metadata Id to delete
+     * @response 200 Metadata deleted successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteAny permission required
+     * @response 404 User or metadata entry not found
+     */
+    deleteUserMetadata(user: UserModel, meta: number): Promise<Ok<any>>;
+    /**
+     * List own metadata
+     * Returns a paginated, filtered, and ordered list of metadata entries for the authenticated user.
+     * @security cookieAuth
+     * @param pagination.page Page number (zero-based)
+     * @param pagination.limit Number of entries per page
+     * @param order.column Column to sort by (default: Id)
+     * @param order.order Sort direction: ASC or DESC (default: DESC)
+     * @returns {IUserMetadataEntry[]} Paginated list of own metadata entries
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readOwn permission required
+     */
+    /**
+     * List own metadata
+     * Returns a paginated, filtered, and ordered list of metadata entries for the authenticated user.
+     * @security cookieAuth
+     * @param pagination.page Page number (zero-based)
+     * @param pagination.limit Number of entries per page
+     * @param order.column Column to sort by (default: Id)
+     * @param order.order Sort direction: ASC or DESC (default: DESC)
+     * @returns {IUserMetadataEntry[]} Paginated list of own metadata entries
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readOwn permission required
+     */
+    readMeta(pagination?: PaginationDTO, order?: OrderDTO, filter?: IFilterRequest): Promise<Ok<import("@spinajs/orm").ISelectQueryBuilder<FilterableUserMetadata[]> & import("@spinajs/orm").QueryScope>>;
+    /**
+     * Get own metadata entry by key
+     * Retrieves a single metadata entry by key for the authenticated user.
+     * @security cookieAuth
+     * @param key Metadata key to retrieve
+     * @returns {IUserMetadataEntry} Single own metadata entry by key
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — readOwn permission required
+     * @response 404 Metadata key not found
+     */
+    getMeta(key: string): Promise<Ok<UserMetadata>>;
+    /**
+     * Add or update own metadata
+     * Inserts a new metadata entry for the authenticated user, or updates it if the key already exists.
+     * @security cookieAuth
+     * @response 200 Metadata created or updated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateOwn permission required
      */
-    readMeta(pagination?: PaginationDTO, order?: OrderDTO, filter?: IFilterRequest): Promise<Ok>;
-    getMeta(key: string): Promise<Ok>;
     addMetadata(metadata: UserMetadata): Promise<void>;
-    updateMetadata(meta: string, data: UserMetadataDto): Promise<Ok>;
-    deleteMetadata(meta: number): Promise<Ok>;
+    /**
+     * Update own metadata entry
+     * Updates Key, Value, and Type of an existing metadata entry identified by Id or Key.
+     * @security cookieAuth
+     * @param meta Metadata Id or Key to update
+
+     * @response 200 Metadata updated successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — updateOwn permission required
+     * @response 404 Metadata entry not found
+     */
+    updateMetadata(meta: string, data: UserMetadataDto): Promise<Ok<any>>;
+    /**
+     * Delete own metadata entry
+     * Permanently removes a metadata entry by Id from the authenticated user's metadata.
+     * @security cookieAuth
+     * @param meta Metadata Id to delete
+     * @response 200 Metadata deleted successfully
+     * @response 401 Unauthorized — valid session required
+     * @response 403 Forbidden — deleteOwn permission required
+     * @response 404 Metadata entry not found
+     */
+    deleteMetadata(meta: number): Promise<Ok<any>>;
 }
 //# sourceMappingURL=UserMetadataController.d.ts.map

package/lib/cjs/controllers/UserMetadataController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserMetadataController.d.ts","sourceRoot":"","sources":["../../../src/controllers/UserMetadataController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,EAAE,EAAwC,cAAc,EAAS,MAAM,eAAe,CAAC;AAChH,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAW,aAAa,EAAE,QAAQ,EAAU,cAAc,EAAa,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,qBAGa,sBAAuB,SAAQ,cAAc;IAGtD;;OAEG;IAIU,YAAY,CACc,IAAI,EAAE,SAAS,EACzC,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAEzB,MAAM,CAAC,EAAE,cAAc;IAcd,WAAW,CACe,IAAI,EAAE,SAAS,EACzC,GAAG,EAAE,MAAM;IASX,eAAe,CACW,IAAI,EAAE,SAAS,EACvC,QAAQ,EAAE,YAAY;IASxB,kBAAkB,CAOxB,IAAI,EAAE,YAAY,EACc,KAAK,EAAE,SAAS,EAC3C,IAAI,EAAE,eAAe;IAYpB,kBAAkB,CACQ,IAAI,EAAE,SAAS,EACzC,IAAI,EAAE,MAAM;IAWzB;;OAEG;IAMU,QAAQ,CACR,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAEzB,MAAM,CAAC,EAAE,cAAc;IAWd,OAAO,CAAU,GAAG,EAAE,MAAM;IAQ5B,WAAW,CAAY,QAAQ,EAAE,YAAY;IAM7C,cAAc,CAAU,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE,eAAe;IAYnE,cAAc,CAAU,IAAI,EAAE,MAAM;CAOpD"}
+{"version":3,"file":"UserMetadataController.d.ts","sourceRoot":"","sources":["../../../src/controllers/UserMetadataController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,EAAE,EAAwC,cAAc,EAAS,MAAM,eAAe,CAAC;AAChH,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAW,aAAa,EAAE,QAAQ,EAAU,cAAc,EAAa,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E;;;;;;GAMG;AACH,qBAGa,sBAAuB,SAAQ,cAAc;IAEtD;;;;;;;;;;;;;OAaG;IAGU,YAAY,CACc,IAAI,EAAE,SAAS,EACzC,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAEzB,MAAM,CAAC,EAAE,cAAc;IAY3B;;;;;;;;;;OAUG;IAGU,WAAW,CACe,IAAI,EAAE,SAAS,EACzC,GAAG,EAAE,MAAM;IAOxB;;;;;;;;;OASG;IAGU,eAAe,CACW,IAAI,EAAE,SAAS,EACvC,QAAQ,EAAE,YAAY;IAOrC;;;;;;;;;;;OAWG;IAGU,kBAAkB,CAOxB,IAAI,EAAE,YAAY,EACc,KAAK,EAAE,SAAS,EAC3C,IAAI,EAAE,eAAe;IAUjC;;;;;;;;;;OAUG;IAGU,kBAAkB,CACQ,IAAI,EAAE,SAAS,EACzC,IAAI,EAAE,MAAM;IASzB;;;;;;;;;;;OAWG;IAIH;;;;;;;;;;;OAWG;IAGU,QAAQ,CACR,UAAU,CAAC,EAAE,aAAa,EAC1B,KAAK,CAAC,EAAE,QAAQ,EAEzB,MAAM,CAAC,EAAE,cAAc;IAS3B;;;;;;;;;OASG;IAGU,OAAO,CAAU,GAAG,EAAE,MAAM;IAMzC;;;;;;;OAOG;IAGU,WAAW,CAAY,QAAQ,EAAE,YAAY;IAI1D;;;;;;;;;;OAUG;IAGU,cAAc,CAAU,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE,eAAe;IAUhF;;;;;;;;;OASG;IAGU,cAAc,CAAU,IAAI,EAAE,MAAM;CAOpD"}