@maccuaa/intellitrust-auth-sdk

TypeScript SDK for the Entrust Identity as a Service (IDaaS) Authentication API.

Note: This is an unofficial community-maintained SDK, not an official Entrust product.

Features

• 🎯 Fully Typed: Complete TypeScript definitions for all API operations
• 🚀 Modern ESM: Built for modern JavaScript environments
• 📦 Tree-shakeable: Import only the functions you need
• 🔒 Type-safe: Discriminated union types for response handling
• 🪶 Lightweight: Minimal runtime dependencies

Installation

npm install @maccuaa/intellitrust-auth-sdk

bun add @maccuaa/intellitrust-auth-sdk

Quick Start

import {
  userChallengeUsingPost,
  userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";

const baseUrl = "https://customer.region.trustedauth.com";

// Step 1: Request authentication challenge
const challengeResponse = await userChallengeUsingPost(
  {
    authenticator: "TOKEN",
    userChallengeParameters: {
      userId: "john.doe",
      applicationId: "app-id",
    },
  },
  { baseUrl }
);

if (challengeResponse.status === 200) {
  const authToken = challengeResponse.data.token;

  // Step 2: Complete authentication with OTP
  const authResponse = await userAuthenticateUsingPost(
    {
      authenticator: "TOKEN",
      authorization: authToken,
      userAuthenticateParameters: {
        userId: "john.doe",
        applicationId: "app-id",
        response: "123456", // OTP code
      },
    },
    { baseUrl }
  );

  if (
    authResponse.status === 200 &&
    authResponse.data.authenticationCompleted
  ) {
    console.log("Authentication successful!");
  }
}

Response Handling

The SDK uses discriminated union types for type-safe response handling:

const response = await userAuthenticatorQueryUsingPost(
  {
    userAuthenticateQueryParameters: {
      userId: "john.doe",
      applicationId: "app-id",
    },
  },
  { baseUrl }
);

// Type guard with status check
if (response.status === 200) {
  // response.data is now typed as UserAuthenticateQueryResponse
  console.log("User authenticators:", response.data.authenticators);
} else if (response.status === 404) {
  // response.data is now typed as ErrorInfo
  console.log("Error:", response.data.errorMessage);
}

Configuration

Global Defaults

Set default options for all requests:

import { defaults } from "@maccuaa/intellitrust-auth-sdk";

defaults.baseUrl = "https://customer.region.trustedauth.com";

// Now you can call functions without specifying baseUrl each time
const response = await userAuthenticatorQueryUsingPost({
  userAuthenticateQueryParameters: {
    userId: "john.doe",
    applicationId: "app-id",
  },
});

Per-Request Options

Override defaults for individual requests:

const response = await userAuthenticateUsingPost(
  {
    authenticator: "PASSWORD",
    userAuthenticateParameters: {
      userId: "john.doe",
      applicationId: "app-id",
      response: "password123",
    },
  },
  {
    baseUrl: "https://different.trustedauth.com",
    headers: { "Custom-Header": "value" },
  }
);

Authentication Flows

Token (OTP) Authentication

import {
  userChallengeUsingPost,
  userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";

// Request challenge
const challenge = await userChallengeUsingPost(
  {
    authenticator: "TOKEN",
    userChallengeParameters: {
      userId: "[email protected]",
      applicationId: "app-id",
    },
  },
  { baseUrl }
);

if (challenge.status === 200) {
  // Complete authentication with OTP
  const auth = await userAuthenticateUsingPost(
    {
      authenticator: "TOKEN",
      authorization: challenge.data.token,
      userAuthenticateParameters: {
        userId: "[email protected]",
        applicationId: "app-id",
        response: "123456",
      },
    },
    { baseUrl }
  );
}

Password Authentication

const response = await userAuthenticateUsingPost(
  {
    authenticator: "PASSWORD",
    userAuthenticateParameters: {
      userId: "[email protected]",
      applicationId: "app-id",
      response: "securePassword123",
    },
  },
  { baseUrl }
);

if (response.status === 200 && response.data.authenticationCompleted) {
  console.log("Login successful");
}

FIDO Authentication

import {
  userChallengeUsingPost,
  userAuthenticateUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";

// Request FIDO challenge
const challenge = await userChallengeUsingPost(
  {
    authenticator: "FIDO",
    userChallengeParameters: {
      userId: "[email protected]",
      applicationId: "app-id",
    },
  },
  { baseUrl }
);

if (challenge.status === 200 && challenge.data.fido) {
  // Process FIDO challenge and get credential response
  const fidoResponse = {
    authenticatorData: "...",
    clientDataJSON: "...",
    credentialId: "...",
    signature: "...",
  };

  // Complete FIDO authentication
  const auth = await userAuthenticateUsingPost(
    {
      authenticator: "FIDO",
      authorization: challenge.data.token,
      userAuthenticateParameters: {
        userId: "[email protected]",
        applicationId: "app-id",
        fido: fidoResponse,
      },
    },
    { baseUrl }
  );
}

Query Available Authenticators

import { userAuthenticatorQueryUsingPost } from "@maccuaa/intellitrust-auth-sdk";

const response = await userAuthenticatorQueryUsingPost(
  {
    userAuthenticateQueryParameters: {
      userId: "[email protected]",
      applicationId: "app-id",
    },
  },
  { baseUrl }
);

if (response.status === 200) {
  console.log("Available authenticators:", response.data.authenticators);
}

FIDO Token Management

Register FIDO Token

import {
  startFidoRegisterUsingGet,
  completeFidoRegisterUsingPost,
} from "@maccuaa/intellitrust-auth-sdk";

// Start FIDO registration
const startResponse = await startFidoRegisterUsingGet({ baseUrl });

if (startResponse.status === 200) {
  const challenge = startResponse.data;

  // Process challenge with WebAuthn API and get credential
  const credential = {
    attestationObject: "...",
    clientDataJSON: "...",
  };

  // Complete registration
  const completeResponse = await completeFidoRegisterUsingPost(
    {
      fidoRegisterResponse: credential,
    },
    { baseUrl }
  );

  if (completeResponse.status === 200) {
    console.log("FIDO token registered:", completeResponse.data);
  }
}

Manage FIDO Tokens

import {
  getSelfFidoTokenUsingGet,
  updateSelfFidoTokenUsingPut,
  deleteSelfFidoTokenUsingDelete,
} from "@maccuaa/intellitrust-auth-sdk";

// Get token details
const token = await getSelfFidoTokenUsingGet(
  { tokenid: "token-id" },
  { baseUrl }
);

// Update token
await updateSelfFidoTokenUsingPut(
  {
    tokenid: "token-id",
    fidoTokenParms: { label: "My Security Key" },
  },
  { baseUrl }
);

// Delete token
await deleteSelfFidoTokenUsingDelete({ tokenid: "token-id" }, { baseUrl });

Supported Authenticators

• PASSWORD - Password authentication
• TOKEN - OTP tokens (soft tokens, hardware tokens)
• FIDO - FIDO/WebAuthn
• PASSKEY - Passkeys
• MACHINE - Device authentication
• GRID - Grid card authentication
• KBA - Knowledge-based authentication
• OTP - One-time passwords
• EXTERNAL - External identity provider
• IDP - Identity provider
• USER_CERTIFICATE - Certificate-based authentication
• And more...

API Documentation

For detailed API documentation, refer to the official Entrust IDaaS Authentication API documentation.

Requirements

• Node.js >= 22.12.0
• TypeScript >= 5.0 (for TypeScript projects)

License

ISC

Support

This is a community-maintained SDK. For issues or feature requests, please visit the GitHub repository.

For official Entrust IDaaS support, contact Entrust directly.