@twin.org/api-auth-entity-storage-service 0.0.3-next.9 → 0.9.0-next.1

package/dist/types/services/entityStorageAuthenticationService.d.ts

@@ -21,9 +21,15 @@ export declare class EntityStorageAuthenticationService implements IAuthenticati
     /**
      * The service needs to be started when the application is initialized.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns Nothing.
+     * @returns A promise that resolves when rate-limit actions have been registered and the node identity cached.
      */
     start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when all rate-limit actions have been unregistered.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Perform a login for the user.
      * @param email The email address for the user.
@@ -37,7 +43,7 @@ export declare class EntityStorageAuthenticationService implements IAuthenticati
     /**
      * Logout the current user.
      * @param token The token to logout, if it uses a mechanism with public access.
-     * @returns Nothing.
+     * @returns A promise that resolves when the logout audit entry has been recorded.
      */
     logout(token?: string): Promise<void>;
     /**
@@ -51,10 +57,9 @@ export declare class EntityStorageAuthenticationService implements IAuthenticati
     }>;
     /**
      * Update the user's password.
-     * @param email The email address of the user to update.
      * @param currentPassword The current password for the user.
      * @param newPassword The new password for the user.
-     * @returns Nothing.
+     * @returns A promise that resolves when the password has been updated and the rate limit cleared.
      */
-    updatePassword(email: string, currentPassword: string, newPassword: string): Promise<void>;
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
 }

package/dist/types/utils/passwordHelper.d.ts

@@ -1,3 +1,6 @@
+import type { IAuthenticationAuditComponent } from "@twin.org/api-auth-entity-storage-models";
+import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
+import type { AuthenticationUser } from "../entities/authenticationUser.js";
 /**
  * Helper class for password operations.
  */
@@ -7,10 +10,15 @@ export declare class PasswordHelper {
      */
     static readonly CLASS_NAME: string;
     /**
-     * Hash the password for the user.
-     * @param passwordBytes The password bytes.
-     * @param saltBytes The salt bytes.
-     * @returns The hashed password.
+     * Update the password for a user.
+     * Validates password strength, verifies the current password if provided, then hashes and stores the new password and raises an audit event.
+     * @param userEntityStorage The entity storage for users.
+     * @param authenticationAuditService The optional audit service.
+     * @param user The user whose password is being updated.
+     * @param newPassword The new password to set.
+     * @param currentPassword The current password to verify against, if supplied.
+     * @param minPasswordLength Optional minimum password length for validation.
+     * @returns A promise that resolves when the new password has been stored and the audit entry recorded.
      */
-    static hashPassword(passwordBytes: Uint8Array, saltBytes: Uint8Array): Promise<string>;
+    static updatePassword(userEntityStorage: IEntityStorageConnector<AuthenticationUser>, authenticationAuditService: IAuthenticationAuditComponent | undefined, user: AuthenticationUser, newPassword: string, currentPassword?: string, minPasswordLength?: number): Promise<void>;
 }

package/dist/types/utils/tokenHelper.d.ts

@@ -11,26 +11,32 @@ export declare class TokenHelper {
     /**
      * Create a new token.
      * @param vaultConnector The vault connector.
-     * @param signingKeyName The signing key name.
+     * @param nodeId The node identifier, embedded as the JWT issuer claim.
+     * @param signingKeyName The signing key name, embedded as the JWT key identifier.
      * @param userIdentity The subject for the token.
      * @param organizationIdentity The organization for the token.
      * @param tenantId The tenant id for the token.
      * @param ttlMinutes The time to live for the token in minutes.
+     * @param scope The scopes for the token.
+     * @param passwordVersion The user's current password version counter, embedded in the token so that a password change invalidates existing tokens.
      * @returns The new token and its expiry date.
      */
-    static createToken(vaultConnector: IVaultConnector, signingKeyName: string, userIdentity: string, organizationIdentity: string | undefined, tenantId: string | undefined, ttlMinutes: number): Promise<{
+    static createToken(vaultConnector: IVaultConnector, nodeId: string, signingKeyName: string, userIdentity: string, organizationIdentity: string | undefined, tenantId: string | undefined, ttlMinutes: number, scope?: string, passwordVersion?: number): Promise<{
         token: string;
         expiry: number;
     }>;
     /**
      * Verify the token.
      * @param vaultConnector The vault connector.
-     * @param signingKeyName The signing key name.
+     * @param nodeId The node identifier, expected to match the JWT issuer claim.
+     * @param signingKeyName The signing key name, expected to match the JWT key identifier.
      * @param token The token to verify.
+     * @param requiredScopes The required scopes.
+     * @param verifyUser A function to verify the user identity and organization. The password version counter embedded in the token (pver claim) is passed so callers can detect if the password has changed since the token was issued.
      * @returns The verified details.
      * @throws UnauthorizedError if the token is missing, invalid or expired.
      */
-    static verify(vaultConnector: IVaultConnector, signingKeyName: string, token: string | undefined): Promise<{
+    static verify(vaultConnector: IVaultConnector, nodeId: string, signingKeyName: string, token: string | undefined, requiredScopes?: string[], verifyUser?: (sub: string, org: string, tid: string | undefined, passwordVersion: number | undefined) => Promise<string[]>): Promise<{
         header: IJwtHeader;
         payload: IJwtPayload;
     }>;