@simonsbs/keylore 1.0.0-rc4 → 1.0.0-rc5

package/.env.example

@@ -1,4 +1,8 @@
-KEYLORE_DATABASE_URL=postgresql://keylore:keylore@127.0.0.1:5432/keylore
+KEYLORE_DATABASE_MODE=local
+KEYLORE_LOCAL_DATABASE_FILE=keylore.db
+# Optional advanced override:
+# KEYLORE_DATABASE_MODE=postgres
+# KEYLORE_DATABASE_URL=postgresql://keylore:keylore@127.0.0.1:5432/keylore
 KEYLORE_DATABASE_POOL_MAX=10
 KEYLORE_AUTH_CLIENTS_FILE=auth-clients.json
 KEYLORE_LOCAL_SECRETS_FILE=local-secrets.enc.json

package/README.md

@@ -22,7 +22,7 @@ This repository is incubating privately today, but it is structured to be publis
 - MCP server for `stdio` and Streamable HTTP
 - metadata-only catalogue search and retrieval tools
 - default-deny policy engine with domain and operation constraints
-- PostgreSQL-backed catalogue, policy, and audit persistence with startup migrations
+- file-backed local persistence by default with startup migrations, plus explicit PostgreSQL support for advanced deployments
 - OAuth-style client credentials token issuance for remote HTTP and MCP access
 - PKCE-bound `authorization_code` plus rotating `refresh_token` support for interactive public or confidential clients
 - protected-resource metadata for REST and MCP surfaces
@@ -64,13 +64,13 @@ This repository is incubating privately today, but it is structured to be publis
 
 ## What is intentionally deferred
 
-The full `KeyLore.md` specification is broader than a sane `v1.0.0-rc4` delivery. The main remaining work before `v1.0.0` is:
+The full `KeyLore.md` specification is broader than a sane `v1.0.0-rc5` delivery. The main remaining work before `v1.0.0` is:
 
 - public release polish and final operator documentation cleanup
 
 Those items are tracked in [docs/roadmap.md](/home/simon/keylore/docs/roadmap.md) and mapped back to the spec in [docs/keylore-spec-map.md](/home/simon/keylore/docs/keylore-spec-map.md).
 
-The active post-`v1.0.0-rc4` refocus is documented in [docs/core-mode-plan.md](/home/simon/keylore/docs/core-mode-plan.md): make the default user journey "add secret, add context, connect MCP, use it" and push broader operator features behind an advanced path.
+The active post-`v1.0.0-rc5` refocus is documented in [docs/core-mode-plan.md](/home/simon/keylore/docs/core-mode-plan.md): make the default user journey "add secret, add context, connect MCP, use it" and push broader operator features behind an advanced path.
 
 The handoff from local core mode to advanced self-hosted mode is documented in [docs/production-handoff.md](/home/simon/keylore/docs/production-handoff.md).
 
@@ -88,14 +88,16 @@ npm install
 npm run quickstart
 ```
 
+That starts KeyLore in the background. Use `keylore-http status`, `keylore-http stop`, and `keylore-http restart` to manage it later. Use `keylore-http run` only when you intentionally want the server attached to the terminal for debugging.
+
 For a clean Linux VM install from npm instead of cloning the repo:
 
 ```bash
 npm install -g @simonsbs/keylore@next
-keylore-http
+keylore-http start
 ```
 
-That starts KeyLore from the packaged migrations and seed data, while writable state defaults to `~/.keylore`.
+That starts KeyLore from the packaged migrations and seed data with no Docker or external PostgreSQL required. Writable state defaults to `~/.keylore`.
 
 To simulate a brand-new user install on the same machine without reusing your normal checkout or shell environment:
 
@@ -105,8 +107,8 @@ npm run ops:fresh-user-env
 
 That launches an isolated disposable user, a fresh clone, and a separate KeyLore UI port for onboarding and MCP testing. By default it clones from the current local repo source so it also works while the repo is private.
 
-This starts local PostgreSQL, waits for readiness, and boots KeyLore at `http://127.0.0.1:8787`.
-If KeyLore is already running locally on that port, the command reuses the existing instance instead of failing.
+This boots KeyLore at `http://127.0.0.1:8787` with a local embedded database and encrypted local secret store.
+If KeyLore is already running locally, the command reuses the existing background instance instead of failing.
 
 3. Open KeyLore in your browser:
 
@@ -164,12 +166,14 @@ KEYLORE_SANDBOX_COMMAND_ALLOWLIST=/usr/bin/env,node
 
 ## Advanced local usage
 
-Start PostgreSQL only:
+If you want production-style external persistence locally, start PostgreSQL first:
 
 ```bash
 npm run db:up
 ```
 
+Then either set `KEYLORE_DATABASE_MODE=postgres` and `KEYLORE_DATABASE_URL=...` in `.env`, or export them for one run.
+
 Start the HTTP server directly:
 
 ```bash

package/bin/keylore-http.js

@@ -1,3 +1,11 @@
 #!/usr/bin/env node
-process.argv.push("--transport", "http");
-await import("../dist/index.js");
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+const runtimeEntryPath = path.resolve(binDir, "../dist/index.js");
+const serviceManagerPath = path.resolve(binDir, "../dist/http-service.js");
+
+const { runHttpServiceCommand } = await import(serviceManagerPath);
+const exitCode = await runHttpServiceCommand(process.argv.slice(2), runtimeEntryPath);
+process.exit(exitCode);

package/dist/app.js

@@ -38,13 +38,13 @@ import { TenantService } from "./services/tenant-service.js";
 import { TraceExportService } from "./services/trace-export-service.js";
 import { TraceService } from "./services/trace-service.js";
 import { bootstrapFromFiles } from "./storage/bootstrap.js";
-import { createPostgresDatabase } from "./storage/database.js";
+import { createSqlDatabase } from "./storage/database.js";
 import { runMigrations } from "./storage/migrations.js";
 import { SandboxRunner } from "./runtime/sandbox-runner.js";
 export async function createKeyLoreApp() {
     const config = loadConfig();
     const logger = pino({ name: config.appName, level: config.logLevel });
-    const database = createPostgresDatabase(config);
+    const database = await createSqlDatabase(config);
     const telemetry = new TelemetryService();
     const traces = new TraceService(config.traceCaptureEnabled, config.traceRecentSpanLimit);
     const traceExports = new TraceExportService(config.traceExportUrl, config.traceExportAuthHeader, config.traceExportBatchSize, config.traceExportIntervalMs, config.traceExportTimeoutMs, telemetry);

package/dist/config.js

@@ -3,7 +3,6 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as z from "zod/v4";
-const LOCAL_DATABASE_URL = "postgresql://keylore:keylore@127.0.0.1:5432/keylore";
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const LOCAL_ADMIN_CLIENT_ID = "keylore-admin-local";
 const LOCAL_ADMIN_CLIENT_SECRET = "keylore-local-admin";
@@ -73,9 +72,6 @@ function hydrateEnvironment(cwd) {
         ...fileEnv,
         ...process.env,
     };
-    if (isMissing(effectiveEnv.KEYLORE_DATABASE_URL)) {
-        effectiveEnv.KEYLORE_DATABASE_URL = LOCAL_DATABASE_URL;
-    }
     const environment = effectiveEnv.KEYLORE_ENVIRONMENT?.trim() || "development";
     const httpHost = effectiveEnv.KEYLORE_HTTP_HOST?.trim() || "127.0.0.1";
     const bootstrapFromFiles = effectiveEnv.KEYLORE_BOOTSTRAP_FROM_FILES !== "false";
@@ -113,14 +109,16 @@ function resolveDefaultDataDir(cwd) {
     return path.join(os.homedir(), ".keylore");
 }
 const envSchema = z.object({
+    KEYLORE_DATABASE_MODE: z.enum(["local", "postgres"]).optional(),
     KEYLORE_DATA_DIR: z.string().optional(),
     KEYLORE_CATALOG_FILE: z.string().optional(),
     KEYLORE_POLICY_FILE: z.string().optional(),
     KEYLORE_AUTH_CLIENTS_FILE: z.string().optional(),
     KEYLORE_MIGRATIONS_DIR: z.string().optional(),
+    KEYLORE_LOCAL_DATABASE_FILE: z.string().optional(),
     KEYLORE_LOCAL_SECRETS_FILE: z.string().optional(),
     KEYLORE_LOCAL_SECRETS_KEY_FILE: z.string().optional(),
-    KEYLORE_DATABASE_URL: z.string().min(1),
+    KEYLORE_DATABASE_URL: optionalString,
     KEYLORE_DATABASE_POOL_MAX: z.coerce.number().int().min(1).max(100).default(10),
     KEYLORE_HTTP_HOST: z.string().default("127.0.0.1"),
     KEYLORE_HTTP_PORT: z.coerce.number().int().min(1).max(65535).default(8787),
@@ -196,22 +194,28 @@ export function loadConfig(cwd = process.cwd()) {
     const env = envSchema.parse(hydrated.env);
     const runtimeRoot = resolveRuntimeRoot(cwd);
     const dataDir = path.resolve(env.KEYLORE_DATA_DIR ?? resolveDefaultDataDir(cwd));
+    const databaseMode = env.KEYLORE_DATABASE_MODE ?? (env.KEYLORE_DATABASE_URL ? "postgres" : "local");
     const publicBaseUrl = env.KEYLORE_PUBLIC_BASE_URL ?? `http://${env.KEYLORE_HTTP_HOST}:${env.KEYLORE_HTTP_PORT}`;
     const oauthIssuerUrl = env.KEYLORE_OAUTH_ISSUER_URL ?? `${publicBaseUrl}/oauth`;
     const localQuickstartEnabled = env.KEYLORE_ENVIRONMENT !== "production" &&
         env.KEYLORE_BOOTSTRAP_FROM_FILES &&
         isLoopbackHost(env.KEYLORE_HTTP_HOST);
+    if (databaseMode === "postgres" && isMissing(env.KEYLORE_DATABASE_URL)) {
+        throw new Error("KEYLORE_DATABASE_URL is required when KEYLORE_DATABASE_MODE=postgres.");
+    }
     return {
         appName: "keylore",
-        version: "1.0.0-rc4",
+        version: "1.0.0-rc5",
         dataDir,
         bootstrapCatalogPath: path.resolve(runtimeRoot, "data", env.KEYLORE_CATALOG_FILE ?? "catalog.json"),
         bootstrapPolicyPath: path.resolve(runtimeRoot, "data", env.KEYLORE_POLICY_FILE ?? "policies.json"),
         bootstrapAuthClientsPath: path.resolve(runtimeRoot, "data", env.KEYLORE_AUTH_CLIENTS_FILE ?? "auth-clients.json"),
         migrationsDir: path.resolve(runtimeRoot, env.KEYLORE_MIGRATIONS_DIR ?? "migrations"),
+        databaseMode,
+        localDatabasePath: path.resolve(dataDir, env.KEYLORE_LOCAL_DATABASE_FILE ?? "keylore.db"),
         localSecretsFilePath: path.resolve(dataDir, env.KEYLORE_LOCAL_SECRETS_FILE ?? "local-secrets.enc.json"),
         localSecretsKeyPath: path.resolve(dataDir, env.KEYLORE_LOCAL_SECRETS_KEY_FILE ?? "local-secrets.key"),
-        databaseUrl: env.KEYLORE_DATABASE_URL,
+        databaseUrl: env.KEYLORE_DATABASE_URL || undefined,
         databasePoolMax: env.KEYLORE_DATABASE_POOL_MAX,
         httpHost: env.KEYLORE_HTTP_HOST,
         httpPort: env.KEYLORE_HTTP_PORT,

package/dist/http-service.js

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+function resolvePaths() {
+    const serviceDir = path.join(os.homedir(), ".keylore", "service");
+    return {
+        serviceDir,
+        metadataFile: path.join(serviceDir, "http-service.json"),
+        logFile: path.join(serviceDir, "http-service.log"),
+    };
+}
+async function ensureServiceDir(paths) {
+    await fsp.mkdir(paths.serviceDir, { recursive: true });
+}
+async function readMetadata(paths) {
+    try {
+        const raw = await fsp.readFile(paths.metadataFile, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+        }
+        return undefined;
+    }
+}
+async function writeMetadata(paths, metadata) {
+    await ensureServiceDir(paths);
+    await fsp.writeFile(paths.metadataFile, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+}
+async function removeMetadata(paths) {
+    await fsp.rm(paths.metadataFile, { force: true });
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shouldPreferCurrentCwd(cwd) {
+    return (fs.existsSync(path.join(cwd, ".env")) ||
+        (fs.existsSync(path.join(cwd, "data")) && fs.existsSync(path.join(cwd, "migrations"))));
+}
+async function resolveLaunchCwd(paths, preferredCwd) {
+    const cwd = process.cwd();
+    if (shouldPreferCurrentCwd(cwd)) {
+        return cwd;
+    }
+    if (preferredCwd) {
+        return preferredCwd;
+    }
+    const metadata = await readMetadata(paths);
+    if (metadata?.cwd) {
+        return metadata.cwd;
+    }
+    return cwd;
+}
+async function stopPid(pid) {
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        return;
+    }
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        if (!isRunning(pid)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        return;
+    }
+}
+export async function runHttpServiceCommand(argv, runtimeEntryPath) {
+    const command = argv[0] ?? "start";
+    const paths = resolvePaths();
+    if (command === "run") {
+        const child = spawn(process.execPath, [runtimeEntryPath, "--transport", "http"], {
+            cwd: await resolveLaunchCwd(paths),
+            env: process.env,
+            stdio: "inherit",
+        });
+        const exitCode = await new Promise((resolve) => {
+            child.on("exit", (code, signal) => {
+                if (signal) {
+                    resolve(1);
+                    return;
+                }
+                resolve(code ?? 0);
+            });
+        });
+        return exitCode;
+    }
+    if (command === "status") {
+        const metadata = await readMetadata(paths);
+        if (!metadata || !isRunning(metadata.pid)) {
+            await removeMetadata(paths);
+            process.stdout.write("KeyLore HTTP is not running.\n");
+            return 0;
+        }
+        process.stdout.write(`KeyLore HTTP is running.\nPID: ${metadata.pid}\nWorking directory: ${metadata.cwd}\nLog: ${metadata.logFile}\nStarted: ${metadata.startedAt}\n`);
+        return 0;
+    }
+    if (command === "stop") {
+        const metadata = await readMetadata(paths);
+        if (!metadata || !isRunning(metadata.pid)) {
+            await removeMetadata(paths);
+            process.stdout.write("KeyLore HTTP is not running.\n");
+            return 0;
+        }
+        await stopPid(metadata.pid);
+        await removeMetadata(paths);
+        process.stdout.write("KeyLore HTTP stopped.\n");
+        return 0;
+    }
+    let rememberedCwd;
+    if (command === "restart") {
+        const metadata = await readMetadata(paths);
+        rememberedCwd = metadata?.cwd;
+        if (metadata && isRunning(metadata.pid)) {
+            await stopPid(metadata.pid);
+            await removeMetadata(paths);
+        }
+        else {
+            await removeMetadata(paths);
+        }
+    }
+    else if (command !== "start") {
+        process.stderr.write("Usage: keylore-http [start|stop|restart|status|run]\n");
+        return 1;
+    }
+    const existing = await readMetadata(paths);
+    if (existing && isRunning(existing.pid)) {
+        process.stdout.write(`KeyLore HTTP is already running in the background.\nPID: ${existing.pid}\nLog: ${existing.logFile}\n`);
+        return 0;
+    }
+    await ensureServiceDir(paths);
+    const cwd = await resolveLaunchCwd(paths, rememberedCwd);
+    const logHandle = await fsp.open(paths.logFile, "a");
+    const child = spawn(process.execPath, [runtimeEntryPath, "--transport", "http"], {
+        cwd,
+        env: process.env,
+        detached: true,
+        stdio: ["ignore", logHandle.fd, logHandle.fd],
+    });
+    child.unref();
+    await logHandle.close();
+    const metadata = {
+        cwd,
+        pid: child.pid ?? 0,
+        logFile: paths.logFile,
+        startedAt: new Date().toISOString(),
+    };
+    await writeMetadata(paths, metadata);
+    process.stdout.write(`KeyLore HTTP started in the background.\nPID: ${metadata.pid}\nWorking directory: ${metadata.cwd}\nLog: ${metadata.logFile}\n`);
+    return 0;
+}

package/dist/storage/database.js

@@ -1,3 +1,6 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { PGlite } from "@electric-sql/pglite";
 import { Pool } from "pg";
 class PostgresDatabase {
     pool;
@@ -7,11 +10,20 @@ class PostgresDatabase {
     async query(text, params) {
         return this.pool.query(text, params);
     }
+    async exec(text) {
+        await this.pool.query(text);
+    }
     async withTransaction(fn) {
         const client = await this.pool.connect();
         try {
             await client.query("BEGIN");
-            const result = await fn(client);
+            const transactionalClient = {
+                query: (text, params) => client.query(text, params),
+                exec: async (text) => {
+                    await client.query(text);
+                },
+            };
+            const result = await fn(transactionalClient);
             await client.query("COMMIT");
             return result;
         }
@@ -30,10 +42,81 @@ class PostgresDatabase {
         await this.pool.end();
     }
 }
-export function createPostgresDatabase(config) {
+class LocalDatabase {
+    database;
+    queue = Promise.resolve();
+    constructor(database) {
+        this.database = database;
+    }
+    enqueue(fn) {
+        const next = this.queue.then(fn, fn);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    normalize(result) {
+        const rows = result.rows;
+        return {
+            command: "",
+            rowCount: result.affectedRows && result.affectedRows > 0 ? result.affectedRows : rows.length,
+            oid: 0,
+            rows,
+            fields: (result.fields ?? []),
+        };
+    }
+    async query(text, params) {
+        return this.enqueue(async () => this.normalize(await this.database.query(text, params)));
+    }
+    async exec(text) {
+        await this.enqueue(async () => {
+            await this.database.exec(text);
+        });
+    }
+    async withTransaction(fn) {
+        return this.enqueue(async () => {
+            await this.database.exec("BEGIN");
+            const client = {
+                query: async (text, params) => this.normalize(await this.database.query(text, params)),
+                exec: async (text) => {
+                    await this.database.exec(text);
+                },
+            };
+            try {
+                const result = await fn(client);
+                await this.database.exec("COMMIT");
+                return result;
+            }
+            catch (error) {
+                await this.database.exec("ROLLBACK");
+                throw error;
+            }
+        });
+    }
+    async healthcheck() {
+        await this.enqueue(async () => {
+            await this.database.query("SELECT 1");
+        });
+    }
+    async close() {
+        await this.enqueue(async () => {
+            await this.database.close();
+        });
+    }
+}
+function createPostgresDatabase(config) {
     const pool = new Pool({
         connectionString: config.databaseUrl,
         max: config.databasePoolMax,
     });
     return new PostgresDatabase(pool);
 }
+async function createLocalDatabase(config) {
+    await fs.mkdir(path.dirname(config.localDatabasePath), { recursive: true });
+    const database = new PGlite(config.localDatabasePath);
+    return new LocalDatabase(database);
+}
+export async function createSqlDatabase(config) {
+    if (config.databaseMode === "postgres") {
+        return createPostgresDatabase(config);
+    }
+    return createLocalDatabase(config);
+}

package/dist/storage/in-memory-database.js

@@ -7,11 +7,20 @@ class InMemoryDatabase {
     async query(text, params) {
         return this.pool.query(text, params);
     }
+    async exec(text) {
+        await this.pool.query(text);
+    }
     async withTransaction(fn) {
         const client = await this.pool.connect();
         try {
             await client.query("BEGIN");
-            const result = await fn(client);
+            const transactionalClient = {
+                query: (text, params) => client.query(text, params),
+                exec: async (text) => {
+                    await client.query(text);
+                },
+            };
+            const result = await fn(transactionalClient);
             await client.query("COMMIT");
             return result;
         }

package/dist/storage/migrations.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 export async function runMigrations(database, migrationsDir) {
-    await database.query(`
+    await database.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
       version TEXT PRIMARY KEY,
       applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
@@ -20,7 +20,7 @@ export async function runMigrations(database, migrationsDir) {
         }
         const sql = await fs.readFile(path.join(migrationsDir, fileName), "utf8");
         await database.withTransaction(async (client) => {
-            await client.query(sql);
+            await client.exec(sql);
             await client.query("INSERT INTO schema_migrations(version) VALUES ($1)", [version]);
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonsbs/keylore",
-  "version": "1.0.0-rc4",
+  "version": "1.0.0-rc5",
   "description": "MCP credential broker and searchable credential catalogue for LLM coding tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -63,6 +63,7 @@
     "test": "node --test --import tsx src/test/**/*.test.ts"
   },
   "dependencies": {
+    "@electric-sql/pglite": "^0.3.16",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "pg": "^8.20.0",
     "pg-mem": "^3.0.14",