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

package/docs/examples.md

@@ -1 +1,178 @@
-# @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
+```
+
+## EntityStorageAuthenticationRateService
+
+```typescript
+import { EntityStorageAuthenticationRateService } from '@twin.org/api-auth-entity-storage-service';
+import { BaseError, GeneralError } from '@twin.org/core';
+import { TooManyRequestsError } from '@twin.org/api-models';
+
+const rateService = new EntityStorageAuthenticationRateService({
+  config: {
+    cleanupIntervalMinutes: 5
+  }
+});
+
+console.log(rateService.className()); // EntityStorageAuthenticationRateService
+
+await rateService.registerAction('login', {
+  maxAttempts: 3,
+  windowMinutes: 15
+});
+
+await rateService.start('default');
+
+await rateService.check('login', 'alice@example.org');
+await rateService.check('login', 'alice@example.org');
+await rateService.check('login', 'alice@example.org');
+
+try {
+  await rateService.check('login', 'alice@example.org');
+} catch (error) {
+  if (BaseError.isErrorName(error, TooManyRequestsError.CLASS_NAME)) {
+    const tooMany = error as TooManyRequestsError;
+    console.log(tooMany.properties?.retryAfterSeconds); // 900
+    console.log(tooMany.properties?.nextRequestTime); // 2026-04-13T10:15:00.000Z
+  }
+}
+
+await rateService.clear('login', 'alice@example.org');
+await rateService.unregisterAction('login');
+
+try {
+  await rateService.check('login', 'alice@example.org');
+} catch (error) {
+  if (BaseError.isErrorName(error, GeneralError.CLASS_NAME)) {
+    console.log((error as GeneralError).name); // GeneralError
+  }
+}
+
+await rateService.stop('default');
+```
+
+## EntityStorageAuthenticationAuditService
+
+```typescript
+import { EntityStorageAuthenticationAuditService } from '@twin.org/api-auth-entity-storage-service';
+
+const auditService = new EntityStorageAuthenticationAuditService({
+  config: {
+    ipHashSalt: 'StrongServerSideSaltForAuditHashing123'
+  }
+});
+
+console.log(auditService.className()); // EntityStorageAuthenticationAuditService
+
+const createdAuditId = await auditService.create({
+  event: 'login-failure',
+  actorId: 'did:example:user:alice',
+  nodeId: 'did:example:node:eu-west-1',
+  organizationId: 'did:example:org:core',
+  tenantId: 'did:example:tenant:alpha',
+  data: {
+    reason: 'invalid-password'
+  }
+});
+
+const auditPage = await auditService.query(
+  {
+    actorId: 'did:example:user:alice',
+    event: 'login-failure',
+    startDate: '2026-04-01T00:00:00.000Z',
+    endDate: '2026-04-30T23:59:59.999Z'
+  },
+  undefined,
+  50
+);
+
+console.log(createdAuditId); // 018f2f67bb9d4a0caad8386f56df85ce
+console.log(auditPage.entries.length); // 1
+console.log(auditPage.cursor); // eyJpZCI6IjAxOGYyZjY3YmI5ZDRhMGNhYWQ4Mzg2ZjU2ZGY4NWNlIn0=
+```
+
+## 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/AuthHeaderProcessor.md

@@ -12,7 +12,7 @@ Handle a JWT token in the authorization header or cookies and validate it to pop
 
 > **new AuthHeaderProcessor**(`options?`): `AuthHeaderProcessor`
 
-Create a new instance of AuthCookiePreProcessor.
+Create a new instance of AuthHeaderProcessor.
 
 #### Parameters
 
@@ -28,7 +28,7 @@ Options for the processor.
 
 ## 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 the node identity and organization ID have been cached.
 
 #### Implementation of
 
@@ -80,7 +80,7 @@ Nothing.
 
 ***
 
-### pre()
+### pre() {#pre}
 
 > **pre**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
 
@@ -102,9 +102,9 @@ The outgoing response.
 
 ##### route
 
-The route to process.
+`IBaseRoute` \| `undefined`
 
-`IBaseRoute` | `undefined`
+The route to process.
 
 ##### contextIds
 
@@ -120,13 +120,15 @@ The state handed through the processors.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the JWT has been verified and the context populated, or an error response set.
+
 #### Implementation of
 
 `IBaseRouteProcessor.pre`
 
 ***
 
-### post()
+### post() {#post}
 
 > **post**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
 
@@ -148,9 +150,9 @@ The outgoing response.
 
 ##### route
 
-The route to process.
+`IBaseRoute` \| `undefined`
 
-`IBaseRoute` | `undefined`
+The route to process.
 
 ##### contextIds
 
@@ -166,6 +168,8 @@ The state handed through the processors.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the Set-Cookie header has been applied to the response if required.
+
 #### Implementation of
 
 `IBaseRouteProcessor.post`

package/docs/reference/classes/AuthenticationAuditEntry.md

@@ -0,0 +1,101 @@
+# Class: AuthenticationAuditEntry
+
+Class defining the storage for authentication audit entries.
+
+## Constructors
+
+### Constructor
+
+> **new AuthenticationAuditEntry**(): `AuthenticationAuditEntry`
+
+#### Returns
+
+`AuthenticationAuditEntry`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the audit entry.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The timestamp of the audit entry in ISO 8601 format.
+
+***
+
+### event {#event}
+
+> **event**: `string`
+
+The audit event that occurred.
+
+***
+
+### actorId? {#actorid}
+
+> `optional` **actorId?**: `string`
+
+The actor identifier, could be e-mail, username, or other unique identifier.
+
+***
+
+### nodeId? {#nodeid}
+
+> `optional` **nodeId?**: `string`
+
+The node identifier associated with the audit entry, if applicable.
+
+***
+
+### organizationId? {#organizationid}
+
+> `optional` **organizationId?**: `string`
+
+The organization identifier associated with the audit entry, if applicable.
+
+***
+
+### tenantId? {#tenantid}
+
+> `optional` **tenantId?**: `string`
+
+The tenant identifier associated with the audit entry, if applicable.
+
+***
+
+### ipAddressHashes? {#ipaddresshashes}
+
+> `optional` **ipAddressHashes?**: `string`[]
+
+The hashed IP addresses of the client.
+
+***
+
+### userAgent? {#useragent}
+
+> `optional` **userAgent?**: `string`
+
+The user agent string of the client.
+
+***
+
+### correlationId? {#correlationid}
+
+> `optional` **correlationId?**: `string`
+
+The correlation ID for request tracing.
+
+***
+
+### data? {#data}
+
+> `optional` **data?**: `unknown`
+
+Additional data related to the audit entry, such as IP address, user agent, etc.

package/docs/reference/classes/AuthenticationRateEntry.md

@@ -0,0 +1,37 @@
+# Class: AuthenticationRateEntry
+
+Class defining the storage for authentication rate entries.
+
+## Constructors
+
+### Constructor
+
+> **new AuthenticationRateEntry**(): `AuthenticationRateEntry`
+
+#### Returns
+
+`AuthenticationRateEntry`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The id for the rate entry.
+
+***
+
+### timestamps {#timestamps}
+
+> **timestamps**: `string`[]
+
+Array of ISO date strings representing timestamps of failed attempts.
+
+***
+
+### dateModified {#datemodified}
+
+> **dateModified**: `string`
+
+Last modification time in ISO date format.

package/docs/reference/classes/AuthenticationUser.md

@@ -14,7 +14,7 @@ Class defining the storage for user login credentials.
 
 ## Properties
 
-### email
+### email {#email}
 
 > **email**: `string`
 
@@ -22,7 +22,7 @@ The user e-mail address.
 
 ***
 
-### password
+### password {#password}
 
 > **password**: `string`
 
@@ -30,7 +30,7 @@ The encrypted password for the user.
 
 ***
 
-### salt
+### salt {#salt}
 
 > **salt**: `string`
 
@@ -38,7 +38,7 @@ The salt for the password.
 
 ***
 
-### identity
+### identity {#identity}
 
 > **identity**: `string`
 
@@ -46,8 +46,24 @@ The user identity.
 
 ***
 
-### organization
+### organization {#organization}
 
 > **organization**: `string`
 
 The users organization.
+
+***
+
+### scope {#scope}
+
+> **scope**: `string`
+
+The scope assigned to the user, comma separated.
+
+***
+
+### passwordVersion? {#passwordversion}
+
+> `optional` **passwordVersion?**: `number`
+
+The password version counter, incremented on every password change to invalidate existing tokens.

package/docs/reference/classes/EntityStorageAuthenticationAdminService.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,51 +54,111 @@ The class name of the component.
 
 ***
 
-### create()
+### create() {#create}
 
-> **create**(`email`, `password`, `userIdentity`, `organizationIdentity`): `Promise`\<`void`\>
+> **create**(`user`): `Promise`\<`void`\>
 
 Create a login for the user.
 
 #### Parameters
 
+##### user
+
+`IAuthenticationUser` & `object`
+
+The user to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the user account has been created and the audit entry recorded.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.create`
+
+***
+
+### update() {#update}
+
+> **update**(`user`): `Promise`\<`void`\>
+
+Update a login for the user.
+
+#### Parameters
+
+##### user
+
+`Partial`\<`IAuthenticationUser`\>
+
+The user to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the user account has been updated and the audit entry recorded.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.update`
+
+***
+
+### get() {#get}
+
+> **get**(`email`): `Promise`\<`IAuthenticationUser`\>
+
+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`\<`IAuthenticationUser`\>
+
+The user details.
 
-The password for the user.
+#### Implementation of
 
-##### userIdentity
+`IAuthenticationAdminComponent.get`
 
-`string`
+***
 
-The DID to associate with the account.
+### getByIdentity() {#getbyidentity}
 
-##### organizationIdentity
+> **getByIdentity**(`identity`): `Promise`\<`IAuthenticationUser`\>
+
+Get a user by identity.
+
+#### Parameters
+
+##### identity
 
 `string`
 
-The organization of the user.
+The identity of the user to get.
 
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`IAuthenticationUser`\>
 
-Nothing.
+The user details.
 
 #### Implementation of
 
-`IAuthenticationAdminComponent.create`
+`IAuthenticationAdminComponent.getByIdentity`
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`email`): `Promise`\<`void`\>
 
@@ -116,7 +176,7 @@ The email address of the user to remove.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the user account has been removed and the audit entry recorded.
 
 #### Implementation of
 
@@ -124,7 +184,7 @@ Nothing.
 
 ***
 
-### updatePassword()
+### updatePassword() {#updatepassword}
 
 > **updatePassword**(`email`, `newPassword`, `currentPassword?`): `Promise`\<`void`\>
 
@@ -154,7 +214,7 @@ The current password, optional, if supplied will check against existing.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the password has been updated.
 
 #### Implementation of