@thotischner/observability-mcp 3.0.0 → 3.1.0

package/dist/scim/patch-ops.test.js

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyPatchOps } from "./routes.js";
+function group(members = []) {
+    return {
+        schemas: ["urn:ietf:params:scim:schemas:core:2.0:Group"],
+        id: "g1",
+        displayName: "team",
+        members,
+        meta: { resourceType: "Group", created: "2026-06-06T00:00:00Z", lastModified: "2026-06-06T00:00:00Z" },
+    };
+}
+function patch(...ops) {
+    return { schemas: ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], Operations: ops };
+}
+// --- replace (existing behaviour preserved) --------------------------
+test("replace with no path merges allow-listed keys", () => {
+    const out = applyPatchOps(group(), patch({ op: "replace", value: { displayName: "renamed", externalId: "x" } }));
+    assert.equal(out.displayName, "renamed");
+    assert.equal(out.externalId, "x");
+});
+test("replace with path sets that attribute", () => {
+    const out = applyPatchOps(group(), patch({ op: "replace", path: "displayName", value: "n2" }));
+    assert.equal(out.displayName, "n2");
+});
+test("replace drops non-allowlisted keys (proto-pollution guard)", () => {
+    const out = applyPatchOps(group(), patch({ op: "replace", value: { __proto__: { polluted: true }, constructor: 1, displayName: "ok" } }));
+    assert.equal(out.displayName, "ok");
+    assert.equal({}.polluted, undefined);
+    assert.equal(Object.prototype.hasOwnProperty.call(out, "__proto__"), false);
+    assert.equal(Object.prototype.hasOwnProperty.call(out, "constructor"), false);
+});
+// --- add members -----------------------------------------------------
+test("add appends a member to an empty group", () => {
+    const out = applyPatchOps(group(), patch({ op: "add", path: "members", value: [{ value: "u1", display: "Alice" }] }));
+    assert.deepEqual(out.members, [{ value: "u1", display: "Alice" }]);
+});
+test("add appends to existing members and dedups by value", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "add", path: "members", value: [{ value: "u1" }, { value: "u2" }] }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u1", "u2"]);
+});
+test("add accepts a single (non-array) value", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "add", path: "members", value: { value: "u2" } }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u1", "u2"]);
+});
+test("pathless add appends array attrs + sets scalars", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "add", value: { members: [{ value: "u2" }], displayName: "renamed" } }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u1", "u2"]);
+    assert.equal(out.displayName, "renamed");
+});
+// --- remove members --------------------------------------------------
+test("remove with a filter drops the matching member", () => {
+    const out = applyPatchOps(group([{ value: "u1" }, { value: "u2" }, { value: "u3" }]), patch({ op: "remove", path: 'members[value eq "u2"]' }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u1", "u3"]);
+});
+test("remove with a non-matching filter is a no-op on contents", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "remove", path: 'members[value eq "ghost"]' }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u1"]);
+});
+test("remove of the whole members attr clears it", () => {
+    const out = applyPatchOps(group([{ value: "u1" }, { value: "u2" }]), patch({ op: "remove", path: "members" }));
+    assert.deepEqual(out.members, []);
+});
+// --- chained ops in one request (Entra-style) ------------------------
+test("add then remove in one request compose against the working value", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "add", path: "members", value: [{ value: "u2" }, { value: "u3" }] }, { op: "remove", path: 'members[value eq "u1"]' }));
+    assert.deepEqual(out.members.map((m) => m.value), ["u2", "u3"]);
+});
+// --- security: filtered paths can't pollute --------------------------
+test("crafted __proto__ filter path is rejected (fail-closed no-op), no pollution", () => {
+    const out = applyPatchOps(group([{ value: "u1" }]), patch({ op: "remove", path: 'members[__proto__ eq "x"]' }));
+    // The sub-attribute regex requires a leading letter, so this path
+    // doesn't parse as a filter and isn't a bare allow-listed attr —
+    // the op is skipped entirely. No members key is emitted (no change)
+    // and nothing is polluted.
+    assert.equal(Object.prototype.hasOwnProperty.call(out, "members"), false);
+    assert.equal({}.x, undefined);
+});
+test("add to a non-allowlisted path is ignored", () => {
+    const out = applyPatchOps(group(), patch({ op: "add", path: "__proto__", value: { polluted: true } }));
+    assert.equal(Object.keys(out).length, 0);
+    assert.equal({}.polluted, undefined);
+});
+// --- emails array (same machinery) -----------------------------------
+test("add + remove works on emails too", () => {
+    const user = {
+        schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"],
+        id: "u1",
+        userName: "a@x",
+        emails: [{ value: "a@x", primary: true }],
+        meta: { resourceType: "User", created: "2026-06-06T00:00:00Z", lastModified: "2026-06-06T00:00:00Z" },
+    };
+    const added = applyPatchOps(user, patch({ op: "add", path: "emails", value: [{ value: "a2@x" }] }));
+    assert.deepEqual(added.emails.map((e) => e.value), ["a@x", "a2@x"]);
+    const removed = applyPatchOps(user, patch({ op: "remove", path: 'emails[value eq "a@x"]' }));
+    assert.deepEqual(removed.emails.map((e) => e.value), []);
+});
+test("missing target resource throws", () => {
+    assert.throws(() => applyPatchOps(undefined, patch({ op: "add", path: "members", value: [] })), /not found/);
+});

package/dist/scim/redis-store.d.ts

@@ -0,0 +1,38 @@
+import { type ScimGroup, type ScimUser } from "./types.js";
+import { type IScimStore } from "./store.js";
+/**
+ * Minimal Redis surface we depend on. Matches both `ioredis` and the
+ * built-in promisified node-redis client — easier to swap clients
+ * and trivial to fake in unit tests.
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+}
+export declare class RedisScimStore implements IScimStore {
+    private readonly redis;
+    private readonly key;
+    private snapshot;
+    private bootstrapped;
+    private writeQueue;
+    constructor(redis: RedisLike, opts?: {
+        key?: 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>;
+    groupsContaining(userId: string): Array<{
+        value: string;
+        display?: string;
+    }>;
+    private persist;
+}

package/dist/scim/redis-store.js

@@ -0,0 +1,178 @@
+// Redis-backed SCIM store — same surface as the file-backed ScimStore,
+// persists the snapshot in a single Redis key.
+//
+// Multi-replica deployments need a shared store so that a Microsoft
+// Entra / Okta SCIM-push delivered to replica A is visible to replica
+// B's reads. The file store can't do that without a shared filesystem;
+// this one targets the same Redis the F8 SessionStore + the F8b
+// transport-map ride on (Q11 promotes the transport-map onto the same
+// interface).
+//
+// Concurrency note. SCIM clients (Entra, Okta, JumpCloud, generic
+// SCIM) deliver provisioning requests SERIALLY per resource — the
+// upstream IDP holds the connection open until the gateway responds.
+// A single load-balanced gateway in front of N replicas observes one
+// in-flight request per resource at a time, so last-writer-wins on
+// the single-key snapshot matches the source-of-truth semantics of
+// SCIM provisioning. We still serialise persists within a replica
+// via a small mutex so concurrent route handlers don't lose writes
+// to each other in the read-modify-write window.
+import { randomUUID } from "node:crypto";
+import { nowIso, SCIM_SCHEMA_GROUP, SCIM_SCHEMA_USER, } from "./types.js";
+import { ScimNotFoundError, ScimValidationError } from "./store.js";
+const DEFAULT_KEY = "omcp:scim:snapshot";
+export class RedisScimStore {
+    redis;
+    key;
+    snapshot = { users: [], groups: [] };
+    bootstrapped = null;
+    writeQueue = Promise.resolve();
+    constructor(redis, opts = {}) {
+        this.redis = redis;
+        this.key = opts.key || DEFAULT_KEY;
+    }
+    async load() {
+        if (this.bootstrapped)
+            return this.bootstrapped;
+        this.bootstrapped = (async () => {
+            try {
+                const raw = await this.redis.get(this.key);
+                if (!raw) {
+                    this.snapshot = { users: [], groups: [] };
+                    return;
+                }
+                const parsed = JSON.parse(raw);
+                this.snapshot = {
+                    users: Array.isArray(parsed.users) ? parsed.users : [],
+                    groups: Array.isArray(parsed.groups) ? parsed.groups : [],
+                };
+            }
+            catch (err) {
+                console.warn(`[scim] failed to load redis snapshot ${this.key}: ${err.message} — starting empty`);
+                this.snapshot = { users: [], groups: [] };
+            }
+        })();
+        return this.bootstrapped;
+    }
+    listUsers() {
+        return this.snapshot.users.slice();
+    }
+    getUser(id) {
+        return this.snapshot.users.find((u) => u.id === id);
+    }
+    getUserByUserName(userName) {
+        return this.snapshot.users.find((u) => u.userName === userName);
+    }
+    async createUser(input) {
+        if (!input.userName)
+            throw new ScimValidationError("userName is required");
+        if (this.getUserByUserName(input.userName)) {
+            throw new ScimValidationError(`User with userName '${input.userName}' already exists`, "uniqueness");
+        }
+        const ts = nowIso();
+        const user = {
+            schemas: [SCIM_SCHEMA_USER],
+            id: randomUUID(),
+            userName: input.userName,
+            active: input.active ?? true,
+            displayName: input.displayName,
+            name: input.name,
+            emails: input.emails,
+            externalId: input.externalId,
+            meta: { resourceType: "User", created: ts, lastModified: ts },
+        };
+        this.snapshot.users.push(user);
+        await this.persist();
+        return user;
+    }
+    async updateUser(id, patch) {
+        const i = this.snapshot.users.findIndex((u) => u.id === id);
+        if (i < 0)
+            throw new ScimNotFoundError(`User ${id} not found`);
+        const next = {
+            ...this.snapshot.users[i],
+            ...patch,
+            schemas: [SCIM_SCHEMA_USER],
+            id,
+            meta: {
+                ...this.snapshot.users[i].meta,
+                lastModified: nowIso(),
+            },
+        };
+        this.snapshot.users[i] = next;
+        await this.persist();
+        return next;
+    }
+    async deleteUser(id) {
+        const before = this.snapshot.users.length;
+        this.snapshot.users = this.snapshot.users.filter((u) => u.id !== id);
+        if (this.snapshot.users.length === before)
+            return false;
+        for (const g of this.snapshot.groups) {
+            g.members = (g.members ?? []).filter((m) => m.value !== id);
+        }
+        await this.persist();
+        return true;
+    }
+    listGroups() {
+        return this.snapshot.groups.slice();
+    }
+    getGroup(id) {
+        return this.snapshot.groups.find((g) => g.id === id);
+    }
+    async createGroup(input) {
+        if (!input.displayName)
+            throw new ScimValidationError("displayName is required");
+        const ts = nowIso();
+        const group = {
+            schemas: [SCIM_SCHEMA_GROUP],
+            id: randomUUID(),
+            displayName: input.displayName,
+            members: input.members ?? [],
+            externalId: input.externalId,
+            meta: { resourceType: "Group", created: ts, lastModified: ts },
+        };
+        this.snapshot.groups.push(group);
+        await this.persist();
+        return group;
+    }
+    async updateGroup(id, patch) {
+        const i = this.snapshot.groups.findIndex((g) => g.id === id);
+        if (i < 0)
+            throw new ScimNotFoundError(`Group ${id} not found`);
+        const next = {
+            ...this.snapshot.groups[i],
+            ...patch,
+            schemas: [SCIM_SCHEMA_GROUP],
+            id,
+            meta: {
+                ...this.snapshot.groups[i].meta,
+                lastModified: nowIso(),
+            },
+        };
+        this.snapshot.groups[i] = next;
+        await this.persist();
+        return next;
+    }
+    async deleteGroup(id) {
+        const before = this.snapshot.groups.length;
+        this.snapshot.groups = this.snapshot.groups.filter((g) => g.id !== id);
+        if (this.snapshot.groups.length === before)
+            return false;
+        await this.persist();
+        return true;
+    }
+    groupsContaining(userId) {
+        return this.snapshot.groups
+            .filter((g) => (g.members ?? []).some((m) => m.value === userId))
+            .map((g) => ({ value: g.id, display: g.displayName }));
+    }
+    persist() {
+        // Serialise persists so two concurrent updateUser calls don't
+        // race each other to the SET — the snapshot in memory is the
+        // canonical state, Redis just mirrors it.
+        const snap = { users: this.snapshot.users.slice(), groups: this.snapshot.groups.slice() };
+        this.writeQueue = this.writeQueue.then(() => this.redis.set(this.key, JSON.stringify(snap)).then(() => undefined));
+        return this.writeQueue;
+    }
+}

package/dist/scim/redis-store.test.d.ts

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

package/dist/scim/redis-store.test.js

@@ -0,0 +1,138 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { RedisScimStore } from "./redis-store.js";
+import { ScimNotFoundError, ScimValidationError } from "./store.js";
+/** In-memory fake of the RedisLike surface — single-key GET/SET. */
+function fakeRedis(initial) {
+    const store = new Map(Object.entries(initial || {}));
+    return {
+        _store: store,
+        _writeCount: 0,
+        async get(key) { return store.has(key) ? store.get(key) : null; },
+        async set(key, value) {
+            store.set(key, value);
+            this._writeCount += 1;
+            return "OK";
+        },
+    };
+}
+test("load() initialises empty when redis key is missing", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    assert.deepEqual(s.listUsers(), []);
+    assert.deepEqual(s.listGroups(), []);
+});
+test("load() hydrates from a serialised snapshot in redis", async () => {
+    const r = fakeRedis({
+        "omcp:scim:snapshot": JSON.stringify({
+            users: [{ id: "u1", userName: "alice@example.com", schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"], meta: { resourceType: "User" } }],
+            groups: [],
+        }),
+    });
+    const s = new RedisScimStore(r);
+    await s.load();
+    assert.equal(s.listUsers().length, 1);
+    assert.equal(s.listUsers()[0].userName, "alice@example.com");
+});
+test("createUser persists to redis", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const u = await s.createUser({ userName: "bob@example.com" });
+    assert.ok(u.id);
+    assert.equal(u.userName, "bob@example.com");
+    // Persisted snapshot round-trips through redis
+    const raw = JSON.parse(r._store.get("omcp:scim:snapshot"));
+    assert.equal(raw.users.length, 1);
+    assert.equal(raw.users[0].userName, "bob@example.com");
+});
+test("createUser enforces unique userName", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    await s.createUser({ userName: "alice@example.com" });
+    await assert.rejects(s.createUser({ userName: "alice@example.com" }), ScimValidationError);
+});
+test("createUser without userName throws", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    await assert.rejects(s.createUser({}), ScimValidationError);
+});
+test("updateUser preserves id + sets lastModified to a not-earlier ts", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const u = await s.createUser({ userName: "u@x" });
+    // 2ms gap so the ISO timestamp differs even on slow CI clocks
+    await new Promise((res) => setTimeout(res, 2));
+    const u2 = await s.updateUser(u.id, { displayName: "U" });
+    assert.equal(u2.id, u.id);
+    assert.equal(u2.displayName, "U");
+    assert.ok(u2.meta.lastModified >= u.meta.lastModified);
+});
+test("updateUser missing throws ScimNotFoundError", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    await assert.rejects(s.updateUser("nope", { displayName: "x" }), ScimNotFoundError);
+});
+test("deleteUser purges the user from all group member lists", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const u = await s.createUser({ userName: "u@x" });
+    const g = await s.createGroup({ displayName: "admins", members: [{ value: u.id, display: "u@x" }] });
+    await s.deleteUser(u.id);
+    const updated = s.getGroup(g.id);
+    assert.equal(updated?.members?.length, 0);
+});
+test("group CRUD round-trip persists", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const g = await s.createGroup({ displayName: "team-alpha" });
+    assert.equal(g.displayName, "team-alpha");
+    const g2 = await s.updateGroup(g.id, { displayName: "team-beta" });
+    assert.equal(g2.displayName, "team-beta");
+    assert.equal((await s.deleteGroup(g.id)), true);
+    assert.equal((await s.deleteGroup(g.id)), false);
+});
+test("groupsContaining returns membership", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const u = await s.createUser({ userName: "u@x" });
+    const g = await s.createGroup({ displayName: "admins", members: [{ value: u.id, display: "u@x" }] });
+    const groups = s.groupsContaining(u.id);
+    assert.equal(groups.length, 1);
+    assert.equal(groups[0].value, g.id);
+    assert.equal(groups[0].display, "admins");
+});
+test("custom key is honoured", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r, { key: "custom:key" });
+    await s.load();
+    await s.createUser({ userName: "u@x" });
+    assert.ok(r._store.has("custom:key"));
+    assert.equal(r._store.has("omcp:scim:snapshot"), false);
+});
+test("concurrent writes serialise — no lost-write race", async () => {
+    const r = fakeRedis();
+    const s = new RedisScimStore(r);
+    await s.load();
+    const u1 = s.createUser({ userName: "a@x" });
+    const u2 = s.createUser({ userName: "b@x" });
+    const u3 = s.createUser({ userName: "c@x" });
+    await Promise.all([u1, u2, u3]);
+    const final = JSON.parse(r._store.get("omcp:scim:snapshot"));
+    assert.equal(final.users.length, 3);
+});
+test("malformed snapshot in redis → starts empty (warning logged)", async () => {
+    const r = fakeRedis({ "omcp:scim:snapshot": "this is not json" });
+    const s = new RedisScimStore(r);
+    await s.load();
+    assert.deepEqual(s.listUsers(), []);
+    assert.deepEqual(s.listGroups(), []);
+});

package/dist/scim/routes.d.ts

@@ -1,7 +1,8 @@
 import type { Application } from "express";
-import { ScimStore } from "./store.js";
+import { type ScimPatchRequest } from "./types.js";
+import { type IScimStore } from "./store.js";
 export interface ScimRoutesDeps {
-    store: ScimStore;
+    store: IScimStore;
     bearerToken: string;
     /** Audit hook called after every successful mutation. Best-effort. */
     audit?: (event: {
@@ -13,3 +14,27 @@ export interface ScimRoutesDeps {
     }) => void;
 }
 export declare function registerScimRoutes(app: Application, deps: ScimRoutesDeps): void;
+/** Translate a SCIM PatchOp request into a partial resource patch.
+ *
+ *  Supported (RFC 7644 §3.5.2):
+ *   - replace, no path        → whole-resource merge of allow-listed keys
+ *   - replace, path=attr      → set that attribute
+ *   - add, no path            → merge; array attrs append (deduped), scalars set
+ *   - add, path=arrayAttr     → append value(s) to the array (deduped)
+ *   - add, path=scalarAttr    → set
+ *   - remove, path=arrayAttr  → clear the array
+ *   - remove, path=arrayAttr[sub eq "x"] → drop matching elements
+ *   - remove, path=scalarAttr → clear the attribute (set undefined)
+ *
+ *  Array ops are computed against the CURRENT resource value and the
+ *  full resulting array is returned in `out` (the store merges
+ *  shallowly, so out[attr] replaces current[attr] wholesale).
+ *
+ *  Every property name written into `out` is gated through
+ *  `PATCH_ALLOWED_ATTRS` so a SCIM client can't inject __proto__ /
+ *  constructor / arbitrary fields (CodeQL js/remote-property-injection +
+ *  js/prototype-polluting-assignment). Filter sub-attributes are
+ *  read-only. */
+export declare function applyPatchOps<T extends {
+    id: string;
+}>(current: T | undefined, patch: ScimPatchRequest): Partial<T>;