@forwardreach/saas-mcp 0.1.0

package/dist/hono/routes.js

@@ -0,0 +1,535 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { buildMcpAuthorizationServerMetadata, buildMcpBearerChallenge, buildMcpProtectedResourceMetadata, validateMcpHttpEnvelope } from "../core/index.js";
+import { addSeconds, hashMcpToken, parseBearerToken, randomMcpToken, verifyPkceS256 } from "../node/index.js";
+import { formatMcpScopeString, hasRequiredMcpScopes, includesUnsupportedMcpScope, normalizeMcpScopes, requestedMcpScopes } from "../core/scopes.js";
+function json(data, status = 200, headers = {}) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            "content-type": "application/json",
+            ...headers
+        }
+    });
+}
+function configuredResponse(data, status = 200) {
+    return json(data, status, { "cache-control": "no-store", "Access-Control-Allow-Origin": "*" });
+}
+function tokenResponse(data) {
+    return json(data, 200, { "cache-control": "no-store", pragma: "no-cache" });
+}
+function oauthError(error, description, status = 400) {
+    return json({ error, error_description: description }, status, { "cache-control": "no-store", pragma: "no-cache" });
+}
+function jsonRpcErrorResponse(status, code, message, id = null, headers = {}) {
+    return json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id
+    }, status, headers);
+}
+function bearerUnauthorized(config, message = "Missing or invalid bearer token") {
+    return jsonRpcErrorResponse(401, ErrorCode.InvalidRequest, message, null, {
+        "WWW-Authenticate": buildMcpBearerChallenge({
+            appBaseUrl: config.appBaseUrl,
+            protectedResourceMetadataPath: config.routes.protectedResourceMetadataPath,
+            scopes: config.supportedScopes
+        })
+    });
+}
+function formValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+async function readBody(c) {
+    const contentType = c.req.header("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return ((await c.req.json().catch(() => ({}))) ?? {});
+    }
+    const form = await c.req.parseBody().catch(() => ({}));
+    return Object.fromEntries(Object.entries(form).map(([key, value]) => [key, formValue(value)]));
+}
+function queryOrBody(c, body, key) {
+    const fromQuery = c.req.query(key);
+    if (fromQuery !== undefined)
+        return fromQuery;
+    const fromBody = body[key];
+    return typeof fromBody === "string" ? fromBody : undefined;
+}
+function clientIdFromRequest(c, body) {
+    const clientId = queryOrBody(c, body, "client_id");
+    if (!clientId)
+        throw new Error("client_id is required");
+    return clientId;
+}
+function validateRedirectUri(clientRedirectUris, redirectUri) {
+    if (!redirectUri || !clientRedirectUris.includes(redirectUri))
+        throw new Error("redirect_uri is invalid for this OAuth client");
+    return redirectUri;
+}
+function validateResource(resource, config) {
+    const resolved = resource ?? config.resourceUri;
+    if (resolved !== config.resourceUri)
+        throw new Error("resource is invalid for this MCP server");
+    return resolved;
+}
+function requestedResource(c, body, config) {
+    return validateResource(queryOrBody(c, body, "resource"), config);
+}
+function redirectWithError(redirectUri, error, state) {
+    const url = new URL(redirectUri);
+    url.searchParams.set("error", error);
+    if (state)
+        url.searchParams.set("state", state);
+    return Response.redirect(url, 302);
+}
+function authorizationRequestError(redirectUri, error, description, state, status = 400) {
+    return redirectUri ? redirectWithError(redirectUri, error, state) : oauthError(error, description, status);
+}
+function consentRedirect(config, request) {
+    const consentPath = config.routes.consentPagePath ?? "/oauth/consent";
+    const url = new URL(consentPath, config.appBaseUrl);
+    url.pathname = consentPath;
+    url.searchParams.set("client_id", request.client.id);
+    url.searchParams.set("redirect_uri", request.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("code_challenge", request.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("scope", formatMcpScopeString(request.scopes));
+    url.searchParams.set("resource", request.resource);
+    url.searchParams.set("workspace_id", request.workspaceId);
+    url.searchParams.set("user_id", request.userId);
+    if (request.state)
+        url.searchParams.set("state", request.state);
+    return Response.redirect(url, 302);
+}
+function forwardedProto(c) {
+    const forwardedProtoHeader = c.req.header("x-forwarded-proto")?.split(",")[0]?.trim().toLowerCase();
+    if (forwardedProtoHeader)
+        return forwardedProtoHeader;
+    const forwardedHeader = c.req.header("forwarded")?.split(",")[0];
+    const protoPair = forwardedHeader
+        ?.split(";")
+        .map((part) => part.trim())
+        .find((part) => part.toLowerCase().startsWith("proto="));
+    return protoPair?.slice("proto=".length).replace(/^"|"$/g, "").toLowerCase() ?? null;
+}
+async function parseMcpBody(request) {
+    if (request.method !== "POST")
+        return null;
+    const body = await request.clone().json().catch(() => null);
+    const messages = Array.isArray(body) ? body : body ? [body] : [];
+    const isInitialize = messages.some((message) => typeof message === "object" && message && message.method === "initialize");
+    const requestMessage = messages.find((message) => typeof message === "object" && message && "id" in message);
+    return { body, isInitialize, id: requestMessage?.id ?? null };
+}
+function calledToolName(parsedBody) {
+    const messages = Array.isArray(parsedBody) ? parsedBody : parsedBody ? [parsedBody] : [];
+    for (const message of messages) {
+        if (!message || typeof message !== "object")
+            continue;
+        const candidate = message;
+        if (candidate.method === "tools/call" && typeof candidate.params?.name === "string")
+            return { name: candidate.params.name, id: candidate.id ?? null };
+    }
+    return null;
+}
+function sameScopes(left, right) {
+    return left.length === right.length && left.every((scope) => right.includes(scope));
+}
+function tokenMatchesSession(_context, token, sessionToken) {
+    return (sessionToken.grantId === token.grantId &&
+        sessionToken.clientId === token.clientId &&
+        sessionToken.workspaceId === token.workspaceId &&
+        sessionToken.userId === token.userId &&
+        sessionToken.sourceKind === token.sourceKind &&
+        sameScopes(sessionToken.scopes, token.scopes));
+}
+async function authenticateMcpRequest(c, config, adapters) {
+    const rawToken = parseBearerToken(c.req.raw);
+    if (!rawToken)
+        return bearerUnauthorized(config);
+    const token = await adapters.validateOAuthToken({
+        tokenHash: hashMcpToken(rawToken),
+        kind: "access",
+        resource: config.resourceUri,
+        recordLastUsed: true
+    });
+    if (!token)
+        return bearerUnauthorized(config, "Bearer token is expired, revoked, malformed, or issued for another resource");
+    return { rawToken, token };
+}
+function authInfo(rawToken, token, config) {
+    return {
+        token: rawToken,
+        clientId: token.clientId,
+        scopes: [...token.scopes],
+        expiresAt: Math.trunc(Date.parse(token.expiresAt) / 1000),
+        resource: new URL(config.resourceUri)
+    };
+}
+async function validateAuthorizationRequest(c, body, config, adapters) {
+    let clientId;
+    try {
+        clientId = clientIdFromRequest(c, body);
+    }
+    catch {
+        return oauthError("invalid_request", "client_id is required");
+    }
+    const client = await adapters.getOAuthClient(clientId);
+    if (!client)
+        return oauthError("invalid_client", "OAuth client not found", 401);
+    let redirectUri;
+    try {
+        redirectUri = validateRedirectUri(client.redirectUris, queryOrBody(c, body, "redirect_uri"));
+    }
+    catch {
+        return oauthError("invalid_request", "redirect_uri is invalid for this OAuth client");
+    }
+    const state = queryOrBody(c, body, "state");
+    if (queryOrBody(c, body, "response_type") !== "code")
+        return authorizationRequestError(redirectUri, "unsupported_response_type", "Only response_type=code is supported", state);
+    let resource;
+    try {
+        resource = requestedResource(c, body, config);
+    }
+    catch {
+        return authorizationRequestError(redirectUri, "invalid_request", "resource is invalid for this MCP server", state);
+    }
+    const codeChallenge = queryOrBody(c, body, "code_challenge");
+    const codeChallengeMethod = queryOrBody(c, body, "code_challenge_method");
+    if (!codeChallenge || codeChallengeMethod !== "S256")
+        return authorizationRequestError(redirectUri, "invalid_request", "PKCE S256 code challenge is required", state);
+    const rawScope = queryOrBody(c, body, "scope");
+    const allowedScopes = client.scopes.length > 0 ? client.scopes : config.supportedScopes;
+    if (includesUnsupportedMcpScope(rawScope, allowedScopes))
+        return authorizationRequestError(redirectUri, "invalid_scope", "Requested scope is not supported for this OAuth client", state);
+    const scopes = requestedMcpScopes(rawScope, allowedScopes, config.defaultScopes);
+    try {
+        const identity = await adapters.resolveConsentIdentity({
+            headers: c.req.raw.headers,
+            workspaceId: queryOrBody(c, body, "workspace_id"),
+            userId: queryOrBody(c, body, "user_id")
+        });
+        return { client, redirectUri, state, resource, codeChallenge, scopes, workspaceId: identity.workspaceId, userId: identity.userId };
+    }
+    catch (error) {
+        return authorizationRequestError(redirectUri, "invalid_request", error instanceof Error ? error.message : "Workspace could not be resolved", state);
+    }
+}
+async function handleMcpRequest(c, options, activeSessions, sessionTokens) {
+    const config = options.resolveConfig(c.req.url);
+    const envelope = validateMcpHttpEnvelope({
+        url: new URL(c.req.url),
+        method: c.req.method,
+        headers: c.req.raw.headers,
+        requireHttps: config.requireHttps,
+        allowedHosts: config.allowedHosts,
+        allowedOrigins: config.allowedOrigins,
+        supportedProtocolVersions: config.supportedProtocolVersions,
+        forwardedProto: forwardedProto(c)
+    });
+    if (!envelope.ok) {
+        if (envelope.reason === "query_token")
+            return bearerUnauthorized(config, envelope.message);
+        return jsonRpcErrorResponse(envelope.status, ErrorCode.InvalidRequest, envelope.message);
+    }
+    const auth = await authenticateMcpRequest(c, config, options.adapters);
+    if (auth instanceof Response)
+        return auth;
+    const parsed = await parseMcpBody(c.req.raw);
+    const sessionId = c.req.header("mcp-session-id") ?? undefined;
+    if (!parsed?.isInitialize && !sessionId) {
+        return jsonRpcErrorResponse(400, ErrorCode.InvalidRequest, "Mcp-Session-Id header is required after initialization", parsed?.id ?? null);
+    }
+    const toolCall = calledToolName(parsed?.body);
+    if (toolCall && options.adapters.getToolByName) {
+        const tool = options.adapters.getToolByName(toolCall.name);
+        if (tool && !hasRequiredMcpScopes(auth.token.scopes, tool.requiredScopes)) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                clientId: auth.token.clientId,
+                accessTokenId: auth.token.id,
+                sourceKind: auth.token.sourceKind,
+                activityKind: tool.annotations?.readOnlyHint ? "read" : "write",
+                toolName: tool.name,
+                outcome: "rejected",
+                metadata: { reason: "insufficient_scope", requiredScopes: tool.requiredScopes }
+            });
+            return jsonRpcErrorResponse(403, ErrorCode.InvalidRequest, `insufficient_scope: requires ${tool.requiredScopes.join(" ")}`, toolCall.id);
+        }
+        if (tool?.annotations?.readOnlyHint) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                clientId: auth.token.clientId,
+                accessTokenId: auth.token.id,
+                sourceKind: auth.token.sourceKind,
+                activityKind: "read",
+                toolName: tool.name,
+                outcome: "matched",
+                metadata: { method: "tools/call" }
+            });
+        }
+    }
+    if (sessionId) {
+        const active = activeSessions.get(sessionId);
+        const sessionToken = sessionTokens.get(sessionId);
+        if (!active || !sessionToken)
+            return jsonRpcErrorResponse(404, ErrorCode.InvalidRequest, "MCP session not found", parsed?.id ?? null);
+        if (!tokenMatchesSession(active.context, auth.token, sessionToken))
+            return bearerUnauthorized(config, "Bearer token does not match this MCP session");
+        const refreshed = options.adapters.refreshMcpContext?.(active.context, auth.token);
+        if (refreshed)
+            active.context = refreshed;
+        sessionTokens.set(sessionId, auth.token);
+        await options.adapters.touchMcpSession(sessionId, { accessTokenId: auth.token.id, scopes: [...auth.token.scopes] });
+        const response = await active.transport.handleRequest(c.req.raw, { authInfo: authInfo(auth.rawToken, auth.token, config) });
+        if (c.req.raw.method === "DELETE") {
+            activeSessions.delete(sessionId);
+            sessionTokens.delete(sessionId);
+            await options.adapters.closeMcpSession(sessionId);
+        }
+        return response;
+    }
+    const context = options.adapters.createMcpContext({ token: auth.token, config });
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: options.sessionIdGenerator,
+        enableJsonResponse: true,
+        onsessioninitialized: (newSessionId) => {
+            void options.adapters.trackMcpSession({
+                id: newSessionId,
+                accessTokenId: auth.token.id,
+                clientId: auth.token.clientId,
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                scopes: [...auth.token.scopes],
+                protocolVersion: c.req.header("mcp-protocol-version") ?? config.latestProtocolVersion
+            });
+            activeSessions.set(newSessionId, { transport, context });
+            sessionTokens.set(newSessionId, auth.token);
+        },
+        onsessionclosed: (closedSessionId) => {
+            activeSessions.delete(closedSessionId);
+            sessionTokens.delete(closedSessionId);
+            void options.adapters.closeMcpSession(closedSessionId);
+        }
+    });
+    const server = options.adapters.createMcpServer(context);
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw, { authInfo: authInfo(auth.rawToken, auth.token, config) });
+}
+/**
+ * Register OAuth discovery, dynamic client registration, authorization-code
+ * flow, token revocation, and Streamable HTTP MCP routes on a Hono app.
+ *
+ * The function is intentionally adapter-driven: it does not import product
+ * repositories, auth systems, or tool handlers. Consumers mount these routes
+ * inside their own API surface and supply product-specific adapters.
+ */
+export function registerMcpHonoRoutes(app, options) {
+    const activeSessions = new Map();
+    const sessionTokens = new Map();
+    app.get(options.mounts.protectedResourceMetadata, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        return configuredResponse(buildMcpProtectedResourceMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(`${options.mounts.protectedResourceMetadata}/*`, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        return configuredResponse(buildMcpProtectedResourceMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(options.mounts.authorizationServerMetadata, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        return configuredResponse(buildMcpAuthorizationServerMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(options.mounts.authorize, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const request = await validateAuthorizationRequest(c, {}, config, options.adapters);
+        if (request instanceof Response)
+            return request;
+        return consentRedirect(config, request);
+    });
+    app.post(options.mounts.authorize, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const request = await validateAuthorizationRequest(c, body, config, options.adapters);
+        if (request instanceof Response)
+            return request;
+        const consentAction = queryOrBody(c, body, "consent_action") ?? queryOrBody(c, body, "decision") ?? queryOrBody(c, body, "action");
+        if (consentAction === "cancel" || consentAction === "deny")
+            return redirectWithError(request.redirectUri, "access_denied", request.state);
+        if (consentAction !== "approve")
+            return consentRedirect(config, request);
+        const rawCode = randomMcpToken(config.tokenPrefixes?.authorizationCode ?? "mcp_code");
+        await options.adapters.createOAuthAuthorizationCode({
+            codeHash: hashMcpToken(rawCode),
+            clientId: request.client.id,
+            redirectUri: request.redirectUri,
+            workspaceId: request.workspaceId,
+            userId: request.userId,
+            scopes: request.scopes,
+            resource: request.resource,
+            codeChallenge: request.codeChallenge,
+            codeChallengeMethod: "S256",
+            expiresAt: addSeconds(new Date(), config.authorizationCodeTtlSeconds)
+        });
+        const redirect = new URL(request.redirectUri);
+        redirect.searchParams.set("code", rawCode);
+        if (request.state)
+            redirect.searchParams.set("state", request.state);
+        return Response.redirect(redirect, 302);
+    });
+    app.post(options.mounts.registration, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris.filter((uri) => typeof uri === "string") : [];
+        if (redirectUris.length === 0)
+            return oauthError("invalid_client_metadata", "redirect_uris is required");
+        const rawScope = typeof body.scope === "string" ? body.scope : undefined;
+        const rawScopes = Array.isArray(body.scopes) ? body.scopes.filter((scope) => typeof scope === "string") : undefined;
+        const scopes = normalizeMcpScopes(rawScopes ?? rawScope, config.supportedScopes);
+        const client = await options.adapters.registerOAuthClient({
+            name: typeof body.client_name === "string" ? body.client_name : "MCP client",
+            displayName: typeof body.client_name === "string" ? body.client_name : undefined,
+            redirectUris,
+            scopes: scopes.length > 0 ? scopes : [...config.supportedScopes]
+        });
+        return json({
+            client_id: client.id,
+            client_name: client.name,
+            redirect_uris: client.redirectUris,
+            scope: formatMcpScopeString(client.scopes),
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            client_id_issued_at: Math.trunc(Date.parse(client.createdAt) / 1000)
+        }, 201, { "cache-control": "no-store" });
+    });
+    app.post(options.mounts.token, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const grantType = body.grant_type;
+        const clientId = clientIdFromRequest(c, body);
+        const client = await options.adapters.getOAuthClient(clientId);
+        if (!client)
+            return oauthError("invalid_client", "OAuth client not found", 401);
+        if (grantType === "authorization_code") {
+            const redirectUri = validateRedirectUri(client.redirectUris, queryOrBody(c, body, "redirect_uri"));
+            const resource = requestedResource(c, body, config);
+            const code = queryOrBody(c, body, "code");
+            const codeVerifier = queryOrBody(c, body, "code_verifier");
+            if (!code || !codeVerifier)
+                return oauthError("invalid_request", "code and code_verifier are required");
+            const grant = await options.adapters.consumeOAuthAuthorizationCode({ codeHash: hashMcpToken(code), clientId, redirectUri, resource });
+            if (!grant)
+                return oauthError("invalid_grant", "Authorization code is expired, reused, or invalid");
+            if (!verifyPkceS256(codeVerifier, grant.codeChallenge))
+                return oauthError("invalid_grant", "PKCE verification failed");
+            if (!(await options.adapters.hasWorkspaceMembership({ workspaceId: grant.workspaceId, userId: grant.userId })))
+                return oauthError("invalid_grant", "Workspace membership required");
+            const accessToken = randomMcpToken(config.tokenPrefixes?.accessToken ?? "mcp_at");
+            const refreshToken = randomMcpToken(config.tokenPrefixes?.refreshToken ?? "mcp_rt");
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(accessToken),
+                kind: "access",
+                grantId: grant.id,
+                clientId,
+                workspaceId: grant.workspaceId,
+                userId: grant.userId,
+                scopes: [...grant.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.accessTokenTtlSeconds)
+            });
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(refreshToken),
+                kind: "refresh",
+                grantId: grant.id,
+                clientId,
+                workspaceId: grant.workspaceId,
+                userId: grant.userId,
+                scopes: [...grant.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.refreshTokenTtlSeconds)
+            });
+            return tokenResponse({
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: config.accessTokenTtlSeconds,
+                refresh_token: refreshToken,
+                scope: formatMcpScopeString(grant.scopes),
+                resource
+            });
+        }
+        if (grantType === "refresh_token") {
+            const resource = requestedResource(c, body, config);
+            const refreshToken = queryOrBody(c, body, "refresh_token");
+            if (!refreshToken)
+                return oauthError("invalid_request", "refresh_token is required");
+            const tokenRecord = await options.adapters.validateOAuthToken({ tokenHash: hashMcpToken(refreshToken), kind: "refresh", resource });
+            if (!tokenRecord || tokenRecord.clientId !== clientId)
+                return oauthError("invalid_grant", "Refresh token is expired, revoked, or invalid");
+            const accessToken = randomMcpToken(config.tokenPrefixes?.accessToken ?? "mcp_at");
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(accessToken),
+                kind: "access",
+                grantId: tokenRecord.grantId,
+                clientId,
+                workspaceId: tokenRecord.workspaceId,
+                userId: tokenRecord.userId,
+                scopes: [...tokenRecord.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.accessTokenTtlSeconds)
+            });
+            return tokenResponse({
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: config.accessTokenTtlSeconds,
+                scope: formatMcpScopeString(tokenRecord.scopes),
+                resource
+            });
+        }
+        return oauthError("unsupported_grant_type", "Only authorization_code and refresh_token grants are supported");
+    });
+    app.post(options.mounts.revocation, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const tokenValue = queryOrBody(c, body, "token");
+        if (!tokenValue)
+            return new Response(null, { status: 200 });
+        const tokenHash = hashMcpToken(tokenValue);
+        const tokenRecord = await options.adapters.getOAuthTokenByHash({ tokenHash, resource: config.resourceUri });
+        const clientId = queryOrBody(c, body, "client_id");
+        if (tokenRecord && clientId && tokenRecord.clientId !== clientId)
+            return oauthError("invalid_client", "client_id does not match token owner", 401);
+        if (tokenRecord && (await options.adapters.revokeOAuthToken(tokenHash, { revokedByUserId: tokenRecord.userId, revokedReason: "oauth_revocation_endpoint" }))) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: tokenRecord.workspaceId,
+                userId: tokenRecord.userId,
+                clientId: tokenRecord.clientId,
+                accessTokenId: tokenRecord.kind === "access" ? tokenRecord.id : null,
+                sourceKind: tokenRecord.sourceKind,
+                activityKind: "management",
+                toolName: "oauth.revoke",
+                outcome: "revoked",
+                metadata: { tokenKind: tokenRecord.kind, grantId: tokenRecord.grantId, tokenName: tokenRecord.displayName }
+            });
+        }
+        return new Response(null, { status: 200 });
+    });
+    app.all(options.mounts.mcp, async (c) => handleMcpRequest(c, options, activeSessions, sessionTokens));
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/dist/node/better-auth.d.ts

@@ -0,0 +1,84 @@
+import type { McpHumanIdentityContext, McpUser, McpWorkspace, McpWorkspaceMembership } from "../core/types.js";
+/** Package-local, BetterAuth-compatible user shape consumed by MCP identity helpers. */
+export interface BetterAuthUserLike {
+    id: string;
+    email?: string | null;
+    emailVerified?: boolean | null;
+    name?: string | null;
+    displayName?: string | null;
+    image?: string | null;
+    [key: string]: unknown;
+}
+/** Package-local, BetterAuth-compatible session shape used for fresh-auth checks. */
+export interface BetterAuthSessionLike {
+    id?: string;
+    userId?: string;
+    createdAt?: Date | string | null;
+    updatedAt?: Date | string | null;
+    expiresAt?: Date | string | null;
+    fresh?: boolean | null;
+    [key: string]: unknown;
+}
+/** Package-local shape returned by a product's BetterAuth session resolver adapter. */
+export interface BetterAuthSessionResultLike {
+    user: BetterAuthUserLike;
+    session?: BetterAuthSessionLike | null;
+}
+/** Package-local JWT/OIDC claims shape used for app-token identity normalization. */
+export interface BetterAuthClaimsLike {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    [key: string]: unknown;
+}
+/** Normalized MCP human identity resolved from product-adapted BetterAuth session or JWT data. */
+export interface BetterAuthIdentityAdapterResult {
+    user: McpUser;
+    sessionFresh: boolean;
+    rawSession?: BetterAuthSessionLike | null;
+    rawClaims?: BetterAuthClaimsLike | null;
+}
+/** Product function that resolves a BetterAuth session from request headers. */
+export type BetterAuthSessionResolver = (headers: Headers) => Promise<BetterAuthSessionResultLike | null> | BetterAuthSessionResultLike | null;
+/** Product function that verifies an app JWT and returns claims. */
+export type BetterAuthJwtVerifier = (token: string) => Promise<BetterAuthClaimsLike | null> | BetterAuthClaimsLike | null;
+/**
+ * Optional BetterAuth integration hooks for resolving the human app user.
+ *
+ * BetterAuth proves the signed-in human for consent or management actions. MCP
+ * client authorization still uses separate OAuth/developer tokens.
+ */
+export interface BetterAuthMcpIdentityAdapter {
+    resolveSession?: BetterAuthSessionResolver;
+    verifyJwt?: BetterAuthJwtVerifier;
+    providerKey?: string;
+    issuer?: string;
+    freshSessionMaxAgeMs?: number;
+}
+/** Return whether a BetterAuth session satisfies a fresh-auth age window. */
+export declare function isFreshBetterAuthSession(session: BetterAuthSessionLike | null | undefined, maxAgeMs?: number, now?: number): boolean;
+/** Normalize BetterAuth session data into the shared MCP user shape. */
+export declare function normalizeBetterAuthSessionIdentity(input: {
+    result: BetterAuthSessionResultLike;
+    providerKey?: string;
+    issuer?: string;
+    freshSessionMaxAgeMs?: number;
+}): BetterAuthIdentityAdapterResult;
+/** Normalize verified JWT claims into the shared MCP user shape. */
+export declare function normalizeBetterAuthJwtIdentity(input: {
+    claims: BetterAuthClaimsLike;
+    providerKey?: string;
+    issuer?: string;
+}): BetterAuthIdentityAdapterResult;
+/** Resolve human identity from a BetterAuth session first, then optional JWT. */
+export declare function resolveBetterAuthMcpIdentity(headers: Headers, adapter: BetterAuthMcpIdentityAdapter): Promise<BetterAuthIdentityAdapterResult | null>;
+/** Combine normalized identity with product workspace membership context. */
+export declare function createMcpHumanIdentityContext(input: {
+    identity: BetterAuthIdentityAdapterResult;
+    workspace: McpWorkspace;
+    membership: McpWorkspaceMembership;
+}): McpHumanIdentityContext;