@seanhogg/builderforce-memory-mcp 2026.6.31 → 2026.6.34

package/README.md

@@ -7,7 +7,9 @@ tool core over a pluggable `MemoryBackend`, three transports:
 |---|---|---|---|
 | **In-process (Claude Agent SDK)** | `createMemoryMcpServer(backend)` | the returned `type:"sdk"` object | the consuming product is TS and runs `@anthropic-ai/claude-agent-sdk` in-process — lowest latency |
 | **stdio** | `runStdio(backend)` / `npx @seanhogg/builderforce-memory-mcp` | `{ type:"stdio", command, args }` | any language / separate process; decouples the SSM+IndexedDB deps from the consumer |
-| **HTTP (Streamable)** | `createMemoryHttpHandler(backend, { authToken })` | `{ type:"http", url, headers }` | multi-tenant / networked (builderforce.ai hosting, remote claws) |
+| **HTTP (Streamable)** | `createMemoryHttpHandler(backend, { authToken })` | `{ type:"http", url, headers }` | multi-tenant / networked (builderforce.ai hosting, remote agents) |
+
+> **Technical report & peer review.** This transport is reviewed in the Evermind technical report's adversarial [`PEER-REVIEW.md`](../../publication/evermind/PEER-REVIEW.md). Note before exposing the HTTP handler publicly: the `authToken` check is a **non-constant-time** string compare (timing channel) and the handler shares **one `backend` with no per-tenant isolation** — a single token reads every tenant's facts. Despite the "multi-tenant" note above, real isolation (token→namespace mapping, constant-time compare, rate limiting) is **not yet implemented**. Tracked as `EVM-3` in the Builderforce.ai Consolidated Gap Register.
 
 ## Why this saves tokens
 
@@ -67,7 +69,7 @@ for await (const msg of query({
 
 The local backend defaults to **lexical (Jaccard)** recall. For SSM-embedding
 cosine recall, pass an SSM runtime — e.g. reuse the agent-runtime's already-loaded
-hippocampus instead of standing up a second model:
+Evermind runtime instead of standing up a second model:
 
 ```ts
 const backend = await createLocalMemoryStoreBackend({ runtime: ssmMemoryService.runtime });

package/dist/backends/memory-store.d.ts

@@ -47,7 +47,7 @@ export interface LocalBackendOptions {
     /**
      * Optional SSMRuntime for embedding-based recall. Omit for lexical (Jaccard)
      * recall. In the agent-runtime, pass `ssmMemoryService.runtime` here to reuse
-     * the already-loaded hippocampus instead of standing up a second model.
+     * the already-loaded Evermind runtime instead of standing up a second model.
      */
     runtime?: unknown;
     /**

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export type { McpServerOptions } from "./transports/mcp-server.js";
 export { runStdio } from "./transports/stdio.js";
 export { createMemoryHttpHandler } from "./transports/http.js";
 export type { HttpHandlerOptions } from "./transports/http.js";
+export { hashToken, timingSafeEqualStr, buildTenantIndex, bearerToken, RateLimiter } from "./transports/auth.js";
 export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
 export type { StdioServerSpec, ServerSpecOptions } from "./install/server-spec.js";
 export { installMemoryServer } from "./install/install.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGjH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -15,6 +15,7 @@ export { createMemoryMcpServer } from "./transports/sdk.js";
 export { buildMcpServer } from "./transports/mcp-server.js";
 export { runStdio } from "./transports/stdio.js";
 export { createMemoryHttpHandler } from "./transports/http.js";
+export { hashToken, timingSafeEqualStr, buildTenantIndex, bearerToken, RateLimiter } from "./transports/auth.js";
 // ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
 export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
 export { installMemoryServer } from "./install/install.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEjE,qFAAqF;AACrF,4FAA4F;AAC5F,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjH,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEjE,qFAAqF;AACrF,4FAA4F;AAC5F,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/transports/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * transports/auth.ts — auth + rate-limiting primitives for the HTTP transport.
+ *
+ * The networked MCP surface is multi-tenant: one bearer token must map to ONE
+ * tenant's memory namespace, the comparison must not leak the secret through a
+ * timing side channel, and a noisy or hostile caller must not be able to hammer
+ * the server. These helpers provide exactly those three pieces, dependency-free
+ * (node:crypto only).
+ */
+/** SHA-256 hex digest of a token — the stable, non-reversible lookup key. */
+export declare function hashToken(token: string): string;
+/**
+ * Constant-time string equality. Hashes both sides to fixed-length digests
+ * first, so neither the comparison nor the input length leaks the secret.
+ */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
+/**
+ * Build a tenant lookup keyed by token HASH (never the raw token). Resolving a
+ * presented token is a hash + map lookup — no per-character secret comparison,
+ * so there is no early-return timing channel on the token value.
+ */
+export declare function buildTenantIndex<B>(tenants: Record<string, B>): Map<string, B>;
+/** Fixed-window rate limiter. Memory-bounded by pruning expired windows. */
+export declare class RateLimiter {
+    private readonly windowMs;
+    private readonly max;
+    private readonly now;
+    private readonly _hits;
+    constructor(windowMs: number, max: number, now?: () => number);
+    /** Returns true when the call is allowed; false when the window is exhausted. */
+    check(key: string): boolean;
+    private _prune;
+}
+/** Extract the bearer token from an Authorization header value, or undefined. */
+export declare function bearerToken(header: string | string[] | undefined): string | undefined;
+//# sourceMappingURL=auth.d.ts.map

package/dist/transports/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/transports/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAM9E;AAED,4EAA4E;AAC5E,qBAAa,WAAW;IAIhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyD;gBAG1D,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,MAAyB;IAGzD,iFAAiF;IACjF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAa3B,OAAO,CAAC,MAAM;CAKjB;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKrF"}

package/dist/transports/auth.js

@@ -0,0 +1,78 @@
+/**
+ * transports/auth.ts — auth + rate-limiting primitives for the HTTP transport.
+ *
+ * The networked MCP surface is multi-tenant: one bearer token must map to ONE
+ * tenant's memory namespace, the comparison must not leak the secret through a
+ * timing side channel, and a noisy or hostile caller must not be able to hammer
+ * the server. These helpers provide exactly those three pieces, dependency-free
+ * (node:crypto only).
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+/** SHA-256 hex digest of a token — the stable, non-reversible lookup key. */
+export function hashToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+/**
+ * Constant-time string equality. Hashes both sides to fixed-length digests
+ * first, so neither the comparison nor the input length leaks the secret.
+ */
+export function timingSafeEqualStr(a, b) {
+    const ha = createHash("sha256").update(a, "utf8").digest();
+    const hb = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(ha, hb);
+}
+/**
+ * Build a tenant lookup keyed by token HASH (never the raw token). Resolving a
+ * presented token is a hash + map lookup — no per-character secret comparison,
+ * so there is no early-return timing channel on the token value.
+ */
+export function buildTenantIndex(tenants) {
+    const index = new Map();
+    for (const [token, backend] of Object.entries(tenants)) {
+        if (token)
+            index.set(hashToken(token), backend);
+    }
+    return index;
+}
+/** Fixed-window rate limiter. Memory-bounded by pruning expired windows. */
+export class RateLimiter {
+    windowMs;
+    max;
+    now;
+    _hits = new Map();
+    constructor(windowMs, max, now = () => Date.now()) {
+        this.windowMs = windowMs;
+        this.max = max;
+        this.now = now;
+    }
+    /** Returns true when the call is allowed; false when the window is exhausted. */
+    check(key) {
+        const t = this.now();
+        const entry = this._hits.get(key);
+        if (!entry || t >= entry.resetAt) {
+            if (this._hits.size > 10_000)
+                this._prune(t);
+            this._hits.set(key, { count: 1, resetAt: t + this.windowMs });
+            return true;
+        }
+        if (entry.count >= this.max)
+            return false;
+        entry.count++;
+        return true;
+    }
+    _prune(t) {
+        for (const [k, v] of this._hits) {
+            if (t >= v.resetAt)
+                this._hits.delete(k);
+        }
+    }
+}
+/** Extract the bearer token from an Authorization header value, or undefined. */
+export function bearerToken(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value)
+        return undefined;
+    const m = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return m ? m[1].trim() : undefined;
+}
+//# sourceMappingURL=auth.js.map

package/dist/transports/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/transports/auth.ts"],"names":[],"mappings":"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"}

package/dist/transports/http.d.ts

@@ -1,8 +1,22 @@
 /**
  * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
- * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * remote hosts). Stateless Streamable HTTP: one short-lived McpServer +
  * transport per request, so it scales horizontally with no sticky sessions.
- * Bearer-token auth gates every request.
+ *
+ * Auth model (pick one, in precedence order):
+ *   • `tenants` — a `{ token: backend }` map. The bearer token selects the
+ *     tenant's OWN backend (namespace isolation); an unknown token is 401. This
+ *     is the production multi-tenant mode — one token can never read another
+ *     tenant's facts.
+ *   • `resolveBackend` — a function `(token) => backend` for dynamic tenant
+ *     resolution (e.g. a gateway lookup).
+ *   • `authToken` — a single shared secret guarding the one positional backend
+ *     (single-tenant / reference hosting).
+ *   • none — open, only valid behind a trusted gateway that already authed.
+ *
+ * Token comparison is constant-time (hash + timingSafeEqual / hash-keyed lookup),
+ * and an optional fixed-window rate limit (per tenant, or per client IP when
+ * unauthenticated) caps abuse.
  *
  * Consumed from the Claude Agent SDK as:
  *   mcpServers: {
@@ -15,16 +29,36 @@ import type { MemoryBackend } from "../backend.js";
 import { type McpServerOptions } from "./mcp-server.js";
 export interface HttpHandlerOptions extends McpServerOptions {
     /**
-     * Shared secret required in `Authorization: Bearer <token>`. When set, every
-     * request without a matching token is rejected 401. Omit only behind a trusted
-     * gateway that has already authenticated the caller.
+     * Shared secret required in `Authorization: Bearer <token>` for the single
+     * positional backend. Every request without a matching token is rejected 401.
+     * Omit only behind a trusted gateway that has already authenticated the caller.
      */
     authToken?: string;
+    /**
+     * Multi-tenant map: bearer token → that tenant's backend. When set, the token
+     * selects the backend (namespace isolation) and the positional `backend` is
+     * only used as a fallback when no token-auth modes match. Lookups are keyed by
+     * token hash, never the raw token.
+     */
+    tenants?: Record<string, MemoryBackend>;
+    /**
+     * Dynamic tenant resolver: `(token) => backend | undefined`. Used when tenants
+     * live in an external store. Returning undefined → 401.
+     */
+    resolveBackend?: (token: string) => MemoryBackend | undefined | Promise<MemoryBackend | undefined>;
+    /** Fixed-window rate limit applied per tenant (or per client IP if open). */
+    rateLimit?: {
+        windowMs: number;
+        max: number;
+    };
+    /** Injectable clock (ms) for deterministic rate-limit tests. */
+    now?: () => number;
 }
 /**
  * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
- * server (or Express). Per request it spins up a stateless MCP server bound to
- * `backend`, handles the MCP exchange, and tears down on response close.
+ * server (or Express). Per request it authenticates, resolves the tenant
+ * backend, rate-limits, spins up a stateless MCP server bound to that backend,
+ * handles the MCP exchange, and tears down on response close.
  */
 export declare function createMemoryHttpHandler(backend: MemoryBackend, opts?: HttpHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 //# sourceMappingURL=http.d.ts.map

package/dist/transports/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,kBAAuB,GAC9B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAuB9D"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACnG,6EAA6E;IAC7E,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAcD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,kBAAuB,GAC9B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAyD9D"}

package/dist/transports/http.js

@@ -1,8 +1,22 @@
 /**
  * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
- * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * remote hosts). Stateless Streamable HTTP: one short-lived McpServer +
  * transport per request, so it scales horizontally with no sticky sessions.
- * Bearer-token auth gates every request.
+ *
+ * Auth model (pick one, in precedence order):
+ *   • `tenants` — a `{ token: backend }` map. The bearer token selects the
+ *     tenant's OWN backend (namespace isolation); an unknown token is 401. This
+ *     is the production multi-tenant mode — one token can never read another
+ *     tenant's facts.
+ *   • `resolveBackend` — a function `(token) => backend` for dynamic tenant
+ *     resolution (e.g. a gateway lookup).
+ *   • `authToken` — a single shared secret guarding the one positional backend
+ *     (single-tenant / reference hosting).
+ *   • none — open, only valid behind a trusted gateway that already authed.
+ *
+ * Token comparison is constant-time (hash + timingSafeEqual / hash-keyed lookup),
+ * and an optional fixed-window rate limit (per tenant, or per client IP when
+ * unauthenticated) caps abuse.
  *
  * Consumed from the Claude Agent SDK as:
  *   mcpServers: {
@@ -12,25 +26,78 @@
  */
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { buildMcpServer } from "./mcp-server.js";
-function unauthorized(res) {
-    res.writeHead(401, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "unauthorized" }));
+import { RateLimiter, bearerToken, buildTenantIndex, hashToken, timingSafeEqualStr } from "./auth.js";
+function send(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+/** First-hop client IP, for rate-limiting unauthenticated callers. */
+function clientIp(req) {
+    const fwd = req.headers["x-forwarded-for"];
+    const first = Array.isArray(fwd) ? fwd[0] : fwd?.split(",")[0];
+    return (first?.trim() || req.socket?.remoteAddress || "unknown");
 }
 /**
  * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
- * server (or Express). Per request it spins up a stateless MCP server bound to
- * `backend`, handles the MCP exchange, and tears down on response close.
+ * server (or Express). Per request it authenticates, resolves the tenant
+ * backend, rate-limits, spins up a stateless MCP server bound to that backend,
+ * handles the MCP exchange, and tears down on response close.
  */
 export function createMemoryHttpHandler(backend, opts = {}) {
+    const tenantIndex = opts.tenants ? buildTenantIndex(opts.tenants) : undefined;
+    const limiter = opts.rateLimit
+        ? new RateLimiter(opts.rateLimit.windowMs, opts.rateLimit.max, opts.now ?? (() => Date.now()))
+        : undefined;
     return async (req, res) => {
-        if (opts.authToken) {
-            const header = req.headers["authorization"];
-            if (header !== `Bearer ${opts.authToken}`) {
-                unauthorized(res);
+        const token = bearerToken(req.headers["authorization"]);
+        // ── Resolve the per-request backend + a rate-limit key ────────────────
+        let resolved;
+        let rateKey;
+        if (tenantIndex) {
+            // Multi-tenant: token → that tenant's backend (hash-keyed lookup).
+            if (!token) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            resolved = tenantIndex.get(hashToken(token));
+            if (!resolved) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else if (opts.resolveBackend) {
+            if (!token) {
+                send(res, 401, { error: "unauthorized" });
                 return;
             }
+            resolved = await opts.resolveBackend(token);
+            if (!resolved) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else if (opts.authToken) {
+            // Single shared secret, constant-time compare.
+            if (!token || !timingSafeEqualStr(token, opts.authToken)) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            resolved = backend;
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else {
+            // Open (trusted gateway): rate-limit by client IP.
+            resolved = backend;
+            rateKey = `ip:${clientIp(req)}`;
+        }
+        // ── Rate limit ────────────────────────────────────────────────────────
+        if (limiter && !limiter.check(rateKey)) {
+            send(res, 429, { error: "rate_limited" });
+            return;
         }
-        const server = buildMcpServer(backend, opts);
+        const server = buildMcpServer(resolved, opts);
         // Stateless: no session id generator → a fresh transport per request.
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         res.on("close", () => {

package/dist/transports/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAEnG,OAAO,EAAE,cAAc,EAAyB,MAAM,iBAAiB,CAAC;AAWxE,SAAS,YAAY,CAAC,GAAmB;IACrC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACnC,OAAsB,EACtB,OAA2B,EAAE;IAE7B,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACtB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,UAAU,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;gBACxC,YAAY,CAAC,GAAG,CAAC,CAAC;gBAClB,OAAO;YACX,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC7C,sEAAsE;QACtE,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAC;QAEvF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACjB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,8EAA8E;QAC9E,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-mcp",
-  "version": "2026.6.31",
+  "version": "2026.6.34",
   "description": "BuilderForce Agent Memory — MCP transport. Exposes @seanhogg/builderforce-memory to any MCP client (Claude Agent SDK in-process, stdio, or HTTP) over a pluggable MemoryBackend, with token-saving fetch-on-demand recall.",
   "type": "module",
   "main": "dist/index.js",
@@ -73,7 +73,7 @@
     "fake-indexeddb": "^6.0.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory": "2026.6.31"
+    "@seanhogg/builderforce-memory": "2026.6.34"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -83,7 +83,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs",
+    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs tests/http.test.mjs",
     "lint": "eslint src/",
     "typecheck:native": "tsgo --noEmit"
   }

package/src/backends/memory-store.ts

@@ -81,7 +81,7 @@ export interface LocalBackendOptions {
     /**
      * Optional SSMRuntime for embedding-based recall. Omit for lexical (Jaccard)
      * recall. In the agent-runtime, pass `ssmMemoryService.runtime` here to reuse
-     * the already-loaded hippocampus instead of standing up a second model.
+     * the already-loaded Evermind runtime instead of standing up a second model.
      */
     runtime?: unknown;
     /**

package/src/index.ts

@@ -29,6 +29,7 @@ export { runStdio } from "./transports/stdio.js";
 
 export { createMemoryHttpHandler } from "./transports/http.js";
 export type { HttpHandlerOptions } from "./transports/http.js";
+export { hashToken, timingSafeEqualStr, buildTenantIndex, bearerToken, RateLimiter } from "./transports/auth.js";
 
 // ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
 export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";

package/src/transports/auth.ts

@@ -0,0 +1,78 @@
+/**
+ * transports/auth.ts — auth + rate-limiting primitives for the HTTP transport.
+ *
+ * The networked MCP surface is multi-tenant: one bearer token must map to ONE
+ * tenant's memory namespace, the comparison must not leak the secret through a
+ * timing side channel, and a noisy or hostile caller must not be able to hammer
+ * the server. These helpers provide exactly those three pieces, dependency-free
+ * (node:crypto only).
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/** SHA-256 hex digest of a token — the stable, non-reversible lookup key. */
+export function hashToken(token: string): string {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+
+/**
+ * Constant-time string equality. Hashes both sides to fixed-length digests
+ * first, so neither the comparison nor the input length leaks the secret.
+ */
+export function timingSafeEqualStr(a: string, b: string): boolean {
+    const ha = createHash("sha256").update(a, "utf8").digest();
+    const hb = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(ha, hb);
+}
+
+/**
+ * Build a tenant lookup keyed by token HASH (never the raw token). Resolving a
+ * presented token is a hash + map lookup — no per-character secret comparison,
+ * so there is no early-return timing channel on the token value.
+ */
+export function buildTenantIndex<B>(tenants: Record<string, B>): Map<string, B> {
+    const index = new Map<string, B>();
+    for (const [token, backend] of Object.entries(tenants)) {
+        if (token) index.set(hashToken(token), backend);
+    }
+    return index;
+}
+
+/** Fixed-window rate limiter. Memory-bounded by pruning expired windows. */
+export class RateLimiter {
+    private readonly _hits = new Map<string, { count: number; resetAt: number }>();
+
+    constructor(
+        private readonly windowMs: number,
+        private readonly max: number,
+        private readonly now: () => number = () => Date.now(),
+    ) {}
+
+    /** Returns true when the call is allowed; false when the window is exhausted. */
+    check(key: string): boolean {
+        const t = this.now();
+        const entry = this._hits.get(key);
+        if (!entry || t >= entry.resetAt) {
+            if (this._hits.size > 10_000) this._prune(t);
+            this._hits.set(key, { count: 1, resetAt: t + this.windowMs });
+            return true;
+        }
+        if (entry.count >= this.max) return false;
+        entry.count++;
+        return true;
+    }
+
+    private _prune(t: number): void {
+        for (const [k, v] of this._hits) {
+            if (t >= v.resetAt) this._hits.delete(k);
+        }
+    }
+}
+
+/** Extract the bearer token from an Authorization header value, or undefined. */
+export function bearerToken(header: string | string[] | undefined): string | undefined {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value) return undefined;
+    const m = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return m ? m[1]!.trim() : undefined;
+}

package/src/transports/http.ts

@@ -1,8 +1,22 @@
 /**
  * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
- * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * remote hosts). Stateless Streamable HTTP: one short-lived McpServer +
  * transport per request, so it scales horizontally with no sticky sessions.
- * Bearer-token auth gates every request.
+ *
+ * Auth model (pick one, in precedence order):
+ *   • `tenants` — a `{ token: backend }` map. The bearer token selects the
+ *     tenant's OWN backend (namespace isolation); an unknown token is 401. This
+ *     is the production multi-tenant mode — one token can never read another
+ *     tenant's facts.
+ *   • `resolveBackend` — a function `(token) => backend` for dynamic tenant
+ *     resolution (e.g. a gateway lookup).
+ *   • `authToken` — a single shared secret guarding the one positional backend
+ *     (single-tenant / reference hosting).
+ *   • none — open, only valid behind a trusted gateway that already authed.
+ *
+ * Token comparison is constant-time (hash + timingSafeEqual / hash-keyed lookup),
+ * and an optional fixed-window rate limit (per tenant, or per client IP when
+ * unauthenticated) caps abuse.
  *
  * Consumed from the Claude Agent SDK as:
  *   mcpServers: {
@@ -15,40 +29,99 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import type { MemoryBackend } from "../backend.js";
 import { buildMcpServer, type McpServerOptions } from "./mcp-server.js";
+import { RateLimiter, bearerToken, buildTenantIndex, hashToken, timingSafeEqualStr } from "./auth.js";
 
 export interface HttpHandlerOptions extends McpServerOptions {
     /**
-     * Shared secret required in `Authorization: Bearer <token>`. When set, every
-     * request without a matching token is rejected 401. Omit only behind a trusted
-     * gateway that has already authenticated the caller.
+     * Shared secret required in `Authorization: Bearer <token>` for the single
+     * positional backend. Every request without a matching token is rejected 401.
+     * Omit only behind a trusted gateway that has already authenticated the caller.
      */
     authToken?: string;
+    /**
+     * Multi-tenant map: bearer token → that tenant's backend. When set, the token
+     * selects the backend (namespace isolation) and the positional `backend` is
+     * only used as a fallback when no token-auth modes match. Lookups are keyed by
+     * token hash, never the raw token.
+     */
+    tenants?: Record<string, MemoryBackend>;
+    /**
+     * Dynamic tenant resolver: `(token) => backend | undefined`. Used when tenants
+     * live in an external store. Returning undefined → 401.
+     */
+    resolveBackend?: (token: string) => MemoryBackend | undefined | Promise<MemoryBackend | undefined>;
+    /** Fixed-window rate limit applied per tenant (or per client IP if open). */
+    rateLimit?: { windowMs: number; max: number };
+    /** Injectable clock (ms) for deterministic rate-limit tests. */
+    now?: () => number;
 }
 
-function unauthorized(res: ServerResponse): void {
-    res.writeHead(401, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "unauthorized" }));
+function send(res: ServerResponse, status: number, body: unknown): void {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+
+/** First-hop client IP, for rate-limiting unauthenticated callers. */
+function clientIp(req: IncomingMessage): string {
+    const fwd = req.headers["x-forwarded-for"];
+    const first = Array.isArray(fwd) ? fwd[0] : fwd?.split(",")[0];
+    return (first?.trim() || req.socket?.remoteAddress || "unknown");
 }
 
 /**
  * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
- * server (or Express). Per request it spins up a stateless MCP server bound to
- * `backend`, handles the MCP exchange, and tears down on response close.
+ * server (or Express). Per request it authenticates, resolves the tenant
+ * backend, rate-limits, spins up a stateless MCP server bound to that backend,
+ * handles the MCP exchange, and tears down on response close.
  */
 export function createMemoryHttpHandler(
     backend: MemoryBackend,
     opts: HttpHandlerOptions = {},
 ): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+    const tenantIndex = opts.tenants ? buildTenantIndex(opts.tenants) : undefined;
+    const limiter = opts.rateLimit
+        ? new RateLimiter(opts.rateLimit.windowMs, opts.rateLimit.max, opts.now ?? (() => Date.now()))
+        : undefined;
+
     return async (req, res) => {
-        if (opts.authToken) {
-            const header = req.headers["authorization"];
-            if (header !== `Bearer ${opts.authToken}`) {
-                unauthorized(res);
+        const token = bearerToken(req.headers["authorization"]);
+
+        // ── Resolve the per-request backend + a rate-limit key ────────────────
+        let resolved: MemoryBackend | undefined;
+        let rateKey: string;
+
+        if (tenantIndex) {
+            // Multi-tenant: token → that tenant's backend (hash-keyed lookup).
+            if (!token) { send(res, 401, { error: "unauthorized" }); return; }
+            resolved = tenantIndex.get(hashToken(token));
+            if (!resolved) { send(res, 401, { error: "unauthorized" }); return; }
+            rateKey = `t:${hashToken(token)}`;
+        } else if (opts.resolveBackend) {
+            if (!token) { send(res, 401, { error: "unauthorized" }); return; }
+            resolved = await opts.resolveBackend(token);
+            if (!resolved) { send(res, 401, { error: "unauthorized" }); return; }
+            rateKey = `t:${hashToken(token)}`;
+        } else if (opts.authToken) {
+            // Single shared secret, constant-time compare.
+            if (!token || !timingSafeEqualStr(token, opts.authToken)) {
+                send(res, 401, { error: "unauthorized" });
                 return;
             }
+            resolved = backend;
+            rateKey = `t:${hashToken(token)}`;
+        } else {
+            // Open (trusted gateway): rate-limit by client IP.
+            resolved = backend;
+            rateKey = `ip:${clientIp(req)}`;
+        }
+
+        // ── Rate limit ────────────────────────────────────────────────────────
+        if (limiter && !limiter.check(rateKey)) {
+            send(res, 429, { error: "rate_limited" });
+            return;
         }
 
-        const server = buildMcpServer(backend, opts);
+        const server = buildMcpServer(resolved, opts);
         // Stateless: no session id generator → a fresh transport per request.
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });