@thotischner/observability-mcp 1.7.1 → 1.8.1

package/dist/quota/token-budget.js

@@ -0,0 +1,297 @@
+/**
+ * Per-identity token-budget tracker.
+ *
+ * The MCP transport gets per-call sliding-window cap from
+ * `IdentityRateLimiter`. Operators with paid-tier LLM agents want a
+ * second axis: a daily token quota that limits the number of tokens
+ * a credential can pull through the tool layer in a 24-hour rolling
+ * window. This module is the data-plane half of that knob.
+ *
+ * Token estimation:
+ *   The MCP tool response (and the agent's request args) cross the
+ *   boundary as JSON text. We don't tokenize with a real tokenizer
+ *   here — pulling in tiktoken / gpt-tokenizer would add a non-trivial
+ *   wasm/dep that the airgapped-friendly posture wants to avoid. The
+ *   estimate uses a deliberate over-approximation:
+ *       tokens ≈ ceil(chars / 4) * 1.05
+ *   which tends to over-count by ~5% vs. cl100k_base on prose payloads
+ *   and ~15% on dense code/JSON. Under-counting is the worse error
+ *   mode for budget control, so the rounding direction is intentional.
+ *
+ * Window:
+ *   24h rolling, bucketed at 1-hour resolution to keep memory bounded.
+ *   Each bucket records (hour-aligned timestamp, tokens). On every
+ *   `check()` we drop buckets older than 24h and sum the rest.
+ *
+ * Persistence is OUT OF SCOPE for this slice (planned for E6/3). The
+ * in-memory tracker is constructed fresh at boot; restart-survival
+ * requires the persistence layer.
+ */
+import { readFile, writeFile, rename } from "node:fs/promises";
+const HOUR_MS = 60 * 60 * 1000;
+const WINDOW_MS = 24 * HOUR_MS;
+/** Estimate tokens from a string. Intentionally over-counts. */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Chars/4 is the cl100k rule-of-thumb. Multiplied by 1.05 to push
+    // the estimate slightly above the real value — quota enforcement
+    // wants false-positives over false-negatives.
+    return Math.ceil((text.length / 4) * 1.05);
+}
+/** Estimate tokens for an arbitrary JSON-serialisable value. */
+export function estimateTokensFor(v) {
+    if (v === undefined || v === null)
+        return 0;
+    if (typeof v === "string")
+        return estimateTokens(v);
+    try {
+        return estimateTokens(JSON.stringify(v));
+    }
+    catch {
+        return 0;
+    }
+}
+/** Per-identity 24h-rolling token budget with 1h buckets. */
+export class TokenBudget {
+    limit;
+    now;
+    buckets = new Map();
+    filePath;
+    debounceMs;
+    flushTimer = null;
+    writeQueue = Promise.resolve();
+    bootstrapped = null;
+    constructor(cfg = {}) {
+        this.limit = cfg.dailyLimit && cfg.dailyLimit > 0 ? Math.floor(cfg.dailyLimit) : 0;
+        this.now = cfg.now ?? Date.now;
+        this.filePath = cfg.filePath;
+        this.debounceMs = cfg.flushDebounceMs ?? 1000;
+    }
+    /** Load a prior snapshot from disk (when filePath is set).
+     *  Safe to call multiple times — bootstraps once and caches. */
+    async bootstrap() {
+        if (!this.filePath)
+            return;
+        if (this.bootstrapped)
+            return this.bootstrapped;
+        this.bootstrapped = (async () => {
+            let raw;
+            try {
+                raw = await readFile(this.filePath, "utf8");
+            }
+            catch (e) {
+                // ENOENT on a first run is fine; everything else is worth a
+                // warning so an operator notices a missing-mount / perms
+                // issue immediately rather than discovering quotas reset
+                // silently on next restart.
+                if (e.code !== "ENOENT") {
+                    console.warn(`[token-budget] could not read snapshot ${this.filePath}: ${e.message} — starting fresh`);
+                }
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (e) {
+                console.warn(`[token-budget] snapshot ${this.filePath} is not valid JSON (${e.message}) — starting fresh, prior 24h charges are lost`);
+                return;
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                console.warn(`[token-budget] snapshot ${this.filePath} root is not a JSON object — starting fresh`);
+                return;
+            }
+            const now = this.now();
+            const cutoff = now - WINDOW_MS;
+            for (const [identity, raw] of Object.entries(parsed)) {
+                if (!Array.isArray(raw))
+                    continue;
+                const kept = [];
+                for (const b of raw) {
+                    if (!b || typeof b !== "object")
+                        continue;
+                    const at = b.at;
+                    const tokens = b.tokens;
+                    if (typeof at !== "number" || typeof tokens !== "number" || tokens <= 0)
+                        continue;
+                    if (at < cutoff)
+                        continue;
+                    kept.push({ at, tokens });
+                }
+                kept.sort((a, b) => a.at - b.at);
+                if (kept.length > 0)
+                    this.buckets.set(identity, kept);
+            }
+        })();
+        return this.bootstrapped;
+    }
+    /** Record-and-test: does adding `tokens` keep `identity` under the
+     *  daily cap? When `allowed`, the tokens are persisted into the
+     *  bucket; when denied, they are NOT recorded (so a single huge
+     *  request can't push the bucket arbitrarily over the cap and
+     *  starve the rest of the window). */
+    check(identity, tokens, now = this.now()) {
+        if (this.limit <= 0) {
+            // Uncapped → always allow, still track usage for /api/usage.
+            this.record(identity, tokens, now);
+            return { allowed: true, used: this.usedInWindow(identity, now), limit: 0, retryAfterSeconds: 0, freedAtRetry: 0 };
+        }
+        const safeTokens = tokens > 0 ? Math.floor(tokens) : 0;
+        const existing = this.usedInWindow(identity, now);
+        if (existing + safeTokens > this.limit) {
+            const needed = existing + safeTokens - this.limit;
+            const { waitMs, freed } = this.nextEnoughHeadroom(identity, now, needed);
+            return {
+                allowed: false,
+                used: existing,
+                limit: this.limit,
+                retryAfterSeconds: waitMs > 0 ? Math.max(1, Math.ceil(waitMs / 1000)) : 1,
+                freedAtRetry: freed,
+            };
+        }
+        this.record(identity, safeTokens, now);
+        return {
+            allowed: true,
+            used: existing + safeTokens,
+            limit: this.limit,
+            retryAfterSeconds: 0,
+            freedAtRetry: 0,
+        };
+    }
+    /** Read-only snapshot for /api/usage. */
+    inspect(identity, now = this.now()) {
+        return { used: this.usedInWindow(identity, now), limit: this.limit, windowMs: WINDOW_MS };
+    }
+    /** All identities the tracker has ever seen — for /api/usage aggregation. */
+    knownIdentities() {
+        return Array.from(this.buckets.keys());
+    }
+    /** For tests — clear everything. */
+    reset() {
+        this.buckets.clear();
+    }
+    /** Internal: append `tokens` to the current hour's bucket for
+     *  `identity`. Creates a new bucket when the hour boundary rolls. */
+    record(identity, tokens, now) {
+        if (tokens <= 0)
+            return;
+        const hourAt = Math.floor(now / HOUR_MS) * HOUR_MS;
+        const fresh = this.pruneOld(identity, now);
+        const last = fresh[fresh.length - 1];
+        if (last && last.at === hourAt) {
+            last.tokens += tokens;
+        }
+        else {
+            fresh.push({ at: hourAt, tokens });
+        }
+        this.buckets.set(identity, fresh);
+        this.scheduleFlush();
+    }
+    /** Debounce a snapshot write. No-op when filePath isn't configured. */
+    scheduleFlush() {
+        if (!this.filePath)
+            return;
+        if (this.flushTimer)
+            return;
+        if (this.debounceMs === 0) {
+            // Tests pass 0 so the write happens before the next assertion.
+            void this.flushNow();
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushNow();
+        }, this.debounceMs);
+        // Don't keep the event loop alive for the snapshot flush —
+        // the in-memory state is the truth; the file is a recovery
+        // aid. Process shutdown without one final flush loses at
+        // most one debounce window of charge data.
+        if (typeof this.flushTimer.unref === "function")
+            this.flushTimer.unref();
+    }
+    /** Write the current bucket state to disk atomically (tmp + rename).
+     *  Public so a graceful shutdown can `await tokenBudget.flushNow()`. */
+    async flushNow() {
+        if (!this.filePath)
+            return;
+        const path = this.filePath;
+        // Build the snapshot synchronously so we capture a consistent
+        // point-in-time view of the map, then write asynchronously.
+        const snapshot = {};
+        for (const [id, buckets] of this.buckets) {
+            if (buckets.length > 0)
+                snapshot[id] = buckets;
+        }
+        const body = JSON.stringify(snapshot);
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                const tmp = path + ".tmp";
+                await writeFile(tmp, body, "utf8");
+                await rename(tmp, path);
+            }
+            catch {
+                // Best-effort: persistence is recovery insurance, not the
+                // source of truth. A failed write doesn't poison in-memory
+                // state.
+            }
+        });
+        return this.writeQueue;
+    }
+    /** Internal: drop buckets older than 24h and return the remainder. */
+    pruneOld(identity, now) {
+        const cutoff = now - WINDOW_MS;
+        const buckets = this.buckets.get(identity) ?? [];
+        let i = 0;
+        while (i < buckets.length && buckets[i].at < cutoff)
+            i++;
+        if (i === 0)
+            return buckets;
+        const kept = buckets.slice(i);
+        this.buckets.set(identity, kept);
+        return kept;
+    }
+    usedInWindow(identity, now) {
+        const fresh = this.pruneOld(identity, now);
+        let total = 0;
+        for (const b of fresh)
+            total += b.tokens;
+        return total;
+    }
+    /** Walk the bucket list oldest-first until enough tokens would have
+     *  dropped off to fit a request needing `needed` extra headroom.
+     *  Returns the wait in ms + the cumulative freed tokens at that
+     *  point. When `needed` exceeds the entire window's content (the
+     *  caller wants more than the cap), returns the time until the
+     *  newest bucket drops + everything freed. */
+    nextEnoughHeadroom(identity, now, needed) {
+        const fresh = this.pruneOld(identity, now);
+        if (fresh.length === 0)
+            return { waitMs: 0, freed: 0 };
+        let freed = 0;
+        for (const b of fresh) {
+            freed += b.tokens;
+            if (freed >= needed) {
+                const dropAt = b.at + WINDOW_MS;
+                return { waitMs: Math.max(0, dropAt - now), freed };
+            }
+        }
+        // Even dropping every bucket isn't enough — the request alone
+        // exceeds the daily cap. Return the time until the newest bucket
+        // drops so the caller knows the window will be empty by then; the
+        // request will still get rejected on size if it exceeds limit.
+        const newest = fresh[fresh.length - 1];
+        return { waitMs: Math.max(0, newest.at + WINDOW_MS - now), freed };
+    }
+}
+/** Parse OMCP_TOOL_DAILY_TOKENS into a daily limit. Mirrors the
+ *  resolveToolRatePerMin pattern: unset / empty / non-numeric /
+ *  zero / negative → uncapped (0). Positive integers pass through. */
+export function resolveDailyTokenLimit(raw) {
+    if (raw === undefined || raw === "")
+        return 0;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.floor(n);
+}

package/dist/quota/token-budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/quota/token-budget.test.js

@@ -0,0 +1,215 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { TokenBudget, estimateTokens, estimateTokensFor, resolveDailyTokenLimit } from "./token-budget.js";
+test("estimateTokens — empty/null/undefined → 0", () => {
+    assert.equal(estimateTokens(""), 0);
+});
+test("estimateTokens — over-counts by design (~5% above chars/4)", () => {
+    // 100 chars → cl100k actual is ~22-25; our estimate is ceil(100/4 * 1.05) = 27.
+    // We want > chars/4 so quota enforcement errs on the strict side.
+    const t = estimateTokens("x".repeat(100));
+    assert.ok(t >= 26, `expected ≥26, got ${t}`);
+    assert.ok(t <= 30, `expected ≤30, got ${t}`);
+});
+test("estimateTokensFor — handles non-string values via JSON serialisation", () => {
+    assert.equal(estimateTokensFor(null), 0);
+    assert.equal(estimateTokensFor(undefined), 0);
+    assert.ok(estimateTokensFor({ a: 1, b: "hello" }) > 0);
+    assert.ok(estimateTokensFor([1, 2, 3]) > 0);
+});
+test("estimateTokensFor — circular / non-serialisable returns 0 (don't crash)", () => {
+    const a = {};
+    a.self = a;
+    assert.equal(estimateTokensFor(a), 0);
+});
+test("TokenBudget — uncapped allows everything but still tracks usage", () => {
+    const t = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 0, now: () => t });
+    const r = b.check("alice", 999_999);
+    assert.equal(r.allowed, true);
+    assert.equal(r.limit, 0);
+    assert.equal(b.inspect("alice").used, 999_999);
+});
+test("TokenBudget — allows up to the daily cap, denies the request that would exceed", () => {
+    const t = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 1000, now: () => t });
+    assert.equal(b.check("alice", 600).allowed, true);
+    assert.equal(b.check("alice", 300).allowed, true);
+    // 600 + 300 = 900; +200 would push to 1100 → deny
+    const denied = b.check("alice", 200);
+    assert.equal(denied.allowed, false);
+    assert.equal(denied.used, 900, "denied request must NOT have been recorded");
+    assert.equal(denied.limit, 1000);
+    assert.ok(denied.retryAfterSeconds > 0);
+    // Subsequent small request within remaining headroom still works
+    assert.equal(b.check("alice", 50).allowed, true);
+});
+test("TokenBudget — 24h rolling: buckets older than 24h drop off", () => {
+    let now = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 1000, now: () => now });
+    b.check("alice", 800); // bucket at hour 0
+    now += 23 * 60 * 60 * 1000; // +23h: still in window
+    assert.equal(b.inspect("alice").used, 800);
+    now += 2 * 60 * 60 * 1000; // +25h total: bucket from hour 0 drops
+    assert.equal(b.inspect("alice").used, 0);
+    // Full daily budget available again
+    assert.equal(b.check("alice", 1000).allowed, true);
+});
+test("TokenBudget — denied request returns retryAfter ≈ time until enough buckets drop to fit the request", () => {
+    let now = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 100, now: () => now });
+    b.check("alice", 100); // fully consumed at hour 0
+    now += 60 * 60 * 1000; // +1h
+    const denied = b.check("alice", 1);
+    assert.equal(denied.allowed, false);
+    // Need 1 free; oldest bucket (100 tokens) drops at hour 24 → ~23h wait.
+    const expectedSeconds = 23 * 60 * 60;
+    assert.ok(Math.abs(denied.retryAfterSeconds - expectedSeconds) < 3600, `expected ~${expectedSeconds}s, got ${denied.retryAfterSeconds}s`);
+    // freedAtRetry exposes how much will be available
+    assert.equal(denied.freedAtRetry, 100);
+});
+test("TokenBudget — retryAfter walks enough buckets to fit a LARGER request", () => {
+    let now = 1_700_000_000_000;
+    const HOUR = 60 * 60 * 1000;
+    const b = new TokenBudget({ dailyLimit: 1000, now: () => now });
+    // Three 300-token calls spread across 3 different hours.
+    b.check("alice", 300, now); // bucket hour 0
+    b.check("alice", 300, now + HOUR); // bucket hour 1
+    b.check("alice", 400, now + 2 * HOUR); // bucket hour 2 — total 1000
+    now += 3 * HOUR;
+    // Now request 700 more. Need 700 free. Dropping bucket@hour0 (300)
+    // only frees 300 — not enough. Dropping bucket@hour1 (300 more)
+    // gets to 600 — still not enough. Dropping bucket@hour2 (400 more)
+    // gets to 1000 — fits 700 with headroom.
+    const denied = b.check("alice", 700);
+    assert.equal(denied.allowed, false);
+    // Must wait until bucket@hour1 drops (at hour 1 + 24 = hour 25),
+    // we are at hour 3 → 22h wait? No — we need bucket@hour1 to drop to
+    // get freed=600, still not enough. Need bucket@hour2 → drops at
+    // hour 26, we're at hour 3 → 23h wait, with 1000 freed by then.
+    const expectedSeconds = 23 * 60 * 60;
+    assert.ok(Math.abs(denied.retryAfterSeconds - expectedSeconds) < 3600, `expected ~${expectedSeconds}s, got ${denied.retryAfterSeconds}s`);
+    assert.equal(denied.freedAtRetry, 1000, "all three buckets must have dropped to fit the 700 request");
+});
+test("TokenBudget — per-identity isolation (alice's bucket doesn't affect bob)", () => {
+    const t = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 1000, now: () => t });
+    b.check("alice", 1000); // fully consumed
+    assert.equal(b.check("alice", 1).allowed, false);
+    assert.equal(b.check("bob", 500).allowed, true);
+    assert.equal(b.inspect("bob").used, 500);
+});
+test("TokenBudget — hour bucket aggregation: 3 calls in the same hour share one bucket", () => {
+    let now = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 10000, now: () => now });
+    b.check("alice", 100, now);
+    b.check("alice", 200, now + 5_000);
+    b.check("alice", 50, now + 10_000);
+    assert.equal(b.inspect("alice").used, 350);
+});
+test("TokenBudget — knownIdentities surfaces every identity seen", () => {
+    const t = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 0, now: () => t });
+    b.check("a", 1);
+    b.check("b", 1);
+    b.check("a", 1);
+    assert.deepEqual(b.knownIdentities().sort(), ["a", "b"]);
+});
+test("TokenBudget — zero/negative tokens silently dropped", () => {
+    const t = 1_700_000_000_000;
+    const b = new TokenBudget({ dailyLimit: 1000, now: () => t });
+    b.check("alice", 0);
+    b.check("alice", -10);
+    assert.equal(b.inspect("alice").used, 0);
+});
+test("resolveDailyTokenLimit — unset/empty/zero/negative/non-numeric → 0 (uncapped)", () => {
+    assert.equal(resolveDailyTokenLimit(undefined), 0);
+    assert.equal(resolveDailyTokenLimit(""), 0);
+    assert.equal(resolveDailyTokenLimit("0"), 0);
+    assert.equal(resolveDailyTokenLimit("-100"), 0);
+    assert.equal(resolveDailyTokenLimit("not-a-number"), 0);
+    assert.equal(resolveDailyTokenLimit("NaN"), 0);
+});
+test("resolveDailyTokenLimit — positive integers pass through; decimals floored", () => {
+    assert.equal(resolveDailyTokenLimit("50000"), 50000);
+    assert.equal(resolveDailyTokenLimit("1"), 1);
+    assert.equal(resolveDailyTokenLimit("1234.7"), 1234);
+});
+test("TokenBudget persistence — flushNow writes a snapshot that bootstrap() reads back", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-token-"));
+    const file = join(dir, "budget.json");
+    try {
+        const t = 1_700_000_000_000;
+        const b1 = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 0, now: () => t });
+        b1.check("alice", 300);
+        b1.check("bob", 700);
+        await b1.flushNow();
+        const text = await readFile(file, "utf8");
+        const parsed = JSON.parse(text);
+        assert.equal(parsed.alice[0].tokens, 300);
+        assert.equal(parsed.bob[0].tokens, 700);
+        // A fresh tracker pointed at the same file picks up the buckets.
+        const b2 = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 0, now: () => t });
+        await b2.bootstrap();
+        assert.equal(b2.inspect("alice").used, 300);
+        assert.equal(b2.inspect("bob").used, 700);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("TokenBudget persistence — bootstrap drops entries older than 24h", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-token-"));
+    const file = join(dir, "budget.json");
+    try {
+        const t0 = 1_700_000_000_000;
+        const b1 = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 0, now: () => t0 });
+        b1.check("alice", 500);
+        await b1.flushNow();
+        // Restart 30h later — the alice entry should drop on bootstrap.
+        const tLater = t0 + 30 * 60 * 60 * 1000;
+        const b2 = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 0, now: () => tLater });
+        await b2.bootstrap();
+        assert.equal(b2.inspect("alice").used, 0, "expired buckets must drop on bootstrap");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("TokenBudget persistence — corrupt snapshot is tolerated (start fresh, don't crash)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-token-"));
+    const file = join(dir, "budget.json");
+    try {
+        // Write something that's not valid JSON.
+        const fs = await import("node:fs/promises");
+        await fs.writeFile(file, "{not: json", "utf8");
+        const b = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 0 });
+        await b.bootstrap();
+        // Tracker should be empty; subsequent operations should work fine.
+        assert.equal(b.inspect("alice").used, 0);
+        b.check("alice", 100);
+        assert.equal(b.inspect("alice").used, 100);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("TokenBudget persistence — debounced flush eventually writes (default 1s)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-token-"));
+    const file = join(dir, "budget.json");
+    try {
+        const b = new TokenBudget({ dailyLimit: 1000, filePath: file, flushDebounceMs: 50 });
+        b.check("alice", 42);
+        // Wait past the debounce window
+        await new Promise((r) => setTimeout(r, 120));
+        const text = await readFile(file, "utf8");
+        const parsed = JSON.parse(text);
+        assert.equal(parsed.alice[0].tokens, 42);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});

package/dist/tenancy/context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Multi-tenant context primitives.
+ *
+ * Every request lands in EXACTLY ONE tenant. Identities resolve to a
+ * tenant via one of three paths:
+ *
+ *   1. Anonymous (no auth, the demo / single-operator path) → DEFAULT_TENANT.
+ *   2. Basic-mode local user → user file's optional `tenant` field;
+ *      missing → DEFAULT_TENANT (so existing single-tenant deployments
+ *      keep working without any config change).
+ *   3. OIDC session → OMCP_OIDC_TENANT_CLAIM (default `tenant`);
+ *      empty / missing claim → DEFAULT_TENANT.
+ *   4. MCP credential (bearer token) → optional per-credential
+ *      `tenant` field assigned via OMCP_KEY_TENANTS env, mirroring
+ *      OMCP_KEY_SOURCES / OMCP_KEY_BYPASS_REDACTION shape.
+ *
+ * The constant `DEFAULT_TENANT` is the universal escape hatch — any
+ * non-multi-tenant deployment behaves as if everything is in
+ * tenant `default`, identical to the pre-E7 single-namespace world.
+ *
+ * Cross-tenant requests return 404 (not 403) per the plan — leaking
+ * existence by status code defeats half the point of isolation.
+ */
+export declare const DEFAULT_TENANT = "default";
+/** Maximum tenant identifier length. Defence-in-depth against a
+ *  hostile claim payload pushing arbitrary KB-sized strings through
+ *  every cookie. Operators with longer names should pick shorter
+ *  ones; the audit chain still hashes the full string but the
+ *  cookie payload + log lines stay bounded. */
+export declare const MAX_TENANT_LENGTH = 64;
+/** Normalise + validate a tenant identifier. Returns the trimmed,
+ *  lower-cased string when valid; DEFAULT_TENANT for empty or
+ *  invalid input (silent fallback rather than crash — an OIDC claim
+ *  with junk should drop the user into the safe default, not 500
+ *  the whole flow). */
+export declare function normaliseTenant(raw: unknown): string;
+/** Walk a dotted-path claim out of an arbitrary claim set, then
+ *  normalise. Used for OIDC sessions where the tenant lives at e.g.
+ *  `app.tenant_id` rather than the top level. */
+export declare function tenantFromClaim(claims: Record<string, unknown>, claimPath: string): string;
+/** Parse OMCP_KEY_TENANTS="ci=acme;agent=bigco" into a name → tenant
+ *  map. Mirrors parseKeySources in auth/credentials.ts so the operator
+ *  cognitive load stays low. Invalid tenant strings normalise to
+ *  DEFAULT_TENANT silently. */
+export declare function parseKeyTenants(raw: string | undefined): Map<string, string>;

package/dist/tenancy/context.js

@@ -0,0 +1,97 @@
+/**
+ * Multi-tenant context primitives.
+ *
+ * Every request lands in EXACTLY ONE tenant. Identities resolve to a
+ * tenant via one of three paths:
+ *
+ *   1. Anonymous (no auth, the demo / single-operator path) → DEFAULT_TENANT.
+ *   2. Basic-mode local user → user file's optional `tenant` field;
+ *      missing → DEFAULT_TENANT (so existing single-tenant deployments
+ *      keep working without any config change).
+ *   3. OIDC session → OMCP_OIDC_TENANT_CLAIM (default `tenant`);
+ *      empty / missing claim → DEFAULT_TENANT.
+ *   4. MCP credential (bearer token) → optional per-credential
+ *      `tenant` field assigned via OMCP_KEY_TENANTS env, mirroring
+ *      OMCP_KEY_SOURCES / OMCP_KEY_BYPASS_REDACTION shape.
+ *
+ * The constant `DEFAULT_TENANT` is the universal escape hatch — any
+ * non-multi-tenant deployment behaves as if everything is in
+ * tenant `default`, identical to the pre-E7 single-namespace world.
+ *
+ * Cross-tenant requests return 404 (not 403) per the plan — leaking
+ * existence by status code defeats half the point of isolation.
+ */
+export const DEFAULT_TENANT = "default";
+/** Maximum tenant identifier length. Defence-in-depth against a
+ *  hostile claim payload pushing arbitrary KB-sized strings through
+ *  every cookie. Operators with longer names should pick shorter
+ *  ones; the audit chain still hashes the full string but the
+ *  cookie payload + log lines stay bounded. */
+export const MAX_TENANT_LENGTH = 64;
+/** Pattern: alphanumeric + `-` + `_` + `.`. Mirrors what most CI
+ *  identifiers accept. Rejects `/`, space, control chars (which
+ *  could break filesystem layouts in slice 2). */
+const VALID_TENANT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Normalise + validate a tenant identifier. Returns the trimmed,
+ *  lower-cased string when valid; DEFAULT_TENANT for empty or
+ *  invalid input (silent fallback rather than crash — an OIDC claim
+ *  with junk should drop the user into the safe default, not 500
+ *  the whole flow). */
+export function normaliseTenant(raw) {
+    if (typeof raw !== "string")
+        return DEFAULT_TENANT;
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return DEFAULT_TENANT;
+    if (trimmed.length > MAX_TENANT_LENGTH)
+        return DEFAULT_TENANT;
+    if (!VALID_TENANT_RE.test(trimmed))
+        return DEFAULT_TENANT;
+    return trimmed;
+}
+/** Walk a dotted-path claim out of an arbitrary claim set, then
+ *  normalise. Used for OIDC sessions where the tenant lives at e.g.
+ *  `app.tenant_id` rather than the top level. */
+export function tenantFromClaim(claims, claimPath) {
+    if (!claimPath)
+        return DEFAULT_TENANT;
+    const parts = claimPath.split(".");
+    let cur = claims;
+    for (const p of parts) {
+        if (cur && typeof cur === "object" && !Array.isArray(cur) && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return DEFAULT_TENANT;
+        }
+    }
+    // Arrays: take the first string-shaped entry (the same posture as
+    // resolveRoles in auth/oidc/runtime.ts). Operators wanting per-call
+    // multi-tenancy should use one tenant claim per token, not a list.
+    if (Array.isArray(cur)) {
+        for (const v of cur)
+            if (typeof v === "string")
+                return normaliseTenant(v);
+        return DEFAULT_TENANT;
+    }
+    return normaliseTenant(cur);
+}
+/** Parse OMCP_KEY_TENANTS="ci=acme;agent=bigco" into a name → tenant
+ *  map. Mirrors parseKeySources in auth/credentials.ts so the operator
+ *  cognitive load stays low. Invalid tenant strings normalise to
+ *  DEFAULT_TENANT silently. */
+export function parseKeyTenants(raw) {
+    const out = new Map();
+    if (!raw)
+        return out;
+    for (const entry of raw.split(";").map((s) => s.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = entry.slice(0, eq).trim();
+        const tenant = normaliseTenant(entry.slice(eq + 1).trim());
+        if (name)
+            out.set(name, tenant);
+    }
+    return out;
+}

package/dist/tenancy/context.test.d.ts

@@ -0,0 +1 @@
+export {};