@twin.org/api-auth-entity-storage-service 0.0.3-next.2 → 0.0.3-next.21

package/docs/examples.md

@@ -1 +1,88 @@
-# @twin.org/api-auth-entity-storage-service - Examples
+# Auth Entity Storage Service Examples
+
+These snippets show how to wire authentication services into your component container and apply token processing in request pipelines.
+
+## EntityStorageAuthenticationAdminService
+
+```typescript
+import { EntityStorageAuthenticationAdminService } from '@twin.org/api-auth-entity-storage-service';
+
+const adminService = new EntityStorageAuthenticationAdminService();
+
+console.log(adminService.className()); // EntityStorageAuthenticationAdminService
+
+await adminService.create({
+  email: 'owner@example.org',
+  password: 'StartPassword123',
+  userIdentity: 'did:example:owner',
+  organizationIdentity: 'did:example:org',
+  scope: ['admin']
+});
+
+await adminService.update({
+  email: 'owner@example.org',
+  scope: ['admin', 'security']
+});
+
+await adminService.updatePassword('owner@example.org', 'StartPassword124', 'StartPassword123');
+
+const fromIdentity = await adminService.getByIdentity('did:example:owner');
+console.log(fromIdentity.scope.length); // 2
+```
+
+```typescript
+import { EntityStorageAuthenticationAdminService } from '@twin.org/api-auth-entity-storage-service';
+
+const adminService = new EntityStorageAuthenticationAdminService();
+const user = await adminService.get('owner@example.org');
+await adminService.remove(user.email);
+
+console.log(user.email); // owner@example.org
+```
+
+## EntityStorageAuthenticationService
+
+```typescript
+import { EntityStorageAuthenticationService } from '@twin.org/api-auth-entity-storage-service';
+
+const authService = new EntityStorageAuthenticationService();
+
+await authService.start('default');
+console.log(authService.className()); // EntityStorageAuthenticationService
+
+const loginResult = await authService.login('alice@example.org', 'correct-horse-battery-staple');
+
+const refreshResult = await authService.refresh(loginResult.token);
+
+await authService.updatePassword('correct-horse-battery-staple', 'correct-horse-battery-staple-2');
+
+await authService.logout(refreshResult.token);
+console.log(refreshResult.expiry > 0); // true
+```
+
+## AuthHeaderProcessor
+
+```typescript
+import { AuthHeaderProcessor } from '@twin.org/api-auth-entity-storage-service';
+
+const processor = new AuthHeaderProcessor();
+
+await processor.start('default');
+console.log(processor.className()); // AuthHeaderProcessor
+
+const request = {
+  method: 'get',
+  url: '/info',
+  headers: {
+    authorization: 'Bearer token-value'
+  }
+};
+
+const response = {};
+const contextIds = {};
+const processorState: { [id: string]: unknown } = {};
+
+await processor.pre(request, response, { skipAuth: false }, contextIds, processorState);
+
+await processor.post(request, response, { skipAuth: false }, contextIds, processorState);
+```

package/docs/reference/classes/AuthenticationUser.md

@@ -51,3 +51,11 @@ The user identity.
 > **organization**: `string`
 
 The users organization.
+
+***
+
+### scope
+
+> **scope**: `string`
+
+The scope assigned to the user, comma separated.

package/docs/reference/classes/EntityStorageAuthenticationAdminService.md

@@ -56,45 +56,105 @@ The class name of the component.
 
 ### create()
 
-> **create**(`email`, `password`, `userIdentity`, `organizationIdentity`): `Promise`\<`void`\>
+> **create**(`user`): `Promise`\<`void`\>
 
 Create a login for the user.
 
 #### Parameters
 
+##### user
+
+`Omit`\<`IAuthenticationUser`, `"salt"`\>
+
+The user to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.create`
+
+***
+
+### update()
+
+> **update**(`user`): `Promise`\<`void`\>
+
+Update a login for the user.
+
+#### Parameters
+
+##### user
+
+`Partial`\<`Omit`\<`IAuthenticationUser`, `"password"` \| `"salt"`\>\>
+
+The user to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.update`
+
+***
+
+### get()
+
+> **get**(`email`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
+
+Get a user by email.
+
+#### Parameters
+
 ##### email
 
 `string`
 
-The email address for the user.
+The email address of the user to get.
 
-##### password
+#### Returns
 
-`string`
+`Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
 
-The password for the user.
+The user details.
 
-##### userIdentity
+#### Implementation of
 
-`string`
+`IAuthenticationAdminComponent.get`
+
+***
+
+### getByIdentity()
 
-The DID to associate with the account.
+> **getByIdentity**(`identity`): `Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
 
-##### organizationIdentity
+Get a user by identity.
+
+#### Parameters
+
+##### identity
 
 `string`
 
-The organization of the user.
+The identity of the user to get.
 
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`Omit`\<`IAuthenticationUser`, `"salt"` \| `"password"`\>\>
 
-Nothing.
+The user details.
 
 #### Implementation of
 
-`IAuthenticationAdminComponent.create`
+`IAuthenticationAdminComponent.getByIdentity`
 
 ***
 

package/docs/reference/classes/EntityStorageAuthenticationService.md

@@ -140,7 +140,7 @@ Nothing.
 
 ### refresh()
 
-> **refresh**(`token?`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
+> **refresh**(`token?`): `Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
 
 Refresh the token.
 
@@ -154,7 +154,7 @@ The token to refresh, if it uses a mechanism with public access.
 
 #### Returns
 
-`Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
+`Promise`\<\{ `token?`: `string`; `expiry`: `number`; \}\>
 
 The refreshed token, if it uses a mechanism with public access.
 
@@ -166,18 +166,12 @@ The refreshed token, if it uses a mechanism with public access.
 
 ### 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`

package/docs/reference/classes/TokenHelper.md

@@ -24,7 +24,7 @@ Runtime name for the class.
 
 ### createToken()
 
-> `static` **createToken**(`vaultConnector`, `signingKeyName`, `userIdentity`, `organizationIdentity`, `ttlMinutes`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
+> `static` **createToken**(`vaultConnector`, `signingKeyName`, `userIdentity`, `organizationIdentity`, `tenantId`, `ttlMinutes`, `scope?`): `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
 
 Create a new token.
 
@@ -54,12 +54,24 @@ The organization for the token.
 
 `string` | `undefined`
 
+##### tenantId
+
+The tenant id for the token.
+
+`string` | `undefined`
+
 ##### ttlMinutes
 
 `number`
 
 The time to live for the token in minutes.
 
+##### scope?
+
+`string`
+
+The scopes for the token.
+
 #### Returns
 
 `Promise`\<\{ `token`: `string`; `expiry`: `number`; \}\>
@@ -70,7 +82,7 @@ The new token and its expiry date.
 
 ### verify()
 
-> `static` **verify**(`vaultConnector`, `signingKeyName`, `token`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
+> `static` **verify**(`vaultConnector`, `signingKeyName`, `token`, `requiredScopes?`): `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>
 
 Verify the token.
 
@@ -94,6 +106,12 @@ The token to verify.
 
 `string` | `undefined`
 
+##### requiredScopes?
+
+`string`[]
+
+The required scopes.
+
 #### Returns
 
 `Promise`\<\{ `header`: `JWTHeaderParameters`; `payload`: `JWTPayload`; \}\>

package/docs/reference/functions/authenticationAdminCreateUser.md

@@ -0,0 +1,31 @@
+# Function: authenticationAdminCreateUser()
+
+> **authenticationAdminCreateUser**(`httpRequestContext`, `componentName`, `request`): `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.
+
+## 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/generateRestRoutesAuthenticationAdmin.md

@@ -0,0 +1,25 @@
+# Function: generateRestRoutesAuthenticationAdmin()
+
+> **generateRestRoutesAuthenticationAdmin**(`baseRouteName`, `componentName`): `IRestRoute`\<`any`, `any`\>[]
+
+The REST routes for authentication admin.
+
+## 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

@@ -6,7 +6,6 @@
 - [AuthHeaderProcessor](classes/AuthHeaderProcessor.md)
 - [EntityStorageAuthenticationAdminService](classes/EntityStorageAuthenticationAdminService.md)
 - [EntityStorageAuthenticationService](classes/EntityStorageAuthenticationService.md)
-- [PasswordHelper](classes/PasswordHelper.md)
 - [TokenHelper](classes/TokenHelper.md)
 
 ## Interfaces
@@ -21,10 +20,18 @@
 ## Variables
 
 - [restEntryPoints](variables/restEntryPoints.md)
+- [tagsAuthenticationAdmin](variables/tagsAuthenticationAdmin.md)
 - [tagsAuthentication](variables/tagsAuthentication.md)
 
 ## Functions
 
+- [generateRestRoutesAuthenticationAdmin](functions/generateRestRoutesAuthenticationAdmin.md)
+- [authenticationAdminCreateUser](functions/authenticationAdminCreateUser.md)
+- [authenticationAdminUpdateUser](functions/authenticationAdminUpdateUser.md)
+- [authenticationAdminUpdateUserPassword](functions/authenticationAdminUpdateUserPassword.md)
+- [authenticationAdminGetUser](functions/authenticationAdminGetUser.md)
+- [authenticationAdminGetUserByIdentity](functions/authenticationAdminGetUserByIdentity.md)
+- [authenticationAdminRemoveUser](functions/authenticationAdminRemoveUser.md)
 - [generateRestRoutesAuthentication](functions/generateRestRoutesAuthentication.md)
 - [authenticationLogin](functions/authenticationLogin.md)
 - [authenticationLogout](functions/authenticationLogout.md)

package/docs/reference/interfaces/IAuthHeaderProcessorConfig.md

@@ -10,12 +10,6 @@ Configuration for the authentication header processor
 
 The name of the key to retrieve from the vault for signing JWT.
 
-#### Default
-
-```ts
-auth-signing
-```
-
 ***
 
 ### cookieName?
@@ -23,9 +17,3 @@ auth-signing
 > `optional` **cookieName**: `string`
 
 The name of the cookie to use for the token.
-
-#### Default
-
-```ts
-access_token
-```

package/docs/reference/interfaces/IAuthHeaderProcessorConstructorOptions.md

@@ -10,12 +10,6 @@ Options for the AuthHeaderProcessor constructor.
 
 The vault for the private keys.
 
-#### Default
-
-```ts
-vault
-```
-
 ***
 
 ### config?

package/docs/reference/interfaces/IEntityStorageAuthenticationAdminServiceConfig.md

@@ -9,9 +9,3 @@ Configuration for the entity storage authentication admin service.
 > `optional` **minPasswordLength**: `number`
 
 The minimum password length.
-
-#### Default
-
-```ts
-8
-```

package/docs/reference/interfaces/IEntityStorageAuthenticationAdminServiceConstructorOptions.md

@@ -10,12 +10,6 @@ Options for the EntityStorageAuthenticationAdminService constructor.
 
 The entity storage for the users.
 
-#### Default
-
-```ts
-authentication-user
-```
-
 ***
 
 ### config?

package/docs/reference/interfaces/IEntityStorageAuthenticationServiceConfig.md

@@ -10,12 +10,6 @@ Configuration for the entity storage authentication service.
 
 The name of the key to retrieve from the vault for signing JWT.
 
-#### Default
-
-```ts
-auth-signing
-```
-
 ***
 
 ### defaultTtlMinutes?
@@ -23,9 +17,3 @@ auth-signing
 > `optional` **defaultTtlMinutes**: `number`
 
 The default time to live for the JWT.
-
-#### Default
-
-```ts
-1440
-```

package/docs/reference/interfaces/IEntityStorageAuthenticationServiceConstructorOptions.md

@@ -10,12 +10,6 @@ Options for the EntityStorageAuthenticationService constructor.
 
 The entity storage for the users.
 
-#### Default
-
-```ts
-authentication-user
-```
-
 ***
 
 ### vaultConnectorType?
@@ -24,12 +18,6 @@ authentication-user
 
 The vault for the private keys.
 
-#### Default
-
-```ts
-vault
-```
-
 ***
 
 ### authenticationAdminServiceType?
@@ -38,12 +26,6 @@ vault
 
 The admin service.
 
-#### Default
-
-```ts
-authentication-admin
-```
-
 ***
 
 ### config?

package/docs/reference/variables/tagsAuthenticationAdmin.md

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