@twin.org/api-auth-entity-storage-service 0.0.3-next.21 → 0.0.3-next.23

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

@@ -1,3 +1,4 @@
+import type { IAuthenticationRateActionConfig } from "@twin.org/api-auth-entity-storage-models";
 /**
  * Configuration for the entity storage authentication service.
  */
@@ -9,7 +10,22 @@ export interface IEntityStorageAuthenticationServiceConfig {
     signingKeyName?: string;
     /**
      * The default time to live for the JWT.
-     * @default 1440
+     * @default 60
      */
     defaultTtlMinutes?: 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

@@ -18,6 +18,16 @@ export interface IEntityStorageAuthenticationServiceConstructorOptions {
      * @default authentication-admin
      */
     authenticationAdminServiceType?: string;
+    /**
+     * The audit service.
+     * @default authentication-audit
+     */
+    authenticationAuditServiceType?: string;
+    /**
+     * The rate service.
+     * @default authentication-rate
+     */
+    authenticationRateServiceType?: string;
     /**
      * The configuration for the authentication.
      */

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

@@ -0,0 +1,29 @@
+import type { IAuditCreateRequest, IAuditQueryRequest, IAuditQueryResponse } from "@twin.org/api-auth-entity-storage-models";
+import type { ICreatedResponse, IHttpRequestContext, IRestRoute, ITag } from "@twin.org/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.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAuditCreate(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditCreateRequest): Promise<ICreatedResponse>;
+/**
+ * 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/services/entityStorageAuthenticationAuditService.d.ts

@@ -0,0 +1,59 @@
+import type { AuthAuditEvent, IAuthenticationAuditComponent, IAuthenticationAuditEntry } from "@twin.org/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>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Hash a list of IP addresses using SHA-256.
+     * @param ipAddresses The IP addresses to hash.
+     * @returns The hexadecimal hashes of the salted IPs.
+     */
+    private hashIpAddresses;
+}

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

@@ -0,0 +1,60 @@
+import type { IAuthenticationRateActionConfig, IAuthenticationRateComponent } from "@twin.org/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 Nothing.
+     */
+    registerAction(action: string, config: IAuthenticationRateActionConfig): Promise<void>;
+    /**
+     * Unregister rate-limit configuration for an action.
+     * @param action The action name.
+     * @returns Nothing.
+     */
+    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 Nothing.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    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 Nothing.
+     */
+    clear(action: string, identifier: string): Promise<void>;
+}

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

@@ -24,6 +24,12 @@ export declare class EntityStorageAuthenticationService implements IAuthenticati
      * @returns Nothing.
      */
     start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Perform a login for the user.
      * @param email The email address for the user.

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

@@ -29,10 +29,11 @@ export declare class TokenHelper {
      * @param signingKeyName The signing key name.
      * @param token The token to verify.
      * @param requiredScopes The required scopes.
+     * @param verifyUser A function to verify the user identity and organization, which can be used to check if the user is still active or not.
      * @returns The verified details.
      * @throws UnauthorizedError if the token is missing, invalid or expired.
      */
-    static verify(vaultConnector: IVaultConnector, signingKeyName: string, token: string | undefined, requiredScopes?: string[]): Promise<{
+    static verify(vaultConnector: IVaultConnector, signingKeyName: string, token: string | undefined, requiredScopes?: string[], verifyUser?: (userIdentity: string, organizationIdentity: string) => Promise<string[]>): Promise<{
         header: IJwtHeader;
         payload: IJwtPayload;
     }>;

package/docs/changelog.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.0.3-next.23](https://github.com/twinfoundation/api/compare/api-auth-entity-storage-service-v0.0.3-next.22...api-auth-entity-storage-service-v0.0.3-next.23) (2026-04-14)
+
+
+### Features
+
+* auth enhancements ([#93](https://github.com/twinfoundation/api/issues/93)) ([921a50c](https://github.com/twinfoundation/api/commit/921a50cd89d26e530a6be6174a5a803060fa0eb6))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-auth-entity-storage-models bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/api-core bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/api-models bumped from 0.0.3-next.22 to 0.0.3-next.23
+
+## [0.0.3-next.22](https://github.com/twinfoundation/api/compare/api-auth-entity-storage-service-v0.0.3-next.21...api-auth-entity-storage-service-v0.0.3-next.22) (2026-03-27)
+
+
+### Miscellaneous Chores
+
+* **api-auth-entity-storage-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-auth-entity-storage-models bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/api-core bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/api-models bumped from 0.0.3-next.21 to 0.0.3-next.22
+
 ## [0.0.3-next.21](https://github.com/twinfoundation/api/compare/api-auth-entity-storage-service-v0.0.3-next.20...api-auth-entity-storage-service-v0.0.3-next.21) (2026-03-11)
 
 

package/docs/reference/classes/AuthHeaderProcessor.md

@@ -28,7 +28,7 @@ Options for the processor.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -54,7 +54,7 @@ The class name of the component.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -80,7 +80,7 @@ Nothing.
 
 ***
 
-### pre()
+### pre() {#pre}
 
 > **pre**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
 
@@ -102,9 +102,9 @@ The outgoing response.
 
 ##### route
 
-The route to process.
+`IBaseRoute` \| `undefined`
 
-`IBaseRoute` | `undefined`
+The route to process.
 
 ##### contextIds
 
@@ -126,7 +126,7 @@ The state handed through the processors.
 
 ***
 
-### post()
+### post() {#post}
 
 > **post**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
 
@@ -148,9 +148,9 @@ The outgoing response.
 
 ##### route
 
-The route to process.
+`IBaseRoute` \| `undefined`
 
-`IBaseRoute` | `undefined`
+The route to process.
 
 ##### contextIds
 

package/docs/reference/classes/AuthenticationAuditEntry.md

@@ -0,0 +1,101 @@
+# Class: AuthenticationAuditEntry
+
+Class defining the storage for authentication audit entries.
+
+## Constructors
+
+### Constructor
+
+> **new AuthenticationAuditEntry**(): `AuthenticationAuditEntry`
+
+#### Returns
+
+`AuthenticationAuditEntry`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the audit entry.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The timestamp of the audit entry in ISO 8601 format.
+
+***
+
+### event {#event}
+
+> **event**: `string`
+
+The audit event that occurred.
+
+***
+
+### actorId? {#actorid}
+
+> `optional` **actorId?**: `string`
+
+The actor identifier, could be e-mail, username, or other unique identifier.
+
+***
+
+### nodeId? {#nodeid}
+
+> `optional` **nodeId?**: `string`
+
+The node identifier associated with the audit entry, if applicable.
+
+***
+
+### organizationId? {#organizationid}
+
+> `optional` **organizationId?**: `string`
+
+The organization identifier associated with the audit entry, if applicable.
+
+***
+
+### tenantId? {#tenantid}
+
+> `optional` **tenantId?**: `string`
+
+The tenant identifier associated with the audit entry, if applicable.
+
+***
+
+### ipAddressHashes? {#ipaddresshashes}
+
+> `optional` **ipAddressHashes?**: `string`[]
+
+The hashed IP addresses of the client.
+
+***
+
+### userAgent? {#useragent}
+
+> `optional` **userAgent?**: `string`
+
+The user agent string of the client.
+
+***
+
+### correlationId? {#correlationid}
+
+> `optional` **correlationId?**: `string`
+
+The correlation ID for request tracing.
+
+***
+
+### data? {#data}
+
+> `optional` **data?**: `unknown`
+
+Additional data related to the audit entry, such as IP address, user agent, etc.

package/docs/reference/classes/AuthenticationRateEntry.md

@@ -0,0 +1,37 @@
+# Class: AuthenticationRateEntry
+
+Class defining the storage for authentication rate entries.
+
+## Constructors
+
+### Constructor
+
+> **new AuthenticationRateEntry**(): `AuthenticationRateEntry`
+
+#### Returns
+
+`AuthenticationRateEntry`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The id for the rate entry.
+
+***
+
+### timestamps {#timestamps}
+
+> **timestamps**: `string`[]
+
+Array of ISO date strings representing timestamps of failed attempts.
+
+***
+
+### dateModified {#datemodified}
+
+> **dateModified**: `string`
+
+Last modification time in ISO date format.

package/docs/reference/classes/AuthenticationUser.md

@@ -14,7 +14,7 @@ Class defining the storage for user login credentials.
 
 ## Properties
 
-### email
+### email {#email}
 
 > **email**: `string`
 
@@ -22,7 +22,7 @@ The user e-mail address.
 
 ***
 
-### password
+### password {#password}
 
 > **password**: `string`
 
@@ -30,7 +30,7 @@ The encrypted password for the user.
 
 ***
 
-### salt
+### salt {#salt}
 
 > **salt**: `string`
 
@@ -38,7 +38,7 @@ The salt for the password.
 
 ***
 
-### identity
+### identity {#identity}
 
 > **identity**: `string`
 
@@ -46,7 +46,7 @@ The user identity.
 
 ***
 
-### organization
+### organization {#organization}
 
 > **organization**: `string`
 
@@ -54,7 +54,7 @@ The users organization.
 
 ***
 
-### scope
+### scope {#scope}
 
 > **scope**: `string`
 

package/docs/reference/classes/EntityStorageAuthenticationAdminService.md

@@ -28,7 +28,7 @@ The dependencies for the identity connector.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -54,7 +54,7 @@ The class name of the component.
 
 ***
 
-### create()
+### create() {#create}
 
 > **create**(`user`): `Promise`\<`void`\>
 
@@ -80,7 +80,7 @@ Nothing.
 
 ***
 
-### update()
+### update() {#update}
 
 > **update**(`user`): `Promise`\<`void`\>
 
@@ -106,9 +106,9 @@ Nothing.
 
 ***
 
-### get()
+### get() {#get}
 
-> **get**(`email`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
+> **get**(`email`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"password"` \| `"salt"`\>\>
 
 Get a user by email.
 
@@ -122,7 +122,7 @@ The email address of the user to get.
 
 #### Returns
 
-`Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
+`Promise`\<`Omit`\<`IAuthenticationUser`, `"password"` \| `"salt"`\>\>
 
 The user details.
 
@@ -132,9 +132,9 @@ The user details.
 
 ***
 
-### getByIdentity()
+### getByIdentity() {#getbyidentity}
 
-> **getByIdentity**(`identity`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
+> **getByIdentity**(`identity`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"password"` \| `"salt"`\>\>
 
 Get a user by identity.
 
@@ -148,7 +148,7 @@ The identity of the user to get.
 
 #### Returns
 
-`Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
+`Promise`\<`Omit`\<`IAuthenticationUser`, `"password"` \| `"salt"`\>\>
 
 The user details.
 
@@ -158,7 +158,7 @@ The user details.
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`email`): `Promise`\<`void`\>
 
@@ -184,7 +184,7 @@ Nothing.
 
 ***
 
-### updatePassword()
+### updatePassword() {#updatepassword}
 
 > **updatePassword**(`email`, `newPassword`, `currentPassword?`): `Promise`\<`void`\>