@3sixty/api-auth-models 0.0.0-stage → 0.20.0-next.1

package/dist/types/models/api/IAuditGetResponse.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticationAuditEntry } from "../IAuthenticationAuditEntry.js";
+/**
+ * Response from getting an authentication audit entry.
+ */
+export interface IAuditGetResponse {
+    /**
+     * The response body.
+     */
+    body: IAuthenticationAuditEntry;
+}

package/dist/types/models/api/IAuditQueryRequest.d.ts

@@ -0,0 +1,47 @@
+import type { AuthAuditEvent } from "../authAuditEvent.js";
+/**
+ * Query authentication audit entries.
+ */
+export interface IAuditQueryRequest {
+    /**
+     * The query parameters for the request.
+     */
+    query?: {
+        /**
+         * The actor identifier to filter by.
+         */
+        actorId?: string;
+        /**
+         * The organisation identifier to filter by.
+         */
+        organizationId?: string;
+        /**
+         * The tenant identifier to filter by.
+         */
+        tenantId?: string;
+        /**
+         * The node identifier to filter by.
+         */
+        nodeId?: string;
+        /**
+         * The event to filter by.
+         */
+        event?: AuthAuditEvent | string;
+        /**
+         * The inclusive start date for filtering, in ISO 8601 format.
+         */
+        startDate?: string;
+        /**
+         * The inclusive end date for filtering, in ISO 8601 format.
+         */
+        endDate?: string;
+        /**
+         * The pagination cursor.
+         */
+        cursor?: string;
+        /**
+         * The maximum number of results to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/IAuditQueryResponse.d.ts

@@ -0,0 +1,19 @@
+import type { IAuthenticationAuditEntry } from "../IAuthenticationAuditEntry.js";
+/**
+ * Response from querying authentication audit entries.
+ */
+export interface IAuditQueryResponse {
+    /**
+     * The response body.
+     */
+    body: {
+        /**
+         * The returned audit entries.
+         */
+        entries: IAuthenticationAuditEntry[];
+        /**
+         * The cursor to retrieve the next page, if any.
+         */
+        cursor?: string;
+    };
+}

package/dist/types/models/api/IAuditRemoveRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remove an authentication audit entry.
+ */
+export interface IAuditRemoveRequest {
+    /**
+     * The path parameters for the request.
+     */
+    pathParams: {
+        /**
+         * The audit entry id.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IAuditUpdateRequest.d.ts

@@ -0,0 +1,19 @@
+import type { IAuthenticationAuditEntry } from "../IAuthenticationAuditEntry.js";
+/**
+ * Update an authentication audit entry.
+ */
+export interface IAuditUpdateRequest {
+    /**
+     * The path parameters for the request.
+     */
+    pathParams: {
+        /**
+         * The audit entry id.
+         */
+        id: string;
+    };
+    /**
+     * The body of the request.
+     */
+    body: Partial<Omit<IAuthenticationAuditEntry, "id" | "dateCreated">>;
+}

package/dist/types/models/authAuditEvent.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Supported authentication audit events.
+ */
+export declare const AuthAuditEvent: {
+    /**
+     * Login success.
+     */
+    readonly LoginSuccess: "login-success";
+    /**
+     * Login failure.
+     */
+    readonly LoginFailure: "login-failure";
+    /**
+     * Logout.
+     */
+    readonly Logout: "logout";
+    /**
+     * Token refreshed.
+     */
+    readonly TokenRefreshed: "token-refreshed";
+    /**
+     * Account created.
+     */
+    readonly AccountCreated: "account-created";
+    /**
+     * Account deleted.
+     */
+    readonly AccountDeleted: "account-deleted";
+    /**
+     * Account updated.
+     */
+    readonly AccountUpdated: "account-updated";
+    /**
+     * Account locked.
+     */
+    readonly AccountLocked: "account-locked";
+    /**
+     * Account unlocked.
+     */
+    readonly AccountUnlocked: "account-unlocked";
+    /**
+     * Password changed.
+     */
+    readonly PasswordChanged: "password-changed";
+};
+/**
+ * Supported authentication audit event values.
+ */
+export type AuthAuditEvent = (typeof AuthAuditEvent)[keyof typeof AuthAuditEvent];

package/docs/changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/api-auth/compare/api-auth-models-v0.20.0-next.0...api-auth-models-v0.20.0-next.1) (2026-10-23)
+
+
+### Features
+
+* authorization ([#3](https://github.com/3sixtyglobal/api-auth/issues/3)) ([5688693](https://github.com/3sixtyglobal/api-auth/commit/568869364065b9d2c82c5c17c81f07cbdc64ec8b))
+
+## Changelog

package/docs/examples.md

@@ -0,0 +1,60 @@
+# Auth Models Examples
+
+Use these snippets to shape authentication audit entries, audit queries and rate limit configuration consistently across services and clients.
+
+## Audit Entries
+
+```typescript
+import { AuthAuditEvent, type IAuthenticationAuditEntry } from '@3sixty/api-auth-models';
+
+const entry: IAuthenticationAuditEntry = {
+  id: '018f2f67bb9d4a0caad8386f56df85ce',
+  event: AuthAuditEvent.LoginFailure,
+  dateCreated: '2026-04-13T10:00:00.000Z',
+  actorId: 'did:example:user:alice',
+  tenantId: 'did:example:tenant:alpha',
+  data: {
+    reason: 'invalid-password'
+  }
+};
+
+console.log(entry.event); // login-failure
+```
+
+## Audit Requests
+
+```typescript
+import type { IAuditCreateRequest, IAuditQueryRequest } from '@3sixty/api-auth-models';
+
+const createRequest: IAuditCreateRequest = {
+  body: {
+    event: 'account-locked',
+    actorId: 'did:example:user:alice'
+  }
+};
+
+const queryRequest: IAuditQueryRequest = {
+  query: {
+    actorId: 'did:example:user:alice',
+    startDate: '2026-04-01T00:00:00.000Z',
+    endDate: '2026-04-30T23:59:59.999Z',
+    limit: '25'
+  }
+};
+
+console.log(createRequest.body.event); // account-locked
+console.log(queryRequest.query?.limit); // 25
+```
+
+## Rate Limit Configuration
+
+```typescript
+import type { IAuthenticationRateActionConfig } from '@3sixty/api-auth-models';
+
+const loginLimit: IAuthenticationRateActionConfig = {
+  maxAttempts: 5,
+  windowMinutes: 15
+};
+
+console.log(loginLimit.maxAttempts); // 5
+```

package/docs/reference/index.md

@@ -0,0 +1,23 @@
+# @3sixty/api-auth-models
+
+## Interfaces
+
+- [IAuthenticationAuditComponent](interfaces/IAuthenticationAuditComponent.md)
+- [IAuthenticationAuditEntry](interfaces/IAuthenticationAuditEntry.md)
+- [IAuthenticationRateActionConfig](interfaces/IAuthenticationRateActionConfig.md)
+- [IAuthenticationRateComponent](interfaces/IAuthenticationRateComponent.md)
+- [IAuditCreateRequest](interfaces/IAuditCreateRequest.md)
+- [IAuditGetRequest](interfaces/IAuditGetRequest.md)
+- [IAuditGetResponse](interfaces/IAuditGetResponse.md)
+- [IAuditQueryRequest](interfaces/IAuditQueryRequest.md)
+- [IAuditQueryResponse](interfaces/IAuditQueryResponse.md)
+- [IAuditRemoveRequest](interfaces/IAuditRemoveRequest.md)
+- [IAuditUpdateRequest](interfaces/IAuditUpdateRequest.md)
+
+## Type Aliases
+
+- [AuthAuditEvent](type-aliases/AuthAuditEvent.md)
+
+## Variables
+
+- [AuthAuditEvent](variables/AuthAuditEvent.md)

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/IAuditGetRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAuditGetRequest
+
+Get an authentication audit entry by id.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### id
+
+> **id**: `string`
+
+The audit entry id.

package/docs/reference/interfaces/IAuditGetResponse.md

@@ -0,0 +1,11 @@
+# Interface: IAuditGetResponse
+
+Response from getting an authentication audit entry.
+
+## Properties
+
+### body {#body}
+
+> **body**: [`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md)
+
+The response body.

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 organisation 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/IAuditRemoveRequest.md

@@ -0,0 +1,17 @@
+# Interface: IAuditRemoveRequest
+
+Remove an authentication audit entry.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### id
+
+> **id**: `string`
+
+The audit entry id.

package/docs/reference/interfaces/IAuditUpdateRequest.md

@@ -0,0 +1,25 @@
+# Interface: IAuditUpdateRequest
+
+Update an authentication audit entry.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters for the request.
+
+#### id
+
+> **id**: `string`
+
+The audit entry id.
+
+***
+
+### body {#body}
+
+> **body**: `Partial`\<`Omit`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md), `"id"` \| `"dateCreated"`\>\>
+
+The body of the request.

package/docs/reference/interfaces/IAuthenticationAuditComponent.md

@@ -0,0 +1,175 @@
+# 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.
+
+***
+
+### get() {#get}
+
+> **get**(`id`): `Promise`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md)\>
+
+Get an audit entry by id.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The unique identifier of the audit entry.
+
+#### Returns
+
+`Promise`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md)\>
+
+The audit entry.
+
+***
+
+### update() {#update}
+
+> **update**(`id`, `entry`): `Promise`\<`void`\>
+
+Update an audit entry.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The unique identifier of the audit entry to update.
+
+##### entry
+
+`Partial`\<`Omit`\<[`IAuthenticationAuditEntry`](IAuthenticationAuditEntry.md), `"id"` \| `"dateCreated"`\>\>
+
+The fields to update on the audit entry.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the audit entry has been updated.
+
+***
+
+### remove() {#remove}
+
+> **remove**(`id`): `Promise`\<`void`\>
+
+Remove an audit entry.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The unique identifier of the audit entry to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the audit entry has been removed.
+
+***
+
+### 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 organisation 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.