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

package/dist/types/services/entityStorageAuthenticationAdminService.d.ts

@@ -0,0 +1,69 @@
+import type { IAuthenticationAdminComponent, IAuthenticationUser } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationAdminServiceConstructorOptions } from "../models/IEntityStorageAuthenticationAdminServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication component using entity storage.
+ */
+export declare class EntityStorageAuthenticationAdminService implements IAuthenticationAdminComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The default role that grants escalated privilege.
+     */
+    static readonly DEFAULT_ESCALATED_PRIVILEGE_ROLE: string;
+    /**
+     * The default authorization model ID used to look up roles.
+     */
+    static readonly DEFAULT_AUTHORIZATION_MODEL_ID: string;
+    /**
+     * Create a new instance of EntityStorageAuthentication.
+     * @param options The dependencies for the identity connector.
+     */
+    constructor(options?: IEntityStorageAuthenticationAdminServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a login for the user.
+     * @param user The user to create.
+     * @returns A promise that resolves when the user account has been created and the audit entry recorded.
+     */
+    create(user: IAuthenticationUser & {
+        password: string;
+    }): Promise<void>;
+    /**
+     * Update a login for the user.
+     * @param user The user to update.
+     * @returns A promise that resolves when the user account has been updated and the audit entry recorded.
+     */
+    update(user: Partial<IAuthenticationUser>): Promise<void>;
+    /**
+     * Get a user by email.
+     * @param email The email address of the user to get.
+     * @returns The user details.
+     */
+    get(email: string): Promise<IAuthenticationUser>;
+    /**
+     * Get a user by identity.
+     * @param identity The identity of the user to get.
+     * @returns The user details.
+     */
+    getByIdentity(identity: string): Promise<IAuthenticationUser>;
+    /**
+     * Remove the current user.
+     * @param email The email address of the user to remove.
+     * @returns A promise that resolves when the user account has been removed and the audit entry recorded.
+     */
+    remove(email: string): Promise<void>;
+    /**
+     * Update the user's password.
+     * @param email The email address of the user to update.
+     * @param newPassword The new password for the user.
+     * @param currentPassword The current password, optional, if supplied will check against existing.
+     * @returns A promise that resolves when the password has been updated.
+     */
+    updatePassword(email: string, newPassword: string, currentPassword?: string): Promise<void>;
+}

package/dist/types/services/entityStorageAuthenticationService.d.ts

@@ -0,0 +1,70 @@
+import type { IAuthenticationComponent, IPasswordOptions } from "@3sixty/api-auth-entity-storage-models";
+import type { IEntityStorageAuthenticationServiceConstructorOptions } from "../models/IEntityStorageAuthenticationServiceConstructorOptions.js";
+/**
+ * Implementation of the authentication component using entity storage.
+ */
+export declare class EntityStorageAuthenticationService implements IAuthenticationComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthentication.
+     * @param options The dependencies for the identity connector.
+     */
+    constructor(options?: IEntityStorageAuthenticationServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when rate-limit actions have been registered and the node identity cached.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when all rate-limit actions have been unregistered.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Perform a login for the user.
+     * @param email The email address for the user.
+     * @param password The password for the user.
+     * @returns The authentication token for the user, if it uses a mechanism with public access.
+     */
+    login(email: string, password: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Logout the current user.
+     * @param token The token to logout, if it uses a mechanism with public access.
+     * @returns A promise that resolves when the logout audit entry has been recorded.
+     */
+    logout(token?: string): Promise<void>;
+    /**
+     * Refresh the token.
+     * @param token The token to refresh, if it uses a mechanism with public access.
+     * @returns The refreshed token, if it uses a mechanism with public access.
+     */
+    refresh(token?: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Update the user's password.
+     * @param currentPassword The current password for the user.
+     * @param newPassword The new password for the user.
+     * @returns A promise that resolves when the password has been updated and the rate limit cleared.
+     */
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Get the password policy used for password validation.
+     * @returns The password policy options.
+     */
+    passwordPolicy(): Promise<IPasswordOptions>;
+}

package/dist/types/utils/passwordHelper.d.ts

@@ -0,0 +1,27 @@
+import type { IPasswordOptions } from "@3sixty/api-auth-entity-storage-models";
+import type { IAuthenticationAuditComponent } from "@3sixty/api-auth-models";
+import type { IEntityStorageConnector } from "@3sixty/entity-storage-models";
+import type { AuthenticationUser } from "../entities/authenticationUser.js";
+/**
+ * Helper class for password operations.
+ */
+export declare class PasswordHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * 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.
+     * @param userEntityStorage The entity storage for users.
+     * @param authenticationAuditService The optional audit service.
+     * @param user The user whose password is being updated.
+     * @param newPassword The new password to set.
+     * @param currentPassword The current password to verify against, if supplied.
+     * @param options Optional password length validation options.
+     * @param options.minPasswordLength Optional minimum password length for validation.
+     * @param options.maxPasswordLength Optional maximum password length for validation.
+     * @returns A promise that resolves when the new password has been stored and the audit entry recorded.
+     */
+    static updatePassword(userEntityStorage: IEntityStorageConnector<AuthenticationUser>, authenticationAuditService: IAuthenticationAuditComponent | undefined, user: AuthenticationUser, newPassword: string, currentPassword?: string, options?: IPasswordOptions): Promise<void>;
+}

package/dist/types/utils/tokenHelper.d.ts

@@ -0,0 +1,51 @@
+import { type IVaultConnector } from "@3sixty/vault-models";
+import { type IHttpHeaders, type IJwtHeader, type IJwtPayload } from "@3sixty/web";
+/**
+ * Helper class for token operations.
+ */
+export declare class TokenHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new token.
+     * @param vaultConnector The vault connector.
+     * @param nodeId The node identifier, embedded as the JWT issuer claim.
+     * @param signingKeyName The signing key name, embedded as the JWT key identifier.
+     * @param userIdentity The subject for the token.
+     * @param organizationIdentity The organization for the token.
+     * @param tenantId The tenant id for the token.
+     * @param ttlMinutes The time to live for the token in minutes.
+     * @param passwordVersion The user's current password version counter, embedded in the token so that a password change invalidates existing tokens.
+     * @returns The new token and its expiry date.
+     */
+    static createToken(vaultConnector: IVaultConnector, nodeId: string, signingKeyName: string, userIdentity: string, organizationIdentity: string | undefined, tenantId: string | undefined, ttlMinutes: number, passwordVersion?: number): Promise<{
+        token: string;
+        expiry: number;
+    }>;
+    /**
+     * Verify the token.
+     * @param vaultConnector The vault connector.
+     * @param nodeId The node identifier, expected to match the JWT issuer claim.
+     * @param signingKeyName The signing key name, expected to match the JWT key identifier.
+     * @param token The token to verify.
+     * @param verifyUser 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 The verified details.
+     * @throws UnauthorizedError if the token is missing, invalid or expired.
+     */
+    static verify(vaultConnector: IVaultConnector, nodeId: string, signingKeyName: string, token: string | undefined, verifyUser?: (sub: string, org: string, tid: string | undefined, passwordVersion: number | undefined) => Promise<string[]>): Promise<{
+        header: IJwtHeader;
+        payload: IJwtPayload;
+    }>;
+    /**
+     * Extract the auth token from the headers, either from the authorization header or the cookie header.
+     * @param headers The headers to extract the token from.
+     * @param cookieName The name of the cookie to extract the token from.
+     * @returns The token if found.
+     */
+    static extractTokenFromHeaders(headers?: IHttpHeaders, cookieName?: string): {
+        token: string;
+        location: "authorization" | "cookie";
+    } | undefined;
+}

package/docs/changelog.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/api-auth/compare/api-auth-entity-storage-service-v0.20.0-next.0...api-auth-entity-storage-service-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))
+* initial commit ([b9112fb](https://github.com/3sixtyglobal/api-auth/commit/b9112fb6994758b43effdde1b9e41435ff50fe50))
+* publish packages under the [@3sixty](https://github.com/3sixty) namespace ([6c22482](https://github.com/3sixtyglobal/api-auth/commit/6c2248295620000807ff91087c3b1dfc9b018b31))
+* updated ts compile ([83c72bd](https://github.com/3sixtyglobal/api-auth/commit/83c72bd5d2e9d81208b7a2755450d96fbbb04004))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @3sixty/api-auth-entity-storage-models bumped from 0.20.0-next.0 to 0.20.0-next.1
+    * @3sixty/api-auth-models bumped from 0.20.0-next.0 to 0.20.0-next.1

package/docs/examples.md

@@ -0,0 +1,94 @@
+# 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 '@3sixty/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'
+});
+
+await adminService.update({
+  email: 'owner@example.org',
+  organizationIdentity: 'did:example:org:security'
+});
+
+await adminService.updatePassword('owner@example.org', 'StartPassword124', 'StartPassword123');
+
+const fromIdentity = await adminService.getByIdentity('did:example:owner');
+console.log(fromIdentity.organizationIdentity); // did:example:org:security
+```
+
+```typescript
+import { EntityStorageAuthenticationAdminService } from '@3sixty/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 '@3sixty/api-auth-entity-storage-service';
+
+const authService = new EntityStorageAuthenticationService();
+
+await authService.start('default');
+console.log(authService.className()); // EntityStorageAuthenticationService
+
+const policy = await authService.passwordPolicy();
+console.log(policy.minPasswordLength); // 8
+
+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
+
+await authService.stop('default');
+```
+
+## AuthHeaderProcessor
+
+```typescript
+import { AuthHeaderProcessor } from '@3sixty/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);
+
+await processor.stop();
+```