VeriFayda Auth Client

Node.js/TypeScript SDK for VeriFayda eSignet authentication flow implementing OAuth2/OIDC with OTP authentication.

Installation

``bash
npm install verifayda-auth-client
`

Configuration

All configuration must be provided via environment variables:

$3

- VERIFAYDA_CLIENT_ID - OAuth2 client identifier
- VERIFAYDA_REDIRECT_URI - OAuth2 redirect URI
- VERIFAYDA_PRIVATE_KEY - RSA private key (format depends on VERIFAYDA_PRIVATE_KEY_TYPE)
- VERIFAYDA_PRIVATE_KEY_TYPE - Private key type: JWKS_BASE64 or PEM_RAW
- VERIFAYDA_BASE_URL - Base URL for VeriFayda services

$3

- VERIFAYDA_SCOPE - OAuth2 scope (defaults to "openid profile email")
- VERIFAYDA_CLAIMS - OAuth claims as JSON string (defaults to id_token with email and name)
- VERIFAYDA_NONCE - OAuth nonce (auto-generated if not provided)
- VERIFAYDA_STATE - OAuth state (auto-generated if not provided)
- VERIFAYDA_CLAIMS_LOCALES - Claims locales (defaults to "en")
- VERIFAYDA_CODE_CHALLENGE - PKCE code challenge (auto-generated if not provided)
- VERIFAYDA_CODE_CHALLENGE_METHOD - PKCE code challenge method (defaults to "S256")

Private Key Types

$3

`typescript
import { VeriFaydaClient } from 'verifayda-auth-client';

// Initialize client with configuration from environment variables
const client = new VeriFaydaClient({
clientId: process.env.VERIFAYDA_CLIENT_ID!,
redirectUri: process.env.VERIFAYDA_REDIRECT_URI!,
privateKey: process.env.VERIFAYDA_PRIVATE_KEY!,
privateKeyType: process.env.VERIFAYDA_PRIVATE_KEY_TYPE as 'JWKS_BASE64' | 'PEM_RAW',
baseUrl: process.env.VERIFAYDA_BASE_URL!,
scope: process.env.VERIFAYDA_SCOPE
});

// Complete the full authentication flow with configurable OAuth parameters
const result = await client.completeAuthenticationFlow({
individualId: 'user_individual_id',
otpValue: '123456', // OTP received by user
otpChannels: ['phone', 'email'],
claims: { id_token: { email: null, name: null, phone_number: null } }, // Optional
nonce: process.env.VERIFAYDA_NONCE, // Optional, auto-generated if not provided
state: process.env.VERIFAYDA_STATE, // Optional, auto-generated if not provided
claimsLocales: process.env.VERIFAYDA_CLAIMS_LOCALES || 'en', // Optional
codeChallenge: process.env.VERIFAYDA_CODE_CHALLENGE, // Optional
codeChallengeMethod: process.env.VERIFAYDA_CODE_CHALLENGE_METHOD || 'S256', // Optional
});

console.log(Access Token: ${result.accessToken});
console.log(User Info:, result.userInfo);
`

Step-by-Step Authentication Flow

For more control, execute each step individually:

`typescript
import { VeriFaydaClient } from 'verifayda-auth-client';

const client = new VeriFaydaClient({
clientId: process.env.VERIFAYDA_CLIENT_ID!,
redirectUri: process.env.VERIFAYDA_REDIRECT_URI!,
privateKey: process.env.VERIFAYDA_PRIVATE_KEY!,
privateKeyType: process.env.VERIFAYDA_PRIVATE_KEY_TYPE as 'JWKS_BASE64' | 'PEM_RAW',
baseUrl: process.env.VERIFAYDA_BASE_URL!
});

// Step 1: Get CSRF token
await client.getCsrfToken();

// Step 2: Post OAuth details with configurable parameters
const oauthRequest = client.buildOAuthRequest({
claims: { id_token: { email: null, name: null, phone_number: null } },
nonce: process.env.VERIFAYDA_NONCE, // Optional, auto-generated if not provided
state: process.env.VERIFAYDA_STATE, // Optional, auto-generated if not provided
claimsLocales: process.env.VERIFAYDA_CLAIMS_LOCALES || 'en',
codeChallenge: process.env.VERIFAYDA_CODE_CHALLENGE, // Optional, uses instance value
codeChallengeMethod: process.env.VERIFAYDA_CODE_CHALLENGE_METHOD || 'S256'
});
await client.postOAuthDetails(oauthRequest);

// Step 3: Send OTP
await client.sendOtp('user_individual_id', ['phone']);

// Step 4: Authenticate with OTP (user provides OTP)
const challengeList = [
{ authFactorType: 'OTP', challenge: '123456', format: 'alpha-numeric' }
];
await client.authenticateUser('user_individual_id', challengeList);

// Step 5: Request authorization code
await client.requestAuthCode();

// Step 6: Exchange code for tokens
const tokenResponse = await client.exchangeCodeForTokens();

// Step 7: Get user info
const userInfo = await client.getUserInfo();
`

JWT Decoding and Language-Coded Fields

The SDK provides utilities for decoding JWT tokens and handling language-coded fields.

$3

`typescript
import { VeriFaydaClient, JWTUtils } from 'verifayda-auth-client';

// Decode ID token
const idTokenPayload = client.getIdTokenPayload();

// Or decode any JWT manually
const decoded = JWTUtils.decodeJwt(idToken, false);
`

$3

Some fields in the JWT payload may have language variants (e.g., name#en, name#am), while others do not (e.g., email, phone_number).

`typescript
import { VeriFaydaClient } from 'verifayda-auth-client';

const userInfo = await client.getUserInfo();

// Get a field with language support (defaults to 'en')
const name = VeriFaydaClient.getFieldWithLanguage(userInfo, 'name', 'en');

// Get all language variants of a field
const nameVariants = VeriFaydaClient.getAllLanguageVariants(userInfo, 'name');
// Returns: { base: 'John Doe', en: 'John Doe', am: 'ጆን ዶይ' }

// Fields without language variants (email, phone_number, etc.)
const email = VeriFaydaClient.getFieldWithLanguage(userInfo, 'email');
`

$3

- name
- nationality
- address
- gender
- birthdate

$3

- email
- phone_number
- sub
- individual_id
- picture

API Reference

$3

Main client class for VeriFayda authentication.

#### Constructor

`typescript
new VeriFaydaClient(config: VeriFaydaClientConfig)
`

#### Methods

- getCsrfToken(): Get CSRF token from server
- postOAuthDetails(oauthRequestBody): Post OAuth details to initiate authentication flow
- sendOtp(individualId, otpChannels?, captchaToken?): Send OTP to user
- authenticateUser(individualId, challengeList): Authenticate user with OTP
- requestAuthCode(acceptedClaims?, permittedScopes?): Request authorization code
- exchangeCodeForTokens(code?): Exchange authorization code for access and ID tokens
- getUserInfo(): Get user information using access token
- getIdTokenPayload(): Decode and return the ID token payload
- buildOAuthRequest(options?): Build OAuth request body with configurable parameters
- completeAuthenticationFlow(options): Complete the full authentication flow

#### Static Methods

- getFieldWithLanguage(decodedData, fieldName, languageCode?): Get a field value with language code support
- getAllLanguageVariants(decodedData, fieldName): Get all language variants of a field

Error Handling

The SDK provides custom error classes:

`typescript
import { VeriFaydaError, AuthenticationError, ConfigurationError } from 'verifayda-auth-client';

try {
await client.completeAuthenticationFlow(options);
} catch (error) {
if (error instanceof ConfigurationError) {
console.error('Configuration error:', error.message);
} else if (error instanceof AuthenticationError) {
console.error('Authentication error:', error.message);
} else if (error instanceof VeriFaydaError) {
console.error('VeriFayda error:', error.message);
}
}
``

License

MIT

Author

Fayda Team - api_support@id.et