taurusdb-core 0.3.0 → 0.5.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaurusDB MCP contributors
+
+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

@@ -4,7 +4,7 @@ Shared TaurusDB data-plane engine for:
 
 - schema discovery
 - readonly and mutation SQL execution
-- SQL guardrails and confirmation flow
+- SQL guardrails and external operator-signed approval flow
 - TaurusDB capability detection
 - diagnostics workflows
 
@@ -19,3 +19,5 @@ npm install taurusdb-core
 - Requires Node.js `>= 20`
 - This is the shared engine package
 - Most end users should install `taurusdb-mcp` instead
+- TLS verification, least-privilege credentials, bounded results, and JSONL
+  auditing are enabled as production safety controls

package/dist/audit/jsonl-writer.d.ts

@@ -0,0 +1,47 @@
+export type AuditDecision = "allowed" | "blocked" | "approval_required" | "approval_denied" | "failed";
+export interface AuditEvent {
+    timestamp: string;
+    task_id: string;
+    tool: string;
+    actor: string;
+    datasource?: string;
+    database?: string;
+    host?: string;
+    port?: number;
+    project_id?: string;
+    instance_id?: string;
+    node_id?: string;
+    sql_hash?: string;
+    raw_sql?: string;
+    decision: AuditDecision;
+    outcome: "success" | "error";
+    error_code?: string;
+    duration_ms: number;
+}
+export interface AuditWriter {
+    write(event: AuditEvent): Promise<void>;
+    close(): Promise<void>;
+}
+export interface JsonlAuditWriterOptions {
+    logPath: string;
+    syncWrites?: boolean;
+    maxBytes?: number;
+    maxFiles?: number;
+}
+export declare class JsonlAuditWriter implements AuditWriter {
+    private handle;
+    private readonly logPath;
+    private readonly syncWrites;
+    private readonly maxBytes;
+    private readonly maxFiles;
+    private currentBytes;
+    private pending;
+    private closed;
+    private constructor();
+    static create(options: JsonlAuditWriterOptions): Promise<JsonlAuditWriter>;
+    private rotate;
+    private writeLine;
+    write(event: AuditEvent): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createJsonlAuditWriter(options: JsonlAuditWriterOptions): Promise<JsonlAuditWriter>;

package/dist/audit/jsonl-writer.js

@@ -0,0 +1,124 @@
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function expandHome(input) {
+    if (input === "~") {
+        return os.homedir();
+    }
+    return input.startsWith("~/") ? path.join(os.homedir(), input.slice(2)) : input;
+}
+export class JsonlAuditWriter {
+    handle;
+    logPath;
+    syncWrites;
+    maxBytes;
+    maxFiles;
+    currentBytes;
+    pending = Promise.resolve();
+    closed = false;
+    constructor(opened, logPath, syncWrites, maxBytes, maxFiles) {
+        this.handle = opened.handle;
+        this.currentBytes = opened.size;
+        this.logPath = logPath;
+        this.syncWrites = syncWrites;
+        this.maxBytes = maxBytes;
+        this.maxFiles = maxFiles;
+    }
+    static async create(options) {
+        const logPath = path.resolve(expandHome(options.logPath));
+        await mkdir(path.dirname(logPath), { recursive: true, mode: 0o700 });
+        const opened = await openAuditFile(logPath);
+        const maxBytes = options.maxBytes ?? 104857600;
+        const maxFiles = options.maxFiles ?? 10;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            await opened.handle.close();
+            throw new Error("Audit maxBytes must be a positive safe integer.");
+        }
+        if (!Number.isSafeInteger(maxFiles) || maxFiles <= 0 || maxFiles > 100) {
+            await opened.handle.close();
+            throw new Error("Audit maxFiles must be an integer between 1 and 100.");
+        }
+        return new JsonlAuditWriter(opened, logPath, options.syncWrites ?? true, maxBytes, maxFiles);
+    }
+    async rotate() {
+        if (this.syncWrites) {
+            await this.handle.sync();
+        }
+        await this.handle.close();
+        try {
+            await rm(`${this.logPath}.${this.maxFiles}`, { force: true });
+            for (let index = this.maxFiles - 1; index >= 1; index -= 1) {
+                const source = `${this.logPath}.${index}`;
+                const destination = `${this.logPath}.${index + 1}`;
+                try {
+                    await rm(destination, { force: true });
+                    await rename(source, destination);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            }
+            await rm(`${this.logPath}.1`, { force: true });
+            await rename(this.logPath, `${this.logPath}.1`);
+            const opened = await openAuditFile(this.logPath);
+            this.handle = opened.handle;
+            this.currentBytes = opened.size;
+        }
+        catch (error) {
+            const reopened = await openAuditFile(this.logPath);
+            this.handle = reopened.handle;
+            this.currentBytes = reopened.size;
+            throw error;
+        }
+    }
+    async writeLine(line) {
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        if (this.currentBytes > 0 && this.currentBytes + lineBytes > this.maxBytes) {
+            await this.rotate();
+        }
+        await this.handle.write(line, undefined, "utf8");
+        this.currentBytes += lineBytes;
+        if (this.syncWrites) {
+            await this.handle.sync();
+        }
+    }
+    write(event) {
+        if (this.closed) {
+            return Promise.reject(new Error("Audit writer is closed."));
+        }
+        const line = `${JSON.stringify(event)}\n`;
+        const next = this.pending.then(() => this.writeLine(line));
+        this.pending = next.catch(() => undefined);
+        return next;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await this.pending;
+        await this.handle.close();
+    }
+}
+async function openAuditFile(logPath) {
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const handle = await open(logPath, constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | noFollow, 0o600);
+    try {
+        const fileStat = await handle.stat();
+        if (!fileStat.isFile()) {
+            throw new Error("Audit log target must be a regular file.");
+        }
+        await handle.chmod(0o600);
+        return { handle, size: fileStat.size };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+export function createJsonlAuditWriter(options) {
+    return JsonlAuditWriter.create(options);
+}

package/dist/auth/sql-profile-loader/env-source.js

@@ -60,6 +60,13 @@ export function parseEnvProfile(env) {
     if (!passwordRef) {
         throw new Error("Missing SQL password in environment. Set TAURUSDB_SQL_PASSWORD or include it in DSN.");
     }
+    const mutationUsername = asString(env.TAURUSDB_SQL_MUTATION_USER);
+    const mutationPasswordRef = Object.hasOwn(env, "TAURUSDB_SQL_MUTATION_PASSWORD")
+        ? parseCredentialRef(env.TAURUSDB_SQL_MUTATION_PASSWORD, "TAURUSDB_SQL_MUTATION_PASSWORD")
+        : undefined;
+    if ((mutationUsername && !mutationPasswordRef) || (!mutationUsername && mutationPasswordRef)) {
+        throw new Error("Mutation credentials require both TAURUSDB_SQL_MUTATION_USER and TAURUSDB_SQL_MUTATION_PASSWORD.");
+    }
     const poolSize = asInteger(env.TAURUSDB_SQL_POOL_SIZE);
     if (poolSize !== undefined && poolSize <= 0) {
         throw new Error("Invalid TAURUSDB_SQL_POOL_SIZE: must be positive.");
@@ -74,6 +81,9 @@ export function parseEnvProfile(env) {
             username,
             password: passwordRef,
         },
+        mutationUser: mutationUsername && mutationPasswordRef
+            ? { username: mutationUsername, password: mutationPasswordRef }
+            : undefined,
         poolSize,
     });
 }

package/dist/auth/sql-profile-loader/parsing.js

@@ -1,4 +1,4 @@
-const CREDENTIAL_URI_PREFIXES = ["aws-sm:", "hw-kms:", "uri:"];
+const CREDENTIAL_URI_PREFIXES = ["aws-sm:", "hw-csms:", "hw-kms:", "hw-kms-file:", "uri:"];
 const SENSITIVE_KEY_PATTERN = /(password|secret|token|credential|apikey|api_key)/i;
 export function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -190,11 +190,13 @@ export function parseProfileRecord(name, value, context) {
         throw new Error(`Invalid datasource profile ${name} in ${context}: port must be positive.`);
     }
     const database = asString(value.database);
+    const instanceId = asString(value.instanceId ?? value.instance_id);
+    const nodeId = asString(value.nodeId ?? value.node_id);
     const poolSize = asInteger(value.poolSize);
     if (poolSize !== undefined && poolSize <= 0) {
         throw new Error(`Invalid datasource profile ${name} in ${context}: poolSize must be positive.`);
     }
-    // Backward compatibility for older profile field names. New configs should use `user`.
+    // `user` is the read-only credential. Keep older read-only aliases for compatibility.
     const userRaw = value.user ??
         value.readonlyUser ??
         value.readonly ??
@@ -203,6 +205,10 @@ export function parseProfileRecord(name, value, context) {
         throw new Error(`Invalid datasource profile ${name} in ${context}: missing user.`);
     }
     const user = parseUserCredential(userRaw, `${context}.${name}.user`);
+    const mutationUserRaw = value.mutationUser ?? value.writeUser ?? value.rwUser;
+    const mutationUser = mutationUserRaw === undefined
+        ? undefined
+        : parseUserCredential(mutationUserRaw, `${context}.${name}.mutationUser`);
     const tls = parseTlsOptions(value.tls, `${context}.${name}.tls`);
     return withRedactedToString({
         name,
@@ -210,7 +216,10 @@ export function parseProfileRecord(name, value, context) {
         host,
         port,
         database,
+        instanceId,
+        nodeId,
         user,
+        mutationUser,
         tls,
         poolSize,
     });

package/dist/auth/sql-profile-loader/runtime-override.js

@@ -8,6 +8,8 @@ export function applyRuntimeTarget(profile, target) {
         host: target.host ?? profile.host,
         port: target.port ?? profile.port,
         database: target.database ?? profile.database,
+        instanceId: target.instanceId ?? profile.instanceId,
+        nodeId: target.nodeId ?? profile.nodeId,
         user: target.user ?? profile.user,
     });
 }
@@ -19,14 +21,19 @@ export class RuntimeOverrideProfileLoader {
     }
     setRuntimeTarget(name, target) {
         const current = this.runtimeTargets.get(name);
+        const targetChanged = (target.host !== undefined && target.host !== current?.host) ||
+            (target.instanceId !== undefined && target.instanceId !== current?.instanceId);
+        const user = target.user ?? (targetChanged ? undefined : current?.user);
         const next = {
             host: target.host ?? current?.host,
             port: target.port ?? current?.port,
             database: target.database ?? current?.database,
-            user: target.user ?? current?.user,
             instanceId: target.instanceId ?? current?.instanceId,
             nodeId: target.nodeId ?? current?.nodeId,
         };
+        if (user) {
+            next.user = user;
+        }
         this.runtimeTargets.set(name, next);
     }
     clearRuntimeUser(name) {
@@ -44,7 +51,8 @@ export class RuntimeOverrideProfileLoader {
         this.runtimeTargets.clear();
     }
     getRuntimeTarget(name) {
-        return this.runtimeTargets.get(name);
+        const target = this.runtimeTargets.get(name);
+        return target ? { ...target } : undefined;
     }
     async load() {
         const loaded = await this.base.load();

package/dist/auth/sql-profile-loader/types.d.ts

@@ -31,7 +31,12 @@ export interface DataSourceProfile {
     host?: string;
     port: number;
     database?: string;
+    instanceId?: string;
+    nodeId?: string;
+    /** Read-only credential used by discovery, diagnostics, and query tools. */
     user?: UserCredential;
+    /** Separate credential required for mutation tools. No fallback is allowed. */
+    mutationUser?: UserCredential;
     tls?: TlsOptions;
     poolSize?: number;
     toString(): string;

package/dist/capability/probe.js

@@ -111,7 +111,9 @@ export class CapabilityProbeImpl {
         this.connectionPool = options.connectionPool;
     }
     async probe(ctx) {
-        const session = await this.connectionPool.acquire(ctx.datasource, "ro");
+        const session = await this.connectionPool.acquire(ctx.datasource, "ro", {
+            database: ctx.database,
+        });
         try {
             const variables = await collectVariables(session);
             const kernelInfo = await detectKernelInfo(session, variables);

package/dist/cloud/auth.d.ts

@@ -9,7 +9,15 @@ export interface HuaweiCloudAuthOptions {
     domainSuffix?: string;
     iamEndpoint?: string;
     language?: "en-us" | "zh-cn";
+    allowedEndpointHosts?: string[];
+    credentialProvider?: HuaweiCloudCredentialProvider;
 }
+export interface HuaweiCloudCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    securityToken?: string;
+}
+export type HuaweiCloudCredentialProvider = () => Promise<HuaweiCloudCredentials>;
 export interface FetchHuaweiCloudOptions {
     url: string;
     method?: string;

package/dist/cloud/auth.js

@@ -1,7 +1,26 @@
 import { createHash, createHmac } from "node:crypto";
+import { createSystemCredentialProvider } from "./keychain.js";
 function readString(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
+function validateHuaweiCloudUrl(url, auth) {
+    if (url.protocol !== "https:") {
+        throw new Error("Huawei Cloud API endpoints must use HTTPS.");
+    }
+    if (url.username || url.password) {
+        throw new Error("Huawei Cloud API endpoints must not contain credentials.");
+    }
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, "");
+    const suffix = (readString(auth.domainSuffix) ?? "myhuaweicloud.com")
+        .toLowerCase()
+        .replace(/^\.+|\.+$/g, "");
+    const explicitHosts = new Set((auth.allowedEndpointHosts ?? []).map((host) => host.toLowerCase().replace(/\.$/, "")));
+    if (hostname !== suffix &&
+        !hostname.endsWith(`.${suffix}`) &&
+        !explicitHosts.has(hostname)) {
+        throw new Error(`Huawei Cloud API endpoint host is not allowed: ${hostname}.`);
+    }
+}
 function sha256Hex(value) {
     return createHash("sha256").update(value, "utf8").digest("hex");
 }
@@ -87,6 +106,7 @@ export async function fetchHuaweiCloud(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const method = options.method ?? "GET";
     const url = new URL(options.url);
+    validateHuaweiCloudUrl(url, options.auth);
     const body = options.body ?? "";
     const authToken = readString(options.auth.authToken);
     const headers = new Headers(options.headers);
@@ -98,9 +118,21 @@ export async function fetchHuaweiCloud(options) {
             body: options.body,
         });
     }
-    const { accessKeyId, secretAccessKey } = requireAksk(options.auth);
+    const providerCredentials = (!readString(options.auth.accessKeyId) ||
+        !readString(options.auth.secretAccessKey)) &&
+        options.auth.credentialProvider
+        ? await options.auth.credentialProvider()
+        : undefined;
+    const resolvedAuth = {
+        ...options.auth,
+        accessKeyId: readString(options.auth.accessKeyId) ?? providerCredentials?.accessKeyId,
+        secretAccessKey: readString(options.auth.secretAccessKey) ??
+            providerCredentials?.secretAccessKey,
+        securityToken: readString(options.auth.securityToken) ?? providerCredentials?.securityToken,
+    };
+    const { accessKeyId, secretAccessKey } = requireAksk(resolvedAuth);
     const sdkDate = formatSdkDate(new Date());
-    const headerMap = buildHeaderMap(headers, url, sdkDate, readString(options.auth.securityToken));
+    const headerMap = buildHeaderMap(headers, url, sdkDate, readString(resolvedAuth.securityToken));
     headerMap.set("authorization", buildAuthorization(method, url, headerMap, body, accessKeyId, secretAccessKey));
     return fetchImpl(url, {
         method,
@@ -169,6 +201,12 @@ export async function resolveHuaweiCloudProjectId(auth, fetchImpl) {
     throw new Error(`Unable to resolve project id for region ${region}. Set TAURUSDB_CLOUD_PROJECT_ID explicitly or restrict the account to a single visible project in that region.`);
 }
 export function getHuaweiCloudAuthFromConfig(config) {
+    const credentialProvider = config.cloud?.keychainService
+        ? createSystemCredentialProvider({
+            service: config.cloud.keychainService,
+            account: config.cloud.keychainAccount,
+        })
+        : undefined;
     return {
         region: config.cloud?.region,
         projectId: config.cloud?.projectId,
@@ -179,10 +217,30 @@ export function getHuaweiCloudAuthFromConfig(config) {
         domainSuffix: config.cloud?.domainSuffix,
         iamEndpoint: config.cloud?.iamEndpoint,
         language: config.cloud?.language,
+        allowedEndpointHosts: [
+            config.cloud?.apiEndpoint,
+            config.cloud?.iamEndpoint,
+            config.cloud?.kmsEndpoint,
+            config.cloud?.csmsEndpoint,
+            config.slowSqlSource?.taurusApi?.endpoint,
+            config.slowSqlSource?.das?.endpoint,
+            config.metricsSource?.ces?.endpoint,
+        ]
+            .filter((value) => Boolean(value))
+            .flatMap((value) => {
+            try {
+                return [new URL(value).hostname];
+            }
+            catch {
+                return [];
+            }
+        }),
+        credentialProvider,
     };
 }
 export function hasHuaweiCloudCredentialAuth(config) {
-    return canAuthenticateHuaweiCloudRequests(getHuaweiCloudAuthFromConfig(config));
+    return Boolean(config.cloud?.keychainService ||
+        canAuthenticateHuaweiCloudRequests(getHuaweiCloudAuthFromConfig(config)));
 }
 export function inferHuaweiCloudRegionFromEndpoint(endpoint) {
     const normalized = readString(endpoint);

package/dist/cloud/csms.d.ts

@@ -0,0 +1,7 @@
+import type { UriSecretResolver } from "../auth/secret-resolver.js";
+import type { Config } from "../config/index.js";
+export type HuaweiCsmsSecretResolverOptions = {
+    config: Config;
+    fetchImpl?: typeof fetch;
+};
+export declare function createHuaweiCsmsSecretResolver(options: HuaweiCsmsSecretResolverOptions): UriSecretResolver;

package/dist/cloud/csms.js

@@ -0,0 +1,60 @@
+import { fetchHuaweiCloud, getHuaweiCloudAuthFromConfig, resolveHuaweiCloudProjectId, } from "./auth.js";
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function readSecretName(uri) {
+    if (!uri.startsWith("hw-csms:")) {
+        throw new Error(`Unsupported Huawei CSMS credential reference: ${uri}`);
+    }
+    const secretName = decodeURIComponent(uri.slice("hw-csms:".length).trim());
+    if (!secretName) {
+        throw new Error("Huawei CSMS credential reference is missing a secret name.");
+    }
+    return secretName;
+}
+function parseSecretString(payload) {
+    const record = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : {};
+    const version = record.version && typeof record.version === "object" && !Array.isArray(record.version)
+        ? record.version
+        : {};
+    const secretString = readString(version.secret_string);
+    if (!secretString) {
+        throw new Error("Huawei CSMS response did not include version.secret_string.");
+    }
+    return secretString;
+}
+export function createHuaweiCsmsSecretResolver(options) {
+    const auth = getHuaweiCloudAuthFromConfig(options.config);
+    const endpoint = options.config.cloud.csmsEndpoint?.replace(/\/+$/g, "");
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return async (uri) => {
+        if (!endpoint) {
+            throw new Error("Huawei CSMS endpoint is not configured. Set TAURUSDB_CLOUD_REGION or TAURUSDB_CLOUD_CSMS_ENDPOINT.");
+        }
+        const [secretName, projectId] = await Promise.all([
+            Promise.resolve(readSecretName(uri)),
+            resolveHuaweiCloudProjectId(auth, fetchImpl),
+        ]);
+        if (!projectId) {
+            throw new Error("Huawei CSMS request could not resolve a project id. Set TAURUSDB_CLOUD_PROJECT_ID or configure region plus Huawei Cloud credentials.");
+        }
+        const response = await fetchHuaweiCloud({
+            url: `${endpoint}/v1/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent(secretName)}/versions/latest`,
+            headers: { "content-type": "application/json" },
+            auth,
+            fetchImpl,
+        });
+        const payload = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            const record = payload && typeof payload === "object" && !Array.isArray(payload)
+                ? payload
+                : {};
+            const code = readString(record.error_code) ?? readString(record.code);
+            const message = readString(record.error_msg) ?? readString(record.message);
+            throw new Error(`Huawei CSMS request failed with status ${response.status}${code ? ` (${code})` : ""}${message ? `: ${message}` : ""}.`);
+        }
+        return parseSecretString(payload);
+    };
+}

package/dist/cloud/keychain.d.ts

@@ -0,0 +1,28 @@
+import type { HuaweiCloudCredentialProvider } from "./auth.js";
+export type MacOsKeychainCredentialProviderOptions = {
+    service: string;
+    account?: string;
+    platform?: NodeJS.Platform;
+    readPassword?: (service: string, account: string) => Promise<string | undefined>;
+};
+export type LinuxSecretServiceCredentialProviderOptions = {
+    service: string;
+    account?: string;
+    platform?: NodeJS.Platform;
+    readPassword?: (service: string, account: string, key: string) => Promise<string | undefined>;
+};
+export type WindowsCredentialManagerProviderOptions = {
+    service: string;
+    account?: string;
+    platform?: NodeJS.Platform;
+    readPassword?: (service: string, account: string, key: string) => Promise<string | undefined>;
+};
+export type SystemCredentialProviderOptions = {
+    service: string;
+    account?: string;
+    platform?: NodeJS.Platform;
+};
+export declare function createMacOsKeychainCredentialProvider(options: MacOsKeychainCredentialProviderOptions): HuaweiCloudCredentialProvider;
+export declare function createLinuxSecretServiceCredentialProvider(options: LinuxSecretServiceCredentialProviderOptions): HuaweiCloudCredentialProvider;
+export declare function createWindowsCredentialManagerProvider(options: WindowsCredentialManagerProviderOptions): HuaweiCloudCredentialProvider;
+export declare function createSystemCredentialProvider(options: SystemCredentialProviderOptions): HuaweiCloudCredentialProvider;