memwarden 0.0.1

package/dist/state/store.js

@@ -0,0 +1,58 @@
+//
+// StateStore is the single persistence abstraction behind the StateKV
+// contract. It preserves the EXACT observable semantics of the original
+// two-level KV (src/state/kv.ts + src/mcp/in-memory-kv.ts):
+//
+// - scope and key are BOTH opaque strings, no prefix/hierarchy semantics
+// - get  -> value | null   (null, never undefined, never throws on miss)
+// - set  -> upsert, last-write-wins, returns the written value
+// - update -> read-or-{}, apply flat {type:"set", path, value} ops, write back
+// - delete -> idempotent, no error on missing
+// - list -> VALUES only (no keys), exact scope match, insertion order,
+// [] on unknown scope
+//
+// On top of those semantics it adds two things memwarden needs beyond a plain
+// key-value store:
+//
+// 1. Mutation events. set/update/delete report the affected key, the
+// event_type, and the old/new values so the kernel can drive the
+// registered type:"state" trigger (events.ts:108-145). The store does
+// NOT know about triggers; it just emits and the kernel routes.
+// 2. An append-only, hash-chained oplog of every mutation (SQLite-backed
+// impl persists it; the memory impl mirrors it in an array). Ed25519
+// signing lands in a later phase; for now each entry carries a SHA-256
+// hash over its canonical bytes plus the previous entry's hash.
+/**
+ * Apply the StateKV `update` op-list to a record, in place semantics returning
+ * the mutated record. Shared by both store implementations so their behavior
+ * is identical. Only `type:"set"` is honored (no push/inc/delete/append is
+ * ever produced by callers); `path` is a flat
+ * top-level field name, never dotted. Unknown op types are ignored.
+ */
+export function applyUpdateOps(current, ops) {
+    for (const op of ops) {
+        if (op.type === "set") {
+            current[op.path] = op.value;
+        }
+    }
+    return current;
+}
+/**
+ * Canonical JSON for hashing/signing: deterministic key ordering so the same
+ * logical value always produces the same bytes regardless of insertion order.
+ */
+export function canonicalize(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    const obj = value;
+    const out = {};
+    for (const key of Object.keys(obj).sort()) {
+        out[key] = sortValue(obj[key]);
+    }
+    return out;
+}

package/dist/triggers/api.d.ts

@@ -0,0 +1,14 @@
+import type { ApiRequest, ISdk } from "../kernel/index.js";
+type Response = {
+    status_code: number;
+    headers?: Record<string, string>;
+    body: unknown;
+};
+/**
+ * Inline auth check for handlers that receive the request directly
+ * (defense-in-depth alongside the api-auth middleware). When no secret is
+ * configured the API is open.
+ */
+export declare function checkAuth(req: ApiRequest, secret: string | undefined): Response | null;
+export declare function registerApiTriggers(sdk: ISdk, secret?: string): void;
+export {};

package/dist/triggers/api.js

@@ -0,0 +1,510 @@
+//
+// HTTP route registrations for the core surface. Each route is a
+// registerFunction(id, handler) + registerTrigger({type:"http", ...}) pair
+// that validates the request body and delegates to a mem::<x> business
+// handler via sdk.trigger (paths prefixed /memwarden, with the
+// middleware::api-auth chain). Scope: livez, observe, context, search,
+// verify, stats, doctor, export, import.
+import { getSecret, getQuantBits } from "../functions/config.js";
+import { getVectorIndex, getEmbeddingProvider } from "../functions/index.js";
+import { QuantizedVectorIndex } from "../functions/quantized-vector-index.js";
+import { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+import { metrics } from "../observability/metrics.js";
+import { exportBundle, importBundle, isBrainBundle } from "../bundle/bundle.js";
+import { timingSafeCompare } from "./auth.js";
+function asNonEmptyString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function parseOptionalFiniteNumber(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return undefined;
+        const parsed = Number(trimmed);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function parseOptionalPositiveInt(value) {
+    const parsed = parseOptionalFiniteNumber(value);
+    if (parsed === undefined || parsed === null)
+        return parsed;
+    if (!Number.isInteger(parsed) || parsed < 1)
+        return null;
+    return parsed;
+}
+/**
+ * Inline auth check for handlers that receive the request directly
+ * (defense-in-depth alongside the api-auth middleware). When no secret is
+ * configured the API is open.
+ */
+export function checkAuth(req, secret) {
+    if (!secret)
+        return null;
+    const auth = req.headers?.["authorization"] || req.headers?.["Authorization"];
+    if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${secret}`)) {
+        return { status_code: 401, body: { error: "unauthorized" } };
+    }
+    return null;
+}
+export function registerApiTriggers(sdk, secret) {
+    const resolvedSecret = secret ?? getSecret();
+    // --- auth middleware ----------------------------------------------
+    // Invoked by the kernel with { request: { headers } }; returns
+    // continue/respond. Absent secret = open (continue).
+    sdk.registerFunction("middleware::api-auth", async (input) => {
+        if (!resolvedSecret)
+            return { action: "continue" };
+        const headers = input?.request?.headers || {};
+        const auth = headers["authorization"] || headers["Authorization"];
+        if (typeof auth !== "string" ||
+            !timingSafeCompare(auth, `Bearer ${resolvedSecret}`)) {
+            return {
+                action: "respond",
+                response: { status_code: 401, body: { error: "unauthorized" } },
+            };
+        }
+        return { action: "continue" };
+    });
+    // --- GET /memwarden/livez (no auth) -----------------------------
+    sdk.registerFunction("api::liveness", async () => ({
+        status_code: 200,
+        body: { status: "ok", service: "memwarden" },
+    }));
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::liveness",
+        config: { api_path: "/memwarden/livez", http_method: "GET" },
+    });
+    // --- POST /memwarden/observe ------------------------------------
+    sdk.registerFunction("api::observe", async (req) => {
+        const body = (req.body ?? {});
+        const hookType = asNonEmptyString(body["hookType"]);
+        const sessionId = asNonEmptyString(body["sessionId"]);
+        const project = asNonEmptyString(body["project"]);
+        const cwd = asNonEmptyString(body["cwd"]);
+        const timestamp = asNonEmptyString(body["timestamp"]);
+        if (!hookType || !sessionId || !project || !cwd || !timestamp) {
+            return {
+                status_code: 400,
+                body: {
+                    error: "hookType, sessionId, project, cwd, and timestamp are required strings",
+                },
+            };
+        }
+        const payload = {
+            hookType: hookType,
+            sessionId,
+            project,
+            cwd,
+            timestamp,
+            data: body["data"],
+        };
+        const result = await sdk.trigger({
+            function_id: "mem::observe",
+            payload,
+        });
+        return { status_code: 201, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::observe",
+        config: {
+            api_path: "/memwarden/observe",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/context ------------------------------------
+    sdk.registerFunction("api::context", async (req) => {
+        const body = (req.body ?? {});
+        const sessionId = asNonEmptyString(body["sessionId"]);
+        const project = asNonEmptyString(body["project"]);
+        if (!sessionId || !project) {
+            return {
+                status_code: 400,
+                body: { error: "sessionId and project are required strings" },
+            };
+        }
+        const budget = parseOptionalPositiveInt(body["budget"]);
+        if (budget === null) {
+            return {
+                status_code: 400,
+                body: { error: "budget must be a positive integer" },
+            };
+        }
+        const payload = {
+            sessionId,
+            project,
+        };
+        if (budget !== undefined)
+            payload.budget = budget;
+        const result = await sdk.trigger({
+            function_id: "mem::context",
+            payload,
+        });
+        return { status_code: 200, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::context",
+        config: {
+            api_path: "/memwarden/context",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/search -------------------------------------
+    sdk.registerFunction("api::search", async (req) => {
+        const body = (req.body ?? {});
+        if (typeof body["query"] !== "string" || !body["query"].trim()) {
+            return {
+                status_code: 400,
+                body: { error: "query is required and must be a non-empty string" },
+            };
+        }
+        if (body["limit"] !== undefined &&
+            (!Number.isInteger(body["limit"]) || body["limit"] < 1)) {
+            return {
+                status_code: 400,
+                body: { error: "limit must be a positive integer" },
+            };
+        }
+        if (body["project"] !== undefined && typeof body["project"] !== "string") {
+            return {
+                status_code: 400,
+                body: { error: "project must be a string" },
+            };
+        }
+        if (body["cwd"] !== undefined && typeof body["cwd"] !== "string") {
+            return { status_code: 400, body: { error: "cwd must be a string" } };
+        }
+        if (body["format"] !== undefined &&
+            (typeof body["format"] !== "string" ||
+                !["full", "compact", "narrative"].includes(body["format"].trim().toLowerCase()))) {
+            return {
+                status_code: 400,
+                body: { error: "format must be one of: full, compact, narrative" },
+            };
+        }
+        if (body["token_budget"] !== undefined &&
+            (!Number.isInteger(body["token_budget"]) ||
+                body["token_budget"] < 1)) {
+            return {
+                status_code: 400,
+                body: { error: "token_budget must be a positive integer" },
+            };
+        }
+        // Verified Recall fails closed: safe_only needs a repo root to verify
+        // against, so reject it rather than silently returning unverified memory.
+        if (body["safe_only"] === true &&
+            (typeof body["cwd"] !== "string" || !body["cwd"].trim())) {
+            return {
+                status_code: 400,
+                body: { error: "safe_only requires cwd (a repo root to verify against)" },
+            };
+        }
+        const payload = { query: body["query"].trim() };
+        if (body["limit"] !== undefined)
+            payload.limit = body["limit"];
+        if (body["project"] !== undefined)
+            payload.project = body["project"];
+        if (body["cwd"] !== undefined)
+            payload.cwd = body["cwd"];
+        if (typeof body["format"] === "string")
+            payload.format = body["format"].trim().toLowerCase();
+        if (body["token_budget"] !== undefined)
+            payload.token_budget = body["token_budget"];
+        if (body["safe_only"] === true)
+            payload.safe_only = true;
+        const result = await sdk.trigger({
+            function_id: "mem::search",
+            payload,
+        });
+        return { status_code: 200, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::search",
+        config: {
+            api_path: "/memwarden/search",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- GET /memwarden/verify --------------------------------------
+    // Tamper-evidence: show the memory store's oplog hash chain is intact.
+    // The differentiating guarantee — memory whose history is tamper-evident
+    // (detects edits/reorders; not signed, so it is evidence, not proof).
+    sdk.registerFunction("api::verify", async () => {
+        const result = (await sdk.trigger({
+            function_id: "state::verify",
+            payload: {},
+        }));
+        const count = (await sdk.trigger({
+            function_id: "state::oplog-count",
+            payload: {},
+        }));
+        return {
+            status_code: result.ok ? 200 : 409,
+            body: {
+                verified: result.ok,
+                oplogEntries: count.count,
+                ...(result.ok ? {} : { brokenAt: result.brokenAt }),
+            },
+        };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::verify",
+        config: {
+            api_path: "/memwarden/verify",
+            http_method: "GET",
+            // Auth'd when a secret is set: oplog state is private brain metadata.
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- GET /memwarden/stats ---------------------------------------
+    // Live self-custody dashboard: memory counts, the active embedding
+    // provider, and the TurboQuant compression ratio.
+    sdk.registerFunction("api::stats", async () => {
+        const kv = new StateKV(sdk);
+        const [memories, sessions] = await Promise.all([
+            kv.list(KV.memories).catch(() => []),
+            kv.list(KV.sessions).catch(() => []),
+        ]);
+        const provider = getEmbeddingProvider();
+        const vec = getVectorIndex();
+        const body = {
+            memories: memories.length,
+            sessions: sessions.length,
+            vectors: vec?.size ?? 0,
+            embedding: provider
+                ? { provider: provider.name, dimensions: provider.dimensions }
+                : null,
+        };
+        if (vec instanceof QuantizedVectorIndex) {
+            const { dims, paddedDims, bits, rescoreDepth } = vec.params;
+            const fullBytes = dims * 4;
+            const codeBytes = Math.ceil((paddedDims * bits) / 8) + 4; // codes + norm
+            const storedBytes = codeBytes + (rescoreDepth > 0 ? fullBytes : 0);
+            body["compression"] = {
+                algorithm: "TurboQuant",
+                bits: getQuantBits(),
+                fullBytesPerVector: fullBytes,
+                storedBytesPerVector: storedBytes,
+                ratio: Math.round((fullBytes / storedBytes) * 10) / 10,
+                rescore: rescoreDepth,
+            };
+        }
+        else {
+            body["compression"] = null;
+        }
+        body["performance"] = metrics.snapshot();
+        return { status_code: 200, body };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::stats",
+        config: {
+            api_path: "/memwarden/stats",
+            http_method: "GET",
+            // Auth'd when a secret is set: stats expose memory/session counts.
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/doctor -------------------------------------
+    // The memory doctor: audit stored memories for staleness and sourcing
+    // against the live repo. The differentiating "is this safe to inject?"
+    // surface.
+    sdk.registerFunction("api::doctor", async (req) => {
+        const body = (req.body ?? {});
+        const report = await sdk.trigger({
+            function_id: "mem::doctor",
+            payload: { root: body.root, project: body.project },
+        });
+        return { status_code: 200, body: report };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::doctor",
+        config: {
+            api_path: "/memwarden/doctor",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/forget --------------------------------------
+    // User-initiated deletion with a tamper-evident receipt. Auth'd: deleting
+    // memory is as sensitive as reading it.
+    sdk.registerFunction("api::forget", async (req) => {
+        const body = (req.body ?? {});
+        const observationId = asNonEmptyString(body.observation_id) ??
+            asNonEmptyString(body.observationId);
+        if (!observationId) {
+            return { status_code: 400, body: { error: "observation_id is required" } };
+        }
+        const result = await sdk.trigger({
+            function_id: "mem::forget",
+            payload: { observationId },
+        });
+        return { status_code: 200, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::forget",
+        config: {
+            api_path: "/memwarden/forget",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/dejafix/lookup -----------------------------
+    // Déjà Fix: surface verified fixes for an error any agent already solved.
+    // Returns only fixes whose referenced files still hash-match (Verified
+    // Recall) — a stale fix is never returned. cwd is required: it is both the
+    // project firewall (a fix learned in repo A never leaks to repo B) and the
+    // working tree the fix is verified against.
+    sdk.registerFunction("api::dejafix-lookup", async (req) => {
+        const body = (req.body ?? {});
+        const errorText = asNonEmptyString(body.error_text) ?? asNonEmptyString(body.errorText);
+        if (!errorText) {
+            return { status_code: 400, body: { error: "error_text is required" } };
+        }
+        const cwd = asNonEmptyString(body.cwd);
+        if (!cwd) {
+            return {
+                status_code: 400,
+                body: { error: "cwd is required (the repo to verify fixes against)" },
+            };
+        }
+        const result = await sdk.trigger({
+            function_id: "mem::dejafix_lookup",
+            payload: { errorText, cwd },
+        });
+        return { status_code: 200, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::dejafix-lookup",
+        config: {
+            api_path: "/memwarden/dejafix/lookup",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/dejafix/record -----------------------------
+    // Record a {error -> root cause + fix} so any agent that hits the same error
+    // later gets it back. Referenced files are hashed now so drift is detectable.
+    sdk.registerFunction("api::dejafix-record", async (req) => {
+        const body = (req.body ?? {});
+        const fix = asNonEmptyString(body["fix"]);
+        if (!fix) {
+            return { status_code: 400, body: { error: "fix is required" } };
+        }
+        const cwd = asNonEmptyString(body["cwd"]);
+        if (!cwd) {
+            return { status_code: 400, body: { error: "cwd is required" } };
+        }
+        const errorText = asNonEmptyString(body["error_text"]) ??
+            asNonEmptyString(body["errorText"]);
+        const signature = asNonEmptyString(body["signature"]);
+        if (!errorText && !signature) {
+            return {
+                status_code: 400,
+                body: { error: "error_text or signature is required" },
+            };
+        }
+        const files = Array.isArray(body["files"])
+            ? body["files"].filter((f) => typeof f === "string" && f.trim().length > 0)
+            : undefined;
+        const payload = { fix, cwd };
+        if (errorText)
+            payload["errorText"] = errorText;
+        if (signature)
+            payload["signature"] = signature;
+        const rootCause = asNonEmptyString(body["root_cause"]) ??
+            asNonEmptyString(body["rootCause"]);
+        if (rootCause)
+            payload["rootCause"] = rootCause;
+        if (files && files.length > 0)
+            payload["files"] = files;
+        const tool = asNonEmptyString(body["tool"]);
+        if (tool)
+            payload["tool"] = tool;
+        const sessionId = asNonEmptyString(body["session_id"]) ??
+            asNonEmptyString(body["sessionId"]);
+        if (sessionId)
+            payload["sessionId"] = sessionId;
+        const result = await sdk.trigger({
+            function_id: "mem::dejafix_record",
+            payload,
+        });
+        return { status_code: 200, body: result };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::dejafix-record",
+        config: {
+            api_path: "/memwarden/dejafix/record",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- GET /memwarden/export --------------------------------------
+    // Portability: a self-contained Brain Bundle the user can move between
+    // machines or agents. No vendor in the loop.
+    sdk.registerFunction("api::export", async () => {
+        const bundle = await exportBundle(new StateKV(sdk));
+        return {
+            status_code: 200,
+            body: { ...bundle, exportedAt: new Date().toISOString() },
+        };
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::export",
+        config: {
+            api_path: "/memwarden/export",
+            http_method: "GET",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+    // --- POST /memwarden/import -------------------------------------
+    sdk.registerFunction("api::import", async (req) => {
+        const body = req.body;
+        if (!isBrainBundle(body)) {
+            return {
+                status_code: 400,
+                body: { error: "body is not a valid memwarden brain bundle" },
+            };
+        }
+        try {
+            const counts = await importBundle(new StateKV(sdk), body);
+            return { status_code: 200, body: { imported: counts } };
+        }
+        catch (err) {
+            return {
+                status_code: 400,
+                body: { error: err instanceof Error ? err.message : String(err) },
+            };
+        }
+    });
+    sdk.registerTrigger({
+        type: "http",
+        function_id: "api::import",
+        config: {
+            api_path: "/memwarden/import",
+            http_method: "POST",
+            middleware_function_ids: ["middleware::api-auth"],
+        },
+    });
+}

package/dist/triggers/auth.d.ts

@@ -0,0 +1 @@
+export declare function timingSafeCompare(a: string, b: string): boolean;

package/dist/triggers/auth.js

@@ -0,0 +1,13 @@
+//
+// Constant-time bearer-token comparison. Both inputs are HMAC'd under a
+// random per-process key and then compared with timingSafeEqual, so the
+// result is independent of input length and leaks no timing about how many
+// leading characters happened to match.
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+const COMPARE_KEY = randomBytes(32);
+function fingerprint(value) {
+    return createHmac("sha256", COMPARE_KEY).update(value).digest();
+}
+export function timingSafeCompare(a, b) {
+    return timingSafeEqual(fingerprint(a), fingerprint(b));
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "memwarden",
+  "version": "0.0.1",
+  "description": "The memory firewall for AI coding agents. Verified, self-custodied, tamper-evident — one brain across every tool.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "memwarden": "dist/cli/bin.js",
+    "memwarden-mcp": "dist/mcp/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saiyam1814/memwarden.git"
+  },
+  "homepage": "https://github.com/saiyam1814/memwarden#readme",
+  "bugs": {
+    "url": "https://github.com/saiyam1814/memwarden/issues"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "agents",
+    "mcp",
+    "claude-code",
+    "verified-recall",
+    "memory-firewall",
+    "local-first"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "benchmark": "tsx benchmark/recall.ts",
+    "demo:trust": "tsx demo/trust.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@libsql/client": "^0.15.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}