drawio-mcp-server 2.0.4 → 2.1.0

package/build/request_queue.test.js

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "@jest/globals";
+import { create_request_queue } from "./request_queue.js";
+import { create_logger } from "./standard_console_logger.js";
+describe("request queue", () => {
+    function activeTailCount(queue) {
+        return queue._active_tail_count();
+    }
+    it("runs enqueued tasks in FIFO order", async () => {
+        const queue = create_request_queue(create_logger());
+        const steps = [];
+        let releaseFirst;
+        const first = queue.enqueue("alpha", async () => {
+            steps.push("first:start");
+            await new Promise((resolve) => {
+                releaseFirst = resolve;
+            });
+            steps.push("first:end");
+            return "first";
+        });
+        const second = queue.enqueue("alpha", async () => {
+            steps.push("second:start");
+            steps.push("second:end");
+            return "second";
+        });
+        await Promise.resolve();
+        expect(steps).toEqual(["first:start"]);
+        releaseFirst();
+        await expect(Promise.all([first, second])).resolves.toEqual([
+            "first",
+            "second",
+        ]);
+        expect(steps).toEqual([
+            "first:start",
+            "first:end",
+            "second:start",
+            "second:end",
+        ]);
+    });
+    it("continues processing after a rejected task", async () => {
+        const queue = create_request_queue(create_logger());
+        const steps = [];
+        const first = queue.enqueue("alpha", async () => {
+            steps.push("first");
+            throw new Error("boom");
+        });
+        const second = queue.enqueue("alpha", async () => {
+            steps.push("second");
+            return "ok";
+        });
+        await expect(first).rejects.toThrow("boom");
+        await expect(second).resolves.toBe("ok");
+        expect(steps).toEqual(["first", "second"]);
+    });
+    it("allows different queue keys to run independently", async () => {
+        const queue = create_request_queue(create_logger());
+        const steps = [];
+        let releaseFirst;
+        const first = queue.enqueue("alpha", async () => {
+            steps.push("alpha:start");
+            await new Promise((resolve) => {
+                releaseFirst = resolve;
+            });
+            steps.push("alpha:end");
+            return "alpha";
+        });
+        const second = queue.enqueue("beta", async () => {
+            steps.push("beta:start");
+            steps.push("beta:end");
+            return "beta";
+        });
+        await Promise.resolve();
+        await expect(second).resolves.toBe("beta");
+        expect(steps).toEqual(["alpha:start", "beta:start", "beta:end"]);
+        releaseFirst();
+        await expect(first).resolves.toBe("alpha");
+        expect(steps).toEqual([
+            "alpha:start",
+            "beta:start",
+            "beta:end",
+            "alpha:end",
+        ]);
+    });
+    it("cleans up finished queue keys", async () => {
+        const queue = create_request_queue(create_logger());
+        expect(activeTailCount(queue)).toBe(0);
+        await expect(queue.enqueue("alpha", async () => "alpha")).resolves.toBe("alpha");
+        await Promise.resolve();
+        expect(activeTailCount(queue)).toBe(0);
+        const first = queue.enqueue("alpha", async () => "first");
+        const second = queue.enqueue("beta", async () => "second");
+        await expect(Promise.all([first, second])).resolves.toEqual([
+            "first",
+            "second",
+        ]);
+        await Promise.resolve();
+        expect(activeTailCount(queue)).toBe(0);
+    });
+});

package/build/stdio-transport-purity.test.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+async function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr && typeof addr === "object") {
+                const port = addr.port;
+                srv.close(() => resolve(port));
+            }
+            else {
+                srv.close(() => reject(new Error("could not resolve free port")));
+            }
+        });
+    });
+}
+const here = dirname(fileURLToPath(import.meta.url));
+// Tests run from build/, so build/index.js is sibling to this compiled file.
+const SERVER_BIN = join(here, "index.js");
+describe("stdio transport stdout purity", () => {
+    let proc;
+    afterEach(() => {
+        if (proc && !proc.killed) {
+            proc.kill("SIGTERM");
+        }
+        proc = undefined;
+    });
+    it("emits only valid JSON-RPC frames on stdout during initialize", async () => {
+        const extensionPort = await getFreePort();
+        const httpPort = await getFreePort();
+        proc = spawn(process.execPath, [
+            SERVER_BIN,
+            "--transport",
+            "stdio",
+            "--extension-port",
+            String(extensionPort),
+            "--http-port",
+            String(httpPort),
+            "--host",
+            "127.0.0.1",
+        ], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        proc.stdout.on("data", (b) => stdoutChunks.push(b.toString("utf8")));
+        proc.stderr.on("data", (b) => stderrChunks.push(b.toString("utf8")));
+        const initRequest = {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-03-26",
+                capabilities: {},
+                clientInfo: { name: "purity-test", version: "1.0.0" },
+            },
+        };
+        proc.stdin.write(`${JSON.stringify(initRequest)}\n`);
+        // Wait for the initialize response to arrive on stdout.
+        const response = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("timed out waiting for initialize response")), 10000);
+            const onChunk = () => {
+                const text = stdoutChunks.join("");
+                if (text.includes("\n")) {
+                    clearTimeout(timer);
+                    proc?.stdout.off("data", onChunk);
+                    resolve(text);
+                }
+            };
+            proc?.stdout.on("data", onChunk);
+            // Re-check synchronously in case data arrived before we attached.
+            onChunk();
+        });
+        const lines = response.split("\n").filter((line) => line.length > 0);
+        expect(lines.length).toBeGreaterThan(0);
+        for (const line of lines) {
+            expect(() => JSON.parse(line)).not.toThrow();
+        }
+        const parsed = JSON.parse(lines[0]);
+        expect(parsed.jsonrpc).toBe("2.0");
+        expect(parsed.id).toBe(1);
+        expect(parsed.result?.serverInfo?.name).toBe("drawio-mcp-server");
+    }, 20000);
+});

package/build/strip-schema.js

@@ -0,0 +1,61 @@
+/**
+ * Strips the `$schema` key from a JSON Schema object.
+ * The `$schema` key injected by zodToJsonSchema causes Claude Code to silently
+ * drop tools because the `$` character fails Anthropic's validation regex
+ * `^[a-zA-Z0-9_.-]{1,64}$`.
+ *
+ * @param schema - The input schema object (may have `$schema` key)
+ * @returns The schema without `$schema` key
+ */
+export function stripSchemaKey(schema) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { $schema, ...rest } = schema;
+    return rest;
+}
+/**
+ * Recursively strips the `$schema` key from a JSON Schema object and all nested schemas.
+ * This handles cases like `definitions` in the schema.
+ *
+ * @param schema - The input schema object
+ * @returns The schema without `$schema` key
+ */
+export function stripSchemaRecursively(schema) {
+    if (!schema || typeof schema !== "object") {
+        return schema;
+    }
+    // Create a shallow copy first
+    const result = { ...schema };
+    // Remove $schema if present
+    if ("$schema" in result) {
+        delete result["$schema"];
+    }
+    // Recursively process properties
+    if ("properties" in result && typeof result.properties === "object") {
+        result.properties = stripSchemaRecursively(result.properties);
+    }
+    // Recursively process items
+    if ("items" in result && typeof result.items === "object") {
+        result.items = stripSchemaRecursively(result.items);
+    }
+    // Recursively process additionalProperties
+    if ("additionalProperties" in result &&
+        typeof result.additionalProperties === "object") {
+        result.additionalProperties = stripSchemaRecursively(result.additionalProperties);
+    }
+    // Recursively process patternProperties
+    if ("patternProperties" in result &&
+        typeof result.patternProperties === "object") {
+        result.patternProperties = stripSchemaRecursively(result.patternProperties);
+    }
+    // Process definitions
+    if ("definitions" in result && typeof result.definitions === "object") {
+        result.definitions = stripSchemaRecursively(result.definitions);
+    }
+    // Process anyOf, allOf, oneOf
+    for (const key of ["anyOf", "allOf", "oneOf"]) {
+        if (key in result && Array.isArray(result[key])) {
+            result[key] = result[key].map((item) => typeof item === "object" ? stripSchemaRecursively(item) : item);
+        }
+    }
+    return result;
+}

package/build/tls/expiry.js

@@ -0,0 +1,14 @@
+const RENEWAL_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+export function evaluateMaterial(args) {
+    if (!args.meta)
+        return "missing";
+    const caExpiresAt = new Date(args.meta.caNotAfter).getTime();
+    if (caExpiresAt - args.now.getTime() < RENEWAL_WINDOW_MS)
+        return "ca-expired";
+    const leafExpiresAt = new Date(args.meta.serverNotAfter).getTime();
+    if (leafExpiresAt - args.now.getTime() < RENEWAL_WINDOW_MS)
+        return "leaf-expired";
+    if (args.meta.sanHash !== args.currentSanHash)
+        return "san-drift";
+    return "valid";
+}

package/build/tls/expiry.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "@jest/globals";
+import { evaluateMaterial } from "./expiry.js";
+const baseMeta = (overrides = {}) => ({
+    version: 1,
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    sanHash: "hash-A",
+    caNotAfter: "2036-01-01T00:00:00.000Z",
+    serverNotAfter: "2027-01-01T00:00:00.000Z",
+    ...overrides,
+});
+describe("evaluateMaterial", () => {
+    it("returns 'missing' when meta is null", () => {
+        expect(evaluateMaterial({
+            meta: null,
+            currentSanHash: "hash-A",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("missing");
+    });
+    it("returns 'valid' when CA + leaf future-valid and SAN matches", () => {
+        expect(evaluateMaterial({
+            meta: baseMeta(),
+            currentSanHash: "hash-A",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("valid");
+    });
+    it("returns 'san-drift' when SAN hash differs but CA still valid", () => {
+        expect(evaluateMaterial({
+            meta: baseMeta(),
+            currentSanHash: "hash-B",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("san-drift");
+    });
+    it("returns 'leaf-expired' when leaf within 30-day expiry window", () => {
+        expect(evaluateMaterial({
+            meta: baseMeta({ serverNotAfter: "2026-06-15T00:00:00.000Z" }),
+            currentSanHash: "hash-A",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("leaf-expired");
+    });
+    it("returns 'ca-expired' when CA within 30-day expiry window (overrides leaf)", () => {
+        expect(evaluateMaterial({
+            meta: baseMeta({ caNotAfter: "2026-06-15T00:00:00.000Z" }),
+            currentSanHash: "hash-A",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("ca-expired");
+    });
+    it("CA expired wins over SAN drift", () => {
+        expect(evaluateMaterial({
+            meta: baseMeta({ caNotAfter: "2026-06-15T00:00:00.000Z" }),
+            currentSanHash: "hash-B",
+            now: new Date("2026-06-01T00:00:00Z"),
+        })).toBe("ca-expired");
+    });
+});

package/build/tls/generate.js

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import forge from "node-forge";
+const SERIAL_BYTES = 16;
+function randomSerialHex() {
+    const bytes = forge.random.getBytesSync(SERIAL_BYTES);
+    const arr = Array.from(bytes, (c) => c.charCodeAt(0));
+    arr[0] = arr[0] & 0x7f;
+    return arr.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function setValidity(cert, from, years) {
+    cert.validity.notBefore = from;
+    const to = new Date(from);
+    to.setUTCFullYear(to.getUTCFullYear() + years);
+    cert.validity.notAfter = to;
+}
+export function generateCa(args) {
+    const keys = forge.pki.rsa.generateKeyPair(2048);
+    const cert = forge.pki.createCertificate();
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = randomSerialHex();
+    setValidity(cert, args.now, 10);
+    const attrs = [{ name: "commonName", value: "drawio-mcp-server local CA" }];
+    cert.setSubject(attrs);
+    cert.setIssuer(attrs);
+    cert.setExtensions([
+        { name: "basicConstraints", cA: true, critical: true },
+        {
+            name: "keyUsage",
+            keyCertSign: true,
+            cRLSign: true,
+            critical: true,
+        },
+        { name: "subjectKeyIdentifier" },
+    ]);
+    cert.sign(keys.privateKey, forge.md.sha256.create());
+    return {
+        certPem: forge.pki.certificateToPem(cert),
+        keyPem: forge.pki.privateKeyToPem(keys.privateKey),
+        cert,
+        keys,
+    };
+}
+function sanListToAltNames(sanList) {
+    return sanList.map((entry) => entry.type === "dns"
+        ? { type: 2, value: entry.value }
+        : { type: 7, ip: entry.value });
+}
+export function generateLeaf(args) {
+    const keys = forge.pki.rsa.generateKeyPair(2048);
+    const cert = forge.pki.createCertificate();
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = randomSerialHex();
+    setValidity(cert, args.now, 1);
+    cert.setSubject([{ name: "commonName", value: "drawio-mcp-server" }]);
+    cert.setIssuer(args.ca.cert.subject.attributes);
+    cert.setExtensions([
+        { name: "basicConstraints", cA: false, critical: true },
+        {
+            name: "keyUsage",
+            digitalSignature: true,
+            keyEncipherment: true,
+            critical: true,
+        },
+        { name: "extKeyUsage", serverAuth: true },
+        { name: "subjectAltName", altNames: sanListToAltNames(args.sanList) },
+        { name: "subjectKeyIdentifier" },
+    ]);
+    cert.sign(args.ca.keys.privateKey, forge.md.sha256.create());
+    return {
+        certPem: forge.pki.certificateToPem(cert),
+        keyPem: forge.pki.privateKeyToPem(keys.privateKey),
+        cert,
+        keys,
+    };
+}
+export function writeMaterial(args) {
+    mkdirSync(dirname(args.paths.caCert), { recursive: true, mode: 0o700 });
+    writeFileSync(args.paths.caCert, args.ca.certPem, { mode: 0o644 });
+    writeFileSync(args.paths.caKey, args.ca.keyPem, { mode: 0o600 });
+    writeFileSync(args.paths.serverCert, args.leaf.certPem, { mode: 0o644 });
+    writeFileSync(args.paths.serverKey, args.leaf.keyPem, { mode: 0o600 });
+    const meta = {
+        version: 1,
+        generatedAt: args.generatedAt.toISOString(),
+        sanHash: args.sanHash,
+        caNotAfter: args.ca.cert.validity.notAfter.toISOString(),
+        serverNotAfter: args.leaf.cert.validity.notAfter.toISOString(),
+    };
+    writeFileSync(args.paths.meta, JSON.stringify(meta, null, 2), {
+        mode: 0o644,
+    });
+}
+export function readMeta(paths) {
+    if (!existsSync(paths.meta))
+        return null;
+    let parsed;
+    try {
+        const raw = readFileSync(paths.meta, "utf8");
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed?.version !== 1)
+        return null;
+    return parsed;
+}
+export function loadCaMaterial(paths) {
+    if (!existsSync(paths.caCert) || !existsSync(paths.caKey)) {
+        throw new Error(`TLS material directory is in an inconsistent state: ${dirname(paths.caCert)}. Delete it and restart.`);
+    }
+    const certPem = readFileSync(paths.caCert, "utf8");
+    const keyPem = readFileSync(paths.caKey, "utf8");
+    const cert = forge.pki.certificateFromPem(certPem);
+    const privateKey = forge.pki.privateKeyFromPem(keyPem);
+    return {
+        certPem,
+        keyPem,
+        cert,
+        keys: { privateKey, publicKey: cert.publicKey },
+    };
+}

package/build/tls/generate.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "@jest/globals";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import forge from "node-forge";
+import { generateCa, generateLeaf, writeMaterial, readMeta, } from "./generate.js";
+import { tlsFilePaths } from "./paths.js";
+import { buildSanList } from "./san.js";
+describe("generateCa", () => {
+    it("produces a self-signed CA cert with basicConstraints CA:true", () => {
+        const ca = generateCa({ now: new Date("2026-01-01T00:00:00Z") });
+        const cert = forge.pki.certificateFromPem(ca.certPem);
+        const bc = cert.getExtension("basicConstraints");
+        expect(bc?.cA).toBe(true);
+    });
+    it("validity is 10 years from `now`", () => {
+        const now = new Date("2026-01-01T00:00:00Z");
+        const ca = generateCa({ now });
+        const cert = forge.pki.certificateFromPem(ca.certPem);
+        expect(cert.validity.notBefore.toISOString()).toBe("2026-01-01T00:00:00.000Z");
+        expect(cert.validity.notAfter.toISOString()).toBe("2036-01-01T00:00:00.000Z");
+    });
+    it("subject CN identifies the app", () => {
+        const ca = generateCa({ now: new Date() });
+        const cert = forge.pki.certificateFromPem(ca.certPem);
+        const cn = cert.subject.getField("CN")?.value;
+        expect(cn).toBe("drawio-mcp-server local CA");
+    });
+});
+describe("generateLeaf", () => {
+    const ca = generateCa({ now: new Date("2026-01-01T00:00:00Z") });
+    const sanList = buildSanList("192.168.1.10");
+    it("is signed by the CA (issuer = CA subject)", () => {
+        const leaf = generateLeaf({
+            ca,
+            sanList,
+            now: new Date("2026-01-01T00:00:00Z"),
+        });
+        const cert = forge.pki.certificateFromPem(leaf.certPem);
+        const caCert = forge.pki.certificateFromPem(ca.certPem);
+        expect(cert.issuer.hash).toBe(caCert.subject.hash);
+    });
+    it("validity is 1 year from `now`", () => {
+        const now = new Date("2026-01-01T00:00:00Z");
+        const leaf = generateLeaf({ ca, sanList, now });
+        const cert = forge.pki.certificateFromPem(leaf.certPem);
+        expect(cert.validity.notAfter.toISOString()).toBe("2027-01-01T00:00:00.000Z");
+    });
+    it("includes every SAN entry with correct type", () => {
+        const leaf = generateLeaf({ ca, sanList, now: new Date() });
+        const cert = forge.pki.certificateFromPem(leaf.certPem);
+        const ext = cert.getExtension("subjectAltName");
+        const altNames = ext?.altNames ?? [];
+        expect(altNames.find((a) => a.type === 2 && a.value === "localhost")).toBeTruthy();
+        expect(altNames.find((a) => a.type === 7 && a.ip === "127.0.0.1")).toBeTruthy();
+        expect(altNames.find((a) => a.type === 7 && a.ip === "::1")).toBeTruthy();
+        expect(altNames.find((a) => a.type === 7 && a.ip === "192.168.1.10")).toBeTruthy();
+    });
+    it("EKU includes serverAuth", () => {
+        const leaf = generateLeaf({ ca, sanList, now: new Date() });
+        const cert = forge.pki.certificateFromPem(leaf.certPem);
+        const eku = cert.getExtension("extKeyUsage");
+        expect(eku?.serverAuth).toBe(true);
+    });
+});
+describe("writeMaterial / readMeta", () => {
+    it("writes all PEM files and meta.json with private keys at mode 0600 (POSIX)", () => {
+        const dir = mkdtempSync(join(tmpdir(), "tls-test-"));
+        const paths = tlsFilePaths(dir);
+        const ca = generateCa({ now: new Date("2026-01-01T00:00:00Z") });
+        const leaf = generateLeaf({
+            ca,
+            sanList: buildSanList(undefined),
+            now: new Date("2026-01-01T00:00:00Z"),
+        });
+        writeMaterial({
+            paths,
+            ca,
+            leaf,
+            sanHash: "abc",
+            generatedAt: new Date("2026-01-01T00:00:00Z"),
+        });
+        expect(readFileSync(paths.caCert, "utf8")).toContain("BEGIN CERTIFICATE");
+        expect(readFileSync(paths.serverCert, "utf8")).toContain("BEGIN CERTIFICATE");
+        expect(readFileSync(paths.caKey, "utf8")).toContain("PRIVATE KEY");
+        expect(readFileSync(paths.serverKey, "utf8")).toContain("PRIVATE KEY");
+        if (process.platform !== "win32") {
+            expect(statSync(paths.caKey).mode & 0o777).toBe(0o600);
+            expect(statSync(paths.serverKey).mode & 0o777).toBe(0o600);
+            expect(statSync(paths.caCert).mode & 0o777).toBe(0o644);
+            expect(statSync(paths.serverCert).mode & 0o777).toBe(0o644);
+            expect(statSync(paths.meta).mode & 0o777).toBe(0o644);
+        }
+        const meta = readMeta(paths);
+        expect(meta?.sanHash).toBe("abc");
+        expect(meta?.caNotAfter).toBe("2036-01-01T00:00:00.000Z");
+        expect(meta?.serverNotAfter).toBe("2027-01-01T00:00:00.000Z");
+    });
+    it("readMeta returns null when meta.json missing", () => {
+        const dir = mkdtempSync(join(tmpdir(), "tls-test-"));
+        expect(readMeta(tlsFilePaths(dir))).toBeNull();
+    });
+    it("readMeta returns null when meta.json has unknown version", () => {
+        const dir = mkdtempSync(join(tmpdir(), "tls-test-"));
+        const paths = tlsFilePaths(dir);
+        writeFileSync(paths.meta, JSON.stringify({ version: 99, sanHash: "x" }));
+        expect(readMeta(paths)).toBeNull();
+    });
+    it("readMeta returns null when meta.json is malformed", () => {
+        const dir = mkdtempSync(join(tmpdir(), "tls-test-"));
+        const paths = tlsFilePaths(dir);
+        writeFileSync(paths.meta, "{not json");
+        expect(readMeta(paths)).toBeNull();
+    });
+});

package/build/tls/index.js

@@ -0,0 +1,80 @@
+import { homedir, platform as osPlatform } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { generateCa, generateLeaf, readMeta, writeMaterial, loadCaMaterial, } from "./generate.js";
+import { caInstallHint } from "./install-hint.js";
+import { evaluateMaterial } from "./expiry.js";
+import { loadManualMaterial } from "./load.js";
+import { resolveTlsDir, tlsFilePaths } from "./paths.js";
+import { buildSanList, sanHash } from "./san.js";
+export function resolveTlsMaterial(args) {
+    const { config } = args;
+    if (!config.tlsEnabled)
+        return null;
+    const hasManual = Boolean(config.tlsCert || config.tlsKey);
+    const hasAuto = Boolean(config.tlsAuto);
+    if (hasManual && hasAuto) {
+        throw new Error("Cannot combine --tls-auto with --tls-cert/--tls-key. Pick one mode.");
+    }
+    if (!hasManual && !hasAuto) {
+        throw new Error("--tls requires either --tls-auto or --tls-cert/--tls-key");
+    }
+    if (hasManual) {
+        if (!config.tlsCert || !config.tlsKey) {
+            throw new Error("--tls-cert and --tls-key must both be provided");
+        }
+        const m = loadManualMaterial({
+            certPath: config.tlsCert,
+            keyPath: config.tlsKey,
+        });
+        return { cert: m.cert, key: m.key, caPath: undefined };
+    }
+    // Auto mode
+    const now = args.now ?? new Date();
+    const platform = args.platform ?? osPlatform();
+    const env = args.env ?? process.env;
+    const home = args.home ?? homedir();
+    const dir = resolveTlsDir({
+        override: config.tlsDir,
+        platform,
+        env,
+        home,
+    });
+    const paths = tlsFilePaths(dir);
+    const sanList = buildSanList(config.host);
+    const currentSanHash = sanHash(sanList);
+    const meta = readMeta(paths);
+    const state = evaluateMaterial({ meta, currentSanHash, now });
+    if (state === "valid") {
+        if (existsSync(paths.serverCert) && existsSync(paths.serverKey)) {
+            return {
+                cert: readFileSync(paths.serverCert, "utf8"),
+                key: readFileSync(paths.serverKey, "utf8"),
+                caPath: paths.caCert,
+            };
+        }
+        // meta said valid but files vanished — treat as missing
+    }
+    let ca;
+    const cacheLost = state === "valid"; // we already returned if cache existed
+    if (!cacheLost && (state === "san-drift" || state === "leaf-expired")) {
+        // CA still valid — keep it, regen leaf only
+        ca = loadCaMaterial(paths);
+    }
+    else {
+        // missing, ca-expired, or vanished cache — full regen
+        ca = generateCa({ now });
+    }
+    const leaf = generateLeaf({ ca, sanList, now });
+    writeMaterial({ paths, ca, leaf, sanHash: currentSanHash, generatedAt: now });
+    if (state !== "san-drift" && state !== "leaf-expired") {
+        args.log(`\n${caInstallHint({ platform, caPath: paths.caCert })}\n`);
+    }
+    else {
+        args.log(`Renewed TLS leaf certificate (state: ${state}). CA at ${paths.caCert} unchanged.`);
+    }
+    return {
+        cert: leaf.certPem,
+        key: leaf.keyPem,
+        caPath: paths.caCert,
+    };
+}