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

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`

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`\>
+
+A promise that resolves when the action configuration has been stored.
+
+#### 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`\>
+
+A promise that resolves when the action configuration has been removed.
+
+#### 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`\>
+
+A promise that resolves when the periodic cleanup task has been registered.
+
+#### 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`\>
+
+A promise that resolves when the periodic cleanup task has been removed.
+
+#### 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`\>
+
+A promise that resolves when the rate entry has been removed.
+
+#### Implementation of
+
+`IAuthenticationRateComponent.clear`

package/docs/reference/classes/EntityStorageAuthenticationService.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.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -72,7 +72,7 @@ The node logging component type.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when rate-limit actions have been registered and the node identity cached.
 
 #### Implementation of
 
@@ -80,7 +80,33 @@ Nothing.
 
 ***
 
-### login()
+### 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`\>
+
+A promise that resolves when all rate-limit actions have been unregistered.
+
+#### Implementation of
+
+`IAuthenticationComponent.stop`
+
+***
+
+### login() {#login}
 
 > **login**(`email`, `password`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
 
@@ -112,7 +138,7 @@ The authentication token for the user, if it uses a mechanism with public access
 
 ***
 
-### logout()
+### logout() {#logout}
 
 > **logout**(`token?`): `Promise`\<`void`\>
 
@@ -130,7 +156,7 @@ The token to logout, if it uses a mechanism with public access.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the logout audit entry has been recorded.
 
 #### Implementation of
 
@@ -138,7 +164,7 @@ Nothing.
 
 ***
 
-### refresh()
+### refresh() {#refresh}
 
 > **refresh**(`token?`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
 
@@ -164,20 +190,14 @@ The refreshed token, if it uses a mechanism with public access.
 
 ***
 
-### updatePassword()
+### updatePassword() {#updatepassword}
 
-> **updatePassword**(`email`, `currentPassword`, `newPassword`): `Promise`\<`void`\>
+> **updatePassword**(`currentPassword`, `newPassword`): `Promise`\<`void`\>
 
 Update the user's password.
 
 #### Parameters
 
-##### email
-
-`string`
-
-The email address of the user to update.
-
 ##### currentPassword
 
 `string`
@@ -194,7 +214,7 @@ The new password for the user.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the password has been updated and the rate limit cleared.
 
 #### Implementation of
 

package/docs/reference/classes/PasswordHelper.md

@@ -14,7 +14,7 @@ Helper class for password operations.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,28 +22,53 @@ Runtime name for the class.
 
 ## Methods
 
-### hashPassword()
+### updatePassword() {#updatepassword}
 
-> `static` **hashPassword**(`passwordBytes`, `saltBytes`): `Promise`\<`string`\>
+> `static` **updatePassword**(`userEntityStorage`, `authenticationAuditService`, `user`, `newPassword`, `currentPassword?`, `minPasswordLength?`): `Promise`\<`void`\>
 
-Hash the password for the user.
+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.
 
 #### Parameters
 
-##### passwordBytes
+##### userEntityStorage
 
-`Uint8Array`
+`IEntityStorageConnector`\<[`AuthenticationUser`](AuthenticationUser.md)\>
 
-The password bytes.
+The entity storage for users.
 
-##### saltBytes
+##### authenticationAuditService
 
-`Uint8Array`
+`IAuthenticationAuditComponent` \| `undefined`
 
-The salt bytes.
+The optional audit service.
+
+##### user
+
+[`AuthenticationUser`](AuthenticationUser.md)
+
+The user whose password is being updated.
+
+##### newPassword
+
+`string`
+
+The new password to set.
+
+##### currentPassword?
+
+`string`
+
+The current password to verify against, if supplied.
+
+##### minPasswordLength?
+
+`number`
+
+Optional minimum password length for validation.
 
 #### Returns
 
-`Promise`\<`string`\>
+`Promise`\<`void`\>
 
-The hashed password.
+A promise that resolves when the new password has been stored and the audit entry recorded.

package/docs/reference/classes/TokenHelper.md

@@ -14,7 +14,7 @@ Helper class for token operations.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,9 +22,9 @@ Runtime name for the class.
 
 ## Methods
 
-### createToken()
+### createToken() {#createtoken}
 
-> `static` **createToken**(`vaultConnector`, `signingKeyName`, `userIdentity`, `organizationIdentity`, `tenantId`, `ttlMinutes`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
+> `static` **createToken**(`vaultConnector`, `nodeId`, `signingKeyName`, `userIdentity`, `organizationIdentity`, `tenantId`, `ttlMinutes`, `scope?`, `passwordVersion?`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
 
 Create a new token.
 
@@ -36,11 +36,17 @@ Create a new token.
 
 The vault connector.
 
+##### nodeId
+
+`string`
+
+The node identifier, embedded as the JWT issuer claim.
+
 ##### signingKeyName
 
 `string`
 
-The signing key name.
+The signing key name, embedded as the JWT key identifier.
 
 ##### userIdentity
 
@@ -50,15 +56,15 @@ The subject for the token.
 
 ##### organizationIdentity
 
-The organization for the token.
+`string` \| `undefined`
 
-`string` | `undefined`
+The organization for the token.
 
 ##### tenantId
 
-The tenant id for the token.
+`string` \| `undefined`
 
-`string` | `undefined`
+The tenant id for the token.
 
 ##### ttlMinutes
 
@@ -66,6 +72,18 @@ The tenant id for the token.
 
 The time to live for the token in minutes.
 
+##### scope?
+
+`string`
+
+The scopes for the token.
+
+##### passwordVersion?
+
+`number`
+
+The user's current password version counter, embedded in the token so that a password change invalidates existing tokens.
+
 #### Returns
 
 `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
@@ -74,9 +92,9 @@ The new token and its expiry date.
 
 ***
 
-### verify()
+### verify() {#verify}
 
-> `static` **verify**(`vaultConnector`, `signingKeyName`, `token`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+> `static` **verify**(`vaultConnector`, `nodeId`, `signingKeyName`, `token`, `requiredScopes?`, `verifyUser?`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
 
 Verify the token.
 
@@ -88,17 +106,35 @@ Verify the token.
 
 The vault connector.
 
+##### nodeId
+
+`string`
+
+The node identifier, expected to match the JWT issuer claim.
+
 ##### signingKeyName
 
 `string`
 
-The signing key name.
+The signing key name, expected to match the JWT key identifier.
 
 ##### token
 
+`string` \| `undefined`
+
 The token to verify.
 
-`string` | `undefined`
+##### requiredScopes?
+
+`string`[]
+
+The required scopes.
+
+##### verifyUser?
+
+(`sub`, `org`, `tid`, `passwordVersion`) => `Promise`\<`string`[]\>
+
+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
 
@@ -112,7 +148,7 @@ UnauthorizedError if the token is missing, invalid or expired.
 
 ***
 
-### extractTokenFromHeaders()
+### extractTokenFromHeaders() {#extracttokenfromheaders}
 
 > `static` **extractTokenFromHeaders**(`headers?`, `cookieName?`): \{ `token`: `string`; `location`: `"authorization"` \| `"cookie"`; \} \| `undefined`