qyl-mcp-server 7.0.0 → 7.1.1

package/dist/events-authorization.js

@@ -0,0 +1,160 @@
+/**
+ * Recheck the Auth0 account, explicit application grant, user consent and RBAC
+ * permission without retaining the subscriber's OAuth tokens. Management
+ * credentials come from the host's secret store; their access token lives only
+ * in memory. API failures never authorize delivery.
+ *
+ * Auth0 Management API: users/{id}, users/{id}/permissions, client-grants, grants.
+ */
+import { z } from "zod";
+import { QYL_MCP_ISSUER, QYL_MCP_RESOURCE, QYL_MCP_SCOPE } from "./oauth.js";
+const REQUEST_TIMEOUT_MS = 10_000;
+const ACCESS_CACHE_MS = 5_000;
+const MAX_CACHE_ENTRIES = 1_000;
+const PAGE_SIZE = 100;
+const MAX_PAGES = 10;
+const TokenSchema = z.object({
+    access_token: z.string().min(1),
+    token_type: z.literal("Bearer"),
+    expires_in: z.number().positive(),
+});
+const UserSchema = z.object({ blocked: z.boolean().optional() });
+const CimdClientSchema = z.object({ client_id: z.string(), external_client_id: z.string().optional() });
+const PermissionSchema = z.object({
+    resource_server_identifier: z.string(), permission_name: z.string(),
+});
+const ClientGrantSchema = z.object({
+    client_id: z.string().optional(), audience: z.string(),
+    subject_type: z.string().optional(), scope: z.array(z.string()),
+});
+const UserGrantSchema = z.object({
+    clientID: z.string(), user_id: z.string(), audience: z.string(),
+    scope: z.array(z.string()), organization_id: z.string().optional(),
+});
+/** Thrown without response bodies, credentials or subscriber identifiers. */
+class EventsAuthorizationUnavailable extends Error {
+    name = "EventsAuthorizationUnavailable";
+    constructor() { super("Event authorization is temporarily unavailable"); }
+}
+export function createEventsAuthorization(options) {
+    const request = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    let token;
+    let refreshing;
+    const pending = new Map();
+    const cache = new Map();
+    async function managementToken() {
+        if (token !== undefined && token.expiresAt > now())
+            return token.value;
+        refreshing ??= (async () => {
+            const response = await request(new URL("oauth/token", QYL_MCP_ISSUER), {
+                method: "POST", redirect: "error", signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "client_credentials", client_id: options.clientId,
+                    client_secret: options.clientSecret, audience: `${QYL_MCP_ISSUER}api/v2/`,
+                }),
+            });
+            if (!response.ok)
+                throw new EventsAuthorizationUnavailable();
+            const result = TokenSchema.parse(await response.json());
+            token = { value: result.access_token, expiresAt: now() + Math.max(0, result.expires_in - 60) * 1_000 };
+            return token.value;
+        })().finally(() => { refreshing = undefined; });
+        return refreshing;
+    }
+    async function get(path, query = {}) {
+        const url = new URL(`api/v2/${path}`, QYL_MCP_ISSUER);
+        url.search = new URLSearchParams(query).toString();
+        const response = await request(url, {
+            redirect: "error", signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: { authorization: `Bearer ${await managementToken()}` },
+        });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok) {
+            if (response.status === 401)
+                token = undefined;
+            throw new EventsAuthorizationUnavailable();
+        }
+        return response.json();
+    }
+    async function any(path, query, schema, predicate) {
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const body = await get(path, { ...query, per_page: String(PAGE_SIZE), page: String(page) });
+            if (body === undefined)
+                return false;
+            const entries = z.array(schema).parse(body);
+            if (entries.some(predicate))
+                return true;
+            if (entries.length < PAGE_SIZE)
+                return false;
+        }
+        // An incomplete permission listing is not evidence of revocation.
+        throw new EventsAuthorizationUnavailable();
+    }
+    async function applicationClientId(clientId) {
+        if (!clientId.startsWith("https://"))
+            return clientId;
+        // Auth0 puts the CIMD URL in the token, but its Management API grants use
+        // the internal application ID. Resolve through the trusted issuer only.
+        const body = await get("clients", {
+            external_client_id: clientId, fields: "client_id,external_client_id",
+            include_fields: "true", per_page: "2",
+        });
+        if (body === undefined)
+            return undefined;
+        const clients = z.array(CimdClientSchema).parse(body);
+        // Auth0's field projection can omit external_client_id. The exact query
+        // still filters by it; reject multiple matches or a conflicting value.
+        return clients.length === 1
+            && (clients[0].external_client_id === undefined || clients[0].external_client_id === clientId)
+            ? clients[0].client_id : undefined;
+    }
+    async function check(principal) {
+        const userPath = `users/${encodeURIComponent(principal.subject)}`;
+        const body = await get(userPath, { fields: "blocked", include_fields: "true" });
+        if (body === undefined || UserSchema.parse(body).blocked === true)
+            return false;
+        const clientId = await applicationClientId(principal.clientId);
+        if (clientId === undefined)
+            return false;
+        const [permission, application, consent] = await Promise.all([
+            any(`${userPath}/permissions`, {}, PermissionSchema, (entry) => entry.resource_server_identifier === QYL_MCP_RESOURCE && entry.permission_name === QYL_MCP_SCOPE),
+            any("client-grants", { client_id: clientId, audience: QYL_MCP_RESOURCE, subject_type: "user" }, ClientGrantSchema, (entry) => entry.client_id === clientId && entry.audience === QYL_MCP_RESOURCE
+                && entry.subject_type === "user" && entry.scope.includes(QYL_MCP_SCOPE)),
+            any("grants", { user_id: principal.subject, client_id: clientId, audience: QYL_MCP_RESOURCE }, UserGrantSchema, (entry) => entry.user_id === principal.subject && entry.clientID === clientId
+                && entry.audience === QYL_MCP_RESOURCE && entry.organization_id === undefined
+                && entry.scope.includes(QYL_MCP_SCOPE)),
+        ]);
+        return permission && application && consent;
+    }
+    return (principal) => {
+        const key = JSON.stringify([principal.subject, principal.clientId]);
+        const cached = cache.get(key);
+        if (cached !== undefined && cached.expiresAt > now())
+            return Promise.resolve(cached.allowed);
+        let checking = pending.get(key);
+        if (checking === undefined) {
+            checking = check(principal).then((allowed) => {
+                if (cache.size >= MAX_CACHE_ENTRIES)
+                    cache.clear();
+                cache.set(key, { allowed, expiresAt: now() + ACCESS_CACHE_MS });
+                return allowed;
+            }).catch(() => {
+                throw new EventsAuthorizationUnavailable();
+            }).finally(() => { pending.delete(key); });
+            pending.set(key, checking);
+        }
+        return checking;
+    };
+}
+export function hostedEventsAuthorization(environment) {
+    const clientId = environment["MCP_EVENTS_AUTH0_CLIENT_ID"]?.trim();
+    const clientSecret = environment["MCP_EVENTS_AUTH0_CLIENT_SECRET"]?.trim();
+    if (!clientId || !clientSecret) {
+        throw new Error("MCP_EVENTS_STORE requires MCP_EVENTS_AUTH0_CLIENT_ID and MCP_EVENTS_AUTH0_CLIENT_SECRET for ongoing access checks");
+    }
+    return createEventsAuthorization({ clientId, clientSecret });
+}
+//# sourceMappingURL=events-authorization.js.map

package/dist/events-authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-authorization.js","sourceRoot":"","sources":["../src/events-authorization.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,234 @@
+/**
+ * MCP Events for ChatGPT: `events/list`, `events/subscribe` and
+ * `events/unsubscribe` on the authenticated MCP endpoint, with signed webhook
+ * delivery of one event type, `trace.error`.
+ *
+ * Contract: developers.openai.com/plugins/build/mcp-events (ChatGPT supports
+ * webhook delivery with callback verification only) and the draft MCP Events
+ * design sketch in modelcontextprotocol/experimental-ext-triggers-events.
+ * `@modelcontextprotocol/server` 2.3.1 ships no `events/*` methods, so the
+ * three are custom request handlers and the capability is added by hand.
+ *
+ * Delivery source: the collector's recent-trace list, polled only while a
+ * subscription is live. The first poll sets a baseline, so a subscription
+ * never receives a backlog. Events carry `cursor: null` — there is no replay;
+ * traces that arrive while the server is down are not delivered.
+ *
+ * Access: subscribing, refreshing and unsubscribing each pass the same OAuth
+ * gate as every tool call. The required authorization callback rechecks the
+ * owner's current access while polling and before delivery, including retries.
+ * Authorization outages suspend delivery; revoked access removes the record.
+ */
+import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { AtomicJsonStore } from "./atomic-json-store.js";
+import type { QylTrace } from "./wire.js";
+import { type WebhookPost } from "./webhook.js";
+export declare const TRACE_ERROR_EVENT_NAME = "trace.error";
+/** JSON-RPC error for a callback that failed validation or verification. */
+export declare const CALLBACK_ENDPOINT_ERROR = -32015;
+export declare const DEFAULT_TTL_MS: number;
+export declare const MIN_TTL_MS: number;
+export declare const MAX_TTL_MS: number;
+/**
+ * Live subscriptions one caller may hold. Every subscription is a stored
+ * entry, a delivery fan-out target and, for a new callback, an outbound
+ * verification POST; without a cap one account grows all three at will.
+ */
+export declare const MAX_SUBSCRIPTIONS_PER_PRINCIPAL = 20;
+/** The one event definition `events/list` returns. */
+export declare const TRACE_ERROR_EVENT: {
+    readonly name: "trace.error";
+    readonly description: string;
+    readonly delivery: readonly ["webhook"];
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly service_name: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+                readonly description: "Only traces that involve this service.";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+    readonly payloadSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly trace_id: {
+                readonly type: "string";
+                readonly description: "Trace identifier; pass it to get_trace or display_traces.";
+            };
+            readonly root_span: {
+                readonly type: "string";
+                readonly description: "Name of the trace's root span.";
+            };
+            readonly services: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Services involved in the trace.";
+            };
+            readonly span_count: {
+                readonly type: "integer";
+                readonly description: "Total span count.";
+            };
+            readonly duration_ms: {
+                readonly type: "number";
+                readonly description: "Trace duration in milliseconds.";
+            };
+            readonly start_time: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "Trace start time.";
+            };
+        };
+        readonly required: readonly ["trace_id", "root_span", "services", "span_count", "duration_ms", "start_time"];
+        readonly additionalProperties: false;
+    };
+};
+declare const SubscribeParamsSchema: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    delivery: z.ZodObject<{
+        mode: z.ZodString;
+        url: z.ZodString;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ttlMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type SubscribeParams = z.infer<typeof SubscribeParamsSchema>;
+declare const UnsubscribeParamsSchema: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    delivery: z.ZodObject<{
+        mode: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type UnsubscribeParams = z.infer<typeof UnsubscribeParamsSchema>;
+/** The authenticated caller a subscription belongs to. */
+export interface Principal {
+    subject: string;
+    clientId: string;
+}
+declare const StoredSubscriptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    clientId: z.ZodString;
+    name: z.ZodLiteral<"trace.error">;
+    arguments: z.ZodObject<{
+        service_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    url: z.ZodString;
+    secret: z.ZodString;
+    previousSecret: z.ZodOptional<z.ZodString>;
+    previousSecretUntil: z.ZodOptional<z.ZodString>;
+    refreshBefore: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type StoredSubscription = z.infer<typeof StoredSubscriptionSchema>;
+declare const EventStoreStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    subscriptions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        subject: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodLiteral<"trace.error">;
+        arguments: z.ZodObject<{
+            service_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        url: z.ZodString;
+        secret: z.ZodString;
+        previousSecret: z.ZodOptional<z.ZodString>;
+        previousSecretUntil: z.ZodOptional<z.ZodString>;
+        refreshBefore: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EventStoreState = z.infer<typeof EventStoreStateSchema>;
+/** Subscription storage that survives restarts: an atomic JSON file (0600). */
+export declare function createEventStore(filePath: string): AtomicJsonStore<EventStoreState>;
+/** Key-order-independent JSON, so `{a,b}` and `{b,a}` name one subscription. */
+export declare function canonicalJson(value: unknown): string;
+/** Deterministic ID over principal, callback URL, event name and arguments. */
+export declare function subscriptionId(principal: Principal, url: string, name: string, args: unknown): string;
+/** The lifetime granted for a requested `ttlMs`: bounded, and never unbounded. */
+export declare function grantedTtlMs(ttlMs: number | null | undefined): number;
+/** The principal of a verified request, or a JSON-RPC error without one. */
+export declare function principalOf(ctx: Pick<ServerContext, "http">): Principal;
+/** The `data` of a `trace.error` delivery; matches `payloadSchema`. */
+export declare function traceErrorPayload(trace: QylTrace): Record<string, unknown>;
+export interface EventsRuntimeOptions {
+    store: AtomicJsonStore<EventStoreState>;
+    /** Live access check. False revokes; errors suspend delivery without deleting state. */
+    isAuthorized: (principal: Principal) => Promise<boolean>;
+    /** Network seam; defaults to the public-HTTPS-only `postWebhook`. */
+    post?: WebhookPost;
+    /** Trace source; defaults to the collector's most recent traces. */
+    recentTraces?: () => Promise<readonly QylTrace[]>;
+    pollIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    log?: (message: string) => void;
+}
+/**
+ * One per process: owns the subscription store, the verification cache and the
+ * poller. `register` wires the three methods into each per-request McpServer.
+ */
+export declare class EventsRuntime {
+    private readonly store;
+    private readonly isAuthorized;
+    private readonly post;
+    private readonly recentTraces;
+    private readonly pollIntervalMs;
+    private readonly now;
+    private readonly sleep;
+    private readonly log;
+    private readonly verified;
+    private seen;
+    private ready;
+    private timer;
+    private polling;
+    private stopped;
+    private readonly deliveries;
+    constructor(options: EventsRuntimeOptions);
+    /** Advertise `events` and answer the three methods on this server instance. */
+    register(server: McpServer): void;
+    list(): {
+        events: (typeof TRACE_ERROR_EVENT)[];
+    };
+    subscribe(params: SubscribeParams, principal: Principal): Promise<{
+        id: string;
+        refreshBefore: string;
+        cursor: null;
+        truncated: false;
+    }>;
+    unsubscribe(params: UnsubscribeParams, principal: Principal): Promise<Record<string, never>>;
+    /** A refresh always passes; a new subscription needs a free slot for its caller. */
+    private assertCapacity;
+    /**
+     * A signed, single-use challenge before any application data; a success is
+     * cached per principal and callback URL for a bounded period.
+     */
+    private verifyCallback;
+    /** Loads the store once; every store access waits for it. */
+    private initialized;
+    /** Start the poller if a live subscription exists; `stop` ends it. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private ensurePolling;
+    private isLive;
+    private pruneState;
+    private authorized;
+    /** One poll: drop lapsed subscriptions, then deliver each new error trace. */
+    poll(): Promise<void>;
+    private pollOnce;
+    private deliver;
+    /** POST one signed event, retrying transient failures with backoff. */
+    private deliverWhileActive;
+}
+export {};