sentinel-js-client 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Demeng Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+[![npm](https://img.shields.io/npm/v/sentinel-js-client)](https://www.npmjs.com/package/sentinel-js-client)
+
+# Sentinel Node.js Client
+
+Official Node.js client library for the [Sentinel](https://demeng.dev/sentinel) v2 API.
+
+## Documentation
+
+Full documentation is available on GitBook:
+[https://demeng.gitbook.io/sentinel/clients/node](https://demeng.gitbook.io/sentinel/clients/node)
+
+## License
+
+[MIT](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { ConnectionOperations } from './operations/connections.js';
+import { IpOperations } from './operations/ips.js';
+import { ServerOperations } from './operations/servers.js';
+import { SubUserOperations } from './operations/sub-users.js';
+import type { CreateLicenseRequest, License, ListLicensesRequest, Page, SentinelClientOptions, UpdateLicenseRequest, ValidateRequest, ValidationDetails, ValidationResult } from './types.js';
+export declare class SentinelClient {
+    readonly connections: ConnectionOperations;
+    readonly subUsers: SubUserOperations;
+    readonly servers: ServerOperations;
+    readonly ips: IpOperations;
+    private readonly http;
+    private readonly signatureVerifier?;
+    private readonly replayProtector?;
+    constructor(options: SentinelClientOptions);
+    validate(request: ValidateRequest): Promise<ValidationResult>;
+    create(request: CreateLicenseRequest): Promise<License>;
+    get(key: string): Promise<License>;
+    list(request?: ListLicensesRequest): Promise<Page<License>>;
+    update(key: string, request: UpdateLicenseRequest): Promise<License>;
+    delete(key: string): Promise<void>;
+    regenerateKey(key: string, newKey?: string): Promise<License>;
+    private buildUpdateBody;
+}
+export declare function requireValid(result: ValidationResult): ValidationDetails;

package/dist/client.js

@@ -0,0 +1,147 @@
+import { LicenseValidationError, SentinelError } from './errors.js';
+import { getMachineFingerprint } from './fingerprint.js';
+import { SentinelHttpClient } from './http.js';
+import { ConnectionOperations } from './operations/connections.js';
+import { IpOperations } from './operations/ips.js';
+import { ServerOperations } from './operations/servers.js';
+import { SubUserOperations } from './operations/sub-users.js';
+import { parseApiResponse, parseLicense, parsePage, parseValidationResponse } from './parsing.js';
+import { ReplayProtector } from './replay.js';
+import { SignatureVerifier } from './signature.js';
+export class SentinelClient {
+    connections;
+    subUsers;
+    servers;
+    ips;
+    http;
+    signatureVerifier;
+    replayProtector;
+    constructor(options) {
+        if (!options.baseUrl) {
+            throw new SentinelError('baseUrl is required');
+        }
+        if (!options.apiKey) {
+            throw new SentinelError('apiKey is required');
+        }
+        if (options.replayProtection && !options.publicKey) {
+            throw new SentinelError('replayProtection requires publicKey to be set');
+        }
+        this.http = new SentinelHttpClient(options.baseUrl, options.apiKey, options.timeout ?? 10_000);
+        if (options.publicKey) {
+            this.signatureVerifier = new SignatureVerifier(options.publicKey);
+            this.replayProtector = new ReplayProtector(options.replayProtection?.maxTimestampAge ?? 30_000, options.replayProtection?.cacheSize ?? 1_000);
+        }
+        this.connections = new ConnectionOperations(this.http);
+        this.subUsers = new SubUserOperations(this.http);
+        this.servers = new ServerOperations(this.http);
+        this.ips = new IpOperations(this.http);
+    }
+    async validate(request) {
+        const body = { product: request.product };
+        if (request.key !== undefined)
+            body.key = request.key;
+        if (request.connectionPlatform !== undefined)
+            body.connectionPlatform = request.connectionPlatform;
+        if (request.connectionValue !== undefined)
+            body.connectionValue = request.connectionValue;
+        body.server = request.server ?? getMachineFingerprint();
+        if (request.ip !== undefined)
+            body.ip = request.ip;
+        const response = await this.http.request('POST', '/api/v2/licenses/validate', body);
+        const apiResponse = parseApiResponse(response, 403);
+        const parsed = parseValidationResponse(apiResponse);
+        if (apiResponse.statusCode === 200 && this.signatureVerifier) {
+            if (parsed.rawPayload !== null) {
+                this.signatureVerifier.verify(parsed.rawPayload, parsed.signature);
+                if (parsed.nonce !== null && parsed.timestamp !== null) {
+                    this.replayProtector?.check(parsed.nonce, parsed.timestamp);
+                }
+            }
+        }
+        return parsed.result;
+    }
+    async create(request) {
+        const response = await this.http.request('POST', '/api/v2/licenses', request);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async get(key) {
+        const response = await this.http.request('GET', `/api/v2/licenses/${encodeURIComponent(key)}`);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async list(request) {
+        const query = new URLSearchParams();
+        if (request) {
+            for (const [key, value] of Object.entries(request)) {
+                if (value !== undefined)
+                    query.set(key, String(value));
+            }
+        }
+        const response = await this.http.request('GET', '/api/v2/licenses', undefined, query.size > 0 ? query : undefined);
+        const apiResponse = parseApiResponse(response);
+        return parsePage(apiResponse.result.page);
+    }
+    async update(key, request) {
+        const body = this.buildUpdateBody(request);
+        const response = await this.http.request('PATCH', `/api/v2/licenses/${encodeURIComponent(key)}`, body);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async delete(key) {
+        const response = await this.http.request('DELETE', `/api/v2/licenses/${encodeURIComponent(key)}`);
+        parseApiResponse(response);
+    }
+    async regenerateKey(key, newKey) {
+        const query = newKey ? new URLSearchParams({ newKey }) : undefined;
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/regenerate-key`, undefined, query);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    buildUpdateBody(request) {
+        const body = {};
+        if (request.product !== undefined)
+            body.product = request.product;
+        if (request.tier !== undefined)
+            body.tier = request.tier;
+        if (request.expiration === null) {
+            body.expiration = '1970-01-01T00:00:00Z';
+        }
+        else if (request.expiration !== undefined) {
+            body.expiration = request.expiration.toISOString();
+        }
+        if (request.maxServers !== undefined)
+            body.maxServers = request.maxServers;
+        if (request.maxIps !== undefined)
+            body.maxIps = request.maxIps;
+        if (request.note === null) {
+            body.note = '';
+        }
+        else if (request.note !== undefined) {
+            body.note = request.note;
+        }
+        if (request.connections !== undefined)
+            body.connections = request.connections;
+        if (request.subUsers !== undefined)
+            body.subUsers = request.subUsers;
+        if (request.servers !== undefined)
+            body.servers = request.servers;
+        if (request.ips !== undefined)
+            body.ips = request.ips;
+        if (request.additionalEntitlements !== undefined)
+            body.additionalEntitlements = request.additionalEntitlements;
+        if (request.blacklistReason === null) {
+            body.blacklistReason = '';
+        }
+        else if (request.blacklistReason !== undefined) {
+            body.blacklistReason = request.blacklistReason;
+        }
+        return body;
+    }
+}
+export function requireValid(result) {
+    if (!result.success) {
+        throw new LicenseValidationError(result.message, result.type, result.details);
+    }
+    return result.details;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { FailureDetails, ValidationResultType } from './types.js';
+export declare class SentinelError extends Error {
+    name: string;
+}
+export declare class SentinelApiError extends SentinelError {
+    name: string;
+    readonly statusCode: number;
+    readonly retryAfter?: number;
+    readonly type?: string;
+    constructor(message: string, statusCode: number, retryAfter?: number, type?: string);
+}
+export declare class SentinelConnectionError extends SentinelError {
+    name: string;
+    readonly cause: Error;
+}
+export declare class LicenseValidationError extends SentinelError {
+    name: string;
+    readonly type: ValidationResultType;
+    readonly details?: FailureDetails;
+    constructor(message: string, type: ValidationResultType, details?: FailureDetails);
+}
+export declare class SignatureVerificationError extends SentinelError {
+    name: string;
+}
+export declare class ReplayDetectedError extends SentinelError {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+export class SentinelError extends Error {
+    name = 'SentinelError';
+}
+export class SentinelApiError extends SentinelError {
+    name = 'SentinelApiError';
+    statusCode;
+    retryAfter;
+    type;
+    constructor(message, statusCode, retryAfter, type) {
+        super(message);
+        this.statusCode = statusCode;
+        this.retryAfter = retryAfter;
+        this.type = type;
+    }
+}
+export class SentinelConnectionError extends SentinelError {
+    name = 'SentinelConnectionError';
+}
+export class LicenseValidationError extends SentinelError {
+    name = 'LicenseValidationError';
+    type;
+    details;
+    constructor(message, type, details) {
+        super(message);
+        this.type = type;
+        this.details = details;
+    }
+}
+export class SignatureVerificationError extends SentinelError {
+    name = 'SignatureVerificationError';
+}
+export class ReplayDetectedError extends SentinelError {
+    name = 'ReplayDetectedError';
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1 @@
+export declare function getMachineFingerprint(): string;

package/dist/fingerprint.js

@@ -0,0 +1,175 @@
+import { execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { arch, hostname, networkInterfaces, type as osType, platform } from 'node:os';
+let cached;
+export function getMachineFingerprint() {
+    if (cached !== undefined)
+        return cached;
+    const signals = [];
+    const primaryId = getPlatformId();
+    if (primaryId) {
+        signals.push(primaryId);
+    }
+    else {
+        collectFallbackSignals(signals);
+    }
+    cached = createHash('sha256').update(signals.join('\0')).digest('hex').substring(0, 32);
+    return cached;
+}
+function getPlatformId() {
+    try {
+        switch (platform()) {
+            case 'linux':
+                return readFileSafe('/etc/machine-id') ?? readFileSafe('/var/lib/dbus/machine-id');
+            case 'darwin': {
+                const output = execSafe('ioreg -rd1 -c IOPlatformExpertDevice');
+                return output?.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/)?.[1] ?? null;
+            }
+            case 'win32': {
+                const output = execSafe('reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid');
+                return output?.match(/MachineGuid\s+REG_SZ\s+(\S+)/)?.[1] ?? null;
+            }
+            case 'freebsd':
+                return execSafe('sysctl -n kern.hostuuid')?.trim() ?? null;
+            default:
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function collectFallbackSignals(signals) {
+    const containerized = isContainerized();
+    if (platform() === 'linux') {
+        collectDmiSignals(signals);
+    }
+    signals.push(platform(), arch(), osType());
+    if (!containerized) {
+        const host = hostname();
+        if (host)
+            signals.push(host);
+    }
+    const macs = getMacAddresses(containerized);
+    if (macs.length > 0)
+        signals.push(...macs);
+}
+const VIRTUAL_INTERFACE_PREFIXES = [
+    'docker',
+    'br-',
+    'veth',
+    'cni',
+    'flannel',
+    'cali',
+    'virbr',
+    'podman',
+    'vmnet',
+    'vboxnet',
+    'awdl',
+    'llw',
+    'utun',
+    'dummy',
+    'zt',
+    'tailscale',
+    'wg',
+    'tun',
+    'tap',
+    'isatap',
+    'teredo',
+    'bond',
+    'team',
+];
+function getMacAddresses(containerized) {
+    const interfaces = networkInterfaces();
+    const macs = new Set();
+    for (const [name, entries] of Object.entries(interfaces)) {
+        if (!entries)
+            continue;
+        const lower = name.toLowerCase();
+        if (VIRTUAL_INTERFACE_PREFIXES.some((p) => lower.startsWith(p)))
+            continue;
+        for (const entry of entries) {
+            if (entry.internal)
+                continue;
+            if (!entry.mac || entry.mac === '00:00:00:00:00:00' || entry.mac === 'ff:ff:ff:ff:ff:ff')
+                continue;
+            if (containerized && isLocallyAdministered(entry.mac))
+                continue;
+            macs.add(entry.mac);
+        }
+    }
+    if (containerized && macs.size === 0) {
+        return getMacAddresses(false);
+    }
+    return [...macs].sort();
+}
+function isLocallyAdministered(mac) {
+    const firstByte = parseInt(mac.split(':')[0], 16);
+    return (firstByte & 0x02) !== 0;
+}
+const DMI_PATHS = [
+    '/sys/class/dmi/id/product_serial',
+    '/sys/class/dmi/id/board_serial',
+    '/sys/class/dmi/id/product_uuid',
+];
+const DMI_COMPOSITE_PATHS = [
+    '/sys/class/dmi/id/board_vendor',
+    '/sys/class/dmi/id/board_name',
+    '/sys/class/dmi/id/product_name',
+    '/sys/class/dmi/id/sys_vendor',
+];
+function collectDmiSignals(signals) {
+    for (const path of DMI_PATHS) {
+        const value = readFileSafe(path);
+        if (value) {
+            signals.push(value);
+            return;
+        }
+    }
+    const composite = DMI_COMPOSITE_PATHS.map(readFileSafe)
+        .filter((v) => v !== null)
+        .join(':');
+    if (composite)
+        signals.push(composite);
+}
+function isContainerized() {
+    if (platform() !== 'linux')
+        return false;
+    try {
+        if (existsSync('/.dockerenv') || existsSync('/run/.containerenv'))
+            return true;
+    }
+    catch {
+        /* ignore */
+    }
+    if (process.env.KUBERNETES_SERVICE_HOST ||
+        process.env.container ||
+        process.env.DOTNET_RUNNING_IN_CONTAINER) {
+        return true;
+    }
+    const cgroup = readFileSafe('/proc/1/cgroup') ?? readFileSafe('/proc/self/cgroup');
+    if (cgroup) {
+        const markers = ['docker', 'containerd', 'kubepods', 'podman', 'libpod', 'lxc', 'machine.slice'];
+        if (markers.some((m) => cgroup.includes(m)))
+            return true;
+    }
+    return false;
+}
+function readFileSafe(path) {
+    try {
+        const content = readFileSync(path, 'utf-8').trim();
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+function execSafe(command) {
+    try {
+        return execSync(command, { encoding: 'utf-8', timeout: 5_000 });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,12 @@
+export interface HttpResponse {
+    statusCode: number;
+    body: string | null;
+    headers: Headers;
+}
+export declare class SentinelHttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    request(method: string, path: string, body?: unknown, query?: URLSearchParams): Promise<HttpResponse>;
+}

package/dist/http.js

@@ -0,0 +1,42 @@
+import { SentinelConnectionError } from './errors.js';
+export class SentinelHttpClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    constructor(baseUrl, apiKey, timeout) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        this.timeout = timeout;
+    }
+    async request(method, path, body, query) {
+        let url = `${this.baseUrl}${path}`;
+        if (query && query.size > 0) {
+            url += `?${query.toString()}`;
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+        };
+        const init = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.timeout),
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, init);
+            const text = await response.text();
+            return {
+                statusCode: response.status,
+                body: text || null,
+                headers: response.headers,
+            };
+        }
+        catch (error) {
+            throw new SentinelConnectionError(error instanceof Error ? error.message : 'Connection failed', { cause: error });
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { requireValid, SentinelClient } from './client.js';
+export { LicenseValidationError, ReplayDetectedError, SentinelApiError, SentinelConnectionError, SentinelError, SignatureVerificationError, } from './errors.js';
+export { getMachineFingerprint } from './fingerprint.js';
+export { getPublicIp } from './ip.js';
+export type { BlacklistInfo, CreateLicenseRequest, FailureDetails, License, LicenseIssuer, LicenseProduct, LicenseTier, ListLicensesRequest, Page, SentinelClientOptions, SubUser, UpdateLicenseRequest, ValidateRequest, ValidationDetails, ValidationResult, } from './types.js';
+export { ValidationResultType } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { requireValid, SentinelClient } from './client.js';
+export { LicenseValidationError, ReplayDetectedError, SentinelApiError, SentinelConnectionError, SentinelError, SignatureVerificationError, } from './errors.js';
+export { getMachineFingerprint } from './fingerprint.js';
+export { getPublicIp } from './ip.js';
+export { ValidationResultType } from './types.js';

package/dist/ip.d.ts

@@ -0,0 +1 @@
+export declare function getPublicIp(): Promise<string | null>;

package/dist/ip.js

@@ -0,0 +1,14 @@
+export async function getPublicIp() {
+    try {
+        const response = await fetch('https://checkip.amazonaws.com', {
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!response.ok)
+            return null;
+        const text = await response.text();
+        return text.trim();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/operations/connections.d.ts

@@ -0,0 +1,8 @@
+import type { SentinelHttpClient } from '../http.js';
+import type { License } from '../types.js';
+export declare class ConnectionOperations {
+    private readonly http;
+    constructor(http: SentinelHttpClient);
+    add(key: string, connections: Record<string, string>): Promise<License>;
+    remove(key: string, platforms: string[]): Promise<License>;
+}

package/dist/operations/connections.js

@@ -0,0 +1,20 @@
+import { parseApiResponse, parseLicense } from '../parsing.js';
+export class ConnectionOperations {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async add(key, connections) {
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/connections`, connections);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async remove(key, platforms) {
+        const query = new URLSearchParams();
+        for (const p of platforms)
+            query.append('platforms', p);
+        const response = await this.http.request('DELETE', `/api/v2/licenses/${encodeURIComponent(key)}/connections`, undefined, query);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+}

package/dist/operations/ips.d.ts

@@ -0,0 +1,8 @@
+import type { SentinelHttpClient } from '../http.js';
+import type { License } from '../types.js';
+export declare class IpOperations {
+    private readonly http;
+    constructor(http: SentinelHttpClient);
+    add(key: string, ips: string[]): Promise<License>;
+    remove(key: string, ips: string[]): Promise<License>;
+}

package/dist/operations/ips.js

@@ -0,0 +1,20 @@
+import { parseApiResponse, parseLicense } from '../parsing.js';
+export class IpOperations {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async add(key, ips) {
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/ips`, ips);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async remove(key, ips) {
+        const query = new URLSearchParams();
+        for (const ip of ips)
+            query.append('ips', ip);
+        const response = await this.http.request('DELETE', `/api/v2/licenses/${encodeURIComponent(key)}/ips`, undefined, query);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+}

package/dist/operations/servers.d.ts

@@ -0,0 +1,8 @@
+import type { SentinelHttpClient } from '../http.js';
+import type { License } from '../types.js';
+export declare class ServerOperations {
+    private readonly http;
+    constructor(http: SentinelHttpClient);
+    add(key: string, servers: string[]): Promise<License>;
+    remove(key: string, servers: string[]): Promise<License>;
+}

package/dist/operations/servers.js

@@ -0,0 +1,20 @@
+import { parseApiResponse, parseLicense } from '../parsing.js';
+export class ServerOperations {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async add(key, servers) {
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/servers`, servers);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async remove(key, servers) {
+        const query = new URLSearchParams();
+        for (const s of servers)
+            query.append('servers', s);
+        const response = await this.http.request('DELETE', `/api/v2/licenses/${encodeURIComponent(key)}/servers`, undefined, query);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+}

package/dist/operations/sub-users.d.ts

@@ -0,0 +1,8 @@
+import type { SentinelHttpClient } from '../http.js';
+import type { License, SubUser } from '../types.js';
+export declare class SubUserOperations {
+    private readonly http;
+    constructor(http: SentinelHttpClient);
+    add(key: string, subUsers: SubUser[]): Promise<License>;
+    remove(key: string, subUsers: SubUser[]): Promise<License>;
+}

package/dist/operations/sub-users.js

@@ -0,0 +1,17 @@
+import { parseApiResponse, parseLicense } from '../parsing.js';
+export class SubUserOperations {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async add(key, subUsers) {
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/sub-users`, subUsers);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+    async remove(key, subUsers) {
+        const response = await this.http.request('POST', `/api/v2/licenses/${encodeURIComponent(key)}/sub-users/remove`, subUsers);
+        const apiResponse = parseApiResponse(response);
+        return parseLicense(apiResponse.result.license);
+    }
+}

package/dist/parsing.d.ts

@@ -0,0 +1,20 @@
+import type { HttpResponse } from './http.js';
+import type { CanonicalPayloadFields } from './signature.js';
+import type { License, Page, ValidationResult } from './types.js';
+export interface ApiResponse {
+    statusCode: number;
+    type: string;
+    message: string;
+    result: unknown;
+}
+export interface ParsedValidation {
+    result: ValidationResult;
+    nonce: string | null;
+    timestamp: number | null;
+    signature: string | null;
+    rawPayload: CanonicalPayloadFields | null;
+}
+export declare function parseApiResponse(response: HttpResponse, ...allowedStatuses: number[]): ApiResponse;
+export declare function parseLicense(data: unknown): License;
+export declare function parsePage(data: unknown): Page<License>;
+export declare function parseValidationResponse(response: ApiResponse): ParsedValidation;

package/dist/parsing.js

@@ -0,0 +1,193 @@
+import { SentinelApiError } from './errors.js';
+import { ValidationResultType } from './types.js';
+export function parseApiResponse(response, ...allowedStatuses) {
+    const isSuccess = response.statusCode >= 200 && response.statusCode < 300;
+    const isAllowed = allowedStatuses.includes(response.statusCode);
+    let type = '';
+    let message = '';
+    let result = null;
+    if (response.body) {
+        try {
+            const json = JSON.parse(response.body);
+            type = json.type ?? '';
+            message = json.message ?? '';
+            result = json.result ?? null;
+        }
+        catch {
+            // non-JSON body
+        }
+    }
+    if (!isSuccess && !isAllowed) {
+        let retryAfter;
+        if (response.statusCode === 429) {
+            const header = response.headers.get('X-Rate-Limit-Retry-After-Seconds');
+            if (header)
+                retryAfter = parseInt(header, 10) || undefined;
+        }
+        throw new SentinelApiError(message || `HTTP ${response.statusCode}`, response.statusCode, retryAfter, type || undefined);
+    }
+    return { statusCode: response.statusCode, type, message, result };
+}
+export function parseLicense(data) {
+    const d = data;
+    return {
+        id: d.id,
+        key: d.key,
+        product: parseProduct(d.product),
+        tier: parseTier(d.tier),
+        issuer: parseIssuer(d.issuer),
+        createdAt: new Date(d.createdAt),
+        expiration: d.expiration ? new Date(d.expiration) : undefined,
+        maxServers: d.maxServers,
+        maxIps: d.maxIps,
+        note: d.note ?? undefined,
+        connections: d.connections ?? {},
+        subUsers: (d.subUsers ?? []).map(parseSubUser),
+        servers: parseTimestampMap(d.servers),
+        ips: parseTimestampMap(d.ips),
+        additionalEntitlements: new Set(d.additionalEntitlements ?? []),
+        entitlements: new Set(d.entitlements ?? []),
+        blacklist: d.blacklist ? parseBlacklist(d.blacklist) : undefined,
+    };
+}
+export function parsePage(data) {
+    const d = data;
+    const meta = d.page;
+    return {
+        content: (d.content ?? []).map(parseLicense),
+        size: meta.size,
+        number: meta.number,
+        totalElements: meta.totalElements,
+        totalPages: meta.totalPages,
+    };
+}
+export function parseValidationResponse(response) {
+    if (response.statusCode === 200) {
+        const result = response.result;
+        const validation = result?.validation;
+        const details = validation?.details;
+        const rawEntitlements = details?.entitlements ?? [];
+        const rawExpiration = details?.expiration ?? null;
+        const validationDetails = {
+            expiration: rawExpiration ? new Date(rawExpiration) : undefined,
+            serverCount: details.serverCount,
+            maxServers: details.maxServers,
+            ipCount: details.ipCount,
+            maxIps: details.maxIps,
+            tier: details.tier,
+            entitlements: new Set(rawEntitlements),
+        };
+        return {
+            result: { success: true, message: response.message, details: validationDetails },
+            nonce: validation?.nonce ?? null,
+            timestamp: validation?.timestamp ?? null,
+            signature: validation?.signature ?? null,
+            rawPayload: {
+                entitlements: rawEntitlements,
+                expiration: rawExpiration,
+                ipCount: details.ipCount,
+                maxIps: details.maxIps,
+                maxServers: details.maxServers,
+                nonce: validation?.nonce,
+                serverCount: details.serverCount,
+                tier: details.tier,
+                timestamp: validation?.timestamp,
+            },
+        };
+    }
+    const resultType = mapValidationResultType(response.type);
+    if (resultType === ValidationResultType.Unknown) {
+        throw new SentinelApiError(response.message || `HTTP ${response.statusCode}`, response.statusCode, undefined, response.type || undefined);
+    }
+    const failureDetails = parseFailureDetails(resultType, response.result);
+    return {
+        result: {
+            success: false,
+            message: response.message,
+            type: resultType,
+            details: failureDetails,
+        },
+        nonce: null,
+        timestamp: null,
+        signature: null,
+        rawPayload: null,
+    };
+}
+function mapValidationResultType(type) {
+    const match = Object.values(ValidationResultType).find((v) => v === type);
+    return match ?? ValidationResultType.Unknown;
+}
+function parseFailureDetails(type, result) {
+    if (!result)
+        return undefined;
+    const r = result;
+    switch (type) {
+        case ValidationResultType.BlacklistedLicense: {
+            const blacklist = r.blacklist;
+            if (blacklist) {
+                return {
+                    type: 'blacklist',
+                    timestamp: new Date(blacklist.timestamp),
+                    reason: blacklist.reason,
+                };
+            }
+            return undefined;
+        }
+        case ValidationResultType.ExcessiveServers:
+            if (r.maxServers !== undefined) {
+                return { type: 'excessiveServers', maxServers: r.maxServers };
+            }
+            return undefined;
+        case ValidationResultType.ExcessiveIps:
+            if (r.maxIps !== undefined) {
+                return { type: 'excessiveIps', maxIps: r.maxIps };
+            }
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+function parseProduct(data) {
+    const d = data;
+    return {
+        id: d.id,
+        name: d.name,
+        description: d.description ?? undefined,
+        logoUrl: d.logoUrl ?? undefined,
+    };
+}
+function parseTier(data) {
+    const d = data;
+    return {
+        name: d.name,
+        entitlements: new Set(d.entitlements ?? []),
+    };
+}
+function parseIssuer(data) {
+    const d = data;
+    return {
+        type: d.type,
+        id: d.id,
+        displayName: d.displayName,
+    };
+}
+function parseSubUser(data) {
+    const d = data;
+    return { platform: d.platform, value: d.value };
+}
+function parseBlacklist(data) {
+    const d = data;
+    return {
+        timestamp: new Date(d.timestamp),
+        reason: d.reason ?? undefined,
+    };
+}
+function parseTimestampMap(data) {
+    if (!data)
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        result[key] = new Date(value);
+    }
+    return result;
+}

package/dist/replay.d.ts

@@ -0,0 +1,7 @@
+export declare class ReplayProtector {
+    private readonly maxAge;
+    private readonly maxSize;
+    private readonly seen;
+    constructor(maxTimestampAge: number, cacheSize: number);
+    check(nonce: string, timestamp: number): void;
+}

package/dist/replay.js

@@ -0,0 +1,25 @@
+import { ReplayDetectedError } from './errors.js';
+export class ReplayProtector {
+    maxAge;
+    maxSize;
+    seen = new Map();
+    constructor(maxTimestampAge, cacheSize) {
+        this.maxAge = maxTimestampAge;
+        this.maxSize = cacheSize;
+    }
+    check(nonce, timestamp) {
+        const now = Date.now();
+        if (Math.abs(now - timestamp) > this.maxAge) {
+            throw new ReplayDetectedError(`Response timestamp is outside acceptable window (drift: ${Math.abs(now - timestamp)}ms, max: ${this.maxAge}ms)`);
+        }
+        if (this.seen.has(nonce)) {
+            throw new ReplayDetectedError(`Duplicate nonce detected: ${nonce}`);
+        }
+        this.seen.set(nonce, timestamp);
+        if (this.seen.size > this.maxSize) {
+            const oldestKey = this.seen.keys().next().value;
+            if (oldestKey !== undefined)
+                this.seen.delete(oldestKey);
+        }
+    }
+}

package/dist/signature.d.ts

@@ -0,0 +1,17 @@
+export interface CanonicalPayloadFields {
+    entitlements: string[];
+    expiration: string | null;
+    ipCount: number;
+    maxIps: number;
+    maxServers: number;
+    nonce: string;
+    serverCount: number;
+    tier: string;
+    timestamp: number;
+}
+export declare function buildCanonicalPayload(fields: CanonicalPayloadFields): string;
+export declare class SignatureVerifier {
+    private readonly publicKey;
+    constructor(base64PublicKey: string);
+    verify(payload: CanonicalPayloadFields, signature: string | null): void;
+}

package/dist/signature.js

@@ -0,0 +1,35 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { SignatureVerificationError } from './errors.js';
+export function buildCanonicalPayload(fields) {
+    return JSON.stringify({
+        entitlements: [...fields.entitlements].sort(),
+        expiration: fields.expiration,
+        ipCount: fields.ipCount,
+        maxIps: fields.maxIps,
+        maxServers: fields.maxServers,
+        nonce: fields.nonce,
+        serverCount: fields.serverCount,
+        tier: fields.tier,
+        timestamp: fields.timestamp,
+    });
+}
+export class SignatureVerifier {
+    publicKey;
+    constructor(base64PublicKey) {
+        this.publicKey = createPublicKey({
+            key: Buffer.from(base64PublicKey, 'base64'),
+            format: 'der',
+            type: 'spki',
+        });
+    }
+    verify(payload, signature) {
+        if (!signature) {
+            throw new SignatureVerificationError('Response signature is missing');
+        }
+        const canonical = buildCanonicalPayload(payload);
+        const isValid = verify(null, Buffer.from(canonical), this.publicKey, Buffer.from(signature, 'base64'));
+        if (!isValid) {
+            throw new SignatureVerificationError('Signature verification failed');
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+export interface SentinelClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    publicKey?: string;
+    replayProtection?: {
+        maxTimestampAge?: number;
+        cacheSize?: number;
+    };
+}
+export interface License {
+    id: string;
+    key: string;
+    product: LicenseProduct;
+    tier: LicenseTier;
+    issuer: LicenseIssuer;
+    createdAt: Date;
+    expiration?: Date;
+    maxServers: number;
+    maxIps: number;
+    note?: string;
+    connections: Record<string, string>;
+    subUsers: SubUser[];
+    servers: Record<string, Date>;
+    ips: Record<string, Date>;
+    additionalEntitlements: Set<string>;
+    entitlements: Set<string>;
+    blacklist?: BlacklistInfo;
+}
+export interface LicenseProduct {
+    id: string;
+    name: string;
+    description?: string;
+    logoUrl?: string;
+}
+export interface LicenseTier {
+    name: string;
+    entitlements: Set<string>;
+}
+export interface LicenseIssuer {
+    type: string;
+    id: string;
+    displayName: string;
+}
+export interface SubUser {
+    platform: string;
+    value: string;
+}
+export interface BlacklistInfo {
+    timestamp: Date;
+    reason?: string;
+}
+export interface Page<T> {
+    content: T[];
+    size: number;
+    number: number;
+    totalElements: number;
+    totalPages: number;
+}
+export type ValidationResult = {
+    success: true;
+    message: string;
+    details: ValidationDetails;
+} | {
+    success: false;
+    message: string;
+    type: ValidationResultType;
+    details?: FailureDetails;
+};
+export interface ValidationDetails {
+    expiration?: Date;
+    serverCount: number;
+    maxServers: number;
+    ipCount: number;
+    maxIps: number;
+    tier: string;
+    entitlements: Set<string>;
+}
+export declare enum ValidationResultType {
+    Success = "SUCCESS",
+    InvalidProduct = "INVALID_PRODUCT",
+    InvalidLicense = "INVALID_LICENSE",
+    InvalidPlatform = "INVALID_PLATFORM",
+    ExpiredLicense = "EXPIRED_LICENSE",
+    BlacklistedLicense = "BLACKLISTED_LICENSE",
+    ConnectionMismatch = "CONNECTION_MISMATCH",
+    ExcessiveServers = "EXCESSIVE_SERVERS",
+    ExcessiveIps = "EXCESSIVE_IPS",
+    Unknown = "UNKNOWN"
+}
+export type FailureDetails = {
+    type: 'blacklist';
+    timestamp: Date;
+    reason: string;
+} | {
+    type: 'excessiveServers';
+    maxServers: number;
+} | {
+    type: 'excessiveIps';
+    maxIps: number;
+};
+export interface ValidateRequest {
+    key?: string;
+    product: string;
+    connectionPlatform?: string;
+    connectionValue?: string;
+    server?: string;
+    ip?: string;
+}
+export interface CreateLicenseRequest {
+    product: string;
+    key?: string;
+    tier?: string;
+    expiration?: Date;
+    maxServers?: number;
+    maxIps?: number;
+    note?: string;
+    connections?: Record<string, string>;
+    additionalEntitlements?: string[];
+}
+export interface UpdateLicenseRequest {
+    product?: string;
+    tier?: string;
+    expiration?: Date | null;
+    maxServers?: number;
+    maxIps?: number;
+    note?: string | null;
+    connections?: Record<string, string>;
+    subUsers?: SubUser[];
+    servers?: string[];
+    ips?: string[];
+    additionalEntitlements?: string[];
+    blacklistReason?: string | null;
+}
+export interface ListLicensesRequest {
+    product?: string;
+    status?: string;
+    query?: string;
+    platform?: string;
+    value?: string;
+    server?: string;
+    ip?: string;
+    page?: number;
+    size?: number;
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+export var ValidationResultType;
+(function (ValidationResultType) {
+    ValidationResultType["Success"] = "SUCCESS";
+    ValidationResultType["InvalidProduct"] = "INVALID_PRODUCT";
+    ValidationResultType["InvalidLicense"] = "INVALID_LICENSE";
+    ValidationResultType["InvalidPlatform"] = "INVALID_PLATFORM";
+    ValidationResultType["ExpiredLicense"] = "EXPIRED_LICENSE";
+    ValidationResultType["BlacklistedLicense"] = "BLACKLISTED_LICENSE";
+    ValidationResultType["ConnectionMismatch"] = "CONNECTION_MISMATCH";
+    ValidationResultType["ExcessiveServers"] = "EXCESSIVE_SERVERS";
+    ValidationResultType["ExcessiveIps"] = "EXCESSIVE_IPS";
+    ValidationResultType["Unknown"] = "UNKNOWN";
+})(ValidationResultType || (ValidationResultType = {}));

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "sentinel-js-client",
+  "version": "2.0.3",
+  "description": "Node.js client library for Sentinel",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx --test test/**/*.test.ts",
+    "check": "biome check",
+    "format": "biome check --write"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Demeng",
+    "email": "hi@demeng.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/demengc/sentinel-js-client.git"
+  },
+  "homepage": "https://github.com/demengc/sentinel-js-client",
+  "bugs": {
+    "url": "https://github.com/demengc/sentinel-js-client/issues"
+  },
+  "keywords": [
+    "sentinel",
+    "license",
+    "licensing",
+    "api-client"
+  ]
+}