toolcraft 0.0.141 → 0.0.143

package/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.141",
+      "version": "0.0.143",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.141",
+      "version": "0.0.143",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.141",
+      "version": "0.0.143",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.141",
+      "version": "0.0.143",
       "license": "MIT"
     },
     {

package/dist/http-hosted-oauth.compile-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http-hosted-oauth.compile-check.js

@@ -0,0 +1,54 @@
+import { hostedOAuth } from "./http-hosted-oauth.js";
+const ignoredHostedOAuth = hostedOAuth({
+    publicUrl: "https://calendar.example/mcp",
+    storage: ignoredStorage,
+    provider: {
+        name: "Skylight",
+        login: { fields: ["email", "password"] },
+        async connect({ email, password, signal }) {
+            const ignoredEmail = email;
+            const ignoredPassword = password;
+            const ignoredSignal = signal;
+            return {
+                accountId: ignoredEmail,
+                credential: `${ignoredPassword}:${ignoredSignal.aborted}`
+            };
+        },
+        services({ credentials, identity }) {
+            const ignoredSubject = identity.subject;
+            const ignoredClientId = identity.clientId;
+            const ignoredScopes = identity.scopes;
+            const ignoredResource = identity.resource;
+            const ignoredIssuer = identity.issuer;
+            void ignoredSubject;
+            void ignoredClientId;
+            void ignoredScopes;
+            void ignoredResource;
+            void ignoredIssuer;
+            return { skylight: { credential: () => credentials.read() } };
+        }
+    }
+});
+void ignoredHostedOAuth;
+const ignoredRedirectHostedOAuth = hostedOAuth({
+    publicUrl: "https://calendar.example/mcp",
+    storage: ignoredStorage,
+    provider: {
+        name: "Skylight",
+        services: ({ credentials }) => ({
+            skylight: { credential: () => credentials.read() }
+        })
+    },
+    advanced: {
+        interaction: {
+            paths: ["/oauth/skylight/callback"],
+            start: () => Response.redirect("https://login.example/authorize"),
+            handle: async ({ complete }) => complete({
+                transactionId: "transaction-id",
+                accountId: "account-id",
+                credential: "provider-session"
+            })
+        }
+    }
+});
+void ignoredRedirectHostedOAuth;

package/dist/http-hosted-oauth.d.ts

@@ -0,0 +1,121 @@
+import { type JWK } from "jose";
+import { type AuthorizationServerStore, type AuthorizationTransactionRecord, type OAuthAuthorizationServerSigningKey } from "mcp-oauth-server";
+import type { HttpAdditionalRequestHandler, TinyHttpMcpServerOAuthOptions } from "tiny-http-mcp-server/server";
+export type HostedOAuthLoginFieldName = "email" | "password" | "apiKey" | (string & {});
+export interface HostedOAuthLoginField {
+    name: HostedOAuthLoginFieldName;
+    label?: string;
+    type?: "text" | "email" | "password";
+}
+export interface HostedOAuthCredentialStore<TCredential = unknown> {
+    get(subject: string): Promise<TCredential | undefined>;
+    set(subject: string, credential: TCredential): Promise<void>;
+    delete(subject: string): Promise<void>;
+    update(subject: string, update: (credential: TCredential) => Promise<TCredential> | TCredential): Promise<TCredential>;
+}
+export interface HostedOAuthStorageCapabilities {
+    durable: boolean;
+    encryptedCredentials: boolean;
+    stableKeys: boolean;
+    shared: boolean;
+}
+export interface HostedOAuthInteractionStore {
+    set(transaction: AuthorizationTransactionRecord): Promise<void>;
+    get(transactionId: string): Promise<AuthorizationTransactionRecord | undefined>;
+    delete(transactionId: string): Promise<void>;
+}
+export interface HostedOAuthStorage<TCredential = unknown> {
+    authorizationServer: AuthorizationServerStore;
+    interactions: HostedOAuthInteractionStore;
+    credentials: HostedOAuthCredentialStore<TCredential>;
+    capabilities: HostedOAuthStorageCapabilities;
+    signingKey(): Promise<OAuthAuthorizationServerSigningKey>;
+    resolveSubject(providerName: string, accountId: string): Promise<string>;
+    cleanup?(now?: number): Promise<void>;
+}
+export interface HostedOAuthCredentialAccess<TCredential = unknown> {
+    read(): Promise<TCredential>;
+    update(update: (credential: TCredential) => Promise<TCredential> | TCredential): Promise<TCredential>;
+    delete(): Promise<void>;
+}
+export interface HostedOAuthIdentity {
+    issuer: string;
+    subject: string;
+    clientId: string;
+    scopes: readonly string[];
+    resource: string;
+}
+export interface HostedOAuthProvider<TCredential = unknown, TServices extends object = object> {
+    name: string;
+    login?: {
+        fields: readonly (HostedOAuthLoginFieldName | HostedOAuthLoginField)[];
+    };
+    connect?(fields: Readonly<Record<string, string>> & {
+        signal: AbortSignal;
+    }): Promise<{
+        accountId: string;
+        credential: TCredential;
+    }>;
+    services(input: {
+        credentials: HostedOAuthCredentialAccess<TCredential>;
+        identity: HostedOAuthIdentity;
+    }): Promise<Partial<TServices>> | Partial<TServices>;
+}
+export interface HostedOAuthInteractionAdapter<TCredential = unknown> {
+    paths: readonly string[];
+    start(context: {
+        request: Request;
+        transaction: AuthorizationTransactionRecord;
+    }): Promise<Response> | Response;
+    handle(context: {
+        request: Request;
+        complete(input: {
+            transactionId: string;
+            accountId: string;
+            credential: TCredential;
+        }): Promise<Response>;
+    }): Promise<Response> | Response;
+}
+export interface HostedOAuthAdvancedOptions<TCredential = unknown> {
+    scopes?: readonly string[];
+    branding?: {
+        title?: string;
+    };
+    accessTokenTtlSeconds?: number;
+    authorizationCodeTtlSeconds?: number;
+    authorizationTransactionTtlSeconds?: number;
+    refreshTokenTtlSeconds?: number;
+    additionalPublicJwks?: readonly JWK[];
+    interaction?: HostedOAuthInteractionAdapter<TCredential>;
+}
+export interface HostedOAuthOptions<TCredential = unknown, TServices extends object = object> {
+    publicUrl: string;
+    storage: HostedOAuthStorage<TCredential>;
+    provider: HostedOAuthProvider<TCredential, TServices>;
+    advanced?: HostedOAuthAdvancedOptions<TCredential>;
+}
+export interface PreparedHostedOAuth {
+    publicUrl: URL;
+    issuer: URL;
+    scopes: readonly string[];
+}
+export interface HostedOAuthConfiguration<TCredential = unknown, TServices extends object = object> extends HostedOAuthOptions<TCredential, TServices> {
+    readonly kind: "hosted";
+    prepare(options?: {
+        production?: boolean;
+    }): Promise<PreparedHostedOAuth>;
+}
+export declare function isHostedOAuthConfiguration(value: unknown): value is HostedOAuthConfiguration<unknown, object>;
+export declare function hostedOAuth<TCredential = unknown, TServices extends object = object>(options: HostedOAuthOptions<TCredential, TServices>): HostedOAuthConfiguration<TCredential, TServices>;
+export declare class HostedOAuthLoginError extends Error {
+    constructor(message: string);
+}
+export interface HostedOAuthRuntime<TServices extends object = object> {
+    mcpPath: string;
+    oauth: TinyHttpMcpServerOAuthOptions;
+    requestHandler: HttpAdditionalRequestHandler;
+    requestServices(identity: HostedOAuthIdentity): Promise<Partial<TServices>>;
+}
+export declare function createInMemoryHostedOAuthStorage<TCredential = unknown>(options: {
+    development: true;
+}): HostedOAuthStorage<TCredential>;

package/dist/http-hosted-oauth.js

@@ -0,0 +1,438 @@
+import { createHash, createHmac, generateKeyPairSync, randomBytes } from "node:crypto";
+import { exportJWK } from "jose";
+import { createAuthorizationInteractionSecurity, createInMemoryAuthorizationServerStore, createOAuthAuthorizationServer, verifyAuthorizationInteractionCsrf } from "mcp-oauth-server";
+export function isHostedOAuthConfiguration(value) {
+    return typeof value === "object" && value !== null && "kind" in value && value.kind === "hosted";
+}
+function normalizePublicUrl(value) {
+    const url = new URL(value);
+    if (url.hash.length > 0 || url.search.length > 0) {
+        throw new Error("hosted OAuth publicUrl must not contain a query or fragment.");
+    }
+    if (url.username.length > 0 || url.password.length > 0) {
+        throw new Error("hosted OAuth publicUrl must not contain credentials.");
+    }
+    if (url.pathname === "/" || url.pathname.endsWith("/")) {
+        throw new Error("hosted OAuth publicUrl must contain a non-root path without a trailing slash.");
+    }
+    return url;
+}
+function configurationErrors(config, production) {
+    const errors = [];
+    const scopes = config.advanced?.scopes ?? ["mcp", "offline_access"];
+    if (!scopes.includes("mcp"))
+        errors.push("scopes containing required mcp scope");
+    if (scopes.some((scope) => scope.length === 0 || scope.trim() !== scope || scope.includes(" "))) {
+        errors.push("valid space-free scope names");
+    }
+    if (production) {
+        if (normalizePublicUrl(config.publicUrl).protocol !== "https:")
+            errors.push("HTTPS publicUrl");
+        if (!config.storage.capabilities.durable)
+            errors.push("durable storage");
+        if (!config.storage.capabilities.encryptedCredentials)
+            errors.push("encrypted credentials");
+        if (!config.storage.capabilities.stableKeys)
+            errors.push("stable signing and subject keys");
+    }
+    return errors;
+}
+export function hostedOAuth(options) {
+    if (options.provider.name.trim().length === 0)
+        throw new Error("provider.name is required.");
+    if (options.advanced?.interaction === undefined &&
+        (options.provider.login === undefined || options.provider.connect === undefined)) {
+        throw new Error("provider.login and provider.connect are required without an advanced interaction.");
+    }
+    if (options.provider.login !== undefined && options.provider.login.fields.length === 0) {
+        throw new Error("provider.login.fields must contain at least one field.");
+    }
+    const fieldNames = (options.provider.login?.fields ?? []).map((field) => typeof field === "string" ? field : field.name);
+    if (new Set(fieldNames).size !== fieldNames.length ||
+        fieldNames.some((name) => name.length === 0 || name === "signal" || name === "csrf" || name === "transaction")) {
+        throw new Error("provider.login.fields must have unique, non-reserved names.");
+    }
+    if (options.advanced?.interaction !== undefined &&
+        (options.advanced.interaction.paths.length === 0 ||
+            new Set(options.advanced.interaction.paths).size !==
+                options.advanced.interaction.paths.length ||
+            options.advanced.interaction.paths.some((path) => !path.startsWith("/") ||
+                [
+                    "/healthz",
+                    "/oauth/connect",
+                    "/authorize",
+                    "/register",
+                    "/token",
+                    "/revoke",
+                    "/.well-known/oauth-authorization-server",
+                    "/.well-known/jwks.json",
+                    normalizePublicUrl(options.publicUrl).pathname
+                ].includes(path)))) {
+        throw new Error("advanced.interaction.paths must contain unique, non-reserved absolute paths.");
+    }
+    normalizePublicUrl(options.publicUrl);
+    return {
+        ...options,
+        kind: "hosted",
+        async prepare({ production = process.env.NODE_ENV === "production" } = {}) {
+            const errors = configurationErrors(this, production);
+            if (errors.length > 0) {
+                throw new Error(`Hosted OAuth configuration requires: ${errors.join(", ")}.`);
+            }
+            const publicUrl = normalizePublicUrl(this.publicUrl);
+            return {
+                publicUrl,
+                issuer: new URL(publicUrl.origin),
+                scopes: this.advanced?.scopes ?? ["mcp", "offline_access"]
+            };
+        }
+    };
+}
+export class HostedOAuthLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostedOAuthLoginError";
+    }
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function loginField(field) {
+    if (typeof field !== "string")
+        return field;
+    return {
+        name: field,
+        label: field === "apiKey" ? "API key" : `${field[0]?.toUpperCase() ?? ""}${field.slice(1)}`,
+        type: field === "password" || field === "apiKey" ? "password" : field === "email" ? "email" : "text"
+    };
+}
+function renderLogin(providerName, fields, transaction, csrfToken, error) {
+    const controls = fields
+        .map((field) => {
+        const name = escapeHtml(field.name);
+        return `<label>${escapeHtml(field.label ?? field.name)}<input name="${name}" type="${field.type ?? "text"}" required autocomplete="${field.type === "password" ? "current-password" : "off"}"></label>`;
+    })
+        .join("");
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Connect ${escapeHtml(providerName)}</title><style>body{font:16px system-ui;max-width:28rem;margin:10vh auto;padding:1rem;color:#171717}form{display:grid;gap:1rem}label{display:grid;gap:.35rem}input,button{font:inherit;padding:.7rem}button{cursor:pointer}${error === undefined ? "" : ".error{color:#b42318}"}</style></head><body><h1>Connect ${escapeHtml(providerName)}</h1>${error === undefined ? "" : `<p class="error">${escapeHtml(error)}</p>`}<form method="post" action="/oauth/connect"><input type="hidden" name="transaction" value="${escapeHtml(transaction.id)}"><input type="hidden" name="csrf" value="${escapeHtml(csrfToken)}">${controls}<button type="submit">Connect</button></form></body></html>`;
+}
+function loginContentSecurityPolicy(transaction) {
+    const callbackOrigin = new URL(transaction.redirectUri).origin;
+    return `default-src 'none'; style-src 'unsafe-inline'; form-action 'self' ${callbackOrigin}; base-uri 'none'; frame-ancestors 'none'`;
+}
+function interactionCookieName(transactionId) {
+    const suffix = createHash("sha256").update(transactionId).digest("base64url").slice(0, 22);
+    return `__Host-mcp_oauth_csrf_${suffix}`;
+}
+function writeWebResponse(response, webResponse) {
+    webResponse.headers.forEach((value, name) => response.setHeader(name, value));
+    response.statusCode = webResponse.status;
+    return webResponse.arrayBuffer().then((body) => {
+        response.end(Buffer.from(body));
+    });
+}
+async function readBody(request, maxBytes = 65_536) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > maxBytes)
+            throw new Error("Request body is too large.");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+function toWebRequest(request, issuer, body) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value !== undefined)
+            headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    return new Request(new URL(request.url ?? "/", issuer), {
+        method: request.method,
+        headers,
+        ...(body !== undefined && body.length > 0 ? { body: body.toString("utf8") } : {})
+    });
+}
+function credentialsFor(storage, subject) {
+    return {
+        async read() {
+            const credential = await storage.credentials.get(subject);
+            if (credential === undefined)
+                throw new Error("Provider credential is missing; reconnect required.");
+            return credential;
+        },
+        update: (update) => storage.credentials.update(subject, update),
+        delete: () => storage.credentials.delete(subject)
+    };
+}
+/** @internal */
+export async function prepareHostedOAuthRuntime(config) {
+    const prepared = await config.prepare();
+    const fields = (config.provider.login?.fields ?? []).map(loginField);
+    const customInteraction = config.advanced?.interaction;
+    const displayName = config.advanced?.branding?.title ?? config.provider.name;
+    const interaction = {
+        async start({ request, transaction }) {
+            await config.storage.interactions.set(transaction);
+            if (customInteraction !== undefined) {
+                return customInteraction.start({ request, transaction });
+            }
+            const security = createAuthorizationInteractionSecurity({
+                cookieName: interactionCookieName(transaction.id)
+            });
+            return new Response(renderLogin(displayName, fields, transaction, security.csrfToken), {
+                status: 200,
+                headers: {
+                    "content-type": "text/html; charset=utf-8",
+                    "content-security-policy": loginContentSecurityPolicy(transaction),
+                    "cache-control": "no-store",
+                    "referrer-policy": "no-referrer",
+                    "x-content-type-options": "nosniff",
+                    "set-cookie": security.setCookie
+                }
+            });
+        }
+    };
+    await config.storage.cleanup?.();
+    const authorizationServer = createOAuthAuthorizationServer({
+        issuer: prepared.issuer.href,
+        resources: [prepared.publicUrl.href],
+        scopesSupported: prepared.scopes,
+        defaultScopes: prepared.scopes,
+        signingKey: await config.storage.signingKey(),
+        additionalPublicJwks: config.advanced?.additionalPublicJwks,
+        store: config.storage.authorizationServer,
+        interaction,
+        accessTokenTtlSeconds: config.advanced?.accessTokenTtlSeconds,
+        authorizationCodeTtlSeconds: config.advanced?.authorizationCodeTtlSeconds,
+        authorizationTransactionTtlSeconds: config.advanced?.authorizationTransactionTtlSeconds,
+        refreshTokenTtlSeconds: config.advanced?.refreshTokenTtlSeconds
+    });
+    const requestHandler = async (request, response) => {
+        const url = new URL(request.url ?? "/", prepared.issuer);
+        if (request.method === "GET" && url.pathname === "/healthz") {
+            response.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end('{"ok":true}');
+            return true;
+        }
+        if (customInteraction?.paths.includes(url.pathname) === true) {
+            const body = request.method === "GET" || request.method === "HEAD" ? undefined : await readBody(request);
+            const handled = await customInteraction.handle({
+                request: toWebRequest(request, prepared.issuer, body),
+                async complete({ transactionId, accountId, credential }) {
+                    const subject = await config.storage.resolveSubject(config.provider.name, accountId);
+                    const completed = await authorizationServer.completeAuthorization({
+                        transactionId,
+                        subject
+                    });
+                    await config.storage.credentials.set(subject, credential);
+                    await config.storage.interactions.delete(transactionId);
+                    return new Response(null, {
+                        status: 303,
+                        headers: {
+                            location: completed.redirectUrl.href,
+                            "cache-control": "no-store",
+                            "content-security-policy": "default-src 'none'",
+                            "referrer-policy": "no-referrer"
+                        }
+                    });
+                }
+            });
+            await writeWebResponse(response, handled);
+            return true;
+        }
+        if (request.method === "POST" && url.pathname === "/oauth/connect") {
+            const body = new URLSearchParams((await readBody(request)).toString("utf8"));
+            const transactionId = body.get("transaction") ?? "";
+            const transaction = await config.storage.interactions.get(transactionId);
+            const csrf = body.get("csrf") ?? "";
+            if (transaction === undefined ||
+                !verifyAuthorizationInteractionCsrf({
+                    cookieHeader: request.headers.cookie ?? null,
+                    submittedToken: csrf,
+                    cookieName: interactionCookieName(transactionId)
+                }) ||
+                transaction.expiresAt <= Date.now()) {
+                response.writeHead(400, {
+                    "content-type": "text/plain; charset=utf-8",
+                    "cache-control": "no-store"
+                });
+                response.end("This connection has expired or was already used. Restart the connection.");
+                return true;
+            }
+            const controller = new AbortController();
+            request.once("aborted", () => controller.abort());
+            const values = Object.assign(Object.create(null), {
+                signal: controller.signal
+            });
+            for (const field of fields)
+                values[field.name] = body.get(field.name) ?? "";
+            try {
+                const connect = config.provider.connect;
+                if (connect === undefined)
+                    throw new Error("Provider form connection is not configured.");
+                const connected = await connect(values);
+                if (connected.accountId.trim().length === 0)
+                    throw new Error("Provider returned an empty accountId.");
+                const subject = await config.storage.resolveSubject(config.provider.name, connected.accountId);
+                const completed = await authorizationServer.completeAuthorization({
+                    transactionId,
+                    subject
+                });
+                await config.storage.credentials.set(subject, connected.credential);
+                await config.storage.interactions.delete(transactionId);
+                response.writeHead(303, {
+                    location: completed.redirectUrl.href,
+                    "cache-control": "no-store",
+                    "content-security-policy": "default-src 'none'",
+                    "referrer-policy": "no-referrer"
+                });
+                response.end();
+            }
+            catch (error) {
+                const safeError = error instanceof HostedOAuthLoginError
+                    ? error.message
+                    : "Sign-in failed. Please try again.";
+                response.writeHead(400, {
+                    "content-type": "text/html; charset=utf-8",
+                    "content-security-policy": loginContentSecurityPolicy(transaction),
+                    "cache-control": "no-store",
+                    "referrer-policy": "no-referrer"
+                });
+                response.end(renderLogin(displayName, fields, transaction, csrf, safeError));
+            }
+            return true;
+        }
+        const oauthPaths = new Set([
+            "/.well-known/oauth-authorization-server",
+            "/.well-known/jwks.json",
+            "/authorize",
+            "/register",
+            "/token",
+            "/revoke"
+        ]);
+        if (!oauthPaths.has(url.pathname))
+            return false;
+        const body = request.method === "POST" ? await readBody(request) : undefined;
+        await writeWebResponse(response, await authorizationServer.handle(toWebRequest(request, prepared.issuer, body)));
+        return true;
+    };
+    return {
+        mcpPath: prepared.publicUrl.pathname,
+        oauth: {
+            resource: prepared.publicUrl.href,
+            authorizationServers: [authorizationServer.issuer],
+            requiredScopes: ["mcp"],
+            scopesSupported: [...prepared.scopes],
+            verifier: {
+                async verify(input) {
+                    const verified = await authorizationServer.verifyAccessToken(input.token, prepared.publicUrl.href);
+                    return {
+                        token: input.token,
+                        issuer: authorizationServer.issuer,
+                        audience: [verified.resource],
+                        scopes: [...verified.scopes],
+                        expiresAt: verified.expiresAt,
+                        claims: { sub: verified.subject, client_id: verified.clientId, jti: verified.tokenId },
+                        subject: verified.subject,
+                        clientId: verified.clientId
+                    };
+                }
+            }
+        },
+        requestHandler,
+        async requestServices(identity) {
+            const credentials = credentialsFor(config.storage, identity.subject);
+            await credentials.read();
+            return config.provider.services({ credentials, identity });
+        }
+    };
+}
+export function createInMemoryHostedOAuthStorage(options) {
+    if (options.development !== true) {
+        throw new Error("In-memory hosted OAuth storage requires explicit development mode.");
+    }
+    const credentials = new Map();
+    const interactions = new Map();
+    const updates = new Map();
+    const subjectSalt = randomBytes(32);
+    let signingKeyPromise;
+    return {
+        authorizationServer: createInMemoryAuthorizationServerStore(),
+        interactions: {
+            async set(transaction) {
+                interactions.set(transaction.id, structuredClone(transaction));
+            },
+            async get(transactionId) {
+                const transaction = interactions.get(transactionId);
+                return transaction === undefined ? undefined : structuredClone(transaction);
+            },
+            async delete(transactionId) {
+                interactions.delete(transactionId);
+            }
+        },
+        capabilities: {
+            durable: false,
+            encryptedCredentials: false,
+            stableKeys: false,
+            shared: false
+        },
+        credentials: {
+            async get(subject) {
+                return credentials.get(subject);
+            },
+            async set(subject, credential) {
+                credentials.set(subject, credential);
+            },
+            async delete(subject) {
+                credentials.delete(subject);
+            },
+            async update(subject, update) {
+                const previous = updates.get(subject) ?? Promise.resolve();
+                const next = previous.then(async () => {
+                    const current = credentials.get(subject);
+                    if (current === undefined)
+                        throw new Error("Provider credential is missing; reconnect required.");
+                    const replacement = await update(current);
+                    credentials.set(subject, replacement);
+                    return replacement;
+                });
+                updates.set(subject, next);
+                try {
+                    return await next;
+                }
+                finally {
+                    if (updates.get(subject) === next)
+                        updates.delete(subject);
+                }
+            }
+        },
+        async signingKey() {
+            signingKeyPromise ??= (async () => {
+                const { privateKey, publicKey } = generateKeyPairSync("ec", {
+                    namedCurve: "prime256v1"
+                });
+                return {
+                    algorithm: "ES256",
+                    keyId: randomBytes(16).toString("base64url"),
+                    privateKey,
+                    publicJwk: await exportJWK(publicKey)
+                };
+            })();
+            return await signingKeyPromise;
+        },
+        async resolveSubject(providerName, accountId) {
+            return createHmac("sha256", subjectSalt)
+                .update(providerName)
+                .update("\0")
+                .update(accountId)
+                .digest("base64url");
+        }
+    };
+}

package/dist/http.d.ts

@@ -1,18 +1,20 @@
 import "./node-require-shim.js";
-import { type HttpListenOptions, type HttpServer, type HttpServerHandle, type HttpToolContext, type HttpTransportOptions } from "tiny-http-mcp-server/server";
+import { type HttpListenOptions, type HttpServer, type HttpServerHandle, type HttpToolContext, type HttpTransportOptions, type TinyHttpMcpServerOAuthOptions } from "tiny-http-mcp-server/server";
 import type { Group } from "./index.js";
 import type { OAuthAuthorizationServer } from "mcp-oauth-server";
 import { type RunMCPOptions } from "./mcp.js";
+import { type HostedOAuthConfiguration } from "./http-hosted-oauth.js";
 export type ToolcraftHTTPContext = HttpToolContext;
 export type ToolcraftHTTPServer = HttpServer;
 export type ToolcraftHTTPServerHandle = HttpServerHandle;
-type HTTPTransportControls = Omit<HttpTransportOptions, "name" | "version" | "validateToolArguments">;
+type HTTPTransportControls = Omit<HttpTransportOptions, "name" | "version" | "validateToolArguments" | "oauth" | "requestHandler">;
 type HTTPListenControls = Omit<HttpListenOptions, "port" | "hostname" | "path">;
 export interface RunHTTPMCPOptions<TServices extends object = Record<string, unknown>> extends RunMCPOptions<TServices>, HTTPTransportControls, HTTPListenControls {
     hostname?: string;
     port?: number;
     path?: string;
     requestServices?(context: ToolcraftHTTPContext): Partial<TServices> | Promise<Partial<TServices>>;
+    oauth?: TinyHttpMcpServerOAuthOptions | HostedOAuthConfiguration<unknown, TServices>;
 }
 export interface HTTPMCPAuthorizationOptions {
     authorizationServer: Pick<OAuthAuthorizationServer, "issuer" | "verifyAccessToken">;

package/dist/http.js

@@ -2,6 +2,7 @@ import "./node-require-shim.js";
 import { createHttpServer } from "tiny-http-mcp-server/server";
 import { createMCPServerForTransport } from "./mcp.js";
 import { enableSourceMaps } from "./stack-trim.js";
+import { isHostedOAuthConfiguration, prepareHostedOAuthRuntime } from "./http-hosted-oauth.js";
 function toVerifiedAccessToken(token, issuer, verified) {
     return {
         token,
@@ -62,7 +63,8 @@ function createTransportOptions(options, serverOptions) {
         requestIdGenerator: options.requestIdGenerator,
         observability: options.observability,
         trustedProxy: options.trustedProxy,
-        oauth: options.oauth
+        oauth: options.oauth,
+        requestHandler: options.requestHandler
     };
 }
 function createListenOptions(options) {
@@ -77,20 +79,70 @@ function createListenOptions(options) {
     };
 }
 export async function createHTTPMCPServer(roots, options) {
+    let resolvedOptions = options;
+    let hostedMcpPath;
+    if (isHostedOAuthConfiguration(options.oauth)) {
+        const runtime = await prepareHostedOAuthRuntime(options.oauth);
+        const applicationServices = options.requestServices;
+        hostedMcpPath = runtime.mcpPath;
+        resolvedOptions = {
+            ...options,
+            oauth: runtime.oauth,
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+            requestServices: async (context) => {
+                const auth = context.auth;
+                const subject = auth?.subject;
+                if (auth === undefined || subject === undefined)
+                    throw new Error("Hosted OAuth request is missing a verified subject.");
+                return {
+                    ...(applicationServices === undefined ? {} : await applicationServices(context)),
+                    ...(await runtime.requestServices({
+                        issuer: auth.issuer,
+                        subject,
+                        clientId: auth.clientId,
+                        scopes: auth.scopes,
+                        resource: auth.resource.href
+                    }))
+                };
+            },
+            requestHandler: runtime.requestHandler
+        };
+    }
     let server;
-    await createMCPServerForTransport(roots, options, {
+    await createMCPServerForTransport(roots, resolvedOptions, {
         createServer(serverOptions) {
-            server = createHttpServer(createTransportOptions(options, serverOptions));
+            server = createHttpServer(createTransportOptions(resolvedOptions, serverOptions));
             return server;
         },
         getRequestContext() {
             return server?.getRequestContext();
         },
-        requestServices: options.requestServices
+        requestServices: resolvedOptions.requestServices
     });
     if (server === undefined) {
         throw new Error("Toolcraft HTTP MCP server was not created.");
     }
+    if (hostedMcpPath !== undefined) {
+        const listenHttp = server.listenHttp.bind(server);
+        server.listenHttp = async (listenOptions = {}) => {
+            if (listenOptions.path !== undefined) {
+                const withLeadingSlash = listenOptions.path.startsWith("/")
+                    ? listenOptions.path
+                    : `/${listenOptions.path}`;
+                const requestedPath = withLeadingSlash.length > 1 && withLeadingSlash.endsWith("/")
+                    ? withLeadingSlash.slice(0, -1)
+                    : withLeadingSlash;
+                if (requestedPath !== hostedMcpPath) {
+                    throw new Error(`Hosted OAuth MCP path ${JSON.stringify(requestedPath)} conflicts with publicUrl path ${JSON.stringify(hostedMcpPath)}.`);
+                }
+            }
+            return listenHttp({
+                ...listenOptions,
+                path: hostedMcpPath
+            });
+        };
+    }
     return server;
 }
 export async function runHTTPMCP(roots, options) {

package/node_modules/mcp-oauth-server/dist/index.d.ts

@@ -98,6 +98,8 @@ export interface OAuthAuthorizationServerSigningKey {
 export interface OAuthAuthorizationServerOptions {
     issuer: string;
     resources: readonly string[];
+    scopesSupported?: readonly string[];
+    defaultScopes?: readonly string[];
     signingKey: OAuthAuthorizationServerSigningKey;
     additionalPublicJwks?: readonly JWK[];
     store: AuthorizationServerStore;

package/node_modules/mcp-oauth-server/dist/index.js

@@ -44,8 +44,7 @@ export function verifyAuthorizationInteractionCsrf(input) {
         return false;
     const cookieBuffer = Buffer.from(cookieValue);
     const submittedBuffer = Buffer.from(input.submittedToken);
-    return (cookieBuffer.length === submittedBuffer.length &&
-        timingSafeEqual(cookieBuffer, submittedBuffer));
+    return (cookieBuffer.length === submittedBuffer.length && timingSafeEqual(cookieBuffer, submittedBuffer));
 }
 function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -70,7 +69,9 @@ function parseAbsoluteUrl(value, label) {
 }
 function validateIssuer(value) {
     const issuer = new URL(parseAbsoluteUrl(value, "issuer"));
-    if (issuer.protocol !== "https:" && issuer.hostname !== "localhost" && issuer.hostname !== "127.0.0.1") {
+    if (issuer.protocol !== "https:" &&
+        issuer.hostname !== "localhost" &&
+        issuer.hostname !== "127.0.0.1") {
         throw new Error("issuer must use HTTPS unless it is loopback.");
     }
     if (issuer.pathname !== "/" || issuer.search.length > 0) {
@@ -247,6 +248,14 @@ export function createInMemoryAuthorizationServerStore() {
 export function createOAuthAuthorizationServer(options) {
     const issuer = validateIssuer(options.issuer);
     const resources = validateResources(options.resources);
+    const scopesSupported = options.scopesSupported === undefined ? undefined : new Set(options.scopesSupported);
+    const defaultScopes = [...new Set(options.defaultScopes ?? [])];
+    if (defaultScopes.some((scope) => scope.length === 0 || /[\u0000-\u0020\u007f]/u.test(scope))) {
+        throw new Error("default scopes must contain valid scope names.");
+    }
+    if (scopesSupported !== undefined && defaultScopes.some((scope) => !scopesSupported.has(scope))) {
+        throw new Error("default scopes must be included in supported scopes.");
+    }
     const now = options.now ?? Date.now;
     const randomToken = options.randomToken ?? opaqueToken;
     const accessTokenTtlMs = (options.accessTokenTtlSeconds ?? 300) * 1000;
@@ -363,13 +372,23 @@ export function createOAuthAuthorizationServer(options) {
         if (url.searchParams.get("code_challenge_method") !== "S256") {
             throw new OAuthProtocolError("invalid_request", "code_challenge_method must be S256.");
         }
+        const requestedScopes = url.searchParams.has("scope")
+            ? parseScopes(url.searchParams.get("scope"))
+            : [...defaultScopes];
+        if (defaultScopes.length > 0 && requestedScopes.length === 0) {
+            throw new OAuthProtocolError("invalid_scope", "scope must not be empty.");
+        }
+        if (scopesSupported !== undefined &&
+            requestedScopes.some((scope) => !scopesSupported.has(scope))) {
+            throw new OAuthProtocolError("invalid_scope", "One or more requested scopes are not supported.");
+        }
         const transaction = {
             id: randomToken(),
             clientId,
             redirectUri,
             codeChallenge,
             resource: requireResource(url.searchParams.get("resource")),
-            scopes: parseScopes(url.searchParams.get("scope")),
+            scopes: requestedScopes,
             ...(url.searchParams.has("state") && { state: url.searchParams.get("state") ?? undefined }),
             createdAt: now(),
             expiresAt: now() + authorizationTransactionTtlMs
@@ -563,6 +582,7 @@ export function createOAuthAuthorizationServer(options) {
                     grant_types_supported: ["authorization_code", "refresh_token"],
                     token_endpoint_auth_methods_supported: ["none"],
                     code_challenge_methods_supported: ["S256"],
+                    ...(scopesSupported === undefined ? {} : { scopes_supported: [...scopesSupported] }),
                     protected_resources: [...resources]
                 });
             }

package/node_modules/tiny-http-mcp-server/dist/composition.json

@@ -18,7 +18,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "license": "MIT"
     },
     {

package/node_modules/tiny-http-mcp-server/dist/express-middleware.js

@@ -40,7 +40,7 @@ export function createProtectedResourceMetadataRouter(options) {
         if (path === "/") {
             return [PROTECTED_RESOURCE_METADATA_PATH];
         }
-        return [`${PROTECTED_RESOURCE_METADATA_PATH}${path}`];
+        return [PROTECTED_RESOURCE_METADATA_PATH, `${PROTECTED_RESOURCE_METADATA_PATH}${path}`];
     })();
     return (req, res, next) => {
         if (req.method !== "GET" || !metadataPaths.includes(req.path)) {

package/node_modules/tiny-http-mcp-server/dist/http-server.d.ts

@@ -14,7 +14,9 @@ export interface TinyHttpMcpServerOAuthOptions extends ProtectedResourceMetadata
 }
 export type HttpTransportOptions = ServerOptions & StreamableHttpTransportOptions & {
     oauth?: TinyHttpMcpServerOAuthOptions;
+    requestHandler?: HttpAdditionalRequestHandler;
 };
+export type HttpAdditionalRequestHandler = (request: IncomingMessage, response: ServerResponse) => boolean | Promise<boolean>;
 export interface HttpListenOptions {
     port?: number;
     hostname?: string;

package/node_modules/tiny-http-mcp-server/dist/http-server.js

@@ -19,7 +19,7 @@ function getProtectedResourceMetadataPaths(path) {
     if (path === "/") {
         return [PROTECTED_RESOURCE_METADATA_PATH];
     }
-    return [`${PROTECTED_RESOURCE_METADATA_PATH}${path}`];
+    return [PROTECTED_RESOURCE_METADATA_PATH, `${PROTECTED_RESOURCE_METADATA_PATH}${path}`];
 }
 function formatHostnameForUrl(hostname) {
     if (hostname.includes(":") && !hostname.startsWith("[")) {
@@ -157,6 +157,9 @@ export function createHttpServer(options) {
         const nodeServer = http.createServer(async (req, res) => {
             const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
             try {
+                if (options.requestHandler !== undefined && (await options.requestHandler(req, res))) {
+                    return;
+                }
                 if (protectedResourceMetadataBody !== undefined &&
                     req.method === "GET" &&
                     getProtectedResourceMetadataPaths(path).includes(requestUrl.pathname)) {
@@ -249,6 +252,9 @@ export function createHttpServer(options) {
         };
     };
     httpServer.handleRequest = async (req, res) => {
+        if (options.requestHandler !== undefined && (await options.requestHandler(req, res))) {
+            return;
+        }
         const { baseUrl } = req;
         const protectedResourcePath = typeof baseUrl === "string" && baseUrl.length > 0 ? baseUrl : "/mcp";
         if (!(await authorizeHttpRequest(req, res, protectedResourcePath))) {

package/node_modules/tiny-http-mcp-server/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { Server, TypedSchema, ImageContent, AudioContent, EmbeddedResource,
 export { createExpressMiddleware, createExpressOAuthHandlers, createProtectedResourceMetadataRouter } from "./express-middleware.js";
 export type { CreateExpressOAuthHandlersOptions } from "./express-middleware.js";
 export { createHttpServer, createProtectedResourceMetadataDocument } from "./http-server.js";
-export type { HttpToolContext, HttpToolHandler, HttpListenOptions, HttpServer, HttpServerHandle, HttpTransportOptions, ProtectedResourceMetadataOptions, TinyHttpMcpServerOAuthOptions } from "./http-server.js";
+export type { HttpToolContext, HttpToolHandler, HttpAdditionalRequestHandler, HttpListenOptions, HttpServer, HttpServerHandle, HttpTransportOptions, ProtectedResourceMetadataOptions, TinyHttpMcpServerOAuthOptions } from "./http-server.js";
 export { TokenVerificationError } from "./auth.js";
 export type { RequestAuthInfo, TokenVerifier, VerifiedAccessToken } from "./auth.js";
 export { StreamableHttpTransport } from "./http-transport.js";

package/node_modules/tiny-http-mcp-server/dist/server.d.ts

@@ -1,5 +1,5 @@
 export { createHttpServer, createProtectedResourceMetadataDocument } from "./http-server.js";
-export type { HttpToolContext, HttpToolHandler, HttpListenOptions, HttpServer, HttpServerHandle, HttpTransportOptions, ProtectedResourceMetadataOptions, TinyHttpMcpServerOAuthOptions } from "./http-server.js";
+export type { HttpToolContext, HttpToolHandler, HttpAdditionalRequestHandler, HttpListenOptions, HttpServer, HttpServerHandle, HttpTransportOptions, ProtectedResourceMetadataOptions, TinyHttpMcpServerOAuthOptions } from "./http-server.js";
 export { TokenVerificationError } from "./auth.js";
 export type { RequestAuthInfo, TokenVerifier, VerifiedAccessToken } from "./auth.js";
 export { StreamableHttpTransport } from "./http-transport.js";

package/node_modules/tiny-http-mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-http-mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Minimal MCP server over HTTP built on tiny-stdio-mcp-server",
   "type": "module",
   "main": "dist/index.js",

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.141",
+      "version": "0.0.143",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.141",
+  "version": "0.0.143",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.141",
+  "version": "0.0.143",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -70,6 +70,10 @@
       "types": "./dist/http.d.ts",
       "import": "./dist/http.js"
     },
+    "./http/hosted-oauth": {
+      "types": "./dist/http-hosted-oauth.d.ts",
+      "import": "./dist/http-hosted-oauth.js"
+    },
     "./frontmatter": {
       "types": "./dist/frontmatter.d.ts",
       "import": "./dist/frontmatter.js"
@@ -154,7 +158,7 @@
     "yaml"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.141",
+    "toolcraft-schema": "0.0.143",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",