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

package/docs/reference/classes/EntityStorageAuthenticationService.md

@@ -0,0 +1,239 @@
+# Class: EntityStorageAuthenticationService
+
+Implementation of the authentication component using entity storage.
+
+## Implements
+
+- `IAuthenticationComponent`
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageAuthenticationService**(`options?`): `EntityStorageAuthenticationService`
+
+Create a new instance of EntityStorageAuthentication.
+
+#### Parameters
+
+##### options?
+
+[`IEntityStorageAuthenticationServiceConstructorOptions`](../interfaces/IEntityStorageAuthenticationServiceConstructorOptions.md)
+
+The dependencies for the identity connector.
+
+#### Returns
+
+`EntityStorageAuthenticationService`
+
+## 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
+
+`IAuthenticationComponent.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 rate-limit actions have been registered and the node identity cached.
+
+#### Implementation of
+
+`IAuthenticationComponent.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 all rate-limit actions have been unregistered.
+
+#### Implementation of
+
+`IAuthenticationComponent.stop`
+
+***
+
+### login() {#login}
+
+> **login**(`email`, `password`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
+
+Perform a login for the user.
+
+#### Parameters
+
+##### email
+
+`string`
+
+The email address for the user.
+
+##### password
+
+`string`
+
+The password for the user.
+
+#### Returns
+
+`Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
+
+The authentication token for the user, if it uses a mechanism with public access.
+
+#### Implementation of
+
+`IAuthenticationComponent.login`
+
+***
+
+### logout() {#logout}
+
+> **logout**(`token?`): `Promise`\<`void`\>
+
+Logout the current user.
+
+#### Parameters
+
+##### token?
+
+`string`
+
+The token to logout, if it uses a mechanism with public access.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the logout audit entry has been recorded.
+
+#### Implementation of
+
+`IAuthenticationComponent.logout`
+
+***
+
+### refresh() {#refresh}
+
+> **refresh**(`token?`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
+
+Refresh the token.
+
+#### Parameters
+
+##### token?
+
+`string`
+
+The token to refresh, if it uses a mechanism with public access.
+
+#### Returns
+
+`Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
+
+The refreshed token, if it uses a mechanism with public access.
+
+#### Implementation of
+
+`IAuthenticationComponent.refresh`
+
+***
+
+### updatePassword() {#updatepassword}
+
+> **updatePassword**(`currentPassword`, `newPassword`): `Promise`\<`void`\>
+
+Update the user's password.
+
+#### Parameters
+
+##### currentPassword
+
+`string`
+
+The current password for the user.
+
+##### newPassword
+
+`string`
+
+The new password for the user.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the password has been updated and the rate limit cleared.
+
+#### Implementation of
+
+`IAuthenticationComponent.updatePassword`
+
+***
+
+### passwordPolicy() {#passwordpolicy}
+
+> **passwordPolicy**(): `Promise`\<`IPasswordOptions`\>
+
+Get the password policy used for password validation.
+
+#### Returns
+
+`Promise`\<`IPasswordOptions`\>
+
+The password policy options.
+
+#### Implementation of
+
+`IAuthenticationComponent.passwordPolicy`

package/docs/reference/classes/PasswordHelper.md

@@ -0,0 +1,74 @@
+# Class: PasswordHelper
+
+Helper class for password operations.
+
+## Constructors
+
+### Constructor
+
+> **new PasswordHelper**(): `PasswordHelper`
+
+#### Returns
+
+`PasswordHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### updatePassword() {#updatepassword}
+
+> `static` **updatePassword**(`userEntityStorage`, `authenticationAuditService`, `user`, `newPassword`, `currentPassword?`, `options?`): `Promise`\<`void`\>
+
+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
+
+##### userEntityStorage
+
+`IEntityStorageConnector`\<[`AuthenticationUser`](AuthenticationUser.md)\>
+
+The entity storage for users.
+
+##### authenticationAuditService
+
+`IAuthenticationAuditComponent` \| `undefined`
+
+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.
+
+##### options?
+
+`IPasswordOptions`
+
+Optional password length validation options.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the new password has been stored and the audit entry recorded.

package/docs/reference/classes/TokenHelper.md

@@ -0,0 +1,163 @@
+# Class: TokenHelper
+
+Helper class for token operations.
+
+## Constructors
+
+### Constructor
+
+> **new TokenHelper**(): `TokenHelper`
+
+#### Returns
+
+`TokenHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### createToken() {#createtoken}
+
+> `static` **createToken**(`vaultConnector`, `nodeId`, `signingKeyName`, `userIdentity`, `organizationIdentity`, `tenantId`, `ttlMinutes`, `passwordVersion?`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
+
+Create a new token.
+
+#### Parameters
+
+##### vaultConnector
+
+`IVaultConnector`
+
+The vault connector.
+
+##### nodeId
+
+`string`
+
+The node identifier, embedded as the JWT issuer claim.
+
+##### signingKeyName
+
+`string`
+
+The signing key name, embedded as the JWT key identifier.
+
+##### userIdentity
+
+`string`
+
+The subject for the token.
+
+##### organizationIdentity
+
+`string` \| `undefined`
+
+The organization for the token.
+
+##### tenantId
+
+`string` \| `undefined`
+
+The tenant id for the token.
+
+##### ttlMinutes
+
+`number`
+
+The time to live for the token in minutes.
+
+##### 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`; \}\>
+
+The new token and its expiry date.
+
+***
+
+### verify() {#verify}
+
+> `static` **verify**(`vaultConnector`, `nodeId`, `signingKeyName`, `token`, `verifyUser?`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+
+Verify the token.
+
+#### Parameters
+
+##### vaultConnector
+
+`IVaultConnector`
+
+The vault connector.
+
+##### nodeId
+
+`string`
+
+The node identifier, expected to match the JWT issuer claim.
+
+##### signingKeyName
+
+`string`
+
+The signing key name, expected to match the JWT key identifier.
+
+##### token
+
+`string` \| `undefined`
+
+The token to verify.
+
+##### 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
+
+`Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+
+The verified details.
+
+#### Throws
+
+UnauthorizedError if the token is missing, invalid or expired.
+
+***
+
+### extractTokenFromHeaders() {#extracttokenfromheaders}
+
+> `static` **extractTokenFromHeaders**(`headers?`, `cookieName?`): \{ `token`: `string`; `location`: `"authorization"` \| `"cookie"`; \} \| `undefined`
+
+Extract the auth token from the headers, either from the authorization header or the cookie header.
+
+#### Parameters
+
+##### headers?
+
+`IHttpHeaders`
+
+The headers to extract the token from.
+
+##### cookieName?
+
+`string`
+
+The name of the cookie to extract the token from.
+
+#### Returns
+
+\{ `token`: `string`; `location`: `"authorization"` \| `"cookie"`; \} \| `undefined`
+
+The token if found.

package/docs/reference/functions/authenticationAdminCreateUser.md

@@ -0,0 +1,37 @@
+# Function: authenticationAdminCreateUser()
+
+> **authenticationAdminCreateUser**(`httpRequestContext`, `componentName`, `request`, `baseRouteName`): `Promise`\<`ICreatedResponse`\>
+
+Create a new user.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserCreateRequest`
+
+The request.
+
+### baseRouteName
+
+`string`
+
+The base route name to use for the location header.
+
+## Returns
+
+`Promise`\<`ICreatedResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAdminGetUser.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminGetUser()
+
+> **authenticationAdminGetUser**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAdminUserGetResponse`\>
+
+Get an existing user.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserGetRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAdminUserGetResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAdminGetUserByIdentity.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminGetUserByIdentity()
+
+> **authenticationAdminGetUserByIdentity**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAdminUserGetResponse`\>
+
+Get an existing user by identity.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserGetByIdentityRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAdminUserGetResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAdminRemoveUser.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminRemoveUser()
+
+> **authenticationAdminRemoveUser**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Remove an existing user.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserRemoveRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAdminUpdateUser.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminUpdateUser()
+
+> **authenticationAdminUpdateUser**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Update an existing user.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserUpdateRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAdminUpdateUserPassword.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminUpdateUserPassword()
+
+> **authenticationAdminUpdateUserPassword**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Update an existing user password.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`IAdminUserUpdatePasswordRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationLogin.md

@@ -0,0 +1,31 @@
+# Function: authenticationLogin()
+
+> **authenticationLogin**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ILoginResponse` & `IRestRouteResponseOptions`\>
+
+Login to the server.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ILoginRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ILoginResponse` & `IRestRouteResponseOptions`\>
+
+The response object with additional http response properties.