@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/policy/redact.js

@@ -0,0 +1,144 @@
+/**
+ * Conservative PII / secret redaction for tool outputs that may contain
+ * arbitrary log payloads.
+ *
+ * Scope of this module: pure string redaction with deterministic
+ * patterns. Returns the rewritten string plus a per-category count so
+ * callers can surface a "redacted N matches" hint to the user / agent
+ * without leaking what was matched. Designed to be safe-by-default
+ * (over-redact rather than under-redact) and explicit (each category
+ * tagged in the replacement marker, e.g. `[redacted-email]`).
+ *
+ * Bypass today is process-wide only: set `OMCP_REDACTION=off` if the
+ * upstream is already PII-clean. A per-request `redaction:bypass` RBAC
+ * permission for interactive admin sessions is on the roadmap — see
+ * docs/access-control.md "Why are my logs returning [redacted-email]?"
+ * and docs/redaction.md for the current state.
+ */
+// Patterns chosen for low false-positive on operational log text:
+// - Email: standard local@domain.tld with limited TLD chars.
+// - IPv4: strict 0-255 quads to avoid matching version numbers etc.
+// - IPv6: full / compressed; we accept the common forms only.
+// - Bearer: "Authorization: Bearer <token>" — pulls the token out.
+// - JWT: 3-part base64url joined by dots.
+// - Generic API-key: long alnum + base64-ish run after a key= marker.
+const PATTERNS = [
+    // High-confidence cloud-vendor secrets go first — their prefixes are
+    // distinctive enough that they don't conflict with generic patterns.
+    // - AWS access key id: 16-32 chars after AKIA/ASIA/AROA prefix.
+    // - Slack tokens: xoxa-/xoxb-/xoxp-/xoxr-/xoxs- + 10+ chars.
+    // - GitHub PAT: github_pat_<base62 segments> or ghp_/gho_/ghs_/ghu_/ghr_ + 36 chars.
+    // - PEM private-key blocks: greedy match across newlines.
+    { category: "aws-key", re: /\b(?:AKIA|ASIA|AROA)[0-9A-Z]{16,20}\b/g },
+    { category: "slack-token", re: /\bxox[abprsu]-[A-Za-z0-9-]{10,}\b/g },
+    { category: "gh-pat", re: /\b(?:github_pat_[A-Za-z0-9_]{40,}|gh[opsuru]_[A-Za-z0-9]{36})\b/g },
+    { category: "private-key", re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+    // emails before other patterns so they don't get eaten partially
+    { category: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,24}\b/g },
+    { category: "jwt", re: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g },
+    { category: "bearer", re: /\b[Bb]earer\s+[A-Za-z0-9._\-+/=]{12,}\b/g },
+    { category: "api-key", re: /\b(?:api[_-]?key|x-api-key|token|secret)[=:]\s*['"]?[A-Za-z0-9._\-+/=]{16,}['"]?/gi },
+    // ipv6 — covers full, mid-compressed, leading "::loopback" / "::ffff:v4"
+    // mapped forms, and "::1". Trailing-only `xxxx::` shapes are rare in
+    // operational logs and intentionally not covered. MUST run before
+    // ipv4 so that the IPv4-mapped form (`::ffff:192.168.1.42`) is
+    // classified as IPv6 rather than having ipv4 eat the dotted tail
+    // and leave a half-redacted `::ffff:[redacted-ipv4]` token.
+    { category: "ipv6", re: /\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,6}(?::[0-9a-fA-F]{1,4}){1,6}\b|::1\b|::ffff:(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g },
+    { category: "ipv4", re: /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g },
+];
+function emptyCounts() {
+    return {
+        email: 0, ipv4: 0, ipv6: 0, bearer: 0, jwt: 0, "api-key": 0,
+        "aws-key": 0, "slack-token": 0, "private-key": 0, "gh-pat": 0,
+        "credit-card": 0,
+    };
+}
+/** Luhn check — accepts digits-only string of 13–19 chars. Used to
+ * keep the credit-card redaction from over-matching random digit
+ * strings (order IDs, timestamps, etc.). */
+function luhn(digits) {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = digits.charCodeAt(i) - 48;
+        if (n < 0 || n > 9)
+            return false;
+        if (alt) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+/** Run all patterns in a deterministic order; later patterns won't
+ * re-match content already replaced by an earlier one (the marker
+ * starts with `[redacted-` which none of the patterns match). */
+export function redactText(input) {
+    const matches = emptyCounts();
+    let text = input;
+    for (const { category, re } of PATTERNS) {
+        text = text.replace(re, () => {
+            matches[category] += 1;
+            return `[redacted-${category}]`;
+        });
+    }
+    // Credit-card pass runs last so an inner-substring of a longer
+    // already-redacted token can't accidentally match. Luhn-validated
+    // so order numbers / timestamps / random digit strings stay intact.
+    text = text.replace(/\b(?:\d[ -]?){12,18}\d\b/g, (match) => {
+        const digits = match.replace(/[ -]/g, "");
+        if (digits.length < 13 || digits.length > 19)
+            return match;
+        if (!luhn(digits))
+            return match;
+        matches["credit-card"] += 1;
+        return "[redacted-credit-card]";
+    });
+    let total = 0;
+    for (const k of Object.keys(matches))
+        total += matches[k];
+    return { text, matches, totalMatches: total };
+}
+/** Maximum nesting depth the walker will descend into. Operational
+ * log payloads are essentially flat (objects of strings + a few
+ * nested arrays); a pathologically deep structure is almost certainly
+ * a bug or an attack, and stack-overflowing the auth path is worse
+ * than truncating. The cap is generous — well above anything a
+ * Prometheus / Loki record would ever produce. */
+export const MAX_REDACT_DEPTH = 64;
+/** Walk an arbitrary parsed-JSON value and redact every string leaf,
+ * accumulating match counts. Non-string leaves and structural keys are
+ * left untouched. Returns a new value (does not mutate input). Bails
+ * out below `MAX_REDACT_DEPTH` levels of nesting and returns the raw
+ * sub-tree untouched at that point. */
+export function redactValue(input) {
+    const counts = emptyCounts();
+    function walk(v, depth) {
+        if (depth > MAX_REDACT_DEPTH)
+            return v;
+        if (typeof v === "string") {
+            const r = redactText(v);
+            for (const k of Object.keys(counts))
+                counts[k] += r.matches[k];
+            return r.text;
+        }
+        if (Array.isArray(v))
+            return v.map((x) => walk(x, depth + 1));
+        if (v && typeof v === "object") {
+            const out = {};
+            for (const [k, vv] of Object.entries(v))
+                out[k] = walk(vv, depth + 1);
+            return out;
+        }
+        return v;
+    }
+    const value = walk(input, 0);
+    let total = 0;
+    for (const k of Object.keys(counts))
+        total += counts[k];
+    return { value, matches: counts, totalMatches: total };
+}

package/dist/policy/redact.test.d.ts

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

package/dist/policy/redact.test.js

@@ -0,0 +1,172 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { redactText, redactValue } from "./redact.js";
+test("redactText — emails are redacted, counted", () => {
+    const r = redactText("alert from alice@example.com to bob@corp.co.uk");
+    assert.equal(r.matches.email, 2);
+    assert.equal(r.totalMatches, 2);
+    assert.match(r.text, /\[redacted-email\].*\[redacted-email\]/);
+});
+test("redactText — IPv4 quads redacted, version numbers left alone", () => {
+    const r = redactText("client 192.168.1.42 connected to 10.0.0.1; version 1.2.3.4");
+    // "1.2.3.4" technically matches as IPv4 — that's fine, it's a valid IPv4
+    // and our threat model errs on the side of over-redaction.
+    assert.ok(r.matches.ipv4 >= 2);
+    assert.match(r.text, /\[redacted-ipv4\]/);
+});
+test("redactText — bearer tokens stripped", () => {
+    const r = redactText('GET /api/foo Authorization: Bearer abcdef1234567890XYZ');
+    assert.equal(r.matches.bearer, 1);
+    assert.match(r.text, /\[redacted-bearer\]/);
+    assert.doesNotMatch(r.text, /abcdef1234567890XYZ/);
+});
+test("redactText — JWTs detected by eyJ prefix + three-part shape", () => {
+    const jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMifQ.abcdefghijk-_ABC";
+    const r = redactText(`token=${jwt} for user`);
+    assert.ok(r.matches.jwt >= 1);
+    assert.doesNotMatch(r.text, /eyJ/);
+});
+test("redactText — api-key / cloud-token style assignments", () => {
+    // r1: generic prefix-based api-key match.
+    // r2: x-api-key with an opaque body — falls through to api-key.
+    // r3: token= with a Slack-shape value — the new slack-token pattern
+    //     wins because it runs before api-key; either outcome is fine,
+    //     the contract is "the secret is gone after one pass".
+    const r1 = redactText('api_key="abc123def456ghi789jkl"');
+    const r2 = redactText("x-api-key: sk_test_abcdefghijklmnopqrstuvwxyz");
+    const r3 = redactText("token=xoxb-1234567890-abcdefghijklm");
+    assert.ok(r1.totalMatches >= 1, "expected r1 to be redacted somewhere");
+    assert.ok(r2.totalMatches >= 1, "expected r2 to be redacted somewhere");
+    assert.ok(r3.totalMatches >= 1, "expected r3 to be redacted somewhere");
+    assert.doesNotMatch(r1.text, /abc123def456ghi789jkl/);
+    assert.doesNotMatch(r2.text, /sk_test_abcdefghijklmnopqrstuvwxyz/);
+    assert.doesNotMatch(r3.text, /xoxb-1234567890/);
+});
+test("redactText — leaves harmless text alone", () => {
+    const r = redactText("the order-service replied with 200 OK after 45ms");
+    assert.equal(r.totalMatches, 0);
+    assert.equal(r.text, "the order-service replied with 200 OK after 45ms");
+});
+test("redactText — long digit strings without Luhn don't trigger credit-card", () => {
+    // 16-digit telemetry sequence (UNIX nanos + service id) — should pass through.
+    const r = redactText("ts=1717000000000000000 seq=4242424242424242 user=test");
+    // 4242424242424242 IS Luhn-valid (Visa test number), so that counts as a hit;
+    // but ts=1717... starts with a non-bordered digit run that includes "1717" pattern.
+    // The assertion: only the Luhn-valid 16-digit string is counted as credit-card.
+    assert.equal(r.matches["credit-card"], 1);
+});
+test("redactText — already-redacted markers don't re-match in further passes", () => {
+    // Run the redactor twice; the second pass should be a no-op.
+    const first = redactText("contact alice@example.com");
+    const second = redactText(first.text);
+    assert.equal(second.totalMatches, 0);
+});
+test("redactValue — walks nested objects / arrays, mutates only strings", () => {
+    const input = {
+        user: "bob@corp.co.uk",
+        nested: {
+            ip: "10.0.0.1",
+            count: 42,
+            tags: ["audit", "client=alice@example.com"],
+        },
+        flag: true,
+    };
+    const r = redactValue(input);
+    const v = r.value;
+    assert.equal(v.user, "[redacted-email]");
+    assert.equal(v.nested.ip, "[redacted-ipv4]");
+    assert.equal(v.nested.count, 42);
+    assert.equal(v.nested.tags[0], "audit");
+    assert.equal(v.nested.tags[1], "client=[redacted-email]");
+    assert.equal(v.flag, true);
+    assert.equal(r.matches.email, 2);
+    assert.equal(r.matches.ipv4, 1);
+    assert.equal(r.totalMatches, 3);
+});
+test("redactText — AWS access key IDs (AKIA / ASIA / AROA) are redacted", () => {
+    const r1 = redactText("log: assumed role AKIAIOSFODNN7EXAMPLE today");
+    const r2 = redactText("temporary creds ASIAY34FZKBOKMUTVV7A logged");
+    const r3 = redactText("role-arn AROAIIAFOO2ZBADBCEXAMPLE");
+    assert.equal(r1.matches["aws-key"], 1);
+    assert.equal(r2.matches["aws-key"], 1);
+    assert.equal(r3.matches["aws-key"], 1);
+    assert.match(r1.text, /\[redacted-aws-key\]/);
+    assert.doesNotMatch(r1.text, /AKIAIOSFODNN7EXAMPLE/);
+});
+test("redactText — Slack tokens (xoxa / xoxb / xoxp / …) are redacted", () => {
+    const r = redactText("slack notify: token=xoxb-1234567890-abcdefghijklm result: ok");
+    assert.equal(r.matches["slack-token"], 1);
+    assert.doesNotMatch(r.text, /xoxb-1234567890/);
+});
+test("redactText — GitHub PATs are redacted (ghp_ / github_pat_)", () => {
+    const r1 = redactText("git remote set-url origin https://ghp_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789@github.com/x/y.git");
+    // Use a 40-char body, which matches `[A-Za-z0-9_]{40,}` (note: includes underscore)
+    const r2 = redactText("token github_pat_ABCDEFGH_IJKLMNOPQRSTUVWXYZ012345678ABCDEFGHIJKLMNOP");
+    assert.equal(r1.matches["gh-pat"], 1);
+    assert.equal(r2.matches["gh-pat"], 1);
+});
+test("redactText — Luhn-valid credit-card numbers are redacted, invalid ones pass through", () => {
+    // Visa test number 4111 1111 1111 1111 (Luhn-valid)
+    const r1 = redactText("charge attempted on card 4111111111111111 for $42.00");
+    assert.equal(r1.matches["credit-card"], 1);
+    assert.match(r1.text, /\[redacted-credit-card\]/);
+    // Same number with separators
+    const r2 = redactText("card 4111-1111-1111-1111 declined");
+    assert.equal(r2.matches["credit-card"], 1);
+    assert.doesNotMatch(r2.text, /4111-1111-1111-1111/);
+    // Random 16 digits that DON'T pass Luhn → left alone (e.g. order ID)
+    const r3 = redactText("order 1234567890123456 created");
+    assert.equal(r3.matches["credit-card"], 0);
+    assert.match(r3.text, /1234567890123456/);
+    // Too short / too long stays as-is
+    const r4 = redactText("seq 123456789012 and 12345678901234567890");
+    assert.equal(r4.matches["credit-card"], 0);
+});
+test("redactText — PEM private-key blocks are redacted greedily", () => {
+    const pem = `-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAwLPVKj…
+-----END RSA PRIVATE KEY-----`;
+    const r = redactText(`config:\n${pem}\nend`);
+    assert.equal(r.matches["private-key"], 1);
+    assert.doesNotMatch(r.text, /MIIEpAIBAA/);
+});
+test("redactValue — pathologically deep nesting hits the depth cap, returns sub-tree untouched", () => {
+    // Build a structure deeper than MAX_REDACT_DEPTH (64). At the cap,
+    // the walker should return the remaining sub-tree as-is — no
+    // mutations beyond depth 64, and no stack overflow.
+    let leaf = "alice@example.com";
+    for (let i = 0; i < 200; i++)
+        leaf = { wrap: leaf };
+    // Wrap the deep sub-tree inside a shallow root so a string near
+    // the surface still gets redacted.
+    const r = redactValue({ shallow: "bob@example.com", deep: leaf });
+    const v = r.value;
+    assert.equal(v.shallow, "[redacted-email]", "shallow leaf still redacted");
+    assert.equal(r.matches.email, 1, "only the shallow email is redacted past the depth cap");
+});
+test("redactText — IPv6 addresses are redacted across full / compressed / mapped forms", () => {
+    // Full 8-group address
+    const r1 = redactText("peer 2001:0db8:85a3:0000:0000:8a2e:0370:7334 connected");
+    assert.ok(r1.matches.ipv6 >= 1, "expected full IPv6 to be redacted");
+    assert.doesNotMatch(r1.text, /2001:0db8/);
+    // Mid-compressed (single :: collapsing one zero run)
+    const r2 = redactText("client 2001:db8::8a2e:370:7334 disconnected");
+    assert.ok(r2.matches.ipv6 >= 1, "expected compressed IPv6 to be redacted");
+    // Loopback
+    const r3 = redactText("listening on ::1 port 8080");
+    assert.ok(r3.matches.ipv6 >= 1, "expected ::1 loopback to be redacted");
+    assert.doesNotMatch(r3.text, /::1\b/);
+    // IPv4-mapped IPv6
+    const r4 = redactText("source ::ffff:192.168.1.42 forwarded");
+    assert.ok(r4.matches.ipv6 >= 1, "expected ::ffff: mapped form to be redacted");
+    // Pure version string — must NOT match IPv6 (only two colons, not 7-group)
+    const r5 = redactText("server version 1.2.3 build 4");
+    assert.equal(r5.matches.ipv6, 0, "version string must not look like IPv6");
+});
+test("redactValue — null / undefined leaves are preserved", () => {
+    const r = redactValue({ a: null, b: undefined, c: "alice@example.com" });
+    const v = r.value;
+    assert.equal(v.a, null);
+    assert.equal(v.b, undefined);
+    assert.equal(v.c, "[redacted-email]");
+});

package/dist/products/loader.d.ts

@@ -0,0 +1,84 @@
+/**
+ * MCP Products — curated, agent-facing collections of tools.
+ *
+ * A Product is a named bundle that ships with branding metadata
+ * (icon, description, version) plus a list of allowed MCP tools.
+ * The agent calling /mcp can be told which Product it belongs to
+ * (via a future header / arg, slice 2+), and the server can filter
+ * tools/list and tools/call responses accordingly.
+ *
+ * Today's surface (slice 1):
+ *   - In-memory ProductsStore loaded from OMCP_PRODUCTS_FILE
+ *     (YAML or JSON). Missing/empty file → empty catalog.
+ *   - Strict validation: unknown action / unknown resource /
+ *     unexpected keys reject loudly.
+ *   - Hot-reload on next /api/products call (slice 2 wires the
+ *     reload trigger; for now the file is read once at boot).
+ */
+export interface Product {
+    /** Stable identifier — used in URLs, audit entries, /api/products/{id}. */
+    id: string;
+    /** Display name shown in the UI / agent dropdown. */
+    name: string;
+    /** One-sentence description. */
+    description?: string;
+    /** Allowed MCP tool names. Empty / undefined → all tools allowed. */
+    tools?: string[];
+    /** Operator-defined version label, e.g. "1.0.0" or "preview". */
+    version?: string;
+    /** Free-form branding metadata for the UI — icon URL, theme colour, etc. */
+    branding?: {
+        iconUrl?: string;
+        color?: string;
+    };
+    /** Lifecycle stage: published = visible to agents; staging = admin-only. */
+    status?: "published" | "staging";
+    /** Tenant this product belongs to. Omitted → "default". */
+    tenant?: string;
+}
+export interface ProductsFile {
+    products: Product[];
+}
+export declare class ProductsLoadError extends Error {
+    constructor(msg: string);
+}
+export declare function readProductsFile(path: string | undefined): Promise<ProductsFile>;
+export declare function parseProductsText(text: string, origin: string): ProductsFile;
+/** In-memory store with tenant- and status-aware queries. */
+export declare class ProductsStore {
+    private file;
+    constructor(file?: ProductsFile);
+    /** Return the product list. When `tenant` is set, filters to that
+     *  tenant (entries without a tenant field treated as "default").
+     *  When `includeStaging` is false (default), staging products are
+     *  hidden from the result — admins should pass true. */
+    list(opts?: {
+        tenant?: string;
+        includeStaging?: boolean;
+    }): Product[];
+    /** Lookup by id. Cross-tenant gets return undefined when `tenant` set. */
+    get(id: string, tenant?: string): Product | undefined;
+    count(tenant?: string): number;
+    replace(file: ProductsFile): void;
+    /** Upsert (replace if id exists, else append). Returns the new
+     *  ProductsFile so the caller can persist it. */
+    upsert(product: Product): ProductsFile;
+    /** Remove by id. Returns true when the product existed, false
+     *  otherwise. Caller persists the resulting file. */
+    delete(id: string): {
+        removed: boolean;
+        file: ProductsFile;
+    };
+    /** Snapshot of the current file (for tests / persistence). */
+    snapshot(): ProductsFile;
+}
+/** Validate a single product entry by routing it through the same
+ *  parser as the file format. Throws ProductsLoadError on any
+ *  shape problem. Used by PUT /api/products/:id so a typo / wrong
+ *  type / unknown key gets the same loud rejection a malformed
+ *  file would. */
+export declare function validateProduct(input: unknown, origin?: string): Product;
+/** Atomic write of the products file. Same tmp+rename pattern as
+ *  the audit-chain + token-budget snapshot, so a crash mid-write
+ *  leaves the previous file intact. */
+export declare function writeProductsFile(path: string, file: ProductsFile): Promise<void>;

package/dist/products/loader.js

@@ -0,0 +1,216 @@
+/**
+ * MCP Products — curated, agent-facing collections of tools.
+ *
+ * A Product is a named bundle that ships with branding metadata
+ * (icon, description, version) plus a list of allowed MCP tools.
+ * The agent calling /mcp can be told which Product it belongs to
+ * (via a future header / arg, slice 2+), and the server can filter
+ * tools/list and tools/call responses accordingly.
+ *
+ * Today's surface (slice 1):
+ *   - In-memory ProductsStore loaded from OMCP_PRODUCTS_FILE
+ *     (YAML or JSON). Missing/empty file → empty catalog.
+ *   - Strict validation: unknown action / unknown resource /
+ *     unexpected keys reject loudly.
+ *   - Hot-reload on next /api/products call (slice 2 wires the
+ *     reload trigger; for now the file is read once at boot).
+ */
+import { readFile, writeFile, rename } from "node:fs/promises";
+import yaml from "js-yaml";
+const EMPTY = { products: [] };
+const VALID_STATUS = new Set(["published", "staging"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export class ProductsLoadError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "ProductsLoadError";
+    }
+}
+export async function readProductsFile(path) {
+    if (!path)
+        return EMPTY;
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return EMPTY;
+        console.warn(`[products] could not read ${path}: ${e.message} — starting with empty catalog`);
+        return EMPTY;
+    }
+    return parseProductsText(text, path);
+}
+export function parseProductsText(text, origin) {
+    let parsed;
+    try {
+        parsed = yaml.load(text);
+    }
+    catch (e) {
+        throw new ProductsLoadError(`${origin}: not valid YAML/JSON: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ProductsLoadError(`${origin}: root must be an object with a 'products' array`);
+    }
+    const root = parsed;
+    const rawProducts = root.products;
+    if (!Array.isArray(rawProducts)) {
+        throw new ProductsLoadError(`${origin}: 'products' must be an array`);
+    }
+    const out = [];
+    const seenIds = new Set();
+    for (let i = 0; i < rawProducts.length; i++) {
+        const e = rawProducts[i];
+        if (!e || typeof e !== "object" || Array.isArray(e)) {
+            throw new ProductsLoadError(`${origin}: products[${i}] must be an object`);
+        }
+        const r = e;
+        if (typeof r.id !== "string" || !ID_RE.test(r.id)) {
+            throw new ProductsLoadError(`${origin}: products[${i}].id must be a string matching ${ID_RE}`);
+        }
+        if (seenIds.has(r.id)) {
+            throw new ProductsLoadError(`${origin}: duplicate product id '${r.id}'`);
+        }
+        seenIds.add(r.id);
+        if (typeof r.name !== "string" || !r.name) {
+            throw new ProductsLoadError(`${origin}: products[${i}].name must be a non-empty string`);
+        }
+        const p = { id: r.id, name: r.name };
+        if (r.description !== undefined) {
+            if (typeof r.description !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].description must be a string`);
+            p.description = r.description;
+        }
+        if (r.tools !== undefined) {
+            if (!Array.isArray(r.tools) || !r.tools.every((t) => typeof t === "string")) {
+                throw new ProductsLoadError(`${origin}: products[${i}].tools must be an array of strings`);
+            }
+            p.tools = r.tools;
+        }
+        if (r.version !== undefined) {
+            if (typeof r.version !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].version must be a string`);
+            p.version = r.version;
+        }
+        if (r.status !== undefined) {
+            if (typeof r.status !== "string" || !VALID_STATUS.has(r.status)) {
+                throw new ProductsLoadError(`${origin}: products[${i}].status must be one of ${[...VALID_STATUS].join(", ")}`);
+            }
+            p.status = r.status;
+        }
+        if (r.tenant !== undefined) {
+            if (typeof r.tenant !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].tenant must be a string`);
+            p.tenant = r.tenant;
+        }
+        if (r.branding !== undefined) {
+            if (!r.branding || typeof r.branding !== "object" || Array.isArray(r.branding)) {
+                throw new ProductsLoadError(`${origin}: products[${i}].branding must be an object`);
+            }
+            const b = r.branding;
+            p.branding = {};
+            if (b.iconUrl !== undefined) {
+                if (typeof b.iconUrl !== "string")
+                    throw new ProductsLoadError(`${origin}: products[${i}].branding.iconUrl must be a string`);
+                p.branding.iconUrl = b.iconUrl;
+            }
+            if (b.color !== undefined) {
+                if (typeof b.color !== "string")
+                    throw new ProductsLoadError(`${origin}: products[${i}].branding.color must be a string`);
+                p.branding.color = b.color;
+            }
+        }
+        // Reject unexpected top-level keys — operator typo guard
+        for (const k of Object.keys(r)) {
+            if (!["id", "name", "description", "tools", "version", "branding", "status", "tenant"].includes(k)) {
+                throw new ProductsLoadError(`${origin}: products[${i}] has unexpected key '${k}'`);
+            }
+        }
+        out.push(p);
+    }
+    return { products: out };
+}
+/** In-memory store with tenant- and status-aware queries. */
+export class ProductsStore {
+    file;
+    constructor(file = EMPTY) {
+        this.file = file;
+    }
+    /** Return the product list. When `tenant` is set, filters to that
+     *  tenant (entries without a tenant field treated as "default").
+     *  When `includeStaging` is false (default), staging products are
+     *  hidden from the result — admins should pass true. */
+    list(opts = {}) {
+        return this.file.products.filter((p) => {
+            if (opts.tenant) {
+                const pt = p.tenant || "default";
+                if (pt !== opts.tenant)
+                    return false;
+            }
+            if (!opts.includeStaging && p.status === "staging")
+                return false;
+            return true;
+        });
+    }
+    /** Lookup by id. Cross-tenant gets return undefined when `tenant` set. */
+    get(id, tenant) {
+        const p = this.file.products.find((x) => x.id === id);
+        if (!p)
+            return undefined;
+        if (tenant && (p.tenant || "default") !== tenant)
+            return undefined;
+        return p;
+    }
+    count(tenant) {
+        return this.list({ tenant, includeStaging: true }).length;
+    }
+    replace(file) {
+        this.file = file;
+    }
+    /** Upsert (replace if id exists, else append). Returns the new
+     *  ProductsFile so the caller can persist it. */
+    upsert(product) {
+        const i = this.file.products.findIndex((p) => p.id === product.id);
+        const next = this.file.products.slice();
+        if (i >= 0)
+            next[i] = product;
+        else
+            next.push(product);
+        this.file = { products: next };
+        return this.file;
+    }
+    /** Remove by id. Returns true when the product existed, false
+     *  otherwise. Caller persists the resulting file. */
+    delete(id) {
+        const i = this.file.products.findIndex((p) => p.id === id);
+        if (i < 0)
+            return { removed: false, file: this.file };
+        const next = this.file.products.slice();
+        next.splice(i, 1);
+        this.file = { products: next };
+        return { removed: true, file: this.file };
+    }
+    /** Snapshot of the current file (for tests / persistence). */
+    snapshot() {
+        return { products: this.file.products.slice() };
+    }
+}
+/** Validate a single product entry by routing it through the same
+ *  parser as the file format. Throws ProductsLoadError on any
+ *  shape problem. Used by PUT /api/products/:id so a typo / wrong
+ *  type / unknown key gets the same loud rejection a malformed
+ *  file would. */
+export function validateProduct(input, origin = "input") {
+    const wrapped = parseProductsText(yaml.dump({ products: [input] }), origin);
+    return wrapped.products[0];
+}
+/** Atomic write of the products file. Same tmp+rename pattern as
+ *  the audit-chain + token-budget snapshot, so a crash mid-write
+ *  leaves the previous file intact. */
+export async function writeProductsFile(path, file) {
+    const text = yaml.dump(file, { sortKeys: false, lineWidth: 100 });
+    const tmp = path + ".tmp";
+    await writeFile(tmp, text, "utf8");
+    await rename(tmp, path);
+}

package/dist/products/loader.test.d.ts

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