taurusdb-mcp 0.5.0-rc.3 → 0.5.0-rc.4

package/README.md

@@ -10,7 +10,7 @@ TaurusDB MCP server for MCP clients such as:
 ## Install
 
 ```bash
-npm install taurusdb-mcp
+npm install taurusdb-mcp@latest
 ```
 
 Run directly with:
@@ -46,9 +46,6 @@ claude mcp add huaweicloud-taurusdb \
   -e TAURUSDB_CLOUD_REGION=<your-region> \
   -e TAURUSDB_CLOUD_KEYCHAIN_SERVICE=taurusdb-mcp/huaweicloud \
   -e TAURUSDB_ENABLE_DYNAMIC_TARGETS=true \
-  -e TAURUSDB_SQL_DATABASE=<your-database> \
-  -e TAURUSDB_SQL_USER=<your-readonly-user> \
-  -e TAURUSDB_SQL_PASSWORD='hw-kms-file:~/.taurusdb-mcp/password.ciphertext' \
   -- npx -y taurusdb-mcp
 ```
 
@@ -59,12 +56,19 @@ codex mcp add huaweicloud-taurusdb \
   --env TAURUSDB_CLOUD_REGION=<your-region> \
   --env TAURUSDB_CLOUD_KEYCHAIN_SERVICE=taurusdb-mcp/huaweicloud \
   --env TAURUSDB_ENABLE_DYNAMIC_TARGETS=true \
-  --env TAURUSDB_SQL_DATABASE=<your-database> \
-  --env TAURUSDB_SQL_USER=<your-readonly-user> \
-  --env TAURUSDB_SQL_PASSWORD='hw-kms-file:~/.taurusdb-mcp/password.ciphertext' \
   -- npx -y taurusdb-mcp
 ```
 
+Interactive connection flow:
+
+1. Call `list_cloud_taurus_instances`.
+2. Call `select_cloud_taurus_instance`.
+3. Open the returned `login_url` in a browser and enter the database credentials.
+4. Continue with `list_databases`, `set_default_database`, and readonly tools.
+
+The browser submits credentials directly to the loopback MCP process. They are not
+sent through Agent-visible tool arguments or persisted by MCP.
+
 Initialize local MCP client config:
 
 ```bash
@@ -84,18 +88,20 @@ npx taurusdb-mcp credentials check
 
 - Requires Node.js `>= 20`
 - Depends on `taurusdb-core`
-- Database passwords support `env:`, `file:`, `hw-csms:`, `hw-kms:`, and `hw-kms-file:` references
-- Huawei DEW CSMS is recommended when the database password should be stored and retrieved from Huawei Cloud
+- Interactive clients do not need database usernames or passwords in MCP configuration
+- Unattended static deployments may use `env:`, `file:`, `hw-csms:`, `hw-kms:`, or `hw-kms-file:` password references
 - macOS Keychain, Linux Secret Service, or Windows Credential Manager cloud identity is enabled with `TAURUSDB_CLOUD_KEYCHAIN_SERVICE`
 - SQL TLS with certificate verification is required by default
-- Database mutation tools do not exist; the MCP remains read-only regardless of database account privileges
+- General database mutation tools do not exist; the Agent-facing operating plane remains read-only regardless of database account privileges
+- Recycle-bin request/status tools are visible by default: `prepare_recycle_bin_restore` performs readonly preflight and the loopback-only operator page requires the Agent-invisible HttpOnly browser session established by database login before executing one target-bound native restore with the active in-memory SQL session; no secret file, direct restore tool, or Agent-held execution token is required
 - `analyze_mutation_sql` returns evidence-backed SQL Advice with `execution_status: not_executed`
-- Local SQL login validates the connection before binding credentials, allows at most three attempts per five-minute link, and never sends the password through Agent-visible tool arguments
+- Selecting a cloud instance returns a local SQL login link immediately; login validates the connection before binding credentials, allows at most three attempts per five-minute link, and never sends the password through Agent-visible tool arguments
 - Session SQL credentials expire after 30 idle minutes and eight absolute hours; administrators may shorten these limits with `TAURUSDB_SQL_CREDENTIAL_IDLE_TTL_MINUTES` and `TAURUSDB_SQL_CREDENTIAL_MAX_TTL_MINUTES`
 - MCP audit events are written to `~/.taurusdb-mcp/audit.jsonl` by default, with
   configurable size rotation for collection into centralized immutable storage
 - Run one stdio process per customer/client trust boundary; this package is not
   a shared multi-tenant HTTP service
 
-Customers execute reviewed `advised_sql` through their own controlled change process;
-the MCP never executes database state changes.
+Customers execute reviewed general-purpose `advised_sql` through their own controlled
+change process. The only MCP database-state exception is the target-bound,
+same-browser-confirmed recycle-bin recovery described above.

package/dist/security/browser-operator-session.d.ts

@@ -0,0 +1,14 @@
+export declare class BrowserOperatorSessionStore {
+    private readonly now;
+    private readonly cookieName;
+    private readonly sessions;
+    constructor(options?: {
+        now?: () => number;
+    });
+    issue(datasource: string, ttlMs?: number): string;
+    authorizes(cookieHeader: string | undefined, datasource: string): boolean;
+    clear(): void;
+    revokeDatasource(datasource: string): void;
+    private readCookie;
+    private expire;
+}

package/dist/security/browser-operator-session.js

@@ -0,0 +1,57 @@
+import { randomBytes } from "node:crypto";
+const DEFAULT_TTL_MS = 8 * 60 * 60 * 1000;
+export class BrowserOperatorSessionStore {
+    now;
+    cookieName;
+    sessions = new Map();
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.cookieName = `taurusdb_mcp_operator_${randomBytes(8).toString("hex")}`;
+    }
+    issue(datasource, ttlMs = DEFAULT_TTL_MS) {
+        this.expire();
+        const token = randomBytes(32).toString("base64url");
+        const boundedTtlMs = Math.max(1, Math.min(ttlMs, DEFAULT_TTL_MS));
+        this.sessions.set(token, {
+            datasource,
+            expiresAtMs: this.now() + boundedTtlMs,
+        });
+        return `${this.cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${Math.ceil(boundedTtlMs / 1000)}`;
+    }
+    authorizes(cookieHeader, datasource) {
+        this.expire();
+        const token = this.readCookie(cookieHeader);
+        const session = token ? this.sessions.get(token) : undefined;
+        return session?.datasource === datasource;
+    }
+    clear() {
+        this.sessions.clear();
+    }
+    revokeDatasource(datasource) {
+        for (const [token, session] of this.sessions) {
+            if (session.datasource === datasource)
+                this.sessions.delete(token);
+        }
+    }
+    readCookie(cookieHeader) {
+        if (!cookieHeader)
+            return undefined;
+        for (const part of cookieHeader.split(";")) {
+            const separator = part.indexOf("=");
+            if (separator < 0)
+                continue;
+            const name = part.slice(0, separator).trim();
+            if (name === this.cookieName) {
+                return part.slice(separator + 1).trim() || undefined;
+            }
+        }
+        return undefined;
+    }
+    expire() {
+        const now = this.now();
+        for (const [token, session] of this.sessions) {
+            if (session.expiresAtMs <= now)
+                this.sessions.delete(token);
+        }
+    }
+}

package/dist/security/local-credential-login.d.ts

@@ -1,3 +1,4 @@
+import { BrowserOperatorSessionStore } from "./browser-operator-session.js";
 export type SqlLoginCredentials = {
     datasource: string;
     username: string;
@@ -33,12 +34,14 @@ export type LocalCredentialLoginServiceOptions = {
     tokenTtlMs?: number;
     maxAttempts?: number;
     failureDelayMs?: number;
+    operatorSessions?: BrowserOperatorSessionStore;
 };
 export declare class LocalCredentialLoginService implements CredentialLoginService {
     private readonly now;
     private readonly tokenTtlMs;
     private readonly maxAttempts;
     private readonly failureDelayMs;
+    private readonly operatorSessions?;
     private readonly pending;
     private server;
     private port;

package/dist/security/local-credential-login.js

@@ -266,6 +266,7 @@ export class LocalCredentialLoginService {
     tokenTtlMs;
     maxAttempts;
     failureDelayMs;
+    operatorSessions;
     pending = new Map();
     server;
     port;
@@ -274,6 +275,7 @@ export class LocalCredentialLoginService {
         this.tokenTtlMs = options.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS;
         this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
         this.failureDelayMs = options.failureDelayMs ?? DEFAULT_FAILURE_DELAY_MS;
+        this.operatorSessions = options.operatorSessions;
     }
     async issueSqlLogin(request) {
         await this.ensureStarted();
@@ -287,6 +289,7 @@ export class LocalCredentialLoginService {
     }
     async close() {
         this.pending.clear();
+        this.operatorSessions?.clear();
         const server = this.server;
         this.server = undefined;
         this.port = undefined;
@@ -402,6 +405,11 @@ export class LocalCredentialLoginService {
                 return;
             }
             this.pending.delete(token);
+            const maxTtlMinutes = Math.min(pending.target?.credentialIdleTtlMinutes ?? 30, pending.target?.credentialMaxTtlMinutes ?? 480);
+            const operatorCookie = this.operatorSessions?.issue(pending.datasource, maxTtlMinutes * 60_000);
+            if (operatorCookie) {
+                res.setHeader("set-cookie", operatorCookie);
+            }
             respond(res, 200, page({ locale, state: "success", target: pending.target }));
         }
         catch {

package/dist/security/local-recovery-approval.d.ts

@@ -0,0 +1,62 @@
+import { BrowserOperatorSessionStore } from "./browser-operator-session.js";
+export type RecoveryTarget = {
+    datasource: string;
+    recycleTable: string;
+    destinationDatabase: string;
+    destinationTable: string;
+};
+export type RecoveryExecutionResult = {
+    queryId: string;
+    affectedRows: number;
+    verified: boolean;
+};
+export type RecoveryRequestStatus = {
+    requestId: string;
+    status: "pending" | "executing" | "succeeded" | "failed" | "expired";
+    target: RecoveryTarget;
+    createdAt: string;
+    expiresAt: string;
+    operator?: string;
+    completedAt?: string;
+    result?: RecoveryExecutionResult;
+    error?: string;
+};
+export type RecoveryApprovalRequest = {
+    target: RecoveryTarget;
+    execute: (operator: string, requestId: string) => Promise<RecoveryExecutionResult>;
+};
+export type IssuedRecoveryApproval = {
+    requestId: string;
+    approvalUrl: string;
+    expiresAt: string;
+};
+export interface RecoveryApprovalService {
+    issue(request: RecoveryApprovalRequest): Promise<IssuedRecoveryApproval>;
+    getStatus(requestId: string): RecoveryRequestStatus | undefined;
+    close(): Promise<void>;
+}
+export type LocalRecoveryApprovalServiceOptions = {
+    operatorSessions: BrowserOperatorSessionStore;
+    now?: () => number;
+    ttlMs?: number;
+    maxPending?: number;
+    maxAttempts?: number;
+};
+export declare class LocalRecoveryApprovalService implements RecoveryApprovalService {
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxPending;
+    private readonly maxAttempts;
+    private readonly operatorSessions;
+    private readonly byToken;
+    private readonly byRequestId;
+    private server?;
+    private port?;
+    constructor(options: LocalRecoveryApprovalServiceOptions);
+    issue(request: RecoveryApprovalRequest): Promise<IssuedRecoveryApproval>;
+    getStatus(requestId: string): RecoveryRequestStatus | undefined;
+    close(): Promise<void>;
+    private expirePending;
+    private ensureStarted;
+    private handle;
+}

package/dist/security/local-recovery-approval.js

@@ -0,0 +1,258 @@
+import { randomBytes } from "node:crypto";
+import { createServer, } from "node:http";
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_PENDING = 100;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const MAX_REQUEST_BODY_BYTES = 8 * 1024;
+function localeFromRequest(req) {
+    return /(?:^|,)\s*zh(?:-|_|;|,|$)/i.test(req.headers["accept-language"] ?? "")
+        ? "zh-CN"
+        : "en";
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function confirmationText(target) {
+    return `RESTORE ${target.destinationDatabase}.${target.destinationTable}`;
+}
+function page(input) {
+    const zh = input.locale === "zh-CN";
+    const target = input.target;
+    const title = input.state === "confirm"
+        ? (zh ? "确认回收站恢复" : "Confirm recycle-bin recovery")
+        : input.state === "success"
+            ? (zh ? "恢复已完成" : "Recovery completed")
+            : input.state === "failed"
+                ? (zh ? "恢复失败" : "Recovery failed")
+                : input.state === "expired"
+                    ? (zh ? "恢复申请已失效" : "Recovery request expired")
+                    : (zh ? "无法处理申请" : "Request could not be processed");
+    const message = input.message ?? (input.state === "confirm"
+        ? (zh
+            ? "请核对目标并输入操作人身份和确认短语。确认后将立即执行，无法由 Agent 撤销。"
+            : "Review the target, then enter the operator identity and confirmation phrase. Approval executes immediately and cannot be revoked by the Agent.")
+        : input.state === "success"
+            ? (zh ? "目标表已经恢复并通过只读验证，可以返回 MCP 会话。" : "The table was restored and verified. Return to the MCP session.")
+            : input.state === "expired"
+                ? (zh ? "请返回 MCP 会话重新创建恢复申请。" : "Return to the MCP session and create a new recovery request.")
+                : (zh ? "请返回 MCP 会话查看恢复状态。" : "Return to the MCP session to inspect recovery status."));
+    const phrase = target ? confirmationText(target) : "";
+    const body = input.state === "confirm" && target
+        ? `<form method="post" autocomplete="off">
+        <label>${zh ? "操作人身份" : "Operator identity"}</label>
+        <input name="operator" maxlength="256" required placeholder="name@example.com">
+        <label>${zh ? "确认短语" : "Confirmation phrase"}</label>
+        <code>${escapeHtml(phrase)}</code>
+        <input name="confirmation" maxlength="512" required autocomplete="off">
+        <button type="submit">${zh ? "确认并立即恢复" : "Approve and restore now"}</button>
+      </form>`
+        : `<section class="result"><span>${input.state === "success" ? "✓" : "!"}</span><p>${escapeHtml(message)}</p></section>`;
+    return `<!doctype html><html lang="${input.locale}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)} · TaurusDB MCP</title><style>
+    :root{color-scheme:light;--ink:#172033;--muted:#647184;--bg:#f3f6fa;--line:#dce3eb;--danger:#b42318;--teal:#087f73}*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:var(--bg);color:var(--ink);font-family:Inter,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}.panel{width:min(720px,calc(100% - 32px));background:#fff;border:1px solid var(--line);border-radius:22px;padding:40px;box-shadow:0 22px 60px rgba(23,32,51,.12)}.brand{font-weight:760;color:var(--teal)}h1{font-size:32px;margin:18px 0 10px}p{color:var(--muted);line-height:1.65}.warning{padding:14px 16px;border-radius:12px;background:#fff0ee;color:var(--danger);font-weight:650}.grid{display:grid;grid-template-columns:160px 1fr;gap:10px;margin:24px 0;padding:18px;background:#f8fafc;border-radius:14px}.grid b{color:var(--muted)}label{display:block;margin:18px 0 7px;font-weight:700}input{width:100%;padding:13px;border:1px solid #bdc8d5;border-radius:10px;font:inherit}code{display:block;padding:12px;border-radius:9px;background:#eef3f7;font-weight:700}button{width:100%;margin-top:24px;padding:14px;border:0;border-radius:10px;background:var(--danger);color:#fff;font:inherit;font-weight:760;cursor:pointer}.result span{display:inline-grid;place-items:center;width:44px;height:44px;border-radius:50%;background:#e7f5f2;color:var(--teal);font-size:24px;font-weight:800}@media(max-width:600px){.panel{padding:26px}.grid{grid-template-columns:1fr}h1{font-size:27px}}</style></head><body><main class="panel"><div class="brand">TaurusDB MCP · Controlled Recovery</div><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p>${target ? `<div class="warning">${zh ? "此操作会改变数据库状态，是只读 Harness 的唯一受控例外。" : "This changes database state and is the only controlled exception to the read-only Harness."}</div><div class="grid"><b>Datasource</b><span>${escapeHtml(target.datasource)}</span><b>${zh ? "回收站对象" : "Recycle object"}</b><span>${escapeHtml(target.recycleTable)}</span><b>${zh ? "恢复目标" : "Destination"}</b><span>${escapeHtml(`${target.destinationDatabase}.${target.destinationTable}`)}</span></div>` : ""}${body}</main></body></html>`;
+}
+function respond(res, status, body) {
+    res.writeHead(status, {
+        "cache-control": "no-store",
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+        "content-type": "text/html; charset=utf-8",
+        "cross-origin-opener-policy": "same-origin",
+        "cross-origin-resource-policy": "same-origin",
+        "permissions-policy": "camera=(), microphone=(), geolocation=()",
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "DENY",
+    });
+    res.end(body);
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_REQUEST_BODY_BYTES)
+            throw new Error("Request body too large.");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export class LocalRecoveryApprovalService {
+    now;
+    ttlMs;
+    maxPending;
+    maxAttempts;
+    operatorSessions;
+    byToken = new Map();
+    byRequestId = new Map();
+    server;
+    port;
+    constructor(options) {
+        this.operatorSessions = options.operatorSessions;
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+        this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    async issue(request) {
+        this.expirePending();
+        if (this.byToken.size >= this.maxPending)
+            throw new Error("Too many pending recovery requests.");
+        await this.ensureStarted();
+        const token = randomBytes(32).toString("base64url");
+        const requestId = `rrq_${randomBytes(16).toString("base64url")}`;
+        const createdAtMs = this.now();
+        const expiresAtMs = createdAtMs + this.ttlMs;
+        const status = {
+            requestId,
+            status: "pending",
+            target: { ...request.target },
+            createdAt: new Date(createdAtMs).toISOString(),
+            expiresAt: new Date(expiresAtMs).toISOString(),
+        };
+        const pending = { token, request, status, failedAttempts: 0 };
+        this.byToken.set(token, pending);
+        this.byRequestId.set(requestId, status);
+        return {
+            requestId,
+            approvalUrl: `http://127.0.0.1:${this.port}/recovery/${token}`,
+            expiresAt: status.expiresAt,
+        };
+    }
+    getStatus(requestId) {
+        this.expirePending();
+        const status = this.byRequestId.get(requestId);
+        return status ? structuredClone(status) : undefined;
+    }
+    async close() {
+        this.byToken.clear();
+        this.byRequestId.clear();
+        const server = this.server;
+        this.server = undefined;
+        this.port = undefined;
+        if (!server)
+            return;
+        await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+    }
+    expirePending() {
+        const now = this.now();
+        for (const [token, pending] of this.byToken) {
+            if (Date.parse(pending.status.expiresAt) <= now) {
+                pending.status.status = "expired";
+                pending.status.completedAt = new Date(now).toISOString();
+                this.byToken.delete(token);
+            }
+        }
+    }
+    async ensureStarted() {
+        if (this.server)
+            return;
+        const server = createServer((req, res) => void this.handle(req, res));
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+        });
+        const address = server.address();
+        if (!address || typeof address === "string") {
+            await new Promise((resolve) => server.close(() => resolve()));
+            throw new Error("Unable to resolve local recovery approval address.");
+        }
+        this.server = server;
+        this.port = address.port;
+    }
+    async handle(req, res) {
+        const locale = localeFromRequest(req);
+        try {
+            this.expirePending();
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const token = url.pathname.match(/^\/recovery\/([^/]+)$/)?.[1];
+            const pending = token ? this.byToken.get(token) : undefined;
+            if (!token || !pending) {
+                respond(res, 410, page({ locale, state: "expired" }));
+                return;
+            }
+            const cookieHeader = Array.isArray(req.headers.cookie)
+                ? req.headers.cookie.join("; ")
+                : req.headers.cookie;
+            const browserAuthorized = this.operatorSessions.authorizes(cookieHeader, pending.request.target.datasource);
+            if (req.method === "GET") {
+                respond(res, browserAuthorized ? 200 : 401, browserAuthorized
+                    ? page({ locale, state: "confirm", target: pending.request.target })
+                    : page({
+                        locale,
+                        state: "invalid",
+                        target: pending.request.target,
+                        message: locale === "zh-CN"
+                            ? "请先在同一浏览器中完成该数据源的数据库登录，再确认恢复。"
+                            : "Complete database login for this datasource in the same browser before approving recovery.",
+                    }));
+                return;
+            }
+            if (req.method !== "POST") {
+                respond(res, 405, page({ locale, state: "invalid", target: pending.request.target }));
+                return;
+            }
+            const origin = req.headers.origin;
+            if (origin && origin !== `http://${req.headers.host}`) {
+                respond(res, 403, page({ locale, state: "invalid", target: pending.request.target }));
+                return;
+            }
+            if (!browserAuthorized) {
+                respond(res, 401, page({
+                    locale,
+                    state: "invalid",
+                    target: pending.request.target,
+                    message: locale === "zh-CN"
+                        ? "请先在同一浏览器中完成该数据源的数据库登录，再确认恢复。"
+                        : "Complete database login for this datasource in the same browser before approving recovery.",
+                }));
+                return;
+            }
+            const form = new URLSearchParams(await readBody(req));
+            const operator = form.get("operator")?.trim() ?? "";
+            const confirmation = form.get("confirmation") ?? "";
+            if (!operator || confirmation !== confirmationText(pending.request.target)) {
+                pending.failedAttempts += 1;
+                if (pending.failedAttempts >= this.maxAttempts) {
+                    this.byToken.delete(token);
+                    pending.status.status = "failed";
+                    pending.status.error = "Recovery approval attempt limit reached. Create a new request.";
+                    pending.status.completedAt = new Date(this.now()).toISOString();
+                    respond(res, 429, page({ locale, state: "failed", target: pending.request.target }));
+                    return;
+                }
+                respond(res, 400, page({
+                    locale,
+                    state: "confirm",
+                    target: pending.request.target,
+                    message: locale === "zh-CN" ? "操作人身份或确认短语不正确，未执行恢复。" : "Operator identity or confirmation phrase is invalid. Recovery was not executed.",
+                }));
+                return;
+            }
+            this.byToken.delete(token);
+            pending.status.status = "executing";
+            pending.status.operator = operator;
+            try {
+                const result = await pending.request.execute(operator, pending.status.requestId);
+                pending.status.status = "succeeded";
+                pending.status.result = result;
+                pending.status.completedAt = new Date(this.now()).toISOString();
+                respond(res, 200, page({ locale, state: "success", target: pending.request.target }));
+            }
+            catch (error) {
+                pending.status.status = "failed";
+                void error;
+                pending.status.error = "Recovery failed. Inspect the MCP audit log and database state before retrying.";
+                pending.status.completedAt = new Date(this.now()).toISOString();
+                respond(res, 500, page({ locale, state: "failed", target: pending.request.target }));
+            }
+        }
+        catch {
+            respond(res, 400, page({ locale, state: "invalid" }));
+        }
+    }
+}

package/dist/server.d.ts

@@ -3,11 +3,15 @@ import { TaurusDBEngine, type Config, type AuditWriter, type RuntimeTargetProfil
 import { type CredentialLoginService } from "./security/local-credential-login.js";
 import { SessionCoordinator } from "./security/session-coordinator.js";
 import { SessionCredentialManager } from "./security/session-credential-manager.js";
+import { type RecoveryApprovalService } from "./security/local-recovery-approval.js";
+import { BrowserOperatorSessionStore } from "./security/browser-operator-session.js";
 export interface ServerDeps {
     config: Config;
     profileLoader: RuntimeTargetProfileLoader;
     engine: TaurusDBEngine;
     credentialLogin: CredentialLoginService;
+    operatorSessions?: BrowserOperatorSessionStore;
+    recoveryApproval?: RecoveryApprovalService;
     auditWriter?: AuditWriter;
     sessionCoordinator?: SessionCoordinator;
     credentialSessions?: SessionCredentialManager;

package/dist/server.js

@@ -7,8 +7,11 @@ import { VERSION } from "./version.js";
 import { LocalCredentialLoginService, } from "./security/local-credential-login.js";
 import { SessionCoordinator } from "./security/session-coordinator.js";
 import { SessionCredentialManager } from "./security/session-credential-manager.js";
+import { LocalRecoveryApprovalService, } from "./security/local-recovery-approval.js";
+import { BrowserOperatorSessionStore } from "./security/browser-operator-session.js";
 export async function bootstrapDependencies() {
     const config = getConfig();
+    const operatorSessions = new BrowserOperatorSessionStore();
     const profileLoader = new RuntimeOverrideProfileLoader(createSqlProfileLoader({ config }));
     const engine = await TaurusDBEngine.create({ config, profileLoader });
     const auditWriter = await createJsonlAuditWriter({
@@ -28,7 +31,14 @@ export async function bootstrapDependencies() {
         config,
         profileLoader,
         engine,
-        credentialLogin: new LocalCredentialLoginService(),
+        credentialLogin: new LocalCredentialLoginService({ operatorSessions }),
+        operatorSessions,
+        recoveryApproval: config.security.recycleBinRestoreEnabled
+            ? new LocalRecoveryApprovalService({
+                operatorSessions,
+                ttlMs: config.security.approvalTtlSeconds * 1000,
+            })
+            : undefined,
         auditWriter,
         sessionCoordinator,
         credentialSessions,
@@ -45,6 +55,7 @@ export function createServer(deps) {
     const cleanup = () => {
         cleanupPromise ??= Promise.all([
             deps.credentialLogin.close(),
+            deps.recoveryApproval?.close() ?? Promise.resolve(),
             deps.credentialSessions?.close() ?? Promise.resolve(),
             deps.engine.close(),
             deps.auditWriter?.close() ?? Promise.resolve(),

package/dist/tools/registry.d.ts

@@ -19,4 +19,5 @@ export declare const commonToolDefinitions: ToolDefinition[];
 export declare const capabilityToolDefinitions: ToolDefinition[];
 export declare const dynamicTargetToolDefinitions: ToolDefinition[];
 export declare const taurusToolDefinitions: ToolDefinition[];
+export declare const controlledRecoveryToolDefinitions: ToolDefinition[];
 export declare function registerTools(server: McpServer, deps: ToolDeps, config: Config, tools?: ToolDefinition[]): void;

package/dist/tools/registry.js

@@ -11,7 +11,7 @@ import { listCloudTaurusInstancesTool } from "./taurus/cloud-instances.js";
 import { diagnosticToolDefinitions } from "./taurus/diagnostics.js";
 import { explainSqlEnhancedTool } from "./taurus/explain.js";
 import { flashbackQueryTool } from "./taurus/flashback.js";
-import { listRecycleBinTool } from "./taurus/recycle-bin.js";
+import { getRecycleBinRestoreStatusTool, listRecycleBinTool, prepareRecycleBinRestoreTool, } from "./taurus/recycle-bin.js";
 import { ErrorCode, formatError, toMcpToolResult, } from "../utils/formatter.js";
 function formatUnhandledToolError(error, taskId) {
     void error;
@@ -133,6 +133,7 @@ const SQL_CREDENTIAL_ACTIVITY_TOOLS = new Set([
     "explain_sql_enhanced",
     "flashback_query",
     "list_recycle_bin",
+    "prepare_recycle_bin_restore",
     ...diagnosticToolDefinitions.map((tool) => tool.name),
 ]);
 const TOOL_OUTPUT_SHAPE = {
@@ -220,6 +221,10 @@ export const taurusToolDefinitions = [
     flashbackQueryTool,
     listRecycleBinTool,
 ];
+export const controlledRecoveryToolDefinitions = [
+    prepareRecycleBinRestoreTool,
+    getRecycleBinRestoreStatusTool,
+];
 function buildDefaultToolDefinitions(config) {
     return [
         ...commonToolDefinitions,
@@ -227,6 +232,9 @@ function buildDefaultToolDefinitions(config) {
         ...(config.security.dynamicTargetsEnabled ? dynamicTargetToolDefinitions : []),
         ...diagnosticToolDefinitions,
         ...taurusToolDefinitions,
+        ...(config.security.recycleBinRestoreEnabled
+            ? controlledRecoveryToolDefinitions
+            : []),
     ];
 }
 export function registerTools(server, deps, config, tools = buildDefaultToolDefinitions(config)) {

package/dist/tools/taurus/cloud-context.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { formatSuccess } from "../../utils/formatter.js";
 import { formatToolError, ToolInputError } from "../error-handling.js";
 import { metadata } from "../common.js";
+import { issueSqlLoginForDatasource } from "./sql-login.js";
 function buildHuaweiCloudEndpoint(service, region, domainSuffix) {
     return `https://${service}.${region}.${domainSuffix}`;
 }
@@ -109,6 +110,7 @@ export const setCloudRegionTool = {
                 clearCloudSelection(nextConfig, deps);
             });
             deps.credentialSessions?.clearAll();
+            deps.operatorSessions?.clear();
             return formatSuccess({
                 region,
                 api_endpoint: deps.config.cloud.apiEndpoint,
@@ -222,6 +224,7 @@ export const clearSqlCredentialsTool = {
                 deps.profileLoader.clearRuntimeUser(datasource);
             });
             deps.credentialSessions?.clear(datasource);
+            deps.operatorSessions?.revokeDatasource(datasource);
             return formatSuccess({
                 datasource,
             }, {
@@ -320,6 +323,12 @@ export const selectCloudTaurusInstanceTool = {
             const boundDatasource = await resolveBindingDatasource(deps, typeof input.datasource === "string" ? input.datasource : undefined);
             const selectedHost = selectInstanceAddress(matched);
             const selectedPort = normalizePort(matched.port);
+            if (!boundDatasource) {
+                throw new ToolInputError("No datasource template is available for SQL login. Configure TAURUSDB_DEFAULT_DATASOURCE or pass datasource explicitly.");
+            }
+            if (!selectedHost) {
+                throw new ToolInputError(`Cloud instance ${matched.id} does not expose a database address that can be bound for SQL login.`);
+            }
             await updateSessionState(deps, (nextConfig) => {
                 nextConfig.cloud.projectId = projectId;
                 nextConfig.cloud.instanceId = matched.id;
@@ -332,18 +341,16 @@ export const selectCloudTaurusInstanceTool = {
                 nextConfig.metricsSource.ces.projectId = projectId;
                 nextConfig.metricsSource.ces.instanceId = matched.id;
                 nextConfig.metricsSource.ces.nodeId = matched.primaryNodeId;
-                if (boundDatasource && selectedHost) {
-                    deps.profileLoader.setRuntimeTarget(boundDatasource, {
-                        host: selectedHost,
-                        port: selectedPort,
-                        instanceId: matched.id,
-                        nodeId: matched.primaryNodeId,
-                    });
-                }
+                deps.profileLoader.setRuntimeTarget(boundDatasource, {
+                    host: selectedHost,
+                    port: selectedPort,
+                    instanceId: matched.id,
+                    nodeId: matched.primaryNodeId,
+                });
             });
-            if (boundDatasource) {
-                deps.credentialSessions?.clear(boundDatasource);
-            }
+            deps.credentialSessions?.clear(boundDatasource);
+            deps.operatorSessions?.revokeDatasource(boundDatasource);
+            const login = await issueSqlLoginForDatasource(deps, boundDatasource);
             return formatSuccess({
                 project_id: projectId,
                 instance_id: matched.id,
@@ -356,8 +363,10 @@ export const selectCloudTaurusInstanceTool = {
                 bound_datasource: boundDatasource,
                 bound_host: selectedHost,
                 bound_port: selectedPort,
+                login_url: login.loginUrl,
+                login_expires_at: login.expiresAt,
             }, {
-                summary: `Selected cloud instance ${matched.name} (${matched.id}).`,
+                summary: `Selected cloud instance ${matched.name} (${matched.id}) and created a local SQL login link.`,
                 metadata: metadata(context.taskId),
             });
         }

package/dist/tools/taurus/recycle-bin.d.ts

@@ -1,2 +1,4 @@
 import type { ToolDefinition } from "../registry.js";
 export declare const listRecycleBinTool: ToolDefinition;
+export declare const prepareRecycleBinRestoreTool: ToolDefinition;
+export declare const getRecycleBinRestoreStatusTool: ToolDefinition;

package/dist/tools/taurus/recycle-bin.js

@@ -1,6 +1,48 @@
+import { z } from "zod";
+import { buildRestoreRecycleBinTableSql, normalizeSql, sqlHash, } from "taurusdb-core";
 import { formatSuccess } from "../../utils/formatter.js";
-import { formatToolError } from "../error-handling.js";
-import { contextInputShape, metadata, resolveContext, summarizeRows, toPublicQueryResult, } from "../common.js";
+import { formatToolError, ToolInputError } from "../error-handling.js";
+import { asOptionalPositiveInteger, asOptionalString, asRequiredString, contextInputShape, metadata, resolveContext, summarizeRows, toPublicQueryResult, } from "../common.js";
+function recycleObjectExists(result, recycleTable) {
+    if (!result || typeof result !== "object" || !("rows" in result))
+        return false;
+    const rows = result.rows;
+    return Array.isArray(rows) && rows.some((row) => Array.isArray(row) && row.some((value) => String(value) === recycleTable));
+}
+function sameRecoveryTarget(prepared, current) {
+    return prepared.datasource === current.datasource &&
+        prepared.host === current.host &&
+        prepared.port === current.port &&
+        prepared.projectId === current.projectId &&
+        prepared.instanceId === current.instanceId &&
+        prepared.nodeId === current.nodeId;
+}
+async function writeRecoveryAudit(deps, input) {
+    if (!deps.auditWriter) {
+        throw new Error("Controlled recovery requires a durable audit writer.");
+    }
+    const profile = await deps.profileLoader.get(input.datasource);
+    const target = deps.profileLoader.getRuntimeTarget(input.datasource);
+    await deps.auditWriter.write({
+        timestamp: new Date().toISOString(),
+        task_id: input.requestId,
+        tool: input.tool,
+        actor: input.actor,
+        datasource: input.datasource,
+        database: input.database,
+        host: profile?.host,
+        port: profile?.port,
+        project_id: deps.config.cloud.projectId,
+        instance_id: target?.instanceId ?? profile?.instanceId ?? deps.config.cloud.instanceId,
+        node_id: target?.nodeId ?? profile?.nodeId ?? deps.config.cloud.nodeId,
+        sql_hash: sqlHash(normalizeSql(input.sql)),
+        raw_sql: deps.config.audit.includeRawSql ? input.sql : undefined,
+        decision: input.outcome === "success" ? "allowed" : "failed",
+        outcome: input.outcome,
+        error_code: input.errorCode,
+        duration_ms: input.durationMs,
+    });
+}
 export const listRecycleBinTool = {
     name: "list_recycle_bin",
     description: "List TaurusDB recycle bin tables. This is readonly and is intended for recovery triage after accidental DROP TABLE.",
@@ -33,3 +75,221 @@ export const listRecycleBinTool = {
         }
     },
 };
+export const prepareRecycleBinRestoreTool = {
+    name: "prepare_recycle_bin_restore",
+    description: "Prepare a short-lived local operator approval for one TaurusDB recycle-bin table. This tool performs readonly preflight only; the Agent cannot execute the restore.",
+    inputSchema: {
+        datasource: contextInputShape.datasource,
+        recycle_table: z.string().trim().min(1),
+        destination_database: z.string().trim().min(1),
+        destination_table: z.string().trim().min(1),
+        timeout_ms: contextInputShape.timeout_ms,
+    },
+    async handler(input, deps, context) {
+        try {
+            if (!deps.config.security.recycleBinRestoreEnabled) {
+                throw new ToolInputError("Controlled recycle-bin recovery is not enabled by the administrator.");
+            }
+            if (!deps.recoveryApproval) {
+                throw new ToolInputError("Controlled recycle-bin recovery approval is unavailable.");
+            }
+            if (!deps.auditWriter) {
+                throw new ToolInputError("Controlled recycle-bin recovery requires durable audit persistence.");
+            }
+            const recycleTable = asRequiredString(input.recycle_table, "recycle_table");
+            const destinationDatabase = asRequiredString(input.destination_database, "destination_database");
+            const destinationTable = asRequiredString(input.destination_table, "destination_table");
+            const timeoutMs = asOptionalPositiveInteger(input.timeout_ms, "timeout_ms");
+            const datasource = asOptionalString(input.datasource, "datasource");
+            const ctx = await deps.engine.resolveContext({
+                datasource,
+                database: destinationDatabase,
+                timeout_ms: timeoutMs,
+                readonly: true,
+            }, context.taskId);
+            const profile = await deps.profileLoader.get(ctx.datasource);
+            if (!profile?.user) {
+                throw new ToolInputError(`Datasource "${ctx.datasource}" has no active SQL credential session. Select the TaurusDB instance and open its returned local login URL first.`);
+            }
+            const [recycleBin, destinationTables] = await Promise.all([
+                deps.engine.listRecycleBin(ctx),
+                deps.engine.listTables(ctx, destinationDatabase),
+            ]);
+            if (!recycleObjectExists(recycleBin, recycleTable)) {
+                throw new ToolInputError(`Recycle-bin object "${recycleTable}" was not found during readonly preflight.`);
+            }
+            if (destinationTables.some((table) => table.name.toLowerCase() === destinationTable.toLowerCase())) {
+                throw new ToolInputError(`Destination table "${destinationDatabase}.${destinationTable}" already exists. Controlled recovery never overwrites an existing table.`);
+            }
+            const restoreInput = {
+                recycleTable,
+                method: "native_restore",
+                destinationDatabase,
+                destinationTable,
+            };
+            const restoreSql = buildRestoreRecycleBinTableSql(restoreInput);
+            const issued = await deps.recoveryApproval.issue({
+                target: {
+                    datasource: ctx.datasource,
+                    recycleTable,
+                    destinationDatabase,
+                    destinationTable,
+                },
+                execute: async (operator, requestId) => {
+                    const performRecovery = async () => {
+                        const startedAt = Date.now();
+                        let auditTool = "approve_recycle_bin_restore";
+                        try {
+                            const executionCtx = await deps.engine.resolveContext({
+                                datasource: ctx.datasource,
+                                database: destinationDatabase,
+                                timeout_ms: timeoutMs,
+                                readonly: false,
+                            }, requestId);
+                            if (!sameRecoveryTarget(ctx, executionCtx)) {
+                                throw new Error("Datasource target changed after recovery preflight. Create a new recovery request for the current target.");
+                            }
+                            const currentProfile = await deps.profileLoader.get(ctx.datasource);
+                            if (!currentProfile?.user) {
+                                throw new Error("The SQL credential session is no longer available.");
+                            }
+                            const [currentRecycleBin, currentDestinationTables] = await Promise.all([
+                                deps.engine.listRecycleBin(executionCtx),
+                                deps.engine.listTables(executionCtx, destinationDatabase),
+                            ]);
+                            if (!recycleObjectExists(currentRecycleBin, recycleTable)) {
+                                throw new Error("Recycle-bin object is no longer available. Create a new recovery request.");
+                            }
+                            if (currentDestinationTables.some((table) => table.name.toLowerCase() === destinationTable.toLowerCase())) {
+                                throw new Error("Destination table now exists. Controlled recovery will not overwrite it.");
+                            }
+                            await writeRecoveryAudit(deps, {
+                                requestId,
+                                actor: operator,
+                                datasource: executionCtx.datasource,
+                                database: destinationDatabase,
+                                sql: restoreSql,
+                                tool: auditTool,
+                                outcome: "success",
+                                durationMs: Date.now() - startedAt,
+                            });
+                            auditTool = "restore_recycle_bin_table";
+                            const result = await deps.engine.restoreRecycleBinTable(restoreInput, executionCtx, {
+                                timeoutMs,
+                            });
+                            const verifiedTables = await deps.engine.listTables(executionCtx, destinationDatabase);
+                            const verified = verifiedTables.some((table) => table.name.toLowerCase() === destinationTable.toLowerCase());
+                            if (!verified) {
+                                throw new Error("Recovery command completed, but readonly destination verification failed. Inspect database state before retrying.");
+                            }
+                            await writeRecoveryAudit(deps, {
+                                requestId,
+                                actor: operator,
+                                datasource: executionCtx.datasource,
+                                database: destinationDatabase,
+                                sql: restoreSql,
+                                tool: "restore_recycle_bin_table",
+                                outcome: "success",
+                                durationMs: Date.now() - startedAt,
+                            });
+                            return {
+                                queryId: result.queryId,
+                                affectedRows: result.affectedRows,
+                                verified,
+                            };
+                        }
+                        catch (error) {
+                            await writeRecoveryAudit(deps, {
+                                requestId,
+                                actor: operator,
+                                datasource: ctx.datasource,
+                                database: destinationDatabase,
+                                sql: restoreSql,
+                                tool: auditTool,
+                                outcome: "error",
+                                errorCode: "RECOVERY_FAILED",
+                                durationMs: Date.now() - startedAt,
+                            });
+                            throw error;
+                        }
+                    };
+                    return deps.sessionCoordinator
+                        ? deps.sessionCoordinator.runExclusive(performRecovery)
+                        : performRecovery();
+                },
+            });
+            return formatSuccess({
+                request_id: issued.requestId,
+                status: "pending",
+                approval_url: issued.approvalUrl,
+                expires_at: issued.expiresAt,
+                target: {
+                    datasource: ctx.datasource,
+                    recycle_table: recycleTable,
+                    destination_database: destinationDatabase,
+                    destination_table: destinationTable,
+                },
+                agent_can_execute: false,
+            }, {
+                summary: "Readonly preflight passed. A local operator must approve the recovery before it can execute.",
+                metadata: metadata(context.taskId, {
+                    statement_type: "show",
+                    sql_hash: sqlHash(normalizeSql(restoreSql)),
+                }),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "prepare_recycle_bin_restore",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};
+export const getRecycleBinRestoreStatusTool = {
+    name: "get_recycle_bin_restore_status",
+    description: "Get the status of a previously prepared recycle-bin recovery request.",
+    inputSchema: {
+        request_id: z.string().trim().min(1),
+    },
+    async handler(input, deps, context) {
+        try {
+            if (!deps.recoveryApproval) {
+                throw new ToolInputError("Controlled recycle-bin recovery is not enabled by the administrator.");
+            }
+            const requestId = asRequiredString(input.request_id, "request_id");
+            const status = deps.recoveryApproval.getStatus(requestId);
+            if (!status)
+                throw new ToolInputError("Recovery request was not found or is no longer retained.");
+            return formatSuccess({
+                request_id: status.requestId,
+                status: status.status,
+                target: {
+                    datasource: status.target.datasource,
+                    recycle_table: status.target.recycleTable,
+                    destination_database: status.target.destinationDatabase,
+                    destination_table: status.target.destinationTable,
+                },
+                created_at: status.createdAt,
+                expires_at: status.expiresAt,
+                operator: status.operator,
+                completed_at: status.completedAt,
+                result: status.result ? {
+                    query_id: status.result.queryId,
+                    affected_rows: status.result.affectedRows,
+                    verified: status.result.verified,
+                } : undefined,
+                error: status.error,
+            }, {
+                summary: `Recovery request status: ${status.status}.`,
+                metadata: metadata(context.taskId),
+            });
+        }
+        catch (error) {
+            return formatToolError(error, {
+                action: "get_recycle_bin_restore_status",
+                metadata: metadata(context.taskId),
+            });
+        }
+    },
+};

package/dist/tools/taurus/sql-login.d.ts

@@ -1,2 +1,3 @@
 import type { ToolDefinition } from "../registry.js";
+export declare function issueSqlLoginForDatasource(deps: Parameters<ToolDefinition["handler"]>[1], datasource: string): Promise<import("../../security/local-credential-login.js").IssuedSqlLogin>;
 export declare const beginSqlLoginTool: ToolDefinition;

package/dist/tools/taurus/sql-login.js

@@ -44,6 +44,7 @@ function classifyValidationFailure(error) {
 async function expireCredentials(deps, datasource) {
     const expire = async () => {
         deps.profileLoader.clearRuntimeUser(datasource);
+        deps.operatorSessions?.revokeDatasource(datasource);
         const previousEngine = deps.engine;
         if (previousEngine?.close) {
             await previousEngine.close();
@@ -60,6 +61,103 @@ async function expireCredentials(deps, datasource) {
         await expire();
     }
 }
+export async function issueSqlLoginForDatasource(deps, datasource) {
+    const profile = await deps.profileLoader.get(datasource);
+    if (!profile) {
+        throw new ToolInputError(`Datasource "${datasource}" was not found.`);
+    }
+    if (!profile.host) {
+        throw new ToolInputError(`Datasource "${datasource}" does not define a database host. Select a TaurusDB instance before beginning SQL login.`);
+    }
+    const runtimeTarget = deps.profileLoader.getRuntimeTarget(datasource);
+    return deps.credentialLogin.issueSqlLogin({
+        datasource,
+        target: {
+            datasource,
+            instanceId: runtimeTarget?.instanceId ??
+                profile.instanceId ??
+                deps.config.cloud.instanceId,
+            region: deps.config.cloud.region,
+            credentialIdleTtlMinutes: deps.config.security.credentialIdleTtlMinutes,
+            credentialMaxTtlMinutes: deps.config.security.credentialMaxTtlMinutes,
+        },
+        bind: async ({ username, password }) => {
+            const bindCredentials = async () => {
+                const currentTarget = deps.profileLoader.getRuntimeTarget(datasource);
+                const restoreTarget = () => {
+                    deps.profileLoader.clearRuntimeTarget(datasource);
+                    if (currentTarget) {
+                        deps.profileLoader.setRuntimeTarget(datasource, currentTarget);
+                    }
+                };
+                deps.profileLoader.setRuntimeTarget(datasource, {
+                    host: currentTarget?.host ?? profile.host,
+                    port: currentTarget?.port ?? profile.port,
+                    database: currentTarget?.database ?? profile.database,
+                    instanceId: currentTarget?.instanceId,
+                    nodeId: currentTarget?.nodeId,
+                    user: {
+                        username,
+                        password: { type: "plain", value: password },
+                    },
+                });
+                let nextEngine;
+                try {
+                    nextEngine = await TaurusDBEngine.create({
+                        config: deps.config,
+                        profileLoader: deps.profileLoader,
+                    });
+                    const validationTaskId = `credential_validation_${Date.now()}`;
+                    if (deps.sqlCredentialValidator) {
+                        await deps.sqlCredentialValidator(nextEngine, datasource, validationTaskId);
+                    }
+                    else {
+                        const validationContext = await nextEngine.resolveContext({ datasource, readonly: true }, validationTaskId);
+                        await nextEngine.executeReadonly("SELECT 1 AS ok", validationContext, {
+                            timeoutMs: Math.min(deps.config.limits.maxStatementMs, 10_000),
+                            maxRows: 1,
+                            maxColumns: 1,
+                            maxFieldChars: 16,
+                        });
+                    }
+                }
+                catch (error) {
+                    await nextEngine?.close().catch(() => undefined);
+                    restoreTarget();
+                    throw new SqlCredentialValidationError(classifyValidationFailure(error));
+                }
+                const previousEngine = deps.engine;
+                try {
+                    if (previousEngine?.close) {
+                        await previousEngine.close();
+                    }
+                }
+                catch (error) {
+                    await nextEngine.close().catch(() => undefined);
+                    restoreTarget();
+                    try {
+                        deps.engine = await TaurusDBEngine.create({
+                            config: deps.config,
+                            profileLoader: deps.profileLoader,
+                        });
+                    }
+                    catch {
+                        deps.engine = previousEngine;
+                    }
+                    throw new SqlCredentialValidationError(classifyValidationFailure(error));
+                }
+                deps.engine = nextEngine;
+                deps.credentialSessions?.activate(datasource, () => expireCredentials(deps, datasource));
+            };
+            if (deps.sessionCoordinator) {
+                await deps.sessionCoordinator.runExclusive(bindCredentials);
+            }
+            else {
+                await bindCredentials();
+            }
+        },
+    });
+}
 export const beginSqlLoginTool = {
     name: "begin_sql_login",
     description: "Create a short-lived local login URL where the user can enter SQL credentials without sending the password through the Agent or MCP tool arguments.",
@@ -78,101 +176,7 @@ export const beginSqlLoginTool = {
             if (!datasource) {
                 throw new ToolInputError("No datasource selected. Configure a default datasource or pass datasource explicitly.");
             }
-            const profile = await deps.profileLoader.get(datasource);
-            if (!profile) {
-                throw new ToolInputError(`Datasource "${datasource}" was not found.`);
-            }
-            if (!profile.host) {
-                throw new ToolInputError(`Datasource "${datasource}" does not define a database host. Select a TaurusDB instance before beginning SQL login.`);
-            }
-            const runtimeTarget = deps.profileLoader.getRuntimeTarget(datasource);
-            const issued = await deps.credentialLogin.issueSqlLogin({
-                datasource,
-                target: {
-                    datasource,
-                    instanceId: runtimeTarget?.instanceId ??
-                        profile.instanceId ??
-                        deps.config.cloud.instanceId,
-                    region: deps.config.cloud.region,
-                    credentialIdleTtlMinutes: deps.config.security.credentialIdleTtlMinutes,
-                    credentialMaxTtlMinutes: deps.config.security.credentialMaxTtlMinutes,
-                },
-                bind: async ({ username, password }) => {
-                    const bindCredentials = async () => {
-                        const currentTarget = deps.profileLoader.getRuntimeTarget(datasource);
-                        const restoreTarget = () => {
-                            deps.profileLoader.clearRuntimeTarget(datasource);
-                            if (currentTarget) {
-                                deps.profileLoader.setRuntimeTarget(datasource, currentTarget);
-                            }
-                        };
-                        deps.profileLoader.setRuntimeTarget(datasource, {
-                            host: currentTarget?.host ?? profile.host,
-                            port: currentTarget?.port ?? profile.port,
-                            database: currentTarget?.database ?? profile.database,
-                            instanceId: currentTarget?.instanceId,
-                            nodeId: currentTarget?.nodeId,
-                            user: {
-                                username,
-                                password: { type: "plain", value: password },
-                            },
-                        });
-                        let nextEngine;
-                        try {
-                            nextEngine = await TaurusDBEngine.create({
-                                config: deps.config,
-                                profileLoader: deps.profileLoader,
-                            });
-                            const validationTaskId = `credential_validation_${Date.now()}`;
-                            if (deps.sqlCredentialValidator) {
-                                await deps.sqlCredentialValidator(nextEngine, datasource, validationTaskId);
-                            }
-                            else {
-                                const validationContext = await nextEngine.resolveContext({ datasource, readonly: true }, validationTaskId);
-                                await nextEngine.executeReadonly("SELECT 1 AS ok", validationContext, {
-                                    timeoutMs: Math.min(deps.config.limits.maxStatementMs, 10_000),
-                                    maxRows: 1,
-                                    maxColumns: 1,
-                                    maxFieldChars: 16,
-                                });
-                            }
-                        }
-                        catch (error) {
-                            await nextEngine?.close().catch(() => undefined);
-                            restoreTarget();
-                            throw new SqlCredentialValidationError(classifyValidationFailure(error));
-                        }
-                        const previousEngine = deps.engine;
-                        try {
-                            if (previousEngine?.close) {
-                                await previousEngine.close();
-                            }
-                        }
-                        catch (error) {
-                            await nextEngine.close().catch(() => undefined);
-                            restoreTarget();
-                            try {
-                                deps.engine = await TaurusDBEngine.create({
-                                    config: deps.config,
-                                    profileLoader: deps.profileLoader,
-                                });
-                            }
-                            catch {
-                                deps.engine = previousEngine;
-                            }
-                            throw new SqlCredentialValidationError(classifyValidationFailure(error));
-                        }
-                        deps.engine = nextEngine;
-                        deps.credentialSessions?.activate(datasource, () => expireCredentials(deps, datasource));
-                    };
-                    if (deps.sessionCoordinator) {
-                        await deps.sessionCoordinator.runExclusive(bindCredentials);
-                    }
-                    else {
-                        await bindCredentials();
-                    }
-                },
-            });
+            const issued = await issueSqlLoginForDatasource(deps, datasource);
             return formatSuccess({
                 datasource,
                 login_url: issued.loginUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taurusdb-mcp",
-  "version": "0.5.0-rc.3",
+  "version": "0.5.0-rc.4",
   "description": "TaurusDB MCP server for Claude, Cursor, VS Code, and other MCP clients.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "taurusdb-core": "0.5.0-rc.3",
+    "taurusdb-core": "0.5.0-rc.4",
     "@modelcontextprotocol/sdk": "^1.17.0",
     "mysql2": "^3.22.1",
     "zod": "^3.24.1"