@thotischner/observability-mcp 1.8.1 → 3.0.0

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/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[];

package/dist/scim/group-role-map.js

@@ -0,0 +1,33 @@
+// Translate SCIM-provisioned groups into the gateway's RBAC roles.
+// Operators configure the mapping via OMCP_SCIM_GROUP_ROLE_MAP:
+//
+//   OMCP_SCIM_GROUP_ROLE_MAP="admins:admin,sre:operator,readers:viewer"
+//
+// A SCIM-managed user's groups[] (populated from group membership
+// in the ScimStore) translates to a set of RBAC roles via this map,
+// joining the OIDC group-mapping pattern from F6 so a federated
+// IdP rolling Users + Groups via SCIM ends up with the same RBAC
+// posture as a directly-claim-mapped login.
+export function parseScimGroupRoleMap(raw) {
+    const out = new Map();
+    if (!raw)
+        return out;
+    for (const pair of raw.split(",")) {
+        const [groupName, role] = pair.split(":").map((s) => s.trim());
+        if (!groupName || !role)
+            continue;
+        out.set(groupName.toLowerCase(), role);
+    }
+    return out;
+}
+/** Map a user's group-display-names to the gateway's RBAC roles.
+ *  Unknown groups are silently dropped (least-privilege). */
+export function rolesForGroups(groupDisplayNames, map) {
+    const out = new Set();
+    for (const g of groupDisplayNames) {
+        const role = map.get(g.toLowerCase());
+        if (role)
+            out.add(role);
+    }
+    return [...out];
+}

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

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

package/dist/scim/group-role-map.test.js

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseScimGroupRoleMap, rolesForGroups } from "./group-role-map.js";
+test("parseScimGroupRoleMap: empty / undefined → empty map", () => {
+    assert.equal(parseScimGroupRoleMap(undefined).size, 0);
+    assert.equal(parseScimGroupRoleMap("").size, 0);
+});
+test("parseScimGroupRoleMap: comma-separated key:role pairs, lowercased keys", () => {
+    const m = parseScimGroupRoleMap("Admins:admin,SRE:operator,Readers:viewer");
+    assert.equal(m.get("admins"), "admin");
+    assert.equal(m.get("sre"), "operator");
+    assert.equal(m.get("readers"), "viewer");
+});
+test("parseScimGroupRoleMap: malformed entries silently dropped", () => {
+    const m = parseScimGroupRoleMap("admins:admin,no-colon,:emptyKey,validKey:validRole");
+    assert.equal(m.get("admins"), "admin");
+    assert.equal(m.get("validkey"), "validRole");
+    assert.equal(m.size, 2);
+});
+test("rolesForGroups: unknown groups dropped (least-privilege)", () => {
+    const map = parseScimGroupRoleMap("admins:admin,sre:operator");
+    const roles = rolesForGroups(["admins", "unknown-group"], map);
+    assert.deepEqual(roles, ["admin"]);
+});
+test("rolesForGroups: dedupes roles", () => {
+    const map = parseScimGroupRoleMap("admins:admin,sysadmins:admin");
+    const roles = rolesForGroups(["admins", "sysadmins"], map);
+    assert.deepEqual(roles, ["admin"]);
+});
+test("rolesForGroups: case-insensitive group lookup", () => {
+    const map = parseScimGroupRoleMap("Admins:admin");
+    assert.deepEqual(rolesForGroups(["ADMINS"], map), ["admin"]);
+});

package/dist/scim/routes.d.ts

@@ -0,0 +1,15 @@
+import type { Application } from "express";
+import { ScimStore } from "./store.js";
+export interface ScimRoutesDeps {
+    store: ScimStore;
+    bearerToken: string;
+    /** Audit hook called after every successful mutation. Best-effort. */
+    audit?: (event: {
+        actor: string;
+        action: string;
+        target: string;
+        result: "ok" | "error";
+        status: number;
+    }) => void;
+}
+export declare function registerScimRoutes(app: Application, deps: ScimRoutesDeps): void;

package/dist/scim/routes.js

@@ -0,0 +1,249 @@
+// SCIM 2.0 routes — mounted at /scim/v2/.
+//
+// Spec subset covered:
+//   GET    /scim/v2/ServiceProviderConfig
+//   GET    /scim/v2/ResourceTypes
+//   GET    /scim/v2/Schemas
+//   GET    /scim/v2/Users        list (no filter support yet)
+//   GET    /scim/v2/Users/:id
+//   POST   /scim/v2/Users
+//   PATCH  /scim/v2/Users/:id    minimal: replace top-level attrs
+//   DELETE /scim/v2/Users/:id
+//   GET    /scim/v2/Groups
+//   GET    /scim/v2/Groups/:id
+//   POST   /scim/v2/Groups
+//   PATCH  /scim/v2/Groups/:id
+//   DELETE /scim/v2/Groups/:id
+//
+// Auth: Bearer token via OMCP_SCIM_TOKEN; absence of OMCP_SCIM_TOKEN
+// rejects every request (the routes are not safe without it).
+import { timingSafeEqual } from "node:crypto";
+import { SCIM_SCHEMA_LIST_RESPONSE, SCIM_SCHEMA_USER, SCIM_SCHEMA_GROUP, scimError, } from "./types.js";
+import { ScimNotFoundError, ScimValidationError } from "./store.js";
+const constantTimeBearerMatch = (raw, expected) => {
+    if (!raw)
+        return false;
+    const m = raw.match(/^Bearer\s+(.+)$/i);
+    if (!m)
+        return false;
+    const a = Buffer.from(m[1].trim());
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+};
+export function registerScimRoutes(app, deps) {
+    const { store, bearerToken, audit } = deps;
+    // Auth middleware — scoped to /scim/v2/* only.
+    app.use("/scim/v2", (req, res, next) => {
+        if (!bearerToken) {
+            res.status(503).json(scimError(503, "SCIM is enabled but OMCP_SCIM_TOKEN is unset"));
+            return;
+        }
+        if (!constantTimeBearerMatch(req.headers["authorization"], bearerToken)) {
+            res.status(401).json(scimError(401, "valid SCIM bearer token required"));
+            return;
+        }
+        next();
+    });
+    // ---- Discovery endpoints ----
+    app.get("/scim/v2/ServiceProviderConfig", (_req, res) => {
+        res.json({
+            schemas: ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
+            documentationUri: "https://thotischner.github.io/observability-mcp/scim-provisioning/",
+            patch: { supported: true },
+            bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
+            filter: { supported: false, maxResults: 200 },
+            changePassword: { supported: false },
+            sort: { supported: false },
+            etag: { supported: false },
+            authenticationSchemes: [
+                {
+                    name: "OAuth Bearer Token",
+                    description: "Authentication via OAuth 2.0 bearer token (configured per-deployment).",
+                    specUri: "https://datatracker.ietf.org/doc/html/rfc6750",
+                    documentationUri: "https://thotischner.github.io/observability-mcp/scim-provisioning/",
+                    type: "oauthbearertoken",
+                    primary: true,
+                },
+            ],
+        });
+    });
+    app.get("/scim/v2/ResourceTypes", (_req, res) => {
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: 2,
+            Resources: [
+                {
+                    schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+                    id: "User",
+                    name: "User",
+                    endpoint: "/Users",
+                    description: "User account",
+                    schema: SCIM_SCHEMA_USER,
+                },
+                {
+                    schemas: ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
+                    id: "Group",
+                    name: "Group",
+                    endpoint: "/Groups",
+                    description: "Group / role mapping",
+                    schema: SCIM_SCHEMA_GROUP,
+                },
+            ],
+        });
+    });
+    app.get("/scim/v2/Schemas", (_req, res) => {
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: 2,
+            Resources: [
+                { schemas: ["urn:ietf:params:scim:schemas:core:2.0:Schema"], id: SCIM_SCHEMA_USER, name: "User" },
+                { schemas: ["urn:ietf:params:scim:schemas:core:2.0:Schema"], id: SCIM_SCHEMA_GROUP, name: "Group" },
+            ],
+        });
+    });
+    // ---- Users ----
+    app.get("/scim/v2/Users", (_req, res) => {
+        const users = store.listUsers().map((u) => withGroups(u, store));
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: users.length,
+            itemsPerPage: users.length,
+            startIndex: 1,
+            Resources: users,
+        });
+    });
+    app.get("/scim/v2/Users/:id", (req, res) => {
+        const u = store.getUser(req.params.id);
+        if (!u) {
+            res.status(404).json(scimError(404, `User ${req.params.id} not found`));
+            return;
+        }
+        res.json(withGroups(u, store));
+    });
+    app.post("/scim/v2/Users", async (req, res) => {
+        try {
+            const u = await store.createUser((req.body ?? {}));
+            audit?.({ actor: "scim", action: "User.create", target: u.userName, result: "ok", status: 201 });
+            res.status(201).json(withGroups(u, store));
+        }
+        catch (e) {
+            handleStoreError(e, res, "User.create", audit);
+        }
+    });
+    app.patch("/scim/v2/Users/:id", async (req, res) => {
+        try {
+            const patch = applyPatchOps(store.getUser(req.params.id), req.body);
+            const u = await store.updateUser(req.params.id, patch);
+            audit?.({ actor: "scim", action: "User.update", target: u.userName, result: "ok", status: 200 });
+            res.json(withGroups(u, store));
+        }
+        catch (e) {
+            handleStoreError(e, res, "User.update", audit);
+        }
+    });
+    app.delete("/scim/v2/Users/:id", async (req, res) => {
+        const ok = await store.deleteUser(req.params.id);
+        audit?.({ actor: "scim", action: "User.delete", target: req.params.id, result: ok ? "ok" : "error", status: ok ? 204 : 404 });
+        if (!ok) {
+            res.status(404).json(scimError(404, `User ${req.params.id} not found`));
+            return;
+        }
+        res.status(204).end();
+    });
+    // ---- Groups ----
+    app.get("/scim/v2/Groups", (_req, res) => {
+        const groups = store.listGroups();
+        res.json({
+            schemas: [SCIM_SCHEMA_LIST_RESPONSE],
+            totalResults: groups.length,
+            itemsPerPage: groups.length,
+            startIndex: 1,
+            Resources: groups,
+        });
+    });
+    app.get("/scim/v2/Groups/:id", (req, res) => {
+        const g = store.getGroup(req.params.id);
+        if (!g) {
+            res.status(404).json(scimError(404, `Group ${req.params.id} not found`));
+            return;
+        }
+        res.json(g);
+    });
+    app.post("/scim/v2/Groups", async (req, res) => {
+        try {
+            const g = await store.createGroup((req.body ?? {}));
+            audit?.({ actor: "scim", action: "Group.create", target: g.displayName, result: "ok", status: 201 });
+            res.status(201).json(g);
+        }
+        catch (e) {
+            handleStoreError(e, res, "Group.create", audit);
+        }
+    });
+    app.patch("/scim/v2/Groups/:id", async (req, res) => {
+        try {
+            const patch = applyPatchOps(store.getGroup(req.params.id), req.body);
+            const g = await store.updateGroup(req.params.id, patch);
+            audit?.({ actor: "scim", action: "Group.update", target: g.displayName, result: "ok", status: 200 });
+            res.json(g);
+        }
+        catch (e) {
+            handleStoreError(e, res, "Group.update", audit);
+        }
+    });
+    app.delete("/scim/v2/Groups/:id", async (req, res) => {
+        const ok = await store.deleteGroup(req.params.id);
+        audit?.({ actor: "scim", action: "Group.delete", target: req.params.id, result: ok ? "ok" : "error", status: ok ? 204 : 404 });
+        if (!ok) {
+            res.status(404).json(scimError(404, `Group ${req.params.id} not found`));
+            return;
+        }
+        res.status(204).end();
+    });
+}
+function withGroups(u, store) {
+    return { ...u, groups: store.groupsContaining(u.id) };
+}
+/** Translate a SCIM PatchOp into a partial resource patch. Minimal:
+ *  we accept `op: "replace"` with no path (whole-resource merge) or
+ *  with a single-segment path naming a top-level attribute. `add` and
+ *  `remove` for members/emails arrays are a follow-up — the
+ *  Entra/Okta provisioning checklists exercise replace-only on the
+ *  attributes we expose. */
+function applyPatchOps(current, patch) {
+    if (!current)
+        throw new ScimNotFoundError("target resource not found");
+    if (!patch?.Operations || !Array.isArray(patch.Operations))
+        return {};
+    const out = {};
+    for (const op of patch.Operations) {
+        if (op.op !== "replace")
+            continue; // skip add/remove for F21a
+        if (!op.path) {
+            // value is a partial object — merge top-level keys
+            if (op.value && typeof op.value === "object") {
+                Object.assign(out, op.value);
+            }
+            continue;
+        }
+        out[op.path] = op.value;
+    }
+    return out;
+}
+function handleStoreError(e, res, action, audit) {
+    if (e instanceof ScimNotFoundError) {
+        audit?.({ actor: "scim", action, target: "?", result: "error", status: 404 });
+        res.status(404).json(scimError(404, e.message));
+        return;
+    }
+    if (e instanceof ScimValidationError) {
+        const status = e.scimType === "uniqueness" ? 409 : 400;
+        audit?.({ actor: "scim", action, target: "?", result: "error", status });
+        res.status(status).json(scimError(status, e.message, e.scimType));
+        return;
+    }
+    console.warn(`[scim] ${action} failed:`, e);
+    audit?.({ actor: "scim", action, target: "?", result: "error", status: 500 });
+    res.status(500).json(scimError(500, "internal error"));
+}

package/dist/scim/store.d.ts

@@ -0,0 +1,37 @@
+import { type ScimGroup, type ScimUser } from "./types.js";
+export interface ScimSnapshot {
+    users: ScimUser[];
+    groups: ScimGroup[];
+}
+export declare class ScimStore {
+    private readonly path;
+    private snapshot;
+    private bootstrapped;
+    constructor(path: string);
+    load(): Promise<void>;
+    listUsers(): ScimUser[];
+    getUser(id: string): ScimUser | undefined;
+    getUserByUserName(userName: string): ScimUser | undefined;
+    createUser(input: Partial<ScimUser>): Promise<ScimUser>;
+    updateUser(id: string, patch: Partial<ScimUser>): Promise<ScimUser>;
+    deleteUser(id: string): Promise<boolean>;
+    listGroups(): ScimGroup[];
+    getGroup(id: string): ScimGroup | undefined;
+    createGroup(input: Partial<ScimGroup>): Promise<ScimGroup>;
+    updateGroup(id: string, patch: Partial<ScimGroup>): Promise<ScimGroup>;
+    deleteGroup(id: string): Promise<boolean>;
+    /** Look up the groups a user is currently a member of — used to
+     *  populate `User.groups` on read responses. */
+    groupsContaining(userId: string): Array<{
+        value: string;
+        display?: string;
+    }>;
+    private persist;
+}
+export declare class ScimValidationError extends Error {
+    readonly scimType?: string | undefined;
+    constructor(message: string, scimType?: string | undefined);
+}
+export declare class ScimNotFoundError extends Error {
+    constructor(message: string);
+}