@thotischner/observability-mcp 1.8.1 → 3.0.1

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/hook-wrappers.d.ts

@@ -0,0 +1,39 @@
+import type { HookRegistry } from "./hooks.js";
+export interface HookCtxBase {
+    /** Principal sub identifier from the caller's RequestContext. */
+    principal: string;
+    /** Tenant the caller is acting under. */
+    tenant: string;
+    /** Tool / resource / prompt target identifier. */
+    target: string;
+}
+type ToolHandler = (args: unknown, extra: unknown) => Promise<unknown> | unknown;
+type ResourceHandler = (uri: URL | string, extra?: unknown) => Promise<unknown> | unknown;
+type PromptHandler = (args: unknown, extra?: unknown) => Promise<unknown> | unknown;
+/**
+ * Wrap a tool handler with `tool_pre_invoke` + `tool_post_invoke`
+ * hooks. Existing wire-up in index.ts is inlined; extracting it here
+ * for parity with the new resource + prompt wrappers and so tests
+ * can exercise the path without spinning up the full server.
+ */
+export declare function wrapToolHandler(registry: HookRegistry, ctx: HookCtxBase, handler: ToolHandler): ToolHandler;
+/**
+ * Wrap a resource readCallback with `resource_pre_fetch` +
+ * `resource_post_fetch` hooks.
+ *
+ * Pre-fetch sees `{uri}`; the payload's `uri` can be mutated (e.g. a
+ * canonicalising plugin) and the override flows into the original
+ * handler. Post-fetch sees `{uri, contents}`; the post-payload's
+ * `contents` (if set) replaces the response.
+ */
+export declare function wrapResourceHandler(registry: HookRegistry, ctx: HookCtxBase, handler: ResourceHandler): ResourceHandler;
+/**
+ * Wrap a prompt callback with `prompt_pre_fetch` + `prompt_post_fetch`
+ * hooks.
+ *
+ * Pre-fetch sees `{name, arguments}`; the override flows in. Post-fetch
+ * sees `{name, arguments, messages}`; the post-payload's `messages`
+ * (if set) replaces the response messages.
+ */
+export declare function wrapPromptHandler(registry: HookRegistry, ctx: HookCtxBase, handler: PromptHandler): PromptHandler;
+export {};

package/dist/sdk/hook-wrappers.js

@@ -0,0 +1,113 @@
+// Reusable hook-fire wrappers around the MCP SDK's tool / resource /
+// prompt callbacks.
+//
+// Each wrapper fires the matching `*_pre_*` hook before the original
+// handler runs and `*_post_*` after it returns. Hooks can:
+//   - deny the call (allow:false → caller sees a structured error)
+//   - mutate the payload before dispatch (args / uri / arguments)
+//   - mutate the result before it reaches the caller (contents /
+//     messages / tool result)
+//
+// When no hooks are registered (the default in the OSS demo) the
+// wrappers are thin pass-throughs.
+//
+// The wrappers are pure — they take the HookRegistry + a ctx object
+// and a handler, and return the wrapped handler. They never touch
+// the McpServer SDK directly, so they're trivially unit-testable.
+/** Shape an MCP tool dispatch returns on a hook denial. */
+function deniedToolResult(reason) {
+    return {
+        content: [{ type: "text", text: reason ?? "denied by plugin hook" }],
+        isError: true,
+    };
+}
+/** Shape an MCP resource read returns on a hook denial. */
+function deniedResourceResult(uri, reason) {
+    return {
+        contents: [
+            { uri, mimeType: "text/plain", text: reason ?? "denied by plugin hook" },
+        ],
+        isError: true,
+    };
+}
+/** Shape an MCP prompt fetch returns on a hook denial. */
+function deniedPromptResult(reason) {
+    return {
+        description: reason ?? "denied by plugin hook",
+        messages: [],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler with `tool_pre_invoke` + `tool_post_invoke`
+ * hooks. Existing wire-up in index.ts is inlined; extracting it here
+ * for parity with the new resource + prompt wrappers and so tests
+ * can exercise the path without spinning up the full server.
+ */
+export function wrapToolHandler(registry, ctx, handler) {
+    return async (args, extra) => {
+        const pre = await registry.fire("tool_pre_invoke", { ...ctx, kind: "tool_pre_invoke" }, { args });
+        if (!pre.allow)
+            return deniedToolResult(pre.reason);
+        const effectiveArgs = pre.payload?.args ?? args;
+        const result = await handler(effectiveArgs, extra);
+        const post = await registry.fire("tool_post_invoke", { ...ctx, kind: "tool_post_invoke" }, { args: effectiveArgs, result });
+        if (!post.allow)
+            return deniedToolResult(post.reason);
+        return post.payload?.result ?? result;
+    };
+}
+/**
+ * Wrap a resource readCallback with `resource_pre_fetch` +
+ * `resource_post_fetch` hooks.
+ *
+ * Pre-fetch sees `{uri}`; the payload's `uri` can be mutated (e.g. a
+ * canonicalising plugin) and the override flows into the original
+ * handler. Post-fetch sees `{uri, contents}`; the post-payload's
+ * `contents` (if set) replaces the response.
+ */
+export function wrapResourceHandler(registry, ctx, handler) {
+    return async (uri, extra) => {
+        const uriStr = uri instanceof URL ? uri.toString() : String(uri);
+        const pre = await registry.fire("resource_pre_fetch", { ...ctx, kind: "resource_pre_fetch" }, { uri: uriStr });
+        if (!pre.allow)
+            return deniedResourceResult(uriStr, pre.reason);
+        const effectiveUri = pre.payload?.uri ?? uriStr;
+        // Preserve URL vs string typing the SDK expects.
+        const forwardedUri = uri instanceof URL && effectiveUri !== uriStr ? new URL(effectiveUri) : (uri instanceof URL ? uri : effectiveUri);
+        const result = await handler(forwardedUri, extra);
+        const post = await registry.fire("resource_post_fetch", { ...ctx, kind: "resource_post_fetch" }, { uri: effectiveUri, contents: result?.contents });
+        if (!post.allow)
+            return deniedResourceResult(effectiveUri, post.reason);
+        const overrideContents = post.payload?.contents;
+        if (overrideContents !== undefined && result && typeof result === "object") {
+            return { ...result, contents: overrideContents };
+        }
+        return result;
+    };
+}
+/**
+ * Wrap a prompt callback with `prompt_pre_fetch` + `prompt_post_fetch`
+ * hooks.
+ *
+ * Pre-fetch sees `{name, arguments}`; the override flows in. Post-fetch
+ * sees `{name, arguments, messages}`; the post-payload's `messages`
+ * (if set) replaces the response messages.
+ */
+export function wrapPromptHandler(registry, ctx, handler) {
+    return async (args, extra) => {
+        const pre = await registry.fire("prompt_pre_fetch", { ...ctx, kind: "prompt_pre_fetch" }, { name: ctx.target, arguments: args });
+        if (!pre.allow)
+            return deniedPromptResult(pre.reason);
+        const effectiveArgs = pre.payload?.arguments ?? args;
+        const result = await handler(effectiveArgs, extra);
+        const post = await registry.fire("prompt_post_fetch", { ...ctx, kind: "prompt_post_fetch" }, { name: ctx.target, arguments: effectiveArgs, messages: result?.messages });
+        if (!post.allow)
+            return deniedPromptResult(post.reason);
+        const overrideMessages = post.payload?.messages;
+        if (overrideMessages !== undefined && result && typeof result === "object") {
+            return { ...result, messages: overrideMessages };
+        }
+        return result;
+    };
+}

package/dist/sdk/hook-wrappers.test.d.ts

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

package/dist/sdk/hook-wrappers.test.js

@@ -0,0 +1,204 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { HookRegistry } from "./hooks.js";
+import { wrapToolHandler, wrapResourceHandler, wrapPromptHandler, } from "./hook-wrappers.js";
+const CTX = { principal: "alice", tenant: "default", target: "x" };
+// --- tool ------------------------------------------------------------
+test("wrapToolHandler: no hooks → pass-through", async () => {
+    const reg = new HookRegistry();
+    const wrapped = wrapToolHandler(reg, CTX, async (args) => ({ content: [{ type: "text", text: `got ${JSON.stringify(args)}` }] }));
+    const r = await wrapped({ q: 1 }, undefined);
+    assert.deepEqual(r, { content: [{ type: "text", text: 'got {"q":1}' }] });
+});
+test("wrapToolHandler: pre-invoke denial → isError + reason; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "tool_pre_invoke",
+        handler: () => ({ allow: false, reason: "blocked" }),
+    });
+    const wrapped = wrapToolHandler(reg, CTX, async () => {
+        called = true;
+        return { content: [] };
+    });
+    const r = await wrapped({}, undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, { content: [{ type: "text", text: "blocked" }], isError: true });
+});
+test("wrapToolHandler: pre-invoke args mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "enrich",
+        kind: "tool_pre_invoke",
+        handler: (_ctx, payload) => ({
+            allow: true,
+            payload: { args: { ...payload.args, injected: true } },
+        }),
+    });
+    let observedArgs;
+    const wrapped = wrapToolHandler(reg, CTX, async (args) => {
+        observedArgs = args;
+        return { content: [] };
+    });
+    await wrapped({ original: 1 }, undefined);
+    assert.deepEqual(observedArgs, { original: 1, injected: true });
+});
+test("wrapToolHandler: post-invoke result mutation flows back to caller", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "redact",
+        kind: "tool_post_invoke",
+        handler: () => ({ allow: true, payload: { result: { content: [{ type: "text", text: "REDACTED" }] } } }),
+    });
+    const wrapped = wrapToolHandler(reg, CTX, async () => ({
+        content: [{ type: "text", text: "secret-value" }],
+    }));
+    const r = await wrapped({}, undefined);
+    assert.deepEqual(r, { content: [{ type: "text", text: "REDACTED" }] });
+});
+// --- resource --------------------------------------------------------
+test("wrapResourceHandler: no hooks → pass-through with original URI", async () => {
+    const reg = new HookRegistry();
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "hi" }] };
+    });
+    const r = await wrapped("file:///a", undefined);
+    assert.equal(observed, "file:///a");
+    assert.deepEqual(r, { contents: [{ uri: "file:///a", text: "hi" }] });
+});
+test("wrapResourceHandler: pre-fetch denial returns structured error; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: false, reason: "forbidden uri" }),
+    });
+    const wrapped = wrapResourceHandler(reg, CTX, async () => {
+        called = true;
+        return { contents: [] };
+    });
+    const r = await wrapped("file:///secret", undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, {
+        contents: [{ uri: "file:///secret", mimeType: "text/plain", text: "forbidden uri" }],
+        isError: true,
+    });
+});
+test("wrapResourceHandler: pre-fetch URI mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "canon",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: true, payload: { uri: "file:///canonical" } }),
+    });
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "ok" }] };
+    });
+    await wrapped("file:///raw", undefined);
+    assert.equal(observed, "file:///canonical");
+});
+test("wrapResourceHandler: URL instance preserved across mutation", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "canon",
+        kind: "resource_pre_fetch",
+        handler: () => ({ allow: true, payload: { uri: "https://new.example/path" } }),
+    });
+    let observed;
+    const wrapped = wrapResourceHandler(reg, CTX, async (uri) => {
+        observed = uri;
+        return { contents: [{ uri: String(uri), text: "ok" }] };
+    });
+    await wrapped(new URL("https://old.example/path"), undefined);
+    assert.ok(observed instanceof URL, "mutated URI should still be a URL when caller passed one");
+    assert.equal(String(observed), "https://new.example/path");
+});
+test("wrapResourceHandler: post-fetch contents replacement", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "censor",
+        kind: "resource_post_fetch",
+        handler: () => ({ allow: true, payload: { contents: [{ uri: "file:///x", text: "[censored]" }] } }),
+    });
+    const wrapped = wrapResourceHandler(reg, CTX, async () => ({
+        contents: [{ uri: "file:///x", text: "raw" }],
+        _meta: { kept: true },
+    }));
+    const r = (await wrapped("file:///x", undefined));
+    assert.deepEqual(r.contents, [{ uri: "file:///x", text: "[censored]" }]);
+    // Other top-level keys survive the mutation
+    assert.deepEqual(r._meta, { kept: true });
+});
+// --- prompt ----------------------------------------------------------
+test("wrapPromptHandler: no hooks → pass-through", async () => {
+    const reg = new HookRegistry();
+    const wrapped = wrapPromptHandler(reg, { ...CTX, target: "greet" }, async (args) => ({
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: `hi ${JSON.stringify(args)}` } }],
+    }));
+    const r = await wrapped({ who: "world" }, undefined);
+    assert.deepEqual(r, {
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: 'hi {"who":"world"}' } }],
+    });
+});
+test("wrapPromptHandler: pre-fetch denial returns structured error; handler NOT called", async () => {
+    const reg = new HookRegistry();
+    let called = false;
+    reg.register({
+        pluginName: "guard",
+        kind: "prompt_pre_fetch",
+        handler: () => ({ allow: false, reason: "denied" }),
+    });
+    const wrapped = wrapPromptHandler(reg, CTX, async () => {
+        called = true;
+        return { description: "x", messages: [] };
+    });
+    const r = await wrapped({}, undefined);
+    assert.equal(called, false);
+    assert.deepEqual(r, { description: "denied", messages: [], isError: true });
+});
+test("wrapPromptHandler: pre-fetch arguments mutation flows into handler", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "augment",
+        kind: "prompt_pre_fetch",
+        handler: (_ctx, payload) => ({
+            allow: true,
+            payload: { name: payload.name, arguments: { ...payload.arguments, extra: 1 } },
+        }),
+    });
+    let observed;
+    const wrapped = wrapPromptHandler(reg, CTX, async (args) => {
+        observed = args;
+        return { description: "", messages: [] };
+    });
+    await wrapped({ original: true }, undefined);
+    assert.deepEqual(observed, { original: true, extra: 1 });
+});
+test("wrapPromptHandler: post-fetch messages replacement", async () => {
+    const reg = new HookRegistry();
+    reg.register({
+        pluginName: "rewrite",
+        kind: "prompt_post_fetch",
+        handler: () => ({
+            allow: true,
+            payload: {
+                messages: [{ role: "system", content: { type: "text", text: "rewritten" } }],
+            },
+        }),
+    });
+    const wrapped = wrapPromptHandler(reg, CTX, async () => ({
+        description: "ok",
+        messages: [{ role: "user", content: { type: "text", text: "raw" } }],
+    }));
+    const r = (await wrapped({}, undefined));
+    assert.equal(r.description, "ok");
+    assert.deepEqual(r.messages, [{ role: "system", content: { type: "text", text: "rewritten" } }]);
+});

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>;
+}