@hubex/mcp 0.2.0

package/dist/auth.js

@@ -0,0 +1,226 @@
+/**
+ * Authentication. One lifecycle, three ways to obtain the first access token:
+ *  - "token": the user is asked for a ready Bearer JWT.
+ *  - "login": Basic (username:password) -> JWT via the AUTHN service.
+ *  - "service": a long-lived service token -> JWT via AUTHZ/AccessTokens.
+ * Afterwards all three refresh the same way.
+ */
+/** Decode a JWT payload without verifying the signature (we only read claims). */
+export function decodeJwt(token) {
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const json = Buffer.from(parts[1], "base64url").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+function tenantFromClaims(claims) {
+    const t = claims?.TenantID;
+    return t === undefined || t === null ? undefined : String(t);
+}
+/** exp is in seconds since epoch; treat as expired 30s early to avoid races. */
+function isExpired(expSeconds) {
+    if (!expSeconds)
+        return false;
+    return Date.now() >= expSeconds * 1000 - 30_000;
+}
+/**
+ * Validates a token typed in by the user. Rejecting here — before any request —
+ * gives a clear message instead of a bare 401 later.
+ */
+export function assertUsableJwt(token) {
+    const claims = decodeJwt(token);
+    if (!claims) {
+        throw new Error("Это не похоже на JWT: ожидается access-токен HubEx без префикса «Bearer ».");
+    }
+    if (isExpired(claims.exp)) {
+        throw new Error("Срок действия токена уже истёк. Нужен свежий access-токен HubEx.");
+    }
+}
+/**
+ * Obtains a JWT and keeps it fresh. Three ways in — Basic credentials
+ * ("login"), a long-lived service token ("service") or a token typed in by the
+ * user ("token") — and one shared token lifecycle afterwards.
+ */
+class RefreshingAuth {
+    config;
+    prompter;
+    accessToken;
+    accessExp; // seconds since epoch
+    refreshToken;
+    refreshExp; // seconds since epoch
+    tenantId;
+    inflight;
+    constructor(config) {
+        this.config = config;
+        this.tenantId = config.tenantId;
+    }
+    getTenantId() {
+        return this.tenantId;
+    }
+    setPrompter(prompt) {
+        this.prompter = prompt;
+    }
+    /** Stores a token supplied out of band and immediately buys a refresh token. */
+    async acceptToken(token) {
+        const trimmed = token.trim();
+        assertUsableJwt(trimmed);
+        this.refreshToken = undefined;
+        this.refreshExp = undefined;
+        this.absorb({ access_token: trimmed });
+        await this.acquireRefreshToken();
+    }
+    async getAccessToken() {
+        if (this.accessToken && !isExpired(this.accessExp)) {
+            return this.accessToken;
+        }
+        // De-duplicate concurrent acquisitions.
+        if (!this.inflight) {
+            this.inflight = this.acquire().finally(() => {
+                this.inflight = undefined;
+            });
+        }
+        return this.inflight;
+    }
+    async acquire() {
+        if (this.refreshToken && !isExpired(this.refreshExp)) {
+            try {
+                return await this.renew();
+            }
+            catch (err) {
+                // Not fatal: fall back to a full authentication exactly once.
+                console.error(`[hubex-mcp] token refresh failed, re-authenticating: ${err.message}`);
+                this.refreshToken = undefined;
+                this.refreshExp = undefined;
+            }
+        }
+        else if (this.refreshToken) {
+            // Протух — выбрасываем, иначе новый не будет запрошен после аутентификации.
+            this.refreshToken = undefined;
+            this.refreshExp = undefined;
+        }
+        const token = await this.authenticate();
+        if (!this.refreshToken)
+            await this.acquireRefreshToken();
+        return token;
+    }
+    /**
+     * Renew via the refresh token. `accessJwt` carries the old (expired) token on
+     * purpose: AUTHZ reads its LONG_TERM_CLIENT / SHORT_TERM_CLIENT claims to pick
+     * the issuer options, and without it the new token silently gets the default
+     * (shorter) lifetime. The refresh token itself is not rotated.
+     */
+    async renew() {
+        const result = await this.fetchJwt(`${this.config.apiBaseUrl}/AUTHZ/AccessTokens`, {
+            method: "POST",
+            headers: this.authHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ refreshJwt: this.refreshToken, accessJwt: this.accessToken }),
+        });
+        const token = this.absorb(result);
+        if (!token) {
+            throw new Error("Refresh succeeded but no access_token was returned.");
+        }
+        return token;
+    }
+    /** Full authentication: credentials from config, or a token from the user. */
+    async authenticate() {
+        let result;
+        if (this.config.authMode === "service") {
+            result = await this.loginByServiceToken();
+        }
+        else if (this.config.authMode === "token") {
+            result = { access_token: await this.promptForToken() };
+        }
+        else {
+            result = await this.loginByPassword();
+        }
+        const token = this.absorb(result);
+        if (!token) {
+            throw new Error("Authentication succeeded but no access_token was returned.");
+        }
+        return token;
+    }
+    /**
+     * Asks the user for an access token. The token itself is the credential —
+     * there is nothing to exchange, so we validate it and move straight on to
+     * buying a refresh token.
+     */
+    async promptForToken() {
+        if (!this.prompter) {
+            throw new Error("Нет способа запросить токен: клиент не поддерживает интерактивный ввод. " +
+                "Вызови инструмент hubex_set_token и передай access-токен HubEx.");
+        }
+        const token = (await this.prompter()).trim();
+        assertUsableJwt(token);
+        return token;
+    }
+    loginByPassword() {
+        const basic = Buffer.from(`${encodeURIComponent(this.config.username)}:${encodeURIComponent(this.config.password)}`).toString("base64");
+        return this.fetchJwt(`${this.config.apiBaseUrl}/AUTHN/Accounts/login`, {
+            method: "POST",
+            headers: this.authHeaders({ Authorization: `Basic ${basic}` }),
+        });
+    }
+    /** AUTHZ/AccessTokens is anonymous — the service token itself identifies the member. */
+    loginByServiceToken() {
+        return this.fetchJwt(`${this.config.apiBaseUrl}/AUTHZ/AccessTokens`, {
+            method: "POST",
+            headers: this.authHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ serviceToken: this.config.serviceToken }),
+        });
+    }
+    /**
+     * A service-token login never carries a refresh token, so ask for one.
+     * Best-effort: without it we simply re-authenticate when the access token expires.
+     */
+    async acquireRefreshToken() {
+        try {
+            const result = await this.fetchJwt(`${this.config.apiBaseUrl}/AUTHZ/RefreshTokens`, {
+                method: "GET",
+                headers: this.authHeaders({ Authorization: `Bearer ${this.accessToken}` }),
+            });
+            this.absorb(result);
+        }
+        catch (err) {
+            console.error("[hubex-mcp] could not obtain a refresh token; will re-authenticate on expiry: " +
+                `${err.message}`);
+        }
+    }
+    authHeaders(extra) {
+        return {
+            "X-Application-ID": this.config.applicationId,
+            Accept: "application/json",
+            ...extra,
+        };
+    }
+    async fetchJwt(url, init) {
+        const res = await fetch(url, init);
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`${init.method ?? "GET"} ${url} failed (HTTP ${res.status}): ${body.slice(0, 500)}`);
+        }
+        return (await res.json());
+    }
+    /** Stores whatever the response carried; returns its access token, if any. */
+    absorb(result) {
+        if (result.access_token) {
+            this.accessToken = result.access_token;
+            const claims = decodeJwt(result.access_token);
+            this.accessExp = claims?.exp;
+            if (!this.tenantId)
+                this.tenantId = tenantFromClaims(claims);
+        }
+        if (result.refresh_token) {
+            this.refreshToken = result.refresh_token;
+            this.refreshExp = decodeJwt(result.refresh_token)?.exp;
+        }
+        return result.access_token;
+    }
+}
+export function createAuthProvider(config) {
+    return new RefreshingAuth(config);
+}

package/dist/config.js

@@ -0,0 +1,120 @@
+/**
+ * Configuration loaded from environment variables.
+ * See .env.example for the full list.
+ */
+export const ALL_ENVS = ["dev", "stg", "prod"];
+/** Хост API окружения: у прода нет префикса. */
+export function apiBaseUrlFor(env) {
+    return env === "prod" ? "https://api.hubex.ru/fsm" : `https://${env}-api.hubex.ru/fsm`;
+}
+export const ALL_SWAGGER_CATALOGS = ["dev", "prod"];
+export function swaggerCatalogFor(env) {
+    return env === "prod" ? "prod" : "dev";
+}
+export const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+/** Методы, доступные в режиме только-чтение. */
+const READONLY_METHODS = ["GET", "HEAD"];
+function required(name, value) {
+    if (!value || value.trim() === "") {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value.trim();
+}
+function parseBool(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false" && v !== "no";
+}
+/** Как parseBool, но при отсутствии переменной возвращает true. */
+function parseBoolDefaultTrue(value) {
+    if (value === undefined)
+        return true;
+    const v = value.trim().toLowerCase();
+    if (v === "")
+        return true;
+    return v !== "0" && v !== "false" && v !== "no";
+}
+function parseList(name, value) {
+    if (value === undefined)
+        return undefined;
+    const items = value
+        .split(",")
+        .map((s) => s.trim().toUpperCase())
+        .filter((s) => s !== "");
+    if (items.length === 0) {
+        throw new Error(`${name} is set but contains no values. Remove it or list values, e.g. ${name}=GET,POST`);
+    }
+    return items;
+}
+function parseMethods(env, readonly) {
+    const raw = parseList("HUBEX_METHODS", env.HUBEX_METHODS);
+    let methods = ALL_METHODS;
+    if (raw) {
+        for (const item of raw) {
+            if (!ALL_METHODS.includes(item)) {
+                throw new Error(`HUBEX_METHODS contains unknown method "${item}". Allowed: ${ALL_METHODS.join(", ")}`);
+            }
+        }
+        methods = ALL_METHODS.filter((m) => raw.includes(m));
+    }
+    if (readonly) {
+        const narrowed = methods.filter((m) => READONLY_METHODS.includes(m));
+        if (narrowed.length === 0) {
+            throw new Error(`HUBEX_READONLY=true allows only ${READONLY_METHODS.join(", ")}, ` +
+                `but HUBEX_METHODS=${methods.join(",")} leaves nothing enabled`);
+        }
+        return narrowed;
+    }
+    return methods;
+}
+function parseIntEnv(name, value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const n = Number(value.trim());
+    if (!Number.isInteger(n)) {
+        throw new Error(`${name} must be an integer, got: "${value}"`);
+    }
+    return n;
+}
+export function loadConfig(env = process.env) {
+    const rawEnv = (env.HUBEX_ENV ?? "dev").trim().toLowerCase();
+    if (!ALL_ENVS.includes(rawEnv)) {
+        throw new Error(`HUBEX_ENV must be one of ${ALL_ENVS.join(", ")}, got: "${rawEnv}"`);
+    }
+    const hubexEnv = rawEnv;
+    const authMode = (env.HUBEX_AUTH_MODE ?? "token").trim().toLowerCase();
+    if (authMode !== "token" && authMode !== "login" && authMode !== "service") {
+        throw new Error(`HUBEX_AUTH_MODE must be "token", "login" or "service", got: "${authMode}"`);
+    }
+    const config = {
+        env: hubexEnv,
+        apiBaseUrl: apiBaseUrlFor(hubexEnv),
+        swaggerCatalog: swaggerCatalogFor(hubexEnv),
+        applicationId: required("HUBEX_APPLICATION_ID", env.HUBEX_APPLICATION_ID),
+        tenantId: env.HUBEX_TENANT_ID?.trim() || undefined,
+        authMode: authMode,
+        readonly: parseBool(env.HUBEX_READONLY),
+        maskPii: parseBoolDefaultTrue(env.HUBEX_MASK_PII),
+        methods: parseMethods(env, parseBool(env.HUBEX_READONLY)),
+        services: parseList("HUBEX_SERVICES", env.HUBEX_SERVICES),
+        defaults: {
+            requestMethodID: parseIntEnv("HUBEX_DEFAULT_REQUEST_METHOD_ID", env.HUBEX_DEFAULT_REQUEST_METHOD_ID),
+            taskTypeID: parseIntEnv("HUBEX_DEFAULT_TASK_TYPE_ID", env.HUBEX_DEFAULT_TASK_TYPE_ID),
+            companyID: parseIntEnv("HUBEX_DEFAULT_COMPANY_ID", env.HUBEX_DEFAULT_COMPANY_ID),
+        },
+    };
+    for (const key of Object.keys(config.defaults)) {
+        if (config.defaults[key] === undefined)
+            delete config.defaults[key];
+    }
+    // Режим "token" ничего не читает из окружения: токен запрашивается у пользователя.
+    if (authMode === "service") {
+        config.serviceToken = required("HUBEX_SERVICE_TOKEN", env.HUBEX_SERVICE_TOKEN);
+    }
+    else if (authMode === "login") {
+        config.username = required("HUBEX_USERNAME", env.HUBEX_USERNAME);
+        config.password = required("HUBEX_PASSWORD", env.HUBEX_PASSWORD);
+    }
+    return config;
+}