@emseepea/server 0.3.2 → 0.4.0

package/dist/index.js

@@ -9,7 +9,8 @@ import { isIP } from "node:net";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
-import { installRequestTelemetry } from "./telemetry.js";
+import { installObservability, } from "./telemetry.js";
+export { openTelemetry, structuredLogging, } from "./telemetry.js";
 export * from "./ui.js";
 export const inputRequired = Object.assign((spec) => sdkInputRequired({ inputRequests: spec.inputRequests }), {
     elicit: sdkInputRequired.elicit,
@@ -34,7 +35,9 @@ const RESOURCE_KIND = Symbol("resourceKind");
 const RESOURCE_MATCHES = Symbol("resourceMatches");
 const RESOURCE_ROUTE = Symbol("resourceRoute");
 const RESOURCE_LISTING = Symbol("resourceListing");
+const RESOURCE_ACCESS = Symbol("resourceAccess");
 const PROMPT_NAME = Symbol("promptName");
+const PROMPT_ACCESS = Symbol("promptAccess");
 const HAS_COMPLETION = Symbol("hasCompletion");
 const PROMPT_LISTING = Symbol("promptListing");
 const CACHEABLE_METHODS = [
@@ -86,6 +89,7 @@ export function defineMappedTool(definition) {
 export function defineResource(definition) {
     const { name, handler } = definition;
     assertRegistrationName("Resource", name);
+    const access = normalizeCapabilityAccess("Resource", definition.access, definition.requiredScopes);
     const uri = canonicalResourceUri(definition.uri);
     const listing = checkedProtocolValue("Resource", {
         name,
@@ -96,7 +100,7 @@ export function defineResource(definition) {
         icons: definition.icons,
         annotations: definition.annotations,
         size: definition.size,
-        _meta: definition._meta,
+        _meta: accessMetadata(definition._meta, access),
     });
     const metadata = Object.freeze({
         title: listing.title,
@@ -114,6 +118,7 @@ export function defineResource(definition) {
         [RESOURCE_NAME]: name,
         [RESOURCE_URI]: uri,
         [RESOURCE_KIND]: "static",
+        [RESOURCE_ACCESS]: access,
         [RESOURCE_LISTING]: Object.freeze({
             method: "resources/list",
             value: listing,
@@ -128,6 +133,7 @@ export function defineResource(definition) {
                         const result = await handler({
                             signal,
                             deadlineMs,
+                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
                             inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
                         });
                         signal.throwIfAborted();
@@ -156,6 +162,7 @@ export function defineResource(definition) {
 export function defineResourceTemplate(definition) {
     const { name, handler } = definition;
     assertRegistrationName("Resource template", name);
+    const access = normalizeCapabilityAccess("Resource template", definition.access, definition.requiredScopes);
     const { template, route } = checkedResourceTemplate(definition.uriTemplate);
     const uriTemplate = template.uriTemplate.toString();
     const listing = checkedProtocolValue("ResourceTemplate", {
@@ -166,7 +173,7 @@ export function defineResourceTemplate(definition) {
         mimeType: definition.mimeType,
         icons: definition.icons,
         annotations: definition.annotations,
-        _meta: definition._meta,
+        _meta: accessMetadata(definition._meta, access),
     });
     const metadata = Object.freeze({
         title: listing.title,
@@ -185,6 +192,7 @@ export function defineResourceTemplate(definition) {
         [RESOURCE_NAME]: name,
         [RESOURCE_URI]: uriTemplate,
         [RESOURCE_KIND]: "template",
+        [RESOURCE_ACCESS]: access,
         [RESOURCE_MATCHES]: (uri) => template.uriTemplate.match(uri) !== null,
         [RESOURCE_ROUTE]: route,
         [RESOURCE_LISTING]: Object.freeze({
@@ -210,6 +218,7 @@ export function defineResourceTemplate(definition) {
                         const result = await handler({ uri: requestedUri.href, variables }, {
                             signal,
                             deadlineMs,
+                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
                             inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
                         });
                         signal.throwIfAborted();
@@ -239,6 +248,7 @@ export function defineResourceTemplate(definition) {
 export function definePrompt(definition) {
     const { name, argsSchema, handler } = definition;
     assertRegistrationName("Prompt", name);
+    const access = normalizeCapabilityAccess("Prompt", definition.access, definition.requiredScopes);
     const argumentNames = Object.keys(argsSchema.shape);
     const completions = checkedCompletionHandlers("Prompt", definition.complete, argumentNames);
     const listing = checkedProtocolValue("Prompt", {
@@ -246,7 +256,7 @@ export function definePrompt(definition) {
         title: definition.title,
         description: definition.description,
         icons: definition.icons,
-        _meta: definition._meta,
+        _meta: accessMetadata(definition._meta, access),
         arguments: promptArguments(argsSchema),
     });
     const metadata = Object.freeze({
@@ -257,6 +267,7 @@ export function definePrompt(definition) {
     });
     const registration = {
         [PROMPT_NAME]: name,
+        [PROMPT_ACCESS]: access,
         [HAS_COMPLETION]: completions.size > 0,
         [PROMPT_LISTING]: listing,
         [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
@@ -274,6 +285,7 @@ export function definePrompt(definition) {
                         const result = await handler(parsedArgs.data, {
                             signal,
                             deadlineMs,
+                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
                             inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
                         });
                         signal.throwIfAborted();
@@ -420,10 +432,7 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
     const { name, inputSchema, outputSchema } = definition;
     assertRegistrationName("Tool", name);
     assertValidMcpHeaderAnnotations(inputSchema);
-    const access = normalizeToolAccess(definition.access, definition.requiredScopes);
-    const publicAccess = access === "public"
-        ? Object.freeze({ type: "public" })
-        : Object.freeze({ type: "protected", requiredScopes: [...access.requiredScopes] });
+    const access = normalizeCapabilityAccess("Tool", definition.access, definition.requiredScopes);
     const sdkInputSchema = sdkMetadataSchema(inputSchema);
     const sdkOutputSchema = sdkMetadataSchema(outputSchema);
     const listing = checkedProtocolValue("Tool", {
@@ -434,10 +443,7 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
         annotations: definition.annotations,
         inputSchema: jsonMetadataSchema(inputSchema, "input"),
         outputSchema: jsonMetadataSchema(outputSchema, "output"),
-        _meta: {
-            ...definition._meta,
-            "io.emseepea/access": publicAccess,
-        },
+        _meta: accessMetadata(definition._meta, access),
     });
     const metadata = Object.freeze({
         title: listing.title,
@@ -490,7 +496,9 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                             assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
                             return result;
                         }
-                        if (!isRecord(result) || typeof result.text !== "string" || !("data" in result)) {
+                        if (!isRecord(result) ||
+                            (result.text !== undefined && typeof result.text !== "string") ||
+                            !("data" in result)) {
                             throw new Error("Tool returned an invalid result");
                         }
                         signal.throwIfAborted();
@@ -499,7 +507,7 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                             throw new Error("Tool returned output that does not match its schema");
                         }
                         const publicResult = {
-                            content: [{ type: "text", text: result.text }],
+                            content: [{ type: "text", text: result.text ?? JSON.stringify(parsedOutput.data) }],
                             structuredContent: parsedOutput.data,
                             isError: false,
                         };
@@ -564,12 +572,24 @@ function progressReporter(context, signal, maxEvents, maxEventBytes) {
         },
         async finish() {
             closed = true;
-            await Promise.allSettled([...pending]);
+            await Promise.allSettled(pending);
         },
         throwIfFailed() { if (failure)
             throw failure; },
     };
 }
+function catalogueListings(tools, resources, prompts) {
+    return new Map([
+        ["tools/list", tools.map((tool) => tool[TOOL_LISTING])],
+        ["resources/list", resources
+                .filter((resource) => resource[RESOURCE_LISTING].method === "resources/list")
+                .map((resource) => resource[RESOURCE_LISTING].value)],
+        ["resources/templates/list", resources
+                .filter((resource) => resource[RESOURCE_LISTING].method === "resources/templates/list")
+                .map((resource) => resource[RESOURCE_LISTING].value)],
+        ["prompts/list", prompts.map((prompt) => prompt[PROMPT_LISTING])],
+    ]);
+}
 function normalizeListPagination(options) {
     const pageSize = positiveInteger("listPagination.pageSize", options.pageSize);
     if (pageSize > 100)
@@ -661,9 +681,7 @@ function installListPagination(server, pagination) {
         server.server.setRequestHandler("prompts/list", (request) => paginationPage(prompts, request.params?.cursor));
 }
 export function createEmseepea(options) {
-    if (options.telemetry !== undefined && typeof options.telemetry !== "boolean") {
-        throw new TypeError("telemetry must be a boolean");
-    }
+    const observability = normalizeObservability(options.observability);
     const readiness = options.readiness;
     const readinessTimeoutMs = callbackTimeout("readiness", readiness, "readinessTimeoutMs", options.readinessTimeoutMs);
     const stopping = new AbortController();
@@ -712,16 +730,27 @@ export function createEmseepea(options) {
     const maxProgressEventBytes = positiveInteger("maxProgressEventBytes", options.maxProgressEventBytes ?? 8 * 1024);
     const operationTimeoutMs = positiveInteger("operationTimeoutMs", options.operationTimeoutMs ?? 30_000);
     const deployment = normalizeDeployment(options.deployment ?? { mode: "loopback" });
-    const oauth = options.oauth ? normalizeOAuth(options.oauth) : undefined;
+    const authentication = options.authentication
+        ? normalizeAuthentication(options.authentication)
+        : undefined;
     const hasStreaming = tools.some((tool) => tool[TOOL_STREAMING]);
     if (deployment.mode !== "loopback" &&
         tools.some((tool) => tool[TOOL_STREAMING] && tool[TOOL_ACCESS] !== "public")) {
         throw new TypeError("Protected streaming tools currently require the loopback deployment profile");
     }
-    if (tools.some((tool) => tool[TOOL_ACCESS] !== "public") && !oauth) {
-        throw new TypeError("Protected tools require OAuth resource-server configuration");
+    if ([
+        ...tools.map((tool) => tool[TOOL_ACCESS]),
+        ...resources.map((resource) => resource[RESOURCE_ACCESS]),
+        ...prompts.map((prompt) => prompt[PROMPT_ACCESS]),
+    ].some((access) => access !== "public") && !authentication) {
+        throw new TypeError("Protected capabilities require authentication configuration");
     }
     const toolsByName = new Map(tools.map((tool) => [tool[TOOL_NAME], tool]));
+    const resourcesByUri = new Map(resources
+        .filter((resource) => resource[RESOURCE_KIND] === "static")
+        .map((resource) => [resource[RESOURCE_URI], resource]));
+    const resourceTemplates = resources.filter((resource) => resource[RESOURCE_KIND] === "template");
+    const promptsByName = new Map(prompts.map((prompt) => [prompt[PROMPT_NAME], prompt]));
     const enabledMethods = new Set(["server/discover"]);
     if (tools.length)
         enabledMethods.add("tools/list").add("tools/call");
@@ -739,37 +768,43 @@ export function createEmseepea(options) {
     const cacheHints = options.cacheHints === undefined
         ? undefined
         : normalizeCacheHints(options.cacheHints, enabledMethods);
-    const pagination = paginationOptions
-        ? compileListPagination(paginationOptions, new Map([
-            ["tools/list", tools.map((tool) => tool[TOOL_LISTING])],
-            ["resources/list", resources
-                    .filter((resource) => resource[RESOURCE_LISTING].method === "resources/list")
-                    .map((resource) => resource[RESOURCE_LISTING].value)],
-            ["resources/templates/list", resources
-                    .filter((resource) => resource[RESOURCE_LISTING].method === "resources/templates/list")
-                    .map((resource) => resource[RESOURCE_LISTING].value)],
-            ["prompts/list", prompts.map((prompt) => prompt[PROMPT_LISTING])],
-        ]))
+    const basePagination = paginationOptions
+        ? compileListPagination(paginationOptions, catalogueListings(tools, resources, prompts))
         : undefined;
     const sdkHandler = createMcpHandler(() => {
+        const request = requestOperations.getStore();
+        const activeTools = request?.filterCatalogues
+            ? tools.filter((tool) => accessAllows(tool[TOOL_ACCESS], request.principal))
+            : tools;
+        const activeResources = request?.filterCatalogues
+            ? resources.filter((resource) => accessAllows(resource[RESOURCE_ACCESS], request.principal))
+            : resources;
+        const activePrompts = request?.filterCatalogues
+            ? prompts.filter((prompt) => accessAllows(prompt[PROMPT_ACCESS], request.principal))
+            : prompts;
+        const activeHasCompletion = activeResources.some((resource) => resource[HAS_COMPLETION]) ||
+            activePrompts.some((prompt) => prompt[HAS_COMPLETION]);
         const server = new McpServer(serverInfo, {
             capabilities: {
-                ...(tools.length ? { tools: { listChanged: false } } : {}),
-                ...(resources.length ? { resources: { subscribe: false, listChanged: false } } : {}),
-                ...(prompts.length ? { prompts: { listChanged: false } } : {}),
-                ...(hasCompletion ? { completions: {} } : {}),
+                ...(activeTools.length ? { tools: { listChanged: false } } : {}),
+                ...(activeResources.length ? { resources: { subscribe: false, listChanged: false } } : {}),
+                ...(activePrompts.length ? { prompts: { listChanged: false } } : {}),
+                ...(activeHasCompletion ? { completions: {} } : {}),
             },
             instructions: options.instructions,
-            cacheHints,
+            cacheHints: request?.filterCatalogues ? undefined : cacheHints,
             supportedProtocolVersions: [PROTOCOL_VERSION],
         });
-        for (const tool of tools) {
+        for (const tool of activeTools) {
             tool[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes);
         }
-        for (const resource of resources)
+        for (const resource of activeResources)
             resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
-        for (const prompt of prompts)
+        for (const prompt of activePrompts)
             prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
+        const pagination = request?.filterCatalogues && paginationOptions
+            ? compileListPagination(paginationOptions, catalogueListings(activeTools, activeResources, activePrompts))
+            : basePagination;
         if (pagination)
             installListPagination(server, pagination);
         return server;
@@ -780,7 +815,10 @@ export function createEmseepea(options) {
     });
     const nodeHandler = toNodeHandler(sdkHandler);
     const app = createMcpFastifyApp({ host: deployment.mode === "loopback" ? "127.0.0.1" : "0.0.0.0" });
-    const finishTelemetry = options.telemetry === true ? installRequestTelemetry(app) : undefined;
+    const observabilityLimits = observability.length ? { deliveryTimeoutMs: 1_000 } : undefined;
+    const finishObservability = observabilityLimits
+        ? installObservability(app, observability, (body) => capabilityNameForRequest(body, toolsByName, resourcesByUri, resourceTemplates, promptsByName), observabilityLimits)
+        : undefined;
     const limiter = deployment.mode === "production-behind-proxy"
         ? new FixedWindowRateLimiter(deployment.rateLimit)
         : undefined;
@@ -791,11 +829,11 @@ export function createEmseepea(options) {
             .code(available ? 200 : 503).send(available ? "ready\n" : "not ready\n");
     });
     app.addHook("preClose", async () => { stopping.abort(); });
-    if (oauth) {
+    if (authentication) {
         app.all("/.well-known/*", async (request, reply) => {
-            const response = oauthMetadataResponse(new Request(new URL(request.url, oauth.metadata.resourceServerUrl.origin), {
+            const response = oauthMetadataResponse(new Request(new URL(request.url, authentication.metadata.resourceServerUrl.origin), {
                 method: request.method,
-            }), oauth.metadata);
+            }), authentication.metadata);
             if (!response) {
                 await reply.code(404).send();
                 return;
@@ -819,20 +857,32 @@ export function createEmseepea(options) {
             await sendRpcError(reply, 404, -32601, "Method not found", requestId(request.body.id));
             return;
         }
-        const access = protectedAccessForCall(request.body, toolsByName);
-        if (access && oauth) {
+        const access = capabilityAccessForRequest(request.body, toolsByName, resourcesByUri, resourceTemplates, promptsByName);
+        const protectsCatalogue = authentication?.discovery === "protected";
+        let authInfo;
+        if (authentication && (protectsCatalogue || access && access !== "public")) {
             try {
-                const authInfo = await verifyProtectedCall(request, reply, access, oauth);
+                authInfo = await verifyAuthenticatedRequest(request, reply, protectsCatalogue ? [] : access.requiredScopes, authentication);
                 request.raw.auth = authInfo;
             }
             catch (error) {
                 await sendWebResponse(reply, bearerAuthChallengeResponse(safeOAuthError(error), {
-                    requiredScopes: [...access.requiredScopes],
-                    resourceMetadataUrl: oauth.resourceMetadataUrl,
+                    requiredScopes: protectsCatalogue
+                        ? []
+                        : [...access.requiredScopes],
+                    resourceMetadataUrl: authentication.resourceMetadataUrl,
                 }));
                 return;
             }
         }
+        const principal = authInfo ? principalFrom(authInfo) : undefined;
+        if (protectsCatalogue)
+            reply.raw.setHeader("cache-control", "private, no-store");
+        if (protectsCatalogue && isCapabilityInvocation(request.body) &&
+            (access === undefined || !accessAllows(access, principal))) {
+            await sendRpcError(reply, 200, -32602, "Capability not found", requestId(isRecord(request.body) ? request.body.id : undefined));
+            return;
+        }
         const disconnected = new AbortController();
         const abort = () => disconnected.abort();
         request.raw.once("aborted", abort);
@@ -841,7 +891,12 @@ export function createEmseepea(options) {
             abort();
         reply.hijack();
         try {
-            await requestOperations.run({ deadlineMs: Date.now() + operationTimeoutMs, signal: disconnected.signal }, () => nodeHandler(request.raw, reply.raw, request.body));
+            await requestOperations.run({
+                deadlineMs: Date.now() + operationTimeoutMs,
+                signal: disconnected.signal,
+                principal,
+                filterCatalogues: protectsCatalogue,
+            }, () => nodeHandler(request.raw, reply.raw, request.body));
         }
         finally {
             request.raw.off("aborted", abort);
@@ -860,7 +915,13 @@ export function createEmseepea(options) {
         }
     });
     app.addHook("onClose", async () => sdkHandler.close());
-    runtimes.set(app, { deployment, requestTimeoutMs: operationTimeoutMs + 5_000, stopping, finishTelemetry });
+    runtimes.set(app, {
+        deployment,
+        requestTimeoutMs: operationTimeoutMs + 5_000,
+        stopping,
+        observabilityLimits,
+        finishObservability,
+    });
     return app;
 }
 function safeOAuthError(error) {
@@ -875,7 +936,7 @@ function safeOAuthError(error) {
                 : "Authorization request failed";
     return new OAuthError(error.code, message);
 }
-async function verifyProtectedCall(request, reply, access, oauth) {
+async function verifyAuthenticatedRequest(request, reply, requiredScopes, authentication) {
     const disconnected = new AbortController();
     const abort = () => disconnected.abort();
     request.raw.once("aborted", abort);
@@ -883,14 +944,20 @@ async function verifyProtectedCall(request, reply, access, oauth) {
     if (requestAlreadyClosed(request, reply))
         abort();
     try {
-        const authInfo = await runWithDeadline(disconnected.signal, Date.now() + oauth.verificationTimeoutMs, () => verifyBearerToken(singleHeader(request.raw.rawHeaders, "authorization"), {
-            verifier: oauth.verifier,
-            requiredScopes: [...access.requiredScopes],
-            resourceMetadataUrl: oauth.resourceMetadataUrl,
+        const authInfo = await runWithDeadline(disconnected.signal, Date.now() + authentication.verificationTimeoutMs, () => verifyBearerToken(singleHeader(request.raw.rawHeaders, "authorization"), {
+            verifier: {
+                async verifyAccessToken(token) {
+                    const authInfo = await authentication.verifier.verifyAccessToken(token);
+                    principalFrom(authInfo);
+                    return authInfo;
+                },
+            },
+            requiredScopes: [...requiredScopes],
+            resourceMetadataUrl: authentication.resourceMetadataUrl,
         }));
         if (!authInfo.resource || authInfo.resource.hash || !checkResourceAllowed({
             requestedResource: authInfo.resource,
-            configuredResource: oauth.metadata.resourceServerUrl,
+            configuredResource: authentication.metadata.resourceServerUrl,
         })) {
             throw new OAuthError(OAuthErrorCode.InvalidToken, "Token is not valid for this resource");
         }
@@ -910,21 +977,79 @@ async function sendWebResponse(reply, response) {
     const body = Buffer.from(await response.arrayBuffer());
     await reply.code(response.status).send(body.length ? body : undefined);
 }
-function protectedAccessForCall(body, toolsByName) {
-    if (!isRecord(body) || body.method !== "tools/call" || !isRecord(body.params) ||
-        typeof body.params.name !== "string")
+function capabilityAccessForRequest(body, toolsByName, resourcesByUri, resourceTemplates, promptsByName) {
+    if (!isRecord(body) || !isRecord(body.params))
         return undefined;
-    const access = toolsByName.get(body.params.name)?.[TOOL_ACCESS];
-    return access === "public" ? undefined : access;
+    const params = body.params;
+    if (body.method === "tools/call" && typeof params.name === "string") {
+        return toolsByName.get(params.name)?.[TOOL_ACCESS];
+    }
+    if (body.method === "resources/read" && typeof params.uri === "string") {
+        return resourcesByUri.get(params.uri)?.[RESOURCE_ACCESS] ?? resourceTemplates.find((resource) => resource[RESOURCE_MATCHES]?.(params.uri))?.[RESOURCE_ACCESS];
+    }
+    if (body.method === "prompts/get" && typeof params.name === "string") {
+        return promptsByName.get(params.name)?.[PROMPT_ACCESS];
+    }
+    if (body.method === "completion/complete" && isRecord(params.ref)) {
+        const reference = params.ref;
+        if (reference.type === "ref/prompt" && typeof reference.name === "string") {
+            return promptsByName.get(reference.name)?.[PROMPT_ACCESS];
+        }
+        if (reference.type === "ref/resource" && typeof reference.uri === "string") {
+            return resourceTemplates.find((resource) => resource[RESOURCE_URI] === reference.uri)?.[RESOURCE_ACCESS];
+        }
+    }
+    return undefined;
+}
+function isCapabilityInvocation(body) {
+    return isRecord(body) && (body.method === "tools/call" || body.method === "resources/read" ||
+        body.method === "prompts/get" || body.method === "completion/complete");
+}
+function capabilityNameForRequest(body, toolsByName, resourcesByUri, resourceTemplates, promptsByName) {
+    if (!isRecord(body) || !isRecord(body.params))
+        return undefined;
+    const params = body.params;
+    if (body.method === "tools/call" && typeof params.name === "string") {
+        return toolsByName.has(params.name) ? params.name : undefined;
+    }
+    if (body.method === "resources/read" && typeof params.uri === "string") {
+        const resource = resourcesByUri.get(params.uri) ?? resourceTemplates.find((candidate) => candidate[RESOURCE_MATCHES]?.(params.uri));
+        return resource?.[RESOURCE_NAME];
+    }
+    if (body.method === "prompts/get" && typeof params.name === "string") {
+        return promptsByName.has(params.name) ? params.name : undefined;
+    }
+    if (body.method === "completion/complete" && isRecord(params.ref)) {
+        const reference = params.ref;
+        return reference.type === "ref/prompt" && typeof reference.name === "string"
+            ? (promptsByName.has(reference.name) ? reference.name : undefined)
+            : reference.type === "ref/resource" && typeof reference.uri === "string"
+                ? resourceTemplates.find((candidate) => candidate[RESOURCE_URI] === reference.uri)?.[RESOURCE_NAME]
+                : undefined;
+    }
+    return undefined;
 }
 function principalFrom(authInfo) {
     if (!authInfo)
-        throw new Error("Protected tool reached execution without verified authorization");
-    return {
+        throw new Error("Protected capability reached execution without verified authorization");
+    if (typeof authInfo.clientId !== "string" || !authInfo.clientId.trim() || authInfo.clientId.length > 256) {
+        throw new TypeError("Authentication verifier returned an invalid clientId");
+    }
+    if (!Array.isArray(authInfo.scopes) || authInfo.scopes.some((scope) => typeof scope !== "string" || !/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) || new Set(authInfo.scopes).size !== authInfo.scopes.length) {
+        throw new TypeError("Authentication verifier returned invalid permissions");
+    }
+    const permissions = Object.freeze([...authInfo.scopes]);
+    return Object.freeze({
         clientId: authInfo.clientId,
-        scopes: [...authInfo.scopes],
+        permissions,
         resource: authInfo.resource?.href,
-    };
+    });
+}
+function accessAllows(access, principal) {
+    if (access === "public")
+        return true;
+    return principal !== undefined &&
+        access.requiredScopes.every((permission) => principal.permissions.includes(permission));
 }
 export async function serveEmseepea(app, options = {}) {
     const runtime = runtimes.get(app);
@@ -936,8 +1061,13 @@ export async function serveEmseepea(app, options = {}) {
     }
     const port = nonNegativePort(options.port ?? 3000);
     const shutdownTimeoutMs = positiveInteger("shutdownTimeoutMs", options.shutdownTimeoutMs ?? 5_000);
-    const flushTelemetry = options.flushTelemetry;
-    const telemetryFlushTimeoutMs = callbackTimeout("flushTelemetry", flushTelemetry, "telemetryFlushTimeoutMs", options.telemetryFlushTimeoutMs);
+    const observabilityFlushTimeoutMs = positiveInteger("observabilityFlushTimeoutMs", options.observabilityFlushTimeoutMs === undefined ? 1_000 : options.observabilityFlushTimeoutMs);
+    if (observabilityFlushTimeoutMs > 60_000) {
+        throw new TypeError("observabilityFlushTimeoutMs must not exceed 60000");
+    }
+    if (runtime.observabilityLimits) {
+        runtime.observabilityLimits.deliveryTimeoutMs = observabilityFlushTimeoutMs;
+    }
     await app.listen({ host, port });
     app.server.headersTimeout = 10_000;
     app.server.keepAliveTimeout = 5_000;
@@ -955,7 +1085,7 @@ export async function serveEmseepea(app, options = {}) {
         url: new URL(`http://${urlHost}:${address.port}/mcp`),
         close: () => {
             runtime.stopping.abort();
-            return closing ??= closeApp(app, shutdownTimeoutMs, flushTelemetry, telemetryFlushTimeoutMs, runtime.finishTelemetry);
+            return closing ??= closeApp(app, shutdownTimeoutMs, observabilityFlushTimeoutMs, runtime.finishObservability);
         },
     };
 }
@@ -1035,26 +1165,34 @@ class FixedWindowRateLimiter {
         return "allowed";
     }
 }
-function normalizeToolAccess(access, requiredScopes) {
+function normalizeCapabilityAccess(kind, access, requiredScopes) {
     if (access === "public")
         return access;
     if (access !== "protected" || !Array.isArray(requiredScopes) || requiredScopes.length === 0) {
-        throw new TypeError('Tool access must be explicitly declared as "public" or protected with scopes');
+        throw new TypeError(`${kind} access must be explicitly declared as "public" or protected with scopes`);
     }
     const scopes = requiredScopes.map((scope) => {
         if (typeof scope !== "string" || !/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) {
-            throw new TypeError("Protected tool scopes must be valid OAuth scope tokens");
+            throw new TypeError(`Protected ${kind.toLowerCase()} scopes must be valid OAuth scope tokens`);
         }
         return scope;
     });
     if (new Set(scopes).size !== scopes.length) {
-        throw new TypeError("Protected tool scopes must be unique");
+        throw new TypeError(`Protected ${kind.toLowerCase()} scopes must be unique`);
     }
     return { type: "protected", requiredScopes: scopes };
 }
-function normalizeOAuth(options) {
+function accessMetadata(metadata, access) {
+    return Object.freeze({
+        ...metadata,
+        "io.emseepea/access": access === "public"
+            ? Object.freeze({ type: "public" })
+            : Object.freeze({ type: "protected", requiredScopes: [...access.requiredScopes] }),
+    });
+}
+function normalizeAuthentication(options) {
     if (!options.verifier || typeof options.verifier.verifyAccessToken !== "function") {
-        throw new TypeError("oauth.verifier must implement verifyAccessToken");
+        throw new TypeError("authentication.verifier must implement verifyAccessToken");
     }
     if (options.metadata.dangerouslyAllowInsecureIssuerUrl === true) {
         throw new TypeError("Insecure OAuth issuer URLs are not supported");
@@ -1070,9 +1208,37 @@ function normalizeOAuth(options) {
         verifier: options.verifier,
         metadata: options.metadata,
         resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(options.metadata.resourceServerUrl),
-        verificationTimeoutMs: positiveInteger("oauth.verificationTimeoutMs", options.verificationTimeoutMs ?? 10_000),
+        verificationTimeoutMs: positiveInteger("authentication.verificationTimeoutMs", options.verificationTimeoutMs ?? 10_000),
+        discovery: options.discovery === undefined || options.discovery === "public"
+            ? "public"
+            : options.discovery === "protected"
+                ? "protected"
+                : (() => { throw new TypeError('authentication.discovery must be "public" or "protected"'); })(),
     };
 }
+function normalizeObservability(adapters) {
+    if (adapters === undefined)
+        return [];
+    if (!Array.isArray(adapters))
+        throw new TypeError("observability must be an array");
+    const ids = new Set();
+    return Object.freeze(adapters.map((adapter) => {
+        if (!adapter || typeof adapter !== "object" ||
+            typeof adapter.id !== "string" || !/^[A-Za-z0-9_.-]{1,64}$/.test(adapter.id) ||
+            typeof adapter.emit !== "function" ||
+            adapter.flush !== undefined && typeof adapter.flush !== "function") {
+            throw new TypeError("observability adapters require a valid id, emit function, and optional flush function");
+        }
+        if (ids.has(adapter.id))
+            throw new TypeError(`Duplicate observability adapter id: ${adapter.id}`);
+        ids.add(adapter.id);
+        return Object.freeze({
+            id: adapter.id,
+            emit: adapter.emit,
+            ...(adapter.flush ? { flush: adapter.flush } : {}),
+        });
+    }));
+}
 function isLoopbackUrl(url) {
     return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
 }
@@ -1446,6 +1612,7 @@ function completionCallback(complete, currentName, allowedNames, timeoutMs, maxA
                 const values = await complete(value, {
                     signal,
                     deadlineMs,
+                    principal: request?.principal,
                     arguments: completionArguments(context?.arguments, allowedArguments),
                 });
                 signal.throwIfAborted();
@@ -1677,7 +1844,7 @@ function assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal)
 function isLoopbackHost(host) {
     return host === "127.0.0.1" || host === "::1" || host === "localhost";
 }
-async function closeApp(app, timeoutMs, flushTelemetry, flushTimeoutMs, finishTelemetry) {
+async function closeApp(app, timeoutMs, flushTimeoutMs, finishObservability) {
     let timer;
     let onClosed;
     const httpClosed = new Promise((resolve) => { onClosed = resolve; });
@@ -1696,21 +1863,14 @@ async function closeApp(app, timeoutMs, flushTelemetry, flushTimeoutMs, finishTe
     finally {
         if (timer)
             clearTimeout(timer);
-        if (flushTelemetry) {
-            const controller = new AbortController();
-            const flushDeadline = Date.now() + flushTimeoutMs;
+        if (finishObservability) {
             const expired = new Promise((resolve) => {
                 // Keep the process alive long enough to finish flushing after sockets close.
-                timer = setTimeout(() => { controller.abort(); resolve(); }, flushTimeoutMs);
+                timer = setTimeout(resolve, flushTimeoutMs);
             });
             try {
                 await Promise.race([
-                    httpClosed.then(async () => {
-                        await finishTelemetry?.();
-                        if (!controller.signal.aborted && Date.now() < flushDeadline) {
-                            await flushTelemetry({ signal: controller.signal });
-                        }
-                    }).catch(() => { }),
+                    httpClosed.then(() => finishObservability(flushTimeoutMs)).catch(() => { }),
                     expired,
                 ]);
             }