@peoplethread/saas-mcp 0.0.0-stage → 0.3.1

package/dist/core/urls.d.ts

@@ -0,0 +1,97 @@
+import type { McpScopeValue } from "./types.ts";
+/** Public route paths advertised through OAuth/MCP metadata documents. */
+export interface McpOAuthPublicRoutes {
+    protectedResourceMetadataPath: string;
+    /**
+     * No `authorizationServerMetadataPath`: RFC 8414 derives that address from the issuer, so
+     * the router registers it itself. A configurable one could only ever disagree.
+     */
+    authorizePath: string;
+    consentPagePath?: string;
+    /**
+     * Where the product's human sign-in lives. Used by the authorize route to offer sign-in
+     * when an authorization request arrives with no signed-in human, instead of reporting the
+     * missing session to the OAuth client as a malformed request. Only the product knows this
+     * address, and a product that omits it gets the OAuth error path instead.
+     *
+     * Resolved against `appBaseUrl`, so a host-absolute path (`/sign-in`), a relative one, a path
+     * carrying a query (`/sign-in?tenant=acme`), and an absolute URL on a separate identity host
+     * all work as written. A `callbackURL` parameter is added to whatever results.
+     */
+    signInPath?: string;
+    tokenPath: string;
+    registrationPath: string;
+    revocationPath: 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;
+}
+/** Inputs for building a WWW-Authenticate bearer challenge. */
+export interface McpBearerChallengeInput<S extends McpScopeValue = McpScopeValue> {
+    appBaseUrl: string;
+    protectedResourceMetadataPath: string;
+    scopes: readonly S[];
+    /**
+     * RFC 6750 error code, omitted for a plain "authenticate here" challenge. Set it when
+     * a credential was presented and rejected, so the client stops replaying it instead of
+     * treating the 401 as a prompt to retry with the same token.
+     */
+    error?: string;
+}
+/** 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;
+/** 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;
+/**
+ * The address a client fetches authorization-server metadata from, given an issuer.
+ *
+ * RFC 8414 §3.1 inserts the well-known segment between the issuer's host and its path, so a
+ * root issuer yields `<origin>/.well-known/oauth-authorization-server` and an issuer with a
+ * path yields that address with the path appended — never the issuer with the segment tacked
+ * on the end. This is the derivation `authorization_servers` commits a deployment to: the
+ * routes have to serve the document here, or discovery stops at the first hop.
+ *
+ * Exported so the rule is written once. A consumer computing it by hand is how the metadata
+ * URL ended up in `authorization_servers` in the first place.
+ */
+export declare function authorizationServerMetadataUrlForIssuer(issuer: string): string;
+/** 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,106 @@
+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();
+}
+/** 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;
+    }
+}
+/**
+ * The address a client fetches authorization-server metadata from, given an issuer.
+ *
+ * RFC 8414 §3.1 inserts the well-known segment between the issuer's host and its path, so a
+ * root issuer yields `<origin>/.well-known/oauth-authorization-server` and an issuer with a
+ * path yields that address with the path appended — never the issuer with the segment tacked
+ * on the end. This is the derivation `authorization_servers` commits a deployment to: the
+ * routes have to serve the document here, or discovery stops at the first hop.
+ *
+ * Exported so the rule is written once. A consumer computing it by hand is how the metadata
+ * URL ended up in `authorization_servers` in the first place.
+ */
+export function authorizationServerMetadataUrlForIssuer(issuer) {
+    const url = new URL(issuer);
+    const issuerPath = trimTrailingSlash(url.pathname);
+    return `${url.origin}/.well-known/oauth-authorization-server${issuerPath}`;
+}
+/** 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,
+        /**
+         * RFC 9728 defines this as a list of authorization server *issuer identifiers*, not
+         * metadata document URLs: clients apply RFC 8414 well-known path insertion to what they
+         * find here, and RFC 8414 §3.3 requires the result's `issuer` to match the value they
+         * started from. Publishing the metadata URL sends them to `/.well-known/…/api/.well-known/…`,
+         * which 404s, after which they fall back to origin defaults and fail to register. This is
+         * deliberately the same expression `buildMcpAuthorizationServerMetadata` uses for `issuer`
+         * so the two cannot drift.
+         */
+        authorization_servers: [trimTrailingSlash(input.appBaseUrl)],
+        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
+    };
+}
+/** Build the bearer challenge returned with unauthorized MCP requests. */
+export function buildMcpBearerChallenge(input) {
+    const error = input.error ? `error="${input.error}", ` : "";
+    return `Bearer ${error}resource_metadata="${joinUrlPath(input.appBaseUrl, input.protectedResourceMetadataPath)}", scope="${formatMcpScopeString(input.scopes)}"`;
+}

package/dist/hono/index.d.ts

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

package/dist/hono/index.js

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

package/dist/hono/routes.d.ts

@@ -0,0 +1,295 @@
+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.ts";
+import type { OAuthAuthorizationCodeRecord, OAuthClientRecord, OAuthTokenRecord } from "../core/types.ts";
+/**
+ * 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 {
+    /**
+     * Where this Hono app sits in the host's path space, `""` for the host root.
+     *
+     * Supplied because authorization-server metadata has no mount of its own: RFC 8414 fixes
+     * its address relative to the issuer, so the router works out where to register it and
+     * needs this to translate a host-absolute address into a mount on this app. Getting it
+     * wrong, or mounting an app somewhere that cannot reach the derived address at all, is
+     * refused at registration rather than left to 404 during a client's discovery.
+     */
+    basePath?: string;
+    /** GET: OAuth protected-resource metadata for the MCP endpoint. */
+    protectedResourceMetadata: 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;
+}
+/**
+ * Thrown by `createMcpContext` to refuse a session for a token that authenticated but
+ * cannot act on this resource — a principal whose access to the addressed tenant has
+ * gone away, say.
+ *
+ * The router answers `401` with `error="invalid_token"` rather than letting it surface
+ * as a server fault. The token is intact, so the description is arguable, but the
+ * outcome it produces is the correct one: the condition is durable, and a client that
+ * retries the same credential will fail identically until it re-authorizes.
+ */
+export declare class McpContextUnauthorizedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by `resolveConsentIdentity` when no human is signed in to the product.
+ *
+ * The authorization endpoint answers this by sending the browser to the product's sign-in
+ * page and returning it to the same authorization request, because the condition is one the
+ * user can fix in place. It is deliberately distinct from every other failure that resolver
+ * can raise: those are reported to the OAuth client, and this one is not, since telling a
+ * client "invalid request" for a missing cookie leaves the user with nothing to act on.
+ */
+export declare class McpConsentSignInRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by `resolveConsentIdentity` when a human *is* signed in but may not authorize the
+ * requested resource — no membership in the addressed workspace, say.
+ *
+ * Terminal, unlike `McpConsentSignInRequiredError`: signing in again cannot change the
+ * answer, so the router refuses to the client with `access_denied` rather than looping the
+ * browser through sign-in. The message reaches the client as `error_description`, so it must
+ * not name a resource the caller has not been shown to be entitled to know exists.
+ */
+export declare class McpConsentForbiddenError extends Error {
+    constructor(message?: 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.
+     *
+     * Deliberately carries no actor. Revocation here is always self-revocation — the
+     * caller presents the token — so the product can derive who that is from the token
+     * it stores, in whatever grain it records actors in. Asserting a user id would
+     * impose a grain the product may not use.
+     */
+    revokeOAuthToken(tokenHash: string, input?: {
+        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.
+     *
+     * Throw `McpConsentSignInRequiredError` when no human is signed in, so the router offers
+     * sign-in rather than failing the request, and `McpConsentForbiddenError` when a signed-in
+     * human may not authorize the requested resource. Those two are the only throws whose
+     * message reaches the OAuth client.
+     *
+     * Anything else thrown here is treated as a server fault: the client is told `server_error`
+     * with a fixed description and nothing about the failure. A resolver that reads a database
+     * or an identity provider can throw messages carrying connection strings, internal ids, or
+     * provider detail, and this endpoint hands its errors to whatever redirect URI a
+     * self-registered client supplied.
+     */
+    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.
+     *
+     * May return a promise: a product whose context carries identity beyond the token
+     * — a tenant-scoped actor id, say — has to read it, and doing that once per session
+     * here is cheaper than repeating it inside every tool call.
+     *
+     * Throw `McpContextUnauthorizedError` to refuse the session when that identity cannot
+     * be resolved; anything else thrown here is a server fault and is reported as one.
+     */
+    createMcpContext(input: {
+        token: OAuthTokenRecord<S>;
+        config: McpHonoRuntimeConfig<S>;
+    }): C | Promise<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;
+    /**
+     * Report a server-side fault the router caught and did not tell the client about.
+     *
+     * Supplied by the product because the errors that reach here come from the product's own
+     * identity stack, and are the class most likely to carry a connection string, an internal
+     * id, or provider detail — exactly what a product's logger exists to scrub and route.
+     * Defaults to `console.error`, which keeps the failure visible for a product that has no
+     * logger of its own but is the wrong destination for one that does.
+     */
+    logError?(message: string, error: unknown): void;
+}
+/** 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;