@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/quota/charge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure helper that turns a TokenBudget decision into either the
+ * original tool result (when allowed / uncapped) or a structured
+ * error payload distinguishing the two budget-denial cases:
+ *
+ *   - OMCP_TOKEN_BUDGET_EXCEEDED         — cumulative trailing-24h
+ *     usage would push the principal past its cap. Waiting helps;
+ *     `retryAfterSeconds` says how long until enough buckets drop
+ *     off to fit the request.
+ *
+ *   - OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET  — this single response is
+ *     larger than the entire daily cap. Waiting does NOT help — the
+ *     agent must narrow the query or the operator must raise the
+ *     cap. `retryAfterSeconds` is 0 here so retry-with-backoff loops
+ *     terminate instead of churning.
+ *
+ * Extracted from the createMcpServer closure in index.ts purely for
+ * unit-testability. Behaviour is identical to the previous inline
+ * version.
+ */
+import type { CheckResult } from "./token-budget.js";
+export interface ToolResult {
+    content: Array<{
+        text: string;
+        [k: string]: unknown;
+    }>;
+}
+export declare function applyBudgetDecision<T extends ToolResult>(result: T, decision: CheckResult, tokens: number, toolName: string): T;

package/dist/quota/charge.js

@@ -0,0 +1,30 @@
+export function applyBudgetDecision(result, decision, tokens, toolName) {
+    if (decision.allowed || decision.limit === 0)
+        return result;
+    // A request larger than the entire daily cap can never succeed by
+    // waiting — distinct error code so the agent doesn't spin.
+    const requestExceedsCap = tokens > decision.limit;
+    const errBody = {
+        error: requestExceedsCap ? "OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET" : "OMCP_TOKEN_BUDGET_EXCEEDED",
+        tool: toolName,
+        used: decision.used,
+        limit: decision.limit,
+        requested: tokens,
+        retryAfterSeconds: requestExceedsCap ? 0 : decision.retryAfterSeconds,
+        freedAtRetry: decision.freedAtRetry,
+        message: requestExceedsCap
+            ? `This single response (~${tokens} tokens) is larger than the entire daily budget (${decision.limit}). Retrying won't help — narrow the query (smaller window / lower limit / more selective filter) or raise OMCP_TOOL_DAILY_TOKENS.`
+            : `Daily token budget exceeded (${decision.used}/${decision.limit} tokens used in the trailing 24h; this call would have added ~${tokens}). Try again in ~${Math.ceil(decision.retryAfterSeconds / 3600)}h or raise OMCP_TOOL_DAILY_TOKENS.`,
+    };
+    // Preserve any additional content entries (e.g. a future tool
+    // returning [text, image]) — only the text payload of the first
+    // entry is replaced with the error JSON; everything after passes
+    // through unchanged.
+    return {
+        ...result,
+        content: [
+            { ...result.content[0], text: JSON.stringify(errBody) },
+            ...result.content.slice(1),
+        ],
+    };
+}

package/dist/quota/charge.test.d.ts

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

package/dist/quota/charge.test.js

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyBudgetDecision } from "./charge.js";
+function decision(over) {
+    return {
+        allowed: false,
+        used: 0,
+        limit: 1000,
+        retryAfterSeconds: 3600,
+        freedAtRetry: 100,
+        ...over,
+    };
+}
+const sampleResult = () => ({ content: [{ text: "original tool output" }] });
+test("applyBudgetDecision — passes the result through when allowed", () => {
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ allowed: true }), 50, "query_logs");
+    assert.equal(out, r, "exact passthrough when allowed");
+});
+test("applyBudgetDecision — passes through when uncapped (limit === 0)", () => {
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ allowed: false, limit: 0 }), 50_000, "query_logs");
+    assert.equal(out.content[0].text, "original tool output");
+});
+test("applyBudgetDecision — cumulative exceed emits OMCP_TOKEN_BUDGET_EXCEEDED", () => {
+    // Tokens fit a single request (<= limit) but cumulative pushes over.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 950, limit: 1000, retryAfterSeconds: 7200, freedAtRetry: 200 }), 100, "query_logs");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+    assert.equal(body.tool, "query_logs");
+    assert.equal(body.used, 950);
+    assert.equal(body.limit, 1000);
+    assert.equal(body.requested, 100);
+    assert.equal(body.retryAfterSeconds, 7200);
+    assert.equal(body.freedAtRetry, 200);
+    assert.match(body.message, /Daily token budget exceeded/);
+    assert.match(body.message, /Try again in ~2h/);
+});
+test("applyBudgetDecision — single request > limit emits the DISTINCT OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET", () => {
+    // The whole point of the distinct code: an agent that sees this
+    // must NOT retry — waiting can never fit a request larger than the
+    // entire daily cap. retryAfterSeconds is forced to 0 so naive
+    // backoff loops terminate.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 0, limit: 1000, retryAfterSeconds: 3600, freedAtRetry: 0 }), 5000, // request > limit
+    "query_metrics");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET");
+    assert.equal(body.tool, "query_metrics");
+    assert.equal(body.requested, 5000);
+    assert.equal(body.limit, 1000);
+    assert.equal(body.retryAfterSeconds, 0, "retry-loop killer: 0 instead of inherited 3600");
+    assert.match(body.message, /larger than the entire daily budget/);
+    assert.match(body.message, /Retrying won't help/);
+});
+test("applyBudgetDecision — boundary: request == limit is NOT the request-exceeds-cap code", () => {
+    // A request exactly equal to the cap can theoretically succeed on
+    // an empty bucket — it's the cumulative-exceeded path, not the
+    // unconditional-deny path.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 100, limit: 1000 }), 1000, "query_logs");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+});
+test("applyBudgetDecision — preserves additional content entries past the first", () => {
+    const r = {
+        content: [
+            { text: "first", extraField: 42 },
+            { text: "second" },
+            { text: "third" },
+        ],
+    };
+    const out = applyBudgetDecision(r, decision({}), 10, "t");
+    assert.equal(out.content.length, 3);
+    // First entry's text replaced; its other fields (extraField) preserved.
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+    assert.equal(out.content[0].extraField, 42);
+    // Trailing entries pass through verbatim.
+    assert.equal(out.content[1].text, "second");
+    assert.equal(out.content[2].text, "third");
+});

package/dist/quota/limiter.d.ts

@@ -25,19 +25,40 @@
  * - unset / empty / non-numeric → DEFAULT_LIMIT_PER_MIN (60)
  * - `"0"` → DEFAULT_LIMIT_PER_MIN (limit=0 would deny every request,
  *   which is almost never what an operator setting "0" wants — they
- *   either mean "default" or "disable"; we treat it as "default" and
- *   leave the explicit disable path on the roadmap)
+ *   either mean "default" or "disable"; this function maps it to the
+ *   default so they aren't accidentally locked out, and the explicit
+ *   disable path is one of the UNLIMITED_TOKENS instead)
+ * - `"off"` / `"none"` / `"unlimited"` / `"disabled"` / `"false"`
+ *   (case-insensitive) → Number.POSITIVE_INFINITY, which the
+ *   `count >= limit` comparison in check() always allows. JSON
+ *   serialisation renders Infinity as `null`; consumers can treat
+ *   a null limit as "uncapped".
  * - negative → DEFAULT_LIMIT_PER_MIN (limit=-1 with the current
  *   `count >= limit` check would also deny every request)
  * - any positive integer ≥ 1 → that value
  */
 export declare function resolveToolRatePerMin(raw: string | undefined): number;
 export interface LimiterConfig {
-    /** Cap per identity per window. Defaults to 60. */
+    /** Default cap per identity per window. Defaults to 60. */
     limit?: number;
     /** Window length in milliseconds. Defaults to 60_000. */
     windowMs?: number;
+    /** Optional per-identity override. Returns the cap for the named
+     *  identity, or undefined to fall back to the default `limit`.
+     *  Useful for the OMCP_KEY_RATE_PER_MIN credential-level override
+     *  (`agent=600;ci=240`) — admin gives a noisy automation a higher
+     *  quota without affecting every other caller. Returning Infinity
+     *  disables the cap for that identity (matches the global
+     *  unlimited-token contract). */
+    limitFor?: (identity: string) => number | undefined;
 }
+/** Parse OMCP_KEY_RATE_PER_MIN — `name=count;name2=count2`. Same
+ *  shape as parseKeyTenants / parseKeyProducts so operators have one
+ *  syntactic model across all per-credential overrides. Unknown
+ *  counts (non-numeric / ≤ 0) silently skip. Magic disable tokens
+ *  (off/none/unlimited/disabled/false) map to Infinity, same as the
+ *  global OMCP_TOOL_RATE_PER_MIN. */
+export declare function parseKeyRateLimits(raw: string | undefined): Map<string, number>;
 export interface CheckResult {
     /** True when the call is allowed (and the timestamp recorded). */
     allowed: boolean;
@@ -52,10 +73,14 @@ export interface CheckResult {
     retryAfterSeconds: number;
 }
 export declare class IdentityRateLimiter {
-    private readonly limit;
+    private readonly defaultLimit;
     private readonly windowMs;
+    private readonly limitFor?;
     private readonly buckets;
     constructor(cfg?: LimiterConfig);
+    /** Resolved cap for one identity: the per-identity override wins
+     *  when defined; otherwise the process-wide default applies. */
+    private resolveLimit;
     /** Record-and-test a call for the given identity. Returns the
      * decision plus enough context to render a 429 with Retry-After. */
     check(identity: string, now?: number): CheckResult;

package/dist/quota/limiter.js

@@ -18,6 +18,11 @@
  */
 const DEFAULT_LIMIT_PER_MIN = 60;
 const DEFAULT_WINDOW_MS = 60_000;
+/** Magic strings that explicitly disable the per-identity cap.
+ *  Matched case-insensitively. Operators picked any of these to
+ *  mean "no rate limit at all" — useful when the caps are enforced
+ *  upstream (envoy / API-gateway) and OMCP shouldn't double-count. */
+const UNLIMITED_TOKENS = new Set(["off", "none", "unlimited", "disabled", "false"]);
 /** Resolve `OMCP_TOOL_RATE_PER_MIN` (or any equivalent caller-supplied
  * string) into the per-identity cap used by the limiter and reported
  * by `/api/info` + `/api/usage`. Single source of truth, so the three
@@ -27,8 +32,14 @@ const DEFAULT_WINDOW_MS = 60_000;
  * - unset / empty / non-numeric → DEFAULT_LIMIT_PER_MIN (60)
  * - `"0"` → DEFAULT_LIMIT_PER_MIN (limit=0 would deny every request,
  *   which is almost never what an operator setting "0" wants — they
- *   either mean "default" or "disable"; we treat it as "default" and
- *   leave the explicit disable path on the roadmap)
+ *   either mean "default" or "disable"; this function maps it to the
+ *   default so they aren't accidentally locked out, and the explicit
+ *   disable path is one of the UNLIMITED_TOKENS instead)
+ * - `"off"` / `"none"` / `"unlimited"` / `"disabled"` / `"false"`
+ *   (case-insensitive) → Number.POSITIVE_INFINITY, which the
+ *   `count >= limit` comparison in check() always allows. JSON
+ *   serialisation renders Infinity as `null`; consumers can treat
+ *   a null limit as "uncapped".
  * - negative → DEFAULT_LIMIT_PER_MIN (limit=-1 with the current
  *   `count >= limit` check would also deny every request)
  * - any positive integer ≥ 1 → that value
@@ -36,19 +47,63 @@ const DEFAULT_WINDOW_MS = 60_000;
 export function resolveToolRatePerMin(raw) {
     if (raw === undefined || raw === "")
         return DEFAULT_LIMIT_PER_MIN;
+    if (UNLIMITED_TOKENS.has(raw.trim().toLowerCase()))
+        return Number.POSITIVE_INFINITY;
     const n = Number(raw);
     if (!Number.isFinite(n) || n < 1)
         return DEFAULT_LIMIT_PER_MIN;
     return Math.floor(n);
 }
+/** Parse OMCP_KEY_RATE_PER_MIN — `name=count;name2=count2`. Same
+ *  shape as parseKeyTenants / parseKeyProducts so operators have one
+ *  syntactic model across all per-credential overrides. Unknown
+ *  counts (non-numeric / ≤ 0) silently skip. Magic disable tokens
+ *  (off/none/unlimited/disabled/false) map to Infinity, same as the
+ *  global OMCP_TOOL_RATE_PER_MIN. */
+export function parseKeyRateLimits(raw) {
+    const m = new Map();
+    if (!raw)
+        return m;
+    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 valueRaw = entry.slice(eq + 1).trim();
+        if (!name || !valueRaw)
+            continue;
+        if (UNLIMITED_TOKENS.has(valueRaw.toLowerCase())) {
+            m.set(name, Number.POSITIVE_INFINITY);
+            continue;
+        }
+        const n = Number(valueRaw);
+        if (!Number.isFinite(n) || n < 1)
+            continue;
+        m.set(name, Math.floor(n));
+    }
+    return m;
+}
 export class IdentityRateLimiter {
-    limit;
+    defaultLimit;
     windowMs;
+    limitFor;
     // identity → ring of millisecond timestamps, newest at the end.
     buckets = new Map();
     constructor(cfg = {}) {
-        this.limit = cfg.limit ?? DEFAULT_LIMIT_PER_MIN;
+        this.defaultLimit = cfg.limit ?? DEFAULT_LIMIT_PER_MIN;
         this.windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+        this.limitFor = cfg.limitFor;
+    }
+    /** Resolved cap for one identity: the per-identity override wins
+     *  when defined; otherwise the process-wide default applies. */
+    resolveLimit(identity) {
+        if (this.limitFor) {
+            const v = this.limitFor(identity);
+            if (typeof v === "number" && (Number.isFinite(v) ? v >= 1 : v === Number.POSITIVE_INFINITY)) {
+                return v;
+            }
+        }
+        return this.defaultLimit;
     }
     /** Record-and-test a call for the given identity. Returns the
      * decision plus enough context to render a 429 with Retry-After. */
@@ -60,7 +115,8 @@ export class IdentityRateLimiter {
         while (i < bucket.length && bucket[i] <= cutoff)
             i++;
         const fresh = i === 0 ? bucket : bucket.slice(i);
-        if (fresh.length >= this.limit) {
+        const limit = this.resolveLimit(identity);
+        if (fresh.length >= limit) {
             // Compute when the oldest in-window record drops off.
             const retryAfterMs = fresh[0] + this.windowMs - now;
             // Don't store the call we just denied — that would push the
@@ -69,7 +125,7 @@ export class IdentityRateLimiter {
             return {
                 allowed: false,
                 count: fresh.length,
-                limit: this.limit,
+                limit,
                 windowMs: this.windowMs,
                 retryAfterSeconds: Math.max(1, Math.ceil(retryAfterMs / 1000)),
             };
@@ -79,7 +135,7 @@ export class IdentityRateLimiter {
         return {
             allowed: true,
             count: fresh.length,
-            limit: this.limit,
+            limit,
             windowMs: this.windowMs,
             retryAfterSeconds: 0,
         };
@@ -92,7 +148,7 @@ export class IdentityRateLimiter {
         for (const t of bucket)
             if (t > cutoff)
                 count++;
-        return { count, limit: this.limit, windowMs: this.windowMs };
+        return { count, limit: this.resolveLimit(identity), windowMs: this.windowMs };
     }
     /** All identities we've ever seen — for /api/usage aggregation. */
     knownIdentities() {

package/dist/quota/limiter.test.js

@@ -117,3 +117,89 @@ test("default limit applies when constructed with no args", () => {
     }
     assert.equal(lim.check("alice", t + 60).allowed, false);
 });
+test("resolveToolRatePerMin — explicit-disable tokens map to Infinity (any case, with whitespace)", () => {
+    for (const tok of ["off", "OFF", "Off", "none", "NONE", "unlimited", "UNLIMITED", "disabled", "false", "  off  "]) {
+        assert.equal(resolveToolRatePerMin(tok), Number.POSITIVE_INFINITY, `'${tok}' should disable the limiter`);
+    }
+});
+test("IdentityRateLimiter — limit=Infinity always allows (the explicit-disable contract)", () => {
+    const lim = new IdentityRateLimiter({ limit: Number.POSITIVE_INFINITY });
+    const t = 1_700_000_000_000;
+    // Burst far past the default cap; every call must allow.
+    for (let i = 0; i < 1000; i++) {
+        const r = lim.check("alice", t + i);
+        assert.equal(r.allowed, true);
+        assert.equal(r.retryAfterSeconds, 0);
+        // Limit reflects the configured Infinity — JSON serialisation
+        // would render this as null; callers can branch on Number.isFinite.
+        assert.equal(r.limit, Number.POSITIVE_INFINITY);
+    }
+});
+test("resolveToolRatePerMin — disable tokens are NOT a number trap (\"infinity\" alone is not a token)", () => {
+    // We deliberately do NOT accept the literal string "infinity"
+    // because Number("Infinity") === Infinity — operators expect
+    // OMCP_TOOL_RATE_PER_MIN=Infinity to error out, not silently
+    // mean "unlimited". The explicit tokens are off/none/unlimited/
+    // disabled/false. (Number.isFinite is what the resolver checks.)
+    assert.equal(resolveToolRatePerMin("Infinity"), 60, "literal 'Infinity' must NOT secretly enable unlimited mode");
+});
+import { parseKeyRateLimits } from "./limiter.js";
+test("parseKeyRateLimits — parses name=count pairs, skips malformed entries", () => {
+    const m = parseKeyRateLimits("agent=600;ci=240;bad;empty=;negative=-1;zero=0;notnum=abc");
+    assert.equal(m.get("agent"), 600);
+    assert.equal(m.get("ci"), 240);
+    assert.equal(m.get("bad"), undefined);
+    assert.equal(m.get("empty"), undefined);
+    assert.equal(m.get("negative"), undefined);
+    assert.equal(m.get("zero"), undefined);
+    assert.equal(m.get("notnum"), undefined);
+});
+test("parseKeyRateLimits — disable tokens map to Infinity (same vocabulary as the global override)", () => {
+    const m = parseKeyRateLimits("agent=off;ci=unlimited;loud=DISABLED");
+    assert.equal(m.get("agent"), Number.POSITIVE_INFINITY);
+    assert.equal(m.get("ci"), Number.POSITIVE_INFINITY);
+    assert.equal(m.get("loud"), Number.POSITIVE_INFINITY);
+});
+test("IdentityRateLimiter — limitFor override wins over the default cap", () => {
+    // Default is 60; override gives agent=2.
+    const lim = new IdentityRateLimiter({
+        limit: 60,
+        limitFor: (id) => (id === "default agent" ? 2 : undefined),
+    });
+    const t = 1_700_000_000_000;
+    // Two calls allowed for agent, third denies.
+    assert.equal(lim.check("default agent", t).allowed, true);
+    assert.equal(lim.check("default agent", t + 1).allowed, true);
+    const denied = lim.check("default agent", t + 2);
+    assert.equal(denied.allowed, false);
+    assert.equal(denied.limit, 2, "reported limit must be the per-identity override, not the default");
+    // Default identity still gets the global 60.
+    for (let i = 0; i < 60; i++) {
+        assert.equal(lim.check("default other", t + i).allowed, true);
+    }
+    assert.equal(lim.check("default other", t + 60).allowed, false);
+});
+test("IdentityRateLimiter — limitFor returning undefined falls back to default; Infinity disables for that identity", () => {
+    const lim = new IdentityRateLimiter({
+        limit: 5,
+        limitFor: (id) => (id === "default vip" ? Number.POSITIVE_INFINITY : undefined),
+    });
+    const t = 1_700_000_000_000;
+    // VIP can burst far past 5.
+    for (let i = 0; i < 1000; i++) {
+        assert.equal(lim.check("default vip", t + i).allowed, true);
+    }
+    // Default user still capped at 5.
+    for (let i = 0; i < 5; i++) {
+        assert.equal(lim.check("default user", t + i).allowed, true);
+    }
+    assert.equal(lim.check("default user", t + 5).allowed, false);
+});
+test("IdentityRateLimiter — inspect() reports the per-identity limit too (not just the default)", () => {
+    const lim = new IdentityRateLimiter({
+        limit: 60,
+        limitFor: (id) => (id === "default agent" ? 600 : undefined),
+    });
+    assert.equal(lim.inspect("default agent").limit, 600);
+    assert.equal(lim.inspect("default other").limit, 60);
+});

package/dist/scim/compliance.test.d.ts

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

package/dist/scim/compliance.test.js

@@ -0,0 +1,169 @@
+// SCIM 2.0 (RFC 7643 / 7644) compliance harness.
+//
+// Run against a running gateway with SCIM enabled by setting:
+//   OMCP_SCIM_COMPLIANCE_URL  — the SCIM base, e.g.
+//                               http://localhost:3000/scim/v2
+//   OMCP_SCIM_COMPLIANCE_TOKEN — the bearer matching OMCP_SCIM_TOKEN
+//
+// When the URL is unset every test skips — so the file lives happily
+// in a plain `find src -name "*.test.ts"` unit run without needing a
+// server. The `make scim-compliance` target boots the demo with SCIM
+// configured, waits for /healthz, then runs this file.
+//
+//   OMCP_SCIM_COMPLIANCE_URL=http://localhost:3000/scim/v2 \
+//   OMCP_SCIM_COMPLIANCE_TOKEN=secret \
+//   npx tsx --test src/scim/compliance.test.ts
+//
+// The suite is self-contained: it creates resources, exercises them,
+// and deletes them, leaving the store as it found it.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+const BASE = process.env.OMCP_SCIM_COMPLIANCE_URL?.replace(/\/+$/, "");
+const TOKEN = process.env.OMCP_SCIM_COMPLIANCE_TOKEN || "";
+const skip = !BASE;
+const opts = skip ? { skip: "OMCP_SCIM_COMPLIANCE_URL not set" } : {};
+const SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+const SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+const SCHEMA_PATCH = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+const SCHEMA_LIST = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+const SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+async function scim(method, path, body, withAuth = true) {
+    if (!BASE)
+        throw new Error("OMCP_SCIM_COMPLIANCE_URL not set");
+    const headers = { "content-type": "application/scim+json" };
+    if (withAuth)
+        headers["authorization"] = `Bearer ${TOKEN}`;
+    const res = await fetch(`${BASE}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const h = {};
+    res.headers.forEach((v, k) => { h[k] = v; });
+    const text = await res.text();
+    let json = {};
+    if (text.trim().startsWith("{"))
+        json = JSON.parse(text);
+    return { status: res.status, json, headers: h };
+}
+// Resources created during the run, deleted in the final test.
+const created = { users: [], groups: [] };
+function uniq(p) { return `${p}-${Math.floor(performance.now() * 1000)}-${created.users.length + created.groups.length}`; }
+// --- Discovery (RFC 7643 §5) -----------------------------------------
+test("ServiceProviderConfig advertises the spec schema + patch support", opts, async () => {
+    const r = await scim("GET", "/ServiceProviderConfig");
+    assert.equal(r.status, 200);
+    assert.ok(r.json.schemas.includes("urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"));
+    assert.ok(r.json.patch, "patch capability block present");
+});
+test("ResourceTypes lists User + Group endpoints", opts, async () => {
+    const r = await scim("GET", "/ResourceTypes");
+    assert.equal(r.status, 200);
+    const txt = JSON.stringify(r.json);
+    assert.ok(txt.includes("/Users") && txt.includes("/Groups"));
+});
+test("Schemas endpoint returns the core schema definitions", opts, async () => {
+    const r = await scim("GET", "/Schemas");
+    assert.equal(r.status, 200);
+    const txt = JSON.stringify(r.json);
+    assert.ok(txt.includes(SCHEMA_USER) && txt.includes(SCHEMA_GROUP));
+});
+// --- Auth (RFC 7644 §2) ----------------------------------------------
+test("requests without a bearer token are rejected 401", opts, async () => {
+    const r = await scim("GET", "/Users", undefined, false);
+    assert.equal(r.status, 401);
+    assert.ok(r.json.schemas?.includes(SCHEMA_ERROR));
+});
+// --- User lifecycle (RFC 7644 §3.3–3.6) ------------------------------
+let userId = "";
+const userName = uniq("compliance-user") + "@example.com";
+test("POST /Users creates a user → 201 with id + meta", opts, async () => {
+    const r = await scim("POST", "/Users", {
+        schemas: [SCHEMA_USER],
+        userName,
+        name: { givenName: "Comp", familyName: "Liance" },
+        emails: [{ value: userName, primary: true }],
+        active: true,
+    });
+    assert.equal(r.status, 201);
+    assert.equal(typeof r.json.id, "string");
+    assert.equal(r.json.userName, userName);
+    const meta = r.json.meta;
+    assert.equal(meta.resourceType, "User");
+    assert.ok(meta.created && meta.lastModified);
+    userId = r.json.id;
+    created.users.push(userId);
+});
+test("duplicate userName is rejected 409 uniqueness", opts, async () => {
+    const r = await scim("POST", "/Users", { schemas: [SCHEMA_USER], userName });
+    assert.equal(r.status, 409);
+    assert.equal(r.json.scimType, "uniqueness");
+});
+test("GET /Users/:id returns the created user", opts, async () => {
+    const r = await scim("GET", `/Users/${userId}`);
+    assert.equal(r.status, 200);
+    assert.equal(r.json.id, userId);
+    assert.equal(r.json.userName, userName);
+});
+test("GET /Users returns a ListResponse envelope", opts, async () => {
+    const r = await scim("GET", "/Users");
+    assert.equal(r.status, 200);
+    assert.ok(r.json.schemas.includes(SCHEMA_LIST));
+    assert.equal(typeof r.json.totalResults, "number");
+    assert.ok(Array.isArray(r.json.Resources));
+});
+test("PATCH /Users/:id replace toggles active", opts, async () => {
+    const r = await scim("PATCH", `/Users/${userId}`, {
+        schemas: [SCHEMA_PATCH],
+        Operations: [{ op: "replace", path: "active", value: false }],
+    });
+    assert.equal(r.status, 200);
+    assert.equal(r.json.active, false);
+});
+test("unknown user id → 404 with SCIM error schema", opts, async () => {
+    const r = await scim("GET", "/Users/does-not-exist");
+    assert.equal(r.status, 404);
+    assert.ok(r.json.schemas.includes(SCHEMA_ERROR));
+});
+// --- Group lifecycle + membership PATCH (Q14) ------------------------
+let groupId = "";
+test("POST /Groups creates a group", opts, async () => {
+    const r = await scim("POST", "/Groups", { schemas: [SCHEMA_GROUP], displayName: uniq("compliance-grp") });
+    assert.equal(r.status, 201);
+    groupId = r.json.id;
+    created.groups.push(groupId);
+    assert.equal(r.json.meta.resourceType, "Group");
+});
+test("PATCH /Groups/:id add member → membership reflected", opts, async () => {
+    const r = await scim("PATCH", `/Groups/${groupId}`, {
+        schemas: [SCHEMA_PATCH],
+        Operations: [{ op: "add", path: "members", value: [{ value: userId, display: userName }] }],
+    });
+    assert.equal(r.status, 200);
+    const members = r.json.members || [];
+    assert.ok(members.some((m) => m.value === userId), "added member present");
+});
+test("PATCH /Groups/:id remove member by filter → membership cleared", opts, async () => {
+    const r = await scim("PATCH", `/Groups/${groupId}`, {
+        schemas: [SCHEMA_PATCH],
+        Operations: [{ op: "remove", path: `members[value eq "${userId}"]` }],
+    });
+    assert.equal(r.status, 200);
+    const members = r.json.members || [];
+    assert.ok(!members.some((m) => m.value === userId), "removed member gone");
+});
+// --- Cleanup (DELETE → 204, then 404) --------------------------------
+test("DELETE created resources → 204 and subsequent GET → 404", opts, async () => {
+    for (const id of created.groups) {
+        const del = await scim("DELETE", `/Groups/${id}`);
+        assert.ok(del.status === 204 || del.status === 200, `group delete status ${del.status}`);
+        const get = await scim("GET", `/Groups/${id}`);
+        assert.equal(get.status, 404);
+    }
+    for (const id of created.users) {
+        const del = await scim("DELETE", `/Users/${id}`);
+        assert.ok(del.status === 204 || del.status === 200, `user delete status ${del.status}`);
+        const get = await scim("GET", `/Users/${id}`);
+        assert.equal(get.status, 404);
+    }
+});

package/dist/scim/factory.test.d.ts

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

package/dist/scim/factory.test.js

@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createScimStore, ScimStore } from "./store.js";
+import { RedisScimStore } from "./redis-store.js";
+function tmpStorePath() {
+    return join(mkdtempSync(join(tmpdir(), "omcp-scim-factory-")), "scim.json");
+}
+test("createScimStore default = file backend", async () => {
+    const path = tmpStorePath();
+    delete process.env.OMCP_SCIM_BACKEND;
+    const store = await createScimStore({ path });
+    assert.ok(store instanceof ScimStore);
+    // The store is usable
+    const u = await store.createUser({ userName: "a@x" });
+    assert.equal(u.userName, "a@x");
+});
+test("createScimStore explicit backend=file", async () => {
+    const store = await createScimStore({ backend: "file", path: tmpStorePath() });
+    assert.ok(store instanceof ScimStore);
+});
+test("createScimStore backend=redis requires a client", async () => {
+    await assert.rejects(createScimStore({ backend: "redis" }), /backend=redis requires a redis client/);
+});
+test("createScimStore backend=redis returns RedisScimStore", async () => {
+    const fake = {
+        _s: new Map(),
+        async get(k) { return this._s.has(k) ? this._s.get(k) : null; },
+        async set(k, v) { this._s.set(k, v); return "OK"; },
+    };
+    const store = await createScimStore({ backend: "redis", redis: fake });
+    assert.ok(store instanceof RedisScimStore);
+    const u = await store.createUser({ userName: "u@x" });
+    assert.equal(u.userName, "u@x");
+    // Persisted to the fake redis
+    assert.ok(fake._s.has("omcp:scim:snapshot"));
+});
+test("createScimStore reads OMCP_SCIM_BACKEND env when no explicit backend", async () => {
+    process.env.OMCP_SCIM_BACKEND = "redis";
+    try {
+        const fake = {
+            _s: new Map(),
+            async get(k) { return this._s.get(k) ?? null; },
+            async set(k, v) { this._s.set(k, v); return "OK"; },
+        };
+        const store = await createScimStore({ redis: fake });
+        assert.ok(store instanceof RedisScimStore);
+    }
+    finally {
+        delete process.env.OMCP_SCIM_BACKEND;
+    }
+});

package/dist/scim/group-role-map.d.ts

@@ -0,0 +1,4 @@
+export declare function parseScimGroupRoleMap(raw: string | undefined): Map<string, string>;
+/** Map a user's group-display-names to the gateway's RBAC roles.
+ *  Unknown groups are silently dropped (least-privilege). */
+export declare function rolesForGroups(groupDisplayNames: string[], map: Map<string, string>): string[];