@adminforth/mcp 1.0.4 → 1.1.1

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;

package/dist/oauthEndpoints.js

@@ -0,0 +1,126 @@
+import { logger } from 'adminforth';
+import { OAUTH_PATHS } from './oauth.js';
+import { OAuthError } from './oauthError.js';
+import { MCP_PATH } from './urls.js';
+const MAX_FORM_BODY_BYTES = 16 * 1024;
+/**
+ * RFC 6749 token requests are application/x-www-form-urlencoded. The host app may already have parsed the body
+ * with its own urlencoded middleware; otherwise the stream is still unread.
+ */
+async function readFormBody(req) {
+    if (req.body && typeof req.body === 'object' && Object.keys(req.body).length) {
+        return req.body;
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_FORM_BODY_BYTES) {
+            throw new OAuthError('invalid_request', `Request body is larger than ${MAX_FORM_BODY_BYTES} bytes`);
+        }
+        chunks.push(chunk);
+    }
+    return Object.fromEntries(new URLSearchParams(Buffer.concat(chunks).toString('utf8')));
+}
+async function oauthResponse(input, handler) {
+    try {
+        const result = await handler();
+        // A handler that answered through the raw response returns null; headers can no longer be set then.
+        if (result !== null)
+            input.response.setHeader('Cache-Control', 'no-store');
+        return result;
+    }
+    catch (error) {
+        if (!(error instanceof OAuthError))
+            throw error;
+        input.response.setHeader('Cache-Control', 'no-store');
+        input.response.setStatus(400);
+        return error.toResponseObject();
+    }
+}
+export function setupOAuthEndpoints(server, oauth, apiPrefix) {
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.protectedResourceMetadata,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => oauth.protectedResourceMetadata(),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorizationServerMetadata,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => oauth.authorizationServerMetadata(),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.jwks,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => ({ keys: [] }),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorize,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async (input) => oauthResponse(input, async () => {
+            const consentPageUrl = await oauth.authorize(input.query);
+            input._raw_express_res.set('Cache-Control', 'no-store').redirect(302, consentPageUrl);
+            return null;
+        }),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorization,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        handler: async (input) => oauthResponse(input, () => oauth.describeAuthorization(String(input.query.request))),
+    });
+    server.endpoint({
+        method: 'POST',
+        path: OAUTH_PATHS.authorization,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        handler: async (input) => oauthResponse(input, async () => ({
+            redirectUrl: await oauth.resolveAuthorization(String(input.body.request), input.body.approved === true, input.adminUser, input.body.readOnly === true),
+        })),
+    });
+    const { expressApp } = server;
+    // MCP clients try the host-root well-known URLs first and stop at the first 200 response. The AdminForth SPA
+    // answers every unknown path with 200 HTML, so unless these are served the client fails before it reaches
+    // `<issuer>/.well-known/openid-configuration`. Behind a proxy that forwards only the AdminForth path they 404,
+    // and the client goes on to that URL.
+    const mcpPath = `${apiPrefix}${MCP_PATH}`;
+    expressApp.get(`/.well-known/oauth-protected-resource${mcpPath}`, async (_req, res) => {
+        res.json(oauth.protectedResourceMetadata());
+    });
+    expressApp.get(`/.well-known/oauth-authorization-server${mcpPath}`, async (_req, res) => {
+        res.json(oauth.authorizationServerMetadata());
+    });
+    expressApp.post(`${apiPrefix}${OAUTH_PATHS.token}`, async (req, res) => {
+        res.set('Cache-Control', 'no-store');
+        try {
+            res.json(await oauth.exchangeToken(await readFormBody(req)));
+        }
+        catch (error) {
+            if (error instanceof OAuthError) {
+                res.status(400).json(error.toResponseObject());
+                return;
+            }
+            logger.error(`AdminForthMcpPlugin: OAuth token request failed: ${error.stack ?? String(error)}`);
+            res.status(500).json({ error: 'server_error', error_description: 'Internal server error' });
+        }
+    });
+}

package/dist/oauthError.d.ts

@@ -0,0 +1,9 @@
+/** OAuth error answered as RFC 6749 `{ error, error_description }` with HTTP 400. */
+export declare class OAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, description: string);
+    toResponseObject(): {
+        error: string;
+        error_description: string;
+    };
+}

package/dist/oauthError.js

@@ -0,0 +1,11 @@
+/** OAuth error answered as RFC 6749 `{ error, error_description }` with HTTP 400. */
+export class OAuthError extends Error {
+    code;
+    constructor(code, description) {
+        super(description);
+        this.code = code;
+    }
+    toResponseObject() {
+        return { error: this.code, error_description: this.message };
+    }
+}

package/dist/skills.d.ts

@@ -0,0 +1,19 @@
+import type { McpToolDefinition } from './apiTools.js';
+export declare const FETCH_SKILL_TOOL_NAME = "fetch_skill";
+type TemplateValues = Record<string, string | number>;
+/**
+ * Guidance for MCP clients, kept as Markdown in the plugin `custom` folder: `instructions.md` holds the rules every
+ * client gets in the server instructions, `skills/<name>/SKILL.md` the detailed rules clients load with fetch_skill.
+ */
+export declare class McpSkills {
+    private readonly instructions;
+    private readonly skills;
+    constructor(customFolderPath: string, values: TemplateValues);
+    serverInstructions(): string;
+    toolDefinition(): McpToolDefinition;
+    call(args: Record<string, unknown> | undefined): {
+        output: unknown;
+        isError: boolean;
+    };
+}
+export {};

package/dist/skills.js

@@ -0,0 +1,79 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+export const FETCH_SKILL_TOOL_NAME = 'fetch_skill';
+const INSTRUCTIONS_FILE_NAME = 'instructions.md';
+const SKILLS_DIR_NAME = 'skills';
+const SKILL_FILE_NAME = 'SKILL.md';
+// SKILL.md starts with YAML frontmatter between two --- lines, the rest is the skill body.
+const SKILL_FILE_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+// Placeholders like {{pageSize.max}} in instructions and skills are filled from plugin options.
+const TEMPLATE_PLACEHOLDER_RE = /\{\{\s*([\w.]+)\s*\}\}/g;
+function renderTemplate(template, values, source) {
+    return template.replace(TEMPLATE_PLACEHOLDER_RE, (_, key) => {
+        if (!(key in values)) {
+            throw new Error(`AdminForthMcpPlugin: unknown placeholder {{${key}}} in ${source}`);
+        }
+        return String(values[key]);
+    });
+}
+function readSkill(skillsDir, directoryName, values) {
+    const file = join(skillsDir, directoryName, SKILL_FILE_NAME);
+    const [, frontmatter, body] = readFileSync(file, 'utf8').match(SKILL_FILE_RE);
+    const metadata = YAML.parse(frontmatter);
+    return {
+        name: metadata.name,
+        description: renderTemplate(metadata.description, values, file),
+        instructions: renderTemplate(body.trim(), values, file),
+    };
+}
+/**
+ * Guidance for MCP clients, kept as Markdown in the plugin `custom` folder: `instructions.md` holds the rules every
+ * client gets in the server instructions, `skills/<name>/SKILL.md` the detailed rules clients load with fetch_skill.
+ */
+export class McpSkills {
+    instructions;
+    skills;
+    constructor(customFolderPath, values) {
+        const instructionsFile = join(customFolderPath, INSTRUCTIONS_FILE_NAME);
+        this.instructions = renderTemplate(readFileSync(instructionsFile, 'utf8').trim(), values, instructionsFile);
+        const skillsDir = join(customFolderPath, SKILLS_DIR_NAME);
+        this.skills = new Map(readdirSync(skillsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => readSkill(skillsDir, entry.name, values))
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((skill) => [skill.name, skill]));
+    }
+    serverInstructions() {
+        const skillList = Array.from(this.skills.values())
+            .map((skill) => `- ${skill.name}: ${skill.description}`)
+            .join('\n');
+        return [
+            this.instructions,
+            `Before a task, load the matching skill with ${FETCH_SKILL_TOOL_NAME}; it has the detailed rules:\n${skillList}`,
+        ].join('\n\n');
+    }
+    toolDefinition() {
+        return {
+            name: FETCH_SKILL_TOOL_NAME,
+            description: `Returns the detailed rules of a skill for working with this admin panel. Load the matching skill before the task. Skills: ${Array.from(this.skills.keys()).join(', ')}.`,
+            inputSchema: {
+                type: 'object',
+                required: ['skillName'],
+                properties: {
+                    skillName: { type: 'string', enum: Array.from(this.skills.keys()) },
+                },
+            },
+        };
+    }
+    call(args) {
+        const skill = this.skills.get(String(args?.skillName));
+        if (!skill) {
+            return {
+                output: { error: `Unknown skill: ${args?.skillName}`, skills: Array.from(this.skills.keys()) },
+                isError: true,
+            };
+        }
+        return { output: skill.instructions, isError: false };
+    }
+}