@adminforth/mcp 1.1.0 → 1.1.1

package/dist/inputSchema.js

@@ -0,0 +1,63 @@
+// Endpoint request schemas are written for OpenAPI docs. MCP clients keep tool schemas in the model context,
+// so annotations that do not help to build a call and definitions the tool never references are dropped.
+const DOCUMENTATION_ONLY_KEYWORDS = new Set(['title', 'examples']);
+// Keywords whose value maps names to subschemas: their keys are names, not keywords.
+const SUBSCHEMA_MAP_KEYWORDS = new Set(['properties', 'patternProperties', '$defs']);
+// Keywords whose value is data, not a schema.
+const DATA_KEYWORDS = new Set(['enum', 'const', 'default']);
+const DEFS_REF_PREFIX = '#/$defs/';
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function stripDocumentationKeywords(node) {
+    if (Array.isArray(node))
+        return node.map(stripDocumentationKeywords);
+    if (!isObject(node))
+        return node;
+    return Object.fromEntries(Object.entries(node)
+        .filter(([keyword]) => !DOCUMENTATION_ONLY_KEYWORDS.has(keyword))
+        .map(([keyword, value]) => {
+        if (DATA_KEYWORDS.has(keyword))
+            return [keyword, value];
+        if (SUBSCHEMA_MAP_KEYWORDS.has(keyword) && isObject(value)) {
+            return [keyword, Object.fromEntries(Object.entries(value).map(([name, subschema]) => [name, stripDocumentationKeywords(subschema)]))];
+        }
+        return [keyword, stripDocumentationKeywords(value)];
+    }));
+}
+function collectDefRefs(node, refs) {
+    if (Array.isArray(node)) {
+        node.forEach((item) => collectDefRefs(item, refs));
+        return;
+    }
+    if (!isObject(node))
+        return;
+    for (const [keyword, value] of Object.entries(node)) {
+        if (keyword === '$ref' && typeof value === 'string' && value.startsWith(DEFS_REF_PREFIX)) {
+            refs.add(value.slice(DEFS_REF_PREFIX.length));
+        }
+        else if (!DATA_KEYWORDS.has(keyword)) {
+            collectDefRefs(value, refs);
+        }
+    }
+}
+// Shared $defs are attached to every endpoint schema, even to endpoints that use only some of them.
+function pruneUnusedDefs(schema) {
+    const { $defs, ...rest } = schema;
+    if (!isObject($defs))
+        return schema;
+    const used = new Set();
+    const pending = new Set();
+    collectDefRefs(rest, pending);
+    for (const name of pending) {
+        if (used.has(name))
+            continue;
+        used.add(name);
+        collectDefRefs($defs[name], pending);
+    }
+    const usedDefs = Object.fromEntries(Object.entries($defs).filter(([name]) => used.has(name)));
+    return Object.keys(usedDefs).length > 0 ? { ...rest, $defs: usedDefs } : rest;
+}
+export function compactInputSchema(schema) {
+    return pruneUnusedDefs(stripDocumentationKeywords(schema));
+}

package/dist/keyedLock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs tasks with the same key one at a time, within this process. A key is kept only while a task with it runs
+ * or waits, so keys taken by many different callers do not pile up in memory.
+ */
+export declare class KeyedLock {
+    private readonly tails;
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}

package/dist/keyedLock.js

@@ -0,0 +1,20 @@
+/**
+ * Runs tasks with the same key one at a time, within this process. A key is kept only while a task with it runs
+ * or waits, so keys taken by many different callers do not pile up in memory.
+ */
+export class KeyedLock {
+    tails = new Map();
+    async run(key, task) {
+        const result = (this.tails.get(key) ?? Promise.resolve()).then(task);
+        // The next task with this key waits for this one even when it fails.
+        const tail = result.catch(() => { });
+        this.tails.set(key, tail);
+        try {
+            return await result;
+        }
+        finally {
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        }
+    }
+}

package/dist/mcpProtocol.d.ts

@@ -12,7 +12,7 @@ export interface McpServerPresentation {
     serverInfo: McpServerInfo;
     instructions: string;
 }
-export declare function createMcpServerPresentation(brandName: string, adminPanelOrigin?: string, baseUrl?: string, readOnly?: boolean): McpServerPresentation;
+export declare function createMcpServerPresentation(brandName: string, adminPanelUrl?: string, guidance?: string, readOnly?: boolean): McpServerPresentation;
 export interface McpProtocolContext {
     body: Record<string, any>;
     headers: Record<string, any>;

package/dist/mcpProtocol.js

@@ -1,3 +1,4 @@
+import YAML from 'yaml';
 export const MODERN_PROTOCOL_VERSION = '2026-07-28';
 export const LEGACY_PROTOCOL_VERSION = '2025-11-25';
 const LEGACY_PROTOCOL_VERSIONS = new Set([
@@ -8,10 +9,7 @@ const LEGACY_PROTOCOL_VERSIONS = new Set([
 const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
 const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
 const SERVER_INFO_META_KEY = 'io.modelcontextprotocol/serverInfo';
-export function createMcpServerPresentation(brandName, adminPanelOrigin, baseUrl = '', readOnly = false) {
-    const adminPanelUrl = adminPanelOrigin
-        ? new URL(baseUrl || '/', adminPanelOrigin).toString()
-        : undefined;
+export function createMcpServerPresentation(brandName, adminPanelUrl, guidance = '', readOnly = false) {
     const adminPanel = `AdminForth admin panel for "${brandName}"${adminPanelUrl ? ` at ${adminPanelUrl}` : ''}`;
     return {
         serverInfo: {
@@ -21,7 +19,10 @@ export function createMcpServerPresentation(brandName, adminPanelOrigin, baseUrl
             description: `${adminPanel}.`,
             ...(adminPanelUrl && { websiteUrl: adminPanelUrl }),
         },
-        instructions: `This is the ${adminPanel}. Use its tools to ${readOnly ? 'read' : 'read and update'} data allowed for the authenticated user.`,
+        instructions: [
+            `This is the ${adminPanel}. Use its tools to ${readOnly ? 'read' : 'read and update'} data allowed for the authenticated user.`,
+            guidance,
+        ].filter(Boolean).join('\n\n'),
     };
 }
 function errorResponse(id, code, message, status = 400) {
@@ -67,8 +68,9 @@ function validateModernHeaders(body, headers) {
     }
     return null;
 }
+// The JSON round trip drops functions and undefined values that handler responses may carry, which YAML cannot serialize.
 function serializeToolOutput(output) {
-    return typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+    return typeof output === 'string' ? output : YAML.stringify(JSON.parse(JSON.stringify(output ?? null)));
 }
 export async function handleMcpProtocol(context) {
     const { body, headers, serverInfo, instructions } = context;

package/dist/oauth.d.ts

@@ -0,0 +1,96 @@
+import type { AdminUser, IAdminForth } from 'adminforth';
+import type { McpAuthSecretStore } from './authSecretStore.js';
+import type { McpOAuthClient } from './types.js';
+import { type McpUrls } from './urls.js';
+/** Endpoint paths relative to the AdminForth API prefix (`<baseUrl>/adminapi/v1`). */
+export declare const OAUTH_PATHS: {
+    protectedResourceMetadata: string;
+    authorizationServerMetadata: string;
+    jwks: string;
+    authorize: string;
+    token: string;
+    authorization: string;
+};
+export declare const CONSENT_PAGE_PATH = "/mcp-authorize";
+interface AccessToken {
+    pk: string;
+    grantId: string;
+    aud: string;
+}
+/**
+ * OAuth 2.1 authorization server for the MCP endpoint: authorization code flow with PKCE for public clients
+ * identified by Client ID Metadata Documents. Authorization requests and codes are signed JWTs, so only the
+ * resulting grants are stored, as records of the auth secret resource.
+ */
+export declare class McpOAuth {
+    private readonly adminforth;
+    private readonly store;
+    private readonly serverReadOnly;
+    readonly mcpUrl: string;
+    readonly resourceMetadataUrl: string;
+    private readonly issuer;
+    private readonly apiUrl;
+    private readonly consentPageUrl;
+    private readonly configuredClients;
+    private readonly fetchedClients;
+    /**
+     * `configuredClients` are trusted as is, without fetching their client metadata documents. `serverReadOnly` is
+     * the plugin readOnly option: it makes every connection read-only, whatever the user chooses on the consent page.
+     */
+    constructor(adminforth: IAdminForth, store: McpAuthSecretStore, urls: McpUrls, configuredClients?: McpOAuthClient[], serverReadOnly?: boolean);
+    protectedResourceMetadata(): {
+        resource: string;
+        authorization_servers: string[];
+        bearer_methods_supported: string[];
+    };
+    authorizationServerMetadata(): {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        response_types_supported: string[];
+        grant_types_supported: string[];
+        code_challenge_methods_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+        client_id_metadata_document_supported: boolean;
+        authorization_response_iss_parameter_supported: boolean;
+        jwks_uri: string;
+        subject_types_supported: string[];
+        id_token_signing_alg_values_supported: string[];
+    };
+    /**
+     * Validates the authorization request and returns the consent page URL to redirect the browser to.
+     * This endpoint needs no sign-in, so the client metadata document is fetched only once the user opens the
+     * consent page: otherwise anyone could make this server send requests to any URL passed as client_id.
+     */
+    authorize(query: Record<string, unknown>): Promise<string>;
+    /** What the consent page shows about a pending authorization request. */
+    describeAuthorization(signedRequest: string): Promise<{
+        clientName: string;
+        clientHost: string | null;
+        redirectHost: string;
+        loopbackRedirect: boolean;
+        serverReadOnly: boolean;
+    }>;
+    /**
+     * Approves or denies a pending authorization request and returns where to send the browser. `readOnly` is the
+     * choice of the user on the consent page; the connection is read-only with it or with the plugin readOnly option.
+     */
+    resolveAuthorization(signedRequest: string, approved: boolean, adminUser: AdminUser, readOnly?: boolean): Promise<string>;
+    exchangeToken(body: Record<string, unknown>): Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in: number;
+        refresh_token: string;
+    }>;
+    /** Returns the grant an OAuth access token was issued for, or null for an invalid, expired or foreign token. */
+    verifyAccessToken(token: string): Promise<AccessToken | null>;
+    private checkResource;
+    private verifyAuthorizationRequest;
+    /** The consent page loads the client to describe it and again to resolve the request, hence the cache. */
+    private lookUpClient;
+    private redeemAuthorizationCode;
+    private refreshAccessToken;
+    private issueRefreshToken;
+    private tokenResponse;
+}
+export {};

package/dist/oauth.js

@@ -0,0 +1,263 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { fetchClientMetadata, isAllowedRedirectUri, isClientIdUrl, isLoopbackUrl, redirectUriMatches, } from './oauthClientMetadata.js';
+import { OAuthError } from './oauthError.js';
+import { MCP_PATH } from './urls.js';
+const REQUEST_JWT_TYPE = 'mcp-oauth-request';
+const CODE_JWT_TYPE = 'mcp-oauth-code';
+const ACCESS_TOKEN_JWT_TYPE = 'mcp-oauth-access';
+const REFRESH_TOKEN_JWT_TYPE = 'mcp-oauth-refresh';
+const REQUEST_TTL = '10m';
+const CODE_TTL = '5m';
+const ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
+// Every refresh issues a new token, so a connection expires only after this long without use.
+const REFRESH_TOKEN_TTL = '7d';
+const CLIENT_METADATA_TTL_MS = 10 * 60 * 1000;
+/** Endpoint paths relative to the AdminForth API prefix (`<baseUrl>/adminapi/v1`). */
+export const OAUTH_PATHS = {
+    protectedResourceMetadata: `${MCP_PATH}/oauth-protected-resource`,
+    // Clients derive authorization server metadata URL from the issuer; for an issuer with a path, the
+    // OpenID Connect Discovery form `<issuer>/.well-known/openid-configuration` is the only one not at the host root,
+    // so it works behind a proxy that forwards only the AdminForth path. The host-root forms are in oauthEndpoints.ts.
+    authorizationServerMetadata: `${MCP_PATH}/.well-known/openid-configuration`,
+    jwks: `${MCP_PATH}/oauth/jwks`,
+    authorize: `${MCP_PATH}/oauth/authorize`,
+    token: `${MCP_PATH}/oauth/token`,
+    authorization: `${MCP_PATH}/oauth/authorization`,
+};
+export const CONSENT_PAGE_PATH = '/mcp-authorize';
+function requireParams(params, names) {
+    const missing = names.filter((name) => typeof params[name] !== 'string' || !params[name]);
+    if (missing.length) {
+        throw new OAuthError('invalid_request', `Missing or invalid parameters: ${missing.join(', ')}`);
+    }
+    return params;
+}
+function pkceChallenge(codeVerifier) {
+    return createHash('sha256').update(codeVerifier).digest('base64url');
+}
+/**
+ * OAuth 2.1 authorization server for the MCP endpoint: authorization code flow with PKCE for public clients
+ * identified by Client ID Metadata Documents. Authorization requests and codes are signed JWTs, so only the
+ * resulting grants are stored, as records of the auth secret resource.
+ */
+export class McpOAuth {
+    adminforth;
+    store;
+    serverReadOnly;
+    mcpUrl;
+    resourceMetadataUrl;
+    issuer;
+    apiUrl;
+    consentPageUrl;
+    configuredClients;
+    fetchedClients = new Map();
+    /**
+     * `configuredClients` are trusted as is, without fetching their client metadata documents. `serverReadOnly` is
+     * the plugin readOnly option: it makes every connection read-only, whatever the user chooses on the consent page.
+     */
+    constructor(adminforth, store, urls, configuredClients = [], serverReadOnly = false) {
+        this.adminforth = adminforth;
+        this.store = store;
+        this.serverReadOnly = serverReadOnly;
+        this.configuredClients = new Map(configuredClients.map((client) => [client.clientId, client]));
+        this.apiUrl = urls.apiUrl;
+        this.mcpUrl = urls.mcpUrl;
+        this.issuer = this.mcpUrl;
+        this.resourceMetadataUrl = `${this.apiUrl}${OAUTH_PATHS.protectedResourceMetadata}`;
+        this.consentPageUrl = new URL(`${adminforth.config.baseUrl}${CONSENT_PAGE_PATH}`, this.apiUrl).href;
+    }
+    protectedResourceMetadata() {
+        return {
+            resource: this.mcpUrl,
+            authorization_servers: [this.issuer],
+            bearer_methods_supported: ['header'],
+        };
+    }
+    authorizationServerMetadata() {
+        return {
+            issuer: this.issuer,
+            authorization_endpoint: `${this.apiUrl}${OAUTH_PATHS.authorize}`,
+            token_endpoint: `${this.apiUrl}${OAUTH_PATHS.token}`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            code_challenge_methods_supported: ['S256'],
+            token_endpoint_auth_methods_supported: ['none'],
+            client_id_metadata_document_supported: true,
+            authorization_response_iss_parameter_supported: true,
+            // Required by OpenID Connect Discovery, which clients validate this document against. No ID tokens are
+            // issued, so the key set is empty.
+            jwks_uri: `${this.apiUrl}${OAUTH_PATHS.jwks}`,
+            subject_types_supported: ['public'],
+            id_token_signing_alg_values_supported: ['RS256'],
+        };
+    }
+    /**
+     * Validates the authorization request and returns the consent page URL to redirect the browser to.
+     * This endpoint needs no sign-in, so the client metadata document is fetched only once the user opens the
+     * consent page: otherwise anyone could make this server send requests to any URL passed as client_id.
+     */
+    async authorize(query) {
+        const params = requireParams(query, [
+            'response_type', 'client_id', 'redirect_uri', 'code_challenge', 'code_challenge_method',
+        ]);
+        if (params.response_type !== 'code') {
+            throw new OAuthError('unsupported_response_type', 'Only response_type=code is supported');
+        }
+        if (params.code_challenge_method !== 'S256') {
+            throw new OAuthError('invalid_request', 'Only code_challenge_method=S256 is supported');
+        }
+        this.checkResource(query.resource);
+        const redirectUrl = URL.parse(params.redirect_uri);
+        if (!redirectUrl || !isAllowedRedirectUri(redirectUrl)) {
+            throw new OAuthError('invalid_request', 'redirect_uri must use https unless it points to localhost');
+        }
+        if (!this.configuredClients.has(params.client_id) && !isClientIdUrl(params.client_id)) {
+            throw new OAuthError('invalid_client', 'client_id must be the https URL of a client metadata document');
+        }
+        const request = {
+            clientId: params.client_id,
+            redirectUri: params.redirect_uri,
+            codeChallenge: params.code_challenge,
+            state: typeof query.state === 'string' ? query.state : undefined,
+        };
+        const signedRequest = this.adminforth.auth.issueJWT(request, REQUEST_JWT_TYPE, REQUEST_TTL);
+        return `${this.consentPageUrl}?request=${encodeURIComponent(signedRequest)}`;
+    }
+    /** What the consent page shows about a pending authorization request. */
+    async describeAuthorization(signedRequest) {
+        const { request, client, redirectUrl } = await this.verifyAuthorizationRequest(signedRequest);
+        return {
+            clientName: client.clientName,
+            // Null for a configured client whose client_id is not a metadata document URL.
+            clientHost: URL.parse(request.clientId)?.host ?? null,
+            redirectHost: redirectUrl.host,
+            loopbackRedirect: isLoopbackUrl(redirectUrl),
+            serverReadOnly: this.serverReadOnly,
+        };
+    }
+    /**
+     * Approves or denies a pending authorization request and returns where to send the browser. `readOnly` is the
+     * choice of the user on the consent page; the connection is read-only with it or with the plugin readOnly option.
+     */
+    async resolveAuthorization(signedRequest, approved, adminUser, readOnly = false) {
+        // Denying redirects too, so the redirect_uri is checked against the client metadata either way.
+        const { request, client, redirectUrl: url } = await this.verifyAuthorizationRequest(signedRequest);
+        if (approved) {
+            const code = {
+                jti: randomUUID(),
+                pk: adminUser.pk,
+                clientId: request.clientId,
+                clientName: client.clientName,
+                redirectUri: request.redirectUri,
+                codeChallenge: request.codeChallenge,
+                readOnly: this.serverReadOnly || readOnly,
+            };
+            url.searchParams.set('code', this.adminforth.auth.issueJWT(code, CODE_JWT_TYPE, CODE_TTL));
+        }
+        else {
+            url.searchParams.set('error', 'access_denied');
+        }
+        if (request.state !== undefined) {
+            url.searchParams.set('state', request.state);
+        }
+        url.searchParams.set('iss', this.issuer);
+        return url.href;
+    }
+    async exchangeToken(body) {
+        if (body.grant_type === 'authorization_code')
+            return this.redeemAuthorizationCode(body);
+        if (body.grant_type === 'refresh_token')
+            return this.refreshAccessToken(body);
+        throw new OAuthError('unsupported_grant_type', 'Only authorization_code and refresh_token grants are supported');
+    }
+    /** Returns the grant an OAuth access token was issued for, or null for an invalid, expired or foreign token. */
+    async verifyAccessToken(token) {
+        const accessToken = await this.adminforth.auth.verify(token, ACCESS_TOKEN_JWT_TYPE, false);
+        return accessToken?.aud === this.mcpUrl ? accessToken : null;
+    }
+    checkResource(resource) {
+        if (resource !== undefined && resource !== this.mcpUrl) {
+            throw new OAuthError('invalid_target', `resource must be ${this.mcpUrl}`);
+        }
+    }
+    async verifyAuthorizationRequest(signedRequest) {
+        const request = await this.adminforth.auth.verify(signedRequest, REQUEST_JWT_TYPE, false);
+        if (!request) {
+            throw new OAuthError('invalid_request', 'Authorization request is invalid or expired, start connecting again');
+        }
+        const client = await this.lookUpClient(request.clientId);
+        const redirectUrl = new URL(request.redirectUri);
+        if (!client.redirectUris.some((registered) => redirectUriMatches(redirectUrl, registered))) {
+            throw new OAuthError('invalid_request', 'redirect_uri is not listed in the client metadata document');
+        }
+        return { request, client, redirectUrl };
+    }
+    /** The consent page loads the client to describe it and again to resolve the request, hence the cache. */
+    async lookUpClient(clientId) {
+        const configured = this.configuredClients.get(clientId);
+        if (configured)
+            return configured;
+        const cached = this.fetchedClients.get(clientId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.client;
+        const client = await fetchClientMetadata(clientId);
+        this.fetchedClients.set(clientId, { client, expiresAt: Date.now() + CLIENT_METADATA_TTL_MS });
+        return client;
+    }
+    async redeemAuthorizationCode(body) {
+        const params = requireParams(body, ['code', 'code_verifier', 'client_id', 'redirect_uri']);
+        this.checkResource(body.resource);
+        const code = await this.adminforth.auth.verify(params.code, CODE_JWT_TYPE, false);
+        if (!code) {
+            throw new OAuthError('invalid_grant', 'Authorization code is invalid or expired');
+        }
+        if (code.clientId !== params.client_id || code.redirectUri !== params.redirect_uri) {
+            throw new OAuthError('invalid_grant', 'Authorization code was issued for another client_id or redirect_uri');
+        }
+        if (pkceChallenge(params.code_verifier) !== code.codeChallenge) {
+            throw new OAuthError('invalid_grant', 'code_verifier does not match the code challenge');
+        }
+        const refreshToken = this.issueRefreshToken(code.jti);
+        const result = await this.store.createOAuthGrant({
+            id: code.jti,
+            userId: code.pk,
+            clientId: code.clientId,
+            clientName: code.clientName,
+            readOnly: code.readOnly,
+        }, refreshToken);
+        if (result.error) {
+            throw new OAuthError('invalid_grant', result.error);
+        }
+        return this.tokenResponse(code.pk, code.jti, refreshToken);
+    }
+    async refreshAccessToken(body) {
+        const params = requireParams(body, ['refresh_token', 'client_id']);
+        this.checkResource(body.resource);
+        // The signature tells a token this server issued from a made-up one: a made-up token knowing a grant id must
+        // not revoke that grant, and anonymous callers must not reach the store or its lock.
+        const presented = await this.adminforth.auth.verify(params.refresh_token, REFRESH_TOKEN_JWT_TYPE, false);
+        if (!presented) {
+            throw new OAuthError('invalid_grant', 'Refresh token is invalid or expired');
+        }
+        const { grantId } = presented;
+        const refreshToken = this.issueRefreshToken(grantId);
+        const userId = await this.store.rotateRefreshToken(grantId, params.refresh_token, params.client_id, refreshToken);
+        if (!userId) {
+            throw new OAuthError('invalid_grant', 'Refresh token was already used or its connection was revoked');
+        }
+        return this.tokenResponse(userId, grantId, refreshToken);
+    }
+    issueRefreshToken(grantId) {
+        const token = { grantId, nonce: randomBytes(16).toString('base64url') };
+        return this.adminforth.auth.issueJWT(token, REFRESH_TOKEN_JWT_TYPE, REFRESH_TOKEN_TTL);
+    }
+    tokenResponse(pk, grantId, refreshToken) {
+        const accessToken = { pk, grantId, aud: this.mcpUrl };
+        return {
+            access_token: this.adminforth.auth.issueJWT(accessToken, ACCESS_TOKEN_JWT_TYPE, ACCESS_TOKEN_TTL_SECONDS),
+            token_type: 'Bearer',
+            expires_in: ACCESS_TOKEN_TTL_SECONDS,
+            refresh_token: refreshToken,
+        };
+    }
+}

package/dist/oauthClientMetadata.d.ts

@@ -0,0 +1,13 @@
+import type { McpOAuthClient } from './types.js';
+/** BlockList matches IPv4-mapped IPv6 addresses (::ffff:10.0.0.5) against the IPv4 ranges by itself. */
+export declare function isSpecialPurposeAddress(address: string, family: number): boolean;
+export declare function isClientIdUrl(clientId: string): boolean;
+export declare function isLoopbackUrl(url: URL): boolean;
+/** Native clients listen on a random loopback port, so RFC 8252 lets the port differ from the registered one. */
+export declare function redirectUriMatches(requested: URL, registered: string): boolean;
+export declare function isAllowedRedirectUri(redirectUri: URL): boolean;
+/**
+ * Resolves an MCP client by its Client ID Metadata Document, the client_id being the document URL
+ * that passed isClientIdUrl.
+ */
+export declare function fetchClientMetadata(clientId: string): Promise<McpOAuthClient>;

package/dist/oauthClientMetadata.js

@@ -0,0 +1,140 @@
+import dns from 'node:dns';
+import https from 'node:https';
+import net from 'node:net';
+import { logger } from 'adminforth';
+import { OAuthError } from './oauthError.js';
+const MAX_DOCUMENT_BYTES = 5 * 1024;
+const FETCH_TIMEOUT_MS = 5000;
+// client_name is shown on the consent page and stored as the connection name.
+const MAX_CLIENT_NAME_LENGTH = 100;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+const specialPurposeAddresses = new net.BlockList();
+[
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
+    ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24],
+    ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+    ['224.0.0.0', 4], ['240.0.0.0', 4],
+].forEach(([network, prefix]) => specialPurposeAddresses.addSubnet(network, prefix, 'ipv4'));
+[
+    ['::', 128], ['::1', 128], ['64:ff9b::', 96], ['100::', 64], ['2001::', 23], ['2001:db8::', 32],
+    ['2002::', 16], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8],
+].forEach(([network, prefix]) => specialPurposeAddresses.addSubnet(network, prefix, 'ipv6'));
+/** BlockList matches IPv4-mapped IPv6 addresses (::ffff:10.0.0.5) against the IPv4 ranges by itself. */
+export function isSpecialPurposeAddress(address, family) {
+    return specialPurposeAddresses.check(address, family === 6 ? 'ipv6' : 'ipv4');
+}
+/**
+ * client_id is an attacker-chosen URL, so the fetch refuses hosts resolving to private, loopback and other
+ * special-purpose addresses. Checking in the socket lookup, not before the request, closes DNS rebinding.
+ */
+const lookupPublicAddress = (hostname, options, callback) => {
+    dns.lookup(hostname, { ...options, all: true }, (error, addresses) => {
+        if (error) {
+            callback(error, []);
+            return;
+        }
+        const specialAddress = addresses.find(({ address, family }) => isSpecialPurposeAddress(address, family));
+        if (specialAddress) {
+            callback(new Error(`${hostname} resolves to special-purpose address ${specialAddress.address}`), []);
+            return;
+        }
+        if (options.all) {
+            callback(null, addresses);
+        }
+        else {
+            callback(null, addresses[0].address, addresses[0].family);
+        }
+    });
+};
+export function isClientIdUrl(clientId) {
+    const url = URL.parse(clientId);
+    return url?.protocol === 'https:'
+        && url.href === clientId
+        && !url.username
+        && !url.password
+        && url.pathname !== '/'
+        && !url.hash
+        && !net.isIP(url.hostname)
+        && !url.hostname.startsWith('[');
+}
+export function isLoopbackUrl(url) {
+    return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
+}
+/** Native clients listen on a random loopback port, so RFC 8252 lets the port differ from the registered one. */
+export function redirectUriMatches(requested, registered) {
+    const registeredUrl = new URL(registered);
+    if (!isLoopbackUrl(registeredUrl))
+        return requested.href === registeredUrl.href;
+    return requested.protocol === registeredUrl.protocol
+        && requested.hostname === registeredUrl.hostname
+        && requested.pathname === registeredUrl.pathname
+        && requested.search === registeredUrl.search
+        && requested.hash === registeredUrl.hash;
+}
+export function isAllowedRedirectUri(redirectUri) {
+    return redirectUri.protocol === 'https:' || isLoopbackUrl(redirectUri);
+}
+function fetchJson(url) {
+    return new Promise((resolve, reject) => {
+        const request = https.get(url, {
+            lookup: lookupPublicAddress,
+            headers: { Accept: 'application/json' },
+        }, (response) => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                reject(new Error(`responded with HTTP ${response.statusCode}`));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_DOCUMENT_BYTES) {
+                    request.destroy(new Error(`document is larger than ${MAX_DOCUMENT_BYTES} bytes`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        // The `timeout` option of https.get fires only after a silent period, so a server sending a byte every few
+        // seconds would hold the request for hours. The deadline caps the whole request instead.
+        const deadline = setTimeout(() => request.destroy(new Error(`timed out after ${FETCH_TIMEOUT_MS} ms`)), FETCH_TIMEOUT_MS);
+        request.on('close', () => clearTimeout(deadline));
+        request.on('error', reject);
+    });
+}
+/**
+ * Resolves an MCP client by its Client ID Metadata Document, the client_id being the document URL
+ * that passed isClientIdUrl.
+ */
+export async function fetchClientMetadata(clientId) {
+    let document;
+    try {
+        document = await fetchJson(clientId);
+    }
+    catch (error) {
+        // The reason stays in the log: resolved addresses, HTTP statuses and parse errors quoting the response
+        // would tell whoever chose the client_id what this server can reach.
+        logger.warn(`AdminForthMcpPlugin: failed to fetch client metadata document ${clientId}: ${error.message}`);
+        throw new OAuthError('invalid_client', 'Could not fetch the client metadata document');
+    }
+    if (typeof document?.client_name !== 'string'
+        || !Array.isArray(document.redirect_uris)
+        || !document.redirect_uris.length
+        || !document.redirect_uris.every((uri) => typeof uri === 'string' && URL.canParse(uri))
+        || document.token_endpoint_auth_method !== 'none') {
+        throw new OAuthError('invalid_client', 'Client metadata document must have client_name, redirect_uris and token_endpoint_auth_method "none"');
+    }
+    if (document.client_id !== clientId) {
+        throw new OAuthError('invalid_client', 'client_id in the client metadata document does not match its URL');
+    }
+    return { clientId, clientName: document.client_name.slice(0, MAX_CLIENT_NAME_LENGTH), redirectUris: document.redirect_uris };
+}

package/dist/oauthEndpoints.d.ts

@@ -0,0 +1,3 @@
+import { type IHttpServer } from 'adminforth';
+import { type McpOAuth } from './oauth.js';
+export declare function setupOAuthEndpoints(server: IHttpServer, oauth: McpOAuth, apiPrefix: string): void;