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

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?`, `minPasswordLength?`): `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.
+
+##### minPasswordLength?
+
+`number`
+
+Optional minimum password length for validation.
+
+#### 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,205 @@
+# 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`, `scope?`, `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.
+
+##### 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`; \}\>
+
+The new token and its expiry date.
+
+***
+
+### verify() {#verify}
+
+> `static` **verify**(`vaultConnector`, `nodeId`, `signingKeyName`, `token`, `requiredScopes?`, `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.
+
+##### 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
+
+`Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+
+The verified details.
+
+#### Throws
+
+UnauthorizedError if the token is missing, invalid or expired.
+
+***
+
+### verifyScopes() {#verifyscopes}
+
+> `static` **verifyScopes**(`scope`, `requiredScopes?`): `void`
+
+Verify that a token carries all of the required scopes.
+
+#### Parameters
+
+##### scope
+
+`string` \| `undefined`
+
+The comma separated scopes from the token.
+
+##### requiredScopes?
+
+`string`[]
+
+The scopes the caller must hold.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+UnauthorizedError if any of the required scopes is missing.
+
+***
+
+### 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/authenticationAuditCreate.md

@@ -0,0 +1,37 @@
+# Function: authenticationAuditCreate()
+
+> **authenticationAuditCreate**(`httpRequestContext`, `componentName`, `request`, `baseRouteName`): `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.
+
+### 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/authenticationAuditGet.md

@@ -0,0 +1,31 @@
+# Function: authenticationAuditGet()
+
+> **authenticationAuditGet**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IAuditGetResponse`\>
+
+Get 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
+
+`IAuditGetRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IAuditGetResponse`\>
+
+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/authenticationAuditRemove.md

@@ -0,0 +1,31 @@
+# Function: authenticationAuditRemove()
+
+> **authenticationAuditRemove**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Remove 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
+
+`IAuditRemoveRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/authenticationAuditUpdate.md

@@ -0,0 +1,31 @@
+# Function: authenticationAuditUpdate()
+
+> **authenticationAuditUpdate**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+Update 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
+
+`IAuditUpdateRequest`
+
+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.

package/docs/reference/functions/authenticationLogout.md

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