@brickert/kerio-connect-api 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+
+# kerio-connect-api
+
+An unofficial API wrapper in NodeJS for Kerio Connect mail server.
+
+## Notes
+
+Tested on Kerio Connect Linux (using Debian 12 `.deb` file install) version `10.0.8 Patch 2`. You can download it here: [http://download.kerio.com/archive/](http://download.kerio.com/archive/) 
+
+Under the hood it uses jsonrpc protocol version 2. With session cookies `SESSION_CONNECT_WEBADMIN` and an `X-Token` Header for CSRF protection, and a `json` body
+
+The official documentation can be viewed here: [https://manuals.gfi.com/en/kerio/api/connect/admin/reference/index.html](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/index.html)
+
+Although the documentation looks hard to read I did find an official [PHP library example](https://cdn.kerio.com/dwn/kerio-api-php.zip) that helped greatly.
+
+## Features
+
+Currently only implemented a very small set of methods for the Administrative API under endpoint `/admin/api/jsonrpc`
+
+When importing this library a log file is created relative to the where the process is started. E.g. `node /opt/kerio/app.js` will have a `json` log file at `/opt/kerio/log/kerio.log` Generated by the [pino](https://www.npmjs.com/package/pino) package. With also `pino-pretty` printed to `stdout`
+
+## Installation
+
+Use the package manager [npm](https://npmjs.org) to install.
+
+```bash
+npm install @brickert/kerio-connect-api
+```
+
+## Usage
+
+A typical quick one-off script can be such as:
+
+```javascript
+import { Kerio } from "@brickert/kerio-connect-api";
+
+var kerio = new Kerio({
+    hostname: "192.168.1.1",
+    port: 4040,
+    endpoint_url: '/admin/api/jsonrpc',
+    https: true
+}, {
+    name: "kerio-connect-api",
+    vendor: "Example Inc",
+    version: "1.0"
+}, {
+    logLevel: 'info'
+});
+
+try {
+    await kerio.login({
+        username: "operator",
+        password: "foobar"
+    });
+
+    let add_host_id = await kerio.IPAddressGroups.addHostToIPAddressGroup("192.168.1.2", "Example Client Name", "My Group Name", true);
+
+    console.log(add_host_id);
+    // keriodb://ipaddressgroup/1234-5678-901-2345
+
+} catch (e) {
+    console.log(e);
+}
+```

package/index.d.ts

@@ -0,0 +1,246 @@
+import pino from "pino";
+
+export class WebClient {
+    constructor(config: WebClientConfig);
+    
+    hostname: string;
+    port: number;
+    endpoint_url: string;
+    https: boolean;
+    fullURL: string;
+    
+    /**
+     * Executes a request to the WebClient.fullURL with body object
+     * @param requestBody 
+     * @param method 
+     * @param follow_redirects 
+     */
+    doRequest(
+        requestBody: GenericJsonRPCBodyPayload,
+        method?: HTTPMethod,
+        follow_redirects?: RequestRedirect
+    ): Promise<GenericResponse>;
+
+}
+
+export interface WebClientConfig {
+    /** FQDN or IP address of the Kerio Connect Instance */
+    hostname: string;
+
+    /** Port number of the Kerio Connect Instance's API */
+    port?: number;
+
+    /** URL endpoint of the Kerio Connect Instance's Admin API
+     * @example '/admin/api/jsonrpc'
+     */
+    endpoint_url?: string;
+
+    /** The WebClient instance to use https or http */
+    https?: boolean;
+}
+
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'HEAD';
+
+export interface GenericJsonRPCBodyPayload {
+    jsonrpc: string;
+    id: number;
+    method: string;
+    params?: {
+        userName?: string;
+        password?: string;
+        application?: KerioUserAgent;
+        groups?: Array<object>;
+        query?: object;
+        groupIds?: Array<string>;
+    }
+}
+
+export interface GenericResponse {
+    _headers: object;
+    _body: {
+        jsonrpc: string;
+        id: number;
+        error?: {
+            code: number;
+            message: string;
+            data: object;
+        }
+        results?: {
+            errors?: {
+                code: number;
+                message: string;
+            }
+        }
+        result?: {
+            userDetails?: object;
+            list?: Array<object> | Array<IPAddressGroupItem>;
+            totalItems?: number;
+            errors?: Array<{
+                code: number,
+                message: string
+            }>;
+            result?: Array;
+            token?: string;
+        }
+    };
+}
+
+export class Kerio extends WebClient {
+    constructor(config: WebClientConfig, userAgent: KerioUserAgent, logConfig?: KerioLogConfig);
+    
+    hostname: string;
+    port: number;
+    endpoint_url: string;
+    https: boolean;
+    fullURL: string;
+
+    userAgent: KerioUserAgent;
+    session_cookie: string;
+    x_token: string;
+    logged_in: boolean;
+    heartbeat: object;
+
+    logger: pino.Logger;
+
+    IPAddressGroups: IPAddressGroup;
+    Session: Session;
+
+    login(user: KerioUser): void;
+
+    _createHeartBeatCronJob(): CronJob<null, null>;
+
+    renewSessionHeartBeat(): Promise<boolean>;
+}
+
+export interface KerioLogConfig {
+    logLevel: string;
+}
+
+/**
+ * Mainly to be shown in Kerio Connect's logs
+ */
+export interface KerioUserAgent {
+    /** 
+     * The name for your API Connector 
+     * @example 'KerioConnector'
+    */
+    name: string;
+
+    /**
+     * The name for your API Connector Author or Company
+     * @example 'Example Inc'
+     */
+    vendor: string;
+    /**
+     * The version of your API Connector
+     * @example '1.0'
+     */
+    version: string;
+}
+
+export interface KerioUser {
+    /**
+     * The username of the built-in user that has access to the Admin GUI
+     */
+    username: string;
+    /**
+     * The password of the built-in user that has access to the Admin GUI
+     */
+    password: string;
+}
+
+export class KerioModules {
+    sessionedRequest(options: SessionedRequestOptions): GenericResponse;
+    reset(): void;
+}
+
+export interface SessionedRequestOptions {
+    http_method: HTTPMethod;
+    api_method: string;
+    auth: SessionKeys;
+    body_params: object;
+}
+
+export interface SessionKeys {
+    cookie: string;
+    token: string;
+}
+
+export class IPAddressGroup extends KerioModules {
+    /**
+     * Obtain a Mapped Array of IPAddressGroupItem indexed by their ID for the specified group name
+     * @param group_name Name of the IPAddressGroup
+     */
+    listIPAddressItemsByGroupName(group_name: string): Promise<Map<KerioIPAddressID, IPAddressGroupItem>>;
+
+    /**
+     * Add a IPAddressGroupItem of type 'host' of a single IP Address, with a specified description name, within a specified group name, and whether to have it enabled.
+     * The IPAddressGroup will also be created automatically if it doesn't exist yet
+     * @param host_ip The single IP Address string
+     * @param description Name of this IPAddressGroupItem string
+     * @param group_name Name of the IPAddressGroup string to add this host in
+     * @param enabled True to enable this host in the group
+     * @returns Provides the unique KerioID of this host entry
+     */
+    addHostToIPAddressGroup(host_ip: string, description: string, group_name: string, enabled: boolean): Promise<KerioIPAddressID>;
+
+    /**
+     * Remove this IPAddressGroupItem of type 'host' of a single IP Address from this group name
+     * @param host_ip The single IP Address string
+     * @param group_name Name of the IPAddressGroup string to remove this host in
+     * @returns Returns True when removal was successful
+     */
+    removeHostFromIPAddressGroupByIP(host_ip: string, group_name: string): Promise<boolean>;
+
+    /**
+     * Remove IPAddressGroupItem(s) of type 'host' by the description name from this group name. TAKE CARE as this will remove all items upto the specified max limit that share the same name. You may limit number of items to remove. They are sorted by their unique ID.
+     * @param description Name of the group item(s)
+     * @param group_name Name of the IPAddressGroup string to remove from
+     * @param remove_limit Max number of group items to remove upto. Specifying -1 will remove ALL by the description name
+     * @returns Returns an array of host IP addresses that were removed
+     */
+    removeHostFromIPAddressGroupByDesc(description: string, group_name: string, remove_limit: number): Promise<Array<KerioIPAddressHost>>;
+
+}
+
+export type KerioIPAddressHost = string;
+
+export interface IPAddressGroupItem {
+    id: KerioIPAddressID;
+    groupId: KerioIPAddressGroupID;
+    sharedId?: string;
+    appManagerId?: string;
+    groupName: KerioIPAddressGroupName;
+    description: string;
+    type: IPAddressGroupItemType;
+    enabled: boolean;
+    host?: string;
+    addr1?: string;
+    addr2?: string | number;
+    childGroupId?: string;
+    childGroupName?: string;
+}
+
+export type IPAddressGroupItemType = 'Host' | 'Network' | 'Range' | 'ChildGroup';
+/**
+ * @example "keriodb://ipaddressgroup/1234-5678-901-2345"
+ */
+export type KerioIPAddressGroupID = string;
+/**
+ * @example "keriodb://ipaddress/1234-5678-901-2345"
+ */
+export type KerioIPAddressID = string;
+export type KerioIPAddressGroupName = string;
+
+export class Session extends KerioModules {
+    whoAmI(): Promise<KerioInstanceUserResponse>;
+}
+
+export interface KerioInstanceUserResponse {
+    id: string;
+    username: string;
+    name: string;
+    roles: {
+        userRole: string;
+    }
+}

package/jsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM"],
+    "checkJs": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*", "index.d.ts"]
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@brickert/kerio-connect-api",
+  "version": "0.0.1",
+  "description": "An unofficial API wrapper for Kerio Connect Mail Server jsonrpc Admin API.",
+  "keywords": [
+    "kerio",
+    "connect",
+    "mail",
+    "server",
+    "email",
+    "wrapper",
+    "smtp",
+    "imap"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/beckrickert/kerio-connect-api.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
+  "author": "Beck Rickert",
+  "type": "module",
+  "main": "src/kerio.js",
+  "types": "index.d.ts",
+  "directories": {
+    "src": "src"
+  },
+  "dependencies": {
+    "cron": "^4.4.0",
+    "fastify": "^5.6.2",
+    "lodash": "^4.17.21",
+    "node-fetch": "^3.3.2",
+    "pino": "^10.2.0",
+    "pino-pretty": "^13.1.3",
+    "qs": "^6.14.1",
+    "set-cookie-parser": "^2.7.2"
+  }
+}

package/src/client.js

@@ -0,0 +1,97 @@
+import fetch from 'node-fetch';
+import https from 'node:https';
+import setCookie from 'set-cookie-parser';
+
+/**
+ * @type {import('../index.d.ts').WebClient}
+ */
+export class WebClient {
+
+    /**
+     * @param {import('../index.d.ts').WebClientConfig} config 
+     */
+    constructor(config) {
+        this.hostname = config.hostname;
+        this.port = config.port ?? 4040;
+        this.endpoint_url = config.endpoint_url ?? "/admin/api/jsonrpc";
+        this.https = config.https ?? true;
+
+        this.fullURL = this.#getWebClientURL();
+    }
+
+
+    #GLOBAL_REQUEST_TIMEOUT = 5000;
+
+    /**
+     * Obtain the full URL string from WebClientConfig
+     * @returns {string}
+     */
+    #getWebClientURL() {
+
+        let baseURL;
+
+        if (this.https) {
+            baseURL = `https://${this.hostname}:${this.port}`;
+        } else {
+            baseURL = `http://${this.hostname}:${this.port}`;
+        }
+
+        return new URL(this.endpoint_url, baseURL).toString();
+    }
+
+    /**
+     * Executes a request to the WebClient.fullURL with body of GenericJsonRPCBodyPayload
+     * @param {import('../index.d.ts').GenericJsonRPCBodyPayload} requestBody 
+     * @param {import('../index.d.ts').HTTPMethod} method 
+     * @param {import('node-fetch').RequestRedirect} follow_redirects 
+     * @returns {Promise<import('../index.d.ts').GenericResponse>}
+     */
+    async doRequest(requestBody = null, method = "GET", follow_redirects = "follow") {
+        try {
+
+            let fetchOptions = {
+                method: method,
+                headers: new Object(),
+                redirect: follow_redirects,
+                signal: AbortSignal.timeout(this.#GLOBAL_REQUEST_TIMEOUT)
+            }
+
+            if (typeof requestBody == 'object') {
+                fetchOptions.body = JSON.stringify(requestBody);
+                fetchOptions.headers['Content-Type'] = 'application/json';
+            } else {
+                throw "Expected Request Body to be an object";
+            }
+
+            if (this.https) {
+                fetchOptions.agent = new https.Agent({
+                    rejectUnauthorized: false,
+                    requestCert: true,
+                    keepAlive: true
+                });
+            }
+
+            // @ts-ignore
+            let response = await fetch(this.fullURL, fetchOptions);
+
+            if (response.status < 400) {
+
+                /**
+                 * @type {object}
+                 */
+                let response_data = await response.json();
+
+                return {
+                    _headers: response.headers.raw(),
+                    _body: response_data
+                }
+
+            } else {
+                throw "Unexpected HTTP response";
+            }
+
+        } catch (e) {
+            throw e;
+        }
+    }
+}

package/src/ipaddressgroups.js

@@ -0,0 +1,489 @@
+import { KerioModules } from './modules.js';
+import net from 'node:net';
+/**
+ * @type {import('../index.d.ts').IPAddressGroup}
+ */
+export class IPAddressGroup extends KerioModules {
+    
+    /**
+     * Gets a Map Set of IPAddressGroupItem indexed by their UID
+     * @param {string} group_name Name of the IPAddressGroup these items are a member of
+     * @returns {Promise<Map<import('../index.d.ts').KerioIPAddressID, import('../index.d.ts').IPAddressGroupItem>>}
+     */
+    async listIPAddressItemsByGroupName(group_name = null) {
+        try {
+
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.listIPAddressItemsByGroupName"
+                }
+            }
+
+
+            if (!group_name) {
+                throw {
+                    name: "KerioInvalidIPAddressGroupNameError",
+                    message: `Invalid referred Group Name while processing API method 'IPAddressGroups.get' for name '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.listIPAddressItemsByGroupName"
+                }
+            }
+
+
+            let ip_address_items_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'IpAddressGroups.get',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                        conditions: [
+                            {
+                                fieldName: 'name',
+                                comparator: "Eq",
+                                value: group_name
+                            }
+                        ]
+                    }
+                }
+            });
+
+            let response_body = ip_address_items_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+                /**
+                 * @type {import('../index.d.ts').IPAddressGroupItem[]}
+                 */
+                // @ts-ignore
+                let ipAddressItems = response_body.result.list;
+
+                if (ipAddressItems.length != 0 || response_body.result.totalItems > 0) {
+                    //clean up properties who have empty strings and values
+                    ipAddressItems.forEach(ipItem => {
+                        return Object.fromEntries(Object.entries(ipItem).filter(([param, value]) => {
+                            if (value != null && value !== "") {
+                                return true;
+                            }
+                        }));
+                    });
+                    
+                    let ipAddresslist = new Map();
+
+                    ipAddressItems.forEach(item => {
+                        ipAddresslist.set(item.id, item);
+                    });
+
+                    this.instance.logger.debug({
+                        name: "KerioListIPAddressItems",
+                        message: `listed ${ipAddresslist.size} items in IPAddressGroup '${group_name}'`,
+                        type: 'Kerio',
+                        from: "Kerio.IPAddressGroups.listIPAddressItemsByGroupName"
+                    });
+
+                    return ipAddresslist;
+                } else {
+                    return new Map();
+                }
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'IPAddressGroups.get' by name of '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.listIPAddressItemsByGroupName"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Add an IPAddressEntry whose a member under the specific IPAddressGroup name and returns the new KerioIPAddressID. This will also create the IPAddressGroup at root level (no parent) if it does not exist.
+     * @param {string} host_ip Host's IPv4/IPv6 to add
+     * @param {string} description Descriptive name for this host
+     * @param {string} group_name IPAddressGroup name this host is a member of
+     * @param {boolean} enabled Enabled or disabled for this entry, defaults true
+     * @returns {Promise<import('../index.d.ts').KerioIPAddressID>}
+     */
+    async addHostToIPAddressGroup(host_ip, description = null, group_name = null, enabled = true) {
+        try {
+
+            if (!this.instance.logged_in) {
+
+                this.reset();
+                
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                }
+            }
+
+            if (net.isIP(host_ip) == 0) {
+                throw {
+                    name: "KerioInvalidHostError",
+                    message: `Invalid Host IP while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                }
+            }
+
+            if (!description) {
+                throw {
+                    name: "KerioInvalidHostDescriptionError",
+                    message: `Invalid Description for IPAddressEntry while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                }
+            }
+
+            if (!group_name) {
+                throw {
+                    name: "KerioInvalidIPAddressGroupNameError",
+                    message: `Invalid referred Group Name while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                }
+            }
+
+            if (typeof enabled !== 'boolean') {
+                throw {
+                    name: "KerioInvalidIPAddressEntryEnableError",
+                    message: `Invalid Enabled value while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                }
+            }
+
+            let add_host_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'IpAddressGroups.create',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    groups: [
+                        {
+                            groupName: group_name,
+                            host: host_ip,
+                            type: "Host",
+                            description: description,
+                            enabled: enabled
+                        }
+                    ]
+                }
+            });
+
+            let response_body = add_host_response._body;
+
+            if (response_body.result?.errors.length == 0) {
+
+                this.instance.logger.info({
+                        name: "KerioAddHostIPAddressGroup",
+                        message: `Added host ${host_ip} with description ${description} in IPAddressGroup '${group_name}'`,
+                        type: 'Kerio',
+                        from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                });
+
+                return response_body.result.result[0].id;
+
+            } else {
+                switch (response_body.result.errors[0].code) {
+                    case 1001:
+                        throw {
+                            name: "KerioDuplicateError",
+                            message: `Duplicate Host IP while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                            type: 'Kerio',
+                            from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                        }
+                    case 1003:
+                        throw {
+                            name: "KerioInvalidHostError",
+                            message: `Invalid Host IP while processing API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                            type: 'Kerio',
+                            from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                        }
+                    default:
+                        throw {
+                            name: "KerioRequestError",
+                            message: `Error occured while fetching results from API method 'IPAddressGroups.create' for host '${host_ip}' in group '${group_name}'`,
+                            type: 'Kerio',
+                            from: "Kerio.IPAddressGroups.addHostToIPAddressGroup"
+                        }
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Remove an IPAddressEntry from the specific IPAddressGroup name. Returns true when successfully removed.
+     * @param {string} host_ip Host's IPv4/IPv6 to add
+     * @param {string} group_name IPAddressGroup name this host is a member of
+     * @returns {Promise<boolean>} Returns true when removal was successful
+     */
+    async removeHostFromIPAddressGroupByIP(host_ip, group_name = null) {
+        try {
+
+            if (!this.instance.logged_in) {
+                
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                }
+            }
+
+            if (net.isIP(host_ip) == 0) {
+                throw {
+                    name: "KerioInvalidHostError",
+                    message: `Invalid Host IP while processing API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                }
+            }
+
+            if (!group_name) {
+                throw {
+                    name: "KerioInvalidIPAddressGroupNameError",
+                    message: `Invalid referred Group Name while processing API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                }
+            }
+
+            let get_host_ID_response = await this.listIPAddressItemsByGroupName(group_name);
+
+            if (get_host_ID_response.size != 0) {
+                
+                var foundHostID = "";
+
+                for (const [hostID, entryproperties] of get_host_ID_response) {
+                    if (entryproperties.host == host_ip) {
+                        foundHostID = hostID;
+                        break;
+                    }
+                }
+
+                if (foundHostID.length > 0) {
+                    let remove_host_response = await this.sessionedRequest({
+                        http_method: 'POST',
+                        api_method: 'IpAddressGroups.remove',
+                        auth: {
+                            cookie: this.instance.session_cookie,
+                            token: this.instance.x_token
+                        },
+                        body_params: {
+                            groupIds: [foundHostID]
+                        }
+                    });
+
+                    let response_body = remove_host_response._body;
+
+                    if (Array.isArray(response_body.result.errors) && response_body.result.errors.length == 0) {
+                        
+                        this.instance.logger.info({
+                            name: "KerioRemoveHostIPAddressGroup",
+                            message: `Removed host '${host_ip}' in group '${group_name}'`,
+                            type: 'Kerio',
+                            from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                        });
+
+                        return true;
+
+                    } else {
+                        switch (response_body.result.errors[0].code) {
+                            case 1002:
+                                throw {
+                                    name: "KerioHostRemoveError",
+                                    message: `Host does not exist within group while fetching results from API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                                }
+                            case 1003:
+                                throw {
+                                    name: "KerioHostRemoveError",
+                                    message: `Host ID invalid while fetching results from API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                                }
+                            default:
+                                throw {
+                                    name: "KerioRequestError",
+                                    message: `Error occured while fetching results from API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                                }
+                        }
+                    }
+                } else {
+                    throw {
+                        name: "KerioHostNotExistError",
+                        message: `Host IP does not exist in group while processing API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                        type: 'Kerio',
+                        from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                    }
+                }
+            } else {
+                throw {
+                    name: "KerioHostNotExistGroupError",
+                    message: `Group has no hosts while processing API method 'IPAddressGroups.remove' for host '${host_ip}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByIP"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    async removeHostFromIPAddressGroupByDesc(description = null, group_name = null, remove_limit = 1) {
+        try {
+
+            if (!this.instance.logged_in) {
+                
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                }
+            }
+
+            if (remove_limit < -1 || !Number.isInteger(remove_limit)) {
+                throw {
+                    name: "KerioInvalidGroupEntryRemoveLimitError",
+                    message: `Invalid number of max host entries to remove while processing API method 'IPAddressGroups.remove' for description '${description}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                }
+            }
+
+            if (!description) {
+                throw {
+                    name: "KerioInvalidGroupEntryDescriptionError",
+                    message: `Invalid Description to search query while processing API method 'IPAddressGroups.remove' for description '${description}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                }
+            }
+
+            if (!group_name) {
+                throw {
+                    name: "KerioInvalidIPAddressGroupNameError",
+                    message: `Invalid referred Group Name while processing API method 'IPAddressGroups.remove' for description '${description}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                }
+            }
+
+            let get_host_ID_response = await this.listIPAddressItemsByGroupName(group_name);
+
+            if (get_host_ID_response.size != 0) {
+                
+                var foundHostIds = new Array();
+                var foundHostIPs = new Array();
+
+                for (const [hostID, entryproperties] of get_host_ID_response) {
+                    if (entryproperties.description == description) {
+                        foundHostIds.push(hostID);
+                        foundHostIPs.push(entryproperties.host);
+                    }
+                }
+
+                if (remove_limit > 0) {
+                    //only the beginning of the array is kept
+                    foundHostIPs = foundHostIPs.slice(0, remove_limit);
+                    foundHostIds = foundHostIds.slice(0, remove_limit);
+                }
+
+                if (foundHostIds.length > 0) {
+                    let remove_host_response = await this.sessionedRequest({
+                        http_method: 'POST',
+                        api_method: 'IpAddressGroups.remove',
+                        auth: {
+                            cookie: this.instance.session_cookie,
+                            token: this.instance.x_token
+                        },
+                        body_params: {
+                            groupIds: foundHostIds
+                        }
+                    });
+
+                    let response_body = remove_host_response._body;
+
+                    if (Array.isArray(response_body.result.errors) && response_body.result.errors.length == 0) {
+                        
+                        return foundHostIPs;
+
+                    } else {
+                        switch (response_body.result.errors[0].code) {
+                            case 1002:
+                                throw {
+                                    name: "KerioHostRemoveError",
+                                    message: `Host does not exist within group while fetching results from API method 'IPAddressGroups.remove' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                                }
+                            case 1003:
+                                throw {
+                                    name: "KerioHostRemoveError",
+                                    message: `Host ID invalid while fetching results from API method 'IPAddressGroups.remove' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                                }
+                            default:
+                                throw {
+                                    name: "KerioRequestError",
+                                    message: `Error occured while fetching results from API method 'IPAddressGroups.remove' in group '${group_name}'`,
+                                    type: 'Kerio',
+                                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                                }
+                        }
+                    }
+                } else {
+                    throw {
+                        name: "KerioDescriptionHostsNotExistError",
+                        message: `Host ID(s) from specified description does not exist in group while processing API method 'IPAddressGroups.remove' for description '${description}' in group '${group_name}'`,
+                        type: 'Kerio',
+                        from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                    }
+                }
+            } else {
+                throw {
+                    name: "KerioHostNotExistGroupError",
+                    message: `Group has no hosts with the specified description while processing API method 'IPAddressGroups.remove' for description '${description}' in group '${group_name}'`,
+                    type: 'Kerio',
+                    from: "Kerio.IPAddressGroups.removeHostFromIPAddressGroupByDesc"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+}

package/src/kerio.js

@@ -0,0 +1,260 @@
+import { IPAddressGroup } from "./ipaddressgroups.js";
+import { Session } from "./session.js";
+import { WebClient } from "./client.js";
+import { CronJob } from 'cron';
+import pino from 'pino';
+import path from 'node:path';
+
+//https://manuals.gfi.com/en/kerio/api/connect/admin/reference/index.html
+
+export class Kerio extends WebClient {
+
+    /**
+     * @param {import('../index.d.ts').WebClientConfig} config
+     * @param {import('../index.d.ts').KerioUserAgent} userAgent
+     * @param {import('../index.d.ts').KerioLogConfig} logConfig
+     */
+    constructor(config, userAgent, logConfig) {
+        super(config);
+
+        this.userAgent = userAgent;
+
+        this.IPAddressGroups = new IPAddressGroup(this);
+
+        this.Session = new Session(this);
+
+        this.logger = pino({
+            level: "debug",
+            transport: {
+                targets: [
+                    {
+                        //Pretty logging to stdout
+                        target: 'pino-pretty',
+                        level: "info",
+                        options: {
+                            destination: 1
+                        }
+                    }, 
+                    {
+                        target: 'pino/file',
+                        level: logConfig.logLevel ?? "debug",
+                        options: {
+                            destination: path.join(process.cwd(), 'log', 'kerio.log'),
+                            mkdir: true
+                        }
+                    }
+                ]
+            }
+        });
+    }
+
+    /**
+     * Defined once successfully logged in via Kerio.login(user: KerioUser).
+     * Contains the name=value cookie to be passed in subsequent requests in the Cookie header.
+     * @type {string}
+     */
+    session_cookie = null;
+
+    /**
+     * Defined once successfully logged in via Kerio.login(user: KerioUser). Used in subsequent requests in the X-Token header.
+     * @type {string}
+     */
+    x_token = null;
+
+    /**
+     * If successfully logged in via Kerio.login(user: KerioUser). This becomes true.
+     * @type {boolean}
+     */
+    logged_in = false;
+
+    /**
+     * The heartbeat cron job to retain the current logged in session on an interval. 
+     * @type {object}
+     */
+    heartbeat = new Object();
+
+    /**
+     * @type {pino.Logger}
+     */
+    logger;
+
+    /**
+     * Attempts to login with the specified Kerio user
+     * @param {import('../index.d.ts').KerioUser} user 
+     */
+    async login(user) {
+        try {
+            let login_response = await this.doRequest({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "Session.login",
+                params: {
+                    userName: user.username,
+                    password: user.password,
+                    application: this.userAgent
+                }
+            }, "POST", "manual");
+
+            let response_body = login_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                this.x_token = response_body.result.token;
+            
+                let cookies = login_response._headers["set-cookie"];
+                let raw_session_connect_webadmin_cookie = cookies.find(cookie_row => cookie_row.includes("SESSION_CONNECT_WEBADMIN"));
+                this.session_cookie = raw_session_connect_webadmin_cookie.split(";")[0];
+
+                this.logged_in = true;
+
+                this.logger.info({
+                    name: "KerioLogin",
+                    message: `Logged into Kerio successfully`,
+                    type: "Kerio",
+                    from: "Kerio.login"
+                });
+
+                this.logger.debug({
+                    name: "KerioSession",
+                    message: `Obtained valid cookies and tokens for current session`,
+                    type: "Kerio",
+                    from: "Kerio.login"
+                });
+
+                this.heartbeat = this._createHeartBeatCronJob();
+
+                this.logger.debug({
+                    name: "KerioHeartBeatTask",
+                    message: `Created session heartbeat cron task to renew session on an interval`,
+                    type: "Kerio",
+                    from: "Kerio.login"
+                });
+
+                this.heartbeat.start();
+
+                this.logger.debug({
+                    name: "KerioHeartBeat",
+                    message: `Started session heartbeat cron task`,
+                    type: "Kerio",
+                    from: "Kerio.login"
+                });
+
+                return;
+
+            } else {
+                if (response_body.error.code == 1000) {
+
+                    throw {
+                        name: "KerioLoginError",
+                        message: `Kerio username or password is incorrect`,
+                        type: 'Kerio',
+                        from: "Kerio.login"
+                    }
+                } else {
+
+                    throw {
+                        name: "KerioRequestError",
+                        message: `Error occured while attempting login to Kerio`,
+                        type: 'Kerio',
+                        from: "Kerio.login"
+                    }
+                }
+            }
+
+        } catch (e) {
+            this.logged_in = false;
+            this.session_cookie = null;
+            this.x_token = null;
+
+            if (e.name == "AbortError" || e.name == "TimeoutError") {
+
+                this.logger.error({
+                    name: "KerioLoginTimeout",
+                    message: `Login attempt to Kerio timed out`,
+                    type: 'Kerio',
+                    from: "Kerio.login"
+                });
+                
+                throw {
+                    name: "KerioLoginTimeout",
+                    message: "Login attempt Kerio timed out",
+                    type: "Kerio",
+                    from: "Kerio.login"
+                }
+            } else {
+
+                this.logger.error(e);
+
+                throw e;
+            }
+        }
+    }
+
+    _createHeartBeatCronJob() {
+        return CronJob.from({
+            cronTime: `*/15 * * * *`,
+            onTick: async () => {
+                try {
+                    await this.renewSessionHeartBeat();
+                } catch (e) {
+                    throw e;
+                }
+            },
+            start: false,
+            runOnInit: false,
+            waitForCompletion: true 
+        });
+    }
+
+    async renewSessionHeartBeat() {
+        try {
+            if (!this.logged_in) {
+
+                throw {
+                    name: "KerioClientSessionRenewError",
+                    message: `Kerio session invalid to renew. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.renewSessionHeartBeat"
+                }
+            }
+
+            if (this.session_cookie == null) {
+
+                throw {
+                    name: "KerioClientSessionRenewError",
+                    message: `Kerio session cookie invalid to renew. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.renewSessionHeartBeat"
+                }
+            }
+
+            if (this.x_token == null) {
+
+                throw {
+                    name: "KerioClientSessionRenewError",
+                    message: `Kerio session token invalid to renew. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.renewSessionHeartBeat"
+                }
+            }
+
+            let renewed = await this.Session.whoAmI();
+
+            if (renewed.id) {
+                this.logger.info({
+                    name: "KerioClientSessionRenew",
+                    message: `Kerio session renewed, timeout extended`,
+                    type: 'Kerio',
+                    from: "Kerio.renewSessionHeartBeat"
+                });
+                return true;
+            }
+
+        } catch (e) {
+            this.logger.error(e);
+            throw e;
+        }
+    }
+
+
+}

package/src/modules.js

@@ -0,0 +1,112 @@
+import https from 'node:https';
+import fetch from 'node-fetch';
+
+export class KerioModules {
+    /**
+     * @param {import('../index.d.ts').Kerio} instance 
+     */
+    constructor(instance) {
+        /**
+         * @type {import('../index.d.ts').Kerio}
+         */
+        this.instance = instance;
+    }
+
+    /**
+     * @param {import("../index.d.ts").SessionedRequestOptions} options
+     * @returns {Promise<import('../index.d.ts').GenericResponse>}
+     */
+    async sessionedRequest(options) {
+        try {
+
+            if (!this.instance.logged_in) {
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: "This Kerio instance currently has no valid login session",
+                    type: "Kerio"
+                }
+            }
+
+            if (!this.instance.session_cookie?.includes("SESSION_CONNECT_WEBADMIN") || this.instance.x_token?.length != 64) {
+                throw {
+                    name: "KerioClientSessionTokenError",
+                    message: "This Kerio instance currently has no valid tokens",
+                    type: "Kerio"
+                }
+            }
+
+            let fetchOptions = {
+                method: options.http_method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Cookie': options.auth.cookie,
+                    'X-Token': options.auth.token
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: options.api_method,
+                    params: options.body_params
+                }),
+                redirect: 'follow',
+                signal: AbortSignal.timeout(5000)
+            }
+
+            if (this.instance.https) {
+                fetchOptions.agent = new https.Agent({
+                    rejectUnauthorized: false,
+                    requestCert: true,
+                    keepAlive: true
+                });
+            }
+
+            // @ts-ignore
+            let sessionResponse = await fetch(this.instance.fullURL, fetchOptions);
+
+            if (sessionResponse.ok) {
+
+                let sessionResponseBody = await sessionResponse.json();
+
+                return {
+                    _headers: sessionResponse.headers.raw(),
+                    // @ts-ignore
+                    _body: sessionResponseBody
+                }
+
+            } else {
+                let errBody = await sessionResponse.text();
+                let _e = {
+                    name: "HTTPError",
+                    message: `HTTP Error ${sessionResponse.status} ${sessionResponse.statusText} ${fetchOptions.method} ${options.api_method}`,
+                    type: 'fetch',
+                    data: errBody
+                }
+                throw(_e);
+            }
+
+        } catch (e) {
+            this.instance.logger.debug(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Reset login flag and session token and cookie
+     * @returns {void}
+     */
+    reset() {
+        this.instance.logged_in = false;
+        this.instance.session_cookie = null;
+        this.instance.x_token = null;
+
+        this.instance.logger.debug({
+            name: "KerioInstanceSessionReset",
+            message: "Reset login flag, session cookie, and token to defaults",
+            type: "Kerio",
+            from: "Kerio._Modules.reset"
+        });
+
+        return;
+    }
+}

package/src/session.js

@@ -0,0 +1,66 @@
+import { KerioModules } from './modules.js';
+
+/**
+ * @type {import('../index.d.ts').Session}
+ */
+export class Session extends KerioModules {
+
+    /**
+     * Obtain the Kerio Instance's user details. Also used to renew the Instance's session to prevent timeout expiration.
+     * @returns {Promise<import('../index.d.ts').KerioInstanceUserResponse>}
+     */
+    async whoAmI() {
+        try {
+            if (!this.instance.logged_in) {
+                throw {
+                    name: "KerioSessionErrorError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.Session.whoAmI"
+                }
+            }
+
+            let whoami_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Session.whoAmI',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                }
+            });
+
+            let response_body = whoami_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                return {
+                    // @ts-ignore
+                    id: response_body.result.userDetails.id,
+                    // @ts-ignore
+                    username: response_body.result.userDetails.loginName,
+                    // @ts-ignore
+                    name: response_body.result.userDetails.fullName,
+                    roles: {
+                        // @ts-ignore
+                        userRole: response_body.result.userDetails.effectiveRole.userRole
+                    }
+                }
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Session.whoAmI'`,
+                    type: 'Kerio',
+                    from: "Kerio.Session.whoAmI"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+}