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

package/docs/examples.md

@@ -1 +1,80 @@
-# @twin.org/api-auth-entity-storage-models - Examples
+# Auth Entity Storage Models Examples
+
+Use these snippets to shape request and response data consistently across sign-in flows, admin operations, and token refresh handling.
+
+## Authentication Requests
+
+```typescript
+import type {
+  ILoginRequest,
+  IRefreshTokenRequest,
+  IUpdatePasswordRequest
+} from '@twin.org/api-auth-entity-storage-models';
+
+const loginRequest: ILoginRequest = {
+  body: {
+    email: 'alice@example.org',
+    password: 'correct-horse-battery-staple'
+  }
+};
+
+const refreshRequest: IRefreshTokenRequest = {
+  body: {
+    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refresh'
+  }
+};
+
+const updatePasswordRequest: IUpdatePasswordRequest = {
+  body: {
+    currentPassword: 'old-password',
+    newPassword: 'new-password-2026'
+  }
+};
+
+console.log(loginRequest.body.email); // alice@example.org
+```
+
+## Admin User Models
+
+```typescript
+import type {
+  IAdminUserCreateRequest,
+  IAdminUserUpdateRequest
+} from '@twin.org/api-auth-entity-storage-models';
+
+const createRequest: IAdminUserCreateRequest = {
+  body: {
+    email: 'bob@example.org',
+    password: 'initial-password',
+    userIdentity: 'did:example:bob',
+    organizationIdentity: 'did:example:org',
+    scope: ['admin', 'auditor']
+  }
+};
+
+const updateRequest: IAdminUserUpdateRequest = {
+  pathParams: {
+    email: 'bob@example.org'
+  },
+  body: {
+    userIdentity: 'did:example:bob:ops',
+    scope: ['admin']
+  }
+};
+
+console.log(createRequest.body.scope.length); // 2
+```
+
+## Authentication Responses
+
+```typescript
+import type { ILoginResponse } from '@twin.org/api-auth-entity-storage-models';
+
+const loginResponse: ILoginResponse = {
+  body: {
+    expiry: 3600
+  }
+};
+
+console.log(loginResponse.body.expiry); // 3600
+```

package/docs/reference/index.md

@@ -3,10 +3,34 @@
 ## Interfaces
 
 - [IAuthenticationAdminComponent](interfaces/IAuthenticationAdminComponent.md)
+- [IAuthenticationAuditComponent](interfaces/IAuthenticationAuditComponent.md)
+- [IAuthenticationAuditEntry](interfaces/IAuthenticationAuditEntry.md)
 - [IAuthenticationComponent](interfaces/IAuthenticationComponent.md)
+- [IAuthenticationRateActionConfig](interfaces/IAuthenticationRateActionConfig.md)
+- [IAuthenticationRateComponent](interfaces/IAuthenticationRateComponent.md)
+- [IAuthenticationUser](interfaces/IAuthenticationUser.md)
+- [IAuthenticationUserSecure](interfaces/IAuthenticationUserSecure.md)
+- [IAdminUserCreateRequest](interfaces/IAdminUserCreateRequest.md)
+- [IAdminUserGetByIdentityRequest](interfaces/IAdminUserGetByIdentityRequest.md)
+- [IAdminUserGetRequest](interfaces/IAdminUserGetRequest.md)
+- [IAdminUserGetResponse](interfaces/IAdminUserGetResponse.md)
+- [IAdminUserRemoveRequest](interfaces/IAdminUserRemoveRequest.md)
+- [IAdminUserUpdatePasswordRequest](interfaces/IAdminUserUpdatePasswordRequest.md)
+- [IAdminUserUpdateRequest](interfaces/IAdminUserUpdateRequest.md)
+- [IAuditCreateRequest](interfaces/IAuditCreateRequest.md)
+- [IAuditQueryRequest](interfaces/IAuditQueryRequest.md)
+- [IAuditQueryResponse](interfaces/IAuditQueryResponse.md)
 - [ILoginRequest](interfaces/ILoginRequest.md)
 - [ILoginResponse](interfaces/ILoginResponse.md)
 - [ILogoutRequest](interfaces/ILogoutRequest.md)
 - [IRefreshTokenRequest](interfaces/IRefreshTokenRequest.md)
 - [IRefreshTokenResponse](interfaces/IRefreshTokenResponse.md)
 - [IUpdatePasswordRequest](interfaces/IUpdatePasswordRequest.md)
+
+## Type Aliases
+
+- [AuthAuditEvent](type-aliases/AuthAuditEvent.md)
+
+## Variables
+
+- [AuthAuditEvent](variables/AuthAuditEvent.md)

package/docs/reference/interfaces/IAdminUserCreateRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAdminUserCreateRequest
+
+Create a new user as an admin.
+
+## Properties
+
+### body {#body}
+
+> **body**: [`IAuthenticationUser`](IAuthenticationUser.md) & `object`
+
+The body of the request.
+
+#### Type Declaration
+
+##### password
+
+> **password**: `string`

package/docs/reference/interfaces/IAdminUserGetByIdentityRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAdminUserGetByIdentityRequest
+
+Get a user as an admin.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### identity
+
+> **identity**: `string`
+
+The user identity.

package/docs/reference/interfaces/IAdminUserGetRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAdminUserGetRequest
+
+Get a user as an admin.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### email
+
+> **email**: `string`
+
+The user email.

package/docs/reference/interfaces/IAdminUserGetResponse.md

@@ -0,0 +1,11 @@
+# Interface: IAdminUserGetResponse
+
+Get a user as an admin.
+
+## Properties
+
+### body {#body}
+
+> **body**: [`IAuthenticationUser`](IAuthenticationUser.md)
+
+The body of the request.

package/docs/reference/interfaces/IAdminUserRemoveRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAdminUserRemoveRequest
+
+Remove a user as an admin.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### email
+
+> **email**: `string`
+
+The user email.

package/docs/reference/interfaces/IAdminUserUpdatePasswordRequest.md

@@ -0,0 +1,37 @@
+# Interface: IAdminUserUpdatePasswordRequest
+
+Update a users password as an admin.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### email
+
+> **email**: `string`
+
+The user email.
+
+***
+
+### body {#body}
+
+> **body**: `object`
+
+The body of the request.
+
+#### newPassword
+
+> **newPassword**: `string`
+
+The new password for the user.
+
+#### currentPassword?
+
+> `optional` **currentPassword?**: `string`
+
+The current password for the user.

package/docs/reference/interfaces/IAdminUserUpdateRequest.md

@@ -0,0 +1,25 @@
+# Interface: IAdminUserUpdateRequest
+
+Update a user as an admin.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### email
+
+> **email**: `string`
+
+The user email.
+
+***
+
+### body {#body}
+
+> **body**: `Partial`\<`Omit`\<[`IAuthenticationUser`](IAuthenticationUser.md), `"email"`\>\>
+
+The body of the request.

package/docs/reference/interfaces/IAuditCreateRequest.md

@@ -0,0 +1,11 @@
+# Interface: IAuditCreateRequest
+
+Create an authentication audit entry.
+
+## Properties
+
+### body {#body}
+
+> **body**: `Omit`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md), `"id"` \| `"dateCreated"`\>
+
+The body of the request.

package/docs/reference/interfaces/IAuditQueryRequest.md

@@ -0,0 +1,65 @@
+# Interface: IAuditQueryRequest
+
+Query authentication audit entries.
+
+## Properties
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters for the request.
+
+#### actorId?
+
+> `optional` **actorId?**: `string`
+
+The actor identifier to filter by.
+
+#### organizationId?
+
+> `optional` **organizationId?**: `string`
+
+The organization identifier to filter by.
+
+#### tenantId?
+
+> `optional` **tenantId?**: `string`
+
+The tenant identifier to filter by.
+
+#### nodeId?
+
+> `optional` **nodeId?**: `string`
+
+The node identifier to filter by.
+
+#### event?
+
+> `optional` **event?**: `string`
+
+The event to filter by.
+
+#### startDate?
+
+> `optional` **startDate?**: `string`
+
+The inclusive start date for filtering, in ISO 8601 format.
+
+#### endDate?
+
+> `optional` **endDate?**: `string`
+
+The inclusive end date for filtering, in ISO 8601 format.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The pagination cursor.
+
+#### limit?
+
+> `optional` **limit?**: `string`
+
+The maximum number of results to return.

package/docs/reference/interfaces/IAuditQueryResponse.md

@@ -0,0 +1,23 @@
+# Interface: IAuditQueryResponse
+
+Response from querying authentication audit entries.
+
+## Properties
+
+### body {#body}
+
+> **body**: `object`
+
+The response body.
+
+#### entries
+
+> **entries**: [`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md)[]
+
+The returned audit entries.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The cursor to retrieve the next page, if any.

package/docs/reference/interfaces/IAuthenticationAdminComponent.md

@@ -8,51 +8,99 @@ Contract definition for authentication admin component.
 
 ## Methods
 
-### create()
+### create() {#create}
 
-> **create**(`email`, `password`, `userIdentity`, `organizationIdentity`): `Promise`\<`void`\>
+> **create**(`user`): `Promise`\<`void`\>
 
 Create a login for the user.
 
 #### Parameters
 
+##### user
+
+[`IAuthenticationUser`](IAuthenticationUser.md) & `object`
+
+The user to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the user account has been created.
+
+***
+
+### update() {#update}
+
+> **update**(`user`): `Promise`\<`void`\>
+
+Update a login for the user.
+
+#### Parameters
+
+##### user
+
+`Partial`\<[`IAuthenticationUser`](IAuthenticationUser.md)\>
+
+The user to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the user account has been updated.
+
+***
+
+### get() {#get}
+
+> **get**(`email`): `Promise`\<[`IAuthenticationUser`](IAuthenticationUser.md)\>
+
+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`](IAuthenticationUser.md)\>
 
-The password for the user.
+The user details.
 
-##### userIdentity
+***
 
-`string`
+### getByIdentity() {#getbyidentity}
 
-The DID to associate with the account.
+> **getByIdentity**(`identity`): `Promise`\<[`IAuthenticationUser`](IAuthenticationUser.md)\>
 
-##### 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`\<[`IAuthenticationUser`](IAuthenticationUser.md)\>
 
-Nothing.
+The user details.
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > **remove**(`email`): `Promise`\<`void`\>
 
-Remove the current user.
+Remove a user.
 
 #### Parameters
 
@@ -66,11 +114,11 @@ The email address of the user to remove.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the user account has been removed.
 
 ***
 
-### updatePassword()
+### updatePassword() {#updatepassword}
 
 > **updatePassword**(`email`, `newPassword`, `currentPassword?`): `Promise`\<`void`\>
 
@@ -100,4 +148,4 @@ The current password, optional, if supplied will check against existing.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the password has been updated.

package/docs/reference/interfaces/IAuthenticationAuditComponent.md

@@ -0,0 +1,103 @@
+# Interface: IAuthenticationAuditComponent
+
+Contract definition for authentication audit component.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### create() {#create}
+
+> **create**(`entry`): `Promise`\<`string`\>
+
+Create a new audit entry.
+
+#### Parameters
+
+##### entry
+
+`Omit`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md), `"id"` \| `"dateCreated"`\>
+
+The audit entry to be logged.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The unique identifier of the created audit entry.
+
+***
+
+### query() {#query}
+
+> **query**(`options?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: [`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md)[]; `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`](IAuthenticationAuditEntry.md)[]; `cursor?`: `string`; \}\>
+
+The audit entries.

package/docs/reference/interfaces/IAuthenticationAuditEntry.md

@@ -0,0 +1,91 @@
+# Interface: IAuthenticationAuditEntry
+
+Contract definition for authentication audit entry.
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the audit entry.
+
+***
+
+### event {#event}
+
+> **event**: `string`
+
+The audit event that occurred.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The timestamp of the audit entry in ISO 8601 format.
+
+***
+
+### 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.