@xdarkicex/openclaw-memory-libravdb 1.4.80 → 1.5.1

package/README.md

@@ -187,7 +187,7 @@ All keys are optional. For the full reference, see [Configuration](./docs/config
 
 - New install: [Install](./docs/install.md), [Installation reference](./docs/installation.md)
 - Understand the design: [Problem](./docs/problem.md), [Architecture](./docs/architecture.md), [ADRs](./docs/architecture-decisions/README.md)
-- Configure: [Configuration](./docs/configuration.md), [Features](./docs/features.md), [Embedding profiles](./docs/embedding-profiles.md), [Models](./docs/models.md)
+- Configure: [Configuration](./docs/configuration.md), [TLS configuration](./docs/TLS_configuration.md), [mTLS configuration](./docs/mTLS_configuration.md), [Features](./docs/features.md), [Embedding profiles](./docs/embedding-profiles.md), [Models](./docs/models.md)
 - Operate safely: [Security](./docs/security.md), [Uninstall](./docs/uninstall.md)
 - Advanced operations: [Performance and tuning](./docs/performance-and-tuning.md)
 - Work from source: [Development](./docs/development.md), [Contributing](./docs/contributing.md)

package/dist/grpc-client.d.ts

@@ -1,10 +1,29 @@
+import * as grpc from "@grpc/grpc-js";
 export interface GrpcClientOptions {
     endpoint: string;
     secret?: string;
     timeoutMs?: number;
+    tlsCaPath?: string;
+    tlsMode?: "auto" | "tls" | "insecure";
+    tlsClientCertPath?: string;
+    tlsClientKeyPath?: string;
 }
 export declare function resolveGrpcTarget(endpoint: string): string;
-export declare function resolveGrpcCredentialMode(endpoint: string): "insecure" | "tls";
+/**
+ * Selects gRPC credential mode based on endpoint address class.
+ *
+ * - Unix socket endpoints → plaintext (local-only transport)
+ * - Loopback addresses (localhost, 127.0.0.1, ::1) → plaintext
+ * - All other TCP and DNS targets → TLS
+ *
+ * resolveGrpcCredentials uses this classification to return the
+ * appropriate grpc.ChannelCredentials. Pass tlsCaPath to load a
+ * custom CA certificate PEM file for self-signed or private CA
+ * deployments. Omit tlsCaPath for publicly trusted certificates
+ * (Let's Encrypt, cert-manager) — the system CA pool is used.
+ */
+export declare function resolveGrpcCredentialMode(endpoint: string, tlsMode?: "auto" | "tls" | "insecure"): "insecure" | "tls";
+export declare function resolveGrpcCredentials(endpoint: string, tlsCaPath?: string, tlsMode?: "auto" | "tls" | "insecure", tlsClientCertPath?: string, tlsClientKeyPath?: string): grpc.ChannelCredentials;
 export declare class GrpcKernelClient {
     private client;
     private readonly secret;

package/dist/grpc-client.js

@@ -1,6 +1,7 @@
 import { createHmac } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import fs from "node:fs";
 import * as grpc from "@grpc/grpc-js";
 import * as protoLoader from "@grpc/proto-loader";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -10,18 +11,72 @@ const PROTO_PATH = path.resolve(__dirname, "./proto/intelligence_kernel/v1/kerne
 export function resolveGrpcTarget(endpoint) {
     return endpoint.startsWith("tcp:") ? endpoint.substring(4) : endpoint;
 }
-export function resolveGrpcCredentialMode(endpoint) {
+/**
+ * Selects gRPC credential mode based on endpoint address class.
+ *
+ * - Unix socket endpoints → plaintext (local-only transport)
+ * - Loopback addresses (localhost, 127.0.0.1, ::1) → plaintext
+ * - All other TCP and DNS targets → TLS
+ *
+ * resolveGrpcCredentials uses this classification to return the
+ * appropriate grpc.ChannelCredentials. Pass tlsCaPath to load a
+ * custom CA certificate PEM file for self-signed or private CA
+ * deployments. Omit tlsCaPath for publicly trusted certificates
+ * (Let's Encrypt, cert-manager) — the system CA pool is used.
+ */
+export function resolveGrpcCredentialMode(endpoint, tlsMode) {
+    if (tlsMode === "tls")
+        return "tls";
+    if (tlsMode === "insecure")
+        return "insecure";
+    // "auto" or undefined — address-based heuristic
     const target = resolveGrpcTarget(endpoint).trim();
-    if (target.startsWith("unix:")) {
+    if (target.startsWith("unix:"))
         return "insecure";
-    }
     const host = extractGrpcHost(target);
     return isLoopbackHost(host) ? "insecure" : "tls";
 }
-function resolveGrpcCredentials(endpoint) {
-    return resolveGrpcCredentialMode(endpoint) === "insecure"
-        ? grpc.credentials.createInsecure()
-        : grpc.credentials.createSsl();
+export function resolveGrpcCredentials(endpoint, tlsCaPath, tlsMode, tlsClientCertPath, tlsClientKeyPath) {
+    if (resolveGrpcCredentialMode(endpoint, tlsMode) === "insecure") {
+        return grpc.credentials.createInsecure();
+    }
+    // tlsMode is "tls" or "auto"/undefined resolved to "tls"
+    let rootCerts = null;
+    if (tlsCaPath) {
+        try {
+            rootCerts = fs.readFileSync(tlsCaPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`LibraVDB: failed to load TLS CA certificate from "${tlsCaPath}": ${msg}`);
+        }
+    }
+    // Client certificate and key must both be present or both absent
+    const hasCert = tlsClientCertPath !== undefined;
+    const hasKey = tlsClientKeyPath !== undefined;
+    if (hasCert !== hasKey) {
+        throw new Error("LibraVDB: grpcEndpointTlsClientCert and grpcEndpointTlsClientKey " +
+            "must both be set or both be omitted");
+    }
+    let clientKey = null;
+    let clientCert = null;
+    if (tlsClientCertPath && tlsClientKeyPath) {
+        try {
+            clientCert = fs.readFileSync(tlsClientCertPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`LibraVDB: failed to load TLS client certificate from "${tlsClientCertPath}": ${msg}`);
+        }
+        try {
+            clientKey = fs.readFileSync(tlsClientKeyPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`LibraVDB: failed to load TLS client key from "${tlsClientKeyPath}": ${msg}`);
+        }
+    }
+    return grpc.credentials.createSsl(rootCerts, clientKey, clientCert);
 }
 function extractGrpcHost(target) {
     const withoutDnsPrefix = target.startsWith("dns:///") ? target.slice("dns:///".length) : target;
@@ -54,7 +109,7 @@ export class GrpcKernelClient {
         const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
         const kernelService = protoDescriptor.intelligence_kernel.v1.IntelligenceKernel;
         const target = resolveGrpcTarget(options.endpoint);
-        this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint));
+        this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint, options.tlsCaPath, options.tlsMode, options.tlsClientCertPath, options.tlsClientKeyPath));
     }
     getMetadata(signed = true) {
         const md = new grpc.Metadata();

package/dist/index.js

@@ -8810,14 +8810,14 @@ var require_tls_helpers = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.CIPHER_SUITES = void 0;
     exports2.getDefaultRootsData = getDefaultRootsData;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     exports2.CIPHER_SUITES = process.env.GRPC_SSL_CIPHER_SUITES;
     var DEFAULT_ROOTS_FILE_PATH = process.env.GRPC_DEFAULT_SSL_ROOTS_FILE_PATH;
     var defaultRootsData = null;
     function getDefaultRootsData() {
       if (DEFAULT_ROOTS_FILE_PATH) {
         if (defaultRootsData === null) {
-          defaultRootsData = fs4.readFileSync(DEFAULT_ROOTS_FILE_PATH);
+          defaultRootsData = fs5.readFileSync(DEFAULT_ROOTS_FILE_PATH);
         }
         return defaultRootsData;
       }
@@ -14324,7 +14324,7 @@ var require_fetch = __commonJS({
     module2.exports = fetch;
     var asPromise = require_aspromise();
     var inquire2 = require_inquire();
-    var fs4 = inquire2("fs");
+    var fs5 = inquire2("fs");
     function fetch(filename, options, callback) {
       if (typeof options === "function") {
         callback = options;
@@ -14333,8 +14333,8 @@ var require_fetch = __commonJS({
         options = {};
       if (!callback)
         return asPromise(fetch, this, filename, options);
-      if (!options.xhr && fs4 && fs4.readFile)
-        return fs4.readFile(filename, function fetchReadFileCallback(err, contents) {
+      if (!options.xhr && fs5 && fs5.readFile)
+        return fs5.readFile(filename, function fetchReadFileCallback(err, contents) {
           return err && typeof XMLHttpRequest !== "undefined" ? fetch.xhr(filename, options, callback) : err ? callback(err) : callback(null, options.binary ? contents : contents.toString("utf8"));
         });
       return fetch.xhr(filename, options, callback);
@@ -20608,7 +20608,7 @@ var require_util2 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.addCommonProtos = exports2.loadProtosWithOptionsSync = exports2.loadProtosWithOptions = void 0;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var path5 = __require("path");
     var Protobuf = require_protobufjs();
     function addIncludePathResolver(root, includePaths) {
@@ -20620,7 +20620,7 @@ var require_util2 = __commonJS({
         for (const directory of includePaths) {
           const fullPath = path5.join(directory, target);
           try {
-            fs4.accessSync(fullPath, fs4.constants.R_OK);
+            fs5.accessSync(fullPath, fs5.constants.R_OK);
             return fullPath;
           } catch (err) {
             continue;
@@ -30442,7 +30442,7 @@ var require_certificate_provider = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.FileWatcherCertificateProvider = void 0;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var logging = require_logging();
     var constants_1 = require_constants();
     var util_1 = __require("util");
@@ -30450,7 +30450,7 @@ var require_certificate_provider = __commonJS({
     function trace(text) {
       logging.trace(constants_1.LogVerbosity.DEBUG, TRACER_NAME, text);
     }
-    var readFilePromise = (0, util_1.promisify)(fs4.readFile);
+    var readFilePromise = (0, util_1.promisify)(fs5.readFile);
     var FileWatcherCertificateProvider = class {
       constructor(config) {
         this.config = config;
@@ -39661,21 +39661,63 @@ var protoLoader = __toESM(require_src2(), 1);
 import { createHmac } from "node:crypto";
 import path3 from "node:path";
 import { fileURLToPath } from "node:url";
+import fs3 from "node:fs";
 var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
 var PROTO_PATH = path3.resolve(__dirname2, "./proto/intelligence_kernel/v1/kernel.proto");
 function resolveGrpcTarget(endpoint) {
   return endpoint.startsWith("tcp:") ? endpoint.substring(4) : endpoint;
 }
-function resolveGrpcCredentialMode(endpoint) {
+function resolveGrpcCredentialMode(endpoint, tlsMode) {
+  if (tlsMode === "tls") return "tls";
+  if (tlsMode === "insecure") return "insecure";
   const target = resolveGrpcTarget(endpoint).trim();
-  if (target.startsWith("unix:")) {
-    return "insecure";
-  }
+  if (target.startsWith("unix:")) return "insecure";
   const host = extractGrpcHost(target);
   return isLoopbackHost(host) ? "insecure" : "tls";
 }
-function resolveGrpcCredentials(endpoint) {
-  return resolveGrpcCredentialMode(endpoint) === "insecure" ? grpc.credentials.createInsecure() : grpc.credentials.createSsl();
+function resolveGrpcCredentials(endpoint, tlsCaPath, tlsMode, tlsClientCertPath, tlsClientKeyPath) {
+  if (resolveGrpcCredentialMode(endpoint, tlsMode) === "insecure") {
+    return grpc.credentials.createInsecure();
+  }
+  let rootCerts = null;
+  if (tlsCaPath) {
+    try {
+      rootCerts = fs3.readFileSync(tlsCaPath);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `LibraVDB: failed to load TLS CA certificate from "${tlsCaPath}": ${msg}`
+      );
+    }
+  }
+  const hasCert = tlsClientCertPath !== void 0;
+  const hasKey = tlsClientKeyPath !== void 0;
+  if (hasCert !== hasKey) {
+    throw new Error(
+      "LibraVDB: grpcEndpointTlsClientCert and grpcEndpointTlsClientKey must both be set or both be omitted"
+    );
+  }
+  let clientKey = null;
+  let clientCert = null;
+  if (tlsClientCertPath && tlsClientKeyPath) {
+    try {
+      clientCert = fs3.readFileSync(tlsClientCertPath);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `LibraVDB: failed to load TLS client certificate from "${tlsClientCertPath}": ${msg}`
+      );
+    }
+    try {
+      clientKey = fs3.readFileSync(tlsClientKeyPath);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `LibraVDB: failed to load TLS client key from "${tlsClientKeyPath}": ${msg}`
+      );
+    }
+  }
+  return grpc.credentials.createSsl(rootCerts, clientKey, clientCert);
 }
 function extractGrpcHost(target) {
   const withoutDnsPrefix = target.startsWith("dns:///") ? target.slice("dns:///".length) : target;
@@ -39708,7 +39750,13 @@ var GrpcKernelClient = class {
     const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
     const kernelService = protoDescriptor.intelligence_kernel.v1.IntelligenceKernel;
     const target = resolveGrpcTarget(options.endpoint);
-    this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint));
+    this.client = new kernelService(target, resolveGrpcCredentials(
+      options.endpoint,
+      options.tlsCaPath,
+      options.tlsMode,
+      options.tlsClientCertPath,
+      options.tlsClientKeyPath
+    ));
   }
   getMetadata(signed = true) {
     const md = new grpc.Metadata();
@@ -39782,7 +39830,7 @@ var GrpcKernelClient = class {
 };
 
 // src/sidecar.ts
-import fs3 from "node:fs";
+import fs4 from "node:fs";
 import net from "node:net";
 import os3 from "node:os";
 import path4 from "node:path";
@@ -40077,7 +40125,7 @@ function resolveConfiguredEndpoint(cfg) {
 function daemonProvisioningHint() {
   return "If you installed the npm package, install and start libravdbd separately; the package does not provision the daemon binary, ONNX Runtime, or model assets.";
 }
-function defaultEndpoint(platform = process.platform, homeDir = os3.homedir(), pathExists = fs3.existsSync) {
+function defaultEndpoint(platform = process.platform, homeDir = os3.homedir(), pathExists = fs4.existsSync) {
   const envEndpoint = normalizeConfiguredEndpoint(process.env.LIBRAVDB_RPC_ENDPOINT);
   if (envEndpoint) {
     return envEndpoint;
@@ -40178,6 +40226,8 @@ function sleep2(delayMs) {
 import { readFileSync as readFileSync2 } from "node:fs";
 var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var STARTUP_HEALTH_TIMEOUT_MS = 2e3;
+var VALID_TLS_MODES = ["auto", "tls", "insecure"];
+var isTlsModeValid = (m) => VALID_TLS_MODES.includes(m);
 function resolveStartupHealthTimeoutMs(cfg) {
   return Math.max(STARTUP_HEALTH_TIMEOUT_MS, cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS);
 }
@@ -40192,6 +40242,32 @@ function createPluginRuntime(cfg, logger = console) {
     }
     if (!started) {
       started = (async () => {
+        if (cfg.grpcEndpoint) {
+          if (cfg.grpcEndpointTlsMode !== void 0 && !isTlsModeValid(cfg.grpcEndpointTlsMode)) {
+            throw new Error(
+              `LibraVDB: invalid grpcEndpointTlsMode "${cfg.grpcEndpointTlsMode}" \u2014 must be "auto", "tls", or "insecure"`
+            );
+          }
+          const hasClientCert = cfg.grpcEndpointTlsClientCert !== void 0;
+          const hasClientKey = cfg.grpcEndpointTlsClientKey !== void 0;
+          if (hasClientCert !== hasClientKey) {
+            throw new Error(
+              "LibraVDB: grpcEndpointTlsClientCert and grpcEndpointTlsClientKey must both be set or both be omitted"
+            );
+          }
+          if (cfg.grpcEndpointTlsMode === "insecure") {
+            if (cfg.grpcEndpointTlsCa) {
+              logger.warn?.(
+                `LibraVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode is "insecure" \u2014 the CA file will not be used`
+              );
+            }
+            if (cfg.grpcEndpointTlsClientCert) {
+              logger.warn?.(
+                `LibraVDB: grpcEndpointTlsClientCert is set but grpcEndpointTlsMode is "insecure" \u2014 client certificate will not be sent`
+              );
+            }
+          }
+        }
         const sidecar = await startSidecar(cfg, logger);
         const rpc = new RpcClient(sidecar.socket, {
           timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS
@@ -40208,12 +40284,16 @@ function createPluginRuntime(cfg, logger = console) {
         }
         let kernel = null;
         if (cfg.grpcEndpoint) {
+          const secret = loadSecretFromEnv();
           try {
-            const secret = loadSecretFromEnv();
             kernel = new GrpcKernelClient({
               endpoint: cfg.grpcEndpoint,
               secret,
-              timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS
+              timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+              tlsCaPath: cfg.grpcEndpointTlsCa,
+              tlsMode: cfg.grpcEndpointTlsMode,
+              tlsClientCertPath: cfg.grpcEndpointTlsClientCert,
+              tlsClientKeyPath: cfg.grpcEndpointTlsClientKey
             });
           } catch (error) {
             logger.warn?.(`LibraVDB: failed to initialize gRPC kernel client: ${formatError(error)}`);

package/dist/plugin-runtime.d.ts

@@ -4,6 +4,8 @@ import type { LoggerLike, PluginConfig } from "./types.js";
 export type RpcGetter = () => Promise<RpcClient>;
 export declare const DEFAULT_RPC_TIMEOUT_MS = 30000;
 export declare const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+export declare const VALID_TLS_MODES: readonly ["auto", "tls", "insecure"];
+export type ValidTlsMode = typeof VALID_TLS_MODES[number];
 export declare function resolveStartupHealthTimeoutMs(cfg: PluginConfig): number;
 export interface LifecycleHint {
     hook: "before_reset" | "session_end";

package/dist/plugin-runtime.js

@@ -5,6 +5,8 @@ import { formatError } from "./format-error.js";
 import { readFileSync } from "node:fs";
 export const DEFAULT_RPC_TIMEOUT_MS = 30000;
 export const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+export const VALID_TLS_MODES = ["auto", "tls", "insecure"];
+const isTlsModeValid = (m) => VALID_TLS_MODES.includes(m);
 export function resolveStartupHealthTimeoutMs(cfg) {
     return Math.max(STARTUP_HEALTH_TIMEOUT_MS, cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS);
 }
@@ -19,6 +21,30 @@ export function createPluginRuntime(cfg, logger = console) {
         }
         if (!started) {
             started = (async () => {
+                if (cfg.grpcEndpoint) {
+                    if (cfg.grpcEndpointTlsMode !== undefined &&
+                        !isTlsModeValid(cfg.grpcEndpointTlsMode)) {
+                        throw new Error(`LibraVDB: invalid grpcEndpointTlsMode "${cfg.grpcEndpointTlsMode}" — ` +
+                            `must be "auto", "tls", or "insecure"`);
+                    }
+                    const hasClientCert = cfg.grpcEndpointTlsClientCert !== undefined;
+                    const hasClientKey = cfg.grpcEndpointTlsClientKey !== undefined;
+                    if (hasClientCert !== hasClientKey) {
+                        throw new Error("LibraVDB: grpcEndpointTlsClientCert and " +
+                            "grpcEndpointTlsClientKey must both be set or both be omitted");
+                    }
+                    if (cfg.grpcEndpointTlsMode === "insecure") {
+                        if (cfg.grpcEndpointTlsCa) {
+                            logger.warn?.(`LibraVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode ` +
+                                `is "insecure" — the CA file will not be used`);
+                        }
+                        if (cfg.grpcEndpointTlsClientCert) {
+                            logger.warn?.(`LibraVDB: grpcEndpointTlsClientCert is set but ` +
+                                `grpcEndpointTlsMode is "insecure" — client certificate ` +
+                                `will not be sent`);
+                        }
+                    }
+                }
                 const sidecar = await startSidecar(cfg, logger);
                 const rpc = new RpcClient(sidecar.socket, {
                     timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
@@ -37,15 +63,20 @@ export function createPluginRuntime(cfg, logger = console) {
                 }
                 let kernel = null;
                 if (cfg.grpcEndpoint) {
+                    const secret = loadSecretFromEnv();
                     try {
-                        const secret = loadSecretFromEnv();
                         kernel = new GrpcKernelClient({
                             endpoint: cfg.grpcEndpoint,
                             secret,
                             timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+                            tlsCaPath: cfg.grpcEndpointTlsCa,
+                            tlsMode: cfg.grpcEndpointTlsMode,
+                            tlsClientCertPath: cfg.grpcEndpointTlsClientCert,
+                            tlsClientKeyPath: cfg.grpcEndpointTlsClientKey,
                         });
                     }
                     catch (error) {
+                        // Only gRPC init errors land here — config validation already threw above
                         logger.warn?.(`LibraVDB: failed to initialize gRPC kernel client: ${formatError(error)}`);
                     }
                 }

package/dist/types.d.ts

@@ -90,6 +90,23 @@ export interface PluginConfig {
     maxRetries?: number;
     logLevel?: "debug" | "info" | "warn" | "error";
     grpcEndpoint?: string;
+    grpcEndpointTlsCa?: string;
+    /** Path to a client certificate PEM file for mTLS.
+     * The file must contain a PEM-encoded X.509 certificate. Leaf first;
+     * intermediates may follow in the same file. Required when the daemon
+     * requires a client certificate (mTLS). Must be paired with
+     * grpcEndpointTlsClientKey. */
+    grpcEndpointTlsClientCert?: string;
+    /** Path to the client private key PEM file.
+     * Must correspond to the leaf certificate in grpcEndpointTlsClientCert.
+     * Accepts RSA (PKCS#1/PKCS#8), ECDSA (P-256/P-384/P-521), Ed25519.
+     * Required when grpcEndpointTlsClientCert is set. */
+    grpcEndpointTlsClientKey?: string;
+    /** Controls gRPC credential mode.
+     * "auto" (default) — loopback and unix → plaintext, remote → TLS.
+     * "tls"            — always use TLS regardless of address.
+     * "insecure"       — always use plaintext (service mesh, tunnel). */
+    grpcEndpointTlsMode?: "auto" | "tls" | "insecure";
 }
 export interface SearchResult {
     id: string;

package/docs/TLS_configuration.md

@@ -0,0 +1,112 @@
+# TLS Configuration
+
+The plugin selects the right credentials automatically based on which address it connects to. Unix sockets and loopback addresses (localhost, 127.0.0.1, ::1) always use plaintext. All other addresses use TLS. In most deployments no TLS configuration is needed at all. The only time manual configuration is required is when the daemon serves TLS on a loopback address, when the daemon uses a self-signed or private-CA certificate, or when infrastructure such as a service mesh handles TLS outside the plugin.
+
+## Default behavior
+
+The plugin applies the following rules automatically:
+
+| Endpoint type | Credential mode |
+|---|---|
+| Unix socket (`unix:/path/to/socket`) | Plaintext |
+| Loopback (`tcp:127.0.0.1:port`, `tcp:localhost:port`, `[::1]:port`) | Plaintext |
+| Any other TCP or DNS address | TLS |
+
+Because these rules are automatic, most users do not set any TLS-related fields. Plaintext is used where it is safe (local transport) and TLS is used where it is needed (network transport).
+
+## Configuration fields
+
+| Field | Type | Default | When to use |
+|---|---|---|---|
+| `grpcEndpoint` | string | — | The daemon address. Set to a unix socket path, a loopback address, or a remote host. |
+| `grpcEndpointTlsCa` | string | — | Path to a CA certificate PEM file. Required only when the daemon certificate is self-signed or signed by a private CA not in the system certificate store. |
+| `grpcEndpointTlsMode` | `"auto"` \| `"tls"` \| `"insecure"` | `"auto"` | Override the automatic selection. `"auto"` applies the default rules above. `"tls"` forces TLS regardless of address. `"insecure"` forces plaintext regardless of address. |
+
+`grpcEndpointTlsMode` values explained:
+
+- **`"auto"`** (default) — apply the automatic rules. Unix sockets and loopback use plaintext; all other addresses use TLS.
+- **`"tls"`** — always use TLS, even for loopback addresses. Use this when the daemon has TLS enabled on a loopback address.
+- **`"insecure"`** — always use plaintext, even for remote addresses. Use this only when a service mesh or TLS-terminating tunnel handles encryption externally.
+
+## Deployment scenarios
+
+### Local daemon (default)
+
+The daemon runs on the same machine, listening on a unix socket or a loopback address.
+
+```json
+{
+  "grpcEndpoint": "unix:/home/user/.libravdbd/run/libravdb.sock"
+}
+```
+
+or:
+
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090"
+}
+```
+
+The plugin automatically uses plaintext. No TLS fields are needed.
+
+### Remote daemon with a trusted certificate
+
+The daemon runs on a remote host and presents a certificate issued by a public CA such as Let's Encrypt or cert-manager.
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.k8s.internal:9090"
+}
+```
+
+TLS is automatic. The plugin uses the system certificate store to verify the daemon's certificate, so no additional configuration is needed.
+
+### Remote daemon with a self-signed or private CA certificate
+
+The daemon runs on a remote host and uses a self-signed certificate or a certificate signed by a private/internal CA not in the system certificate store.
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.internal:9090",
+  "grpcEndpointTlsCa": "/etc/certs/company-ca.pem"
+}
+```
+
+The CA certificate must be the certificate of the CA that signed the daemon's server certificate — not the server certificate itself. The plugin uses this CA to verify the daemon's certificate during the TLS handshake. Without it, the plugin will reject the daemon's certificate as untrusted.
+
+### TLS on a loopback address
+
+The daemon has TLS enabled on a loopback address. This is uncommon. The automatic rules would select plaintext for a loopback address, so an explicit override is required.
+
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090",
+  "grpcEndpointTlsMode": "tls"
+}
+```
+
+Set `grpcEndpointTlsMode` to `"tls"` to force the plugin to use TLS even on the loopback address. The plugin will use the system certificate store for verification. If the daemon uses a self-signed certificate, add `grpcEndpointTlsCa` as well.
+
+## Service mesh and tunnels
+
+When the daemon runs behind Istio, Envoy, or any other infrastructure that terminates TLS at the mesh or tunnel layer, the plugin should not attempt its own TLS. Set `grpcEndpointTlsMode` to `"insecure"` so the plugin uses plaintext and lets the mesh handle encryption:
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.mesh.svc:9090",
+  "grpcEndpointTlsMode": "insecure"
+}
+```
+
+This applies even for remote addresses. The mesh terminates TLS at the boundary, and the plugin communicates with the mesh over plaintext on the inside.
+
+## Error reference
+
+| Error | Likely cause | Fix |
+|---|---|---|
+| `UNAVAILABLE / connection closed / TLS handshake failed` when connecting to a loopback address | The daemon has TLS enabled on a loopback address but the plugin is using plaintext (the default for loopback). | Add `"grpcEndpointTlsMode": "tls"` to the plugin config. |
+| `x509: certificate signed by unknown authority` | The daemon uses a self-signed certificate or a certificate from a private CA not trusted by the system. | Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file that signed the daemon's server certificate. |
+| `failed to load TLS CA certificate from "...": ENOENT: no such file or directory` | The file path given in `grpcEndpointTlsCa` does not exist on the machine. | Verify the file path is correct and the CA certificate file exists. |
+| `LibraVDB: invalid grpcEndpointTlsMode "..."` | The value set in `grpcEndpointTlsMode` is not one of the accepted values. | Change the value to `"auto"`, `"tls"`, or `"insecure"`. |
+| `LIBRAVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode is "insecure"` (warning) | Both `grpcEndpointTlsCa` and `grpcEndpointTlsMode: "insecure"` are set. The CA file will not be used. | Remove `grpcEndpointTlsCa` if plaintext is intended, or change `grpcEndpointTlsMode` to `"auto"` or `"tls"` to use the CA file. |

package/docs/configuration.md

@@ -12,10 +12,60 @@ CPU when a provider is unavailable.
 | Key | Type | Default | Notes |
 |---|---|---|---|
 | `sidecarPath` | string | `auto` | `"auto"` probes standard socket paths; set `unix:/path` or `tcp:host:port` to override |
-| `grpcEndpoint` | string | — | Optional gRPC kernel endpoint for hosts using the gRPC kernel transport |
+| `grpcEndpoint` | string | — | gRPC kernel endpoint. See `grpcEndpointTlsMode` for credential control. |
+| `grpcEndpointTlsCa` | string | — | Path to CA certificate PEM file. Only needed for self-signed or private CA certs. Omit when using Let's Encrypt or cert-manager. |
+| `grpcEndpointTlsMode` | string | `"auto"` | gRPC credential mode. `"auto"`: loopback/unix → plaintext, remote → TLS. `"tls"`: always TLS. `"insecure"`: always plaintext. |
 | `rpcTimeoutMs` | number | `30000` | Per-call timeout for service RPC (ms) |
 | `dbPath` | string | auto-named | Explicit DB path; when set bypasses model-specific naming |
 
+### gRPC TLS behavior
+
+The plugin selects credentials automatically based on the endpoint:
+
+| Endpoint format | Credential mode |
+|---|---|
+| `unix:/path/to/sock` | Plaintext (local) |
+| `tcp:127.0.0.1:port` / `tcp:localhost:port` / `[::1]:port` | Plaintext (loopback) |
+| Any other TCP or DNS target | TLS |
+
+Use `grpcEndpointTlsMode` to override the default behavior:
+
+| Value | When to use |
+|---|---|
+| `"auto"` (default) | Standard operation — plugin heuristic matches daemon TLS setting automatically. |
+| `"tls"` | Daemon has TLS enabled on loopback or unix socket (rare; use when the daemon's `LIBRAVDB_GRPC_TLS_*` env vars are set on a local address). |
+| `"insecure"` | Service mesh or TLS-terminating tunnel handles encryption externally; both sides are plaintext. |
+
+**Default (local daemon):** No TLS configuration needed.
+Unix socket and loopback endpoints are always plaintext regardless
+of any TLS settings.
+
+**K8 / remote daemon with CA-issued cert:**
+No extra configuration needed. The plugin uses the system CA pool,
+which trusts certs issued by Let's Encrypt, cert-manager, and
+other public CAs automatically.
+
+**Remote daemon with self-signed or private CA cert:**
+Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file:
+```json
+{
+  "grpcEndpoint": "tcp:yourdaemon.internal:50051",
+  "grpcEndpointTlsCa": "/etc/certs/ca.pem"
+}
+```
+The daemon must be configured with matching TLS cert and key via
+`LIBRAVDB_GRPC_TLS_CERT` and `LIBRAVDB_GRPC_TLS_KEY`.
+
+**Local daemon with TLS enabled:**
+If the daemon has `LIBRAVDB_GRPC_TLS_CERT`/`LIBRAVDB_GRPC_TLS_KEY` set on a loopback
+address, explicitly set `grpcEndpointTlsMode: "tls"` to match:
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090",
+  "grpcEndpointTlsMode": "tls"
+}
+```
+
 ## Embedding
 
 | Key | Type | Default | Notes |

package/docs/mTLS_configuration.md

@@ -0,0 +1,78 @@
+# mTLS Configuration
+
+The plugin supports mutual TLS (mTLS) for gRPC connections to the Vector Service. In mTLS, both the client and the server present X.509 certificates, and each side verifies the other's certificate against a trusted CA. When the Vector Service is configured with a client CA, it will reject any client that does not present a valid certificate signed by that CA.
+
+## When mTLS is required
+
+The Vector Service operator enables mTLS by configuring a client CA on the service side. When this is enabled, the Vector Service requires every connecting client to present a certificate signed by that CA. If the plugin is configured to use TLS but does not present a client certificate, the TLS handshake will fail and the connection will be rejected.
+
+The plugin cannot detect whether the daemon requires mTLS — it must be configured explicitly. If connections fail with a "client did not provide a certificate" error, the plugin likely needs a client certificate configured.
+
+## Configuration fields
+
+| Field | Type | When to use |
+|---|---|---|
+| `grpcEndpointTlsClientCert` | string (file path) | Path to a PEM-encoded X.509 client certificate. Required when the Vector Service requires a client certificate. |
+| `grpcEndpointTlsClientKey` | string (file path) | Path to the PEM-encoded private key that corresponds to the certificate. Required when `grpcEndpointTlsClientCert` is set. |
+
+Both fields must be set together or not at all. Setting one without the other will cause a configuration error at startup.
+
+These fields only take effect when the connection uses TLS — that is, when `grpcEndpointTlsMode` is not `"insecure"` and the endpoint is not a loopback address or Unix socket. See [TLS configuration](./TLS_configuration.md) for the full TLS behavior reference.
+
+## Certificate requirements
+
+- **Format**: PEM-encoded X.509 certificate (-----BEGIN CERTIFICATE-----)
+- **Chain order**: Leaf certificate must be first in the file; intermediate certificates may follow in the same file
+- **Signing**: The certificate must be signed by the CA that the Vector Service operator configured as the client CA
+- **Key types accepted**:
+  - RSA (any key size)
+  - ECDSA (P-256, P-384, P-521)
+  - Ed25519
+- **Key file format**: PEM-encoded private key (-----BEGIN PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY----- etc.)
+- **Key/cert match**: The private key must correspond to the leaf certificate's public key
+- **Revocation**: The Vector Service does not perform revocation checking. Expired certificates are rejected (`NotAfter` boundary). Revoked but unexpired certificates are not detected. Keep certificate lifetimes short.
+
+## Example configuration
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.internal:9090",
+  "grpcEndpointTlsCa": "/etc/certs/company-ca.pem",
+  "grpcEndpointTlsClientCert": "/etc/certs/plugin-client.crt",
+  "grpcEndpointTlsClientKey": "/etc/certs/plugin-client.key"
+}
+```
+
+This example shows all four gRPC TLS fields configured together for a remote Vector Service that uses a private CA and requires mTLS.
+
+## Generating a client certificate (quick reference)
+
+The following example shows OpenSSL commands to generate a client key, create a CSR, and sign it with a private CA. This is for illustration only — operators may use cert-manager, Vault, step, or other PKI tooling instead.
+
+**1. Create a client private key:**
+```bash
+openssl genpkey -algorithm ED25519 -out client.key
+```
+
+**2. Create a certificate signing request (CSR):**
+```bash
+openssl req -new -key client.key -out client.csr -subj "/CN=openclaw-plugin/O=LibraVDB"
+```
+
+**3. Sign the CSR with the private CA:**
+```bash
+openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
+  -CAcreateserial -out client.crt -days 365
+```
+
+Replace `ca.crt` and `ca.key` with the CA certificate and key that the daemon operator provided.
+
+## Error reference
+
+| Error | Likely cause | Fix |
+|---|---|---|
+| `tls: client did not provide a certificate` | mTLS is required by the Vector Service, but no client certificate is configured in the plugin | Set `grpcEndpointTlsClientCert` and `grpcEndpointTlsClientKey` in the plugin config |
+| `tls: failed to verify client certificate: x509: certificate signed by unknown authority` | The client certificate is not signed by the Vector Service's client CA | Obtain a certificate signed by the CA the Vector Service operator configured as the client CA |
+| `LibraVDB: failed to load TLS client certificate from "...": ENOENT: no such file or directory` | The certificate file path does not exist or is not readable | Verify the path set in `grpcEndpointTlsClientCert` exists and has correct permissions |
+| `LibraVDB: failed to load TLS client key from "...": ENOENT: no such file or directory` | The key file path does not exist or is not readable | Verify the path set in `grpcEndpointTlsClientKey` exists and has correct permissions |
+| `LibraVDB: grpcEndpointTlsClientCert and grpcEndpointTlsClientKey must both be set or both be omitted` | Only one of the two fields is set | Set both fields or remove both from the configuration |

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.4.80",
+  "version": "1.5.1",
   "kind": [
     "memory",
     "context-engine"
@@ -46,6 +46,27 @@
         "type": "string",
         "description": "Optional gRPC kernel endpoint for hosts using the daemon kernel transport."
       },
+      "grpcEndpointTlsCa": {
+        "type": "string",
+        "description": "Path to a CA certificate PEM file for verifying the daemon's TLS certificate. Only needed for self-signed or private CA certificates. Not required when using a publicly trusted certificate (Let's Encrypt, cert-manager, etc)."
+      },
+      "grpcEndpointTlsClientCert": {
+        "type": "string",
+        "description": "Path to a PEM-encoded X.509 client certificate for mTLS. Required when the daemon requires a client certificate. Must be paired with grpcEndpointTlsClientKey."
+      },
+      "grpcEndpointTlsClientKey": {
+        "type": "string",
+        "description": "Path to the client private key PEM file. Required when grpcEndpointTlsClientCert is set. Accepts RSA, ECDSA (P-256/P-384/P-521), Ed25519 keys."
+      },
+      "grpcEndpointTlsMode": {
+        "type": "string",
+        "enum": [
+          "auto",
+          "tls",
+          "insecure"
+        ],
+        "description": "gRPC credential mode. auto (default): loopback and unix socket use plaintext, remote addresses use TLS. tls: always use TLS regardless of address. insecure: always use plaintext (use with service mesh or tunnel that handles TLS externally)."
+      },
       "authoredHardBudgetFraction": {
         "type": "number",
         "minimum": 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.4.80",
+  "version": "1.5.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,7 +43,7 @@
       "pluginSdkVersion": "2026.4.11"
     },
     "install": {
-      "minHostVersion": ">=2026.3.22"
+      "minHostVersion": ">=2026.4.11"
     }
   },
   "scripts": {