@qelos/integrator-express 4.2.0 → 4.2.2

package/README.md

@@ -160,6 +160,14 @@ import { requireUser } from '@qelos/integrator-express';
 app.get('/private', requireUser((req, res) => res.json(req.qelos.user)));
 ```
 
+## MCP OAuth
+
+When your custom domain serves MCP clients as an OAuth issuer, add `/login` and
+`/mcp/authorize` routes and use the re-exported MCP helpers
+(`resolveMcpLoginRedirect`, `decodeMcpOAuthStatePayload`,
+`completeMcpAuthorizationCallback`, …). See the Qelos docs:
+[MCP OAuth for integrator apps](https://docs.qelos.io/auth/mcp-oauth-integrators).
+
 ## Workspace resolution
 
 `req.qelos.workspace` defaults to whatever the managed Qelos app reports on
@@ -204,7 +212,18 @@ createQelosIntegrator({
 });
 ```
 
-## Requirements
+## Version support
+
+| Runtime | Supported versions |
+|---------|-------------------|
+| Node.js | >= 18 (uses global `fetch` and `Headers.getSetCookie`) |
+| Express | 4.17+ and 5.x |
+
+The integrator is tested against Express 4 and Express 5 in CI (`pnpm --filter
+@qelos/integrator-express test`). Express is a peer dependency — install the
+major version your app already uses; no integrator-specific adapter is required.
 
-- Node.js >= 18 (uses global `fetch` and `Headers.getSetCookie`).
-- Express 4 or 5.
+When upgrading from Express 4 to 5, see the [Express 5 migration
+guide](https://expressjs.com/en/guide/migrating-5.html). This package uses only
+APIs that are stable across both majors (middleware, `req.headers`, response
+headers, and request streaming for the proxy).

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { rewriteSetCookieDomain, rewriteSetCookieDomains } from './cookies';
 export { resolveQelosProxyTarget } from './proxy-target';
 export type { QelosExpressConfig, QelosRequestContext, } from './types';
 export { completeSocialAuthCallback, getSocialAuthSetCookieParts, parseSocialCallbackRefreshToken, type SocialAuthCallbackPayload, type SocialCallbackInput, } from './social-auth';
+export { completeMcpAuthorizationCallback, appendMcpAccessDeniedRedirect, buildMcpAuthorizePath, buildMcpAuthorizePathFromQuery, buildMcpConsentPageUrl, buildMcpLoginRedirectUrl, buildMcpTokenExchangeBody, decodeMcpOAuthStatePayload, parseMcpCallbackParams, resolveMcpLoginRedirect, type CompleteMcpAuthorizationCallbackOptions, type DecodedMcpOAuthStatePayload, type McpAuthorizeOptions, type McpCallbackInput, type McpCallbackParams, type McpPagePathOptions, type McpTokenExchangeOptions, type McpTokenExchangeResult, } from './mcp-auth';
 export interface QelosIntegrator {
     /**
      * User-resolution middleware. Forwards inbound cookies to `/api/me` and

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSocialCallbackRefreshToken = exports.getSocialAuthSetCookieParts = exports.completeSocialAuthCallback = exports.resolveQelosProxyTarget = exports.rewriteSetCookieDomains = exports.rewriteSetCookieDomain = exports.createRequestSdk = exports.createQelosProxy = exports.requireUser = exports.createQelosMiddleware = void 0;
+exports.resolveMcpLoginRedirect = exports.parseMcpCallbackParams = exports.decodeMcpOAuthStatePayload = exports.buildMcpTokenExchangeBody = exports.buildMcpLoginRedirectUrl = exports.buildMcpConsentPageUrl = exports.buildMcpAuthorizePathFromQuery = exports.buildMcpAuthorizePath = exports.appendMcpAccessDeniedRedirect = exports.completeMcpAuthorizationCallback = exports.parseSocialCallbackRefreshToken = exports.getSocialAuthSetCookieParts = exports.completeSocialAuthCallback = exports.resolveQelosProxyTarget = exports.rewriteSetCookieDomains = exports.rewriteSetCookieDomain = exports.createRequestSdk = exports.createQelosProxy = exports.requireUser = exports.createQelosMiddleware = void 0;
 exports.createQelosIntegrator = createQelosIntegrator;
 const middleware_1 = require("./middleware");
 const proxy_1 = require("./proxy");
@@ -20,6 +20,17 @@ var social_auth_1 = require("./social-auth");
 Object.defineProperty(exports, "completeSocialAuthCallback", { enumerable: true, get: function () { return social_auth_1.completeSocialAuthCallback; } });
 Object.defineProperty(exports, "getSocialAuthSetCookieParts", { enumerable: true, get: function () { return social_auth_1.getSocialAuthSetCookieParts; } });
 Object.defineProperty(exports, "parseSocialCallbackRefreshToken", { enumerable: true, get: function () { return social_auth_1.parseSocialCallbackRefreshToken; } });
+var mcp_auth_1 = require("./mcp-auth");
+Object.defineProperty(exports, "completeMcpAuthorizationCallback", { enumerable: true, get: function () { return mcp_auth_1.completeMcpAuthorizationCallback; } });
+Object.defineProperty(exports, "appendMcpAccessDeniedRedirect", { enumerable: true, get: function () { return mcp_auth_1.appendMcpAccessDeniedRedirect; } });
+Object.defineProperty(exports, "buildMcpAuthorizePath", { enumerable: true, get: function () { return mcp_auth_1.buildMcpAuthorizePath; } });
+Object.defineProperty(exports, "buildMcpAuthorizePathFromQuery", { enumerable: true, get: function () { return mcp_auth_1.buildMcpAuthorizePathFromQuery; } });
+Object.defineProperty(exports, "buildMcpConsentPageUrl", { enumerable: true, get: function () { return mcp_auth_1.buildMcpConsentPageUrl; } });
+Object.defineProperty(exports, "buildMcpLoginRedirectUrl", { enumerable: true, get: function () { return mcp_auth_1.buildMcpLoginRedirectUrl; } });
+Object.defineProperty(exports, "buildMcpTokenExchangeBody", { enumerable: true, get: function () { return mcp_auth_1.buildMcpTokenExchangeBody; } });
+Object.defineProperty(exports, "decodeMcpOAuthStatePayload", { enumerable: true, get: function () { return mcp_auth_1.decodeMcpOAuthStatePayload; } });
+Object.defineProperty(exports, "parseMcpCallbackParams", { enumerable: true, get: function () { return mcp_auth_1.parseMcpCallbackParams; } });
+Object.defineProperty(exports, "resolveMcpLoginRedirect", { enumerable: true, get: function () { return mcp_auth_1.resolveMcpLoginRedirect; } });
 /**
  * Build both the user-resolution middleware and the `/api/**` reverse proxy
  * from a single config. When the proxy is enabled (the default), `/api/` is

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAyDA,sDAkBC;AA1ED,6CAAmF;AACnF,mCAA2C;AAG3C,2CAGsB;AAFpB,mHAAA,qBAAqB,OAAA;AACrB,yGAAA,WAAW,OAAA;AAOb,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AAGzB,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AAGzB,qCAA4E;AAAnE,iHAAA,sBAAsB,OAAA;AAAE,kHAAA,uBAAuB,OAAA;AACxD,+CAAyD;AAAhD,uHAAA,uBAAuB,OAAA;AAOhC,6CAMuB;AALrB,yHAAA,0BAA0B,OAAA;AAC1B,0HAAA,2BAA2B,OAAA;AAC3B,8HAAA,+BAA+B,OAAA;AAoBjC;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,OAAgC;IAEhC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,KAAK,IAAI,CAAC;IAE1D,IAAI,MAAM,GAAuB,OAAO,CAAC,MAAM,CAAC;IAChD,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;QACzD,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACtF,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,kCAAqB,EAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,IAAA,wBAAgB,EAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AA8EA,sDAkBC;AA/FD,6CAAmF;AACnF,mCAA2C;AAG3C,2CAGsB;AAFpB,mHAAA,qBAAqB,OAAA;AACrB,yGAAA,WAAW,OAAA;AAOb,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AAGzB,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AAGzB,qCAA4E;AAAnE,iHAAA,sBAAsB,OAAA;AAAE,kHAAA,uBAAuB,OAAA;AACxD,+CAAyD;AAAhD,uHAAA,uBAAuB,OAAA;AAOhC,6CAMuB;AALrB,yHAAA,0BAA0B,OAAA;AAC1B,0HAAA,2BAA2B,OAAA;AAC3B,8HAAA,+BAA+B,OAAA;AAKjC,uCAmBoB;AAlBlB,4HAAA,gCAAgC,OAAA;AAChC,yHAAA,6BAA6B,OAAA;AAC7B,iHAAA,qBAAqB,OAAA;AACrB,0HAAA,8BAA8B,OAAA;AAC9B,kHAAA,sBAAsB,OAAA;AACtB,oHAAA,wBAAwB,OAAA;AACxB,qHAAA,yBAAyB,OAAA;AACzB,sHAAA,0BAA0B,OAAA;AAC1B,kHAAA,sBAAsB,OAAA;AACtB,mHAAA,uBAAuB,OAAA;AA0BzB;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,OAAgC;IAEhC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,KAAK,IAAI,CAAC;IAE1D,IAAI,MAAM,GAAuB,OAAO,CAAC,MAAM,CAAC;IAChD,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;QACzD,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACtF,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,kCAAqB,EAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,IAAA,wBAAgB,EAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}

package/dist/mcp-auth.d.ts

@@ -0,0 +1,12 @@
+import type QelosSDK from '@qelos/sdk';
+import type { McpCallbackInput, McpTokenExchangeResult } from '@qelos/sdk';
+export interface CompleteMcpAuthorizationCallbackOptions {
+    redirectUri: string;
+    codeVerifier: string;
+}
+/**
+ * Parse an MCP OAuth callback and exchange the authorization code for tokens.
+ * Use when your app owns the MCP client callback URL (e.g. a local loopback server).
+ */
+export declare function completeMcpAuthorizationCallback(sdk: QelosSDK, input: McpCallbackInput, options: CompleteMcpAuthorizationCallbackOptions): Promise<McpTokenExchangeResult>;
+export { appendMcpAccessDeniedRedirect, buildMcpAuthorizePath, buildMcpAuthorizePathFromQuery, buildMcpConsentPageUrl, buildMcpLoginRedirectUrl, buildMcpTokenExchangeBody, decodeMcpOAuthStatePayload, parseMcpCallbackParams, resolveMcpLoginRedirect, type DecodedMcpOAuthStatePayload, type McpAuthorizeOptions, type McpCallbackInput, type McpCallbackParams, type McpPagePathOptions, type McpTokenExchangeOptions, type McpTokenExchangeResult, } from '@qelos/sdk';

package/dist/mcp-auth.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMcpLoginRedirect = exports.parseMcpCallbackParams = exports.decodeMcpOAuthStatePayload = exports.buildMcpTokenExchangeBody = exports.buildMcpLoginRedirectUrl = exports.buildMcpConsentPageUrl = exports.buildMcpAuthorizePathFromQuery = exports.buildMcpAuthorizePath = exports.appendMcpAccessDeniedRedirect = void 0;
+exports.completeMcpAuthorizationCallback = completeMcpAuthorizationCallback;
+const sdk_1 = require("@qelos/sdk");
+/**
+ * Parse an MCP OAuth callback and exchange the authorization code for tokens.
+ * Use when your app owns the MCP client callback URL (e.g. a local loopback server).
+ */
+async function completeMcpAuthorizationCallback(sdk, input, options) {
+    const params = (0, sdk_1.parseMcpCallbackParams)(input);
+    if (params.error) {
+        throw new Error(params.errorDescription || params.error);
+    }
+    if (!params.code) {
+        throw new Error('missing authorization code');
+    }
+    return sdk.authentication.exchangeMcpAuthorizationCode({
+        code: params.code,
+        redirectUri: options.redirectUri,
+        codeVerifier: options.codeVerifier,
+    });
+}
+var sdk_2 = require("@qelos/sdk");
+Object.defineProperty(exports, "appendMcpAccessDeniedRedirect", { enumerable: true, get: function () { return sdk_2.appendMcpAccessDeniedRedirect; } });
+Object.defineProperty(exports, "buildMcpAuthorizePath", { enumerable: true, get: function () { return sdk_2.buildMcpAuthorizePath; } });
+Object.defineProperty(exports, "buildMcpAuthorizePathFromQuery", { enumerable: true, get: function () { return sdk_2.buildMcpAuthorizePathFromQuery; } });
+Object.defineProperty(exports, "buildMcpConsentPageUrl", { enumerable: true, get: function () { return sdk_2.buildMcpConsentPageUrl; } });
+Object.defineProperty(exports, "buildMcpLoginRedirectUrl", { enumerable: true, get: function () { return sdk_2.buildMcpLoginRedirectUrl; } });
+Object.defineProperty(exports, "buildMcpTokenExchangeBody", { enumerable: true, get: function () { return sdk_2.buildMcpTokenExchangeBody; } });
+Object.defineProperty(exports, "decodeMcpOAuthStatePayload", { enumerable: true, get: function () { return sdk_2.decodeMcpOAuthStatePayload; } });
+Object.defineProperty(exports, "parseMcpCallbackParams", { enumerable: true, get: function () { return sdk_2.parseMcpCallbackParams; } });
+Object.defineProperty(exports, "resolveMcpLoginRedirect", { enumerable: true, get: function () { return sdk_2.resolveMcpLoginRedirect; } });
+//# sourceMappingURL=mcp-auth.js.map

package/dist/mcp-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-auth.js","sourceRoot":"","sources":["../src/mcp-auth.ts"],"names":[],"mappings":";;;AAaA,4EAkBC;AA7BD,oCAAoD;AAOpD;;;GAGG;AACI,KAAK,UAAU,gCAAgC,CACpD,GAAa,EACb,KAAuB,EACvB,OAAgD;IAEhD,MAAM,MAAM,GAAG,IAAA,4BAAsB,EAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,GAAG,CAAC,cAAc,CAAC,4BAA4B,CAAC;QACrD,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC,CAAC;AACL,CAAC;AAED,kCAiBoB;AAhBlB,oHAAA,6BAA6B,OAAA;AAC7B,4GAAA,qBAAqB,OAAA;AACrB,qHAAA,8BAA8B,OAAA;AAC9B,6GAAA,sBAAsB,OAAA;AACtB,+GAAA,wBAAwB,OAAA;AACxB,gHAAA,yBAAyB,OAAA;AACzB,iHAAA,0BAA0B,OAAA;AAC1B,6GAAA,sBAAsB,OAAA;AACtB,8GAAA,uBAAuB,OAAA"}

package/dist/types.d.ts

@@ -54,13 +54,11 @@ export interface QelosRequestContext {
      */
     sdk: QelosSDK;
 }
-declare module 'express' {
-    interface Request {
-        qelos: QelosRequestContext;
-    }
-}
-declare module 'express-serve-static-core' {
-    interface Request {
-        qelos: QelosRequestContext;
+declare global {
+    namespace Express {
+        interface Request {
+            qelos: QelosRequestContext;
+        }
     }
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/integrator-express",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Express middleware that identifies the Qelos user and active workspace before your route handlers run",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -47,13 +47,13 @@
     }
   },
   "dependencies": {
-    "@qelos/global-types": "4.2.0",
-    "@qelos/sdk": "4.2.0"
+    "@qelos/global-types": "4.2.2",
+    "@qelos/sdk": "4.2.2"
   },
   "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/express-serve-static-core": "^4.19.6",
-    "express": "^4.21.2",
+    "@types/express": "^5.0.0",
+    "express": "^5.0.0",
+    "express4": "npm:express@^4.21.2",
     "tsx": "^4.21.0",
     "typescript": "^5.6.3"
   },
@@ -61,6 +61,8 @@
     "type-check": "tsc --noEmit",
     "build": "tsc",
     "pre-build": "tsc",
-    "test": "node --import tsx --test src/**/*.test.ts test/**/*.test.ts"
+    "test": "pnpm run test:express5 && pnpm run test:express4",
+    "test:express5": "node --import tsx --test src/**/*.test.ts test/middleware.test.ts",
+    "test:express4": "node --import tsx --test test/middleware.express4.test.ts"
   }
 }