@qelos/integrator-express 4.2.0 → 4.2.1

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.1",
   "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",
@@ -23,6 +23,14 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build": "tsc",
+    "pre-build": "tsc",
+    "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"
+  },
   "keywords": [
     "qelos",
     "express",
@@ -47,20 +55,14 @@
     }
   },
   "dependencies": {
-    "@qelos/global-types": "4.2.0",
-    "@qelos/sdk": "4.2.0"
+    "@qelos/global-types": "workspace:*",
+    "@qelos/sdk": "workspace:*"
   },
   "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"
-  },
-  "scripts": {
-    "type-check": "tsc --noEmit",
-    "build": "tsc",
-    "pre-build": "tsc",
-    "test": "node --import tsx --test src/**/*.test.ts test/**/*.test.ts"
   }
-}
+}

package/LICENSE

@@ -1,20 +0,0 @@
-Polyform Shield License 1.0.0
-
-Copyright (c) 2025 Velocitech LTD
-
-Your use of this software is governed by the Polyform Shield License 1.0.0.
-
-You may obtain a copy of the License at:
-https://polyformproject.org/licenses/shield/1.0.0
-
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
-Additional Terms – Exception Notice:
-
-The author of this software grants additional permissions beyond the Polyform Shield License 1.0.0:
-
-✅ All uses of the software are permitted — including modification, distribution, commercial use, and sublicensing — as long as the software is not used to create, offer, or operate any product or service that competes directly with Qelos (https://qelos.io), a no-code platform for building AI-assisted SaaS applications.
-
-❌ "Direct competition" includes platforms, tools, or services that enable users to visually or programmatically create SaaS applications with the assistance of artificial intelligence.
-
-This exception does not modify the terms of the original Polyform Shield License for other users and applies only by explicit permission of the licensor.