Lagertha_js NPM Package

Overview

lagertha_js is a JavaScript client that simplifies the integration process and offers clear methods for managing connections, token verification, and authenticated API calls.

Installation

Install lagertha_js using npm or yarn:

npm install --save lagertha_js
# or
yarn add lagertha_js

Usage

Importing Lagertha Client

To use Lagertha in your project, import it as follows:

import Lagertha from 'lagertha_js';

Connection

Connect to Lagertha using the connect method:

const loginResponse = await Lagertha.connect({
    login: "<username>",
    password: "<password>",
    application_uuid: "<uuid_application>",
    code_2fa: "<optional_2fa_code>",
    env: "<api_url>",
});

This method returns an object with the necessary access tokens.

Token Verification and Renewal

Before each authenticated call, verify the token's validity and renew it if expired using the refresh method:

const refreshedTokens = await Lagertha.refresh({
    refresh_token: "refresh_token",
    application_uuid: "uuid_application",
    env: "api_url",
});

Authenticated Calls

All authenticated calls require adding a `LagerthaConfig`` object as the last argument:

type LagerthaConfig = {
    access_token: string;
    env: string
}

Encryption

For encryption, use Lagertha to create a group, a key chain, and then encrypt your message:

const config: LagerthaConfig = {
    access_token: '<your_lagertha_access_token>',
    env: '<https://Lagertha-api-entry-point>'
};

const group = await Lagertha.create_group({
    name: 'name of my group',
    members: []
}, config);

const key = await Lagertha.create_key_chain([group.uuid], config);
const encrypted = Lagertha.encrypt('<your message>', key.id, config);

Decryption

Decrypt a string by using the decrypt method and associating it with the string and config object:

const decrypted = await Lagertha.decrypt('<your encrypted message>', config);

API

Authentication

• connect: Authenticates a user and returns credentials (access and refresh tokens).
• refresh: Refreshes user credentials.
• partner_check: Verifies partner credentials.
• partner_connect: Authenticates a partner.
• sso_connect: Single Sign-On authentication.

Key Chain Management

• create_key_chain: Creates a new key chain.
• get_key_chain: Retrieves a key chain by UUID.
• delete_key_chain: Deletes a key chain.

Encryption and Decryption

• encrypt, encrypt_with_key_chain: Encrypts text.
• encrypt_file, encrypt_file_with_key_chain: Encrypts file.
• decrypt, decrypt_with_key_chain: Decrypts text.
• decrypt_file, decrypt_file_with_key_chain: Decrypts file.

Group Management

• create_group: Creates a new group.
• add_user_to_group, remove_user_from_group: Manages user membership in groups.
• get_group_users, get_group_keys: Retrieves users or keys of a group.
• add_key_to_group, remove_key_from_group: Manages key membership in groups.

User and Application Management

• get_users, get_applications: Retrieves a list of users or applications.
• create_application, update_application, delete_application: Manages applications.
• get_user_logs, get_user_sessions: Retrieves logs or sessions of a user.

Miscellaneous

• reset_password: Resets a user's password.
• get_otp_code: Gets a one-time password code.
• post_user: Creates a user
• delete_user: Deletes a user.

Each method in the Lagertha class is designed for specific functionalities, ranging from user authentication to key chain management and encryption services. The library also includes utility functions and types for comprehensive data handling.

Types

export type CredentialOutput = {
    access_token: string;
    refresh_token: string;
    open_id: string;
    pk: string;
};

export type CredentialInput = {
    login: string;
    password: string;
    application_uuid: string;
    fingerprint: string;
    code_2fa?: string;
};

export type ErrorObject = {
    message: string;
};

export type CredentialRefreshInput = {
    refresh_token: string;
    application_uuid: string;
    fingerprint: string;
};

export type OpenIdOutput = {
    success: boolean;
};

export type OpenIdInput = {
    open_id: string;
};

export type PartnerCheckOutput = {
    partner_token: string;
};

export type PartnerCheckInput = {
    login: string;
};

export type PartnerConnectInput = {
    partner_token: string;
    fingerprint: string;
    code_2fa?: string;
};

export type UserOutput = {
    id: string;
    email: string;
    firstName: string;
    lastName: string;
    login: string;
    roles: string[];
    application: string;
    created_at: string;
};

export type UserPublicInput = {
    email: string;
    password: string;
    firstName: string;
    lastName: string;
    login: string;
    application_uuid: string;
};

export type UserInput = {
    email: string;
    password: string;
    firstName: string;
    lastName: string;
    login: string;
    application_uuid: string;
    is_admin: boolean;
};

export type UserPassword = {
    password: string;
};

export type ListDto_for_LogOutput = {
    items: LogOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type LogOutput = {
    ip: string;
    key_chain_uuid: string;
    result: string;
    created_at: string;
    user_id: string;
};

export type ListDto_for_UserOutput = {
    items: UserOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type ListDto_for_KeyChainGroupOutput = {
    items: KeyChainGroupOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type KeyChainGroupOutput = {
    uuid: string;
    name: string;
    created_at: string;
};

export type ListDto_for_DeviceSessionOutput = {
    items: DeviceSessionOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type DeviceSessionOutput = {
    user_id: string;
    fingerprint: string;
    ip: string;
    user: UserOutput | null;
    user_agent: string;
    created_at: string;
};

export type ListDto_for_KeyChainAdminOutput = {
    items: KeyChainAdminOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type KeyChainAdminOutput = {
    id: string;
    integrity: boolean;
    created_at: string;
};

export type User2faCode = {
    code: string;
};

export type User2faActivateOutput = {
    result: boolean;
};

export type User2faActivateInput = {
    is_activate: boolean;
    code: string;
};

export type UserResetPasswordOutput = {
    reset_password_token: string;
};

export type UserResetPasswordInput = {
    user_id: string;
};

export type UserUpdatePasswordInput = {
    token: string;
    new_password: string;
    validation_code?: string;
};

export type ApplicationOutput = {
    id: string;
    uuid: string;
    name: string;
    users_number: number;
    keys_number: number;
    is_system: boolean;
    contact_email: string;
    created_at: string;
};

export type ApplicationInput = {
    name: string;
    contact_email: string;
    restricted_admin_ip: string[];
};

export type ListDto_for_ApplicationOutput = {
    items: ApplicationOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type ApplicationEditInput = {
    uuid: string;
    name: string;
    contact_email: string;
};

export type ApplicationIpInput = {
    restricted_ip: string;
};

export type RestrictedIpsOutput = {
    application_uuid: string;
    restricted_ips: string[];
};

export type KeyChainOutput = {
    id: string;
    cipher_key: string;
    digest: string;
    iv?: string;
};

export type GroupListInput = {
    groups: string[];
};

export type KeyGroup = {
    group: string;
};

export type GroupInput = {
    name: string;
    members: string[];
};

export type GroupMember = {
    member: string;
};

export type ListDto_for_BlockChainValidationOutput = {
    items: BlockChainValidationOutput[];
    total_items: number;
    page: number;
    items_per_page: number;
};

export type BlockChainValidationOutput = {
    id: string;
    from_index: number;
    to_index: number;
    is_valid: boolean;
    error_index?: number;
    created_at: string;
};

export type BlockChainValidationInput = {
    from_index: number;
    to_index?: number;
};