@3sixty/api-auth-entity-storage-service 0.0.0-stage → 0.20.0-next.0

package/dist/types/models/IEntityStorageAuthenticationServiceConfig.d.ts

@@ -0,0 +1,36 @@
+import type { IAuthenticationRateActionConfig } from "@3sixty/api-auth-entity-storage-models";
+/**
+ * Configuration for the entity storage authentication service.
+ */
+export interface IEntityStorageAuthenticationServiceConfig {
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @default auth-signing
+     */
+    signingKeyName?: string;
+    /**
+     * The default time to live for the JWT.
+     * @default 60
+     */
+    defaultTtlMinutes?: number;
+    /**
+     * The minimum password length for new password validation.
+     * @default 8
+     */
+    minPasswordLength?: number;
+    /**
+     * Optional override for login failure rate limit.
+     * @default { maxAttempts: 5, windowMinutes: 15 }
+     */
+    loginRateLimit?: IAuthenticationRateActionConfig;
+    /**
+     * Optional override for password change rate limit.
+     * @default { maxAttempts: 5, windowMinutes: 15 }
+     */
+    passwordChangeRateLimit?: IAuthenticationRateActionConfig;
+    /**
+     * Optional override for token refresh rate limit.
+     * @default { maxAttempts: 30, windowMinutes: 60 }
+     */
+    tokenRefreshRateLimit?: IAuthenticationRateActionConfig;
+}

package/dist/types/models/IEntityStorageAuthenticationServiceConstructorOptions.d.ts

@@ -0,0 +1,35 @@
+import type { IEntityStorageAuthenticationServiceConfig } from "./IEntityStorageAuthenticationServiceConfig.js";
+/**
+ * Options for the EntityStorageAuthenticationService constructor.
+ */
+export interface IEntityStorageAuthenticationServiceConstructorOptions {
+    /**
+     * The entity storage for the users.
+     * @default authentication-user
+     */
+    userEntityStorageType?: string;
+    /**
+     * The vault for the private keys.
+     * @default vault
+     */
+    vaultConnectorType?: string;
+    /**
+     * The audit service.
+     * @default authentication-audit
+     */
+    authenticationAuditServiceType?: string;
+    /**
+     * The rate service.
+     * @default authentication-rate
+     */
+    authenticationRateServiceType?: string;
+    /**
+     * The component to retrieve tenant information.
+     * @default tenant-admin
+     */
+    tenantAdminComponentType?: string;
+    /**
+     * The configuration for the authentication.
+     */
+    config?: IEntityStorageAuthenticationServiceConfig;
+}

package/dist/types/processors/authHeaderProcessor.d.ts

@@ -0,0 +1,57 @@
+import { type IBaseRoute, type IBaseRouteProcessor, type IHttpResponse, type IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { IAuthHeaderProcessorConstructorOptions } from "../models/IAuthHeaderProcessorConstructorOptions.js";
+/**
+ * Handle a JWT token in the authorization header or cookies and validate it to populate request context identity.
+ */
+export declare class AuthHeaderProcessor implements IBaseRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of AuthHeaderProcessor.
+     * @param options Options for the processor.
+     */
+    constructor(options?: IAuthHeaderProcessorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the node identity and organization ID have been cached.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Stop the processor and release the token cache.
+     * @returns A promise that resolves when the processor has stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the JWT has been verified and the context populated, or an error response set.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the Set-Cookie header has been applied to the response if required.
+     */
+    post(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@3sixty/api-models";
+/**
+ * REST entry points for the authentication, authentication admin, and authentication audit services.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/routes/entityStorageAuthenticationAdminRoutes.d.ts

@@ -0,0 +1,62 @@
+import type { IAdminUserCreateRequest, IAdminUserGetByIdentityRequest, IAdminUserGetRequest, IAdminUserGetResponse, IAdminUserRemoveRequest, IAdminUserUpdatePasswordRequest, IAdminUserUpdateRequest } from "@3sixty/api-auth-entity-storage-models";
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsAuthenticationAdmin: ITag[];
+/**
+ * The REST routes for authentication admin.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesAuthenticationAdmin(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Create a new user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @param baseRouteName The base route name to use for the location header.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminCreateUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserCreateRequest, baseRouteName: string): Promise<ICreatedResponse>;
+/**
+ * Update an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminUpdateUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserUpdateRequest): Promise<INoContentResponse>;
+/**
+ * Update an existing user password.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminUpdateUserPassword(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserUpdatePasswordRequest): Promise<INoContentResponse>;
+/**
+ * Get an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminGetUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserGetRequest): Promise<IAdminUserGetResponse>;
+/**
+ * Get an existing user by identity.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminGetUserByIdentity(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserGetByIdentityRequest): Promise<IAdminUserGetResponse>;
+/**
+ * Remove an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminRemoveUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserRemoveRequest): Promise<INoContentResponse>;

package/dist/types/routes/entityStorageAuthenticationAuditRoutes.d.ts

@@ -0,0 +1,54 @@
+import type { IAuditCreateRequest, IAuditGetRequest, IAuditGetResponse, IAuditQueryRequest, IAuditQueryResponse, IAuditRemoveRequest, IAuditUpdateRequest } from "@3sixty/api-auth-entity-storage-models";
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsAuthenticationAudit: ITag[];
+/**
+ * The REST routes for authentication audit.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesAuthenticationAudit(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Create an authentication audit entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @param baseRouteName The base route name to use for the location header.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditCreate(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditCreateRequest, baseRouteName: string): Promise<ICreatedResponse>;
+/**
+ * Get an authentication audit entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditGet(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditGetRequest): Promise<IAuditGetResponse>;
+/**
+ * Update an authentication audit entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditUpdate(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditUpdateRequest): Promise<INoContentResponse>;
+/**
+ * Remove an authentication audit entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditRemove(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditRemoveRequest): Promise<INoContentResponse>;
+/**
+ * Query authentication audit entries.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditQuery(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditQueryRequest): Promise<IAuditQueryResponse>;

package/dist/types/routes/entityStorageAuthenticationRoutes.d.ts

@@ -0,0 +1,45 @@
+import type { ILoginRequest, ILoginResponse, ILogoutRequest, IRefreshTokenRequest, IRefreshTokenResponse, IUpdatePasswordRequest } from "@3sixty/api-auth-entity-storage-models";
+import type { IHttpRequestContext, INoContentResponse, IRestRoute, IRestRouteResponseOptions, ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsAuthentication: ITag[];
+/**
+ * The REST routes for authentication.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesAuthentication(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Login to the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationLogin(httpRequestContext: IHttpRequestContext, componentName: string, request: ILoginRequest): Promise<ILoginResponse & IRestRouteResponseOptions>;
+/**
+ * Logout from the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationLogout(httpRequestContext: IHttpRequestContext, componentName: string, request: ILogoutRequest): Promise<INoContentResponse & IRestRouteResponseOptions>;
+/**
+ * Refresh the login token.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationRefreshToken(httpRequestContext: IHttpRequestContext, componentName: string, request: IRefreshTokenRequest): Promise<IRefreshTokenResponse & IRestRouteResponseOptions>;
+/**
+ * Update the user's password.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationUpdatePassword(httpRequestContext: IHttpRequestContext, componentName: string, request: IUpdatePasswordRequest): Promise<INoContentResponse>;

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize the schema for the authentication service.
+ */
+export declare function initSchema(): void;

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

@@ -0,0 +1,65 @@
+import type { IAuthenticationAdminComponent, IAuthenticationUser } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationAdminServiceConstructorOptions } from "../models/IEntityStorageAuthenticationAdminServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication component using entity storage.
+ */
+export declare class EntityStorageAuthenticationAdminService implements IAuthenticationAdminComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The scope value that grants permission to assign privileged roles.
+     */
+    static readonly DEFAULT_ESCALATED_PRIVILEGE_SCOPE: string;
+    /**
+     * Create a new instance of EntityStorageAuthentication.
+     * @param options The dependencies for the identity connector.
+     */
+    constructor(options?: IEntityStorageAuthenticationAdminServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a login for the user.
+     * @param user The user to create.
+     * @returns A promise that resolves when the user account has been created and the audit entry recorded.
+     */
+    create(user: IAuthenticationUser & {
+        password: string;
+    }): Promise<void>;
+    /**
+     * Update a login for the user.
+     * @param user The user to update.
+     * @returns A promise that resolves when the user account has been updated and the audit entry recorded.
+     */
+    update(user: Partial<IAuthenticationUser>): Promise<void>;
+    /**
+     * Get a user by email.
+     * @param email The email address of the user to get.
+     * @returns The user details.
+     */
+    get(email: string): Promise<IAuthenticationUser>;
+    /**
+     * Get a user by identity.
+     * @param identity The identity of the user to get.
+     * @returns The user details.
+     */
+    getByIdentity(identity: string): Promise<IAuthenticationUser>;
+    /**
+     * Remove the current user.
+     * @param email The email address of the user to remove.
+     * @returns A promise that resolves when the user account has been removed and the audit entry recorded.
+     */
+    remove(email: string): Promise<void>;
+    /**
+     * Update the user's password.
+     * @param email The email address of the user to update.
+     * @param newPassword The new password for the user.
+     * @param currentPassword The current password, optional, if supplied will check against existing.
+     * @returns A promise that resolves when the password has been updated.
+     */
+    updatePassword(email: string, newPassword: string, currentPassword?: string): Promise<void>;
+}

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

@@ -0,0 +1,72 @@
+import type { AuthAuditEvent, IAuthenticationAuditComponent, IAuthenticationAuditEntry } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationAuditServiceConstructorOptions } from "../models/IEntityStorageAuthenticationAuditServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication audit component using entity storage.
+ */
+export declare class EntityStorageAuthenticationAuditService implements IAuthenticationAuditComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthenticationAuditService.
+     * @param options The dependencies for the identity connector.
+     */
+    constructor(options?: IEntityStorageAuthenticationAuditServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a new audit entry.
+     * @param entry The audit entry to be logged.
+     * @returns The unique identifier of the created audit entry.
+     */
+    create(entry: Omit<IAuthenticationAuditEntry, "id" | "dateCreated">): Promise<string>;
+    /**
+     * Get an audit entry by id.
+     * @param id The unique identifier of the audit entry.
+     * @returns The audit entry.
+     */
+    get(id: string): Promise<IAuthenticationAuditEntry>;
+    /**
+     * Update an audit entry.
+     * @param id The unique identifier of the audit entry to update.
+     * @param entry The fields to update on the audit entry.
+     * @returns A promise that resolves when the audit entry has been updated.
+     */
+    update(id: string, entry: Partial<Omit<IAuthenticationAuditEntry, "id" | "dateCreated">>): Promise<void>;
+    /**
+     * Remove an audit entry.
+     * @param id The unique identifier of the audit entry to remove.
+     * @returns A promise that resolves when the audit entry has been removed.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Query the audit entries.
+     * @param options The query options.
+     * @param options.actorId The actor identifier to filter the audit entries, optional.
+     * @param options.organizationId The organization identifier to filter the audit entries, optional.
+     * @param options.tenantId The tenant identifier to filter the audit entries, optional.
+     * @param options.nodeId The node identifier to filter the audit entries, optional.
+     * @param options.event The audit event to filter the audit entries, optional.
+     * @param options.startDate The start date to filter the audit entries, optional.
+     * @param options.endDate The end date to filter the audit entries, optional.
+     * @param cursor The cursor for pagination.
+     * @param limit The maximum number of entries to return.
+     * @returns The audit entries.
+     */
+    query(options?: {
+        actorId?: string;
+        organizationId?: string;
+        tenantId?: string;
+        nodeId?: string;
+        event?: AuthAuditEvent | string;
+        startDate?: string;
+        endDate?: string;
+    }, cursor?: string, limit?: number): Promise<{
+        entries: IAuthenticationAuditEntry[];
+        cursor?: string;
+    }>;
+}

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

@@ -0,0 +1,60 @@
+import type { IAuthenticationRateActionConfig, IAuthenticationRateComponent } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationRateServiceConstructorOptions } from "../models/IEntityStorageAuthenticationRateServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication rate component using entity storage.
+ */
+export declare class EntityStorageAuthenticationRateService implements IAuthenticationRateComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthenticationRateService.
+     * @param options The constructor options.
+     */
+    constructor(options?: IEntityStorageAuthenticationRateServiceConstructorOptions);
+    /**
+     * Register or update rate-limit configuration for an action.
+     * @param action The action name.
+     * @param config The action configuration.
+     * @returns A promise that resolves when the action configuration has been stored.
+     */
+    registerAction(action: string, config: IAuthenticationRateActionConfig): Promise<void>;
+    /**
+     * Unregister rate-limit configuration for an action.
+     * @param action The action name.
+     * @returns A promise that resolves when the action configuration has been removed.
+     */
+    unregisterAction(action: string): Promise<void>;
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the periodic cleanup task has been registered.
+     */
+    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 the periodic cleanup task has been removed.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Check the authentication rate for a given action and identifier.
+     * @param action The action to be checked.
+     * @param identifier The identifier to be checked.
+     * @returns The rate entry id.
+     */
+    check(action: string, identifier: string): Promise<string>;
+    /**
+     * Clear the authentication rate entry for the given action and identifier.
+     * @param action The action to clear.
+     * @param identifier The identifier to clear.
+     * @returns A promise that resolves when the rate entry has been removed.
+     */
+    clear(action: string, identifier: string): Promise<void>;
+}

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

@@ -0,0 +1,65 @@
+import type { IAuthenticationComponent } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationServiceConstructorOptions } from "../models/IEntityStorageAuthenticationServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication component using entity storage.
+ */
+export declare class EntityStorageAuthenticationService implements IAuthenticationComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthentication.
+     * @param options The dependencies for the identity connector.
+     */
+    constructor(options?: IEntityStorageAuthenticationServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @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.
+     * @param password The password for the user.
+     * @returns The authentication token for the user, if it uses a mechanism with public access.
+     */
+    login(email: string, password: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Logout the current user.
+     * @param token The token to logout, if it uses a mechanism with public access.
+     * @returns A promise that resolves when the logout audit entry has been recorded.
+     */
+    logout(token?: string): Promise<void>;
+    /**
+     * Refresh the token.
+     * @param token The token to refresh, if it uses a mechanism with public access.
+     * @returns The refreshed token, if it uses a mechanism with public access.
+     */
+    refresh(token?: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Update the user's password.
+     * @param currentPassword The current password for the user.
+     * @param newPassword The new password for the user.
+     * @returns A promise that resolves when the password has been updated and the rate limit cleared.
+     */
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
+}

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

@@ -0,0 +1,24 @@
+import type { IAuthenticationAuditComponent } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageConnector } from "@3sixty/entity-storage-models";
+import type { AuthenticationUser } from "../entities/authenticationUser.js";
+/**
+ * Helper class for password operations.
+ */
+export declare class PasswordHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * 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 updatePassword(userEntityStorage: IEntityStorageConnector<AuthenticationUser>, authenticationAuditService: IAuthenticationAuditComponent | undefined, user: AuthenticationUser, newPassword: string, currentPassword?: string, minPasswordLength?: number): Promise<void>;
+}

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

@@ -0,0 +1,60 @@
+import { type IVaultConnector } from "@3sixty/vault-models";
+import { type IHttpHeaders, type IJwtHeader, type IJwtPayload } from "@3sixty/web";
+/**
+ * Helper class for token operations.
+ */
+export declare class TokenHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new token.
+     * @param vaultConnector The vault connector.
+     * @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, 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 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, 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;
+    }>;
+    /**
+     * Verify that a token carries all of the required scopes.
+     * @param scope The comma separated scopes from the token.
+     * @param requiredScopes The scopes the caller must hold.
+     * @throws UnauthorizedError if any of the required scopes is missing.
+     */
+    static verifyScopes(scope: string | undefined, requiredScopes?: string[]): void;
+    /**
+     * Extract the auth token from the headers, either from the authorization header or the cookie header.
+     * @param headers The headers to extract the token from.
+     * @param cookieName The name of the cookie to extract the token from.
+     * @returns The token if found.
+     */
+    static extractTokenFromHeaders(headers?: IHttpHeaders, cookieName?: string): {
+        token: string;
+        location: "authorization" | "cookie";
+    } | undefined;
+}