@thotischner/observability-mcp 1.8.1 → 3.0.0

package/dist/scim/store.js

@@ -0,0 +1,178 @@
+// SCIM store — file-backed JSON for users + groups.
+//
+// F21a uses an on-disk JSON file (atomic tmp+rename, mode 0600).
+// Multi-replica deployments should plug the F8 SessionStore in here
+// — that's F21b. The interface intentionally mirrors what the
+// SessionStore exposes so the swap is purely additive.
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { nowIso, SCIM_SCHEMA_GROUP, SCIM_SCHEMA_USER } from "./types.js";
+const EMPTY = { users: [], groups: [] };
+export class ScimStore {
+    path;
+    snapshot = EMPTY;
+    bootstrapped = null;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        if (this.bootstrapped)
+            return this.bootstrapped;
+        this.bootstrapped = (async () => {
+            try {
+                const raw = await readFile(this.path, "utf8");
+                const parsed = JSON.parse(raw);
+                this.snapshot = {
+                    users: Array.isArray(parsed.users) ? parsed.users : [],
+                    groups: Array.isArray(parsed.groups) ? parsed.groups : [],
+                };
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    this.snapshot = { users: [], groups: [] };
+                    return;
+                }
+                console.warn(`[scim] failed to load ${this.path}: ${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;
+        // Also remove the user from every group's members list.
+        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;
+    }
+    /** Look up the groups a user is currently a member of — used to
+     *  populate `User.groups` on read responses. */
+    groupsContaining(userId) {
+        return this.snapshot.groups
+            .filter((g) => (g.members ?? []).some((m) => m.value === userId))
+            .map((g) => ({ value: g.id, display: g.displayName }));
+    }
+    async persist() {
+        await mkdir(dirname(this.path), { recursive: true }).catch(() => undefined);
+        const tmp = `${this.path}.tmp`;
+        await writeFile(tmp, JSON.stringify(this.snapshot, null, 2), { mode: 0o600 });
+        await rename(tmp, this.path);
+    }
+}
+export class ScimValidationError extends Error {
+    scimType;
+    constructor(message, scimType) {
+        super(message);
+        this.scimType = scimType;
+        this.name = "ScimValidationError";
+    }
+}
+export class ScimNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScimNotFoundError";
+    }
+}

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

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

package/dist/scim/store.test.js

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, statSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ScimStore, ScimValidationError, ScimNotFoundError } from "./store.js";
+function tmpStore() {
+    return join(mkdtempSync(join(tmpdir(), "scim-")), "scim.json");
+}
+test("ScimStore: load() on missing file → empty snapshot", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    assert.deepEqual(s.listUsers(), []);
+    assert.deepEqual(s.listGroups(), []);
+});
+test("ScimStore: createUser issues UUID id, sets schemas/meta, active=true default", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    assert.match(u.id, /^[0-9a-f-]{36}$/);
+    assert.deepEqual(u.schemas, ["urn:ietf:params:scim:schemas:core:2.0:User"]);
+    assert.equal(u.userName, "alice@example.com");
+    assert.equal(u.active, true);
+    assert.equal(u.meta.resourceType, "User");
+});
+test("ScimStore: createUser rejects duplicate userName with uniqueness scimType", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await s.createUser({ userName: "alice@example.com" });
+    await assert.rejects(() => s.createUser({ userName: "alice@example.com" }), (e) => e instanceof ScimValidationError && e.scimType === "uniqueness");
+});
+test("ScimStore: createUser rejects missing userName", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await assert.rejects(() => s.createUser({}), ScimValidationError);
+});
+test("ScimStore: getUser / getUserByUserName lookups", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    assert.equal(s.getUser(u.id)?.id, u.id);
+    assert.equal(s.getUserByUserName("alice@example.com")?.id, u.id);
+    assert.equal(s.getUser("nope"), undefined);
+});
+test("ScimStore: updateUser merges patch + bumps lastModified", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const created = u.meta.lastModified;
+    await new Promise((r) => setTimeout(r, 5));
+    const updated = await s.updateUser(u.id, { displayName: "Alice" });
+    assert.equal(updated.displayName, "Alice");
+    assert.equal(updated.userName, "alice@example.com");
+    assert.notEqual(updated.meta.lastModified, created);
+});
+test("ScimStore: updateUser on missing id throws NotFound", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    await assert.rejects(() => s.updateUser("nope", { displayName: "x" }), ScimNotFoundError);
+});
+test("ScimStore: deleteUser removes user + scrubs them from group members", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const g = await s.createGroup({
+        displayName: "admins",
+        members: [{ value: u.id, display: "Alice" }],
+    });
+    assert.equal(await s.deleteUser(u.id), true);
+    assert.equal(s.getUser(u.id), undefined);
+    const refreshed = s.getGroup(g.id);
+    assert.deepEqual(refreshed?.members, []);
+});
+test("ScimStore: deleteUser missing → false", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    assert.equal(await s.deleteUser("nope"), false);
+});
+test("ScimStore: createGroup with displayName + member list", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    const g = await s.createGroup({
+        displayName: "admins",
+        members: [{ value: u.id, display: "Alice" }],
+    });
+    assert.equal(g.displayName, "admins");
+    assert.equal(g.members?.length, 1);
+});
+test("ScimStore: groupsContaining(userId) returns the groups a user is in", async () => {
+    const s = new ScimStore(tmpStore());
+    await s.load();
+    const u = await s.createUser({ userName: "alice@example.com" });
+    await s.createGroup({ displayName: "admins", members: [{ value: u.id }] });
+    await s.createGroup({ displayName: "viewers", members: [{ value: u.id }] });
+    await s.createGroup({ displayName: "irrelevant", members: [] });
+    const got = s.groupsContaining(u.id);
+    assert.equal(got.length, 2);
+    assert.deepEqual(got.map((g) => g.display).sort(), ["admins", "viewers"]);
+});
+test("ScimStore: persists to disk with mode 0o600 (atomic tmp+rename)", async () => {
+    const path = tmpStore();
+    const s = new ScimStore(path);
+    await s.load();
+    await s.createUser({ userName: "alice@example.com" });
+    assert.ok(existsSync(path));
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600, `mode 0${mode.toString(8)} != 0600`);
+});
+test("ScimStore: round-trip through disk (load after persist sees the entries)", async () => {
+    const path = tmpStore();
+    const a = new ScimStore(path);
+    await a.load();
+    await a.createUser({ userName: "alice@example.com" });
+    await a.createGroup({ displayName: "admins", members: [{ value: a.listUsers()[0].id }] });
+    const b = new ScimStore(path);
+    await b.load();
+    assert.equal(b.listUsers().length, 1);
+    assert.equal(b.listGroups().length, 1);
+    assert.equal(b.listUsers()[0].userName, "alice@example.com");
+});

package/dist/scim/types.d.ts

@@ -0,0 +1,73 @@
+export declare const SCIM_SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+export declare const SCIM_SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+export declare const SCIM_SCHEMA_PATCH_OP = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export declare const SCIM_SCHEMA_LIST_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export declare const SCIM_SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+export interface ScimMeta {
+    resourceType: "User" | "Group";
+    created: string;
+    lastModified: string;
+    location?: string;
+    version?: string;
+}
+export interface ScimUser {
+    schemas: string[];
+    id: string;
+    userName: string;
+    active?: boolean;
+    displayName?: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+        formatted?: string;
+    };
+    emails?: Array<{
+        value: string;
+        primary?: boolean;
+        type?: string;
+    }>;
+    /** SCIM `groups` is read-only — populated server-side from the
+     *  group→members linkage. */
+    groups?: Array<{
+        value: string;
+        display?: string;
+    }>;
+    externalId?: string;
+    meta: ScimMeta;
+}
+export interface ScimGroup {
+    schemas: string[];
+    id: string;
+    displayName: string;
+    members?: Array<{
+        value: string;
+        display?: string;
+        type?: "User" | "Group";
+    }>;
+    externalId?: string;
+    meta: ScimMeta;
+}
+export interface ScimListResponse<T> {
+    schemas: string[];
+    totalResults: number;
+    Resources: T[];
+    startIndex?: number;
+    itemsPerPage?: number;
+}
+export interface ScimError {
+    schemas: string[];
+    status: string;
+    scimType?: string;
+    detail?: string;
+}
+export interface ScimPatchOperation {
+    op: "add" | "remove" | "replace";
+    path?: string;
+    value?: unknown;
+}
+export interface ScimPatchRequest {
+    schemas: string[];
+    Operations: ScimPatchOperation[];
+}
+export declare function scimError(status: number, detail: string, scimType?: string): ScimError;
+export declare function nowIso(): string;

package/dist/scim/types.js

@@ -0,0 +1,29 @@
+// SCIM 2.0 — minimal shared types.
+//
+// The gateway implements the subset of SCIM 2.0 that the most-common
+// IdPs (Entra ID, Okta) use to provision Users and Groups. We do NOT
+// aim for full RFC 7643 / 7644 compliance — only the methods the
+// provisioning checklists exercise:
+//
+//   Users:   GET (list+by-id), POST, PATCH, DELETE
+//   Groups:  GET (list+by-id), POST, PATCH, DELETE
+//   Discovery: ServiceProviderConfig, ResourceTypes, Schemas
+//
+// Other operations (PUT/replace, Bulk, search-via-POST) are deferred
+// until an IdP customer explicitly requires them.
+export const SCIM_SCHEMA_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
+export const SCIM_SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
+export const SCIM_SCHEMA_PATCH_OP = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export const SCIM_SCHEMA_LIST_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export const SCIM_SCHEMA_ERROR = "urn:ietf:params:scim:api:messages:2.0:Error";
+export function scimError(status, detail, scimType) {
+    return {
+        schemas: [SCIM_SCHEMA_ERROR],
+        status: String(status),
+        scimType,
+        detail,
+    };
+}
+export function nowIso() {
+    return new Date().toISOString();
+}

package/dist/sdk/hooks.d.ts

@@ -0,0 +1,77 @@
+/** Stable identifier for each hook point. Mirrors the canonical set
+ *  the rest of the MCP ecosystem expects to see; extending this is
+ *  a breaking change for the plugin contract. */
+export type HookKind = "tool_pre_invoke" | "tool_post_invoke" | "resource_pre_fetch" | "resource_post_fetch" | "prompt_pre_fetch" | "prompt_post_fetch";
+/** Hook-time context. Mirrors the RequestContext the gateway already
+ *  carries but is intentionally a flat shape so plugins don't take a
+ *  dependency on server internals. */
+export interface HookContext {
+    /** Principal sub identifier (anonymous, OIDC sub, or local user). */
+    principal: string;
+    /** Tenant the principal is acting under. Always set; "default"
+     *  when no tenancy is configured. */
+    tenant: string;
+    /** Hook fan-out kind. */
+    kind: HookKind;
+    /** Per-call metadata. Currently: tool name (for tool_*), resource
+     *  URI (for resource_*), prompt name (for prompt_*). */
+    target: string;
+    /** Free-form labels — used by audit + by the hook itself to
+     *  cooperate with siblings (e.g. correlation ids). */
+    labels?: Record<string, string>;
+}
+/** Hook-time payload. The exact shape depends on the hook kind:
+ *  - tool_pre_invoke: { args: unknown }
+ *  - tool_post_invoke: { args: unknown, result: unknown }
+ *  - resource_pre_fetch: { uri: string }
+ *  - resource_post_fetch: { uri: string, contents: unknown }
+ *  - prompt_pre_fetch: { name: string, arguments: unknown }
+ *  - prompt_post_fetch: { name: string, arguments: unknown, messages: unknown }
+ *
+ *  Plugins may mutate the payload — the gateway forwards the mutated
+ *  value to the next hook, then to the underlying handler / caller. */
+export type HookPayload = Record<string, unknown>;
+/** Hook result. `allow=false` short-circuits the dispatch with
+ *  `reason` surfaced to the caller. `payload` (when present) replaces
+ *  the current payload — used for redaction / transformation /
+ *  enrichment. */
+export interface HookResult {
+    allow: boolean;
+    payload?: HookPayload;
+    reason?: string;
+}
+/** A single hook registration. The plugin manifest carries one of
+ *  these per hook entry; the loader instantiates the function from
+ *  the plugin's source. */
+export interface HookRegistration {
+    pluginName: string;
+    kind: HookKind;
+    /** Lower number runs earlier. Default 100 (mid-range). */
+    priority?: number;
+    /** enforce: blocking errors short-circuit. permissive: errors are
+     *  logged and the chain continues with the prior payload.
+     *  disabled: hook is loaded but not invoked (emergency disable). */
+    mode?: "enforce" | "permissive" | "disabled";
+    handler: (ctx: HookContext, payload: HookPayload) => Promise<HookResult> | HookResult;
+}
+/** Mutable, in-process registry. Plugin loaders push entries here;
+ *  the dispatcher reads `fire()` per call.
+ *
+ *  Hot-swap-safe: a re-registration with the same (pluginName, kind)
+ *  replaces the prior entry — used by /api/connectors/install for
+ *  zero-downtime hook updates. */
+export declare class HookRegistry {
+    private entries;
+    /** Register or replace a hook entry. Returns the resolved registration. */
+    register(entry: HookRegistration): HookRegistration;
+    /** Remove all entries owned by a plugin (e.g. on uninstall). */
+    unregisterPlugin(pluginName: string): number;
+    /** All entries for a hook kind in priority order. */
+    list(kind: HookKind): HookRegistration[];
+    /** Snapshot of every registration regardless of kind (for diagnostics). */
+    all(): HookRegistration[];
+    /** Fire every hook of the given kind in priority order. Each hook
+     *  receives the (possibly mutated) payload from the previous one.
+     *  Short-circuits on first `allow:false`. */
+    fire(kind: HookKind, ctx: HookContext, initialPayload: HookPayload, logger?: (level: "warn" | "info", msg: string) => void): Promise<HookResult>;
+}

package/dist/sdk/hooks.js

@@ -0,0 +1,72 @@
+// Plugin lifecycle hooks — interpose on every tool / resource /
+// prompt invocation the gateway dispatches. Plugins declare hooks in
+// their manifest; the HookRegistry resolves them on load and the
+// dispatcher fires them around each call.
+//
+// Hooks land here as part of Phase F7 so Phase F9 (virtual servers)
+// and Phase F10 (federation) can interpose without duplicating
+// dispatch logic.
+/** Mutable, in-process registry. Plugin loaders push entries here;
+ *  the dispatcher reads `fire()` per call.
+ *
+ *  Hot-swap-safe: a re-registration with the same (pluginName, kind)
+ *  replaces the prior entry — used by /api/connectors/install for
+ *  zero-downtime hook updates. */
+export class HookRegistry {
+    entries = [];
+    /** Register or replace a hook entry. Returns the resolved registration. */
+    register(entry) {
+        this.entries = this.entries.filter((e) => !(e.pluginName === entry.pluginName && e.kind === entry.kind));
+        this.entries.push({
+            ...entry,
+            priority: entry.priority ?? 100,
+            mode: entry.mode ?? "enforce",
+        });
+        return entry;
+    }
+    /** Remove all entries owned by a plugin (e.g. on uninstall). */
+    unregisterPlugin(pluginName) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.pluginName !== pluginName);
+        return before - this.entries.length;
+    }
+    /** All entries for a hook kind in priority order. */
+    list(kind) {
+        return this.entries
+            .filter((e) => e.kind === kind && e.mode !== "disabled")
+            .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    }
+    /** Snapshot of every registration regardless of kind (for diagnostics). */
+    all() {
+        return [...this.entries];
+    }
+    /** Fire every hook of the given kind in priority order. Each hook
+     *  receives the (possibly mutated) payload from the previous one.
+     *  Short-circuits on first `allow:false`. */
+    async fire(kind, ctx, initialPayload, logger = (l, m) => console[l === "warn" ? "warn" : "log"](m)) {
+        let payload = initialPayload;
+        for (const entry of this.list(kind)) {
+            try {
+                const r = await entry.handler({ ...ctx, kind }, payload);
+                if (!r.allow) {
+                    return r;
+                }
+                if (r.payload)
+                    payload = r.payload;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (entry.mode === "permissive") {
+                    logger("warn", `hook ${entry.pluginName}/${kind} threw (permissive): ${msg}`);
+                    continue;
+                }
+                // enforce: block the call.
+                return {
+                    allow: false,
+                    reason: `hook ${entry.pluginName}/${kind} failed: ${msg}`,
+                };
+            }
+        }
+        return { allow: true, payload };
+    }
+}

package/dist/sdk/hooks.test.d.ts

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