@forwardreach/saas-mcp 0.1.0

package/dist/core/urls.d.ts

@@ -0,0 +1,69 @@
+import type { McpScopeValue } from "./types.js";
+/** Public route paths advertised through OAuth/MCP metadata documents. */
+export interface McpOAuthPublicRoutes {
+    protectedResourceMetadataPath: string;
+    authorizationServerMetadataPath: string;
+    authorizePath: string;
+    consentPagePath?: string;
+    tokenPath: string;
+    registrationPath: string;
+    revocationPath: string;
+    mcpEndpointPath: string;
+}
+/** Inputs needed to build product-specific OAuth discovery metadata. */
+export interface McpOAuthMetadataInput<S extends McpScopeValue = McpScopeValue> {
+    appBaseUrl: string;
+    resourceUri: string;
+    supportedScopes: readonly S[];
+    routes: McpOAuthPublicRoutes;
+}
+/** OAuth protected-resource metadata for the MCP endpoint. */
+export interface McpProtectedResourceMetadata<S extends McpScopeValue = McpScopeValue> {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported: S[];
+    resource_documentation: string;
+}
+/** OAuth authorization-server metadata for MCP client registration and tokens. */
+export interface McpAuthorizationServerMetadata<S extends McpScopeValue = McpScopeValue> {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint: string;
+    revocation_endpoint: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported: string[];
+    scopes_supported: S[];
+    resource_parameter_supported: boolean;
+    protected_resources: string[];
+    mcp_endpoint: string;
+}
+/** Inputs for building a WWW-Authenticate bearer challenge. */
+export interface McpBearerChallengeInput<S extends McpScopeValue = McpScopeValue> {
+    appBaseUrl: string;
+    protectedResourceMetadataPath: string;
+    scopes: readonly S[];
+}
+/** Remove trailing slashes from an origin or base URL. */
+export declare function trimTrailingSlash(value: string): string;
+/** Join an app base URL and path without duplicating slashes. */
+export declare function joinUrlPath(appBaseUrl: string, path: string): string;
+/** Build the canonical MCP resource URI from a public app URL and endpoint path. */
+export declare function deriveMcpResourceUri(appBaseUrl: string, mcpEndpointPath: string): string;
+/** Extract an origin from a request URL, returning null for invalid input. */
+export declare function originFromRequestUrl(requestUrl?: string): string | null;
+/** Return whether an origin is a localhost or loopback development origin. */
+export declare function isLocalOrigin(origin: string): boolean;
+/** Return whether an origin is public HTTPS rather than local development. */
+export declare function isPublicHttpsOrigin(origin: string): boolean;
+/** Extract a hostname from a URL, returning null for invalid input. */
+export declare function hostFromUrl(value: string): string | null;
+/** Build RFC 9728 protected-resource metadata for the MCP endpoint. */
+export declare function buildMcpProtectedResourceMetadata<S extends McpScopeValue>(input: McpOAuthMetadataInput<S>): McpProtectedResourceMetadata<S>;
+/** Build OAuth authorization-server metadata for MCP clients. */
+export declare function buildMcpAuthorizationServerMetadata<S extends McpScopeValue>(input: McpOAuthMetadataInput<S>): McpAuthorizationServerMetadata<S>;
+/** Build the bearer challenge returned with unauthorized MCP requests. */
+export declare function buildMcpBearerChallenge<S extends McpScopeValue>(input: McpBearerChallengeInput<S>): string;

package/dist/core/urls.js

@@ -0,0 +1,85 @@
+import { formatMcpScopeString } from "./scopes.js";
+/** Remove trailing slashes from an origin or base URL. */
+export function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+/** Join an app base URL and path without duplicating slashes. */
+export function joinUrlPath(appBaseUrl, path) {
+    return new URL(path, `${trimTrailingSlash(appBaseUrl)}/`).toString();
+}
+/** Build the canonical MCP resource URI from a public app URL and endpoint path. */
+export function deriveMcpResourceUri(appBaseUrl, mcpEndpointPath) {
+    return joinUrlPath(appBaseUrl, mcpEndpointPath);
+}
+/** Extract an origin from a request URL, returning null for invalid input. */
+export function originFromRequestUrl(requestUrl) {
+    if (!requestUrl)
+        return null;
+    try {
+        return new URL(requestUrl).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return whether an origin is a localhost or loopback development origin. */
+export function isLocalOrigin(origin) {
+    try {
+        const url = new URL(origin);
+        return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+/** Return whether an origin is public HTTPS rather than local development. */
+export function isPublicHttpsOrigin(origin) {
+    try {
+        const url = new URL(origin);
+        return url.protocol === "https:" && !isLocalOrigin(url.origin);
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract a hostname from a URL, returning null for invalid input. */
+export function hostFromUrl(value) {
+    try {
+        return new URL(value).host;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build RFC 9728 protected-resource metadata for the MCP endpoint. */
+export function buildMcpProtectedResourceMetadata(input) {
+    return {
+        resource: input.resourceUri,
+        authorization_servers: [joinUrlPath(input.appBaseUrl, input.routes.authorizationServerMetadataPath)],
+        bearer_methods_supported: ["header"],
+        scopes_supported: [...input.supportedScopes],
+        resource_documentation: trimTrailingSlash(input.appBaseUrl)
+    };
+}
+/** Build OAuth authorization-server metadata for MCP clients. */
+export function buildMcpAuthorizationServerMetadata(input) {
+    return {
+        issuer: trimTrailingSlash(input.appBaseUrl),
+        authorization_endpoint: joinUrlPath(input.appBaseUrl, input.routes.authorizePath),
+        token_endpoint: joinUrlPath(input.appBaseUrl, input.routes.tokenPath),
+        registration_endpoint: joinUrlPath(input.appBaseUrl, input.routes.registrationPath),
+        revocation_endpoint: joinUrlPath(input.appBaseUrl, input.routes.revocationPath),
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        token_endpoint_auth_methods_supported: ["none"],
+        code_challenge_methods_supported: ["S256"],
+        scopes_supported: [...input.supportedScopes],
+        resource_parameter_supported: true,
+        protected_resources: [joinUrlPath(input.appBaseUrl, input.routes.protectedResourceMetadataPath)],
+        mcp_endpoint: joinUrlPath(input.appBaseUrl, input.routes.mcpEndpointPath)
+    };
+}
+/** Build the bearer challenge returned with unauthorized MCP requests. */
+export function buildMcpBearerChallenge(input) {
+    return `Bearer resource_metadata="${joinUrlPath(input.appBaseUrl, input.protectedResourceMetadataPath)}", scope="${formatMcpScopeString(input.scopes)}"`;
+}

package/dist/hono/index.d.ts

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

package/dist/hono/index.js

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

package/dist/hono/routes.d.ts

@@ -0,0 +1,212 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Hono } from "hono";
+import { type McpAuditEvent, type McpOAuthPublicRoutes, type McpScopeValue, type McpToolDescriptor } from "../core/index.js";
+import type { OAuthAuthorizationCodeRecord, OAuthClientRecord, OAuthTokenRecord } from "../core/types.js";
+/**
+ * Product-local Hono paths where the shared MCP router mounts its public HTTP API.
+ *
+ * These are pathnames relative to the Hono app or route group supplied by the
+ * consuming product. The absolute URLs advertised to MCP clients are derived
+ * from `McpHonoRuntimeConfig.routes`.
+ */
+export interface McpHonoRouteMounts {
+    /** GET: OAuth protected-resource metadata for the MCP endpoint. */
+    protectedResourceMetadata: string;
+    /** GET: OAuth authorization-server metadata for dynamic MCP clients. */
+    authorizationServerMetadata: string;
+    /** GET renders consent; POST accepts approve/cancel consent decisions. */
+    authorize: string;
+    /** POST: OAuth token exchange for authorization_code and refresh_token grants. */
+    token: string;
+    /** POST: OAuth token revocation endpoint for client-initiated revocation. */
+    revocation: string;
+    /** POST: dynamic client registration for MCP OAuth clients. */
+    registration: string;
+    /** Streamable HTTP MCP endpoint that receives JSON-RPC MCP requests. */
+    mcp: string;
+}
+/**
+ * Per-request runtime settings used by the shared MCP router.
+ *
+ * The consuming product owns deployment-specific values such as public URLs,
+ * HTTPS policy, allowed origins/hosts, supported scopes, and token TTLs. This
+ * keeps the shared package independent of Next.js, Railway, Cloudflare, or any
+ * product-specific hosting model.
+ */
+export interface McpHonoRuntimeConfig<S extends McpScopeValue = McpScopeValue> {
+    appBaseUrl: string;
+    resourceUri: string;
+    requireHttps: boolean;
+    allowedOrigins: readonly string[];
+    allowedHosts: readonly string[];
+    supportedScopes: readonly S[];
+    defaultScopes: readonly S[];
+    latestProtocolVersion: string;
+    supportedProtocolVersions: readonly string[];
+    routes: McpOAuthPublicRoutes;
+    accessTokenTtlSeconds: number;
+    refreshTokenTtlSeconds: number;
+    authorizationCodeTtlSeconds: number;
+    tokenPrefixes?: {
+        authorizationCode?: string;
+        accessToken?: string;
+        refreshToken?: string;
+    };
+}
+/**
+ * Human identity selected for an OAuth consent decision.
+ *
+ * Products should resolve this from their signed-in app user and membership
+ * model. Query/body user IDs are hints only; products must not trust forged
+ * user or workspace identifiers from OAuth clients.
+ */
+export interface McpConsentIdentity {
+    workspaceId: string;
+    userId: string;
+}
+/**
+ * Product-owned storage, identity, membership, audit, and tool adapters used by
+ * the shared Hono implementation.
+ *
+ * The shared router owns protocol mechanics and DTO shape. The product owns all
+ * durable records, workspace authorization, human identity lookup, audit writes,
+ * and construction of the product-specific `McpServer` instance.
+ */
+export interface McpHonoAdapters<S extends McpScopeValue, C> {
+    /** Create or update a dynamically registered OAuth client. */
+    registerOAuthClient(input: {
+        name: string;
+        displayName?: string;
+        redirectUris: string[];
+        scopes: S[];
+    }): Promise<OAuthClientRecord<S>>;
+    /** Look up an OAuth client by client_id. */
+    getOAuthClient(clientId: string): Promise<OAuthClientRecord<S> | null>;
+    /** Persist a hashed, single-use OAuth authorization code after consent. */
+    createOAuthAuthorizationCode(input: {
+        codeHash: string;
+        clientId: string;
+        redirectUri: string;
+        workspaceId: string;
+        userId: string;
+        scopes: S[];
+        resource: string;
+        codeChallenge: string;
+        codeChallengeMethod: "S256";
+        expiresAt: string;
+    }): Promise<OAuthAuthorizationCodeRecord<S>>;
+    /** Atomically consume a valid authorization code during token exchange. */
+    consumeOAuthAuthorizationCode(input: {
+        codeHash: string;
+        clientId: string;
+        redirectUri: string;
+        resource: string;
+        now?: string;
+    }): Promise<OAuthAuthorizationCodeRecord<S> | null>;
+    /** Store a hashed OAuth access or refresh token. */
+    issueOAuthToken(input: {
+        tokenHash: string;
+        kind: OAuthTokenRecord<S>["kind"];
+        grantId: string;
+        clientId: string;
+        workspaceId: string;
+        userId: string;
+        scopes: S[];
+        resource: string;
+        sourceKind?: OAuthTokenRecord<S>["sourceKind"];
+        displayName?: string | null;
+        expiresAt: string;
+    }): Promise<OAuthTokenRecord<S>>;
+    /** Find a token record by hash, optionally including revoked tokens. */
+    getOAuthTokenByHash(input: {
+        tokenHash: string;
+        kind?: OAuthTokenRecord<S>["kind"];
+        resource?: string;
+        includeRevoked?: boolean;
+    }): Promise<OAuthTokenRecord<S> | null>;
+    /** Validate a token for bearer use and optionally update last-used metadata. */
+    validateOAuthToken(input: {
+        tokenHash: string;
+        kind?: OAuthTokenRecord<S>["kind"];
+        resource: string;
+        now?: string;
+        recordLastUsed?: boolean;
+    }): Promise<OAuthTokenRecord<S> | null>;
+    /** Revoke an OAuth or developer token by token hash. */
+    revokeOAuthToken(tokenHash: string, input?: {
+        revokedByUserId?: string | null;
+        revokedReason?: string | null;
+    }): Promise<boolean>;
+    /** Confirm the token or consent user still belongs to the selected workspace. */
+    hasWorkspaceMembership(input: {
+        workspaceId: string;
+        userId: string;
+    }): Promise<boolean>;
+    /** Resolve the signed-in human who is viewing or submitting OAuth consent. */
+    resolveConsentIdentity(input: {
+        headers: Headers;
+        workspaceId?: string | null;
+        userId?: string | null;
+    }): Promise<McpConsentIdentity>;
+    /** Record a newly initialized Streamable HTTP MCP session. */
+    trackMcpSession(input: {
+        id: string;
+        accessTokenId: string;
+        clientId: string;
+        workspaceId: string;
+        userId: string;
+        scopes: S[];
+        protocolVersion?: string | null;
+    }): Promise<unknown>;
+    /** Refresh session metadata after a valid non-initialize MCP request. */
+    touchMcpSession(sessionId: string, input?: {
+        accessTokenId?: string;
+        scopes?: S[];
+    }): Promise<unknown>;
+    /** Mark a Streamable HTTP MCP session closed. */
+    closeMcpSession(sessionId: string): Promise<unknown>;
+    /** Persist an MCP audit event after tool calls or management activity. */
+    recordMcpAuditEvent(input: {
+        workspaceId: string;
+        userId: string;
+        clientId: string;
+        accessTokenId?: string | null;
+        sourceKind?: OAuthTokenRecord<S>["sourceKind"];
+        activityKind?: string;
+        toolName: string;
+        targetRecordIds?: string[];
+        outcome: McpAuditEvent["outcome"];
+        metadata?: Record<string, unknown>;
+    }): Promise<McpAuditEvent>;
+    /** Build the product-specific tool execution context from the bearer token. */
+    createMcpContext(input: {
+        token: OAuthTokenRecord<S>;
+        config: McpHonoRuntimeConfig<S>;
+    }): C;
+    /** Update an existing session context when token metadata changes. */
+    refreshMcpContext?(context: C, token: OAuthTokenRecord<S>): C | void;
+    /** Create the product MCP server and register product-owned tools. */
+    createMcpServer(context: C): McpServer;
+    /** Optional lookup used to classify tool audit activity before execution. */
+    getToolByName?(name: string): McpToolDescriptor<S> | undefined;
+}
+/** Options for registering the shared MCP OAuth and Streamable HTTP routes. */
+export interface RegisterMcpHonoRoutesOptions<S extends McpScopeValue, C> {
+    /** Resolve runtime configuration for the incoming request URL. */
+    resolveConfig(requestUrl?: string): McpHonoRuntimeConfig<S>;
+    /** Product-local route mount points. */
+    mounts: McpHonoRouteMounts;
+    /** Product adapters for persistence, identity, tools, and audit. */
+    adapters: McpHonoAdapters<S, C>;
+    /** Generate an MCP session id for initialized Streamable HTTP sessions. */
+    sessionIdGenerator(): string;
+}
+/**
+ * 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 declare function registerMcpHonoRoutes<S extends McpScopeValue, C>(app: Hono, options: RegisterMcpHonoRoutesOptions<S, C>): void;