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

import { EntityStorageAuthenticationAdminService } from '@twin.org/api-auth-entity-storage-service';

const adminService = new EntityStorageAuthenticationAdminService();

console.log(adminService.className()); // EntityStorageAuthenticationAdminService

await adminService.create({
  email: '[email protected]',
  password: 'StartPassword123',
  userIdentity: 'did:example:owner',
  organizationIdentity: 'did:example:org',
  scope: ['admin']
});

await adminService.update({
  email: '[email protected]',
  scope: ['admin', 'security']
});

await adminService.updatePassword('[email protected]', 'StartPassword124', 'StartPassword123');

const fromIdentity = await adminService.getByIdentity('did:example:owner');
console.log(fromIdentity.scope.length); // 2

import { EntityStorageAuthenticationAdminService } from '@twin.org/api-auth-entity-storage-service';

const adminService = new EntityStorageAuthenticationAdminService();
const user = await adminService.get('[email protected]');
await adminService.remove(user.email);

console.log(user.email); // [email protected]

EntityStorageAuthenticationService

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('[email protected]', '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

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', '[email protected]');
await rateService.check('login', '[email protected]');
await rateService.check('login', '[email protected]');

try {
  await rateService.check('login', '[email protected]');
} 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', '[email protected]');
await rateService.unregisterAction('login');

try {
  await rateService.check('login', '[email protected]');
} catch (error) {
  if (BaseError.isErrorName(error, GeneralError.CLASS_NAME)) {
    console.log((error as GeneralError).name); // GeneralError
  }
}

await rateService.stop('default');

EntityStorageAuthenticationAuditService

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

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);