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

package/docs/reference/classes/EntityStorageAuthenticationRateService.md

@@ -0,0 +1,227 @@
+# Class: EntityStorageAuthenticationRateService
+
+Implementation of the authentication rate component using entity storage.
+
+## Implements
+
+- `IAuthenticationRateComponent`
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageAuthenticationRateService**(`options?`): `EntityStorageAuthenticationRateService`
+
+Create a new instance of EntityStorageAuthenticationRateService.
+
+#### Parameters
+
+##### options?
+
+[`IEntityStorageAuthenticationRateServiceConstructorOptions`](../interfaces/IEntityStorageAuthenticationRateServiceConstructorOptions.md)
+
+The constructor options.
+
+#### Returns
+
+`EntityStorageAuthenticationRateService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### registerAction() {#registeraction}
+
+> **registerAction**(`action`, `config`): `Promise`\<`void`\>
+
+Register or update rate-limit configuration for an action.
+
+#### Parameters
+
+##### action
+
+`string`
+
+The action name.
+
+##### config
+
+`IAuthenticationRateActionConfig`
+
+The action configuration.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.registerAction`
+
+***
+
+### unregisterAction() {#unregisteraction}
+
+> **unregisterAction**(`action`): `Promise`\<`void`\>
+
+Unregister rate-limit configuration for an action.
+
+#### Parameters
+
+##### action
+
+`string`
+
+The action name.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.unregisterAction`
+
+***
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The service needs to be started when the application is initialized.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.start`
+
+***
+
+### stop() {#stop}
+
+> **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be stopped when the node is closed.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.stop`
+
+***
+
+### check() {#check}
+
+> **check**(`action`, `identifier`): `Promise`\<`string`\>
+
+Check the authentication rate for a given action and identifier.
+
+#### Parameters
+
+##### action
+
+`string`
+
+The action to be checked.
+
+##### identifier
+
+`string`
+
+The identifier to be checked.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The rate entry id.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.check`
+
+***
+
+### clear() {#clear}
+
+> **clear**(`action`, `identifier`): `Promise`\<`void`\>
+
+Clear the authentication rate entry for the given action and identifier.
+
+#### Parameters
+
+##### action
+
+`string`
+
+The action to clear.
+
+##### identifier
+
+`string`
+
+The identifier to clear.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.clear`

package/docs/reference/classes/EntityStorageAuthenticationService.md

@@ -80,6 +80,32 @@ Nothing.
 
 ***
 
+### stop() {#stop}
+
+> **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be stopped when the node is closed.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationComponent.stop`
+
+***
+
 ### login() {#login}
 
 > **login**(`email`, `password`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>

package/docs/reference/classes/TokenHelper.md

@@ -82,7 +82,7 @@ The new token and its expiry date.
 
 ### verify() {#verify}
 
-> `static` **verify**(`vaultConnector`, `signingKeyName`, `token`, `requiredScopes?`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+> `static` **verify**(`vaultConnector`, `signingKeyName`, `token`, `requiredScopes?`, `verifyUser?`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
 
 Verify the token.
 
@@ -112,6 +112,12 @@ The token to verify.
 
 The required scopes.
 
+##### verifyUser?
+
+(`userIdentity`, `organizationIdentity`) => `Promise`\<`string`[]\>
+
+A function to verify the user identity and organization, which can be used to check if the user is still active or not.
+
 #### Returns
 
 `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>

package/docs/reference/functions/authenticationAuditCreate.md

@@ -0,0 +1,31 @@
+# Function: authenticationAuditCreate()
+
+> **authenticationAuditCreate**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ICreatedResponse`\>
+
+Create an authentication audit entry.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAuditCreateRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ICreatedResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAuditQuery.md

@@ -0,0 +1,31 @@
+# Function: authenticationAuditQuery()
+
+> **authenticationAuditQuery**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAuditQueryResponse`\>
+
+Query authentication audit entries.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAuditQueryRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAuditQueryResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/generateRestRoutesAuthenticationAudit.md

@@ -0,0 +1,25 @@
+# Function: generateRestRoutesAuthenticationAudit()
+
+> **generateRestRoutesAuthenticationAudit**(`baseRouteName`, `componentName`): `IRestRoute`\<`any`, `any`\>[]
+
+The REST routes for authentication audit.
+
+## Parameters
+
+### baseRouteName
+
+`string`
+
+Prefix to prepend to the paths.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes stored in the ComponentFactory.
+
+## Returns
+
+`IRestRoute`\<`any`, `any`\>[]
+
+The generated routes.

package/docs/reference/index.md

@@ -2,9 +2,13 @@
 
 ## Classes
 
+- [AuthenticationAuditEntry](classes/AuthenticationAuditEntry.md)
+- [AuthenticationRateEntry](classes/AuthenticationRateEntry.md)
 - [AuthenticationUser](classes/AuthenticationUser.md)
 - [AuthHeaderProcessor](classes/AuthHeaderProcessor.md)
 - [EntityStorageAuthenticationAdminService](classes/EntityStorageAuthenticationAdminService.md)
+- [EntityStorageAuthenticationAuditService](classes/EntityStorageAuthenticationAuditService.md)
+- [EntityStorageAuthenticationRateService](classes/EntityStorageAuthenticationRateService.md)
 - [EntityStorageAuthenticationService](classes/EntityStorageAuthenticationService.md)
 - [TokenHelper](classes/TokenHelper.md)
 
@@ -14,6 +18,10 @@
 - [IAuthHeaderProcessorConstructorOptions](interfaces/IAuthHeaderProcessorConstructorOptions.md)
 - [IEntityStorageAuthenticationAdminServiceConfig](interfaces/IEntityStorageAuthenticationAdminServiceConfig.md)
 - [IEntityStorageAuthenticationAdminServiceConstructorOptions](interfaces/IEntityStorageAuthenticationAdminServiceConstructorOptions.md)
+- [IEntityStorageAuthenticationAuditServiceConfig](interfaces/IEntityStorageAuthenticationAuditServiceConfig.md)
+- [IEntityStorageAuthenticationAuditServiceConstructorOptions](interfaces/IEntityStorageAuthenticationAuditServiceConstructorOptions.md)
+- [IEntityStorageAuthenticationRateServiceConfig](interfaces/IEntityStorageAuthenticationRateServiceConfig.md)
+- [IEntityStorageAuthenticationRateServiceConstructorOptions](interfaces/IEntityStorageAuthenticationRateServiceConstructorOptions.md)
 - [IEntityStorageAuthenticationServiceConfig](interfaces/IEntityStorageAuthenticationServiceConfig.md)
 - [IEntityStorageAuthenticationServiceConstructorOptions](interfaces/IEntityStorageAuthenticationServiceConstructorOptions.md)
 
@@ -21,6 +29,7 @@
 
 - [restEntryPoints](variables/restEntryPoints.md)
 - [tagsAuthenticationAdmin](variables/tagsAuthenticationAdmin.md)
+- [tagsAuthenticationAudit](variables/tagsAuthenticationAudit.md)
 - [tagsAuthentication](variables/tagsAuthentication.md)
 
 ## Functions
@@ -32,6 +41,9 @@
 - [authenticationAdminGetUser](functions/authenticationAdminGetUser.md)
 - [authenticationAdminGetUserByIdentity](functions/authenticationAdminGetUserByIdentity.md)
 - [authenticationAdminRemoveUser](functions/authenticationAdminRemoveUser.md)
+- [generateRestRoutesAuthenticationAudit](functions/generateRestRoutesAuthenticationAudit.md)
+- [authenticationAuditCreate](functions/authenticationAuditCreate.md)
+- [authenticationAuditQuery](functions/authenticationAuditQuery.md)
 - [generateRestRoutesAuthentication](functions/generateRestRoutesAuthentication.md)
 - [authenticationLogin](functions/authenticationLogin.md)
 - [authenticationLogout](functions/authenticationLogout.md)

package/docs/reference/interfaces/IAuthHeaderProcessorConstructorOptions.md

@@ -4,6 +4,20 @@ Options for the AuthHeaderProcessor constructor.
 
 ## Properties
 
+### authenticationAdminServiceType? {#authenticationadminservicetype}
+
+> `optional` **authenticationAdminServiceType?**: `string`
+
+The admin service.
+
+#### Default
+
+```ts
+authentication-admin
+```
+
+***
+
 ### vaultConnectorType? {#vaultconnectortype}
 
 > `optional` **vaultConnectorType?**: `string`

package/docs/reference/interfaces/IEntityStorageAuthenticationAdminServiceConstructorOptions.md

@@ -18,6 +18,20 @@ authentication-user
 
 ***
 
+### authenticationAuditServiceType? {#authenticationauditservicetype}
+
+> `optional` **authenticationAuditServiceType?**: `string`
+
+The audit service.
+
+#### Default
+
+```ts
+authentication-audit
+```
+
+***
+
 ### config? {#config}
 
 > `optional` **config?**: [`IEntityStorageAuthenticationAdminServiceConfig`](IEntityStorageAuthenticationAdminServiceConfig.md)

package/docs/reference/interfaces/IEntityStorageAuthenticationAuditServiceConfig.md

@@ -0,0 +1,11 @@
+# Interface: IEntityStorageAuthenticationAuditServiceConfig
+
+Config for the EntityStorageAuthenticationAuditService constructor.
+
+## Properties
+
+### ipHashSalt? {#iphashsalt}
+
+> `optional` **ipHashSalt?**: `string`
+
+The server-side salt for hashing IP addresses in audit logs, if configured.

package/docs/reference/interfaces/IEntityStorageAuthenticationAuditServiceConstructorOptions.md

@@ -0,0 +1,25 @@
+# Interface: IEntityStorageAuthenticationAuditServiceConstructorOptions
+
+Options for the EntityStorageAuthenticationAuditService constructor.
+
+## Properties
+
+### authenticationAuditEntryStorageType? {#authenticationauditentrystoragetype}
+
+> `optional` **authenticationAuditEntryStorageType?**: `string`
+
+The entity storage for the audit entries.
+
+#### Default
+
+```ts
+authentication-audit-entry
+```
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`IEntityStorageAuthenticationAuditServiceConfig`](IEntityStorageAuthenticationAuditServiceConfig.md)
+
+The configuration for the authentication audit service.

package/docs/reference/interfaces/IEntityStorageAuthenticationRateServiceConfig.md

@@ -0,0 +1,17 @@
+# Interface: IEntityStorageAuthenticationRateServiceConfig
+
+Configuration for the entity storage authentication rate service.
+
+## Properties
+
+### cleanupIntervalMinutes? {#cleanupintervalminutes}
+
+> `optional` **cleanupIntervalMinutes?**: `number`
+
+Interval between cleanup runs in minutes.
+
+#### Default
+
+```ts
+5
+```

package/docs/reference/interfaces/IEntityStorageAuthenticationRateServiceConstructorOptions.md

@@ -0,0 +1,39 @@
+# Interface: IEntityStorageAuthenticationRateServiceConstructorOptions
+
+Options for the EntityStorageAuthenticationRateService constructor.
+
+## Properties
+
+### authenticationRateEntryStorageType? {#authenticationrateentrystoragetype}
+
+> `optional` **authenticationRateEntryStorageType?**: `string`
+
+The entity storage for authentication rate entries.
+
+#### Default
+
+```ts
+authentication-rate-entry
+```
+
+***
+
+### taskSchedulerComponentType? {#taskschedulercomponenttype}
+
+> `optional` **taskSchedulerComponentType?**: `string`
+
+The task scheduler component type.
+
+#### Default
+
+```ts
+task-scheduler
+```
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`IEntityStorageAuthenticationRateServiceConfig`](IEntityStorageAuthenticationRateServiceConfig.md)
+
+The configuration for the authentication rate service.

package/docs/reference/interfaces/IEntityStorageAuthenticationServiceConfig.md

@@ -27,5 +27,47 @@ The default time to live for the JWT.
 #### Default
 
 ```ts
-1440
+60
+```
+
+***
+
+### loginRateLimit? {#loginratelimit}
+
+> `optional` **loginRateLimit?**: `IAuthenticationRateActionConfig`
+
+Optional override for login failure rate limit.
+
+#### Default
+
+```ts
+{ maxAttempts: 5, windowMinutes: 15 }
+```
+
+***
+
+### passwordChangeRateLimit? {#passwordchangeratelimit}
+
+> `optional` **passwordChangeRateLimit?**: `IAuthenticationRateActionConfig`
+
+Optional override for password change rate limit.
+
+#### Default
+
+```ts
+{ maxAttempts: 5, windowMinutes: 15 }
+```
+
+***
+
+### tokenRefreshRateLimit? {#tokenrefreshratelimit}
+
+> `optional` **tokenRefreshRateLimit?**: `IAuthenticationRateActionConfig`
+
+Optional override for token refresh rate limit.
+
+#### Default
+
+```ts
+{ maxAttempts: 30, windowMinutes: 60 }
 ```

package/docs/reference/interfaces/IEntityStorageAuthenticationServiceConstructorOptions.md

@@ -46,6 +46,34 @@ authentication-admin
 
 ***
 
+### authenticationAuditServiceType? {#authenticationauditservicetype}
+
+> `optional` **authenticationAuditServiceType?**: `string`
+
+The audit service.
+
+#### Default
+
+```ts
+authentication-audit
+```
+
+***
+
+### authenticationRateServiceType? {#authenticationrateservicetype}
+
+> `optional` **authenticationRateServiceType?**: `string`
+
+The rate service.
+
+#### Default
+
+```ts
+authentication-rate
+```
+
+***
+
 ### config? {#config}
 
 > `optional` **config?**: [`IEntityStorageAuthenticationServiceConfig`](IEntityStorageAuthenticationServiceConfig.md)

package/docs/reference/variables/tagsAuthenticationAudit.md

@@ -0,0 +1,5 @@
+# Variable: tagsAuthenticationAudit
+
+> `const` **tagsAuthenticationAudit**: `ITag`[]
+
+The tag to associate with the routes.

package/locales/en.json

@@ -15,15 +15,24 @@
 			"userNotFound": "The user with the specified e-mail could not be found \"{notFoundId}\"",
 			"currentPasswordMismatch": "The current password is incorrect"
 		},
+		"entityStorageAuthenticationRateService": {
+			"actionConfigMissing": "No rate-limit configuration exists for action \"{action}\".",
+			"rateLimitExceeded": "The rate limit for action \"{action}\" has been exceeded. Retry after {retryAfterSeconds} seconds."
+		},
 		"tokenHelper": {
 			"missing": "The JSON Web token could not be found in the authorization header",
 			"payloadMissingSubject": "The JSON Web token payload does not contain a subject",
 			"payloadMissingOrganization": "The JSON Web token payload does not contain an organization",
 			"expired": "The JSON Web token has expired",
-			"insufficientScopes": "The JSON Web token does not have the required scopes to access this resource"
+			"insufficientScopes": "The JSON Web token does not have the required scopes to access this resource",
+			"userNotVerified": "The user associated with the JSON Web token could not be verified",
+			"organizationNotVerified": "The organization associated with the JSON Web token could not be verified"
 		},
 		"authHeaderProcessor": {
 			"tenantIdMismatch": "The tenant ID in the token does not match the tenant ID in the context"
+		},
+		"validation": {
+			"saltEntropyTooLow": "Salt must have at least 8 unique characters for sufficient entropy."
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-auth-entity-storage-service",
-	"version": "0.0.3-next.22",
+	"version": "0.0.3-next.23",
 	"description": "Authentication service implementation and REST routes backed by entity storage.",
 	"repository": {
 		"type": "git",
@@ -14,9 +14,10 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-auth-entity-storage-models": "0.0.3-next.22",
-		"@twin.org/api-core": "0.0.3-next.22",
-		"@twin.org/api-models": "0.0.3-next.22",
+		"@twin.org/api-auth-entity-storage-models": "0.0.3-next.23",
+		"@twin.org/api-core": "0.0.3-next.23",
+		"@twin.org/api-models": "0.0.3-next.23",
+		"@twin.org/background-task-models": "next",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",