@thotischner/observability-mcp 3.0.0 → 3.1.0

package/dist/scim/routes.js

@@ -23,7 +23,11 @@ import { ScimNotFoundError, ScimValidationError } from "./store.js";
 const constantTimeBearerMatch = (raw, expected) => {
     if (!raw)
         return false;
-    const m = raw.match(/^Bearer\s+(.+)$/i);
+    // Use bounded whitespace ({1,16}) instead of `\s+` to avoid the
+    // polynomial-ReDoS class — `\s+` followed by `(.+)` backtracks on
+    // strings like "bearer<many spaces><payload>". 16 is generous;
+    // RFC 7235 only requires one space.
+    const m = raw.match(/^Bearer[ \t]{1,16}(.+)$/i);
     if (!m)
         return false;
     const a = Buffer.from(m[1].trim());
@@ -205,29 +209,171 @@ export function registerScimRoutes(app, deps) {
 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) {
+// Allow-list of attribute names patchable via SCIM PatchOp.
+// `applyPatchOps` writes into a plain object using a user-supplied
+// path/key — every key is gated through this set so a malicious
+// client can't inject __proto__ / constructor / arbitrary fields.
+const PATCH_ALLOWED_ATTRS = new Set([
+    "userName", "active", "displayName", "name", "emails", "externalId",
+    "members", "groups",
+]);
+function safePatchKey(k) {
+    return typeof k === "string" && PATCH_ALLOWED_ATTRS.has(k);
+}
+// Multi-valued attributes that support add/remove element ops + filter
+// segments. Everything else is treated as a scalar (replace/set).
+const PATCH_ARRAY_ATTRS = new Set(["members", "emails", "groups"]);
+/** Parse a PatchOp `path` into {attr, filter?}. Supports a bare
+ *  attribute (`members`) and a single `eq` filter segment
+ *  (`members[value eq "abc"]`). Returns null for anything that
+ *  doesn't name an allow-listed attribute or that we don't model —
+ *  the caller skips those ops (fail-closed). The sub-attribute in the
+ *  filter is only ever READ for comparison, never written, so it
+ *  can't drive prototype pollution. */
+function parsePatchPath(path) {
+    const filterMatch = /^([A-Za-z][\w]*)\[\s*([A-Za-z][\w]*)\s+eq\s+"([^"]*)"\s*\]$/.exec(path);
+    if (filterMatch) {
+        const attr = filterMatch[1];
+        if (!safePatchKey(attr))
+            return null;
+        return { attr, filter: { sub: filterMatch[2], val: filterMatch[3] } };
+    }
+    if (safePatchKey(path))
+        return { attr: path };
+    return null;
+}
+// Always returns a FRESH array — never the caller's reference — so the
+// add/remove machinery can push/filter without mutating the current
+// resource in place (which would corrupt it across chained ops or
+// repeated calls).
+function asArray(v) {
+    if (Array.isArray(v))
+        return v.slice();
+    if (v == null)
+        return [];
+    return [v];
+}
+/** Element identity for dedup/removal on multi-valued attrs. SCIM
+ *  members/emails carry a `value` key; fall back to JSON equality. */
+function elemKey(e) {
+    if (e && typeof e === "object" && "value" in e) {
+        return String(e.value);
+    }
+    return JSON.stringify(e);
+}
+/** 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 function applyPatchOps(current, patch) {
     if (!current)
         throw new ScimNotFoundError("target resource not found");
     if (!patch?.Operations || !Array.isArray(patch.Operations))
         return {};
+    const cur = current;
     const out = {};
+    // Read the working value for an attr: prefer an in-progress value
+    // from a prior op in this same request, else the current resource.
+    const readAttr = (attr) => (attr in out ? out[attr] : cur[attr]);
     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);
+        const verb = (op.op || "").toLowerCase();
+        if (verb === "replace") {
+            if (!op.path) {
+                if (op.value && typeof op.value === "object") {
+                    for (const [k, v] of Object.entries(op.value)) {
+                        if (safePatchKey(k))
+                            out[k] = v;
+                    }
+                }
+                continue;
+            }
+            const parsed = parsePatchPath(op.path);
+            if (parsed && !parsed.filter)
+                out[parsed.attr] = op.value;
+            continue;
+        }
+        if (verb === "add") {
+            if (!op.path) {
+                if (op.value && typeof op.value === "object") {
+                    for (const [k, v] of Object.entries(op.value)) {
+                        if (!safePatchKey(k))
+                            continue;
+                        if (PATCH_ARRAY_ATTRS.has(k)) {
+                            const existing = asArray(readAttr(k));
+                            const seen = new Set(existing.map(elemKey));
+                            for (const item of asArray(v)) {
+                                if (!seen.has(elemKey(item))) {
+                                    existing.push(item);
+                                    seen.add(elemKey(item));
+                                }
+                            }
+                            out[k] = existing;
+                        }
+                        else {
+                            out[k] = v;
+                        }
+                    }
+                }
+                continue;
+            }
+            const parsed = parsePatchPath(op.path);
+            if (!parsed || parsed.filter)
+                continue;
+            if (PATCH_ARRAY_ATTRS.has(parsed.attr)) {
+                const existing = asArray(readAttr(parsed.attr));
+                const seen = new Set(existing.map(elemKey));
+                for (const item of asArray(op.value)) {
+                    if (!seen.has(elemKey(item))) {
+                        existing.push(item);
+                        seen.add(elemKey(item));
+                    }
+                }
+                out[parsed.attr] = existing;
+            }
+            else {
+                out[parsed.attr] = op.value;
+            }
+            continue;
+        }
+        if (verb === "remove") {
+            if (!op.path)
+                continue; // remove with no path is a no-op (nothing to target)
+            const parsed = parsePatchPath(op.path);
+            if (!parsed)
+                continue;
+            if (parsed.filter && PATCH_ARRAY_ATTRS.has(parsed.attr)) {
+                const existing = asArray(readAttr(parsed.attr));
+                const { sub, val } = parsed.filter;
+                out[parsed.attr] = existing.filter((e) => {
+                    const ev = e && typeof e === "object" ? e[sub] : undefined;
+                    return String(ev) !== val;
+                });
+            }
+            else if (PATCH_ARRAY_ATTRS.has(parsed.attr)) {
+                out[parsed.attr] = [];
+            }
+            else {
+                out[parsed.attr] = undefined;
             }
             continue;
         }
-        out[op.path] = op.value;
     }
     return out;
 }

package/dist/scim/store.d.ts

@@ -3,7 +3,30 @@ export interface ScimSnapshot {
     users: ScimUser[];
     groups: ScimGroup[];
 }
-export declare class ScimStore {
+/**
+ * The store surface route handlers and group-role-map depend on.
+ * Both file + redis backends implement this. New backends (DynamoDB,
+ * Postgres, …) just need to satisfy these methods.
+ */
+export interface IScimStore {
+    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;
+    }>;
+}
+export declare class ScimStore implements IScimStore {
     private readonly path;
     private snapshot;
     private bootstrapped;
@@ -35,3 +58,19 @@ export declare class ScimValidationError extends Error {
 export declare class ScimNotFoundError extends Error {
     constructor(message: string);
 }
+/**
+ * Boot-time factory. Reads OMCP_SCIM_BACKEND and returns the matching
+ * implementation. Loadbearing on Helm too — values.yaml exposes a
+ * scim.backend toggle that ends up as the env var.
+ *
+ * config.path  — file backend storage path (file backend only).
+ * config.redis — RedisLike client (redis backend only).
+ * config.redisKey — override default key name.
+ */
+export interface CreateScimStoreConfig {
+    backend?: "file" | "redis";
+    path?: string;
+    redis?: import("./redis-store.js").RedisLike;
+    redisKey?: string;
+}
+export declare function createScimStore(config?: CreateScimStoreConfig): Promise<IScimStore>;

package/dist/scim/store.js

@@ -1,9 +1,11 @@
-// SCIM store — file-backed JSON for users + groups.
+// SCIM store — file-backed JSON for users + groups (default), with a
+// Redis-backed alternative for multi-replica deployments behind the
+// `OMCP_SCIM_BACKEND=redis` env / `scim.backend: redis` Helm value.
 //
-// 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.
+// F21a shipped the on-disk JSON file (atomic tmp+rename, mode 0600).
+// F21b (Q6) adds the Redis variant + the IScimStore interface every
+// route handler now talks to. The factory `createScimStore` picks
+// the implementation at boot; everything downstream is unchanged.
 import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
 import { dirname } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -176,3 +178,19 @@ export class ScimNotFoundError extends Error {
         this.name = "ScimNotFoundError";
     }
 }
+export async function createScimStore(config = {}) {
+    const backend = (config.backend || process.env.OMCP_SCIM_BACKEND || "file");
+    if (backend === "redis") {
+        if (!config.redis) {
+            throw new Error("createScimStore: backend=redis requires a redis client. Pass config.redis (RedisLike).");
+        }
+        const { RedisScimStore } = await import("./redis-store.js");
+        const store = new RedisScimStore(config.redis, { key: config.redisKey });
+        await store.load();
+        return store;
+    }
+    const path = config.path || process.env.OMCP_SCIM_STORE || "/var/lib/observability-mcp/scim.json";
+    const store = new ScimStore(path);
+    await store.load();
+    return store;
+}

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

@@ -42,6 +42,19 @@ export interface ConnectorManifest {
      * server runs with VERIFY_PLUGINS=true. See docs/plugin-architecture.md.
      */
     integrity?: string;
+    /**
+     * Lifecycle hooks the plugin wants auto-registered on load. Each
+     * entry points to a module path INSIDE the plugin's bundled files;
+     * the loader imports its default export and registers it on the
+     * gateway's HookRegistry. Mirrors the Zod manifestSchema in
+     * mcp-server/src/sdk/manifest-schema.ts. See Q10 / phase-q-sprint.md.
+     */
+    hooks?: Array<{
+        kind: "tool_pre_invoke" | "tool_post_invoke" | "resource_pre_fetch" | "resource_post_fetch" | "prompt_pre_fetch" | "prompt_post_fetch";
+        module: string;
+        priority?: number;
+        mode?: "enforce" | "permissive" | "disabled";
+    }>;
 }
 /**
  * The default export shape a connector plugin module must provide.