@twin.org/api-auth-entity-storage-service 0.0.3-next.22 → 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,21 @@
 # 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)
 
 

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/EntityStorageAuthenticationAdminService.md

@@ -108,7 +108,7 @@ Nothing.
 
 ### 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.
 
@@ -134,7 +134,7 @@ The user details.
 
 ### 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.
 

package/docs/reference/classes/EntityStorageAuthenticationAuditService.md

@@ -0,0 +1,157 @@
+# Class: EntityStorageAuthenticationAuditService
+
+Implementation of the authentication audit component using entity storage.
+
+## Implements
+
+- `IAuthenticationAuditComponent`
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageAuthenticationAuditService**(`options?`): `EntityStorageAuthenticationAuditService`
+
+Create a new instance of EntityStorageAuthenticationAuditService.
+
+#### Parameters
+
+##### options?
+
+[`IEntityStorageAuthenticationAuditServiceConstructorOptions`](../interfaces/IEntityStorageAuthenticationAuditServiceConstructorOptions.md)
+
+The dependencies for the identity connector.
+
+#### Returns
+
+`EntityStorageAuthenticationAuditService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IAuthenticationAuditComponent.className`
+
+***
+
+### create() {#create}
+
+> **create**(`entry`): `Promise`\<`string`\>
+
+Create a new audit entry.
+
+#### Parameters
+
+##### entry
+
+`Omit`\<`IAuthenticationAuditEntry`, `"id"` \| `"dateCreated"`\>
+
+The audit entry to be logged.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The unique identifier of the created audit entry.
+
+#### Implementation of
+
+`IAuthenticationAuditComponent.create`
+
+***
+
+### query() {#query}
+
+> **query**(`options?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuthenticationAuditEntry`[]; `cursor?`: `string`; \}\>
+
+Query the audit entries.
+
+#### Parameters
+
+##### options?
+
+The query options.
+
+###### actorId?
+
+`string`
+
+The actor identifier to filter the audit entries, optional.
+
+###### organizationId?
+
+`string`
+
+The organization identifier to filter the audit entries, optional.
+
+###### tenantId?
+
+`string`
+
+The tenant identifier to filter the audit entries, optional.
+
+###### nodeId?
+
+`string`
+
+The node identifier to filter the audit entries, optional.
+
+###### event?
+
+`string`
+
+The audit event to filter the audit entries, optional.
+
+###### startDate?
+
+`string`
+
+The start date to filter the audit entries, optional.
+
+###### endDate?
+
+`string`
+
+The end date to filter the audit entries, optional.
+
+##### cursor?
+
+`string`
+
+The cursor for pagination.
+
+##### limit?
+
+`number`
+
+The maximum number of entries to return.
+
+#### Returns
+
+`Promise`\<\{ `entries`: `IAuthenticationAuditEntry`[]; `cursor?`: `string`; \}\>
+
+The audit entries.
+
+#### Implementation of
+
+`IAuthenticationAuditComponent.query`