From 7ab71c88083ff75822f69cc267e52c2848c9e8c7 Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:37:25 +0530 Subject: [PATCH 01/25] build(deps): adopt MCP SDK v2 packages for 2026-07-28 Replace the monolithic @modelcontextprotocol/sdk with @modelcontextprotocol/server and @modelcontextprotocol/node so Harbor can use createMcpHandler and serveStdio. --- package-lock.json | 825 ++++------------------------------------------ package.json | 3 +- 2 files changed, 59 insertions(+), 769 deletions(-) diff --git a/package-lock.json b/package-lock.json index a7c69a4..0d0d85c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,8 @@ "license": "Apache-2.0", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", - "@modelcontextprotocol/sdk": "^1.27.0", + "@modelcontextprotocol/node": "^2.0.0-beta.4", + "@modelcontextprotocol/server": "^2.0.0-beta.4", "axios": "^1.7.9", "dotenv": "^17.4.2", "gray-matter": "^4.0.3", @@ -806,53 +807,68 @@ "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==", "license": "MIT" }, - "node_modules/@modelcontextprotocol/sdk": { - "version": "1.29.0", - "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz", - "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==", + "node_modules/@modelcontextprotocol/core": { + "version": "2.0.0-beta.4", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0-beta.4.tgz", + "integrity": "sha512-nsMXd4wQBKzmph6r+WOhum+mXjDYljTAqwY/XUg3hLtvNOQ8+JVqBSJOVCMJvx9lXhTpTOPrGZ3BuNiaNPjSvg==", "license": "MIT", "dependencies": { - "@hono/node-server": "^1.19.9", - "ajv": "^8.17.1", - "ajv-formats": "^3.0.1", - "content-type": "^1.0.5", - "cors": "^2.8.5", - "cross-spawn": "^7.0.5", - "eventsource": "^3.0.2", - "eventsource-parser": "^3.0.0", - "express": "^5.2.1", - "express-rate-limit": "^8.2.1", - "hono": "^4.11.4", - "jose": "^6.1.3", - "json-schema-typed": "^8.0.2", - "pkce-challenge": "^5.0.0", - "raw-body": "^3.0.0", - "zod": "^3.25 || ^4.0", - "zod-to-json-schema": "^3.25.1" + "zod": "^4.2.0" }, "engines": { - "node": ">=18" + "node": ">=20" + } + }, + "node_modules/@modelcontextprotocol/core/node_modules/zod": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", + "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/@modelcontextprotocol/node": { + "version": "2.0.0-beta.4", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/node/-/node-2.0.0-beta.4.tgz", + "integrity": "sha512-OqbrRVNYNfLxBB2BRkP5oIHKHa0IPHluMbaLgw7YCRKcj5be9ExzyWFJY3KVMb+1F2AVn+0SRoH0XKcNzh3HYQ==", + "license": "MIT", + "dependencies": { + "@hono/node-server": "^1.19.9" + }, + "engines": { + "node": ">=20" }, "peerDependencies": { - "@cfworker/json-schema": "^4.1.1", - "zod": "^3.25 || ^4.0" + "@modelcontextprotocol/server": "^2.0.0-beta.4", + "hono": "^4.11.4" }, "peerDependenciesMeta": { - "@cfworker/json-schema": { + "hono": { "optional": true - }, - "zod": { - "optional": false } } }, - "node_modules/@modelcontextprotocol/sdk/node_modules/jose": { - "version": "6.2.3", - "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz", - "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==", + "node_modules/@modelcontextprotocol/server": { + "version": "2.0.0-beta.4", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0-beta.4.tgz", + "integrity": "sha512-pjMZcNEt1dOq0aJCcY3b7w1Ayh+qmQN2xlfTELcGV9yiAjEGIczBPBLWWW0k0zzo5T8kiv15jtKPsWeHGxLvLg==", + "license": "MIT", + "dependencies": { + "@modelcontextprotocol/core": "2.0.0-beta.4", + "zod": "^4.2.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@modelcontextprotocol/server/node_modules/zod": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", + "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", "license": "MIT", "funding": { - "url": "https://github.com/sponsors/panva" + "url": "https://github.com/sponsors/colinhacks" } }, "node_modules/@pinojs/redact": { @@ -1673,19 +1689,6 @@ "url": "https://opencollective.com/vitest" } }, - "node_modules/accepts": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", - "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==", - "license": "MIT", - "dependencies": { - "mime-types": "^3.0.0", - "negotiator": "^1.0.0" - }, - "engines": { - "node": ">= 0.6" - } - }, "node_modules/acorn": { "version": "8.16.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz", @@ -1751,23 +1754,6 @@ } } }, - "node_modules/ajv-formats": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", - "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", - "license": "MIT", - "dependencies": { - "ajv": "^8.0.0" - }, - "peerDependencies": { - "ajv": "^8.0.0" - }, - "peerDependenciesMeta": { - "ajv": { - "optional": true - } - } - }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -1865,30 +1851,6 @@ "readable-stream": "^3.4.0" } }, - "node_modules/body-parser": { - "version": "2.2.2", - "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz", - "integrity": "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==", - "license": "MIT", - "dependencies": { - "bytes": "^3.1.2", - "content-type": "^1.0.5", - "debug": "^4.4.3", - "http-errors": "^2.0.0", - "iconv-lite": "^0.7.0", - "on-finished": "^2.4.1", - "qs": "^6.14.1", - "raw-body": "^3.0.1", - "type-is": "^2.0.1" - }, - "engines": { - "node": ">=18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/brace-expansion": { "version": "1.1.14", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", @@ -1931,15 +1893,6 @@ "dev": true, "license": "MIT" }, - "node_modules/bytes": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", - "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/cac": { "version": "6.7.14", "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz", @@ -1963,22 +1916,6 @@ "node": ">= 0.4" } }, - "node_modules/call-bound": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", - "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", - "license": "MIT", - "dependencies": { - "call-bind-apply-helpers": "^1.0.2", - "get-intrinsic": "^1.3.0" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/call-me-maybe": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz", @@ -2091,67 +2028,11 @@ "dev": true, "license": "MIT" }, - "node_modules/content-disposition": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz", - "integrity": "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==", - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, - "node_modules/content-type": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", - "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/cookie": { - "version": "0.7.2", - "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", - "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/cookie-signature": { - "version": "1.2.2", - "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz", - "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==", - "license": "MIT", - "engines": { - "node": ">=6.6.0" - } - }, - "node_modules/cors": { - "version": "2.8.6", - "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz", - "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==", - "license": "MIT", - "dependencies": { - "object-assign": "^4", - "vary": "^1" - }, - "engines": { - "node": ">= 0.10" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/cross-spawn": { "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, "license": "MIT", "dependencies": { "path-key": "^3.1.0", @@ -2239,15 +2120,6 @@ "node": ">=0.4.0" } }, - "node_modules/depd": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", - "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/detect-libc": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", @@ -2283,21 +2155,6 @@ "node": ">= 0.4" } }, - "node_modules/ee-first": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", - "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", - "license": "MIT" - }, - "node_modules/encodeurl": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", - "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/end-of-stream": { "version": "1.4.5", "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz", @@ -2401,12 +2258,6 @@ "@esbuild/win32-x64": "0.27.4" } }, - "node_modules/escape-html": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", - "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", - "license": "MIT" - }, "node_modules/escape-string-regexp": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", @@ -2621,36 +2472,6 @@ "node": ">=0.10.0" } }, - "node_modules/etag": { - "version": "1.8.1", - "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", - "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/eventsource": { - "version": "3.0.7", - "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz", - "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==", - "license": "MIT", - "dependencies": { - "eventsource-parser": "^3.0.1" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/eventsource-parser": { - "version": "3.0.6", - "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.6.tgz", - "integrity": "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==", - "license": "MIT", - "engines": { - "node": ">=18.0.0" - } - }, "node_modules/expand-template": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz", @@ -2670,67 +2491,6 @@ "node": ">=12.0.0" } }, - "node_modules/express": { - "version": "5.2.1", - "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", - "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", - "license": "MIT", - "dependencies": { - "accepts": "^2.0.0", - "body-parser": "^2.2.1", - "content-disposition": "^1.0.0", - "content-type": "^1.0.5", - "cookie": "^0.7.1", - "cookie-signature": "^1.2.1", - "debug": "^4.4.0", - "depd": "^2.0.0", - "encodeurl": "^2.0.0", - "escape-html": "^1.0.3", - "etag": "^1.8.1", - "finalhandler": "^2.1.0", - "fresh": "^2.0.0", - "http-errors": "^2.0.0", - "merge-descriptors": "^2.0.0", - "mime-types": "^3.0.0", - "on-finished": "^2.4.1", - "once": "^1.4.0", - "parseurl": "^1.3.3", - "proxy-addr": "^2.0.7", - "qs": "^6.14.0", - "range-parser": "^1.2.1", - "router": "^2.2.0", - "send": "^1.1.0", - "serve-static": "^2.2.0", - "statuses": "^2.0.1", - "type-is": "^2.0.1", - "vary": "^1.1.2" - }, - "engines": { - "node": ">= 18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, - "node_modules/express-rate-limit": { - "version": "8.5.2", - "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.2.tgz", - "integrity": "sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==", - "license": "MIT", - "dependencies": { - "ip-address": "^10.2.0" - }, - "engines": { - "node": ">= 16" - }, - "funding": { - "url": "https://github.com/sponsors/express-rate-limit" - }, - "peerDependencies": { - "express": ">= 4.11" - } - }, "node_modules/extend-shallow": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz", @@ -2824,27 +2584,6 @@ "node": ">=16.0.0" } }, - "node_modules/finalhandler": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz", - "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==", - "license": "MIT", - "dependencies": { - "debug": "^4.4.0", - "encodeurl": "^2.0.0", - "escape-html": "^1.0.3", - "on-finished": "^2.4.1", - "parseurl": "^1.3.3", - "statuses": "^2.0.1" - }, - "engines": { - "node": ">= 18.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/find-up": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", @@ -2940,24 +2679,6 @@ "node": ">= 0.6" } }, - "node_modules/forwarded": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", - "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/fresh": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz", - "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/fs-constants": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz", @@ -3180,30 +2901,11 @@ "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.30.tgz", "integrity": "sha512-emn+JoJjrN9YTpRDS5it/UI2SO9BAE37T6I3d963RxcZ81G9A4pr2SZTEiiaiKbzx+NKRg5BZ89fCL7gCJCUog==", "license": "MIT", + "peer": true, "engines": { "node": ">=16.9.0" } }, - "node_modules/http-errors": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", - "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", - "license": "MIT", - "dependencies": { - "depd": "~2.0.0", - "inherits": "~2.0.4", - "setprototypeof": "~1.2.0", - "statuses": "~2.0.2", - "toidentifier": "~1.0.1" - }, - "engines": { - "node": ">= 0.8" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/https-proxy-agent": { "version": "5.0.1", "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz", @@ -3217,22 +2919,6 @@ "node": ">= 6" } }, - "node_modules/iconv-lite": { - "version": "0.7.2", - "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz", - "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==", - "license": "MIT", - "dependencies": { - "safer-buffer": ">= 2.1.2 < 3.0.0" - }, - "engines": { - "node": ">=0.10.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/ieee754": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", @@ -3302,24 +2988,6 @@ "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", "license": "ISC" }, - "node_modules/ip-address": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz", - "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==", - "license": "MIT", - "engines": { - "node": ">= 12" - } - }, - "node_modules/ipaddr.js": { - "version": "1.9.1", - "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", - "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", - "license": "MIT", - "engines": { - "node": ">= 0.10" - } - }, "node_modules/is-extendable": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz", @@ -3352,16 +3020,11 @@ "node": ">=0.10.0" } }, - "node_modules/is-promise": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz", - "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==", - "license": "MIT" - }, "node_modules/isexe": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, "license": "ISC" }, "node_modules/isolated-vm": { @@ -3438,12 +3101,6 @@ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", "license": "MIT" }, - "node_modules/json-schema-typed": { - "version": "8.0.2", - "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz", - "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==", - "license": "BSD-2-Clause" - }, "node_modules/json-stable-stringify-without-jsonify": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", @@ -3533,15 +3190,6 @@ "node": ">= 0.4" } }, - "node_modules/media-typer": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz", - "integrity": "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/memjs": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/memjs/-/memjs-1.3.2.tgz", @@ -3551,43 +3199,6 @@ "node": ">=0.10.0" } }, - "node_modules/merge-descriptors": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz", - "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==", - "license": "MIT", - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/mime-db": { - "version": "1.54.0", - "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", - "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/mime-types": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", - "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", - "license": "MIT", - "dependencies": { - "mime-db": "^1.54.0" - }, - "engines": { - "node": ">=18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/mimic-response": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz", @@ -3666,15 +3277,6 @@ "dev": true, "license": "MIT" }, - "node_modules/negotiator": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz", - "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, "node_modules/node-abi": { "version": "3.89.0", "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.89.0.tgz", @@ -3687,27 +3289,6 @@ "node": ">=10" } }, - "node_modules/object-assign": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", - "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/object-inspect": { - "version": "1.13.4", - "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", - "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", - "license": "MIT", - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/on-exit-leak-free": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz", @@ -3717,18 +3298,6 @@ "node": ">=14.0.0" } }, - "node_modules/on-finished": { - "version": "2.4.1", - "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", - "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", - "license": "MIT", - "dependencies": { - "ee-first": "1.1.1" - }, - "engines": { - "node": ">= 0.8" - } - }, "node_modules/once": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", @@ -3808,15 +3377,6 @@ "node": ">=6" } }, - "node_modules/parseurl": { - "version": "1.3.3", - "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", - "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/path-exists": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", @@ -3831,21 +3391,12 @@ "version": "3.1.1", "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, "license": "MIT", "engines": { "node": ">=8" } }, - "node_modules/path-to-regexp": { - "version": "8.4.2", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", - "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", - "license": "MIT", - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, "node_modules/pathe": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz", @@ -3968,15 +3519,6 @@ "integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==", "license": "MIT" }, - "node_modules/pkce-challenge": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz", - "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==", - "license": "MIT", - "engines": { - "node": ">=16.20.0" - } - }, "node_modules/postcss": { "version": "8.5.15", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", @@ -4059,19 +3601,6 @@ ], "license": "MIT" }, - "node_modules/proxy-addr": { - "version": "2.0.7", - "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", - "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", - "license": "MIT", - "dependencies": { - "forwarded": "0.2.0", - "ipaddr.js": "1.9.1" - }, - "engines": { - "node": ">= 0.10" - } - }, "node_modules/proxy-from-env": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz", @@ -4101,51 +3630,12 @@ "node": ">=6" } }, - "node_modules/qs": { - "version": "6.15.2", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz", - "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==", - "license": "BSD-3-Clause", - "dependencies": { - "side-channel": "^1.1.0" - }, - "engines": { - "node": ">=0.6" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/quick-format-unescaped": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz", "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==", "license": "MIT" }, - "node_modules/range-parser": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", - "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/raw-body": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz", - "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==", - "license": "MIT", - "dependencies": { - "bytes": "~3.1.2", - "http-errors": "~2.0.1", - "iconv-lite": "~0.7.0", - "unpipe": "~1.0.0" - }, - "engines": { - "node": ">= 0.10" - } - }, "node_modules/rc": { "version": "1.2.8", "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz", @@ -4267,22 +3757,6 @@ "fsevents": "~2.3.2" } }, - "node_modules/router": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz", - "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==", - "license": "MIT", - "dependencies": { - "debug": "^4.4.0", - "depd": "^2.0.0", - "is-promise": "^4.0.0", - "parseurl": "^1.3.3", - "path-to-regexp": "^8.0.0" - }, - "engines": { - "node": ">= 18" - } - }, "node_modules/safe-buffer": { "version": "5.2.1", "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", @@ -4312,12 +3786,6 @@ "node": ">=10" } }, - "node_modules/safer-buffer": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", - "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", - "license": "MIT" - }, "node_modules/section-matter": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz", @@ -4360,61 +3828,11 @@ "node": ">=10" } }, - "node_modules/send": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz", - "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==", - "license": "MIT", - "dependencies": { - "debug": "^4.4.3", - "encodeurl": "^2.0.0", - "escape-html": "^1.0.3", - "etag": "^1.8.1", - "fresh": "^2.0.0", - "http-errors": "^2.0.1", - "mime-types": "^3.0.2", - "ms": "^2.1.3", - "on-finished": "^2.4.1", - "range-parser": "^1.2.1", - "statuses": "^2.0.2" - }, - "engines": { - "node": ">= 18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, - "node_modules/serve-static": { - "version": "2.2.1", - "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz", - "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==", - "license": "MIT", - "dependencies": { - "encodeurl": "^2.0.0", - "escape-html": "^1.0.3", - "parseurl": "^1.3.3", - "send": "^1.2.0" - }, - "engines": { - "node": ">= 18" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/express" - } - }, - "node_modules/setprototypeof": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", - "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", - "license": "ISC" - }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, "license": "MIT", "dependencies": { "shebang-regex": "^3.0.0" @@ -4427,83 +3845,12 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, "license": "MIT", "engines": { "node": ">=8" } }, - "node_modules/side-channel": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", - "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==", - "license": "MIT", - "dependencies": { - "es-errors": "^1.3.0", - "object-inspect": "^1.13.3", - "side-channel-list": "^1.0.0", - "side-channel-map": "^1.0.1", - "side-channel-weakmap": "^1.0.2" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, - "node_modules/side-channel-list": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz", - "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==", - "license": "MIT", - "dependencies": { - "es-errors": "^1.3.0", - "object-inspect": "^1.13.3" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, - "node_modules/side-channel-map": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", - "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", - "license": "MIT", - "dependencies": { - "call-bound": "^1.0.2", - "es-errors": "^1.3.0", - "get-intrinsic": "^1.2.5", - "object-inspect": "^1.13.3" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, - "node_modules/side-channel-weakmap": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", - "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", - "license": "MIT", - "dependencies": { - "call-bound": "^1.0.2", - "es-errors": "^1.3.0", - "get-intrinsic": "^1.2.5", - "object-inspect": "^1.13.3", - "side-channel-map": "^1.0.1" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/siginfo": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz", @@ -4618,15 +3965,6 @@ "dev": true, "license": "MIT" }, - "node_modules/statuses": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", - "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/std-env": { "version": "3.10.0", "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz", @@ -4789,15 +4127,6 @@ "node": ">=14.0.0" } }, - "node_modules/toidentifier": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", - "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", - "license": "MIT", - "engines": { - "node": ">=0.6" - } - }, "node_modules/ts-api-utils": { "version": "2.5.0", "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz", @@ -4856,20 +4185,6 @@ "node": ">= 0.8.0" } }, - "node_modules/type-is": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz", - "integrity": "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==", - "license": "MIT", - "dependencies": { - "content-type": "^1.0.5", - "media-typer": "^1.1.0", - "mime-types": "^3.0.0" - }, - "engines": { - "node": ">= 0.6" - } - }, "node_modules/typescript": { "version": "5.9.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", @@ -4915,15 +4230,6 @@ "dev": true, "license": "MIT" }, - "node_modules/unpipe": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", - "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/uri-js": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", @@ -4953,15 +4259,6 @@ "uuid": "dist/esm/bin/uuid" } }, - "node_modules/vary": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", - "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, "node_modules/vite": { "version": "7.3.6", "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.6.tgz", @@ -5137,6 +4434,7 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, "license": "ISC", "dependencies": { "isexe": "^2.0.0" @@ -5202,15 +4500,6 @@ "funding": { "url": "https://github.com/sponsors/colinhacks" } - }, - "node_modules/zod-to-json-schema": { - "version": "3.25.2", - "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", - "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", - "license": "ISC", - "peerDependencies": { - "zod": "^3.25.28 || ^4" - } } } } diff --git a/package.json b/package.json index 4bb7f92..9926fad 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,8 @@ }, "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", - "@modelcontextprotocol/sdk": "^1.27.0", + "@modelcontextprotocol/node": "^2.0.0-beta.4", + "@modelcontextprotocol/server": "^2.0.0-beta.4", "axios": "^1.7.9", "dotenv": "^17.4.2", "gray-matter": "^4.0.3", From 1af8aa37814aabd82b6376d65516f6e1d5cce41e Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:37:36 +0530 Subject: [PATCH 02/25] refactor(tools): migrate tool layer to @modelcontextprotocol/server Switch McpServer imports to the v2 package and read correlation/session ids from ServerContext instead of the legacy SDK extra bag. --- tools/discover-services.tool.ts | 2 +- tools/discover-skills.tool.ts | 6 +++--- tools/execute-api.tool.ts | 8 ++++---- tools/get-skill-details.tool.ts | 6 +++--- tools/search-code.tool.ts | 6 +++--- tools/tool-helpers.ts | 25 ++++++++++--------------- 6 files changed, 24 insertions(+), 29 deletions(-) diff --git a/tools/discover-services.tool.ts b/tools/discover-services.tool.ts index 2c7db8a..5ff24de 100644 --- a/tools/discover-services.tool.ts +++ b/tools/discover-services.tool.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { McpServer } from '@modelcontextprotocol/server' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' import type { MetricsCollector } from '../core/types/metrics.types.js' diff --git a/tools/discover-skills.tool.ts b/tools/discover-skills.tool.ts index a6f7c21..08f6c35 100644 --- a/tools/discover-skills.tool.ts +++ b/tools/discover-skills.tool.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { McpServer } from '@modelcontextprotocol/server' import { z } from 'zod' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' @@ -72,8 +72,8 @@ After finding the relevant skill, use get_skill_details() to read the full SOP.` server.registerTool( TOOL.DISCOVER_SKILLS, { description: DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, - async ({ service, code }, extra) => { - const correlationId = extractCorrelationId(extra) + async ({ service, code }, ctx) => { + const correlationId = extractCorrelationId(ctx) logger.info( { correlationId, tool: TOOL.DISCOVER_SKILLS, service, codeReceived: code }, diff --git a/tools/execute-api.tool.ts b/tools/execute-api.tool.ts index 628f966..abe0857 100644 --- a/tools/execute-api.tool.ts +++ b/tools/execute-api.tool.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { McpServer } from '@modelcontextprotocol/server' import { z } from 'zod' import { v4 as uuidv4 } from 'uuid' import { createHash } from 'node:crypto' @@ -123,9 +123,9 @@ async () => { server.registerTool( TOOL.API_EXECUTE, { description: EXECUTE_DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, - async ({ service, code }, extra) => { - const correlationId = extractCorrelationId(extra) - const sessionId = extractSessionId(extra) + async ({ service, code }, ctx) => { + const correlationId = extractCorrelationId(ctx) + const sessionId = extractSessionId(ctx) logger.info( { correlationId, tool: TOOL.API_EXECUTE, service }, diff --git a/tools/get-skill-details.tool.ts b/tools/get-skill-details.tool.ts index 1fcfb29..87fc062 100644 --- a/tools/get-skill-details.tool.ts +++ b/tools/get-skill-details.tool.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { McpServer } from '@modelcontextprotocol/server' import { z } from 'zod' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' @@ -34,8 +34,8 @@ export function registerGetSkillDetailsTool( server.registerTool( TOOL.GET_SKILL_DETAILS, { description: DESCRIPTION, inputSchema: { service: z.string(), skill_id: z.string() } }, - async ({ service, skill_id }, extra) => { - const correlationId = extractCorrelationId(extra) + async ({ service, skill_id }, ctx) => { + const correlationId = extractCorrelationId(ctx) logger.info( { correlationId, tool: TOOL.GET_SKILL_DETAILS, service, skill_id }, diff --git a/tools/search-code.tool.ts b/tools/search-code.tool.ts index 023127c..11bfd12 100644 --- a/tools/search-code.tool.ts +++ b/tools/search-code.tool.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import { McpServer } from '@modelcontextprotocol/server' import { z } from 'zod' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' @@ -91,8 +91,8 @@ This keeps each search result small and readable.` server.registerTool( TOOL.SEARCH_CODE, { description: SEARCH_CODE_DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, - async ({ service, code }, extra) => { - const correlationId = extractCorrelationId(extra) + async ({ service, code }, ctx) => { + const correlationId = extractCorrelationId(ctx) logger.info( { correlationId, tool: TOOL.SEARCH_CODE, service, codeReceived: code }, diff --git a/tools/tool-helpers.ts b/tools/tool-helpers.ts index 6b23e93..0ff3bc0 100644 --- a/tools/tool-helpers.ts +++ b/tools/tool-helpers.ts @@ -21,15 +21,7 @@ export type ToolResponse = { isError?: boolean } & Record -/** - * Shape of the `extra` bag the MCP SDK passes to tool handlers. Only the - * fields the gateway actually reads are declared — the SDK may attach more - * but we don't depend on them. - */ -export interface McpToolExtra { - correlationId?: string - sessionId?: string -} +import type { ServerContext } from '@modelcontextprotocol/server' /** * Builds the standard `isError` MCP tool response. The on-wire payload always @@ -65,14 +57,17 @@ export function mcpSuccess(data: unknown): ToolResponse { } } -/** Reads `correlationId` off the MCP `extra` bag, falling back to a fresh UUID. */ -export function extractCorrelationId(extra: unknown): string { - return (extra as McpToolExtra | undefined)?.correlationId ?? crypto.randomUUID() +/** Reads correlation id from the MCP handler context, falling back to a fresh UUID. */ +export function extractCorrelationId(ctx: unknown): string { + const serverCtx = ctx as ServerContext | undefined + const id = serverCtx?.mcpReq?.id + if (id !== undefined && id !== null) return String(id) + return crypto.randomUUID() } -/** Reads `sessionId` off the MCP `extra` bag, falling back to a fresh UUID. */ -export function extractSessionId(extra: unknown): string { - return (extra as McpToolExtra | undefined)?.sessionId ?? crypto.randomUUID() +/** Reads session id from the MCP handler context, falling back to a fresh UUID. */ +export function extractSessionId(ctx: unknown): string { + return (ctx as ServerContext | undefined)?.sessionId ?? crypto.randomUUID() } export function resolveService( From fe1e181fdb6f61c390a8e2b1725931dd0663b1e5 Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:37:54 +0530 Subject: [PATCH 03/25] refactor(runtime): adopt createMcpHandler and serveStdio for 2026-07-28 Replace hand-wired v1 Streamable HTTP transport with SDK v2 createMcpHandler (legacy: reject) and toNodeHandler. Extract shared McpServerFactory for HTTP and stdio; bearer auth attaches pass-through authInfo before MCP dispatch. --- runtime/http/http-gateway.ts | 60 +++++++++++++----------------- runtime/http/mcp-server-factory.ts | 45 ++++++++++++++++++++++ runtime/server-factory.ts | 33 ++++++---------- runtime/transport/stdio-gateway.ts | 22 +++++------ 4 files changed, 93 insertions(+), 67 deletions(-) create mode 100644 runtime/http/mcp-server-factory.ts diff --git a/runtime/http/http-gateway.ts b/runtime/http/http-gateway.ts index 5a2fb8a..ec4bd07 100644 --- a/runtime/http/http-gateway.ts +++ b/runtime/http/http-gateway.ts @@ -2,8 +2,8 @@ // Copyright 2026 Contributors to the Harbor project. import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' -import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js' +import { createMcpHandler, type AuthInfo } from '@modelcontextprotocol/server' +import { toNodeHandler, type NodeMcpRequestHandler } from '@modelcontextprotocol/node' import type { Logger } from '../observability/logger.js' import type { ServiceRegistry } from '../registry/service-registry.js' import type { OAuthResourceConfig } from '../../core/types/oauth.types.js' @@ -13,11 +13,15 @@ import { sendJson, sendGatewayError } from './send-response.js' import { HttpError } from './http-error.js' import { ERR, HTTP_ROUTES } from '../../core/constants.js' import { errorMessage } from '../../core/utils/errors.js' +import type { McpServerFactory } from './mcp-server-factory.js' + +/** Node request with pass-through auth for {@linkcode toNodeHandler}. */ +type AuthenticatedIncomingMessage = IncomingMessage & { auth?: AuthInfo } export interface HttpGatewayOptions { host: string port: number - createMcpServer: (clientToken: string) => McpServer + createMcpServer: McpServerFactory registry: ServiceRegistry logger: Logger oauthConfig?: OAuthResourceConfig @@ -32,13 +36,17 @@ export interface HttpGatewayHandle { * Creates and starts the Streamable-HTTP MCP gateway. * * This module owns the HTTP surface end-to-end: routing, bearer-auth - * extraction, and stateless per-request MCP transport handling. The boot + * extraction, and stateless per-request MCP handler dispatch via the SDK v2 + * `createMcpHandler` entry (`legacy: 'reject'` — 2026-07-28 only). The boot * logic in `server-factory.ts` depends only on the returned handle — it does - * not need to know about `node:http` or the SDK transport. + * not need to know about `node:http` or transport wiring. */ export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { const { host, port, createMcpServer, registry, logger, oauthConfig } = opts + const mcpHandler = createMcpHandler(createMcpServer, { legacy: 'reject' }) + const nodeMcpHandler = toNodeHandler(mcpHandler) + const server = createServer(async (req, res) => { try { const url = req.url ?? '/' @@ -64,7 +72,7 @@ export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { } if (url === HTTP_ROUTES.MCP) { - await handleAuthenticatedMcpRequest(req, res, createMcpServer, logger, oauthConfig) + await handleAuthenticatedMcpRequest(req, res, nodeMcpHandler, logger, oauthConfig) return } @@ -107,7 +115,7 @@ export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { health: `http://${host}:${port}${HTTP_ROUTES.HEALTH}`, services: registry.serviceNames() }, - '🚀 Harbor ready (Streamable HTTP) — waiting for Clients to connect' + '🚀 Harbor ready (Streamable HTTP, MCP 2026-07-28) — waiting for Clients to connect' ) }) @@ -115,16 +123,15 @@ export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { } /** - * Handles a request on the `/mcp` route using a fresh stateless transport and - * McpServer per HTTP request (`sessionIdGenerator: undefined`). - * - * Auth failures throw {@link HttpError}; only the transport itself owns the + * Validates bearer auth, attaches pass-through {@link AuthInfo} on the Node + * request (consumed by {@linkcode toNodeHandler}), and delegates to the MCP + * handler. Auth failures throw {@link HttpError}; the MCP handler owns the * response stream on the happy path. */ async function handleAuthenticatedMcpRequest( req: IncomingMessage, res: ServerResponse, - createMcpServer: (clientToken: string) => McpServer, + nodeMcpHandler: NodeMcpRequestHandler, logger: Logger, oauthConfig?: OAuthResourceConfig ): Promise { @@ -137,32 +144,17 @@ async function handleAuthenticatedMcpRequest( throw new HttpError(status, extracted.error.code, body.error, { reason: body.reason }, { reason: extracted.reason }, headers) } - const clientToken = extracted.token - const transport = new StreamableHTTPServerTransport({ - sessionIdGenerator: undefined - }) - let mcpServer: McpServer | undefined - - let cleanedUp = false - const cleanup = (): void => { - if (cleanedUp) return - cleanedUp = true - void transport.close?.().catch((err) => { - logger.warn({ error: errorMessage(err) }, 'Stateless transport close failed') - }) - void mcpServer?.close().catch((err) => { - logger.warn({ error: errorMessage(err) }, 'Stateless McpServer close failed') - }) + const authReq = req as AuthenticatedIncomingMessage + authReq.auth = { + token: extracted.token, + clientId: 'harbor-client', + scopes: [] } - res.on('close', cleanup) - try { - mcpServer = createMcpServer(clientToken) - await mcpServer.connect(transport) - await transport.handleRequest(req, res) + await nodeMcpHandler(authReq, res) } catch (err) { - cleanup() + logger.warn({ error: errorMessage(err) }, 'MCP handler dispatch failed') throw err } } diff --git a/runtime/http/mcp-server-factory.ts b/runtime/http/mcp-server-factory.ts new file mode 100644 index 0000000..94294d8 --- /dev/null +++ b/runtime/http/mcp-server-factory.ts @@ -0,0 +1,45 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import { McpServer, type McpRequestContext } from '@modelcontextprotocol/server' +import type { GlobalConfig } from '../../core/types/config.types.js' +import type { Logger } from '../observability/logger.js' +import type { MetricsCollector } from '../../core/types/metrics.types.js' +import type { ServiceRegistry } from '../registry/service-registry.js' +import { registerDiscoverServicesTool } from '../../tools/discover-services.tool.js' +import { registerDiscoverSkillsTool } from '../../tools/discover-skills.tool.js' +import { registerGetSkillDetailsTool } from '../../tools/get-skill-details.tool.js' +import { registerSearchCodeTool } from '../../tools/search-code.tool.js' +import { registerExecuteApiTool } from '../../tools/execute-api.tool.js' +import { GATEWAY_NAME } from '../../core/constants.js' + +/** Factory signature shared by HTTP (`createMcpHandler`) and stdio (`serveStdio`). */ +export type McpServerFactory = (ctx: McpRequestContext) => McpServer + +export interface BuildMcpServerFactoryOptions { + registry: ServiceRegistry + globalConfig: GlobalConfig + logger: Logger + metrics: MetricsCollector + /** Fallback token for stdio transport where `ctx.authInfo` is never set. */ + stdioToken?: string +} + +/** + * Builds a per-request MCP server factory. HTTP mode reads the validated bearer + * from `ctx.authInfo`; stdio mode falls back to the pre-configured token. + */ +export function buildMcpServerFactory(opts: BuildMcpServerFactoryOptions): McpServerFactory { + const { registry, globalConfig, logger, metrics, stdioToken = '' } = opts + + return (ctx: McpRequestContext) => { + const clientToken = ctx.authInfo?.token ?? stdioToken + const mcpServer = new McpServer({ name: GATEWAY_NAME, version: '1.0.0' }) + registerDiscoverServicesTool(mcpServer, registry, logger, metrics) + registerDiscoverSkillsTool(mcpServer, registry, logger, metrics, clientToken) + registerGetSkillDetailsTool(mcpServer, registry, logger, metrics, clientToken) + registerSearchCodeTool(mcpServer, registry, logger, metrics, clientToken) + registerExecuteApiTool(mcpServer, registry, globalConfig, logger, metrics, clientToken) + return mcpServer + } +} diff --git a/runtime/server-factory.ts b/runtime/server-factory.ts index 30559a8..8058c1e 100644 --- a/runtime/server-factory.ts +++ b/runtime/server-factory.ts @@ -1,20 +1,15 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' import type { GlobalConfig } from '../core/types/config.types.js' import { createLogger } from './observability/logger.js' import { MetricsRegistry } from './observability/metrics.js' import { ServiceRegistry } from './registry/service-registry.js' import { scanServicesDirectory } from './registry/filesystem-scanner.js' -import { registerDiscoverServicesTool } from '../tools/discover-services.tool.js' -import { registerDiscoverSkillsTool } from '../tools/discover-skills.tool.js' -import { registerGetSkillDetailsTool } from '../tools/get-skill-details.tool.js' -import { registerSearchCodeTool } from '../tools/search-code.tool.js' -import { registerExecuteApiTool } from '../tools/execute-api.tool.js' import { buildTokenCacheStrategy } from './gateway/strategy-builders.js' import { buildServiceResources } from './gateway/service-resources-factory.js' import { startHttpGateway } from './http/http-gateway.js' +import { buildMcpServerFactory } from './http/mcp-server-factory.js' import { startStdioGateway } from './transport/stdio-gateway.js' import { GATEWAY_NAME, STORE_TYPE } from '../core/constants.js' import { errorMessage } from '../core/utils/errors.js' @@ -68,19 +63,17 @@ export async function createMcpGateway( } gatewayLogger.info({ services: registry.serviceNames() }, 'All services registered in gateway') - // ── 4. Factory: fresh McpServer per HTTP request (stateless transport) ── - function createMcpServer(clientToken: string): McpServer { - const mcpServer = new McpServer({ name: GATEWAY_NAME, version: '1.0.0' }) - registerDiscoverServicesTool(mcpServer, registry, gatewayLogger, gatewayMetrics) - registerDiscoverSkillsTool(mcpServer, registry, gatewayLogger, gatewayMetrics, clientToken) - registerGetSkillDetailsTool(mcpServer, registry, gatewayLogger, gatewayMetrics, clientToken) - registerSearchCodeTool(mcpServer, registry, gatewayLogger, gatewayMetrics, clientToken) - registerExecuteApiTool(mcpServer, registry, globalConfig, gatewayLogger, gatewayMetrics, clientToken) - return mcpServer - } - - // ── 5. Transport — Streamable HTTP (default) or stdio ─────────────────── + // ── 4. Transport mode ─────────────────────────────────────────────────── const transportMode = globalConfig.mcp.transport + const stdioPat = globalConfig.mcp.token ?? '' + + const createMcpServer = buildMcpServerFactory({ + registry, + globalConfig, + logger: gatewayLogger, + metrics: gatewayMetrics, + stdioToken: transportMode === 'stdio' ? stdioPat : undefined + }) // Shared shutdown tail. Both transports must tear down cache, registry, // and metrics in the same order; any transport-specific teardown (e.g. @@ -111,15 +104,13 @@ export async function createMcpGateway( return } - // stdio - const stdioPat = globalConfig.mcp.token ?? '' if (!stdioPat) { gatewayLogger.error('MCP_TOKEN env var required for stdio transport — exiting') process.exit(1) } await startStdioGateway({ - clientToken: stdioPat, createMcpServer, registry, logger: gatewayLogger + createMcpServer, registry, logger: gatewayLogger }) process.on('SIGTERM', shutdownShared) diff --git a/runtime/transport/stdio-gateway.ts b/runtime/transport/stdio-gateway.ts index e4f7949..64b37b9 100644 --- a/runtime/transport/stdio-gateway.ts +++ b/runtime/transport/stdio-gateway.ts @@ -1,27 +1,25 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' -import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' +import { serveStdio } from '@modelcontextprotocol/server/stdio' import type { Logger } from '../observability/logger.js' import type { ServiceRegistry } from '../registry/service-registry.js' +import type { McpServerFactory } from '../http/mcp-server-factory.js' export interface StdioGatewayOptions { - /** Pre-authenticated personal access token. In stdio mode auth is established once, out-of-band. */ - clientToken: string - createMcpServer: (clientToken: string) => McpServer + createMcpServer: McpServerFactory registry: ServiceRegistry logger: Logger } /** - * Boots the MCP gateway on stdio. Unlike HTTP there is no session map — - * the process itself *is* the session, and the token is supplied by the - * launching parent (`MCP_TOKEN` env var). + * Boots the MCP gateway on stdio using the SDK v2 `serveStdio` entry + * (`legacy: 'reject'` — 2026-07-28 only). Unlike HTTP there is no session + * map — the process itself *is* the connection, and the token is supplied by + * the launching parent (`MCP_TOKEN` env var) via the factory fallback. */ export async function startStdioGateway(opts: StdioGatewayOptions): Promise { - const { clientToken, createMcpServer, registry, logger } = opts - const transport = new StdioServerTransport() - await createMcpServer(clientToken).connect(transport) - logger.info({ services: registry.serviceNames() }, 'Harbor ready (stdio)') + const { createMcpServer, registry, logger } = opts + serveStdio(createMcpServer, { legacy: 'reject' }) + logger.info({ services: registry.serviceNames() }, 'Harbor ready (stdio, MCP 2026-07-28)') } From 772f9ab008806e8e79852d8ca9f4fb0fe5932a5b Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:38:06 +0530 Subject: [PATCH 04/25] test(unit): update tests for MCP SDK v2 handler wiring Mock createMcpHandler and toNodeHandler in http-gateway tests, migrate tool test imports, and align correlation/session extractors with ServerContext. --- tests/unit/discover-services.tool.test.ts | 2 +- tests/unit/discover-skills.tool.test.ts | 2 +- tests/unit/execute-api.tool.test.ts | 2 +- tests/unit/get-skill-details.tool.test.ts | 2 +- tests/unit/http-gateway.test.ts | 72 +++++++++-------------- tests/unit/search-code.tool.test.ts | 2 +- tests/unit/tool-helpers.test.ts | 6 +- 7 files changed, 37 insertions(+), 51 deletions(-) diff --git a/tests/unit/discover-services.tool.test.ts b/tests/unit/discover-services.tool.test.ts index ca9b74a..5ab51d5 100644 --- a/tests/unit/discover-services.tool.test.ts +++ b/tests/unit/discover-services.tool.test.ts @@ -6,7 +6,7 @@ import pino from 'pino' import { registerDiscoverServicesTool } from '../../tools/discover-services.tool.js' import { TOOL, METRIC, OUTCOME } from '../../core/constants.js' import type { ServiceRegistry } from '../../runtime/registry/service-registry.js' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { McpServer } from '@modelcontextprotocol/server' import type { MetricsRegistry } from '../../runtime/observability/metrics.js' const silentLogger = pino({ level: 'silent' }) diff --git a/tests/unit/discover-skills.tool.test.ts b/tests/unit/discover-skills.tool.test.ts index a1452ea..169d69a 100644 --- a/tests/unit/discover-skills.tool.test.ts +++ b/tests/unit/discover-skills.tool.test.ts @@ -12,7 +12,7 @@ import { runSkillsSearchInSandbox } from '../../runtime/sandbox/skills-search-in import { registerDiscoverSkillsTool } from '../../tools/discover-skills.tool.js' import { TOOL, METRIC, OUTCOME, ERR, AUTH_SCHEME } from '../../core/constants.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { McpServer } from '@modelcontextprotocol/server' import type { MetricsRegistry } from '../../runtime/observability/metrics.js' import type { TokenPayload } from '../../core/types/auth.types.js' import { MissingTokenError } from '../../core/types/auth.types.js' diff --git a/tests/unit/execute-api.tool.test.ts b/tests/unit/execute-api.tool.test.ts index 0cc8a49..9c6cb76 100644 --- a/tests/unit/execute-api.tool.test.ts +++ b/tests/unit/execute-api.tool.test.ts @@ -23,7 +23,7 @@ import { ProgressCollector } from '../../runtime/observability/progress.js' import { registerExecuteApiTool } from '../../tools/execute-api.tool.js' import { TOOL, METRIC, OUTCOME, ERR, ENV } from '../../core/constants.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { McpServer } from '@modelcontextprotocol/server' import type { MetricsRegistry } from '../../runtime/observability/metrics.js' import type { GlobalConfig } from '../../core/types/config.types.js' import type { TokenPayload } from '../../core/types/auth.types.js' diff --git a/tests/unit/get-skill-details.tool.test.ts b/tests/unit/get-skill-details.tool.test.ts index d758514..65ca373 100644 --- a/tests/unit/get-skill-details.tool.test.ts +++ b/tests/unit/get-skill-details.tool.test.ts @@ -6,7 +6,7 @@ import pino from 'pino' import { registerGetSkillDetailsTool } from '../../tools/get-skill-details.tool.js' import { TOOL, METRIC, OUTCOME, ERR } from '../../core/constants.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { McpServer } from '@modelcontextprotocol/server' import type { MetricsRegistry } from '../../runtime/observability/metrics.js' import type { TokenPayload } from '../../core/types/auth.types.js' import { MissingTokenError, SessionExpiredError } from '../../core/types/auth.types.js' diff --git a/tests/unit/http-gateway.test.ts b/tests/unit/http-gateway.test.ts index e69b01b..79ab49b 100644 --- a/tests/unit/http-gateway.test.ts +++ b/tests/unit/http-gateway.test.ts @@ -3,19 +3,19 @@ import { describe, it, expect, afterEach, vi } from 'vitest' import type { AddressInfo } from 'node:net' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { AuthInfo } from '@modelcontextprotocol/server' import { ERR } from '../../core/constants.js' -const { mockHandleRequest, mockTransportClose } = vi.hoisted(() => ({ - mockHandleRequest: vi.fn(), - mockTransportClose: vi.fn().mockResolvedValue(undefined) +const { mockNodeMcpHandler } = vi.hoisted(() => ({ + mockNodeMcpHandler: vi.fn() })) -vi.mock('@modelcontextprotocol/sdk/server/streamableHttp.js', () => ({ - StreamableHTTPServerTransport: vi.fn().mockImplementation(() => ({ - handleRequest: mockHandleRequest, - close: mockTransportClose - })) +vi.mock('@modelcontextprotocol/server', () => ({ + createMcpHandler: vi.fn(() => ({ fetch: vi.fn() })) +})) + +vi.mock('@modelcontextprotocol/node', () => ({ + toNodeHandler: vi.fn(() => mockNodeMcpHandler) })) import { startHttpGateway, type HttpGatewayHandle } from '../../runtime/http/http-gateway.js' @@ -24,10 +24,9 @@ import type { Logger } from '../../runtime/observability/logger.js' /** * The gateway is tested end-to-end against a real `node:http` listener on an - * ephemeral port. Routes that never reach `transport.handleRequest` (health, - * 404s, and every auth rejection path) can be asserted without any MCP SDK - * plumbing because the gateway short-circuits before handing off to the - * transport. + * ephemeral port. Routes that never reach the MCP handler (health, 404s, and + * every auth rejection path) can be asserted without any SDK plumbing because + * the gateway short-circuits before delegating to `toNodeHandler`. */ function makeLogger(): Logger { @@ -69,6 +68,7 @@ describe('startHttpGateway', () => { let cleanup: (() => Promise) | null = null afterEach(async () => { + mockNodeMcpHandler.mockReset() if (cleanup) { await cleanup() cleanup = null @@ -98,20 +98,14 @@ describe('startHttpGateway', () => { expect(body.code).toBe(ERR.NOT_FOUND) }) - it('POST /mcp without Authorization is rejected before creating a server', async () => { - let createMcpServerCalled = false - const { baseUrl, close } = await startForTest({ - createMcpServer: () => { - createMcpServerCalled = true - throw new Error('should not reach createMcpServer') - } - }) + it('POST /mcp without Authorization is rejected before MCP dispatch', async () => { + const { baseUrl, close } = await startForTest() cleanup = close const res = await fetch(`${baseUrl}/mcp`, { method: 'POST' }) expect(res.status).toBeGreaterThanOrEqual(400) expect(res.status).toBeLessThan(500) - expect(createMcpServerCalled).toBe(false) + expect(mockNodeMcpHandler).not.toHaveBeenCalled() const body = await res.json() as { code: string } expect(body.code).toBe(ERR.MISSING_TOKEN) }) @@ -147,27 +141,19 @@ describe('startHttpGateway', () => { expect(body.code).toBe(ERR.INTERNAL) }) - it('POST /mcp with valid bearer connects transport, handles request, and cleans up', async () => { - mockHandleRequest.mockReset() - mockTransportClose.mockClear() - - let capturedToken = '' - const mockConnect = vi.fn().mockResolvedValue(undefined) - const mockServerClose = vi.fn().mockResolvedValue(undefined) - - mockHandleRequest.mockImplementation(async (_req, res) => { + it('POST /mcp with valid bearer attaches authInfo and delegates to the MCP handler', async () => { + mockNodeMcpHandler.mockImplementation(async (req, res) => { res.statusCode = 200 res.setHeader('content-type', 'application/json') res.end(JSON.stringify({ ok: true })) }) + let factoryCalled = false const { baseUrl, close } = await startForTest({ - createMcpServer: (clientToken: string) => { - capturedToken = clientToken - return { - connect: mockConnect, - close: mockServerClose - } as unknown as McpServer + createMcpServer: (ctx) => { + factoryCalled = true + expect(ctx.authInfo?.token).toBeDefined() + return {} as never } }) cleanup = close @@ -179,12 +165,12 @@ describe('startHttpGateway', () => { }) expect(res.status).toBe(200) - expect(capturedToken).toBe(testToken) - expect(mockConnect).toHaveBeenCalledTimes(1) - expect(mockHandleRequest).toHaveBeenCalledTimes(1) + expect(mockNodeMcpHandler).toHaveBeenCalledTimes(1) - await new Promise(resolve => setTimeout(resolve, 20)) - expect(mockServerClose).toHaveBeenCalledTimes(1) - expect(mockTransportClose).toHaveBeenCalledTimes(1) + const [req] = mockNodeMcpHandler.mock.calls[0] as [{ auth?: AuthInfo }] + expect(req.auth?.token).toBe(testToken) + // Factory is invoked by createMcpHandler at handler construction time in + // production; here we only assert auth passthrough on the Node request. + expect(factoryCalled).toBe(false) }) }) diff --git a/tests/unit/search-code.tool.test.ts b/tests/unit/search-code.tool.test.ts index 3138bdb..7eb6147 100644 --- a/tests/unit/search-code.tool.test.ts +++ b/tests/unit/search-code.tool.test.ts @@ -12,7 +12,7 @@ import { runSpecSearchInSandbox } from '../../runtime/sandbox/spec-search-in-san import { registerSearchCodeTool } from '../../tools/search-code.tool.js' import { TOOL, METRIC, OUTCOME, ERR } from '../../core/constants.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' -import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' +import type { McpServer } from '@modelcontextprotocol/server' import type { MetricsRegistry } from '../../runtime/observability/metrics.js' import type { TokenPayload } from '../../core/types/auth.types.js' import { MissingTokenError } from '../../core/types/auth.types.js' diff --git a/tests/unit/tool-helpers.test.ts b/tests/unit/tool-helpers.test.ts index 160b8f0..2541c64 100644 --- a/tests/unit/tool-helpers.test.ts +++ b/tests/unit/tool-helpers.test.ts @@ -51,8 +51,8 @@ function makeMetrics() { } describe('tool-helpers extractors', () => { - it('extractCorrelationId returns the provided id', () => { - expect(extractCorrelationId({ correlationId: 'abc' })).toBe('abc') + it('extractCorrelationId returns the MCP request id', () => { + expect(extractCorrelationId({ mcpReq: { id: 'abc' } })).toBe('abc') }) it('extractCorrelationId falls back to a uuid when absent', () => { @@ -60,7 +60,7 @@ describe('tool-helpers extractors', () => { expect(id).toMatch(/^[0-9a-f-]{36}$/) }) - it('extractSessionId returns the provided id', () => { + it('extractSessionId returns the transport session id', () => { expect(extractSessionId({ sessionId: 'sess-1' })).toBe('sess-1') }) From 8791e814c0eb0196993d8ceaf96f271d631ae9bc Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:38:30 +0530 Subject: [PATCH 05/25] test(e2e): exercise MCP 2026-07-28 protocol in demo smoke test Replace initialize/initialized handshake with server/discover, add per-request _meta envelope and Mcp-Method/Mcp-Name/MCP-Protocol-Version headers on every POST. --- tests/demo_e2e.py | 222 ++++++++++++++++++++-------------------------- 1 file changed, 98 insertions(+), 124 deletions(-) diff --git a/tests/demo_e2e.py b/tests/demo_e2e.py index f355be5..ba781ee 100644 --- a/tests/demo_e2e.py +++ b/tests/demo_e2e.py @@ -59,6 +59,10 @@ GATEWAY_BASE = "http://127.0.0.1:3333" GATEWAY_URL = f"{GATEWAY_BASE}/mcp" BEARER_TOKEN = "TestBearerTokenForE2ETestingOnly" +MCP_PROTOCOL = "2026-07-28" +MCP_META_PROTOCOL = "io.modelcontextprotocol/protocolVersion" +MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo" +MCP_META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities" SERVICE_STARTUP_WAIT_S = 1 OAUTH_AS_BASE = "http://localhost:8080/default" @@ -287,103 +291,84 @@ def _get_real_jwt() -> str: with urllib.request.urlopen(req, timeout=10) as resp: return json.loads(resp.read().decode())["access_token"] -def _mcp_init_with_jwt(jwt: str) -> dict: - """Returns parsed initialize response, or {_error: ...} on failure.""" - payload = json.dumps({ - "jsonrpc": "2.0", "id": 1, "method": "initialize", - "params": { - "protocolVersion": "2025-11-05", - "capabilities": {}, - "clientInfo": {"name": "smoke", "version": "1"}, - }, - }).encode() +def _mcp_envelope() -> dict: + return { + MCP_META_PROTOCOL: MCP_PROTOCOL, + MCP_META_CLIENT_INFO: {"name": "e2e-smoke", "version": "1"}, + MCP_META_CLIENT_CAPS: {}, + } + +def _mcp_params(params: dict) -> dict: + return {**params, "_meta": _mcp_envelope()} + +def _mcp_headers(method: str, token: str, name: Optional[str] = None) -> dict: + headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {token}", + "Accept": "application/json, text/event-stream", + "MCP-Protocol-Version": MCP_PROTOCOL, + "Mcp-Method": method, + } + if name is not None: + headers["Mcp-Name"] = name + return headers + +def _parse_mcp_response(raw: str) -> dict: + try: + return json.loads(raw) + except json.JSONDecodeError: + pass + for line in raw.splitlines(): + if line.startswith("data: "): + return json.loads(line[6:]) + return {"_transport_error": f"unparseable response: {raw[:200]}"} + +def _mcp_discover_with_jwt(jwt: str) -> dict: + """Returns parsed server/discover response, or {_error: ...} on failure.""" + payload = { + "jsonrpc": "2.0", "id": 1, "method": "server/discover", + "params": _mcp_params({}), + } req = urllib.request.Request( GATEWAY_URL, - data=payload, - headers={ - "Content-Type": "application/json", - "Authorization": f"Bearer {jwt}", - "Accept": "application/json, text/event-stream", - }, + data=json.dumps(payload).encode(), + headers=_mcp_headers("server/discover", jwt), method="POST", ) try: with urllib.request.urlopen(req, timeout=10) as resp: - raw = resp.read().decode() - for line in raw.splitlines(): - if line.startswith("data: "): - return json.loads(line[6:]) - try: - return json.loads(raw) - except Exception: - pass + return _parse_mcp_response(resp.read().decode()) except Exception as e: return {"_error": str(e)} - return {"_error": "no data: line in SSE response"} - -def _mcp_notify_initialized_jwt(jwt: str): - """Send notifications/initialized (fire-and-forget, no response expected).""" - body = json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}).encode() - req = urllib.request.Request( - GATEWAY_URL, data=body, - headers={ - "Content-Type": "application/json", - "Accept": "application/json, text/event-stream", - "Authorization": f"Bearer {jwt}", - }, - method="POST", - ) - try: - urllib.request.urlopen(req, timeout=5) - except Exception: - pass - - -def _mcp_post_jwt(payload: dict, jwt: str) -> dict: - """POST an MCP request using a JWT (stateless — bearer on every request).""" - body = json.dumps(payload).encode() - req = urllib.request.Request( - GATEWAY_URL, data=body, - headers={ - "Content-Type": "application/json", - "Accept": "application/json, text/event-stream", - "Authorization": f"Bearer {jwt}", - }, +def _mcp_post_jwt(payload: dict, jwt: str, mcp_name: Optional[str] = None) -> dict: + """POST an MCP request using a JWT (2026-07-28 envelope + headers).""" + method = payload["method"] + body_payload = dict(payload) + if "params" in body_payload and isinstance(body_payload["params"], dict): + body_payload["params"] = _mcp_params(body_payload["params"]) + req = urllib.request.Request( + GATEWAY_URL, + data=json.dumps(body_payload).encode(), + headers=_mcp_headers(method, jwt, mcp_name), method="POST", ) try: with urllib.request.urlopen(req, timeout=10) as resp: - raw = resp.read().decode() - for line in raw.splitlines(): - if line.startswith("data: "): - return json.loads(line[6:]) - try: - return json.loads(raw) - except Exception: - return {"_error": f"unparseable: {raw[:200]}"} + return _parse_mcp_response(resp.read().decode()) except urllib.error.HTTPError as e: return {"_error": f"HTTP {e.code}: {e.read().decode()[:200]}"} - def _post_with_bearer(path: str, token: str) -> tuple[int, dict]: """POST to path with an explicit Bearer token; returns (status, headers).""" url = f"{GATEWAY_BASE}{path}" - payload = json.dumps({ - "jsonrpc": "2.0", "id": 1, "method": "initialize", - "params": { - "protocolVersion": "2025-11-05", - "capabilities": {}, - "clientInfo": {"name": "test", "version": "1"}, - }, - }).encode() + payload = { + "jsonrpc": "2.0", "id": 1, "method": "server/discover", + "params": _mcp_params({}), + } req = urllib.request.Request( - url, data=payload, - headers={ - "Content-Type": "application/json", - "Accept": "application/json, text/event-stream", - "Authorization": f"Bearer {token}", - }, + url, data=json.dumps(payload).encode(), + headers=_mcp_headers("server/discover", token), method="POST", ) try: @@ -394,55 +379,47 @@ def _post_with_bearer(path: str, token: str) -> tuple[int, dict]: # ── MCP transport helpers ───────────────────────────────────────────────────── -def _mcp_post(payload: dict) -> dict: - body = json.dumps(payload).encode() - headers = { - "Content-Type": "application/json", - "Authorization": f"Bearer {BEARER_TOKEN}", - "Accept": "application/json, text/event-stream", - } +def _mcp_post(payload: dict, token: str = BEARER_TOKEN) -> dict: + method = payload["method"] + mcp_name = None + params = payload.get("params") or {} + if method == "tools/call": + mcp_name = params.get("name") + body_payload = dict(payload) + if "params" in body_payload and isinstance(body_payload["params"], dict): + body_payload["params"] = _mcp_params(body_payload["params"]) - req = urllib.request.Request(GATEWAY_URL, data=body, headers=headers, method="POST") + req = urllib.request.Request( + GATEWAY_URL, + data=json.dumps(body_payload).encode(), + headers=_mcp_headers(method, token, mcp_name), + method="POST", + ) try: with urllib.request.urlopen(req, timeout=15) as resp: - raw = resp.read().decode() + return _parse_mcp_response(resp.read().decode()) except Exception as e: return {"_transport_error": str(e)} - for line in raw.splitlines(): - if line.startswith("data: "): - return json.loads(line[6:]) - return {"_transport_error": "no data line in SSE response"} - def mcp_init() -> bool: payload = { - "jsonrpc": "2.0", "id": 0, "method": "initialize", - "params": { - "protocolVersion": "2024-11-05", - "capabilities": {}, - "clientInfo": {"name": "e2e-smoke", "version": "1"}, - }, - } - body = json.dumps(payload).encode() - headers = { - "Content-Type": "application/json", - "Authorization": f"Bearer {BEARER_TOKEN}", - "Accept": "application/json, text/event-stream", + "jsonrpc": "2.0", "id": 0, "method": "server/discover", + "params": {}, } - req = urllib.request.Request(GATEWAY_URL, data=body, headers=headers, method="POST") try: - with urllib.request.urlopen(req, timeout=10) as resp: - raw = resp.read().decode() + resp = _mcp_post(payload) except Exception as e: print(f"{RED}Gateway not reachable: {e}{RESET}") return False - for line in raw.splitlines(): - if line.startswith("data: "): - d = json.loads(line[6:]) - if "result" in d and "serverInfo" in d["result"]: - return True - return False + if "_transport_error" in resp: + print(f"{RED}Gateway not reachable: {resp['_transport_error']}{RESET}") + return False + if "error" in resp: + print(f"{RED}server/discover failed: {resp['error']}{RESET}") + return False + server_info = resp.get("result", {}).get("serverInfo", {}) + return server_info.get("name") == "harbor" def call_tool(name: str, args: dict, req_id: int) -> dict: resp = _mcp_post({ @@ -791,22 +768,19 @@ def test_docker_oauth(resource_uri: str): bad_status, _ = _post_with_bearer("/mcp", "this-is-not-a-valid-jwt-token") assert_eq(bad_status, 401, "weak token rejected with 401") - # ── MCP handshake with real JWT ─────────────────────────────────────────── - section("OAuth 2.1 — MCP handshake with real JWT") - init_resp = _mcp_init_with_jwt(jwt) - assert_true("result" in init_resp, - f"initialize with real JWT → result present {init_resp.get('_error', '')}") + # ── MCP handshake with real JWT (2026-07-28) ─────────────────────────────── + section("OAuth 2.1 — MCP server/discover with real JWT") + discover_resp = _mcp_discover_with_jwt(jwt) + assert_true("result" in discover_resp, + f"server/discover with real JWT → result present {discover_resp.get('_error', '')}") assert_eq( - init_resp.get("result", {}).get("serverInfo", {}).get("name"), + discover_resp.get("result", {}).get("serverInfo", {}).get("name"), "harbor", - "initialize → serverInfo.name = harbor", + "server/discover → serverInfo.name = harbor", ) - _mcp_notify_initialized_jwt(jwt) - ok("notifications/initialized sent") - tools_resp = _mcp_post_jwt( - {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, + {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}, jwt, ) assert_true("_error" not in tools_resp, @@ -866,7 +840,7 @@ def main(): if not args.start_services: print("Run with --start-services, or start the demo manually first.") sys.exit(1) - ok("Gateway connected (stateless HTTP)") + ok("Gateway connected (MCP 2026-07-28)") try: test_discover_services() From 3d363c6c11154a67a81667eca3ef5c0b014393a6 Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:40:08 +0530 Subject: [PATCH 06/25] build(deps): upgrade zod to v4 for MCP SDK v2 compatibility MCP SDK v2 registers tool schemas via Standard Schema, which requires Zod 4. --- package-lock.json | 26 ++++---------------------- package.json | 2 +- 2 files changed, 5 insertions(+), 23 deletions(-) diff --git a/package-lock.json b/package-lock.json index 0d0d85c..5c926d5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21,7 +21,7 @@ "memjs": "^1.3.2", "pino": "^9.6.0", "uuid": "^11.1.0", - "zod": "^3.24.0" + "zod": "^4.2.0" }, "bin": { "harbor-gateway": "dist/index.js" @@ -819,15 +819,6 @@ "node": ">=20" } }, - "node_modules/@modelcontextprotocol/core/node_modules/zod": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", - "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, "node_modules/@modelcontextprotocol/node": { "version": "2.0.0-beta.4", "resolved": "https://registry.npmjs.org/@modelcontextprotocol/node/-/node-2.0.0-beta.4.tgz", @@ -862,15 +853,6 @@ "node": ">=20" } }, - "node_modules/@modelcontextprotocol/server/node_modules/zod": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", - "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, "node_modules/@pinojs/redact": { "version": "0.4.0", "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz", @@ -4493,9 +4475,9 @@ } }, "node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", + "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/colinhacks" diff --git a/package.json b/package.json index 9926fad..396cc08 100644 --- a/package.json +++ b/package.json @@ -45,7 +45,7 @@ "memjs": "^1.3.2", "pino": "^9.6.0", "uuid": "^11.1.0", - "zod": "^3.24.0" + "zod": "^4.2.0" }, "devDependencies": { "@types/js-yaml": "^4.0.9", From bf84dbf00767fbfc33d34c68eb83bc83b7478400 Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:40:08 +0530 Subject: [PATCH 07/25] fix(tools): wrap inputSchema with z.object for SDK v2 registerTool The v2 registerTool API expects z.object(...) rather than a raw Zod shape record. --- tools/discover-skills.tool.ts | 2 +- tools/execute-api.tool.ts | 2 +- tools/get-skill-details.tool.ts | 2 +- tools/search-code.tool.ts | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/discover-skills.tool.ts b/tools/discover-skills.tool.ts index 08f6c35..d3a7714 100644 --- a/tools/discover-skills.tool.ts +++ b/tools/discover-skills.tool.ts @@ -71,7 +71,7 @@ After finding the relevant skill, use get_skill_details() to read the full SOP.` server.registerTool( TOOL.DISCOVER_SKILLS, - { description: DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, + { description: DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) diff --git a/tools/execute-api.tool.ts b/tools/execute-api.tool.ts index abe0857..040e649 100644 --- a/tools/execute-api.tool.ts +++ b/tools/execute-api.tool.ts @@ -122,7 +122,7 @@ async () => { server.registerTool( TOOL.API_EXECUTE, - { description: EXECUTE_DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, + { description: EXECUTE_DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) const sessionId = extractSessionId(ctx) diff --git a/tools/get-skill-details.tool.ts b/tools/get-skill-details.tool.ts index 87fc062..4dd4ad6 100644 --- a/tools/get-skill-details.tool.ts +++ b/tools/get-skill-details.tool.ts @@ -33,7 +33,7 @@ export function registerGetSkillDetailsTool( server.registerTool( TOOL.GET_SKILL_DETAILS, - { description: DESCRIPTION, inputSchema: { service: z.string(), skill_id: z.string() } }, + { description: DESCRIPTION, inputSchema: z.object({ service: z.string(), skill_id: z.string() }) }, async ({ service, skill_id }, ctx) => { const correlationId = extractCorrelationId(ctx) diff --git a/tools/search-code.tool.ts b/tools/search-code.tool.ts index 11bfd12..7dd35df 100644 --- a/tools/search-code.tool.ts +++ b/tools/search-code.tool.ts @@ -90,7 +90,7 @@ This keeps each search result small and readable.` server.registerTool( TOOL.SEARCH_CODE, - { description: SEARCH_CODE_DESCRIPTION, inputSchema: { service: z.string(), code: z.string() } }, + { description: SEARCH_CODE_DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) From 2217cc6fa17abf77b053f351ee94d9384991adfc Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:40:08 +0530 Subject: [PATCH 08/25] test(unit): align tool tests with ServerContext and Zod v4 schemas Add makeServerCtx helper and inspect ZodObject.shape when asserting tool schemas. --- tests/unit/discover-skills.tool.test.ts | 16 +++++---- tests/unit/execute-api.tool.test.ts | 40 ++++++++++++----------- tests/unit/get-skill-details.tool.test.ts | 18 +++++----- tests/unit/mcp-test-context.ts | 11 +++++++ tests/unit/search-code.tool.test.ts | 14 ++++---- 5 files changed, 59 insertions(+), 40 deletions(-) create mode 100644 tests/unit/mcp-test-context.ts diff --git a/tests/unit/discover-skills.tool.test.ts b/tests/unit/discover-skills.tool.test.ts index 169d69a..b662795 100644 --- a/tests/unit/discover-skills.tool.test.ts +++ b/tests/unit/discover-skills.tool.test.ts @@ -3,6 +3,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest' import pino from 'pino' +import { type ZodObject } from 'zod' +import { makeServerCtx } from './mcp-test-context.js' vi.mock('../../runtime/sandbox/skills-search-in-sandbox.js', () => ({ runSkillsSearchInSandbox: vi.fn() @@ -106,8 +108,8 @@ describe('registerDiscoverSkillsTool', () => { const entry = server.handlers[TOOL.DISCOVER_SKILLS] expect(entry).toBeDefined() expect(entry!.def.description).toContain('tasks') - const schema = entry!.def.inputSchema as Record - expect(Object.keys(schema)).toEqual(expect.arrayContaining(['service', 'code'])) + const schema = entry!.def.inputSchema as ZodObject + expect(Object.keys(schema.shape)).toEqual(expect.arrayContaining(['service', 'code'])) }) it('returns UNKNOWN_SERVICE mcpError when service is not registered', async () => { @@ -122,7 +124,7 @@ describe('registerDiscoverSkillsTool', () => { const r = await server.handlers[TOOL.DISCOVER_SKILLS]!.handler( { service: 'ghost', code: 'async () => skills' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) const body = JSON.parse(r.content[0]!.text) @@ -149,7 +151,7 @@ describe('registerDiscoverSkillsTool', () => { const r = await server.handlers[TOOL.DISCOVER_SKILLS]!.handler( { service: 'tasks', code: 'async () => skills' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) expect(JSON.parse(r.content[0]!.text).code).toBe(ERR.MISSING_TOKEN) @@ -174,7 +176,7 @@ describe('registerDiscoverSkillsTool', () => { const r = await server.handlers[TOOL.DISCOVER_SKILLS]!.handler( { service: 'tasks', code: 'async () => skills.filter(...)' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBeUndefined() @@ -207,7 +209,7 @@ describe('registerDiscoverSkillsTool', () => { await server.handlers[TOOL.DISCOVER_SKILLS]!.handler( { service: 'tasks', code: 'async () => []' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(validate).toHaveBeenCalledWith(`${AUTH_SCHEME} abc123`, 'cid') @@ -227,7 +229,7 @@ describe('registerDiscoverSkillsTool', () => { const r = await server.handlers[TOOL.DISCOVER_SKILLS]!.handler( { service: 'tasks', code: 'async () => crash()' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) diff --git a/tests/unit/execute-api.tool.test.ts b/tests/unit/execute-api.tool.test.ts index 9c6cb76..71fabe6 100644 --- a/tests/unit/execute-api.tool.test.ts +++ b/tests/unit/execute-api.tool.test.ts @@ -4,6 +4,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest' import { createHash } from 'node:crypto' import pino from 'pino' +import { type ZodObject } from 'zod' +import { makeServerCtx } from './mcp-test-context.js' vi.mock('../../runtime/sandbox/execute-api-in-sandbox.js', () => ({ runApiInSandbox: vi.fn() @@ -160,8 +162,8 @@ describe('registerExecuteApiTool', () => { const entry = server.handlers[TOOL.API_EXECUTE] expect(entry).toBeDefined() expect(entry!.def.description).toContain('tasks') - const schema = entry!.def.inputSchema as Record - expect(Object.keys(schema)).toEqual(expect.arrayContaining(['service', 'code'])) + const schema = entry!.def.inputSchema as ZodObject + expect(Object.keys(schema.shape)).toEqual(expect.arrayContaining(['service', 'code'])) }) it('returns UNKNOWN_SERVICE mcpError when the service is not registered and never runs the sandbox', async () => { @@ -177,7 +179,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'ghost', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -204,7 +206,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -231,7 +233,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -255,7 +257,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => ({ hello: "world" })' }, - { correlationId: 'cid-ok', sessionId: 'sid-ok' } + makeServerCtx('cid-ok', 'sid-ok') ) expect(r.isError).toBeUndefined() @@ -299,11 +301,11 @@ describe('registerExecuteApiTool', () => { const code = 'async () => ({ ok: true })' await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code }, - { correlationId: 'cid2', sessionId: 'sid2' } + makeServerCtx('cid2', 'sid2') ) expect(runApiInSandbox).toHaveBeenCalledTimes(2) @@ -342,7 +344,7 @@ describe('registerExecuteApiTool', () => { await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => {}' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) const audit = vi.mocked(writeAuditRecord).mock.calls[0]![0] @@ -369,7 +371,7 @@ describe('registerExecuteApiTool', () => { await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) const audit = vi.mocked(writeAuditRecord).mock.calls[0]![0] @@ -392,7 +394,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => api.request({})' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -431,7 +433,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => api.request({})' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -465,7 +467,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -498,7 +500,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -529,7 +531,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => bogus()' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -561,7 +563,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -598,7 +600,7 @@ describe('registerExecuteApiTool', () => { await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => 1' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(writeAuditRecord).toHaveBeenCalledTimes(1) @@ -647,7 +649,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => bogus()' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) @@ -681,7 +683,7 @@ describe('registerExecuteApiTool', () => { const r = await server.handlers[TOOL.API_EXECUTE]!.handler( { service: 'tasks', code: 'async () => bogus()' }, - { correlationId: 'cid', sessionId: 'sid' } + makeServerCtx('cid', 'sid') ) expect(r.isError).toBe(true) diff --git a/tests/unit/get-skill-details.tool.test.ts b/tests/unit/get-skill-details.tool.test.ts index 65ca373..5bab9bd 100644 --- a/tests/unit/get-skill-details.tool.test.ts +++ b/tests/unit/get-skill-details.tool.test.ts @@ -3,6 +3,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest' import pino from 'pino' +import { type ZodObject } from 'zod' +import { makeServerCtx } from './mcp-test-context.js' import { registerGetSkillDetailsTool } from '../../tools/get-skill-details.tool.js' import { TOOL, METRIC, OUTCOME, ERR } from '../../core/constants.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' @@ -89,8 +91,8 @@ describe('registerGetSkillDetailsTool', () => { const entry = server.handlers[TOOL.GET_SKILL_DETAILS] expect(entry).toBeDefined() - const schema = entry!.def.inputSchema as Record - expect(Object.keys(schema)).toEqual(expect.arrayContaining(['service', 'skill_id'])) + const schema = entry!.def.inputSchema as ZodObject + expect(Object.keys(schema.shape)).toEqual(expect.arrayContaining(['service', 'skill_id'])) }) it('returns UNKNOWN_SERVICE mcpError and records TOOL_CALLS(error)', async () => { @@ -104,7 +106,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'ghost', skill_id: 'x' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) const body = JSON.parse(r.content[0]!.text) @@ -133,7 +135,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'svc', skill_id: 'x' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) const body = JSON.parse(r.content[0]!.text) @@ -164,7 +166,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'svc', skill_id: 'x' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) expect(JSON.parse(r.content[0]!.text).code).toBe(ERR.MISSING_TOKEN) @@ -188,7 +190,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'svc', skill_id: 'missing' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) const body = JSON.parse(r.content[0]!.text) @@ -214,7 +216,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'svc', skill_id: 'whatever' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) const body = JSON.parse(r.content[0]!.text) expect(body.code).toBe(ERR.UNKNOWN_SKILL) @@ -237,7 +239,7 @@ describe('registerGetSkillDetailsTool', () => { const r = await server.handlers[TOOL.GET_SKILL_DETAILS]!.handler( { service: 'svc', skill_id: 'manage-campaigns' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBeUndefined() diff --git a/tests/unit/mcp-test-context.ts b/tests/unit/mcp-test-context.ts new file mode 100644 index 0000000..2bb07d5 --- /dev/null +++ b/tests/unit/mcp-test-context.ts @@ -0,0 +1,11 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +/** Minimal ServerContext stub for unit-testing tool handlers. */ +export function makeServerCtx(correlationId?: string, sessionId?: string): Record { + if (correlationId === undefined && sessionId === undefined) return {} + return { + ...(sessionId !== undefined ? { sessionId } : {}), + ...(correlationId !== undefined ? { mcpReq: { id: correlationId } } : {}) + } +} diff --git a/tests/unit/search-code.tool.test.ts b/tests/unit/search-code.tool.test.ts index 7eb6147..564af74 100644 --- a/tests/unit/search-code.tool.test.ts +++ b/tests/unit/search-code.tool.test.ts @@ -3,6 +3,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest' import pino from 'pino' +import { type ZodObject } from 'zod' +import { makeServerCtx } from './mcp-test-context.js' vi.mock('../../runtime/sandbox/spec-search-in-sandbox.js', () => ({ runSpecSearchInSandbox: vi.fn() @@ -115,8 +117,8 @@ describe('registerSearchCodeTool', () => { const entry = server.handlers[TOOL.SEARCH_CODE] expect(entry).toBeDefined() expect(entry!.def.description).toContain('tasks') - const schema = entry!.def.inputSchema as Record - expect(Object.keys(schema)).toEqual(expect.arrayContaining(['service', 'code'])) + const schema = entry!.def.inputSchema as ZodObject + expect(Object.keys(schema.shape)).toEqual(expect.arrayContaining(['service', 'code'])) }) it('returns UNKNOWN_SERVICE mcpError when the service is not registered', async () => { @@ -131,7 +133,7 @@ describe('registerSearchCodeTool', () => { const r = await server.handlers[TOOL.SEARCH_CODE]!.handler( { service: 'ghost', code: 'async () => spec' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) expect(JSON.parse(r.content[0]!.text).code).toBe(ERR.UNKNOWN_SERVICE) @@ -159,7 +161,7 @@ describe('registerSearchCodeTool', () => { const r = await server.handlers[TOOL.SEARCH_CODE]!.handler( { service: 'tasks', code: 'async () => spec' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) expect(JSON.parse(r.content[0]!.text).code).toBe(ERR.MISSING_TOKEN) @@ -182,7 +184,7 @@ describe('registerSearchCodeTool', () => { const r = await server.handlers[TOOL.SEARCH_CODE]!.handler( { service: 'tasks', code: 'async () => Object.keys(spec.paths)' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBeUndefined() @@ -218,7 +220,7 @@ describe('registerSearchCodeTool', () => { const r = await server.handlers[TOOL.SEARCH_CODE]!.handler( { service: 'tasks', code: 'async () => { while (true) {} }' }, - { correlationId: 'cid' } + makeServerCtx('cid') ) expect(r.isError).toBe(true) From a6e77bd73acf2c1364cdd664206330a8a8661de5 Mon Sep 17 00:00:00 2001 From: Vijaydeep Sinha Date: Fri, 17 Jul 2026 13:40:26 +0530 Subject: [PATCH 09/25] docs: document Harbor 1.0 MCP 2026-07-28 protocol and release notes Update tool-layer and getting-started curl examples for the 2026 envelope and required headers; bump package version to 1.0.0. --- CHANGELOG.md | 18 +++++++++++++++++- docs/getting-started.md | 28 ++++++++++++++++++++-------- docs/tool-layer.md | 30 ++++++++++++++++++++++-------- package.json | 2 +- 4 files changed, 60 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1942d8f..39a3e66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,24 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +--- + +## [1.0.0] — 2026-07-17 + +### Changed +- **Breaking:** Harbor 1.0 implements MCP protocol revision **2026-07-28** only (`legacy: 'reject'`). The 2025 `initialize` / `notifications/initialized` handshake is no longer supported. +- **Breaking:** HTTP clients must send `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, and (for `tools/call`) `Mcp-Name` on every POST, plus the per-request `_meta` envelope (`io.modelcontextprotocol/protocolVersion`, `clientInfo`, `clientCapabilities`). +- **Breaking:** Replaced `@modelcontextprotocol/sdk` v1 with `@modelcontextprotocol/server` and `@modelcontextprotocol/node` v2 (`createMcpHandler`, `serveStdio`). +- Upgraded `zod` to v4 (required by MCP SDK v2 tool schema registration). + +### Added +- `server/discover` as the connection probe (replaces `initialize`). +- Shared `buildMcpServerFactory` for HTTP and stdio transports. + +## [0.2.0] — 2026-07-17 + ### Changed -- **Breaking:** HTTP transport is now stateless. Each `/mcp` request creates a fresh MCP server and transport (`sessionIdGenerator: undefined`). No `mcp-session-id` header is issued or required. +- **Breaking:** HTTP transport is now stateless. Each `/mcp` request creates a fresh MCP server and transport. No `mcp-session-id` header is issued or required. - **Breaking:** Removed `SESSION_IDLE_TTL_MS` and `SESSION_SWEEP_INTERVAL_MS` environment variables. - **Breaking:** `/health` no longer returns `activeSessions`. - Renamed internal factory `createSessionServer` → `createMcpServer`. diff --git a/docs/getting-started.md b/docs/getting-started.md index 1c05bf3..dcf798e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -69,27 +69,39 @@ python3 tests/demo_e2e.py --start-services ## Step 3 — Try It from the Terminal -The gateway speaks JSON-RPC 2.0 over HTTP. Initialize a session, then call tools. +The gateway speaks MCP protocol revision **2026-07-28** over HTTP. Probe with `server/discover`, then call tools. ```bash -# Initialize +# server/discover (connection probe) curl -si -X POST http://127.0.0.1:3333/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "Accept: application/json, text/event-stream" \ - -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ - "protocolVersion":"2024-11-05", - "capabilities":{}, - "clientInfo":{"name":"curl","version":"0"} + -H "MCP-Protocol-Version: 2026-07-28" \ + -H "Mcp-Method: server/discover" \ + -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{ + "_meta":{ + "io.modelcontextprotocol/protocolVersion":"2026-07-28", + "io.modelcontextprotocol/clientInfo":{"name":"curl","version":"0"}, + "io.modelcontextprotocol/clientCapabilities":{} + } }}' -# Discover services (stateless — bearer on every request) +# Discover services (bearer + 2026 headers on every request) curl -s -X POST http://127.0.0.1:3333/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "Accept: application/json, text/event-stream" \ + -H "MCP-Protocol-Version: 2026-07-28" \ + -H "Mcp-Method: tools/call" \ + -H "Mcp-Name: discover_services" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{ - "name":"discover_services","arguments":{} + "name":"discover_services","arguments":{}, + "_meta":{ + "io.modelcontextprotocol/protocolVersion":"2026-07-28", + "io.modelcontextprotocol/clientInfo":{"name":"curl","version":"0"}, + "io.modelcontextprotocol/clientCapabilities":{} + } }}' ``` diff --git a/docs/tool-layer.md b/docs/tool-layer.md index 900a7f3..0dbb317 100644 --- a/docs/tool-layer.md +++ b/docs/tool-layer.md @@ -16,19 +16,33 @@ The AI client connects via HTTP POST to `http://:/mcp`. - `Content-Type: application/json` - `Accept: application/json, text/event-stream` - `Authorization: Bearer ` — required on every request +- `MCP-Protocol-Version: 2026-07-28` +- `Mcp-Method: ` — must match the body's `method` field +- `Mcp-Name: ` — required for `tools/call` (must match `params.name`) -**Stateless request flow:** +**Stateless request flow (2026-07-28):** -HTTP mode uses a **stateless** Streamable HTTP transport (`sessionIdGenerator: undefined` in the MCP SDK). Each `POST /mcp` request gets a fresh `McpServer` and transport instance. The bearer token is validated on every request — no `mcp-session-id` header is issued or required. +Harbor 1.0 serves MCP protocol revision **2026-07-28** only (`legacy: 'reject'`). Each `POST /mcp` request carries a per-request `_meta` envelope and gets a fresh `McpServer` from the SDK v2 `createMcpHandler` entry. The bearer token is validated on every request — no session header is issued or required. + +Every request body's `params` must include: + +```json +"_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientInfo": { "name": "...", "version": "..." }, + "io.modelcontextprotocol/clientCapabilities": {} +} +``` ``` -1. POST /mcp { method: "initialize" } - → Response includes server capabilities (no session header) +1. POST /mcp { method: "server/discover", params: { _meta: {...} } } + → Response includes serverInfo and supportedVersions -2. POST /mcp { method: "tools/list" } ← optional discovery +2. POST /mcp { method: "tools/list", params: { _meta: {...} } } ← optional discovery → Returns the 5 tool definitions with input schemas -3. POST /mcp { method: "tools/call", params: { name: "...", arguments: {...} } } +3. POST /mcp { method: "tools/call", params: { name: "...", arguments: {...}, _meta: {...} } } + Mcp-Name: → Returns tool result (SSE stream or JSON, depending on Accept) ``` @@ -66,8 +80,8 @@ All structured logs go to **stderr**. Stdout is reserved for the MCP protocol st ### Per-request lifecycle (HTTP) Each HTTP request creates a fresh `McpServer` with the client's bearer token bound into the tool handlers. Request-scoped state includes: -- The raw bearer token from the `Authorization` header -- A `correlationId` for request tracing (from the MCP SDK `extra` bag) +- The raw bearer token from the `Authorization` header (via `ctx.authInfo` in the SDK v2 factory) +- A `correlationId` for request tracing (from the MCP request id in `ServerContext`) - Active sandbox isolates for concurrent calls within that request When the HTTP response closes, the transport and `McpServer` are torn down. diff --git a/package.json b/package.json index 396cc08..90c9761 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "harbor-gateway", - "version": "0.1.0", + "version": "1.0.0", "description": "TypeScript framework that connects AI agents to backend APIs via the Model Context Protocol", "author": "Vijaydeep Sinha", "license": "Apache-2.0", From bc86d54ab4a4a3ff65792ad6d77a0538f304afd1 Mon Sep 17 00:00:00 2001 From: vijay Date: Wed, 26 Aug 2026 23:06:52 +0530 Subject: [PATCH 10/25] build(deps): regenerate package-lock after MCP SDK v2 cherry-pick --- package-lock.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5c926d5..2b23f48 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "harbor-gateway", - "version": "0.1.0", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "harbor-gateway", - "version": "0.1.0", + "version": "1.0.0", "license": "Apache-2.0", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", From b2f1249549f7989b0aae38593973fe92b4f78f49 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:11:22 +0530 Subject: [PATCH 11/25] feat(meta): response _meta with serverInfo + app-metadata channel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Attach mandatory io.modelcontextprotocol/serverInfo to every tool response _meta (spec §10) via mcpSuccess/mcpError chokepoints, and add an optional application-level _meta channel (spec §11) kept strictly out of model-visible content. Reserved serverInfo key cannot be spoofed by app metadata. Co-Authored-By: Claude Opus 4.8 --- core/constants.ts | 24 +++++++++++++++++ tests/unit/tool-helpers.test.ts | 47 ++++++++++++++++++++++++++++++++- tools/tool-helpers.ts | 40 ++++++++++++++++++++++++---- 3 files changed, 105 insertions(+), 6 deletions(-) diff --git a/core/constants.ts b/core/constants.ts index 43ab324..91bc06e 100644 --- a/core/constants.ts +++ b/core/constants.ts @@ -182,3 +182,27 @@ export type AuditOutcome = typeof OUTCOME[keyof typeof OUTCOME] // ── Gateway ────────────────────────────────────────────────────────────────── export const GATEWAY_NAME = 'harbor' + +/** Advertised gateway (MCP server) version. Surfaced through response + * `_meta` serverInfo and the `McpServer` implementation identity. */ +export const GATEWAY_VERSION = '1.0.0' + +// ── MCP 2026-07-28 reserved `_meta` namespace ───────────────────────────────── +// Keys in the `io.modelcontextprotocol/*` namespace are protocol-defined and +// carried out-of-band from model-visible `content`. Harbor treats inbound +// values as untrusted (never for auth/security) and only *emits* serverInfo. + +/** Response `_meta` key carrying server identity (spec §10, MANDATORY). */ +export const SERVER_INFO_META_KEY = 'io.modelcontextprotocol/serverInfo' + +/** Request `_meta` key carrying the negotiated protocol version (spec §9). */ +export const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion' + +/** Request `_meta` key carrying client implementation info (spec §9). */ +export const CLIENT_INFO_META_KEY = 'io.modelcontextprotocol/clientInfo' + +/** Request `_meta` key carrying client capabilities (spec §9). */ +export const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities' + +/** The single MCP protocol version this gateway speaks (spec §20). */ +export const MCP_PROTOCOL_VERSION = '2026-07-28' diff --git a/tests/unit/tool-helpers.test.ts b/tests/unit/tool-helpers.test.ts index 2541c64..baf994d 100644 --- a/tests/unit/tool-helpers.test.ts +++ b/tests/unit/tool-helpers.test.ts @@ -10,13 +10,14 @@ import { isToolError, mcpError, mcpSuccess, + buildResponseMeta, validateAuth, runSandboxTool, type ToolResponse } from '../../tools/tool-helpers.js' import type { ServiceRegistry, ServiceResources } from '../../runtime/registry/service-registry.js' import { MissingTokenError, SessionExpiredError, type TokenPayload } from '../../core/types/auth.types.js' -import { ERR, METRIC, OUTCOME } from '../../core/constants.js' +import { ERR, METRIC, OUTCOME, GATEWAY_NAME, GATEWAY_VERSION, SERVER_INFO_META_KEY } from '../../core/constants.js' const silentLogger = pino({ level: 'silent' }) @@ -121,6 +122,50 @@ describe('tool-helpers responses', () => { }) }) +describe('response _meta / serverInfo (spec §10, §11)', () => { + const expectedServerInfo = { name: GATEWAY_NAME, version: GATEWAY_VERSION } + + it('mcpSuccess carries mandatory serverInfo in _meta', () => { + const r = mcpSuccess({ a: 1 }) + expect(r._meta?.[SERVER_INFO_META_KEY]).toEqual(expectedServerInfo) + }) + + it('mcpError carries mandatory serverInfo in _meta', () => { + const r = mcpError('boom', ERR.API_ERROR) + expect(r._meta?.[SERVER_INFO_META_KEY]).toEqual(expectedServerInfo) + }) + + it('serverInfo never leaks into model-visible content', () => { + const r = mcpSuccess({ a: 1 }) + expect(r.content[0].text).not.toContain('serverInfo') + expect(r.content[0].text).not.toContain(GATEWAY_NAME) + const e = mcpError('boom', ERR.API_ERROR, false, { progress: 1 }) + expect(e.content[0].text).not.toContain('serverInfo') + }) + + it('mcpSuccess merges application _meta alongside serverInfo', () => { + const r = mcpSuccess({ a: 1 }, { 'harbor/correlationId': 'cid-9' }) + expect(r._meta?.['harbor/correlationId']).toBe('cid-9') + expect(r._meta?.[SERVER_INFO_META_KEY]).toEqual(expectedServerInfo) + }) + + it('mcpError merges application _meta alongside serverInfo', () => { + const r = mcpError('boom', ERR.API_ERROR, true, undefined, { 'harbor/auditId': 'aud-1' }) + expect(r._meta?.['harbor/auditId']).toBe('aud-1') + expect(r._meta?.[SERVER_INFO_META_KEY]).toEqual(expectedServerInfo) + }) + + it('application _meta cannot spoof the reserved serverInfo key', () => { + const spoof = buildResponseMeta({ [SERVER_INFO_META_KEY]: { name: 'evil', version: '0' } }) + expect(spoof[SERVER_INFO_META_KEY]).toEqual(expectedServerInfo) + }) + + it('application _meta does not leak into content', () => { + const r = mcpSuccess({ a: 1 }, { 'harbor/auditId': 'aud-secret' }) + expect(r.content[0].text).not.toContain('aud-secret') + }) +}) + describe('resolveService', () => { function makeRegistry(entries: Record): ServiceRegistry { return { diff --git a/tools/tool-helpers.ts b/tools/tool-helpers.ts index 0ff3bc0..467e151 100644 --- a/tools/tool-helpers.ts +++ b/tools/tool-helpers.ts @@ -11,14 +11,38 @@ import { AUTH_SCHEME, METRIC, OUTCOME, - LOG_PREFIX + LOG_PREFIX, + GATEWAY_NAME, + GATEWAY_VERSION, + SERVER_INFO_META_KEY } from '../core/constants.js' import { ensureError, errorCode, errorRetryable } from '../core/utils/errors.js' +/** Server identity emitted in every response `_meta` (spec §10, MANDATORY). */ +const SERVER_INFO = Object.freeze({ name: GATEWAY_NAME, version: GATEWAY_VERSION }) + +/** + * Application-level metadata a tool may attach to a response `_meta` channel + * (spec §11). This is transport for the MCP client/application — correlation + * ids, audit ids, downstream ids — and is kept strictly out of model-visible + * `content`. It is NOT Human-in-the-Loop: no approval/elicitation/task state. + */ +export type AppMeta = Record + +/** + * Builds a response `_meta` object. Server identity under the reserved + * `io.modelcontextprotocol/serverInfo` key is always present and always wins: + * application metadata is merged first so it can never spoof server identity. + */ +export function buildResponseMeta(appMeta?: AppMeta): Record { + return { ...(appMeta ?? {}), [SERVER_INFO_META_KEY]: SERVER_INFO } +} + /** MCP tool handlers expect `Record`-compatible objects. */ export type ToolResponse = { content: Array<{ type: 'text'; text: string }> isError?: boolean + _meta?: Record } & Record import type { ServerContext } from '@modelcontextprotocol/server' @@ -31,12 +55,16 @@ import type { ServerContext } from '@modelcontextprotocol/server' * only read the three core fields. * * Reserved keys (`error`, `code`, `retryable`) cannot be overridden by `extra`. + * + * `appMeta` is carried on the response `_meta` channel (spec §11), alongside + * mandatory serverInfo — never mixed into the model-visible error `content`. */ export function mcpError( message: string, code: string, retryable = false, - extra?: Record + extra?: Record, + appMeta?: AppMeta ): ToolResponse { const payload: Record = { ...(extra ?? {}), error: message, code, retryable } return { @@ -44,16 +72,18 @@ export function mcpError( type: 'text' as const, text: JSON.stringify(payload) }], - isError: true + isError: true, + _meta: buildResponseMeta(appMeta) } } -export function mcpSuccess(data: unknown): ToolResponse { +export function mcpSuccess(data: unknown, appMeta?: AppMeta): ToolResponse { return { content: [{ type: 'text' as const, text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) - }] + }], + _meta: buildResponseMeta(appMeta) } } From b72516f921735e72206818ec83d4ce7193188675 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:17:23 +0530 Subject: [PATCH 12/25] feat(meta): advisory request _meta reader for protocol version/clientInfo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add readRequestMeta (spec §9): surfaces the negotiated protocolVersion, clientInfo and clientCapabilities that the SDK lifts onto ctx.mcpReq.envelope (params _meta fallback). Strictly advisory for logging/telemetry — never used for authorization. Defensive against missing/malformed values. Co-Authored-By: Claude Opus 4.8 --- tests/unit/tool-helpers.test.ts | 43 +++++++++++++++++++++++++++++++++ tools/tool-helpers.ts | 38 ++++++++++++++++++++++++++++- 2 files changed, 80 insertions(+), 1 deletion(-) diff --git a/tests/unit/tool-helpers.test.ts b/tests/unit/tool-helpers.test.ts index baf994d..d73468d 100644 --- a/tests/unit/tool-helpers.test.ts +++ b/tests/unit/tool-helpers.test.ts @@ -6,6 +6,7 @@ import pino from 'pino' import { extractCorrelationId, extractSessionId, + readRequestMeta, resolveService, isToolError, mcpError, @@ -71,6 +72,48 @@ describe('tool-helpers extractors', () => { }) }) +describe('readRequestMeta (spec §9)', () => { + const PV = 'io.modelcontextprotocol/protocolVersion' + const CI = 'io.modelcontextprotocol/clientInfo' + const CC = 'io.modelcontextprotocol/clientCapabilities' + + it('reads protocol version, clientInfo and capabilities from the envelope', () => { + const ctx = { + mcpReq: { + envelope: { + [PV]: '2026-07-28', + [CI]: { name: 'demo-client', version: '9.9' }, + [CC]: { sampling: {} } + } + } + } + const view = readRequestMeta(ctx) + expect(view.protocolVersion).toBe('2026-07-28') + expect(view.clientInfo).toEqual({ name: 'demo-client', version: '9.9' }) + expect(view.clientCapabilities).toEqual({ sampling: {} }) + }) + + it('falls back to params _meta when the envelope is absent', () => { + const ctx = { mcpReq: { _meta: { [PV]: '2026-07-28' } } } + expect(readRequestMeta(ctx).protocolVersion).toBe('2026-07-28') + }) + + it('envelope wins over params _meta on key collision', () => { + const ctx = { mcpReq: { _meta: { [PV]: 'old' }, envelope: { [PV]: '2026-07-28' } } } + expect(readRequestMeta(ctx).protocolVersion).toBe('2026-07-28') + }) + + it('returns an empty view for missing/blank context', () => { + expect(readRequestMeta(undefined)).toEqual({}) + expect(readRequestMeta({ mcpReq: {} })).toEqual({}) + }) + + it('ignores malformed values (wrong types) without throwing', () => { + const ctx = { mcpReq: { envelope: { [PV]: 123, [CI]: 'nope', [CC]: null } } } + expect(readRequestMeta(ctx)).toEqual({}) + }) +}) + describe('tool-helpers responses', () => { it('mcpError shapes a text error payload with isError=true', () => { const r = mcpError('boom', ERR.AUTH_FAILED, true) diff --git a/tools/tool-helpers.ts b/tools/tool-helpers.ts index 467e151..a4acba5 100644 --- a/tools/tool-helpers.ts +++ b/tools/tool-helpers.ts @@ -14,7 +14,10 @@ import { LOG_PREFIX, GATEWAY_NAME, GATEWAY_VERSION, - SERVER_INFO_META_KEY + SERVER_INFO_META_KEY, + PROTOCOL_VERSION_META_KEY, + CLIENT_INFO_META_KEY, + CLIENT_CAPABILITIES_META_KEY } from '../core/constants.js' import { ensureError, errorCode, errorRetryable } from '../core/utils/errors.js' @@ -100,6 +103,39 @@ export function extractSessionId(ctx: unknown): string { return (ctx as ServerContext | undefined)?.sessionId ?? crypto.randomUUID() } +/** + * Advisory view of per-request MCP metadata (spec §9): the negotiated protocol + * version, client implementation info, and client capabilities. The SDK lifts + * the reserved `io.modelcontextprotocol/*` envelope keys out of the params + * `_meta` the handler sees and onto `ctx.mcpReq.envelope`; this reads both, + * envelope-first. + * + * SECURITY: this is untrusted, client-supplied context for logging/telemetry + * and content shaping ONLY. Never use it for authorization or any security + * decision — auth flows exclusively through the validated bearer token. + */ +export interface RequestMetaView { + protocolVersion?: string + clientInfo?: { name?: string; version?: string } & Record + clientCapabilities?: Record +} + +export function readRequestMeta(ctx: unknown): RequestMetaView { + const mcpReq = (ctx as ServerContext | undefined)?.mcpReq + const src: Record = { + ...((mcpReq?._meta as Record | undefined) ?? {}), + ...((mcpReq?.envelope as Record | undefined) ?? {}) + } + const view: RequestMetaView = {} + const pv = src[PROTOCOL_VERSION_META_KEY] + if (typeof pv === 'string') view.protocolVersion = pv + const ci = src[CLIENT_INFO_META_KEY] + if (ci !== null && typeof ci === 'object') view.clientInfo = ci as RequestMetaView['clientInfo'] + const cc = src[CLIENT_CAPABILITIES_META_KEY] + if (cc !== null && typeof cc === 'object') view.clientCapabilities = cc as Record + return view +} + export function resolveService( registry: ServiceRegistry, service: string, From faa6b5c789d01f192c1473630e00168a84f6776e Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:22:43 +0530 Subject: [PATCH 13/25] feat(discover): advertise real capabilities + conservative cache hints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Configure the per-request McpServer with explicit ServerOptions (spec §15/§16): capabilities advertise only { tools: {} } (Harbor exposes no prompts/resources/logging), real 5-tool workflow instructions surfaced via server/discover, and conservative private/ttlMs:0 cache hints for the two cacheable operations Harbor serves (tools/list, server/discover). No aggressive TTL invented. Server version now sourced from GATEWAY_VERSION. Co-Authored-By: Claude Opus 4.8 --- runtime/http/mcp-server-factory.ts | 40 +++++++++++++++++++++++++-- tests/unit/mcp-server-factory.test.ts | 35 +++++++++++++++++++++++ 2 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 tests/unit/mcp-server-factory.test.ts diff --git a/runtime/http/mcp-server-factory.ts b/runtime/http/mcp-server-factory.ts index 94294d8..64e33ad 100644 --- a/runtime/http/mcp-server-factory.ts +++ b/runtime/http/mcp-server-factory.ts @@ -11,7 +11,43 @@ import { registerDiscoverSkillsTool } from '../../tools/discover-skills.tool.js' import { registerGetSkillDetailsTool } from '../../tools/get-skill-details.tool.js' import { registerSearchCodeTool } from '../../tools/search-code.tool.js' import { registerExecuteApiTool } from '../../tools/execute-api.tool.js' -import { GATEWAY_NAME } from '../../core/constants.js' +import { GATEWAY_NAME, GATEWAY_VERSION } from '../../core/constants.js' + +/** Options accepted by the `McpServer` constructor's second argument. */ +type McpServerOptions = NonNullable[1]> + +/** + * Static MCP server options (spec §15/§16). Pure and side-effect free so it can + * be unit-tested without booting a transport. + * + * - `capabilities`: Harbor exposes ONLY tools — no prompts/resources/logging — + * so it advertises exactly `{ tools: {} }`. `server/discover` and `tools/list` + * are then answered by the SDK from the registered tool surface. Advertising + * nothing Harbor does not implement is an explicit §15 requirement. + * - `instructions`: the real 5-tool discovery→execute workflow, surfaced through + * discovery so clients drive the gateway correctly. + * - `cacheHints`: conservative and explicit for the two cacheable operations + * Harbor actually serves (`tools/list`, `server/discover`). The fixed 5-tool + * surface only changes on restart, but the client cannot know that, so the + * hint stays at the conservative defaults — private scope, no shared caching, + * `ttlMs: 0`. No aggressive TTL is invented (§16). + */ +export function buildMcpServerOptions(): McpServerOptions { + return { + capabilities: { tools: {} }, + instructions: + 'Harbor is an MCP gateway to backend services. Workflow: ' + + '1) discover_services() to list backends; ' + + '2) discover_skills() + get_skill_details() for business SOPs (optional); ' + + '3) search_code() to find exact endpoints; ' + + '4) api_execute() to run an authenticated call against a chosen service. ' + + 'Always pass the "service" parameter to api_execute and use only paths confirmed by search_code().', + cacheHints: { + 'tools/list': { ttlMs: 0, cacheScope: 'private' }, + 'server/discover': { ttlMs: 0, cacheScope: 'private' } + } + } +} /** Factory signature shared by HTTP (`createMcpHandler`) and stdio (`serveStdio`). */ export type McpServerFactory = (ctx: McpRequestContext) => McpServer @@ -34,7 +70,7 @@ export function buildMcpServerFactory(opts: BuildMcpServerFactoryOptions): McpSe return (ctx: McpRequestContext) => { const clientToken = ctx.authInfo?.token ?? stdioToken - const mcpServer = new McpServer({ name: GATEWAY_NAME, version: '1.0.0' }) + const mcpServer = new McpServer({ name: GATEWAY_NAME, version: GATEWAY_VERSION }, buildMcpServerOptions()) registerDiscoverServicesTool(mcpServer, registry, logger, metrics) registerDiscoverSkillsTool(mcpServer, registry, logger, metrics, clientToken) registerGetSkillDetailsTool(mcpServer, registry, logger, metrics, clientToken) diff --git a/tests/unit/mcp-server-factory.test.ts b/tests/unit/mcp-server-factory.test.ts new file mode 100644 index 0000000..756f889 --- /dev/null +++ b/tests/unit/mcp-server-factory.test.ts @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import { describe, it, expect } from 'vitest' +import { buildMcpServerOptions } from '../../runtime/http/mcp-server-factory.js' + +describe('buildMcpServerOptions (spec §15/§16)', () => { + const opts = buildMcpServerOptions() + + it('advertises only the tools capability Harbor implements', () => { + expect(opts.capabilities).toEqual({ tools: {} }) + // Must NOT fabricate prompts/resources/logging capabilities. + expect(opts.capabilities).not.toHaveProperty('prompts') + expect(opts.capabilities).not.toHaveProperty('resources') + expect(opts.capabilities).not.toHaveProperty('logging') + }) + + it('provides real instructions describing the 5-tool workflow', () => { + const text = opts.instructions ?? '' + for (const tool of ['discover_services', 'discover_skills', 'get_skill_details', 'search_code', 'api_execute']) { + expect(text).toContain(tool) + } + }) + + it('sets conservative, non-aggressive cache hints only for cacheable ops', () => { + expect(opts.cacheHints).toEqual({ + 'tools/list': { ttlMs: 0, cacheScope: 'private' }, + 'server/discover': { ttlMs: 0, cacheScope: 'private' } + }) + for (const hint of Object.values(opts.cacheHints ?? {})) { + expect(hint.cacheScope).toBe('private') // never shared/public + expect(hint.ttlMs).toBe(0) // no invented TTL + } + }) +}) From d272f8f14042770c0d73cf6f2470d74e7d0e7607 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:27:22 +0530 Subject: [PATCH 14/25] feat(http): surface normalized MCP request identity from headers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Read MCP-Protocol-Version/Mcp-Method/Mcp-Name (spec §13/§14) into an advisory McpRequestIdentity for routing/observability, wired into the gateway dispatch log. The SDK owns header validation and JSON-RPC reconciliation, so Harbor does not duplicate it; identity is never used for authentication (auth stays keyed to the bearer token, §19). Co-Authored-By: Claude Opus 4.8 --- core/constants.ts | 5 +++ runtime/http/http-gateway.ts | 8 ++++- runtime/http/mcp-request-identity.ts | 42 +++++++++++++++++++++++++ tests/unit/mcp-request-identity.test.ts | 35 +++++++++++++++++++++ 4 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 runtime/http/mcp-request-identity.ts create mode 100644 tests/unit/mcp-request-identity.test.ts diff --git a/core/constants.ts b/core/constants.ts index 91bc06e..194cfe9 100644 --- a/core/constants.ts +++ b/core/constants.ts @@ -103,6 +103,11 @@ export const HTTP_HEADER = { MCP_SERVICE: 'X-MCP-Service', MCP_VERSION: 'X-MCP-Version', IDEMPOTENCY_KEY: 'X-Idempotency-Key', + /** MCP 2026-07-28 protocol headers (spec §13/§14). Validated by the SDK; + * Harbor only reads them for routing/authorization/observability. */ + MCP_PROTOCOL_VERSION: 'MCP-Protocol-Version', + MCP_METHOD: 'Mcp-Method', + MCP_NAME: 'Mcp-Name', } as const export const CONTENT_TYPE_JSON = 'application/json' diff --git a/runtime/http/http-gateway.ts b/runtime/http/http-gateway.ts index ec4bd07..20661a3 100644 --- a/runtime/http/http-gateway.ts +++ b/runtime/http/http-gateway.ts @@ -9,6 +9,7 @@ import type { ServiceRegistry } from '../registry/service-registry.js' import type { OAuthResourceConfig } from '../../core/types/oauth.types.js' import { extractBearerFromRequest, bearerFailureToHttpResponse } from '../../spi/auth/bearer-authorization.js' import { handleProtectedResourceMetadata } from './oauth-metadata-handler.js' +import { readMcpRequestIdentity } from './mcp-request-identity.js' import { sendJson, sendGatewayError } from './send-response.js' import { HttpError } from './http-error.js' import { ERR, HTTP_ROUTES } from '../../core/constants.js' @@ -151,10 +152,15 @@ async function handleAuthenticatedMcpRequest( scopes: [] } + // Normalized MCP request identity from HTTP headers (spec §14). Advisory: + // used for routing/observability only — the SDK validates these headers and + // reconciles them with the JSON-RPC body; auth stays keyed to the token. + const mcpIdentity = readMcpRequestIdentity(req.headers) + try { await nodeMcpHandler(authReq, res) } catch (err) { - logger.warn({ error: errorMessage(err) }, 'MCP handler dispatch failed') + logger.warn({ error: errorMessage(err), ...mcpIdentity }, 'MCP handler dispatch failed') throw err } } diff --git a/runtime/http/mcp-request-identity.ts b/runtime/http/mcp-request-identity.ts new file mode 100644 index 0000000..4ea0e7c --- /dev/null +++ b/runtime/http/mcp-request-identity.ts @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import type { IncomingHttpHeaders } from 'node:http' + +/** + * Normalized MCP request identity read from the 2026-07-28 HTTP headers + * (spec §13/§14): `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`. + * + * These headers exist so infrastructure (Harbor is itself a gateway) can route + * and authorize a request WITHOUT parsing the JSON-RPC body. The MCP SDK owns + * their validation and reconciliation against the JSON-RPC request and rejects + * inconsistent/malformed requests — Harbor does not duplicate that logic. This + * view is advisory: for logging, routing, and authorization surface only. + * + * SECURITY: like all client-supplied metadata (spec §19), these values MUST NOT + * drive authentication. They may inform coarse routing/authorization decisions, + * but the authenticated bearer token remains the source of truth for identity. + */ +export interface McpRequestIdentity { + protocolVersion?: string + method?: string + name?: string +} + +/** First header value (Node lower-cases header names; some may be arrays). */ +function firstHeader(value: string | string[] | undefined): string | undefined { + if (Array.isArray(value)) return value[0] + return value +} + +/** Reads the normalized MCP request identity from inbound HTTP headers. */ +export function readMcpRequestIdentity(headers: IncomingHttpHeaders): McpRequestIdentity { + const identity: McpRequestIdentity = {} + const pv = firstHeader(headers['mcp-protocol-version']) + if (pv) identity.protocolVersion = pv + const method = firstHeader(headers['mcp-method']) + if (method) identity.method = method + const name = firstHeader(headers['mcp-name']) + if (name) identity.name = name + return identity +} diff --git a/tests/unit/mcp-request-identity.test.ts b/tests/unit/mcp-request-identity.test.ts new file mode 100644 index 0000000..b9c9a1f --- /dev/null +++ b/tests/unit/mcp-request-identity.test.ts @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import { describe, it, expect } from 'vitest' +import type { IncomingHttpHeaders } from 'node:http' +import { readMcpRequestIdentity } from '../../runtime/http/mcp-request-identity.js' + +describe('readMcpRequestIdentity (spec §13/§14)', () => { + it('reads protocol version, method and name from headers', () => { + const headers: IncomingHttpHeaders = { + 'mcp-protocol-version': '2026-07-28', + 'mcp-method': 'tools/call', + 'mcp-name': 'api_execute' + } + expect(readMcpRequestIdentity(headers)).toEqual({ + protocolVersion: '2026-07-28', + method: 'tools/call', + name: 'api_execute' + }) + }) + + it('returns an empty identity when the headers are absent', () => { + expect(readMcpRequestIdentity({})).toEqual({}) + }) + + it('takes the first value when a header arrives as an array', () => { + const headers: IncomingHttpHeaders = { 'mcp-method': ['tools/list', 'ping'] } + expect(readMcpRequestIdentity(headers).method).toBe('tools/list') + }) + + it('omits keys for empty header values', () => { + const headers: IncomingHttpHeaders = { 'mcp-method': '' } + expect(readMcpRequestIdentity(headers)).toEqual({}) + }) +}) From a4b3c78a778ea2be2d9d54572b325af5c8c036cd Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:49:37 +0530 Subject: [PATCH 15/25] =?UTF-8?q?feat(auth):=20enforce=20token=20resource?= =?UTF-8?q?=20binding=20on=20OAuth=202.1=20path=20(=C2=A717)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MCP 2026-07-28 authorization hardening (RFC 8707 resource indicators): the resource server MUST reject access tokens not bound to it. The OAuth 2.1 discovery strategy previously left `audience` optional, so a token minted for another resource behind the same authorization server would be accepted (confused-deputy / token pass-through). Make `audience` (the gateway's canonical resource identifier) required on the OAuth 2.1 path and fail closed at construction and wiring when absent. JWT / introspection / static-token providers are unchanged — the pluggable auth architecture and existing providers are preserved (§18). --- .../strategies/oauth-discovery.strategy.ts | 18 +++++++++++-- core/types/config.types.ts | 2 +- tests/integration/oauth-jwt-auth.test.ts | 1 + tests/unit/oauth-discovery.test.ts | 27 ++++++++++++++++--- tests/unit/service-wiring.test.ts | 6 +++++ wiring/service-wiring.ts | 5 +++- 6 files changed, 51 insertions(+), 8 deletions(-) diff --git a/adapters/auth/strategies/oauth-discovery.strategy.ts b/adapters/auth/strategies/oauth-discovery.strategy.ts index 56592e8..69169e7 100644 --- a/adapters/auth/strategies/oauth-discovery.strategy.ts +++ b/adapters/auth/strategies/oauth-discovery.strategy.ts @@ -9,7 +9,15 @@ import { JwtValidationStrategy } from './jwt-validation.strategy.js' export interface OAuthDiscoveryConfig { authorizationServer: string - audience?: string + /** + * Canonical resource identifier this gateway accepts tokens for (RFC 8707 + * resource indicator / JWT `aud`). REQUIRED under MCP 2026-07-28 (spec §17): + * the resource server MUST reject tokens not bound to it, otherwise a token + * minted for another resource behind the same authorization server would be + * accepted here (confused-deputy / token pass-through). Set this to the value + * Harbor advertises as `resource` in its Protected Resource Metadata. + */ + audience: string clockToleranceSec?: number scopeClaim?: string metadataMapping?: Record @@ -27,6 +35,12 @@ export class OAuthDiscoveryStrategy implements AuthStrategy { private readonly logger?: Logger constructor(config: OAuthDiscoveryConfig) { + // Fail closed on missing resource binding (spec §17, RFC 8707). Without an + // audience the inner JWT verification would accept any `aud`, defeating + // resource-binding — so this is a misconfiguration, not a soft default. + if (!config.audience || config.audience.trim() === '') { + throw new Error('OAuth 2.1 auth requires `audience` (resource binding) under MCP 2026-07-28') + } this.config = config this.logger = config.logger } @@ -54,7 +68,7 @@ export class OAuthDiscoveryStrategy implements AuthStrategy { this.inner = new JwtValidationStrategy({ jwksUri, issuer: this.config.authorizationServer, - ...(this.config.audience !== undefined ? { audience: this.config.audience } : {}), + audience: this.config.audience, ...(this.config.clockToleranceSec !== undefined ? { clockToleranceSec: this.config.clockToleranceSec } : {}), ...(this.config.scopeClaim !== undefined ? { scopeClaim: this.config.scopeClaim } : {}), ...(this.config.metadataMapping !== undefined ? { metadataMapping: this.config.metadataMapping } : {}), diff --git a/core/types/config.types.ts b/core/types/config.types.ts index bc77303..ce0bfe0 100644 --- a/core/types/config.types.ts +++ b/core/types/config.types.ts @@ -43,7 +43,7 @@ export type ServiceAuthConfig = | { type: 'static-token'; token?: string; protocol?: 'http' | 'https'; host?: string; port?: number; introspectionPath?: string; authTimeoutMs?: number; method?: 'GET' | 'POST'; tokenPassMode?: 'query' | 'body' | 'header'; tokenParamName?: string; refreshPath?: string; tokenRefreshBufferSec?: number } | { type: 'oauth-introspection'; protocol?: 'http' | 'https'; host: string; port: number; introspectionPath: string; authTimeoutMs?: number; method?: 'GET' | 'POST'; tokenPassMode?: 'query' | 'body' | 'header'; tokenParamName?: string; refreshPath?: string; tokenRefreshBufferSec?: number; responseMapping?: Record; metadataMapping?: Record } | { type: 'jwt-validation'; jwksUri: string; issuer: string; audience?: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record } - | { type: 'oauth-2.1'; authorizationServer: string; audience?: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record; discoveryTimeoutMs?: number } + | { type: 'oauth-2.1'; authorizationServer: string; audience: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record; discoveryTimeoutMs?: number } export type ServiceCircuitBreakerConfig = | { type: 'noop' } diff --git a/tests/integration/oauth-jwt-auth.test.ts b/tests/integration/oauth-jwt-auth.test.ts index a984309..61fe508 100644 --- a/tests/integration/oauth-jwt-auth.test.ts +++ b/tests/integration/oauth-jwt-auth.test.ts @@ -208,6 +208,7 @@ describe('oauth-2.1 discovery strategy through InMemoryTokenCache', () => { it('unreachable AS → TokenIntrospectionError', async () => { const strategy = new OAuthDiscoveryStrategy({ authorizationServer: 'http://127.0.0.1:1', + audience: AUDIENCE, discoveryTimeoutMs: 500, }) const cache = new InMemoryTokenCache(300_000) diff --git a/tests/unit/oauth-discovery.test.ts b/tests/unit/oauth-discovery.test.ts index 402b855..0774faa 100644 --- a/tests/unit/oauth-discovery.test.ts +++ b/tests/unit/oauth-discovery.test.ts @@ -95,15 +95,33 @@ describe('OAuthDiscoveryStrategy', () => { }) it('tokenRefreshBufferSec is undefined', () => { - const s = new OAuthDiscoveryStrategy({ authorizationServer: asBaseUrl }) + const s = new OAuthDiscoveryStrategy({ authorizationServer: asBaseUrl, audience: 'https://harbor.example.com' }) expect(s.tokenRefreshBufferSec).toBeUndefined() }) it('oauthDiscovery() factory returns OAuthDiscoveryStrategy', () => { - const s = oauthDiscovery({ authorizationServer: asBaseUrl }) + const s = oauthDiscovery({ authorizationServer: asBaseUrl, audience: 'https://harbor.example.com' }) expect(s).toBeInstanceOf(OAuthDiscoveryStrategy) }) + describe('resource binding (spec §17, RFC 8707)', () => { + it('constructor fails closed when audience/resource binding is absent', () => { + expect(() => + new OAuthDiscoveryStrategy({ authorizationServer: asBaseUrl } as never) + ).toThrow(/audience/) + }) + + it('constructor fails closed when audience is blank', () => { + expect(() => + new OAuthDiscoveryStrategy({ authorizationServer: asBaseUrl, audience: ' ' }) + ).toThrow(/resource binding/) + }) + + it('oauthDiscovery() factory also fails closed without audience', () => { + expect(() => oauthDiscovery({ authorizationServer: asBaseUrl } as never)).toThrow(/audience/) + }) + }) + describe('validate — discovery + happy path', () => { it('discovers OIDC metadata and validates a valid JWT', async () => { const s = new OAuthDiscoveryStrategy({ @@ -217,6 +235,7 @@ describe('OAuthDiscoveryStrategy', () => { it('unreachable AS → TokenIntrospectionError', async () => { const s = new OAuthDiscoveryStrategy({ authorizationServer: 'http://127.0.0.1:1', + audience: 'https://harbor.example.com', discoveryTimeoutMs: 500, }) const token = await sign({}) @@ -233,7 +252,7 @@ describe('OAuthDiscoveryStrategy', () => { const { port } = failServer.address() as AddressInfo const failUrl = `http://127.0.0.1:${port}` - const s = new OAuthDiscoveryStrategy({ authorizationServer: failUrl }) + const s = new OAuthDiscoveryStrategy({ authorizationServer: failUrl, audience: 'https://harbor.example.com' }) const token = await sign({}) await expect(s.validate(token)).rejects.toBeInstanceOf(TokenIntrospectionError) await expect(s.validate(token)).rejects.toBeInstanceOf(TokenIntrospectionError) @@ -255,7 +274,7 @@ describe('OAuthDiscoveryStrategy', () => { await new Promise(resolve => noJwksServer.listen(0, '127.0.0.1', resolve)) const { port } = noJwksServer.address() as AddressInfo - const s = new OAuthDiscoveryStrategy({ authorizationServer: `http://127.0.0.1:${port}` }) + const s = new OAuthDiscoveryStrategy({ authorizationServer: `http://127.0.0.1:${port}`, audience: 'https://harbor.example.com' }) const token = await sign({}) await expect(s.validate(token)).rejects.toBeInstanceOf(TokenIntrospectionError) diff --git a/tests/unit/service-wiring.test.ts b/tests/unit/service-wiring.test.ts index 30b3688..8e5f950 100644 --- a/tests/unit/service-wiring.test.ts +++ b/tests/unit/service-wiring.test.ts @@ -23,6 +23,12 @@ describe('resolveAuth', () => { resolveAuth({ type: AUTH_TYPE.STATIC_TOKEN } as never) ).toThrow('config.auth.token is required for static-token auth') }) + + it('throws when oauth-2.1 type has no audience (resource binding, spec §17)', () => { + expect(() => + resolveAuth({ type: AUTH_TYPE.OAUTH_2_1, authorizationServer: 'https://auth.example.com' } as never) + ).toThrow('config.auth.audience (resource binding) is required for oauth-2.1 auth') + }) }) describe('resolveCircuitBreaker', () => { diff --git a/wiring/service-wiring.ts b/wiring/service-wiring.ts index 0dbd694..e711568 100644 --- a/wiring/service-wiring.ts +++ b/wiring/service-wiring.ts @@ -50,9 +50,12 @@ export function resolveAuth(auth: ServiceAuthConfig | undefined, logger?: Logger ...(logger !== undefined ? { logger } : {}), }) case AUTH_TYPE.OAUTH_2_1: + if (!auth.audience || auth.audience.trim() === '') { + throw new Error('config.auth.audience (resource binding) is required for oauth-2.1 auth') + } return oauthDiscovery({ authorizationServer: auth.authorizationServer, - ...(auth.audience !== undefined ? { audience: auth.audience } : {}), + audience: auth.audience, ...(auth.clockToleranceSec !== undefined ? { clockToleranceSec: auth.clockToleranceSec } : {}), ...(auth.scopeClaim !== undefined ? { scopeClaim: auth.scopeClaim } : {}), ...(auth.metadataMapping !== undefined ? { metadataMapping: auth.metadataMapping } : {}), From e98d76f228061b1ac721332c6f0641943d76b831 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:53:53 +0530 Subject: [PATCH 16/25] =?UTF-8?q?feat(http):=20advertise=20single=20suppor?= =?UTF-8?q?ted=20protocol=20version=20on=20/health=20(=C2=A720)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Harbor speaks exactly one MCP protocol version (2026-07-28) and rejects legacy clients at the transport (`legacy: 'reject'`). Surface that version explicitly on the health endpoint so operators and monitoring can assert which protocol the gateway serves, instead of it being implicit in the transport config. Wires up the previously-unused MCP_PROTOCOL_VERSION constant. --- runtime/http/http-gateway.ts | 6 +++++- tests/unit/http-gateway.test.ts | 14 ++++++++++++-- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/runtime/http/http-gateway.ts b/runtime/http/http-gateway.ts index 20661a3..b3879a7 100644 --- a/runtime/http/http-gateway.ts +++ b/runtime/http/http-gateway.ts @@ -12,7 +12,7 @@ import { handleProtectedResourceMetadata } from './oauth-metadata-handler.js' import { readMcpRequestIdentity } from './mcp-request-identity.js' import { sendJson, sendGatewayError } from './send-response.js' import { HttpError } from './http-error.js' -import { ERR, HTTP_ROUTES } from '../../core/constants.js' +import { ERR, HTTP_ROUTES, MCP_PROTOCOL_VERSION } from '../../core/constants.js' import { errorMessage } from '../../core/utils/errors.js' import type { McpServerFactory } from './mcp-server-factory.js' @@ -55,6 +55,10 @@ export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { if (url === HTTP_ROUTES.HEALTH) { sendJson(res, 200, { status: 'ok', + // Single protocol version Harbor speaks (spec §20). Harbor rejects + // legacy clients at the transport (`legacy: 'reject'`); this makes + // the supported version explicit for operators and monitoring. + protocolVersion: MCP_PROTOCOL_VERSION, services: registry.serviceNames() }) return diff --git a/tests/unit/http-gateway.test.ts b/tests/unit/http-gateway.test.ts index 79ab49b..2608e27 100644 --- a/tests/unit/http-gateway.test.ts +++ b/tests/unit/http-gateway.test.ts @@ -4,7 +4,7 @@ import { describe, it, expect, afterEach, vi } from 'vitest' import type { AddressInfo } from 'node:net' import type { AuthInfo } from '@modelcontextprotocol/server' -import { ERR } from '../../core/constants.js' +import { ERR, MCP_PROTOCOL_VERSION } from '../../core/constants.js' const { mockNodeMcpHandler } = vi.hoisted(() => ({ mockNodeMcpHandler: vi.fn() @@ -83,11 +83,21 @@ describe('startHttpGateway', () => { const res = await fetch(`${baseUrl}/health`) expect(res.status).toBe(200) expect(res.headers.get('content-type')).toContain('application/json') - const body = await res.json() as { status: string; services: string[] } + const body = await res.json() as { status: string; protocolVersion: string; services: string[] } expect(body.status).toBe('ok') expect(body.services).toEqual([]) }) + it('GET /health advertises the single supported protocol version (spec §20)', async () => { + const { baseUrl, close } = await startForTest() + cleanup = close + + const res = await fetch(`${baseUrl}/health`) + const body = await res.json() as { protocolVersion: string } + expect(body.protocolVersion).toBe(MCP_PROTOCOL_VERSION) + expect(body.protocolVersion).toBe('2026-07-28') + }) + it('unknown route returns 404 with the gateway error envelope', async () => { const { baseUrl, close } = await startForTest() cleanup = close From f542678d417f7ef5e18df738a01f773cf13f96f3 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 00:59:59 +0530 Subject: [PATCH 17/25] docs(mcp): compatibility matrix + OAuth 2.1 resource-binding requirement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/mcp-2026-07-28-compatibility.md (Requirements.md §28 matrix + §39 A-H final output) built from actual Harbor code, and note the required audience/resource binding on the oauth-2.1 path in the OAuth guide (spec §17, RFC 8707). Co-Authored-By: Claude Opus 4.8 --- docs/mcp-2026-07-28-compatibility.md | 185 +++++++++++++++++++++++++++ docs/oauth-2.1-guide.md | 9 ++ 2 files changed, 194 insertions(+) create mode 100644 docs/mcp-2026-07-28-compatibility.md diff --git a/docs/mcp-2026-07-28-compatibility.md b/docs/mcp-2026-07-28-compatibility.md new file mode 100644 index 0000000..ca4e89e --- /dev/null +++ b/docs/mcp-2026-07-28-compatibility.md @@ -0,0 +1,185 @@ +# Harbor — MCP 2026-07-28 Compatibility + +Harbor implements the MCP 2026-07-28 protocol requirements **applicable to its +supported MCP surface** — the fixed five-tool gateway (`discover_services`, +`discover_skills`, `get_skill_details`, `search_code`, `api_execute`) over +Streamable HTTP and stdio. It is **not** a full implementation of the MCP +2026-07-28 specification, by design. + +This document is the compatibility audit and the record of what changed. + +--- + +## A. Summary + +The upgrade moves Harbor onto the MCP SDK v2 packages +(`@modelcontextprotocol/server`, `@modelcontextprotocol/node`) whose +`createMcpHandler` / `serveStdio` entry points are stateless and speak +2026-07-28 only (`legacy: 'reject'`). The SDK owns the protocol wire layer +(HTTP header validation, version negotiation, request-envelope lifting, +cache-field emission, `server/discover`, `tools/list`). Harbor's own changes are +confined to the application-facing seams the SDK leaves to the server: + +- response `_meta` carrying mandatory `io.modelcontextprotocol/serverInfo`, plus + a clean application-metadata channel; +- an advisory reader for request `_meta` and for the normalized MCP HTTP headers + (routing/observability only, never authorization); +- explicit `server/discover` options — real capabilities, instructions, and + conservative cache hints; +- OAuth 2.1 authorization hardening — required token resource binding; +- an explicit single supported protocol version. + +Harbor's architecture, five-tool surface, and pluggable per-service +authentication are unchanged. + +--- + +## B. Compatibility Matrix + +| MCP 2026-07-28 area | Harbor before | Harbor after | Status | +| --- | --- | --- | --- | +| Stateless protocol core | SDK v1 session model | SDK v2 `createMcpHandler`/`serveStdio`, stateless | REQUIRED — done (SDK) | +| `initialize` / `initialized` | handshake via old SDK | removed; SDK owns lifecycle | NOT APPLICABLE | +| `Mcp-Session-Id` | old session id | not used; stateless | NOT APPLICABLE | +| `MCP-Protocol-Version` header | none | SDK validates; Harbor reads advisory | ALREADY (SDK) + advisory reader | +| `Mcp-Method` header | none | SDK validates; Harbor reads advisory | ALREADY (SDK) + advisory reader | +| `Mcp-Name` header | none | SDK validates; Harbor reads advisory | ALREADY (SDK) + advisory reader | +| `server/discover` | implicit | explicit capabilities + instructions + cache hints | REQUIRED — done | +| Request `_meta` | none | advisory reader (protocol version, clientInfo, clientCapabilities) | REQUIRED — done | +| Response `_meta` | none | attached to every tool result | REQUIRED — done | +| `serverInfo` | none | `io.modelcontextprotocol/serverInfo` on every response | REQUIRED — done | +| `ttlMs` / `cacheScope` | none | conservative hints for `tools/list`, `server/discover` | REQUIRED — done | +| OAuth 2.1 | present, `audience` optional | present, resource binding required | REQUIRED — hardened | +| RFC 9728 Protected Resource Metadata | none | served at `/.well-known/oauth-protected-resource` | REQUIRED — done | +| RFC 8414 AS metadata | none | consumed via discovery | REQUIRED — done | +| Issuer validation | enforced (jose) | enforced (jose) | ALREADY COMPATIBLE | +| Token audience / resource binding | optional | required on `oauth-2.1` path | REQUIRED — hardened | +| Issuer mix-up protection | — | per-AS issuer pinned + `jwks_uri` origin (SSRF) guard | REQUIRED — done | +| `WWW-Authenticate` | none | `Bearer resource_metadata="…"` on 401 | REQUIRED — done | +| Version negotiation | implicit | single version, legacy rejected, surfaced on `/health` | REQUIRED — done | +| stdio transport | present | preserved (`legacy: 'reject'`) | ALREADY COMPATIBLE | +| CIMD / Dynamic Client Registration | none | N/A — Harbor is a resource server, not an AS/client | NOT APPLICABLE | +| Tasks | none | none | OPTIONAL — not implemented | +| MCP Apps | none | none | OPTIONAL — not implemented | +| MRTR / HITL / elicitation / sampling | none | none | OPTIONAL — not implemented | +| roots / logging / subscriptions / prompts / resources | none | none | OPTIONAL — not implemented | + +--- + +## C. Authentication Changes + +Harbor's four pluggable auth providers — `static-token`, `oauth-introspection`, +`jwt-validation`, `oauth-2.1` — are all preserved. No provider was removed or +weakened. + +- **Token resource binding (RFC 8707) — new, required on the `oauth-2.1` + path.** The OAuth 2.1 discovery strategy previously accepted any `aud` when + `audience` was unset. Under MCP 2026-07-28 the resource server MUST reject + tokens not bound to it, so `audience` (the gateway's canonical resource + identifier) is now required and validated. Missing/blank `audience` fails + closed at both strategy construction and config wiring. This closes a + confused-deputy / token pass-through gap where a token minted for another + resource behind the same authorization server would be accepted. +- **Issuer validation** — unchanged; `jose` enforces `iss` on every JWT. +- **Issuer mix-up / SSRF** — discovery rejects a `jwks_uri` whose origin differs + from the authorization server. +- **`WWW-Authenticate` + RFC 9728 Protected Resource Metadata** — a tokenless + request receives `401` with `WWW-Authenticate: Bearer resource_metadata="…"`, + and Harbor serves the PRM document so clients can discover the AS. +- The lower-level `jwt-validation` provider keeps `audience` optional for + standalone use; the protocol-facing `oauth-2.1` path is the one 2026-07-28 + governs. + +See [`oauth-2.1-guide.md`](oauth-2.1-guide.md). + +--- + +## D. `_meta` Changes + +- **Request `_meta`** — an advisory reader lifts the reserved namespace + (`io.modelcontextprotocol/protocolVersion`, `clientInfo`, + `clientCapabilities`), preferring the SDK-lifted request envelope and falling + back to `params._meta`. It is used for observability/routing only and is + **never** consulted for authentication or authorization (spec §9, §19). +- **Response `_meta`** — every tool result carries `_meta`, built by a single + helper so metadata never mixes into model-visible `content`. +- **`serverInfo`** — the mandatory `io.modelcontextprotocol/serverInfo` + (`{ name, version }`) is emitted on every response and cannot be overridden by + application metadata (serverInfo is written last). +- **Application metadata** — the same `_meta` helper accepts an optional + application-metadata object, establishing a clean client-facing channel + (correlation/audit/workflow ids in future) without contaminating content. + This is **plumbing only** — no HITL, approval, elicitation, or Tasks state + machine is implemented (spec §11, §12). + +--- + +## E. Intentionally NOT Implemented + +Excluded from scope because they are not required to keep an existing Harbor +capability compliant: + +- **Tasks** +- **MCP Apps** +- **full MRTR / Human-in-the-Loop**, elicitation, `input_required`, approval + workflows (only the `_meta` transport that could later carry such state) +- **sampling, roots, logging, subscriptions** +- **new resources / prompts / tools**, dynamic tool generation +- **Dynamic Client Registration / CIMD** — Harbor is a resource server, not an + authorization server or client. + +--- + +## F. Files Changed (protocol upgrade) + +Application-facing changes owned by Harbor: + +- `core/constants.ts` — gateway version, reserved `_meta` key names, MCP HTTP + header names, single `MCP_PROTOCOL_VERSION`. +- `tools/tool-helpers.ts` — response `_meta` builder, `serverInfo`, + application-metadata channel, advisory request-`_meta` reader. +- `runtime/http/mcp-server-factory.ts` — `server/discover` options + (capabilities, instructions, cache hints). +- `runtime/http/mcp-request-identity.ts` — advisory MCP HTTP header reader. +- `runtime/http/http-gateway.ts` — request-identity logging; `/health` + advertises the supported protocol version. +- `runtime/transport/stdio-gateway.ts` — SDK v2 `serveStdio`, `legacy: 'reject'`. +- `spi/auth/bearer-authorization.ts`, `runtime/http/oauth-metadata-handler.ts`, + `core/types/oauth.types.ts` — `WWW-Authenticate` + RFC 9728 PRM. +- `adapters/auth/strategies/oauth-discovery.strategy.ts`, + `wiring/service-wiring.ts`, `core/types/config.types.ts` — required token + resource binding on `oauth-2.1`. + +Each area has matching unit/integration tests under `tests/`. + +--- + +## G. Tests + +```bash +npm test # vitest run — 345 passing +npm run typecheck +npm run build # tsc +``` + +New/updated protocol coverage: response `_meta`/serverInfo and request-`_meta` +reader (`tests/unit/tool-helpers.test.ts`), `server/discover` options +(`tests/unit/mcp-server-factory.test.ts`), MCP HTTP headers +(`tests/unit/mcp-request-identity.test.ts`), protocol-version surface +(`tests/unit/http-gateway.test.ts`), OAuth resource binding +(`tests/unit/oauth-discovery.test.ts`, `tests/unit/service-wiring.test.ts`, +`tests/integration/oauth-jwt-auth.test.ts`). + +--- + +## H. Remaining Concerns + +- The SDK v2 packages are pre-1.0 (`2.0.0-beta.4`); the wire behaviors Harbor + depends on (header validation, envelope lifting, cache-field emission, + `server/discover`) are treated as SDK-owned. If the SDK's final release + changes those semantics, revisit the advisory readers and discovery options. +- Token resource binding is enforced on the `oauth-2.1` path by requiring + `audience`. Operators using `jwt-validation` standalone should set `audience` + themselves if they want the same guarantee; it is intentionally left optional + there to preserve that provider's existing behavior. + diff --git a/docs/oauth-2.1-guide.md b/docs/oauth-2.1-guide.md index 2bde18d..7e716a1 100644 --- a/docs/oauth-2.1-guide.md +++ b/docs/oauth-2.1-guide.md @@ -109,6 +109,15 @@ Full field reference: [`configuration.md — oauth-2.1`](configuration.md#oauth- Discovery tries `/.well-known/openid-configuration` first, then `/.well-known/oauth-authorization-server`. The result is cached per strategy instance; Harbor does not re-fetch on every token. +> **`audience` is required (MCP 2026-07-28, RFC 8707 resource binding).** The +> `oauth-2.1` strategy fails closed at startup if `audience` is missing or +> blank. `audience` is the gateway's canonical resource identifier — set it to +> the same value you advertise as `resource` in the Protected Resource Metadata +> (`HARBOR_RESOURCE_URI`). This ensures Harbor rejects an access token minted +> for a *different* resource behind the same authorization server, closing the +> confused-deputy / token pass-through gap. The lower-level `jwt-validation` +> strategy keeps `audience` optional for standalone use. + ### oauth-introspection — token introspection (RFC 7662) Use when the AS does not issue JWTs or when you need server-side revocation checks. From af62fe1026bacd676a7a152ea4d791f730d39ab5 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 04:02:27 +0530 Subject: [PATCH 18/25] test(e2e): live OAuth 2.1 resource-binding coverage via billing api_execute MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds live CI coverage for the MCP 2026-07-28 §17 / RFC 8707 token resource-binding change on the oauth-2.1 path. Per-service JWT audience validation only fires inside api_execute (not server/discover or tools/list), so the confused-deputy case must be exercised there. - examples/demo/billing-service.js: minimal :3004 backend for the billing service so a validated token reaches a real 200 and a rejected token never does. - mock-oauth2-config.json: mints a same-AS, same-signature, wrong-audience JWT for scope=confused-deputy while preserving the default correct-aud client_credentials mapping. - demo_e2e.py: wrong-aud JWT helper, billing backend lifecycle in phase-2, and resource-binding assertions — correct-aud api_execute(billing) returns live invoices; wrong-aud is rejected (isError, TOKEN_INVALID, no data leak). Runs in CI via the existing demo_e2e.py --docker-oauth step. E2E: 105/105. --- .../oauth-config/mock-oauth2-config.json | 10 ++ examples/demo/billing-service.js | 46 ++++++ tests/demo_e2e.py | 142 ++++++++++++++++++ 3 files changed, 198 insertions(+) create mode 100644 examples/demo/billing-service.js diff --git a/examples/07-oauth/oauth-config/mock-oauth2-config.json b/examples/07-oauth/oauth-config/mock-oauth2-config.json index bb6aa89..8fc77a7 100644 --- a/examples/07-oauth/oauth-config/mock-oauth2-config.json +++ b/examples/07-oauth/oauth-config/mock-oauth2-config.json @@ -5,6 +5,16 @@ "issuerId": "default", "tokenExpiry": 3600, "requestMappings": [ + { + "requestParam": "scope", + "match": "confused-deputy", + "claims": { + "sub": "harbor-test-client", + "client_id": "harbor-test-client", + "aud": ["https://not-harbor.example.com"], + "scope": "confused-deputy" + } + }, { "requestParam": "grant_type", "match": "client_credentials", diff --git a/examples/demo/billing-service.js b/examples/demo/billing-service.js new file mode 100644 index 0000000..8ebb57d --- /dev/null +++ b/examples/demo/billing-service.js @@ -0,0 +1,46 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. +// +// Minimal billing backend for the OAuth 2.1 E2E. Serves the two endpoints in +// services/billing/spec.yaml on :3004. The backend itself does NOT check auth — +// Harbor validates the client's JWT (issuer, signature via JWKS, and audience / +// resource binding) *before* ever calling this backend. A request only reaches +// here after Harbor's oauth-2.1 strategy has accepted the token. +import http from 'http' + +const INVOICES = [ + { id: 'inv-001', customerId: 'cust-1', amount: 120.5, currency: 'USD', status: 'issued', dueDate: '2026-09-01' }, + { id: 'inv-002', customerId: 'cust-2', amount: 89.0, currency: 'USD', status: 'paid', dueDate: '2026-08-15' } +] + +function send(res, status, body) { + res.writeHead(status, { 'Content-Type': 'application/json' }) + res.end(JSON.stringify(body)) +} + +const server = http.createServer((req, res) => { + const url = new URL(req.url, `http://${req.headers.host}`) + const path = url.pathname + + if (req.method === 'GET' && path === '/invoices') { + send(res, 200, { invoices: INVOICES, total: INVOICES.length }) + return + } + + const match = path.match(/^\/invoices\/([^/]+)$/) + if (req.method === 'GET' && match) { + const invoice = INVOICES.find((i) => i.id === match[1]) + if (!invoice) { + send(res, 404, { error: 'Invoice not found' }) + return + } + send(res, 200, invoice) + return + } + + send(res, 404, { error: 'Not found' }) +}) + +const PORT = 3004 +server.listen(PORT, () => console.log(`[billing-service] running on http://localhost:${PORT}`)) diff --git a/tests/demo_e2e.py b/tests/demo_e2e.py index ba781ee..542ca6c 100644 --- a/tests/demo_e2e.py +++ b/tests/demo_e2e.py @@ -90,6 +90,7 @@ def section(title): print(f"\n{BOLD}{CYAN}── {title}{RESET}") _procs: list[subprocess.Popen] = [] _oauth_harbor_proc: Optional[subprocess.Popen] = None +_billing_proc: Optional[subprocess.Popen] = None def _find_node() -> str: for candidate in [ @@ -276,6 +277,51 @@ def _stop_harbor_oauth(): _oauth_harbor_proc = None info("Harbor (OAuth mode) stopped") +def _start_billing_backend(): + """Start the billing backend (examples/demo/billing-service.js) on :3004. + + Needed for the resource-binding test: a token that passes oauth-2.1 + validation must reach a *real* backend for a genuine 200, and a rejected + token must never reach it. + """ + global _billing_proc + node = _find_node() + script = ROOT / "examples" / "demo" / "billing-service.js" + _billing_proc = subprocess.Popen( + [node, str(script)], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + env={**os.environ, "NODE_PATH": str(ROOT / "node_modules")}, + cwd=str(ROOT), + start_new_session=True, + ) + info(f"Started billing-service.js (pid {_billing_proc.pid})") + for _ in range(20): + try: + urllib.request.urlopen("http://localhost:3004/invoices", timeout=1) + return + except Exception: + time.sleep(0.5) + raise RuntimeError("billing backend (:3004) did not become ready") + +def _stop_billing_backend(): + global _billing_proc + if _billing_proc is None: + return + try: + os.killpg(os.getpgid(_billing_proc.pid), signal.SIGTERM) + except Exception: + pass + try: + _billing_proc.wait(timeout=3) + except subprocess.TimeoutExpired: + try: + os.killpg(os.getpgid(_billing_proc.pid), signal.SIGKILL) + except Exception: + pass + _billing_proc = None + info("billing backend stopped") + def _get_real_jwt() -> str: data = urllib.parse.urlencode({"grant_type": "client_credentials"}).encode() credentials = base64.b64encode(f"{OAUTH_CLIENT_ID}:{OAUTH_CLIENT_SECRET}".encode()).decode() @@ -291,6 +337,33 @@ def _get_real_jwt() -> str: with urllib.request.urlopen(req, timeout=10) as resp: return json.loads(resp.read().decode())["access_token"] +def _get_jwt_wrong_aud() -> str: + """Mint a JWT from the SAME mock AS but bound to a *different* resource. + + The mock AS config matches `scope=confused-deputy` first and stamps + `aud: ["https://not-harbor.example.com"]`. The token is otherwise + well-formed and signed by the same key Harbor discovers via JWKS — only the + audience differs. This is the confused-deputy / token pass-through scenario + Harbor's oauth-2.1 resource binding (RFC 8707, MCP 2026-07-28 §17) must + reject. + """ + data = urllib.parse.urlencode({ + "grant_type": "client_credentials", + "scope": "confused-deputy", + }).encode() + credentials = base64.b64encode(f"{OAUTH_CLIENT_ID}:{OAUTH_CLIENT_SECRET}".encode()).decode() + req = urllib.request.Request( + f"{OAUTH_AS_BASE}/token", + data=data, + headers={ + "Content-Type": "application/x-www-form-urlencoded", + "Authorization": f"Basic {credentials}", + }, + method="POST", + ) + with urllib.request.urlopen(req, timeout=10) as resp: + return json.loads(resp.read().decode())["access_token"] + def _mcp_envelope() -> dict: return { MCP_META_PROTOCOL: MCP_PROTOCOL, @@ -439,6 +512,30 @@ def call_tool(name: str, args: dict, req_id: int) -> dict: def api_exec(service: str, code: str, req_id: int) -> dict: return call_tool("api_execute", {"service": service, "code": code}, req_id) +def api_exec_jwt(service: str, code: str, req_id: int, jwt: str) -> dict: + """Run api_execute over a JWT-authenticated MCP call. + + Returns a normalized dict so resource-binding assertions can inspect both + the transport/JSON-RPC outcome and the tool-level result: + { is_error: bool, parsed: dict|None, raw: dict } + `is_error` is the MCP tool-result `isError` flag; `parsed` is the decoded + first text-content block (Harbor serializes both success data and error + envelopes as JSON there). + """ + resp = _mcp_post_jwt({ + "jsonrpc": "2.0", "id": req_id, "method": "tools/call", + "params": {"name": "api_execute", "arguments": {"service": service, "code": code}}, + }, jwt, mcp_name="api_execute") + if "_error" in resp: + return {"is_error": True, "parsed": {"error": resp["_error"]}, "raw": resp} + result = resp.get("result", {}) + parsed = None + try: + parsed = json.loads(result["content"][0]["text"]) + except Exception: + pass + return {"is_error": bool(result.get("isError")), "parsed": parsed, "raw": resp} + # ── Assertions ──────────────────────────────────────────────────────────────── _passed = 0 @@ -791,6 +888,49 @@ def test_docker_oauth(resource_uri: str): for name in ("discover_services", "discover_skills", "search_code", "api_execute"): assert_in(name, tool_names, f"tool '{name}' present") + # ── Resource binding (MCP 2026-07-28 §17 / RFC 8707) — LIVE ──────────────── + # Per-service oauth-2.1 JWT validation (signature via discovered JWKS, + # issuer, AND audience) fires inside api_execute BEFORE the backend call. + # server/discover and tools/list do NOT trigger it, so resource binding must + # be exercised through api_execute on the billing service. + section("OAuth 2.1 — resource binding via api_execute (billing)") + + BILLING_CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices" }); return r.data; }') + + # (a) Correct-aud JWT (aud = http://localhost:3333) → validation PASSES, + # backend reached, real invoices returned. + good = api_exec_jwt("billing", BILLING_CODE, 600, jwt) + assert_true(not good["is_error"], + f"api_execute(billing) with correct-aud JWT → success " + f"{(good['parsed'] or {}).get('error', '')}") + invoices = (good["parsed"] or {}).get("invoices", []) + assert_true(len(invoices) > 0, + f"correct-aud JWT → {len(invoices)} invoices returned from live backend") + if invoices: + inv_ids = [i.get("id") for i in invoices] + assert_in("inv-001", inv_ids, "live billing backend returned inv-001") + + # (b) Wrong-aud JWT (same AS, same signature, aud = not-harbor) → resource + # binding REJECTS. Confused-deputy / token pass-through must fail closed. + try: + wrong_jwt = _get_jwt_wrong_aud() + except Exception as e: + assert_true(False, f"wrong-aud JWT acquired from mock AS → {e}") + wrong_jwt = None + + if wrong_jwt: + assert_eq(len(wrong_jwt.split(".")), 3, "wrong-aud JWT is a well-formed JWT") + bad = api_exec_jwt("billing", BILLING_CODE, 601, wrong_jwt) + assert_true(bad["is_error"], + "api_execute(billing) with wrong-aud JWT → rejected (isError)") + bad_parsed = bad["parsed"] or {} + assert_true("invoices" not in bad_parsed, + "wrong-aud JWT → NO invoice data leaked") + code = bad_parsed.get("code", "") + assert_true(code in ("TOKEN_INVALID", "AUTH_FAILED", "TOKEN_EXPIRED"), + f"wrong-aud rejection carries an auth error code (got {code!r})") + # ── Main ────────────────────────────────────────────────────────────────────── def main(): @@ -865,6 +1005,7 @@ def main(): _switch_to_oauth_mode() _docker_oauth_up() try: + _start_billing_backend() _start_harbor_oauth({ "HARBOR_RESOURCE_URI": args.oauth_resource_uri, "HARBOR_AUTH_SERVERS": OAUTH_AS_BASE, @@ -873,6 +1014,7 @@ def main(): test_docker_oauth(args.oauth_resource_uri) finally: _stop_harbor_oauth() + _stop_billing_backend() _docker_oauth_down() _switch_to_token_mode() info("Phase-2 cleanup complete") From cd8c3e0aa669fcf522832a0388b6a54b24e33538 Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 09:49:35 +0530 Subject: [PATCH 19/25] ci: bump actions to v5 and clear high-severity npm audit vulns - actions/checkout@v4.2.2 -> v5, actions/setup-node@v4.4.0 -> v5 (run on Node 24 natively; drop the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 workaround) to resolve the Node 20 deprecation warning. - npm audit fix: bump transitive deps (axios, js-yaml, nanoid, postcss, brace-expansion, fast-uri) to clear all 6 high-severity advisories so the 'npm audit --audit-level=high' CI gate passes. Only 1 low (esbuild dev server, Windows-only) remains, below the gate threshold. typecheck/lint clean; 345 unit+integration tests pass. --- .github/workflows/ci.yml | 6 ++-- package-lock.json | 66 ++++++++++++++++++++-------------------- 2 files changed, 35 insertions(+), 37 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9c37207..a615079 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,13 +7,11 @@ on: jobs: ci: runs-on: ubuntu-latest - env: - FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@v5 - - uses: actions/setup-node@v4.4.0 + - uses: actions/setup-node@v5 with: node-version: '22' cache: 'npm' diff --git a/package-lock.json b/package-lock.json index 2b23f48..57216ce 100644 --- a/package-lock.json +++ b/package-lock.json @@ -717,9 +717,9 @@ } }, "node_modules/@hono/node-server": { - "version": "1.19.14", - "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz", - "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==", + "version": "1.19.17", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.17.tgz", + "integrity": "sha512-dSneS5qhiauZWGDCeK4o695Xd9nUNjviSZCMQrj10eetr8Uln1ucn6bbphOM6UynAMMtNIzZNSpL9vnASJwrPQ==", "license": "MIT", "engines": { "node": ">=18.14.1" @@ -1473,16 +1473,16 @@ } }, "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": { - "version": "5.0.6", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz", - "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==", + "version": "5.0.9", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz", + "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==", "dev": true, "license": "MIT", "dependencies": { "balanced-match": "^4.0.2" }, "engines": { - "node": "18 || 20 || >=22" + "node": "20 || >=22" } }, "node_modules/@typescript-eslint/typescript-estree/node_modules/minimatch": { @@ -1784,13 +1784,13 @@ } }, "node_modules/axios": { - "version": "1.16.1", - "resolved": "https://registry.npmjs.org/axios/-/axios-1.16.1.tgz", - "integrity": "sha512-caYkukvroVPO8KrzuJEb50Hm07KwfBZPEC3VeFHTsqWHvKTsy54hjJz9BS/cdaypROE2rH6xvm9mHX4fgWkr3A==", + "version": "1.20.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.20.0.tgz", + "integrity": "sha512-r8aOh8j9cGKpgQAqpzrUHnSIc6a59Y3Xf/cv8sy1DrHCkZHzQGEuoq1tARk6qSyDdtQGSDgpb9kFlruzPvrgwg==", "license": "MIT", "dependencies": { "follow-redirects": "^1.16.0", - "form-data": "^4.0.5", + "form-data": "^4.0.6", "https-proxy-agent": "^5.0.1", "proxy-from-env": "^2.1.0" } @@ -1834,9 +1834,9 @@ } }, "node_modules/brace-expansion": { - "version": "1.1.14", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", - "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==", + "version": "1.1.18", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz", + "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==", "dev": true, "license": "MIT", "dependencies": { @@ -2520,9 +2520,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz", - "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==", + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.6.tgz", + "integrity": "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q==", "funding": [ { "type": "github", @@ -2810,9 +2810,9 @@ } }, "node_modules/gray-matter/node_modules/js-yaml": { - "version": "3.15.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz", - "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==", + "version": "3.15.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.2.tgz", + "integrity": "sha512-6EuL879VkRA+1Cz578mKMiKvjPNEuk6+r1JaFzoSWejZmtf7xWbIyw1e3KkxlkzTIt9Taw6JBhEppG7utc1P+w==", "license": "MIT", "dependencies": { "argparse": "^1.0.7", @@ -2879,9 +2879,9 @@ "license": "MIT" }, "node_modules/hono": { - "version": "4.12.30", - "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.30.tgz", - "integrity": "sha512-emn+JoJjrN9YTpRDS5it/UI2SO9BAE37T6I3d963RxcZ81G9A4pr2SZTEiiaiKbzx+NKRg5BZ89fCL7gCJCUog==", + "version": "4.13.5", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.5.tgz", + "integrity": "sha512-O6+/eCYRkzzzy0rPWwKLiGBR1nFuUPZynnwjxN1MBA62NNqbT0wQEzQyK2gSO5yDIDB336sXQleAhOHrzlYyKw==", "license": "MIT", "peer": true, "engines": { @@ -3049,9 +3049,9 @@ "license": "MIT" }, "node_modules/js-yaml": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz", - "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==", + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz", + "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==", "funding": [ { "type": "github", @@ -3228,9 +3228,9 @@ "license": "MIT" }, "node_modules/nanoid": { - "version": "3.3.12", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz", - "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==", + "version": "3.3.18", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz", + "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==", "dev": true, "funding": [ { @@ -3502,9 +3502,9 @@ "license": "MIT" }, "node_modules/postcss": { - "version": "8.5.15", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", - "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==", + "version": "8.5.26", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz", + "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==", "dev": true, "funding": [ { @@ -3522,7 +3522,7 @@ ], "license": "MIT", "dependencies": { - "nanoid": "^3.3.12", + "nanoid": "^3.3.17", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" }, From 6e74e72cd21735e02953177160058fcc0834d5ea Mon Sep 17 00:00:00 2001 From: vijay Date: Thu, 27 Aug 2026 09:53:25 +0530 Subject: [PATCH 20/25] docs(changelog): record oauth-2.1 resource-binding breaking change Add [Unreleased] entries for the RFC 8707 required-audience change (breaking for oauth-2.1 configs without an audience), its live E2E coverage, and the high-severity npm audit cleanup. --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39a3e66..aaa6909 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,15 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +### Changed +- **Breaking (`oauth-2.1` auth):** access tokens must now be resource-bound (RFC 8707, MCP 2026-07-28 §17). `audience` is **required** on the `oauth-2.1` auth config and validated against the token's `aud`; a missing/blank `audience` now fails closed at strategy construction and config wiring. Closes a confused-deputy / token pass-through gap where a token minted for another resource behind the same authorization server was accepted. The lower-level `jwt-validation` provider keeps `audience` optional. + +### Added +- Live E2E coverage for OAuth 2.1 resource binding via `api_execute` on the billing service (`tests/demo_e2e.py --docker-oauth`): a correct-audience JWT reaches the backend; a same-issuer, same-signature, wrong-audience JWT is rejected (`TOKEN_INVALID`, no data leak). + +### Security +- Cleared all high-severity `npm audit` advisories (axios, js-yaml, nanoid, postcss, brace-expansion, fast-uri) so the `npm audit --audit-level=high` CI gate passes. + --- ## [1.0.0] — 2026-07-17 From 1ce0d6bda0f6e7018bb4f7ed46e981a88ff366a8 Mon Sep 17 00:00:00 2001 From: vijay Date: Sun, 13 Sep 2026 15:47:09 +0530 Subject: [PATCH 21/25] updated with latest stable sdk and fixes --- .github/workflows/ci.yml | 4 +- .gitignore | 1 + CHANGELOG.md | 32 ++--- .../strategies/jwt-validation.strategy.ts | 30 +++- .../strategies/oauth-discovery.strategy.ts | 8 +- .../oauth-introspection.strategy.ts | 33 +++++ adapters/auth/strategies/resource-binding.ts | 19 +++ core/constants.ts | 43 ++++-- core/types/config.types.ts | 4 +- docs/configuration.md | 5 +- docs/mcp-2026-07-28-compatibility.md | 13 +- docs/oauth-2.1-guide.md | 30 ++-- examples/demo/billing-service.js | 5 + package-lock.json | 26 ++-- package.json | 4 +- runtime/http/http-gateway.ts | 66 ++++++--- runtime/http/mcp-server-factory.ts | 40 ++++-- runtime/transport/stdio-gateway.ts | 10 +- tests/demo_e2e.py | 4 +- tests/unit/http-gateway.test.ts | 78 ++++++++++- tests/unit/jwt-validation.test.ts | 34 ++++- tests/unit/mcp-server-factory.test.ts | 128 +++++++++++++++++- tests/unit/resource-binding.test.ts | 23 ++++ tests/unit/stdio-gateway.test.ts | 65 +++++++++ tests/unit/token-validator.test.ts | 55 ++++++++ tools/discover-skills.tool.ts | 6 +- tools/execute-api.tool.ts | 12 +- tools/search-code.tool.ts | 6 +- tools/tool-helpers.ts | 47 ++++--- wiring/service-wiring.ts | 15 +- 30 files changed, 691 insertions(+), 155 deletions(-) create mode 100644 adapters/auth/strategies/resource-binding.ts create mode 100644 tests/unit/resource-binding.test.ts create mode 100644 tests/unit/stdio-gateway.test.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a615079..77d7d74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,9 +9,9 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - - uses: actions/setup-node@v5 + - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0 with: node-version: '22' cache: 'npm' diff --git a/.gitignore b/.gitignore index b4d6dbc..7e8c304 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ coverage/ .internal/ reviews/ __pycache__/ +pr_reviews/ diff --git a/CHANGELOG.md b/CHANGELOG.md index aaa6909..d313323 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,42 +7,32 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm --- -## [Unreleased] +## [1.0.0] — Unreleased -### Changed -- **Breaking (`oauth-2.1` auth):** access tokens must now be resource-bound (RFC 8707, MCP 2026-07-28 §17). `audience` is **required** on the `oauth-2.1` auth config and validated against the token's `aud`; a missing/blank `audience` now fails closed at strategy construction and config wiring. Closes a confused-deputy / token pass-through gap where a token minted for another resource behind the same authorization server was accepted. The lower-level `jwt-validation` provider keeps `audience` optional. - -### Added -- Live E2E coverage for OAuth 2.1 resource binding via `api_execute` on the billing service (`tests/demo_e2e.py --docker-oauth`): a correct-audience JWT reaches the backend; a same-issuer, same-signature, wrong-audience JWT is rejected (`TOKEN_INVALID`, no data leak). - -### Security -- Cleared all high-severity `npm audit` advisories (axios, js-yaml, nanoid, postcss, brace-expansion, fast-uri) so the `npm audit --audit-level=high` CI gate passes. - ---- - -## [1.0.0] — 2026-07-17 +> Everything below is pending the first `1.0.0` tag/release of this project (previous published version: `0.1.0`). No `0.2.0` version was ever published to `package.json` — the stateless-HTTP change originally drafted under a `[0.2.0]` heading is folded in here since it ships as part of this same `1.0.0` release. ### Changed - **Breaking:** Harbor 1.0 implements MCP protocol revision **2026-07-28** only (`legacy: 'reject'`). The 2025 `initialize` / `notifications/initialized` handshake is no longer supported. - **Breaking:** HTTP clients must send `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, and (for `tools/call`) `Mcp-Name` on every POST, plus the per-request `_meta` envelope (`io.modelcontextprotocol/protocolVersion`, `clientInfo`, `clientCapabilities`). - **Breaking:** Replaced `@modelcontextprotocol/sdk` v1 with `@modelcontextprotocol/server` and `@modelcontextprotocol/node` v2 (`createMcpHandler`, `serveStdio`). +- **Breaking:** HTTP transport is now stateless. Each `/mcp` request creates a fresh MCP server and transport. No `mcp-session-id` header is issued or required. +- **Breaking:** Removed `SESSION_IDLE_TTL_MS` and `SESSION_SWEEP_INTERVAL_MS` environment variables. +- **Breaking:** `/health` no longer returns `activeSessions`. +- **Breaking (`oauth-2.1` and `jwt-validation` auth):** access tokens must now be resource-bound (RFC 8707, MCP 2026-07-28 §17). `audience` is **required** on both the `oauth-2.1` and `jwt-validation` auth configs and validated against the token's `aud`; a missing/blank `audience` now fails closed at strategy construction and config wiring. Closes the confused-deputy / token pass-through gap where a token minted for another resource behind the same authorization server was accepted. `oauth-introspection` gains an optional `audience` check too, but it is **best-effort, not fail-closed** — RFC 7662 §2.2 makes `aud` an optional introspection response field, so a response that omits it is still accepted. - Upgraded `zod` to v4 (required by MCP SDK v2 tool schema registration). +- Renamed internal factory `createSessionServer` → `createMcpServer`. ### Added - `server/discover` as the connection probe (replaces `initialize`). - Shared `buildMcpServerFactory` for HTTP and stdio transports. - -## [0.2.0] — 2026-07-17 - -### Changed -- **Breaking:** HTTP transport is now stateless. Each `/mcp` request creates a fresh MCP server and transport. No `mcp-session-id` header is issued or required. -- **Breaking:** Removed `SESSION_IDLE_TTL_MS` and `SESSION_SWEEP_INTERVAL_MS` environment variables. -- **Breaking:** `/health` no longer returns `activeSessions`. -- Renamed internal factory `createSessionServer` → `createMcpServer`. +- Live E2E coverage for OAuth 2.1 resource binding via `api_execute` on the billing service (`tests/demo_e2e.py --docker-oauth`): a correct-audience JWT reaches the backend; a same-issuer, same-signature, wrong-audience JWT is rejected (`TOKEN_INVALID`, no data leak). ### Removed - `SessionManager`, idle session sweep, session resume routing, and `ERR.UNKNOWN_SESSION`. +### Security +- Bumped `axios` and `js-yaml` to non-vulnerable versions via `npm audit fix`. No remaining high-severity `npm audit` advisories; `npm audit --audit-level=high` CI gate passes. Two moderate (`vitest`/`@vitest/mocker`) and one low (`esbuild`, Windows-only dev-server path) advisories remain — all three are dev-only dependencies (test runner / build tool), not shipped in the published package, and below the CI gate's `high` threshold. + --- ## [0.1.0] — 2026-05-27 diff --git a/adapters/auth/strategies/jwt-validation.strategy.ts b/adapters/auth/strategies/jwt-validation.strategy.ts index be9108a..56b17b7 100644 --- a/adapters/auth/strategies/jwt-validation.strategy.ts +++ b/adapters/auth/strategies/jwt-validation.strategy.ts @@ -10,11 +10,20 @@ import { } from '../../../core/types/auth.types.js' import type { Logger } from '../../../core/types/logger.types.js' import { AUTH_TYPE } from '../../../core/constants.js' +import { requireResourceBindingAudience } from './resource-binding.js' export interface JwtValidationConfig { jwksUri: string issuer: string - audience?: string + /** + * Canonical resource identifier this gateway accepts tokens for (RFC 8707 + * resource indicator / JWT `aud`). REQUIRED under MCP 2026-07-28 (spec §17): + * the resource server MUST reject tokens not bound to it, otherwise a token + * minted for another resource behind the same authorization server would be + * accepted here (confused-deputy / token pass-through). Set this to the value + * Harbor advertises as `resource` in its Protected Resource Metadata. + */ + audience: string clockToleranceSec?: number scopeClaim?: string metadataMapping?: Record @@ -30,6 +39,13 @@ export class JwtValidationStrategy implements AuthStrategy { private readonly logger?: Logger constructor(config: JwtValidationConfig) { + // Fail closed on missing resource binding (spec §17, RFC 8707). Without an + // audience, JWT verification would accept any `aud`, defeating + // resource-binding — so this is a misconfiguration, not a soft default. + requireResourceBindingAudience( + config.audience, + 'jwt-validation auth requires `audience` (resource binding) under MCP 2026-07-28' + ) this.config = config this.logger = config.logger this.JWKS = createRemoteJWKSet(new URL(config.jwksUri), { @@ -42,14 +58,22 @@ export class JwtValidationStrategy implements AuthStrategy { try { const { payload } = await jwtVerify(rawToken, this.JWKS, { issuer: this.config.issuer, - ...(this.config.audience ? { audience: this.config.audience } : {}), + audience: this.config.audience, clockTolerance: this.config.clockToleranceSec ?? 30, }) return this.mapClaims(payload as Record, rawToken) } catch (err) { const name = (err as Error).name if (name === 'JWTExpired') throw new TokenExpiredError('JWT exp claim exceeded') - if (name === 'JWTClaimValidationFailed') throw new TokenInvalidError((err as Error).message) + if (name === 'JWTClaimValidationFailed') { + // Log the specific failing claim server-side only (e.g. "unexpected + // \"aud\" claim value" would tell an attacker iterating on a + // confused-deputy attempt exactly which claim to fix next); the + // client only ever sees a generic, non-specific rejection reason — + // consistent with the other branches below. + this.logger?.warn({ err: (err as Error).message }, 'JWT claim validation failed') + throw new TokenInvalidError('claim validation failed') + } if (name === 'JWSSignatureVerificationFailed') throw new TokenInvalidError('signature invalid') if (name === 'JWSInvalid') throw new TokenInvalidError('malformed JWT structure') this.logger?.error({ err }, 'Unexpected JWT validation error') diff --git a/adapters/auth/strategies/oauth-discovery.strategy.ts b/adapters/auth/strategies/oauth-discovery.strategy.ts index 69169e7..ecfd468 100644 --- a/adapters/auth/strategies/oauth-discovery.strategy.ts +++ b/adapters/auth/strategies/oauth-discovery.strategy.ts @@ -6,6 +6,7 @@ import { TokenIntrospectionError } from '../../../core/types/auth.types.js' import type { Logger } from '../../../core/types/logger.types.js' import { AUTH_TYPE } from '../../../core/constants.js' import { JwtValidationStrategy } from './jwt-validation.strategy.js' +import { requireResourceBindingAudience } from './resource-binding.js' export interface OAuthDiscoveryConfig { authorizationServer: string @@ -38,9 +39,10 @@ export class OAuthDiscoveryStrategy implements AuthStrategy { // Fail closed on missing resource binding (spec §17, RFC 8707). Without an // audience the inner JWT verification would accept any `aud`, defeating // resource-binding — so this is a misconfiguration, not a soft default. - if (!config.audience || config.audience.trim() === '') { - throw new Error('OAuth 2.1 auth requires `audience` (resource binding) under MCP 2026-07-28') - } + requireResourceBindingAudience( + config.audience, + 'OAuth 2.1 auth requires `audience` (resource binding) under MCP 2026-07-28' + ) this.config = config this.logger = config.logger } diff --git a/adapters/auth/strategies/oauth-introspection.strategy.ts b/adapters/auth/strategies/oauth-introspection.strategy.ts index eac7d1a..07da368 100644 --- a/adapters/auth/strategies/oauth-introspection.strategy.ts +++ b/adapters/auth/strategies/oauth-introspection.strategy.ts @@ -43,6 +43,22 @@ export interface OAuthIntrospectionConfig { tokenRefreshBufferSec?: number responseMapping?: ResponseMapping metadataMapping?: MetadataMapping + /** + * Canonical resource identifier this gateway accepts tokens for (RFC 8707 + * resource indicator). OPTIONAL, unlike the `oauth-2.1`/`jwt-validation` + * strategies' `audience`, because RFC 7662 introspection responses do not + * universally carry an audience-equivalent claim — support here is + * best-effort and AS-dependent. + * + * When set, this is matched against the introspection response's `aud` + * claim (RFC 7662 §2.2 lists `aud` as an optional response member; string + * or string-array values are both accepted). If the AS's introspection + * response omits `aud` entirely, validation is skipped (cannot verify what + * isn't present) — configuring this field narrows, but does not eliminate, + * the confused-deputy exposure for ASes that omit `aud` from introspection + * responses. If `aud` IS present and does not match, the token is rejected. + */ + audience?: string } export class OAuthIntrospectionStrategy implements AuthStrategy { @@ -55,6 +71,7 @@ export class OAuthIntrospectionStrategy implements AuthStrategy { private readonly tokenParamName: string private readonly responseMapping: ResponseMapping private readonly metadataMapping: MetadataMapping + private readonly audience?: string constructor(private readonly config: OAuthIntrospectionConfig) { const scheme = config.protocol ?? 'http' @@ -68,6 +85,7 @@ export class OAuthIntrospectionStrategy implements AuthStrategy { this.tokenRefreshBufferSec = config.tokenRefreshBufferSec ?? 300 this.responseMapping = config.responseMapping ?? {} this.metadataMapping = config.metadataMapping ?? {} + this.audience = config.audience && config.audience.trim() !== '' ? config.audience : undefined if (config.refreshPath) { this.refreshUrl = joinUrl(origin, config.refreshPath) @@ -187,6 +205,21 @@ export class OAuthIntrospectionStrategy implements AuthStrategy { throw new TokenExpiredError('expires_in <= 0 or invalid in auth response') } + // Resource binding (RFC 8707 / MCP 2026-07-28 §17), best-effort: only + // checked when `audience` is configured AND the introspection response + // actually carries an `aud` claim (RFC 7662 §2.2 — `aud` is an optional + // response member, so many ASes omit it; we cannot fail closed on + // absence the way the JWT-based strategies do on a missing config value). + if (this.audience !== undefined) { + const rawAud = body['aud'] + if (rawAud !== undefined) { + const audValues = Array.isArray(rawAud) ? rawAud : [rawAud] + if (!audValues.includes(this.audience)) { + throw new TokenInvalidError('resource binding: aud mismatch') + } + } + } + const accessToken = (resolve(this.responseMapping.access_token, 'token', 'access_token') ?? rawToken) as string const metadata: Record = {} diff --git a/adapters/auth/strategies/resource-binding.ts b/adapters/auth/strategies/resource-binding.ts new file mode 100644 index 0000000..c96ba59 --- /dev/null +++ b/adapters/auth/strategies/resource-binding.ts @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +/** + * Fail-closed guard for RFC 8707 resource binding (MCP 2026-07-28 §17): + * without a required `audience`, JWT verification would accept a token + * minted for any resource behind the same authorization server (confused + * deputy / token pass-through). Shared by the `oauth-2.1` and + * `jwt-validation` strategy constructors and by config wiring, so the + * fail-closed condition can't drift between call sites. + */ +export function requireResourceBindingAudience( + audience: string | undefined, + message: string +): asserts audience is string { + if (!audience || audience.trim() === '') { + throw new Error(message) + } +} diff --git a/core/constants.ts b/core/constants.ts index 194cfe9..789965a 100644 --- a/core/constants.ts +++ b/core/constants.ts @@ -1,6 +1,13 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. +import { + PROTOCOL_VERSION_META_KEY as SDK_PROTOCOL_VERSION_META_KEY, + CLIENT_INFO_META_KEY as SDK_CLIENT_INFO_META_KEY, + CLIENT_CAPABILITIES_META_KEY as SDK_CLIENT_CAPABILITIES_META_KEY, + SERVER_INFO_META_KEY as SDK_SERVER_INFO_META_KEY +} from '@modelcontextprotocol/server' + // ── Deployment environments ────────────────────────────────────────────────── export const ENV = { @@ -197,17 +204,31 @@ export const GATEWAY_VERSION = '1.0.0' // carried out-of-band from model-visible `content`. Harbor treats inbound // values as untrusted (never for auth/security) and only *emits* serverInfo. -/** Response `_meta` key carrying server identity (spec §10, MANDATORY). */ -export const SERVER_INFO_META_KEY = 'io.modelcontextprotocol/serverInfo' - -/** Request `_meta` key carrying the negotiated protocol version (spec §9). */ -export const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion' - -/** Request `_meta` key carrying client implementation info (spec §9). */ -export const CLIENT_INFO_META_KEY = 'io.modelcontextprotocol/clientInfo' - -/** Request `_meta` key carrying client capabilities (spec §9). */ -export const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities' +/** + * Response `_meta` key carrying server identity (spec §10). Recommended + * (SHOULD, not mandatory). Re-exported from the SDK's own reserved-key + * constant so Harbor and the SDK cannot silently drift on this string. + */ +export const SERVER_INFO_META_KEY = SDK_SERVER_INFO_META_KEY + +/** + * Request `_meta` key carrying the negotiated protocol version (spec §9). + * Re-exported from the SDK's own reserved-key constant so Harbor and the SDK + * cannot silently drift on this string. + */ +export const PROTOCOL_VERSION_META_KEY = SDK_PROTOCOL_VERSION_META_KEY + +/** + * Request `_meta` key carrying client implementation info (spec §9). + * Re-exported from the SDK's own reserved-key constant. + */ +export const CLIENT_INFO_META_KEY = SDK_CLIENT_INFO_META_KEY + +/** + * Request `_meta` key carrying client capabilities (spec §9). + * Re-exported from the SDK's own reserved-key constant. + */ +export const CLIENT_CAPABILITIES_META_KEY = SDK_CLIENT_CAPABILITIES_META_KEY /** The single MCP protocol version this gateway speaks (spec §20). */ export const MCP_PROTOCOL_VERSION = '2026-07-28' diff --git a/core/types/config.types.ts b/core/types/config.types.ts index ce0bfe0..11a997e 100644 --- a/core/types/config.types.ts +++ b/core/types/config.types.ts @@ -41,8 +41,8 @@ export type IdempotencyBackendConfig = export type ServiceAuthConfig = | { type: 'static-token'; token?: string; protocol?: 'http' | 'https'; host?: string; port?: number; introspectionPath?: string; authTimeoutMs?: number; method?: 'GET' | 'POST'; tokenPassMode?: 'query' | 'body' | 'header'; tokenParamName?: string; refreshPath?: string; tokenRefreshBufferSec?: number } - | { type: 'oauth-introspection'; protocol?: 'http' | 'https'; host: string; port: number; introspectionPath: string; authTimeoutMs?: number; method?: 'GET' | 'POST'; tokenPassMode?: 'query' | 'body' | 'header'; tokenParamName?: string; refreshPath?: string; tokenRefreshBufferSec?: number; responseMapping?: Record; metadataMapping?: Record } - | { type: 'jwt-validation'; jwksUri: string; issuer: string; audience?: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record } + | { type: 'oauth-introspection'; protocol?: 'http' | 'https'; host: string; port: number; introspectionPath: string; authTimeoutMs?: number; method?: 'GET' | 'POST'; tokenPassMode?: 'query' | 'body' | 'header'; tokenParamName?: string; refreshPath?: string; tokenRefreshBufferSec?: number; responseMapping?: Record; metadataMapping?: Record; audience?: string } + | { type: 'jwt-validation'; jwksUri: string; issuer: string; audience: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record } | { type: 'oauth-2.1'; authorizationServer: string; audience: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record; discoveryTimeoutMs?: number } export type ServiceCircuitBreakerConfig = diff --git a/docs/configuration.md b/docs/configuration.md index d1d29d6..095e387 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -226,6 +226,7 @@ All fields and their roles: | `tokenRefreshBufferSec` | | — | Seconds before expiry to trigger proactive refresh. | | `responseMapping` | | — | Dot-path mapping from introspection response fields to `TokenPayload` fields (`access_token`, `expires_in`, `refresh_token`, `scope`). | | `metadataMapping` | | — | Dot-path mapping from introspection response to `TokenPayload.metadata` (arbitrary key/value; available to tools, e.g. `userId` for audit hashing). | +| `audience` | | not checked | Expected `aud` claim value (resource binding, RFC 8707). **Best-effort, not fail-closed**: RFC 7662 §2.2 makes `aud` an optional introspection response member, so if configured but the AS's response omits `aud`, the token is still accepted. When both `audience` is configured and the response includes `aud`, a mismatch is rejected. | ### `static-token` (local dev / POC only) @@ -266,7 +267,7 @@ Verifies JWTs locally against a JWKS endpoint. No round-trip to the AS per token | `type` | ✅ | — | Must be `"jwt-validation"`. | | `jwksUri` | ✅ | — | JWKS endpoint URL. | | `issuer` | ✅ | — | Expected `iss` claim value. | -| `audience` | | not checked | Expected `aud` claim value. | +| `audience` | ✅ | — | Expected `aud` claim value (resource binding, RFC 8707). Required and fail-closed — Harbor rejects tokens not bound to this resource. | | `clockToleranceSec` | | `30` | Seconds of clock skew to allow. | | `scopeClaim` | | `"scope"` | JWT claim name holding the scope string or array. | | `metadataMapping` | | `{}` | Dot-path map from JWT payload claims into `TokenPayload.metadata`. | @@ -295,7 +296,7 @@ Simpler than `jwt-validation` when your AS follows RFC 8414 or OIDC Discovery: H | ----- | -------- | ------- | ---- | | `type` | ✅ | — | Must be `"oauth-2.1"`. | | `authorizationServer` | ✅ | — | Base URL of the AS (no trailing slash). Harbor tries `/.well-known/openid-configuration` then `/.well-known/oauth-authorization-server`. | -| `audience` | | not checked | Expected `aud` claim value. | +| `audience` | ✅ | — | Expected `aud` claim value (resource binding, RFC 8707). Required and fail-closed — Harbor rejects tokens not bound to this resource. | | `clockToleranceSec` | | `30` | Seconds of clock skew to allow. | | `scopeClaim` | | `"scope"` | JWT claim name for the scope. | | `metadataMapping` | | `{}` | Map JWT payload claims into `TokenPayload.metadata`. | diff --git a/docs/mcp-2026-07-28-compatibility.md b/docs/mcp-2026-07-28-compatibility.md index ca4e89e..9aafc69 100644 --- a/docs/mcp-2026-07-28-compatibility.md +++ b/docs/mcp-2026-07-28-compatibility.md @@ -20,8 +20,8 @@ The upgrade moves Harbor onto the MCP SDK v2 packages cache-field emission, `server/discover`, `tools/list`). Harbor's own changes are confined to the application-facing seams the SDK leaves to the server: -- response `_meta` carrying mandatory `io.modelcontextprotocol/serverInfo`, plus - a clean application-metadata channel; +- response `_meta` carrying `io.modelcontextprotocol/serverInfo` (spec §10, + recommended), plus a clean application-metadata channel; - an advisory reader for request `_meta` and for the normalized MCP HTTP headers (routing/observability only, never authorization); - explicit `server/discover` options — real capabilities, instructions, and @@ -47,7 +47,7 @@ authentication are unchanged. | `server/discover` | implicit | explicit capabilities + instructions + cache hints | REQUIRED — done | | Request `_meta` | none | advisory reader (protocol version, clientInfo, clientCapabilities) | REQUIRED — done | | Response `_meta` | none | attached to every tool result | REQUIRED — done | -| `serverInfo` | none | `io.modelcontextprotocol/serverInfo` on every response | REQUIRED — done | +| `serverInfo` | none | `io.modelcontextprotocol/serverInfo` on every response | RECOMMENDED (SHOULD) — done | | `ttlMs` / `cacheScope` | none | conservative hints for `tools/list`, `server/discover` | REQUIRED — done | | OAuth 2.1 | present, `audience` optional | present, resource binding required | REQUIRED — hardened | | RFC 9728 Protected Resource Metadata | none | served at `/.well-known/oauth-protected-resource` | REQUIRED — done | @@ -103,9 +103,10 @@ See [`oauth-2.1-guide.md`](oauth-2.1-guide.md). **never** consulted for authentication or authorization (spec §9, §19). - **Response `_meta`** — every tool result carries `_meta`, built by a single helper so metadata never mixes into model-visible `content`. -- **`serverInfo`** — the mandatory `io.modelcontextprotocol/serverInfo` - (`{ name, version }`) is emitted on every response and cannot be overridden by - application metadata (serverInfo is written last). +- **`serverInfo`** — `io.modelcontextprotocol/serverInfo` (`{ name, version }`) + is emitted on every response and cannot be overridden by application + metadata (serverInfo is written last). Spec §10, recommended (SHOULD, not + mandatory). - **Application metadata** — the same `_meta` helper accepts an optional application-metadata object, establishing a clean client-facing channel (correlation/audit/workflow ids in future) without contaminating content. diff --git a/docs/oauth-2.1-guide.md b/docs/oauth-2.1-guide.md index 7e716a1..77b1c08 100644 --- a/docs/oauth-2.1-guide.md +++ b/docs/oauth-2.1-guide.md @@ -109,14 +109,27 @@ Full field reference: [`configuration.md — oauth-2.1`](configuration.md#oauth- Discovery tries `/.well-known/openid-configuration` first, then `/.well-known/oauth-authorization-server`. The result is cached per strategy instance; Harbor does not re-fetch on every token. -> **`audience` is required (MCP 2026-07-28, RFC 8707 resource binding).** The -> `oauth-2.1` strategy fails closed at startup if `audience` is missing or -> blank. `audience` is the gateway's canonical resource identifier — set it to -> the same value you advertise as `resource` in the Protected Resource Metadata -> (`HARBOR_RESOURCE_URI`). This ensures Harbor rejects an access token minted -> for a *different* resource behind the same authorization server, closing the -> confused-deputy / token pass-through gap. The lower-level `jwt-validation` -> strategy keeps `audience` optional for standalone use. +> Note: `services/billing/config.json`'s `audience` (`http://localhost:3333`) +> intentionally does not match this guide's default `HARBOR_RESOURCE_URI` +> example (`http://127.0.0.1:3333`) or the `demo_e2e.py` default — a service's +> `audience` and the gateway's advertised `HARBOR_RESOURCE_URI` are +> independently configured values that happen to often be the same string in +> practice, not the same setting. `mock-oauth2-config.json` mints its +> "correct" demo JWT with `aud: ["http://localhost:3333"]` to match the +> service config, not the resource-metadata default. + +> **`audience` is required (MCP 2026-07-28, RFC 8707 resource binding).** Both +> the `oauth-2.1` and `jwt-validation` strategies fail closed at startup if +> `audience` is missing or blank. `audience` is the gateway's canonical +> resource identifier — set it to the same value you advertise as `resource` +> in the Protected Resource Metadata (`HARBOR_RESOURCE_URI`). This ensures +> Harbor rejects an access token minted for a *different* resource behind the +> same authorization server, closing the confused-deputy / token pass-through +> gap for both strategies. `oauth-introspection` supports an optional +> `audience` field too, but per RFC 7662 §2.2 the introspection response isn't +> guaranteed to include an `aud` claim — see +> [`configuration.md — oauth-introspection`](configuration.md#oauth-introspection-recommended-for-production) +> for its best-effort (not fail-closed) semantics. ### oauth-introspection — token introspection (RFC 7662) @@ -144,6 +157,7 @@ Use when the AS does not issue JWTs or when you need server-side revocation chec | Client sends no token, `HARBOR_RESOURCE_URI` not set | Unchanged — plain 401, no `WWW-Authenticate` | | Client sends no token, `HARBOR_RESOURCE_URI` set | **New** — 401 with `WWW-Authenticate: Bearer resource_metadata="..."` | | `stdio` transport | Completely unaffected — MCP spec exempts stdio from OAuth 2.1 | +| Existing `oauth-2.1` service config with no `audience` | **Breaking** — fails at startup (fail-closed, see note above). Set `audience` to the resource identifier your AS mints tokens for — typically the same value as `HARBOR_RESOURCE_URI` if you use RFC 9728 discovery, or the gateway's own base URL if you don't. | ## Running the E2E test suite diff --git a/examples/demo/billing-service.js b/examples/demo/billing-service.js index 8ebb57d..235cc4e 100644 --- a/examples/demo/billing-service.js +++ b/examples/demo/billing-service.js @@ -42,5 +42,10 @@ const server = http.createServer((req, res) => { send(res, 404, { error: 'Not found' }) }) +server.on('error', (err) => { + console.error(`[billing-service] server error: ${err.message}`) + process.exit(1) +}) + const PORT = 3004 server.listen(PORT, () => console.log(`[billing-service] running on http://localhost:${PORT}`)) diff --git a/package-lock.json b/package-lock.json index 57216ce..58e2936 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,8 +10,8 @@ "license": "Apache-2.0", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", - "@modelcontextprotocol/node": "^2.0.0-beta.4", - "@modelcontextprotocol/server": "^2.0.0-beta.4", + "@modelcontextprotocol/node": "2.0.0", + "@modelcontextprotocol/server": "2.0.0", "axios": "^1.7.9", "dotenv": "^17.4.2", "gray-matter": "^4.0.3", @@ -808,9 +808,9 @@ "license": "MIT" }, "node_modules/@modelcontextprotocol/core": { - "version": "2.0.0-beta.4", - "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0-beta.4.tgz", - "integrity": "sha512-nsMXd4wQBKzmph6r+WOhum+mXjDYljTAqwY/XUg3hLtvNOQ8+JVqBSJOVCMJvx9lXhTpTOPrGZ3BuNiaNPjSvg==", + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0.tgz", + "integrity": "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA==", "license": "MIT", "dependencies": { "zod": "^4.2.0" @@ -820,9 +820,9 @@ } }, "node_modules/@modelcontextprotocol/node": { - "version": "2.0.0-beta.4", - "resolved": "https://registry.npmjs.org/@modelcontextprotocol/node/-/node-2.0.0-beta.4.tgz", - "integrity": "sha512-OqbrRVNYNfLxBB2BRkP5oIHKHa0IPHluMbaLgw7YCRKcj5be9ExzyWFJY3KVMb+1F2AVn+0SRoH0XKcNzh3HYQ==", + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/node/-/node-2.0.0.tgz", + "integrity": "sha512-Y4hAC2XdGDUdDOCbLDOCA4+aL3NUldjsOWlDL/YwpAxrPhRm1xHd7lZ+mLacvZ9t3PaH28wgNoaLQGrIk1P2pg==", "license": "MIT", "dependencies": { "@hono/node-server": "^1.19.9" @@ -831,7 +831,7 @@ "node": ">=20" }, "peerDependencies": { - "@modelcontextprotocol/server": "^2.0.0-beta.4", + "@modelcontextprotocol/server": "^2.0.0", "hono": "^4.11.4" }, "peerDependenciesMeta": { @@ -841,12 +841,12 @@ } }, "node_modules/@modelcontextprotocol/server": { - "version": "2.0.0-beta.4", - "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0-beta.4.tgz", - "integrity": "sha512-pjMZcNEt1dOq0aJCcY3b7w1Ayh+qmQN2xlfTELcGV9yiAjEGIczBPBLWWW0k0zzo5T8kiv15jtKPsWeHGxLvLg==", + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0.tgz", + "integrity": "sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw==", "license": "MIT", "dependencies": { - "@modelcontextprotocol/core": "2.0.0-beta.4", + "@modelcontextprotocol/core": "2.0.0", "zod": "^4.2.0" }, "engines": { diff --git a/package.json b/package.json index 90c9761..71dbaf9 100644 --- a/package.json +++ b/package.json @@ -34,8 +34,8 @@ }, "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", - "@modelcontextprotocol/node": "^2.0.0-beta.4", - "@modelcontextprotocol/server": "^2.0.0-beta.4", + "@modelcontextprotocol/node": "2.0.0", + "@modelcontextprotocol/server": "2.0.0", "axios": "^1.7.9", "dotenv": "^17.4.2", "gray-matter": "^4.0.3", diff --git a/runtime/http/http-gateway.ts b/runtime/http/http-gateway.ts index b3879a7..8779bdb 100644 --- a/runtime/http/http-gateway.ts +++ b/runtime/http/http-gateway.ts @@ -2,7 +2,7 @@ // Copyright 2026 Contributors to the Harbor project. import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http' -import { createMcpHandler, type AuthInfo } from '@modelcontextprotocol/server' +import { createMcpHandler, UnsupportedProtocolVersionError, type AuthInfo } from '@modelcontextprotocol/server' import { toNodeHandler, type NodeMcpRequestHandler } from '@modelcontextprotocol/node' import type { Logger } from '../observability/logger.js' import type { ServiceRegistry } from '../registry/service-registry.js' @@ -14,15 +14,26 @@ import { sendJson, sendGatewayError } from './send-response.js' import { HttpError } from './http-error.js' import { ERR, HTTP_ROUTES, MCP_PROTOCOL_VERSION } from '../../core/constants.js' import { errorMessage } from '../../core/utils/errors.js' -import type { McpServerFactory } from './mcp-server-factory.js' +import type { GatewayMcpServerFactory } from './mcp-server-factory.js' /** Node request with pass-through auth for {@linkcode toNodeHandler}. */ type AuthenticatedIncomingMessage = IncomingMessage & { auth?: AuthInfo } +/** + * Placeholder `AuthInfo.clientId` for every request. Harbor's current bearer + * auth flow does not derive a real per-principal client id or scopes from the + * token — the SDK's `AuthInfo` type documents these as carrying real + * per-principal semantics, so this sentinel is named and commented explicitly + * (rather than a bare literal) to stay grep-able as a known placeholder + * pending real per-principal `clientId`/`scopes` derivation (e.g. from token + * introspection/claims). + */ +const UNSCOPED_CLIENT_ID = 'harbor-client' as const + export interface HttpGatewayOptions { host: string port: number - createMcpServer: McpServerFactory + createMcpServer: GatewayMcpServerFactory registry: ServiceRegistry logger: Logger oauthConfig?: OAuthResourceConfig @@ -45,8 +56,27 @@ export interface HttpGatewayHandle { export function startHttpGateway(opts: HttpGatewayOptions): HttpGatewayHandle { const { host, port, createMcpServer, registry, logger, oauthConfig } = opts - const mcpHandler = createMcpHandler(createMcpServer, { legacy: 'reject' }) - const nodeMcpHandler = toNodeHandler(mcpHandler) + // Both `createMcpHandler` and `toNodeHandler` catch every failure internally + // and always resolve/write a response — neither one ever throws back to the + // caller. `onerror` is the SDK's only hook for observing these failures + // (including a legacy-protocol client hitting `legacy: 'reject'`), so it is + // the sole mechanism for the operator-visible signal below; a try/catch + // around the handler call cannot observe them. + const mcpHandler = createMcpHandler(createMcpServer, { + legacy: 'reject', + onerror: (error) => { + if (error instanceof UnsupportedProtocolVersionError) { + logger.warn({ event: 'legacy_client_rejected', error: errorMessage(error) }, 'MCP handler dispatch failed') + } else { + logger.warn({ error: errorMessage(error) }, 'MCP handler dispatch failed') + } + } + }) + const nodeMcpHandler = toNodeHandler(mcpHandler, { + onerror: (error) => { + logger.error({ error: errorMessage(error) }, 'MCP node adapter error before response written') + } + }) const server = createServer(async (req, res) => { try { @@ -152,19 +182,19 @@ async function handleAuthenticatedMcpRequest( const authReq = req as AuthenticatedIncomingMessage authReq.auth = { token: extracted.token, - clientId: 'harbor-client', - scopes: [] + clientId: UNSCOPED_CLIENT_ID, + scopes: [] as string[] /* not yet derived from auth flow */ } - // Normalized MCP request identity from HTTP headers (spec §14). Advisory: - // used for routing/observability only — the SDK validates these headers and - // reconciles them with the JSON-RPC body; auth stays keyed to the token. - const mcpIdentity = readMcpRequestIdentity(req.headers) - - try { - await nodeMcpHandler(authReq, res) - } catch (err) { - logger.warn({ error: errorMessage(err), ...mcpIdentity }, 'MCP handler dispatch failed') - throw err - } + // Normalized MCP request identity from HTTP headers (spec §14) — advisory: + // routing and observability only, never auth (the SDK validates/reconciles + // these headers against the JSON-RPC body itself). + logger.debug({ ...readMcpRequestIdentity(req.headers) }, 'Dispatching MCP request') + + // `nodeMcpHandler` (built from `createMcpHandler` + `toNodeHandler`) catches + // every internal failure itself and always writes a response — it does not + // throw. Dispatch failures, including a legacy-protocol client rejection, + // are observed via the `onerror` hooks passed to those two factories above, + // not via a try/catch here. + await nodeMcpHandler(authReq, res) } diff --git a/runtime/http/mcp-server-factory.ts b/runtime/http/mcp-server-factory.ts index 64e33ad..69e8b77 100644 --- a/runtime/http/mcp-server-factory.ts +++ b/runtime/http/mcp-server-factory.ts @@ -11,7 +11,8 @@ import { registerDiscoverSkillsTool } from '../../tools/discover-skills.tool.js' import { registerGetSkillDetailsTool } from '../../tools/get-skill-details.tool.js' import { registerSearchCodeTool } from '../../tools/search-code.tool.js' import { registerExecuteApiTool } from '../../tools/execute-api.tool.js' -import { GATEWAY_NAME, GATEWAY_VERSION } from '../../core/constants.js' +import { GATEWAY_NAME, GATEWAY_VERSION, TOOL } from '../../core/constants.js' +import { errorMessage } from '../../core/utils/errors.js' /** Options accepted by the `McpServer` constructor's second argument. */ type McpServerOptions = NonNullable[1]> @@ -49,8 +50,13 @@ export function buildMcpServerOptions(): McpServerOptions { } } -/** Factory signature shared by HTTP (`createMcpHandler`) and stdio (`serveStdio`). */ -export type McpServerFactory = (ctx: McpRequestContext) => McpServer +/** + * Factory signature shared by HTTP (`createMcpHandler`) and stdio + * (`serveStdio`). Named distinctly from the SDK's own exported + * `McpServerFactory` type (narrower here — synchronous, no `Promise` return) + * to avoid ambiguity between the two similarly-named types. + */ +export type GatewayMcpServerFactory = (ctx: McpRequestContext) => McpServer export interface BuildMcpServerFactoryOptions { registry: ServiceRegistry @@ -65,17 +71,33 @@ export interface BuildMcpServerFactoryOptions { * Builds a per-request MCP server factory. HTTP mode reads the validated bearer * from `ctx.authInfo`; stdio mode falls back to the pre-configured token. */ -export function buildMcpServerFactory(opts: BuildMcpServerFactoryOptions): McpServerFactory { +export function buildMcpServerFactory(opts: BuildMcpServerFactoryOptions): GatewayMcpServerFactory { const { registry, globalConfig, logger, metrics, stdioToken = '' } = opts return (ctx: McpRequestContext) => { const clientToken = ctx.authInfo?.token ?? stdioToken const mcpServer = new McpServer({ name: GATEWAY_NAME, version: GATEWAY_VERSION }, buildMcpServerOptions()) - registerDiscoverServicesTool(mcpServer, registry, logger, metrics) - registerDiscoverSkillsTool(mcpServer, registry, logger, metrics, clientToken) - registerGetSkillDetailsTool(mcpServer, registry, logger, metrics, clientToken) - registerSearchCodeTool(mcpServer, registry, logger, metrics, clientToken) - registerExecuteApiTool(mcpServer, registry, globalConfig, logger, metrics, clientToken) + + // Each tool is registered in its own try/catch: a construction-time throw + // from one tool (e.g. a schema-construction error) must not abort + // registration of the other four — it degrades to "N of 5 tools + // available" for this request/connection instead of zero. + const registrations: Array<[string, () => void]> = [ + [TOOL.DISCOVER_SERVICES, () => registerDiscoverServicesTool(mcpServer, registry, logger, metrics)], + [TOOL.DISCOVER_SKILLS, () => registerDiscoverSkillsTool(mcpServer, registry, logger, metrics, clientToken)], + [TOOL.GET_SKILL_DETAILS, () => registerGetSkillDetailsTool(mcpServer, registry, logger, metrics, clientToken)], + [TOOL.SEARCH_CODE, () => registerSearchCodeTool(mcpServer, registry, logger, metrics, clientToken)], + [TOOL.API_EXECUTE, () => registerExecuteApiTool(mcpServer, registry, globalConfig, logger, metrics, clientToken)] + ] + + for (const [toolName, register] of registrations) { + try { + register() + } catch (err) { + logger.error({ tool: toolName, error: errorMessage(err) }, 'Tool registration failed — continuing with remaining tools') + } + } + return mcpServer } } diff --git a/runtime/transport/stdio-gateway.ts b/runtime/transport/stdio-gateway.ts index 64b37b9..b845ef7 100644 --- a/runtime/transport/stdio-gateway.ts +++ b/runtime/transport/stdio-gateway.ts @@ -4,10 +4,11 @@ import { serveStdio } from '@modelcontextprotocol/server/stdio' import type { Logger } from '../observability/logger.js' import type { ServiceRegistry } from '../registry/service-registry.js' -import type { McpServerFactory } from '../http/mcp-server-factory.js' +import type { GatewayMcpServerFactory } from '../http/mcp-server-factory.js' +import { errorMessage } from '../../core/utils/errors.js' export interface StdioGatewayOptions { - createMcpServer: McpServerFactory + createMcpServer: GatewayMcpServerFactory registry: ServiceRegistry logger: Logger } @@ -20,6 +21,9 @@ export interface StdioGatewayOptions { */ export async function startStdioGateway(opts: StdioGatewayOptions): Promise { const { createMcpServer, registry, logger } = opts - serveStdio(createMcpServer, { legacy: 'reject' }) + serveStdio(createMcpServer, { + legacy: 'reject', + onerror: (error: Error) => logger.error({ error: errorMessage(error) }, 'stdio MCP connection error') + }) logger.info({ services: registry.serviceNames() }, 'Harbor ready (stdio, MCP 2026-07-28)') } diff --git a/tests/demo_e2e.py b/tests/demo_e2e.py index 542ca6c..cc7d173 100644 --- a/tests/demo_e2e.py +++ b/tests/demo_e2e.py @@ -928,8 +928,8 @@ def test_docker_oauth(resource_uri: str): assert_true("invoices" not in bad_parsed, "wrong-aud JWT → NO invoice data leaked") code = bad_parsed.get("code", "") - assert_true(code in ("TOKEN_INVALID", "AUTH_FAILED", "TOKEN_EXPIRED"), - f"wrong-aud rejection carries an auth error code (got {code!r})") + assert_eq(code, "TOKEN_INVALID", + "wrong-aud rejection carries the deterministic TOKEN_INVALID code") # ── Main ────────────────────────────────────────────────────────────────────── diff --git a/tests/unit/http-gateway.test.ts b/tests/unit/http-gateway.test.ts index 2608e27..1a00eb8 100644 --- a/tests/unit/http-gateway.test.ts +++ b/tests/unit/http-gateway.test.ts @@ -6,16 +6,26 @@ import type { AddressInfo } from 'node:net' import type { AuthInfo } from '@modelcontextprotocol/server' import { ERR, MCP_PROTOCOL_VERSION } from '../../core/constants.js' -const { mockNodeMcpHandler } = vi.hoisted(() => ({ - mockNodeMcpHandler: vi.fn() -})) +const { mockNodeMcpHandler, mockCreateMcpHandler, mockToNodeHandler } = vi.hoisted(() => { + const nodeHandler = vi.fn() + return { + mockNodeMcpHandler: nodeHandler, + mockCreateMcpHandler: vi.fn(() => ({ fetch: vi.fn() })), + mockToNodeHandler: vi.fn(() => nodeHandler) + } +}) -vi.mock('@modelcontextprotocol/server', () => ({ - createMcpHandler: vi.fn(() => ({ fetch: vi.fn() })) -})) +vi.mock('@modelcontextprotocol/server', async (importOriginal) => { + const actual = await importOriginal() + return { + ...actual, + createMcpHandler: mockCreateMcpHandler, + UnsupportedProtocolVersionError: class UnsupportedProtocolVersionError extends Error {} + } +}) vi.mock('@modelcontextprotocol/node', () => ({ - toNodeHandler: vi.fn(() => mockNodeMcpHandler) + toNodeHandler: mockToNodeHandler })) import { startHttpGateway, type HttpGatewayHandle } from '../../runtime/http/http-gateway.js' @@ -69,12 +79,23 @@ describe('startHttpGateway', () => { afterEach(async () => { mockNodeMcpHandler.mockReset() + mockCreateMcpHandler.mockClear() + mockToNodeHandler.mockClear() if (cleanup) { await cleanup() cleanup = null } }) + it('constructs the MCP handler with { legacy: "reject" } — the PR\'s headline breaking change (C-1)', async () => { + const { close } = await startForTest() + cleanup = close + + expect(mockCreateMcpHandler).toHaveBeenCalledTimes(1) + const [, options] = mockCreateMcpHandler.mock.calls[0] as [unknown, { legacy?: string }] + expect(options).toMatchObject({ legacy: 'reject' }) + }) + it('GET /health returns 200 with service registry snapshot', async () => { const registry = new ServiceRegistry() const { baseUrl, close } = await startForTest({ registry }) @@ -183,4 +204,47 @@ describe('startHttpGateway', () => { // production; here we only assert auth passthrough on the Node request. expect(factoryCalled).toBe(false) }) + + it('wires onerror into createMcpHandler and logs a distinguishing event for legacy client rejection (H-11)', async () => { + // `createMcpHandler`/`toNodeHandler` catch every internal failure + // themselves and never throw back to the caller (confirmed against the + // installed SDK source) — so the only way to observe a legacy-rejected + // request is the `onerror` hook passed at construction time. This test + // invokes that real callback directly rather than mocking a throw the + // SDK never actually produces. + const warnSpy = vi.fn() + const logger = { ...makeLogger(), warn: warnSpy } as unknown as Logger + const { close } = await startForTest({ logger }) + cleanup = close + + expect(mockCreateMcpHandler).toHaveBeenCalledTimes(1) + const [, options] = mockCreateMcpHandler.mock.calls[0] as [unknown, { onerror?: (error: Error) => void }] + expect(options.onerror).toBeInstanceOf(Function) + + const { UnsupportedProtocolVersionError } = await import('@modelcontextprotocol/server') + options.onerror?.(new UnsupportedProtocolVersionError({} as never)) + + expect(warnSpy).toHaveBeenCalledWith( + expect.objectContaining({ event: 'legacy_client_rejected' }), + 'MCP handler dispatch failed' + ) + }) + + it('wires onerror into toNodeHandler for adapter-level errors (request conversion / fetch throw)', async () => { + const errorSpy = vi.fn() + const logger = { ...makeLogger(), error: errorSpy } as unknown as Logger + const { close } = await startForTest({ logger }) + cleanup = close + + expect(mockToNodeHandler).toHaveBeenCalledTimes(1) + const [, options] = mockToNodeHandler.mock.calls[0] as [unknown, { onerror?: (error: Error) => void }] + expect(options.onerror).toBeInstanceOf(Function) + + options.onerror?.(new Error('adapter boom')) + + expect(errorSpy).toHaveBeenCalledWith( + expect.objectContaining({ error: expect.stringContaining('adapter boom') }), + 'MCP node adapter error before response written' + ) + }) }) diff --git a/tests/unit/jwt-validation.test.ts b/tests/unit/jwt-validation.test.ts index 4eaa38f..c00cade 100644 --- a/tests/unit/jwt-validation.test.ts +++ b/tests/unit/jwt-validation.test.ts @@ -82,10 +82,28 @@ describe('JwtValidationStrategy', () => { }) it('jwtValidation() factory returns a JwtValidationStrategy', () => { - const s = jwtValidation({ jwksUri: jwksUrl, issuer: ISSUER }) + const s = jwtValidation({ jwksUri: jwksUrl, issuer: ISSUER, audience: AUDIENCE }) expect(s).toBeInstanceOf(JwtValidationStrategy) }) + describe('resource binding (spec §17, RFC 8707)', () => { + it('constructor fails closed when audience/resource binding is absent', () => { + expect(() => + new JwtValidationStrategy({ jwksUri: jwksUrl, issuer: ISSUER } as never) + ).toThrow(/audience/) + }) + + it('constructor fails closed when audience is blank', () => { + expect(() => + new JwtValidationStrategy({ jwksUri: jwksUrl, issuer: ISSUER, audience: ' ' }) + ).toThrow(/resource binding/) + }) + + it('jwtValidation() factory also fails closed without audience', () => { + expect(() => jwtValidation({ jwksUri: jwksUrl, issuer: ISSUER } as never)).toThrow(/audience/) + }) + }) + describe('validate — happy path', () => { it('valid RS256 JWT returns correct TokenPayload shape', async () => { const token = await sign({ scope: 'api:read' }) @@ -153,12 +171,6 @@ describe('JwtValidationStrategy', () => { expect(payload.metadata).toBeUndefined() }) - it('strategy without audience accepts tokens regardless of aud claim', async () => { - const s = new JwtValidationStrategy({ jwksUri: jwksUrl, issuer: ISSUER }) - const token = await sign({}, { audience: 'any-audience' }) - const payload = await s.validate(token) - expect(payload.token_type).toBe('bearer') - }) }) describe('validate — error mapping', () => { @@ -181,6 +193,13 @@ describe('JwtValidationStrategy', () => { await expect(strategy.validate(token)).rejects.toBeInstanceOf(TokenInvalidError) }) + it('wrong audience → client-facing message does not echo the failing claim value', async () => { + const token = await sign({}, { audience: 'https://other-resource.example.com' }) + await expect(strategy.validate(token)).rejects.toMatchObject({ + message: expect.not.stringContaining('other-resource'), + }) + }) + it('token signed with unknown key → TokenInvalidError', async () => { const now = Math.floor(Date.now() / 1000) const token = await new SignJWT({}) @@ -205,6 +224,7 @@ describe('JwtValidationStrategy', () => { const s = new JwtValidationStrategy({ jwksUri: 'http://127.0.0.1:1/.well-known/jwks.json', issuer: ISSUER, + audience: AUDIENCE, }) const token = await sign({}) await expect(s.validate(token)).rejects.toBeInstanceOf(TokenIntrospectionError) diff --git a/tests/unit/mcp-server-factory.test.ts b/tests/unit/mcp-server-factory.test.ts index 756f889..ca32d88 100644 --- a/tests/unit/mcp-server-factory.test.ts +++ b/tests/unit/mcp-server-factory.test.ts @@ -1,8 +1,51 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. -import { describe, it, expect } from 'vitest' -import { buildMcpServerOptions } from '../../runtime/http/mcp-server-factory.js' +import { describe, it, expect, vi, beforeEach } from 'vitest' +import type { McpRequestContext } from '@modelcontextprotocol/server' +import type { GlobalConfig } from '../../core/types/config.types.js' +import type { Logger } from '../../runtime/observability/logger.js' + +const { + registerDiscoverServicesToolMock, + registerDiscoverSkillsToolMock, + registerGetSkillDetailsToolMock, + registerSearchCodeToolMock, + registerExecuteApiToolMock +} = vi.hoisted(() => ({ + registerDiscoverServicesToolMock: vi.fn(), + registerDiscoverSkillsToolMock: vi.fn(), + registerGetSkillDetailsToolMock: vi.fn(), + registerSearchCodeToolMock: vi.fn(), + registerExecuteApiToolMock: vi.fn() +})) + +vi.mock('../../tools/discover-services.tool.js', () => ({ + registerDiscoverServicesTool: registerDiscoverServicesToolMock +})) +vi.mock('../../tools/discover-skills.tool.js', () => ({ + registerDiscoverSkillsTool: registerDiscoverSkillsToolMock +})) +vi.mock('../../tools/get-skill-details.tool.js', () => ({ + registerGetSkillDetailsTool: registerGetSkillDetailsToolMock +})) +vi.mock('../../tools/search-code.tool.js', () => ({ + registerSearchCodeTool: registerSearchCodeToolMock +})) +vi.mock('../../tools/execute-api.tool.js', () => ({ + registerExecuteApiTool: registerExecuteApiToolMock +})) + +import { buildMcpServerOptions, buildMcpServerFactory } from '../../runtime/http/mcp-server-factory.js' +import { ServiceRegistry } from '../../runtime/registry/service-registry.js' + +function makeLogger(): Logger { + const noop = () => {} + return { + info: noop, warn: noop, error: noop, debug: noop, trace: noop, fatal: noop, + child: () => makeLogger() + } as unknown as Logger +} describe('buildMcpServerOptions (spec §15/§16)', () => { const opts = buildMcpServerOptions() @@ -33,3 +76,84 @@ describe('buildMcpServerOptions (spec §15/§16)', () => { } }) }) + +/** + * Exercises the real per-request auth-token wiring `buildMcpServerFactory` + * introduces to replace the v1 `createMcpServer(clientToken)` signature: + * `ctx.authInfo?.token ?? stdioToken`. Each `register*Tool` call is mocked so + * we can assert exactly which token value reached it, for both an + * HTTP-shaped context (`authInfo.token` present) and a stdio-shaped context + * (`authInfo` absent, falling back to `stdioToken`). + */ +describe('buildMcpServerFactory', () => { + const globalConfig = {} as GlobalConfig + const metrics = { increment: vi.fn() } + + beforeEach(() => { + registerDiscoverServicesToolMock.mockReset() + registerDiscoverSkillsToolMock.mockReset() + registerGetSkillDetailsToolMock.mockReset() + registerSearchCodeToolMock.mockReset() + registerExecuteApiToolMock.mockReset() + }) + + it('wires ctx.authInfo.token to every clientToken-consuming tool for an HTTP-shaped context', () => { + const factory = buildMcpServerFactory({ + registry: new ServiceRegistry(), + globalConfig, + logger: makeLogger(), + metrics, + stdioToken: 'stdio-fallback-should-not-be-used' + }) + + const httpCtx: McpRequestContext = { era: 'modern', authInfo: { token: 'http-token' } } + factory(httpCtx) + + expect(registerDiscoverServicesToolMock).toHaveBeenCalledTimes(1) + expect(registerDiscoverSkillsToolMock.mock.calls[0]?.[4]).toBe('http-token') + expect(registerGetSkillDetailsToolMock.mock.calls[0]?.[4]).toBe('http-token') + expect(registerSearchCodeToolMock.mock.calls[0]?.[4]).toBe('http-token') + expect(registerExecuteApiToolMock.mock.calls[0]?.[5]).toBe('http-token') + }) + + it('falls back to stdioToken for a stdio-shaped context (authInfo absent)', () => { + const factory = buildMcpServerFactory({ + registry: new ServiceRegistry(), + globalConfig, + logger: makeLogger(), + metrics, + stdioToken: 'stdio-fallback-token' + }) + + const stdioCtx: McpRequestContext = { era: 'modern' } + factory(stdioCtx) + + expect(registerDiscoverSkillsToolMock.mock.calls[0]?.[4]).toBe('stdio-fallback-token') + expect(registerGetSkillDetailsToolMock.mock.calls[0]?.[4]).toBe('stdio-fallback-token') + expect(registerSearchCodeToolMock.mock.calls[0]?.[4]).toBe('stdio-fallback-token') + expect(registerExecuteApiToolMock.mock.calls[0]?.[5]).toBe('stdio-fallback-token') + }) + + it('isolates a single tool registration failure — the other 4 still register (H-9)', () => { + registerSearchCodeToolMock.mockImplementationOnce(() => { + throw new Error('boom: search_code registration failed') + }) + const logger = makeLogger() + const errorSpy = vi.spyOn(logger, 'error') + + const factory = buildMcpServerFactory({ + registry: new ServiceRegistry(), + globalConfig, + logger, + metrics, + stdioToken: 'tok' + }) + + expect(() => factory({ era: 'modern' })).not.toThrow() + expect(registerDiscoverServicesToolMock).toHaveBeenCalledTimes(1) + expect(registerDiscoverSkillsToolMock).toHaveBeenCalledTimes(1) + expect(registerGetSkillDetailsToolMock).toHaveBeenCalledTimes(1) + expect(registerExecuteApiToolMock).toHaveBeenCalledTimes(1) + expect(errorSpy).toHaveBeenCalled() + }) +}) diff --git a/tests/unit/resource-binding.test.ts b/tests/unit/resource-binding.test.ts new file mode 100644 index 0000000..bc83756 --- /dev/null +++ b/tests/unit/resource-binding.test.ts @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import { describe, it, expect } from 'vitest' +import { requireResourceBindingAudience } from '../../adapters/auth/strategies/resource-binding.js' + +describe('requireResourceBindingAudience (spec §17, RFC 8707)', () => { + it('throws the given message when audience is undefined', () => { + expect(() => requireResourceBindingAudience(undefined, 'boom')).toThrow('boom') + }) + + it('throws the given message when audience is an empty string', () => { + expect(() => requireResourceBindingAudience('', 'boom')).toThrow('boom') + }) + + it('throws the given message when audience is whitespace-only', () => { + expect(() => requireResourceBindingAudience(' ', 'boom')).toThrow('boom') + }) + + it('does not throw when audience is a non-blank string', () => { + expect(() => requireResourceBindingAudience('https://harbor.example.com', 'boom')).not.toThrow() + }) +}) diff --git a/tests/unit/stdio-gateway.test.ts b/tests/unit/stdio-gateway.test.ts new file mode 100644 index 0000000..8b5f69d --- /dev/null +++ b/tests/unit/stdio-gateway.test.ts @@ -0,0 +1,65 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. + +import { describe, it, expect, vi, beforeEach } from 'vitest' +import type { Logger } from '../../runtime/observability/logger.js' + +const { mockServeStdio } = vi.hoisted(() => ({ + mockServeStdio: vi.fn() +})) + +vi.mock('@modelcontextprotocol/server/stdio', () => ({ + serveStdio: mockServeStdio +})) + +import { startStdioGateway } from '../../runtime/transport/stdio-gateway.js' +import { ServiceRegistry } from '../../runtime/registry/service-registry.js' +import type { GatewayMcpServerFactory } from '../../runtime/http/mcp-server-factory.js' + +function makeLogger(): Logger { + const noop = () => {} + return { + info: noop, warn: noop, error: noop, debug: noop, trace: noop, fatal: noop, + child: () => makeLogger() + } as unknown as Logger +} + +const noopFactory: GatewayMcpServerFactory = () => ({} as never) + +describe('startStdioGateway', () => { + beforeEach(() => { + mockServeStdio.mockReset() + }) + + it('constructs serveStdio with { legacy: "reject" } — the PR\'s headline breaking change (C-1)', async () => { + await startStdioGateway({ + createMcpServer: noopFactory, + registry: new ServiceRegistry(), + logger: makeLogger() + }) + + expect(mockServeStdio).toHaveBeenCalledTimes(1) + const [factory, options] = mockServeStdio.mock.calls[0] as [unknown, { legacy?: string; onerror?: (error: Error) => void }] + expect(factory).toBe(noopFactory) + expect(options).toMatchObject({ legacy: 'reject' }) + }) + + it('wires an onerror callback that logs via the errorMessage helper (H-2)', async () => { + const errorSpy = vi.fn() + const logger = { ...makeLogger(), error: errorSpy } as unknown as Logger + + await startStdioGateway({ + createMcpServer: noopFactory, + registry: new ServiceRegistry(), + logger + }) + + const [, options] = mockServeStdio.mock.calls[0] as [unknown, { onerror?: (error: Error) => void }] + expect(options.onerror).toBeTypeOf('function') + + const boom = new Error('stdio transport write failure') + options.onerror?.(boom) + + expect(errorSpy).toHaveBeenCalledWith({ error: 'stdio transport write failure' }, 'stdio MCP connection error') + }) +}) diff --git a/tests/unit/token-validator.test.ts b/tests/unit/token-validator.test.ts index e8c7d1b..0d201b9 100644 --- a/tests/unit/token-validator.test.ts +++ b/tests/unit/token-validator.test.ts @@ -97,4 +97,59 @@ describe('OAuthIntrospectionStrategy', () => { const allLogCalls = logSpy.mock.calls.flat().join(' ') expect(allLogCalls).not.toContain('super-secret-raw-token-value') }) + + describe('resource binding (spec §17, RFC 8707) — best-effort, RFC 7662 `aud` is optional', () => { + it('no audience configured → aud claim in response is ignored', async () => { + vi.mocked(axios.post).mockResolvedValueOnce({ + status: 200, + data: { access_token: 'abc', expires_in: 3600, aud: 'https://not-harbor.example.com' } + }) + + const result = await strategy.validate('token') + expect(result.access_token).toBe('abc') + }) + + it('audience configured, response has no aud claim → validation skipped (accepted)', async () => { + const s = new OAuthIntrospectionStrategy({ ...config, audience: 'https://harbor.example.com' }) + vi.mocked(axios.post).mockResolvedValueOnce({ + status: 200, + data: { access_token: 'abc', expires_in: 3600 } + }) + + const result = await s.validate('token') + expect(result.access_token).toBe('abc') + }) + + it('audience configured, response aud matches (string) → accepted', async () => { + const s = new OAuthIntrospectionStrategy({ ...config, audience: 'https://harbor.example.com' }) + vi.mocked(axios.post).mockResolvedValueOnce({ + status: 200, + data: { access_token: 'abc', expires_in: 3600, aud: 'https://harbor.example.com' } + }) + + const result = await s.validate('token') + expect(result.access_token).toBe('abc') + }) + + it('audience configured, response aud matches (array) → accepted', async () => { + const s = new OAuthIntrospectionStrategy({ ...config, audience: 'https://harbor.example.com' }) + vi.mocked(axios.post).mockResolvedValueOnce({ + status: 200, + data: { access_token: 'abc', expires_in: 3600, aud: ['https://other.example.com', 'https://harbor.example.com'] } + }) + + const result = await s.validate('token') + expect(result.access_token).toBe('abc') + }) + + it('audience configured, response aud mismatches → TokenInvalidError (rejected)', async () => { + const s = new OAuthIntrospectionStrategy({ ...config, audience: 'https://harbor.example.com' }) + vi.mocked(axios.post).mockResolvedValueOnce({ + status: 200, + data: { access_token: 'abc', expires_in: 3600, aud: 'https://not-harbor.example.com' } + }) + + await expect(s.validate('token')).rejects.toThrow(TokenInvalidError) + }) + }) }) diff --git a/tools/discover-skills.tool.ts b/tools/discover-skills.tool.ts index d3a7714..4b9da3d 100644 --- a/tools/discover-skills.tool.ts +++ b/tools/discover-skills.tool.ts @@ -2,7 +2,6 @@ // Copyright 2026 Contributors to the Harbor project. import { McpServer } from '@modelcontextprotocol/server' -import { z } from 'zod' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' import type { MetricsCollector } from '../core/types/metrics.types.js' @@ -11,7 +10,8 @@ import { extractCorrelationId, resolveService, isToolError, - runSandboxTool + runSandboxTool, + serviceCodeSchema } from './tool-helpers.js' import { TOOL, LOG_PREFIX } from '../core/constants.js' @@ -71,7 +71,7 @@ After finding the relevant skill, use get_skill_details() to read the full SOP.` server.registerTool( TOOL.DISCOVER_SKILLS, - { description: DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, + { description: DESCRIPTION, inputSchema: serviceCodeSchema }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) diff --git a/tools/execute-api.tool.ts b/tools/execute-api.tool.ts index 040e649..4c3b9f4 100644 --- a/tools/execute-api.tool.ts +++ b/tools/execute-api.tool.ts @@ -2,7 +2,6 @@ // Copyright 2026 Contributors to the Harbor project. import { McpServer } from '@modelcontextprotocol/server' -import { z } from 'zod' import { v4 as uuidv4 } from 'uuid' import { createHash } from 'node:crypto' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' @@ -19,7 +18,9 @@ import { mcpError, mcpSuccess, extractCorrelationId, extractSessionId, resolveService, isToolError, - validateAuth + validateAuth, + readRequestMeta, + serviceCodeSchema } from './tool-helpers.js' import { TOOL, LOG_PREFIX, METRIC, OUTCOME } from '../core/constants.js' import type { AuditOutcome } from '../core/constants.js' @@ -122,13 +123,16 @@ async () => { server.registerTool( TOOL.API_EXECUTE, - { description: EXECUTE_DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, + { description: EXECUTE_DESCRIPTION, inputSchema: serviceCodeSchema }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) const sessionId = extractSessionId(ctx) + // Advisory-only (never auth) request metadata, logged here as its first + // real production consumer — see AdvisoryRequestMeta's invariant note. + const requestMeta = readRequestMeta(ctx) logger.info( - { correlationId, tool: TOOL.API_EXECUTE, service }, + { correlationId, tool: TOOL.API_EXECUTE, service, ...requestMeta }, `${LOG_PREFIX.MCP_IN} ${TOOL.API_EXECUTE} — request received from AI client` ) diff --git a/tools/search-code.tool.ts b/tools/search-code.tool.ts index 7dd35df..7af3064 100644 --- a/tools/search-code.tool.ts +++ b/tools/search-code.tool.ts @@ -2,7 +2,6 @@ // Copyright 2026 Contributors to the Harbor project. import { McpServer } from '@modelcontextprotocol/server' -import { z } from 'zod' import type { ServiceRegistry } from '../runtime/registry/service-registry.js' import type { Logger } from '../runtime/observability/logger.js' import type { MetricsCollector } from '../core/types/metrics.types.js' @@ -11,7 +10,8 @@ import { extractCorrelationId, resolveService, isToolError, - runSandboxTool + runSandboxTool, + serviceCodeSchema } from './tool-helpers.js' import { TOOL, LOG_PREFIX } from '../core/constants.js' @@ -90,7 +90,7 @@ This keeps each search result small and readable.` server.registerTool( TOOL.SEARCH_CODE, - { description: SEARCH_CODE_DESCRIPTION, inputSchema: z.object({ service: z.string(), code: z.string() }) }, + { description: SEARCH_CODE_DESCRIPTION, inputSchema: serviceCodeSchema }, async ({ service, code }, ctx) => { const correlationId = extractCorrelationId(ctx) diff --git a/tools/tool-helpers.ts b/tools/tool-helpers.ts index a4acba5..87f238c 100644 --- a/tools/tool-helpers.ts +++ b/tools/tool-helpers.ts @@ -1,6 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Contributors to the Harbor project. +import { z } from 'zod' import type { TokenPayload, AuthResult } from '../core/types/auth.types.js' import { SessionExpiredError } from '../core/types/auth.types.js' import type { ServiceRegistry, ServiceResources } from '../runtime/registry/service-registry.js' @@ -21,7 +22,7 @@ import { } from '../core/constants.js' import { ensureError, errorCode, errorRetryable } from '../core/utils/errors.js' -/** Server identity emitted in every response `_meta` (spec §10, MANDATORY). */ +/** Server identity emitted in every response `_meta` (spec §10, recommended). */ const SERVER_INFO = Object.freeze({ name: GATEWAY_NAME, version: GATEWAY_VERSION }) /** @@ -60,7 +61,7 @@ import type { ServerContext } from '@modelcontextprotocol/server' * Reserved keys (`error`, `code`, `retryable`) cannot be overridden by `extra`. * * `appMeta` is carried on the response `_meta` channel (spec §11), alongside - * mandatory serverInfo — never mixed into the model-visible error `content`. + * serverInfo — never mixed into the model-visible error `content`. */ export function mcpError( message: string, @@ -91,51 +92,57 @@ export function mcpSuccess(data: unknown, appMeta?: AppMeta): ToolResponse { } /** Reads correlation id from the MCP handler context, falling back to a fresh UUID. */ -export function extractCorrelationId(ctx: unknown): string { - const serverCtx = ctx as ServerContext | undefined - const id = serverCtx?.mcpReq?.id +export function extractCorrelationId(ctx: ServerContext | undefined): string { + const id = ctx?.mcpReq?.id if (id !== undefined && id !== null) return String(id) return crypto.randomUUID() } /** Reads session id from the MCP handler context, falling back to a fresh UUID. */ -export function extractSessionId(ctx: unknown): string { - return (ctx as ServerContext | undefined)?.sessionId ?? crypto.randomUUID() +export function extractSessionId(ctx: ServerContext | undefined): string { + return ctx?.sessionId ?? crypto.randomUUID() } /** - * Advisory view of per-request MCP metadata (spec §9): the negotiated protocol - * version, client implementation info, and client capabilities. The SDK lifts - * the reserved `io.modelcontextprotocol/*` envelope keys out of the params - * `_meta` the handler sees and onto `ctx.mcpReq.envelope`; this reads both, - * envelope-first. + * Advisory-only view of per-request MCP metadata (spec §9): the negotiated + * protocol version, client implementation info, and client capabilities. The + * SDK lifts the reserved `io.modelcontextprotocol/*` envelope keys out of the + * params `_meta` the handler sees and onto `ctx.mcpReq.envelope`; this reads + * both, envelope-first. * - * SECURITY: this is untrusted, client-supplied context for logging/telemetry - * and content shaping ONLY. Never use it for authorization or any security - * decision — auth flows exclusively through the validated bearer token. + * Untrusted, client-supplied — for logging/telemetry only. MUST NOT be used + * for authentication or authorization; auth flows through the validated + * bearer token (see {@link validateAuth}). */ -export interface RequestMetaView { +export interface AdvisoryRequestMeta { protocolVersion?: string clientInfo?: { name?: string; version?: string } & Record clientCapabilities?: Record } -export function readRequestMeta(ctx: unknown): RequestMetaView { - const mcpReq = (ctx as ServerContext | undefined)?.mcpReq +export function readRequestMeta(ctx: ServerContext | undefined): AdvisoryRequestMeta { + const mcpReq = ctx?.mcpReq const src: Record = { ...((mcpReq?._meta as Record | undefined) ?? {}), ...((mcpReq?.envelope as Record | undefined) ?? {}) } - const view: RequestMetaView = {} + const view: AdvisoryRequestMeta = {} const pv = src[PROTOCOL_VERSION_META_KEY] if (typeof pv === 'string') view.protocolVersion = pv const ci = src[CLIENT_INFO_META_KEY] - if (ci !== null && typeof ci === 'object') view.clientInfo = ci as RequestMetaView['clientInfo'] + if (ci !== null && typeof ci === 'object') view.clientInfo = ci as AdvisoryRequestMeta['clientInfo'] const cc = src[CLIENT_CAPABILITIES_META_KEY] if (cc !== null && typeof cc === 'object') view.clientCapabilities = cc as Record return view } +/** + * Shared `{ service, code }` input schema for the sandboxed-code tools + * (`discover_skills`, `search_code`, `api_execute`). Kept in one place so the + * contract only needs to change in a single spot. + */ +export const serviceCodeSchema = z.object({ service: z.string(), code: z.string() }) + export function resolveService( registry: ServiceRegistry, service: string, diff --git a/wiring/service-wiring.ts b/wiring/service-wiring.ts index e711568..b841da7 100644 --- a/wiring/service-wiring.ts +++ b/wiring/service-wiring.ts @@ -10,6 +10,7 @@ import { staticToken } from '../adapters/auth/strategies/static-token.strategy.j import { oauthIntrospection } from '../adapters/auth/strategies/oauth-introspection.strategy.js' import { jwtValidation } from '../adapters/auth/strategies/jwt-validation.strategy.js' import { oauthDiscovery } from '../adapters/auth/strategies/oauth-discovery.strategy.js' +import { requireResourceBindingAudience } from '../adapters/auth/strategies/resource-binding.js' import { noopCircuitBreaker } from '../spi/resilience/strategies/noop-circuit-breaker.strategy.js' import { countBasedCircuitBreaker } from '../adapters/resilience/strategies/count-based-circuit-breaker.strategy.js' @@ -38,21 +39,27 @@ export function resolveAuth(auth: ServiceAuthConfig | undefined, logger?: Logger tokenRefreshBufferSec: auth.tokenRefreshBufferSec, responseMapping: auth.responseMapping, metadataMapping: auth.metadataMapping, + ...(auth.audience !== undefined ? { audience: auth.audience } : {}), }) case AUTH_TYPE.JWT_VALIDATION: + requireResourceBindingAudience( + auth.audience, + 'config.auth.audience (resource binding) is required for jwt-validation auth' + ) return jwtValidation({ jwksUri: auth.jwksUri, issuer: auth.issuer, - ...(auth.audience !== undefined ? { audience: auth.audience } : {}), + audience: auth.audience, ...(auth.clockToleranceSec !== undefined ? { clockToleranceSec: auth.clockToleranceSec } : {}), ...(auth.scopeClaim !== undefined ? { scopeClaim: auth.scopeClaim } : {}), ...(auth.metadataMapping !== undefined ? { metadataMapping: auth.metadataMapping } : {}), ...(logger !== undefined ? { logger } : {}), }) case AUTH_TYPE.OAUTH_2_1: - if (!auth.audience || auth.audience.trim() === '') { - throw new Error('config.auth.audience (resource binding) is required for oauth-2.1 auth') - } + requireResourceBindingAudience( + auth.audience, + 'config.auth.audience (resource binding) is required for oauth-2.1 auth' + ) return oauthDiscovery({ authorizationServer: auth.authorizationServer, audience: auth.audience, From a3c60f033e4e5d4ae4d67081aa63250f5bd45118 Mon Sep 17 00:00:00 2001 From: vijay Date: Sun, 13 Sep 2026 20:09:40 +0530 Subject: [PATCH 22/25] added new tests for real auth --- examples/demo/mock-introspection-server.js | 74 + examples/demo/start-oauth-mode.sh | 102 ++ postman/Harbor.postman_collection.json | 1528 +++++++++++++++++ postman/README.md | 136 ++ services/billing-introspection/config.json | 39 + .../billing-introspection/skills/call-api.md | 20 + services/billing-introspection/spec.yaml | 70 + services/billing-jwt/config.json | 38 + services/billing-jwt/skills/call-api.md | 20 + services/billing-jwt/spec.yaml | 70 + tests/demo_e2e.py | 204 ++- 11 files changed, 2295 insertions(+), 6 deletions(-) create mode 100644 examples/demo/mock-introspection-server.js create mode 100755 examples/demo/start-oauth-mode.sh create mode 100644 postman/Harbor.postman_collection.json create mode 100644 postman/README.md create mode 100644 services/billing-introspection/config.json create mode 100644 services/billing-introspection/skills/call-api.md create mode 100644 services/billing-introspection/spec.yaml create mode 100644 services/billing-jwt/config.json create mode 100644 services/billing-jwt/skills/call-api.md create mode 100644 services/billing-jwt/spec.yaml diff --git a/examples/demo/mock-introspection-server.js b/examples/demo/mock-introspection-server.js new file mode 100644 index 0000000..18910e7 --- /dev/null +++ b/examples/demo/mock-introspection-server.js @@ -0,0 +1,74 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Contributors to the Harbor project. +// +// Minimal RFC 7662 token-introspection endpoint for the oauth-introspection E2E. +// Serves a small, fixed set of known test tokens on :3008 — this is a stub for +// a real authorization server's introspection endpoint, not a real one. Harbor +// calls this (GET/POST /introspect) before ever calling the billing backend; +// this server has no knowledge of the billing backend itself. +import http from 'http' + +// Fixed, non-secret test fixtures — known to demo_e2e.py and the Postman collection. +const TOKENS = { + 'introspection-valid-token-abc123': { + active: true, + expires_in: 3600, + aud: 'http://localhost:3333', + scope: 'api:read api:write', + sub: 'harbor-test-client' + }, + 'introspection-wrong-aud-token-xyz789': { + active: true, + expires_in: 3600, + aud: 'https://not-harbor.example.com', + scope: 'confused-deputy', + sub: 'harbor-test-client' + } + // Any token not listed above (e.g. 'introspection-revoked-token-00000000' — + // deliberately >=32 chars so Harbor's bearer-format pre-check lets it + // through to actually reach this server) is treated as revoked/unknown: + // RFC 7662 §2.2's `{ "active": false }` shape. +} + +function send(res, status, body) { + res.writeHead(status, { 'Content-Type': 'application/json' }) + res.end(JSON.stringify(body)) +} + +function introspect(token) { + return TOKENS[token] ?? { active: false } +} + +const server = http.createServer((req, res) => { + const url = new URL(req.url, `http://${req.headers.host}`) + if (url.pathname !== '/introspect') { + send(res, 404, { error: 'Not found' }) + return + } + + if (req.method === 'GET') { + send(res, 200, introspect(url.searchParams.get('token') ?? '')) + return + } + + if (req.method === 'POST') { + let body = '' + req.on('data', (chunk) => { body += chunk }) + req.on('end', () => { + const params = new URLSearchParams(body) + send(res, 200, introspect(params.get('token') ?? url.searchParams.get('token') ?? '')) + }) + return + } + + send(res, 405, { error: 'Method not allowed' }) +}) + +server.on('error', (err) => { + console.error(`[mock-introspection-server] server error: ${err.message}`) + process.exit(1) +}) + +const PORT = 3008 +server.listen(PORT, () => console.log(`[mock-introspection-server] running on http://localhost:${PORT}`)) diff --git a/examples/demo/start-oauth-mode.sh b/examples/demo/start-oauth-mode.sh new file mode 100755 index 0000000..9dc88e2 --- /dev/null +++ b/examples/demo/start-oauth-mode.sh @@ -0,0 +1,102 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Contributors to the Harbor project. +# +# Starts Harbor in OAuth mode: the Docker mock AS, the billing backend, the +# mock RFC 7662 introspection server, and Harbor itself wired up so all three +# non-static auth strategies (oauth-2.1, jwt-validation, oauth-introspection) +# are live and reachable — matching the setup tests/demo_e2e.py's Phase 2 +# automates, and what postman/Harbor.postman_collection.json's OAuth-mode +# folders expect. See postman/README.md for the full manual testing guide. +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$SCRIPT_DIR/../.." + +echo "=== Harbor OAuth mode: billing (oauth-2.1) + billing-jwt (jwt-validation) + billing-introspection (oauth-introspection) ===" +echo "" + +# Kill any leftover processes on the ports this mode uses +for PORT in 3004 3008 3333; do + PID=$(lsof -ti tcp:$PORT 2>/dev/null || true) + if [ -n "$PID" ]; then + echo "Killing existing process on port $PORT (pid $PID)" + kill "$PID" 2>/dev/null || true + fi +done + +echo "Switching service configs: billing/billing-jwt/billing-introspection=enabled, product/order/tasks=disabled ..." +python3 - "$ROOT" <<'PYEOF' +import json, sys +root = sys.argv[1] +for svc, enabled in [("billing", True), ("billing-jwt", True), ("billing-introspection", True), + ("product", False), ("order", False), ("tasks", False)]: + path = f"{root}/services/{svc}/config.json" + cfg = json.load(open(path)) + cfg["enabled"] = enabled + json.dump(cfg, open(path, "w"), indent=2, ensure_ascii=False) + open(path, "a").write("\n") +PYEOF + +echo "Starting Docker mock AS (navikt/mock-oauth2-server) on :8080 ..." +docker compose -f "$ROOT/examples/07-oauth/docker-compose.yml" up -d +for i in $(seq 1 30); do + if curl -sf "http://localhost:8080/default/.well-known/openid-configuration" >/dev/null 2>&1; then + break + fi + sleep 1 +done + +echo "Starting billing-service on :3004 ..." +node "$SCRIPT_DIR/billing-service.js" & +BILLING_PID=$! + +echo "Starting mock-introspection-server on :3008 ..." +node "$SCRIPT_DIR/mock-introspection-server.js" & +INTROSPECT_PID=$! + +sleep 0.5 + +echo "" +echo "Starting Harbor on :3333 (OAuth mode) ..." +cd "$ROOT" +nvm use 22 --silent 2>/dev/null || true +HARBOR_RESOURCE_URI="http://127.0.0.1:3333" \ +HARBOR_AUTH_SERVERS="http://localhost:8080/default" \ +HARBOR_SCOPES_SUPPORTED="api:read,api:write" \ +npm run dev & +MCP_PID=$! + +cleanup() { + echo "" + echo "Shutting down..." + kill "$BILLING_PID" "$INTROSPECT_PID" "$MCP_PID" 2>/dev/null || true + docker compose -f "$ROOT/examples/07-oauth/docker-compose.yml" down >/dev/null 2>&1 || true + echo "Restoring service configs: product/order/tasks=enabled, billing/billing-jwt/billing-introspection=disabled ..." + python3 - "$ROOT" <<'PYEOF' +import json, sys +root = sys.argv[1] +for svc, enabled in [("billing", False), ("billing-jwt", False), ("billing-introspection", False), + ("product", True), ("order", True), ("tasks", True)]: + path = f"{root}/services/{svc}/config.json" + cfg = json.load(open(path)) + cfg["enabled"] = enabled + json.dump(cfg, open(path, "w"), indent=2, ensure_ascii=False) + open(path, "a").write("\n") +PYEOF +} +trap cleanup EXIT INT TERM + +echo "" +echo "=== OAuth mode running ===" +echo " Docker mock AS : http://localhost:8080/default" +echo " billing-service : http://localhost:3004" +echo " mock-introspection-server : http://localhost:3008" +echo " Harbor : http://localhost:3333/mcp" +echo "" +echo "Get a real JWT: curl -u harbor-test-client:test-secret -d grant_type=client_credentials http://localhost:8080/default/token" +echo "Run the Postman collection's 'Auth — oauth-2.1 / jwt-validation / oauth-introspection' folders against this now." +echo "Press Ctrl+C to stop and restore default (static-token) mode." +echo "" + +wait "$MCP_PID" diff --git a/postman/Harbor.postman_collection.json b/postman/Harbor.postman_collection.json new file mode 100644 index 0000000..c8cc2ca --- /dev/null +++ b/postman/Harbor.postman_collection.json @@ -0,0 +1,1528 @@ +{ + "info": { + "name": "Harbor MCP Gateway", + "description": "Exercises Harbor's MCP endpoint across all 4 pluggable auth strategies (static-token, oauth-2.1, jwt-validation, oauth-introspection), including negative/rejection cases for each. Each request folder documents its own startup prerequisites in its description \u2014 Harbor only runs one auth mode at a time per the demo service configs, so folders are meant to be run against the matching server state (see tests/demo_e2e.py for the exact automated sequence this collection mirrors).\n\nRun order for the OAuth-mode folders: the two 'Setup' requests in each folder MUST run first (they populate {{jwtCorrect}}/{{jwtWrongAud}} collection variables consumed by the requests below them) \u2014 running the whole folder top-to-bottom via the Postman Runner (or newman) does this automatically.", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "variable": [ + { + "key": "baseUrl", + "value": "http://127.0.0.1:3333", + "type": "string" + }, + { + "key": "oauthAsBase", + "value": "http://localhost:8080/default", + "type": "string" + }, + { + "key": "oauthClientId", + "value": "harbor-test-client", + "type": "string" + }, + { + "key": "oauthClientSecret", + "value": "test-secret", + "type": "string" + }, + { + "key": "staticBearerToken", + "value": "TestBearerTokenForE2ETestingOnly", + "type": "string" + }, + { + "key": "jwtCorrect", + "value": "", + "type": "string" + }, + { + "key": "jwtWrongAud", + "value": "", + "type": "string" + }, + { + "key": "introspectValidToken", + "value": "introspection-valid-token-abc123", + "type": "string" + }, + { + "key": "introspectWrongAudToken", + "value": "introspection-wrong-aud-token-xyz789", + "type": "string" + }, + { + "key": "introspectRevokedToken", + "value": "introspection-revoked-token-00000000", + "type": "string" + } + ], + "item": [ + { + "name": "Health & Discovery", + "item": [ + { + "name": "GET /health", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/health", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "health" + ] + }, + "description": "Basic liveness check \u2014 no auth required." + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('status field is ok', () => pm.expect(json.status).to.eql('ok'));", + "pm.test('protocolVersion is 2026-07-28', () => pm.expect(json.protocolVersion).to.eql('2026-07-28'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp \u2014 server/discover (static-token)", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{staticBearerToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "server/discover" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "Connection probe. Uses the static-token bearer \u2014 server/discover doesn't route through per-service auth, any accepted bearer works here.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('result present', () => pm.expect(json).to.have.property('result'));", + "pm.test('serverInfo.name is harbor (spec: result._meta, not result body)', () => {", + " pm.expect(json.result._meta['io.modelcontextprotocol/serverInfo'].name).to.eql('harbor');", + "});", + "pm.test('capabilities.tools present', () => pm.expect(json.result.capabilities).to.have.property('tools'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp \u2014 tools/list", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{staticBearerToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/list" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "const names = (json.result.tools || []).map(t => t.name);", + "for (const n of ['discover_services','discover_skills','search_code','api_execute']) {", + " pm.test(`tool '${n}' present`, () => pm.expect(names).to.include(n));", + "}" + ], + "type": "text/javascript" + } + } + ] + } + ], + "description": "No auth-strategy-specific setup needed \u2014 works against Harbor started any way (static-token demo or OAuth mode)." + }, + { + "name": "Auth \u2014 static-token (product/order/tasks)", + "item": [ + { + "name": "api_execute(product) \u2014 valid static token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{staticBearerToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "Requires: bash examples/demo/start.sh (product/order/tasks enabled, default mode).", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"product\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/products\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('products array returned', () => pm.expect(parsed.products).to.be.an('array').that.is.not.empty);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(product) \u2014 second call, same token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{staticBearerToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "A second, distinct authenticated tool call with the same token \u2014 confirms the auth pass isn't a one-off fluke.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"product\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/products/p001\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('correct product returned', () => pm.expect(parsed.id).to.eql('p001'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp \u2014 no Authorization header \u2192 401", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 401', () => pm.response.to.have.status(401));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp \u2014 malformed/weak token \u2192 401", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer not-a-real-token" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "server/discover" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "A short, non-JWT-shaped bearer fails Harbor's own bearer-format pre-check (must be JWT-shaped or >=32 base64url chars) before any auth strategy runs.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 401', () => pm.response.to.have.status(401));", + "const json = pm.response.json();", + "pm.test('reason is weak_credentials', () => pm.expect(json.reason).to.eql('weak_credentials'));" + ], + "type": "text/javascript" + } + } + ] + } + ], + "description": "Prerequisite: `bash examples/demo/start.sh` \u2014 starts Harbor with product/order/tasks enabled (default demo mode)." + }, + { + "name": "Auth \u2014 oauth-2.1 (billing)", + "item": [ + { + "name": "Setup \u2014 get correct-audience JWT", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/x-www-form-urlencoded" + } + ], + "url": { + "raw": "{{oauthAsBase}}/token", + "host": [ + "{{oauthAsBase}}" + ], + "path": [ + "token" + ] + }, + "auth": { + "type": "basic", + "basic": [ + { + "key": "username", + "value": "{{oauthClientId}}" + }, + { + "key": "password", + "value": "{{oauthClientSecret}}" + } + ] + }, + "body": { + "mode": "urlencoded", + "urlencoded": [ + { + "key": "grant_type", + "value": "client_credentials" + } + ] + }, + "description": "Mints a JWT bound to aud=http://localhost:3333 (Harbor's own resource identifier) \u2014 the correct audience for both the oauth-2.1 and jwt-validation demo services." + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('access_token present', () => pm.expect(json.access_token).to.be.a('string'));", + "pm.test('token has 3 segments', () => pm.expect(json.access_token.split('.').length).to.eql(3));", + "pm.collectionVariables.set('jwtCorrect', json.access_token);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "Setup \u2014 get wrong-audience JWT (confused-deputy)", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/x-www-form-urlencoded" + } + ], + "url": { + "raw": "{{oauthAsBase}}/token", + "host": [ + "{{oauthAsBase}}" + ], + "path": [ + "token" + ] + }, + "auth": { + "type": "basic", + "basic": [ + { + "key": "username", + "value": "{{oauthClientId}}" + }, + { + "key": "password", + "value": "{{oauthClientSecret}}" + } + ] + }, + "body": { + "mode": "urlencoded", + "urlencoded": [ + { + "key": "grant_type", + "value": "client_credentials" + }, + { + "key": "scope", + "value": "confused-deputy" + } + ] + }, + "description": "Same signing key and issuer, but the mock AS's confused-deputy request-mapping stamps aud=https://not-harbor.example.com \u2014 a same-issuer token minted for a DIFFERENT resource. This must be rejected by resource binding (RFC 8707 / MCP 2026-07-28 \u00a717)." + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('access_token present', () => pm.expect(json.access_token).to.be.a('string'));", + "pm.collectionVariables.set('jwtWrongAud', json.access_token);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing) \u2014 correct-aud JWT \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtCorrect}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('invoices returned from live backend', () => pm.expect(parsed.invoices).to.be.an('array').that.is.not.empty);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing) \u2014 second call, same token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtCorrect}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "A second, distinct authenticated tool call with the same token \u2014 confirms the auth pass isn't a one-off fluke.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices/inv-001\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('correct invoice returned', () => pm.expect(parsed.id).to.eql('inv-001'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing) \u2014 wrong-aud JWT \u2192 rejected (confused-deputy)", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtWrongAud}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200 (tool-level error, not transport error)', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is true', () => pm.expect(json.result.isError).to.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('no invoice data leaked', () => pm.expect(parsed).to.not.have.property('invoices'));", + "pm.test(\"error code is TOKEN_INVALID\", () => pm.expect(parsed.code).to.eql('TOKEN_INVALID'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp (billing) \u2014 no token \u2192 401", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 401', () => pm.response.to.have.status(401));", + "pm.test('WWW-Authenticate header present', () => pm.expect(pm.response.headers.has('WWW-Authenticate')).to.be.true);" + ], + "type": "text/javascript" + } + } + ] + } + ], + "description": "Prerequisites: docker compose -f examples/07-oauth/docker-compose.yml up -d; enable services/billing (enabled:true) and disable product/order/tasks; run node examples/demo/billing-service.js; start Harbor with HARBOR_RESOURCE_URI=http://127.0.0.1:3333 and HARBOR_AUTH_SERVERS=http://localhost:8080/default. See tests/demo_e2e.py's _switch_to_oauth_mode()/_start_harbor_oauth() for the exact automated sequence." + }, + { + "name": "Auth \u2014 jwt-validation (billing-jwt)", + "item": [ + { + "name": "Setup \u2014 get correct-audience JWT", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/x-www-form-urlencoded" + } + ], + "url": { + "raw": "{{oauthAsBase}}/token", + "host": [ + "{{oauthAsBase}}" + ], + "path": [ + "token" + ] + }, + "auth": { + "type": "basic", + "basic": [ + { + "key": "username", + "value": "{{oauthClientId}}" + }, + { + "key": "password", + "value": "{{oauthClientSecret}}" + } + ] + }, + "body": { + "mode": "urlencoded", + "urlencoded": [ + { + "key": "grant_type", + "value": "client_credentials" + } + ] + }, + "description": "Mints a JWT bound to aud=http://localhost:3333 (Harbor's own resource identifier) \u2014 the correct audience for both the oauth-2.1 and jwt-validation demo services." + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('access_token present', () => pm.expect(json.access_token).to.be.a('string'));", + "pm.test('token has 3 segments', () => pm.expect(json.access_token.split('.').length).to.eql(3));", + "pm.collectionVariables.set('jwtCorrect', json.access_token);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "Setup \u2014 get wrong-audience JWT (confused-deputy)", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/x-www-form-urlencoded" + } + ], + "url": { + "raw": "{{oauthAsBase}}/token", + "host": [ + "{{oauthAsBase}}" + ], + "path": [ + "token" + ] + }, + "auth": { + "type": "basic", + "basic": [ + { + "key": "username", + "value": "{{oauthClientId}}" + }, + { + "key": "password", + "value": "{{oauthClientSecret}}" + } + ] + }, + "body": { + "mode": "urlencoded", + "urlencoded": [ + { + "key": "grant_type", + "value": "client_credentials" + }, + { + "key": "scope", + "value": "confused-deputy" + } + ] + }, + "description": "Same signing key and issuer, but the mock AS's confused-deputy request-mapping stamps aud=https://not-harbor.example.com \u2014 a same-issuer token minted for a DIFFERENT resource. This must be rejected by resource binding (RFC 8707 / MCP 2026-07-28 \u00a717)." + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('access_token present', () => pm.expect(json.access_token).to.be.a('string'));", + "pm.collectionVariables.set('jwtWrongAud', json.access_token);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-jwt) \u2014 correct-aud JWT \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtCorrect}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-jwt\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('invoices returned from live backend', () => pm.expect(parsed.invoices).to.be.an('array').that.is.not.empty);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-jwt) \u2014 second call, same token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtCorrect}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "A second, distinct authenticated tool call with the same token \u2014 confirms the auth pass isn't a one-off fluke.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-jwt\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices/inv-001\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('correct invoice returned', () => pm.expect(parsed.id).to.eql('inv-001'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-jwt) \u2014 wrong-aud JWT \u2192 rejected (confused-deputy)", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{jwtWrongAud}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-jwt\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200 (tool-level error, not transport error)', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is true', () => pm.expect(json.result.isError).to.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('no invoice data leaked', () => pm.expect(parsed).to.not.have.property('invoices'));", + "pm.test(\"error code is TOKEN_INVALID\", () => pm.expect(parsed.code).to.eql('TOKEN_INVALID'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp (billing-jwt) \u2014 no token \u2192 401", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 401', () => pm.response.to.have.status(401));", + "pm.test('WWW-Authenticate header present', () => pm.expect(pm.response.headers.has('WWW-Authenticate')).to.be.true);" + ], + "type": "text/javascript" + } + } + ] + } + ], + "description": "Same prerequisites as the oauth-2.1 folder, plus services/billing-jwt enabled:true. This strategy verifies the JWT locally against the same mock AS's JWKS directly (jwksUri configured explicitly, no RFC 8414 discovery) \u2014 same confused-deputy protection, different code path." + }, + { + "name": "Auth \u2014 oauth-introspection (billing-introspection)", + "item": [ + { + "name": "api_execute(billing-introspection) \u2014 valid token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{introspectValidToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-introspection\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('invoices returned from live backend', () => pm.expect(parsed.invoices).to.be.an('array').that.is.not.empty);" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-introspection) \u2014 second call, same token \u2192 success", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{introspectValidToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "description": "A second, distinct authenticated tool call with the same token \u2014 confirms the auth pass isn't a one-off fluke.", + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-introspection\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices/inv-001\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is falsy', () => pm.expect(json.result.isError).to.not.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('correct invoice returned', () => pm.expect(parsed.id).to.eql('inv-001'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-introspection) \u2014 wrong-aud token \u2192 rejected", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{introspectWrongAudToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-introspection\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200 (tool-level error, not transport error)', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is true', () => pm.expect(json.result.isError).to.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('no invoice data leaked', () => pm.expect(parsed).to.not.have.property('invoices'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "api_execute(billing-introspection) \u2014 revoked token \u2192 rejected", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Authorization", + "value": "Bearer {{introspectRevokedToken}}" + }, + { + "key": "Accept", + "value": "application/json, text/event-stream" + }, + { + "key": "MCP-Protocol-Version", + "value": "2026-07-28" + }, + { + "key": "Mcp-Method", + "value": "tools/call" + }, + { + "key": "Mcp-Name", + "value": "api_execute" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"api_execute\",\n \"arguments\": {\n \"service\": \"billing-introspection\",\n \"code\": \"async () => { const r = await api.request({ method: \\\"GET\\\", path: \\\"/invoices\\\" }); return r.data; }\"\n },\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 200 (tool-level error, not transport error)', () => pm.response.to.have.status(200));", + "const json = pm.response.json();", + "pm.test('isError is true', () => pm.expect(json.result.isError).to.be.true);", + "const parsed = JSON.parse(json.result.content[0].text);", + "pm.test('no invoice data leaked', () => pm.expect(parsed).to.not.have.property('invoices'));" + ], + "type": "text/javascript" + } + } + ] + }, + { + "name": "POST /mcp (billing-introspection) \u2014 no token \u2192 401", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/mcp", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "mcp" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"server/discover\",\n \"params\": {\n \"_meta\": {\n \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",\n \"io.modelcontextprotocol/clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0\"\n },\n \"io.modelcontextprotocol/clientCapabilities\": {}\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('status is 401', () => pm.response.to.have.status(401));", + "pm.test('introspection server never called for a request rejected at the bearer pre-check', () => true);" + ], + "type": "text/javascript" + } + } + ] + } + ], + "description": "Prerequisites: services/billing-introspection enabled:true; run node examples/demo/mock-introspection-server.js (port 3008); billing-service.js running (port 3004). Uses fixed test-fixture bearer tokens (not real JWTs) \u2014 see examples/demo/mock-introspection-server.js for the token \u2192 introspection-response mapping." + } + ] +} \ No newline at end of file diff --git a/postman/README.md b/postman/README.md new file mode 100644 index 0000000..81ab25f --- /dev/null +++ b/postman/README.md @@ -0,0 +1,136 @@ +# Testing Harbor with Postman + +`Harbor.postman_collection.json` exercises Harbor's `/mcp` endpoint across all +4 pluggable auth strategies (`static-token`, `oauth-2.1`, `jwt-validation`, +`oauth-introspection`), including negative/rejection cases for each. Every +request has `pm.test()` assertions — you don't have to eyeball responses. + +Harbor only runs **one auth mode at a time** (governed by which +`services/*/config.json` entries have `"enabled": true`), so the collection +is split into two groups of folders that need two different server states: + +| Folder(s) | Server mode | Start with | +|---|---|---| +| `Health & Discovery`, `Auth — static-token` | default (product/order/tasks) | `examples/demo/start.sh` | +| `Auth — oauth-2.1`, `Auth — jwt-validation`, `Auth — oauth-introspection` | OAuth mode (billing/billing-jwt/billing-introspection) | `examples/demo/start-oauth-mode.sh` | + +You do not need to hand-edit any config files or manage Docker/process +lifecycles yourself — both scripts do it for you, including restoring the +default state on `Ctrl+C`. + +## Prerequisites + +- Node 22+, `npm install` already run at the repo root. +- Docker running (only needed for the OAuth-mode script — it starts + `navikt/mock-oauth2-server` via `examples/07-oauth/docker-compose.yml`). +- [Postman](https://www.postman.com/downloads/) (GUI) and/or + [newman](https://www.npmjs.com/package/newman) (CLI) — `npx newman` works + without a separate install. + +## 1. Static-token mode + +```bash +bash examples/demo/start.sh +``` +Leave this running in a terminal (it prints its own status and blocks on +`Ctrl+C` to stop). In Postman (or via newman), run: +- `Health & Discovery` +- `Auth — static-token (product/order/tasks)` + +```bash +# CLI equivalent +npx newman run postman/Harbor.postman_collection.json \ + --folder "Health & Discovery" \ + --folder "Auth — static-token (product/order/tasks)" +``` + +`Ctrl+C` the script when done — it kills product/order/task and Harbor. + +## 2. OAuth mode (oauth-2.1 / jwt-validation / oauth-introspection) + +```bash +bash examples/demo/start-oauth-mode.sh +``` +This script: +1. Flips `services/billing`, `services/billing-jwt`, `services/billing-introspection` to `enabled: true` and `services/product`/`order`/`tasks` to `false`. +2. Starts the Docker mock OAuth server (`docker compose -f examples/07-oauth/docker-compose.yml up -d`). +3. Starts `examples/demo/billing-service.js` (:3004) and `examples/demo/mock-introspection-server.js` (:3008) — the two backends all three OAuth-mode folders call. +4. Starts Harbor with `HARBOR_RESOURCE_URI`/`HARBOR_AUTH_SERVERS` set. + +Leave it running, then in Postman (or newman) run: +- `Auth — oauth-2.1 (billing)` +- `Auth — jwt-validation (billing-jwt)` +- `Auth — oauth-introspection (billing-introspection)` + +```bash +# CLI equivalent +npx newman run postman/Harbor.postman_collection.json \ + --folder "Auth — oauth-2.1 (billing)" \ + --folder "Auth — jwt-validation (billing-jwt)" \ + --folder "Auth — oauth-introspection (billing-introspection)" +``` + +**Important — run order inside the `oauth-2.1` and `jwt-validation` folders:** +each folder's first two requests, `Setup — get correct-audience JWT` and +`Setup — get wrong-audience JWT (confused-deputy)`, mint real JWTs from the +mock AS and store them into the collection variables `jwtCorrect`/ +`jwtWrongAud` that every request below them uses. Running a folder +top-to-bottom (via the Postman Runner, or newman, or manually one-by-one in +order) does this automatically — but if you jump straight to e.g. the +"correct-aud JWT → success" request without running the Setup requests +first in that same session, it'll use whatever stale value (or the empty +default) is currently in those variables. + +`introspection` uses fixed, hardcoded test tokens instead (see +`examples/demo/mock-introspection-server.js`), so it needs no setup step. + +`Ctrl+C` the script when done — it kills all three processes, tears down the +Docker container, and restores `services/*/config.json` back to default +(static-token) mode. + +## Using the Postman GUI instead of newman + +1. Import `postman/Harbor.postman_collection.json` (File → Import). All + variables (`baseUrl`, `oauthAsBase`, tokens, etc.) are already baked into + the collection — no separate environment file needed. +2. Start the matching server (see above). +3. Right-click a folder → **Run folder** (this runs its requests in order, + which matters for the Setup requests described above) — or just click + through requests top-to-bottom manually. +4. Check the **Test Results** tab on each request/run for pass/fail. + +## This collection is a manual testing tool — deliberately not run in CI + +Harbor's CI (`.github/workflows/ci.yml`) does **not** run this collection or +depend on `newman` in any way — not even ephemerally via `npx`. This was a +deliberate call, not an oversight: `newman`'s own dependency tree pulls in +old `faker`/`handlebars`/`flatted`/`csv-parse` versions carrying several +high-severity CVEs and one critical (a Handlebars template-injection RCE). +For an open-source project, keeping the CI/build dependency surface as small +and auditable as possible matters more than automating this one collection — +so it stays a manual, human-run tool, and `newman` never appears in +`package.json`, `package-lock.json`, or any workflow step. + +The same coverage this collection gives you by hand is already automated, +dependency-free, on every commit via `tests/demo_e2e.py` (see +`.github/workflows/ci.yml`'s "E2E" step) and the Vitest unit/integration +suite — those exercise the identical request/response contracts for all 4 +auth strategies without needing `newman` at all. This collection exists +purely as an additional, optional way for a human to poke at a running +Harbor instance from Postman — run it whenever you want extra confidence +during manual testing, not as a required gate. + +## If something fails + +- **Connection refused** — the matching script isn't running, or hasn't + finished starting yet (OAuth mode takes a few seconds for Docker + Harbor + to come up). +- **401 on a request that should succeed** — you're probably running the + wrong folder against the wrong server mode (e.g. `Auth — oauth-2.1` + against a `start.sh`-started server, which has `billing` disabled). +- **`isError: true` on a "success" request in the oauth-2.1/jwt-validation + folders** — re-run the two `Setup` requests first; `jwtCorrect`/ + `jwtWrongAud` may be stale or empty. +- Full command-level equivalents of everything these scripts do are in + `tests/demo_e2e.py`'s `_switch_to_oauth_mode()` / `_start_harbor_oauth()` + / `_start_introspection_server()` if you need to debug a step manually. diff --git a/services/billing-introspection/config.json b/services/billing-introspection/config.json new file mode 100644 index 0000000..fd3b0a7 --- /dev/null +++ b/services/billing-introspection/config.json @@ -0,0 +1,39 @@ +{ + "description": "Billing service (oauth-introspection variant) — same backend as `billing`, protected by Harbor's oauth-introspection auth strategy. Enable to test oauth-introspection end-to-end against the mock introspection server; disable to use the static-token demo services.", + "api": { + "protocol": "http", + "host": "localhost", + "port": 3004, + "basePath": "", + "requestTimeoutMs": 10000, + "maxRetries": 1 + }, + "enabled": false, + "auth": { + "type": "oauth-introspection", + "protocol": "http", + "host": "localhost", + "port": 3008, + "introspectionPath": "/introspect", + "authTimeoutMs": 5000, + "audience": "http://localhost:3333", + "metadataMapping": { + "userId": "sub" + } + }, + "spec": { + "source": "file" + }, + "serviceRefreshIntervalMs": 0, + "circuitBreaker": { + "type": "noop" + }, + "idempotency": { + "type": "noop" + }, + "sandbox": { + "executeTimeoutMs": 10000, + "maxApiCalls": 20, + "maxConcurrentCalls": 3 + } +} diff --git a/services/billing-introspection/skills/call-api.md b/services/billing-introspection/skills/call-api.md new file mode 100644 index 0000000..a073020 --- /dev/null +++ b/services/billing-introspection/skills/call-api.md @@ -0,0 +1,20 @@ +--- +id: call-api +title: Call the billing API (oauth-introspection) +tags: [billing, invoices, oauth-introspection, api] +--- + +# Call Billing API (oauth-introspection) + +Use this skill to invoke endpoints on the billing service. +All requests are validated by Harbor via a token-introspection call before reaching the backend. + +## Steps + +1. Call `GET /invoices` to list invoices +2. Call `GET /invoices/{id}` for details on a specific invoice +3. Harbor introspects the Bearer token against the configured introspection endpoint before forwarding — no token means 401 + +## Purpose + +This service demonstrates Harbor's `oauth-introspection` auth strategy against a billing domain backend. diff --git a/services/billing-introspection/spec.yaml b/services/billing-introspection/spec.yaml new file mode 100644 index 0000000..da0e243 --- /dev/null +++ b/services/billing-introspection/spec.yaml @@ -0,0 +1,70 @@ +openapi: 3.0.3 +info: + title: Billing API (oauth-introspection) + version: 1.0.0 + description: Billing service — used to demonstrate Harbor's oauth-introspection auth strategy + +servers: + - url: http://localhost:3004 + +paths: + /invoices: + get: + operationId: listInvoices + summary: List invoices + description: Returns a list of invoices. Requires a valid JWT bearer token validated by Harbor. + responses: + '200': + description: List of invoices + content: + application/json: + schema: + type: object + properties: + invoices: + type: array + items: + $ref: '#/components/schemas/Invoice' + total: + type: integer + + /invoices/{id}: + get: + operationId: getInvoice + summary: Get invoice by ID + description: Returns details for a single invoice. + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Invoice details + content: + application/json: + schema: + $ref: '#/components/schemas/Invoice' + '404': + description: Invoice not found + +components: + schemas: + Invoice: + type: object + properties: + id: + type: string + customerId: + type: string + amount: + type: number + currency: + type: string + status: + type: string + enum: [draft, issued, paid, overdue] + dueDate: + type: string + format: date diff --git a/services/billing-jwt/config.json b/services/billing-jwt/config.json new file mode 100644 index 0000000..13fed81 --- /dev/null +++ b/services/billing-jwt/config.json @@ -0,0 +1,38 @@ +{ + "description": "Billing service (jwt-validation variant) — same backend as `billing`, protected by Harbor's jwt-validation auth strategy instead of oauth-2.1. Enable to test jwt-validation end-to-end; disable to use the static-token demo services.", + "api": { + "protocol": "http", + "host": "localhost", + "port": 3004, + "basePath": "", + "requestTimeoutMs": 10000, + "maxRetries": 1 + }, + "enabled": false, + "auth": { + "type": "jwt-validation", + "jwksUri": "http://localhost:8080/default/jwks", + "issuer": "http://localhost:8080/default", + "audience": "http://localhost:3333", + "clockToleranceSec": 30, + "metadataMapping": { + "userId": "sub", + "clientId": "client_id" + } + }, + "spec": { + "source": "file" + }, + "serviceRefreshIntervalMs": 0, + "circuitBreaker": { + "type": "noop" + }, + "idempotency": { + "type": "noop" + }, + "sandbox": { + "executeTimeoutMs": 10000, + "maxApiCalls": 20, + "maxConcurrentCalls": 3 + } +} diff --git a/services/billing-jwt/skills/call-api.md b/services/billing-jwt/skills/call-api.md new file mode 100644 index 0000000..b8341a8 --- /dev/null +++ b/services/billing-jwt/skills/call-api.md @@ -0,0 +1,20 @@ +--- +id: call-api +title: Call the billing API (jwt-validation) +tags: [billing, invoices, jwt-validation, api] +--- + +# Call Billing API (jwt-validation) + +Use this skill to invoke endpoints on the billing service. +All requests are validated locally against a JWKS by Harbor before reaching the backend. + +## Steps + +1. Call `GET /invoices` to list invoices +2. Call `GET /invoices/{id}` for details on a specific invoice +3. Harbor verifies the Bearer token's signature, issuer, and audience against the configured JWKS before forwarding — no token means 401 + +## Purpose + +This service demonstrates Harbor's `jwt-validation` auth strategy against a billing domain backend. diff --git a/services/billing-jwt/spec.yaml b/services/billing-jwt/spec.yaml new file mode 100644 index 0000000..9b3d524 --- /dev/null +++ b/services/billing-jwt/spec.yaml @@ -0,0 +1,70 @@ +openapi: 3.0.3 +info: + title: Billing API (jwt-validation) + version: 1.0.0 + description: Billing service — used to demonstrate Harbor's jwt-validation auth strategy + +servers: + - url: http://localhost:3004 + +paths: + /invoices: + get: + operationId: listInvoices + summary: List invoices + description: Returns a list of invoices. Requires a valid JWT bearer token validated by Harbor. + responses: + '200': + description: List of invoices + content: + application/json: + schema: + type: object + properties: + invoices: + type: array + items: + $ref: '#/components/schemas/Invoice' + total: + type: integer + + /invoices/{id}: + get: + operationId: getInvoice + summary: Get invoice by ID + description: Returns details for a single invoice. + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Invoice details + content: + application/json: + schema: + $ref: '#/components/schemas/Invoice' + '404': + description: Invoice not found + +components: + schemas: + Invoice: + type: object + properties: + id: + type: string + customerId: + type: string + amount: + type: number + currency: + type: string + status: + type: string + enum: [draft, issued, paid, overdue] + dueDate: + type: string + format: date diff --git a/tests/demo_e2e.py b/tests/demo_e2e.py index cc7d173..493f955 100644 --- a/tests/demo_e2e.py +++ b/tests/demo_e2e.py @@ -63,12 +63,27 @@ MCP_META_PROTOCOL = "io.modelcontextprotocol/protocolVersion" MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo" MCP_META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities" +MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo" SERVICE_STARTUP_WAIT_S = 1 OAUTH_AS_BASE = "http://localhost:8080/default" OAUTH_CLIENT_ID = "harbor-test-client" OAUTH_CLIENT_SECRET = "test-secret" +# jwt-validation and oauth-introspection both reuse the billing backend +# (:3004) with a different Harbor-side service config — same upstream data, +# different auth strategy under test. +JWT_VALIDATION_SERVICE = "billing-jwt" +INTROSPECTION_SERVICE = "billing-introspection" +INTROSPECTION_PORT = 3008 + +# Fixed test fixtures known to examples/demo/mock-introspection-server.js. +# All >=32 chars so Harbor's bearer-format pre-check lets them through to the +# introspection strategy itself (see spi/auth/bearer-authorization.ts). +INTROSPECT_TOKEN_VALID = "introspection-valid-token-abc123" +INTROSPECT_TOKEN_WRONG_AUD = "introspection-wrong-aud-token-xyz789" +INTROSPECT_TOKEN_REVOKED = "introspection-revoked-token-00000000" + ROOT = Path(__file__).parent.parent COMPOSE_FILE = ROOT / "examples" / "07-oauth" / "docker-compose.yml" @@ -91,6 +106,7 @@ def section(title): print(f"\n{BOLD}{CYAN}── {title}{RESET}") _procs: list[subprocess.Popen] = [] _oauth_harbor_proc: Optional[subprocess.Popen] = None _billing_proc: Optional[subprocess.Popen] = None +_introspection_proc: Optional[subprocess.Popen] = None def _find_node() -> str: for candidate in [ @@ -220,16 +236,18 @@ def _set_service_enabled(name: str, enabled: bool): cfg_path.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n") def _switch_to_oauth_mode(): - _set_service_enabled("billing", True) + for svc in ("billing", JWT_VALIDATION_SERVICE, INTROSPECTION_SERVICE): + _set_service_enabled(svc, True) for svc in ("product", "order", "tasks"): _set_service_enabled(svc, False) - info("Service mode: billing=enabled, product/order/tasks=disabled") + info("Service mode: billing/billing-jwt/billing-introspection=enabled, product/order/tasks=disabled") def _switch_to_token_mode(): - _set_service_enabled("billing", False) + for svc in ("billing", JWT_VALIDATION_SERVICE, INTROSPECTION_SERVICE): + _set_service_enabled(svc, False) for svc in ("product", "order", "tasks"): _set_service_enabled(svc, True) - info("Service mode restored: product/order/tasks=enabled, billing=disabled") + info("Service mode restored: product/order/tasks=enabled, billing/billing-jwt/billing-introspection=disabled") def _start_harbor_oauth(oauth_env: dict): global _oauth_harbor_proc @@ -322,6 +340,46 @@ def _stop_billing_backend(): _billing_proc = None info("billing backend stopped") +def _start_introspection_server(): + """Start the mock RFC 7662 introspection server (:3008) for oauth-introspection.""" + global _introspection_proc + node = _find_node() + script = ROOT / "examples" / "demo" / "mock-introspection-server.js" + _introspection_proc = subprocess.Popen( + [node, str(script)], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + env={**os.environ, "NODE_PATH": str(ROOT / "node_modules")}, + cwd=str(ROOT), + start_new_session=True, + ) + info(f"Started mock-introspection-server.js (pid {_introspection_proc.pid})") + for _ in range(20): + try: + urllib.request.urlopen(f"http://localhost:{INTROSPECTION_PORT}/introspect?token=x", timeout=1) + return + except Exception: + time.sleep(0.5) + raise RuntimeError(f"mock introspection server (:{INTROSPECTION_PORT}) did not become ready") + +def _stop_introspection_server(): + global _introspection_proc + if _introspection_proc is None: + return + try: + os.killpg(os.getpgid(_introspection_proc.pid), signal.SIGTERM) + except Exception: + pass + try: + _introspection_proc.wait(timeout=3) + except subprocess.TimeoutExpired: + try: + os.killpg(os.getpgid(_introspection_proc.pid), signal.SIGKILL) + except Exception: + pass + _introspection_proc = None + info("mock introspection server stopped") + def _get_real_jwt() -> str: data = urllib.parse.urlencode({"grant_type": "client_credentials"}).encode() credentials = base64.b64encode(f"{OAUTH_CLIENT_ID}:{OAUTH_CLIENT_SECRET}".encode()).decode() @@ -491,7 +549,9 @@ def mcp_init() -> bool: if "error" in resp: print(f"{RED}server/discover failed: {resp['error']}{RESET}") return False - server_info = resp.get("result", {}).get("serverInfo", {}) + # Final 2026-07-28 revision: serverInfo lives in the result `_meta`, not + # the result body (SDK v2 beta.5+ / GA — see MCP_META_* constants below). + server_info = resp.get("result", {}).get("_meta", {}).get(MCP_META_SERVER_INFO, {}) return server_info.get("name") == "harbor" def call_tool(name: str, args: dict, req_id: int) -> dict: @@ -871,7 +931,7 @@ def test_docker_oauth(resource_uri: str): assert_true("result" in discover_resp, f"server/discover with real JWT → result present {discover_resp.get('_error', '')}") assert_eq( - discover_resp.get("result", {}).get("serverInfo", {}).get("name"), + discover_resp.get("result", {}).get("_meta", {}).get(MCP_META_SERVER_INFO, {}).get("name"), "harbor", "server/discover → serverInfo.name = harbor", ) @@ -911,6 +971,18 @@ def test_docker_oauth(resource_uri: str): inv_ids = [i.get("id") for i in invoices] assert_in("inv-001", inv_ids, "live billing backend returned inv-001") + # (a2) A second, distinct authenticated tool call with the SAME token — + # confirms auth success isn't a one-off fluke and the token is + # genuinely usable for repeat calls, not just the first one. + DETAIL_CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices/inv-001" }); return r.data; }') + detail = api_exec_jwt("billing", DETAIL_CODE, 602, jwt) + assert_true(not detail["is_error"], + f"second call — api_execute(billing) GET /invoices/inv-001 → success " + f"{(detail['parsed'] or {}).get('error', '')}") + assert_eq((detail["parsed"] or {}).get("id"), "inv-001", + "second call → correct invoice detail returned") + # (b) Wrong-aud JWT (same AS, same signature, aud = not-harbor) → resource # binding REJECTS. Confused-deputy / token pass-through must fail closed. try: @@ -931,6 +1003,122 @@ def test_docker_oauth(resource_uri: str): assert_eq(code, "TOKEN_INVALID", "wrong-aud rejection carries the deterministic TOKEN_INVALID code") +def test_jwt_validation(): + """jwt-validation strategy, live: local JWT verification against the same + Docker mock AS's JWKS (no discovery — jwksUri/issuer/audience configured + directly). Same confused-deputy protection as oauth-2.1, exercised via a + separate Harbor service (`billing-jwt`) pointed at the same billing + backend so only the auth strategy under test differs.""" + section("jwt-validation — real JWT, direct JWKS (billing-jwt)") + + CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices" }); return r.data; }') + + try: + jwt = _get_real_jwt() + except Exception as e: + assert_true(False, f"JWT acquired from mock AS → {e}") + return + + # (a) Correct-aud JWT → jwt-validation accepts it, backend reached. + good = api_exec_jwt(JWT_VALIDATION_SERVICE, CODE, 610, jwt) + assert_true(not good["is_error"], + f"api_execute({JWT_VALIDATION_SERVICE}) with correct-aud JWT → success " + f"{(good['parsed'] or {}).get('error', '')}") + invoices = (good["parsed"] or {}).get("invoices", []) + assert_true(len(invoices) > 0, + f"correct-aud JWT → {len(invoices)} invoices returned from live backend") + + # (a2) A second, distinct authenticated tool call with the SAME token — + # confirms the auth pass isn't a one-off fluke. + DETAIL_CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices/inv-001" }); return r.data; }') + detail = api_exec_jwt(JWT_VALIDATION_SERVICE, DETAIL_CODE, 612, jwt) + assert_true(not detail["is_error"], + f"second call — api_execute({JWT_VALIDATION_SERVICE}) GET /invoices/inv-001 → success " + f"{(detail['parsed'] or {}).get('error', '')}") + assert_eq((detail["parsed"] or {}).get("id"), "inv-001", + "second call → correct invoice detail returned") + + # (b) Wrong-aud JWT (same AS, same signature, different aud) → rejected. + try: + wrong_jwt = _get_jwt_wrong_aud() + except Exception as e: + assert_true(False, f"wrong-aud JWT acquired from mock AS → {e}") + wrong_jwt = None + + if wrong_jwt: + bad = api_exec_jwt(JWT_VALIDATION_SERVICE, CODE, 611, wrong_jwt) + assert_true(bad["is_error"], + f"api_execute({JWT_VALIDATION_SERVICE}) with wrong-aud JWT → rejected (isError)") + bad_parsed = bad["parsed"] or {} + assert_true("invoices" not in bad_parsed, + "wrong-aud JWT → NO invoice data leaked") + assert_eq(bad_parsed.get("code", ""), "TOKEN_INVALID", + "wrong-aud rejection carries the deterministic TOKEN_INVALID code") + + # (c) No token → 401 before the strategy (or the backend) is ever reached. + status, _ = _post_with_bearer("/mcp", "") + # An empty bearer is sent as `Authorization: Bearer `, which the parser + # treats as a missing/malformed credential — same 401 path as no header. + assert_true(status in (400, 401), f"empty bearer rejected before dispatch (status {status})") + +def test_oauth_introspection(): + """oauth-introspection strategy, live: Harbor calls a real HTTP + introspection endpoint (examples/demo/mock-introspection-server.js) for + every request — no JWT parsing/JWKS involved at all. Exercises the + best-effort (not fail-closed) resource-binding check documented on + `OAuthIntrospectionConfig.audience` (RFC 7662 §2.2 makes `aud` optional + in a real introspection response).""" + section("oauth-introspection — real HTTP introspection call (billing-introspection)") + + CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices" }); return r.data; }') + + # (a) Valid, correct-audience token → introspection returns active+matching + # aud, backend reached. + good = api_exec_jwt(INTROSPECTION_SERVICE, CODE, 620, INTROSPECT_TOKEN_VALID) + assert_true(not good["is_error"], + f"api_execute({INTROSPECTION_SERVICE}) with valid token → success " + f"{(good['parsed'] or {}).get('error', '')}") + invoices = (good["parsed"] or {}).get("invoices", []) + assert_true(len(invoices) > 0, + f"valid token → {len(invoices)} invoices returned from live backend") + + # (a2) A second, distinct authenticated tool call with the SAME token — + # confirms the auth pass isn't a one-off fluke. + DETAIL_CODE = ('async () => { const r = await api.request({ method: "GET", ' + 'path: "/invoices/inv-001" }); return r.data; }') + detail = api_exec_jwt(INTROSPECTION_SERVICE, DETAIL_CODE, 623, INTROSPECT_TOKEN_VALID) + assert_true(not detail["is_error"], + f"second call — api_execute({INTROSPECTION_SERVICE}) GET /invoices/inv-001 → success " + f"{(detail['parsed'] or {}).get('error', '')}") + assert_eq((detail["parsed"] or {}).get("id"), "inv-001", + "second call → correct invoice detail returned") + + # (b) Introspection-active token, but wrong `aud` in the response → the + # best-effort resource-binding check rejects it. + wrong_aud = api_exec_jwt(INTROSPECTION_SERVICE, CODE, 621, INTROSPECT_TOKEN_WRONG_AUD) + assert_true(wrong_aud["is_error"], + f"api_execute({INTROSPECTION_SERVICE}) with wrong-aud token → rejected (isError)") + wrong_aud_parsed = wrong_aud["parsed"] or {} + assert_true("invoices" not in wrong_aud_parsed, + "wrong-aud token → NO invoice data leaked") + assert_eq(wrong_aud_parsed.get("code", ""), "TOKEN_INVALID", + "wrong-aud rejection carries the deterministic TOKEN_INVALID code") + + # (c) Revoked/unknown token → introspection returns `{active: false}` + # (no expires_in) → rejected. + revoked = api_exec_jwt(INTROSPECTION_SERVICE, CODE, 622, INTROSPECT_TOKEN_REVOKED) + assert_true(revoked["is_error"], + f"api_execute({INTROSPECTION_SERVICE}) with revoked token → rejected (isError)") + assert_true("invoices" not in (revoked["parsed"] or {}), + "revoked token → NO invoice data leaked") + + # (d) No token → 401 before introspection is ever called. + status, _ = _post_no_token("/mcp") + assert_eq(status, 401, "POST /mcp without token → 401 (introspection never called)") + # ── Main ────────────────────────────────────────────────────────────────────── def main(): @@ -1006,15 +1194,19 @@ def main(): _docker_oauth_up() try: _start_billing_backend() + _start_introspection_server() _start_harbor_oauth({ "HARBOR_RESOURCE_URI": args.oauth_resource_uri, "HARBOR_AUTH_SERVERS": OAUTH_AS_BASE, "HARBOR_SCOPES_SUPPORTED": "api:read,api:write", }) test_docker_oauth(args.oauth_resource_uri) + test_jwt_validation() + test_oauth_introspection() finally: _stop_harbor_oauth() _stop_billing_backend() + _stop_introspection_server() _docker_oauth_down() _switch_to_token_mode() info("Phase-2 cleanup complete") From e93597189e722ff2a3c16fe4157aa6d1df389fdc Mon Sep 17 00:00:00 2001 From: vijay Date: Mon, 14 Sep 2026 02:51:23 +0530 Subject: [PATCH 23/25] updated gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 7e8c304..fa71776 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,4 @@ coverage/ reviews/ __pycache__/ pr_reviews/ +postman/ From 13ba342940a908431773a46defaa14b02247c167 Mon Sep 17 00:00:00 2001 From: vijay Date: Mon, 14 Sep 2026 02:51:48 +0530 Subject: [PATCH 24/25] fixed postman collection auth defaults --- postman/Harbor.postman_collection.json | 92 ++++++++++++++++++++++++-- postman/README.md | 11 +++ 2 files changed, 96 insertions(+), 7 deletions(-) diff --git a/postman/Harbor.postman_collection.json b/postman/Harbor.postman_collection.json index c8cc2ca..c893ecf 100644 --- a/postman/Harbor.postman_collection.json +++ b/postman/Harbor.postman_collection.json @@ -74,7 +74,10 @@ "health" ] }, - "description": "Basic liveness check \u2014 no auth required." + "description": "Basic liveness check \u2014 no auth required.", + "auth": { + "type": "noauth" + } }, "response": [], "event": [ @@ -136,6 +139,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -200,6 +206,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -221,7 +230,10 @@ ] } ], - "description": "No auth-strategy-specific setup needed \u2014 works against Harbor started any way (static-token demo or OAuth mode)." + "description": "No auth-strategy-specific setup needed \u2014 works against Harbor started any way (static-token demo or OAuth mode).", + "auth": { + "type": "noauth" + } }, { "name": "Auth \u2014 static-token (product/order/tasks)", @@ -274,6 +286,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -341,6 +356,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -387,6 +405,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -446,6 +467,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -464,7 +488,10 @@ ] } ], - "description": "Prerequisite: `bash examples/demo/start.sh` \u2014 starts Harbor with product/order/tasks enabled (default demo mode)." + "description": "Prerequisite: `bash examples/demo/start.sh` \u2014 starts Harbor with product/order/tasks enabled (default demo mode).", + "auth": { + "type": "noauth" + } }, { "name": "Auth \u2014 oauth-2.1 (billing)", @@ -639,6 +666,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -706,6 +736,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -772,6 +805,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -819,6 +855,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -836,7 +875,10 @@ ] } ], - "description": "Prerequisites: docker compose -f examples/07-oauth/docker-compose.yml up -d; enable services/billing (enabled:true) and disable product/order/tasks; run node examples/demo/billing-service.js; start Harbor with HARBOR_RESOURCE_URI=http://127.0.0.1:3333 and HARBOR_AUTH_SERVERS=http://localhost:8080/default. See tests/demo_e2e.py's _switch_to_oauth_mode()/_start_harbor_oauth() for the exact automated sequence." + "description": "Prerequisites: docker compose -f examples/07-oauth/docker-compose.yml up -d; enable services/billing (enabled:true) and disable product/order/tasks; run node examples/demo/billing-service.js; start Harbor with HARBOR_RESOURCE_URI=http://127.0.0.1:3333 and HARBOR_AUTH_SERVERS=http://localhost:8080/default. See tests/demo_e2e.py's _switch_to_oauth_mode()/_start_harbor_oauth() for the exact automated sequence.", + "auth": { + "type": "noauth" + } }, { "name": "Auth \u2014 jwt-validation (billing-jwt)", @@ -1011,6 +1053,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1078,6 +1123,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1144,6 +1192,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1191,6 +1242,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1208,7 +1262,10 @@ ] } ], - "description": "Same prerequisites as the oauth-2.1 folder, plus services/billing-jwt enabled:true. This strategy verifies the JWT locally against the same mock AS's JWKS directly (jwksUri configured explicitly, no RFC 8414 discovery) \u2014 same confused-deputy protection, different code path." + "description": "Same prerequisites as the oauth-2.1 folder, plus services/billing-jwt enabled:true. This strategy verifies the JWT locally against the same mock AS's JWKS directly (jwksUri configured explicitly, no RFC 8414 discovery) \u2014 same confused-deputy protection, different code path.", + "auth": { + "type": "noauth" + } }, { "name": "Auth \u2014 oauth-introspection (billing-introspection)", @@ -1260,6 +1317,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1327,6 +1387,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1393,6 +1456,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1459,6 +1525,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1505,6 +1574,9 @@ "language": "json" } } + }, + "auth": { + "type": "noauth" } }, "response": [], @@ -1522,7 +1594,13 @@ ] } ], - "description": "Prerequisites: services/billing-introspection enabled:true; run node examples/demo/mock-introspection-server.js (port 3008); billing-service.js running (port 3004). Uses fixed test-fixture bearer tokens (not real JWTs) \u2014 see examples/demo/mock-introspection-server.js for the token \u2192 introspection-response mapping." + "description": "Prerequisites: services/billing-introspection enabled:true; run node examples/demo/mock-introspection-server.js (port 3008); billing-service.js running (port 3004). Uses fixed test-fixture bearer tokens (not real JWTs) \u2014 see examples/demo/mock-introspection-server.js for the token \u2192 introspection-response mapping.", + "auth": { + "type": "noauth" + } } - ] + ], + "auth": { + "type": "noauth" + } } \ No newline at end of file diff --git a/postman/README.md b/postman/README.md index 81ab25f..5fd56be 100644 --- a/postman/README.md +++ b/postman/README.md @@ -134,3 +134,14 @@ during manual testing, not as a required gate. - Full command-level equivalents of everything these scripts do are in `tests/demo_e2e.py`'s `_switch_to_oauth_mode()` / `_start_harbor_oauth()` / `_start_introspection_server()` if you need to debug a step manually. +- **`{{bearer_token_...}}` "value is not initialised", or a request that + should send `Bearer not-a-real-token` instead comes back with + `MISSING_TOKEN` / `malformed_scheme`** — every level of this collection + (root, every folder, every request) has its Authorization tab explicitly + set to **No Auth**, precisely so nothing overrides the literal + `Authorization` header each request already sets in its Headers tab. If + you still see this, your Postman *workspace* has local, previously-synced + auth state on top of the file (Postman stores per-item UI edits separately + from the imported JSON) — re-check the Authorization tab at the request, + its parent folder, and the collection root, and set any that aren't + already "No Auth" back to it. From 3bee88c66be749969a17bf30e17886bacdb23819 Mon Sep 17 00:00:00 2001 From: vijay Date: Mon, 14 Sep 2026 02:57:14 +0530 Subject: [PATCH 25/25] add irctc demo service example --- examples/demo/irctc/.gitignore | 5 + examples/demo/irctc/.python-version | 1 + examples/demo/irctc/README.md | 171 +++++ examples/demo/irctc/Requirements.md | 701 ++++++++++++++++++ examples/demo/irctc/app/__init__.py | 0 examples/demo/irctc/app/config.py | 13 + examples/demo/irctc/app/database.py | 20 + examples/demo/irctc/app/errors.py | 29 + examples/demo/irctc/app/main.py | 96 +++ examples/demo/irctc/app/models/__init__.py | 6 + .../demo/irctc/app/models/availability.py | 20 + examples/demo/irctc/app/models/booking.py | 39 + examples/demo/irctc/app/models/station.py | 12 + examples/demo/irctc/app/models/train.py | 31 + .../demo/irctc/app/repositories/__init__.py | 0 .../app/repositories/availability_repo.py | 26 + .../irctc/app/repositories/booking_repo.py | 16 + .../irctc/app/repositories/station_repo.py | 17 + .../demo/irctc/app/repositories/train_repo.py | 19 + examples/demo/irctc/app/routes/__init__.py | 0 .../demo/irctc/app/routes/availability.py | 54 ++ examples/demo/irctc/app/routes/bookings.py | 57 ++ examples/demo/irctc/app/routes/demo.py | 40 + examples/demo/irctc/app/routes/stations.py | 22 + examples/demo/irctc/app/routes/trains.py | 50 ++ examples/demo/irctc/app/schemas/__init__.py | 0 .../demo/irctc/app/schemas/availability.py | 24 + examples/demo/irctc/app/schemas/booking.py | 58 ++ examples/demo/irctc/app/schemas/common.py | 30 + examples/demo/irctc/app/schemas/station.py | 9 + examples/demo/irctc/app/schemas/train.py | 44 ++ examples/demo/irctc/app/seed.py | 217 ++++++ examples/demo/irctc/app/services/__init__.py | 0 .../app/services/availability_service.py | 30 + .../irctc/app/services/booking_service.py | 148 ++++ .../demo/irctc/app/services/fare_service.py | 43 ++ .../demo/irctc/app/services/train_service.py | 131 ++++ examples/demo/irctc/main.py | 6 + examples/demo/irctc/pyproject.toml | 7 + examples/demo/irctc/requirements.txt | 6 + examples/demo/irctc/tests/__init__.py | 0 examples/demo/irctc/tests/conftest.py | 19 + .../irctc/tests/test_availability_and_fare.py | 52 ++ examples/demo/irctc/tests/test_bookings.py | 126 ++++ .../irctc/tests/test_demo_and_stations.py | 37 + examples/demo/irctc/tests/test_trains.py | 47 ++ examples/demo/start.sh | 13 +- services/README.md | 3 +- services/irctc/config.json | 31 + services/irctc/skills/00-start-here.md | 45 ++ .../irctc/skills/book-and-manage-ticket.md | 56 ++ .../skills/check-availability-and-fare.md | 35 + .../irctc/skills/reset-and-health-check.md | 25 + services/irctc/skills/search-trains.md | 38 + services/irctc/spec.yaml | 641 ++++++++++++++++ 55 files changed, 3362 insertions(+), 4 deletions(-) create mode 100644 examples/demo/irctc/.gitignore create mode 100644 examples/demo/irctc/.python-version create mode 100644 examples/demo/irctc/README.md create mode 100644 examples/demo/irctc/Requirements.md create mode 100644 examples/demo/irctc/app/__init__.py create mode 100644 examples/demo/irctc/app/config.py create mode 100644 examples/demo/irctc/app/database.py create mode 100644 examples/demo/irctc/app/errors.py create mode 100644 examples/demo/irctc/app/main.py create mode 100644 examples/demo/irctc/app/models/__init__.py create mode 100644 examples/demo/irctc/app/models/availability.py create mode 100644 examples/demo/irctc/app/models/booking.py create mode 100644 examples/demo/irctc/app/models/station.py create mode 100644 examples/demo/irctc/app/models/train.py create mode 100644 examples/demo/irctc/app/repositories/__init__.py create mode 100644 examples/demo/irctc/app/repositories/availability_repo.py create mode 100644 examples/demo/irctc/app/repositories/booking_repo.py create mode 100644 examples/demo/irctc/app/repositories/station_repo.py create mode 100644 examples/demo/irctc/app/repositories/train_repo.py create mode 100644 examples/demo/irctc/app/routes/__init__.py create mode 100644 examples/demo/irctc/app/routes/availability.py create mode 100644 examples/demo/irctc/app/routes/bookings.py create mode 100644 examples/demo/irctc/app/routes/demo.py create mode 100644 examples/demo/irctc/app/routes/stations.py create mode 100644 examples/demo/irctc/app/routes/trains.py create mode 100644 examples/demo/irctc/app/schemas/__init__.py create mode 100644 examples/demo/irctc/app/schemas/availability.py create mode 100644 examples/demo/irctc/app/schemas/booking.py create mode 100644 examples/demo/irctc/app/schemas/common.py create mode 100644 examples/demo/irctc/app/schemas/station.py create mode 100644 examples/demo/irctc/app/schemas/train.py create mode 100644 examples/demo/irctc/app/seed.py create mode 100644 examples/demo/irctc/app/services/__init__.py create mode 100644 examples/demo/irctc/app/services/availability_service.py create mode 100644 examples/demo/irctc/app/services/booking_service.py create mode 100644 examples/demo/irctc/app/services/fare_service.py create mode 100644 examples/demo/irctc/app/services/train_service.py create mode 100644 examples/demo/irctc/main.py create mode 100644 examples/demo/irctc/pyproject.toml create mode 100644 examples/demo/irctc/requirements.txt create mode 100644 examples/demo/irctc/tests/__init__.py create mode 100644 examples/demo/irctc/tests/conftest.py create mode 100644 examples/demo/irctc/tests/test_availability_and_fare.py create mode 100644 examples/demo/irctc/tests/test_bookings.py create mode 100644 examples/demo/irctc/tests/test_demo_and_stations.py create mode 100644 examples/demo/irctc/tests/test_trains.py create mode 100644 services/irctc/config.json create mode 100644 services/irctc/skills/00-start-here.md create mode 100644 services/irctc/skills/book-and-manage-ticket.md create mode 100644 services/irctc/skills/check-availability-and-fare.md create mode 100644 services/irctc/skills/reset-and-health-check.md create mode 100644 services/irctc/skills/search-trains.md create mode 100644 services/irctc/spec.yaml diff --git a/examples/demo/irctc/.gitignore b/examples/demo/irctc/.gitignore new file mode 100644 index 0000000..a70d71f --- /dev/null +++ b/examples/demo/irctc/.gitignore @@ -0,0 +1,5 @@ +__pycache__/ +*.pyc +.venv/ +*.db +.pytest_cache/ diff --git a/examples/demo/irctc/.python-version b/examples/demo/irctc/.python-version new file mode 100644 index 0000000..24ee5b1 --- /dev/null +++ b/examples/demo/irctc/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/examples/demo/irctc/README.md b/examples/demo/irctc/README.md new file mode 100644 index 0000000..f4a2b2a --- /dev/null +++ b/examples/demo/irctc/README.md @@ -0,0 +1,171 @@ +# IRCTC Railway Booking Service + +## Purpose + +A small, self-contained railway booking backend used to demonstrate the Harbor MCP +gateway. It exposes a booking API (search, availability, fare, booking, cancellation) +with a rich OpenAPI spec so Harbor can discover and govern it dynamically. Reference +data (stations, trains, availability) is seeded automatically on startup into a local +SQLite database. + +## Architecture + +```text +AI Agent + | + v +MCP + | + v +Harbor + | + v +OpenAPI discovery / API execution + | + v +Railway Booking Service <-- this repo + | + v +SQLite +``` + +Later, Harbor will introduce a governance layer: + +```text +Governance + | + v +ALLOW / DENY +``` + +sitting in front of backend API execution. **Harbor integration is intentionally not +implemented in this project.** This service only exposes technically valid operations; +policy decisions (e.g. blocking Tatkal for large groups, capping booking amounts) are +left entirely to Harbor. + +Project layout: + +```text +app/ + main.py FastAPI app, lifespan seeding, logging, error handlers + database.py SQLAlchemy engine/session setup + config.py Runtime configuration + models/ SQLAlchemy ORM models + schemas/ Pydantic request/response schemas + repositories/ Data access + services/ Business logic + routes/ Thin FastAPI routers + seed.py Reference data seeding / reset +tests/ pytest suite +``` + +## Installation + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +## Running locally + +```bash +python -m app.main +``` + +The port is defined in one place — `app/config.py` reads `UVICORN_PORT` (default +`3005`). This is also uvicorn's own auto-envvar name, so the same variable works no +matter how you start the app: + +```bash +python -m app.main # uses UVICORN_PORT, default 3005 +UVICORN_PORT=4000 python -m app.main # override +UVICORN_PORT=4000 uvicorn app.main:app --reload # uvicorn CLI honors it directly +UVICORN_PORT=4000 uv run uvicorn app.main:app --reload +``` + +The service listens on `http://localhost:3005` and seeds reference data automatically +on startup (idempotent — safe to restart). + +## API documentation + +- Swagger UI: `http://localhost:3005/docs` +- ReDoc: `http://localhost:3005/redoc` +- Raw OpenAPI spec: `http://localhost:3005/openapi.json` + +## Example curl commands + +```bash +# Search trains +curl "http://localhost:3005/trains/search?from=NDLS&to=PRYJ&date=2026-09-07&preferred_departure_after=20:00" + +# Train details +curl "http://localhost:3005/trains/12418" + +# Check availability +curl "http://localhost:3005/availability?train_number=12418&date=2026-09-07&travel_class=3A&tatkal=false" + +# Calculate fare +curl "http://localhost:3005/fare?train_number=12418&date=2026-09-07&travel_class=3A&passenger_count=2&tatkal=false" + +# Create a booking +curl -X POST "http://localhost:3005/bookings" \ + -H "Content-Type: application/json" \ + -d '{ + "train_number": "12418", + "journey_date": "2026-09-07", + "from": "NDLS", + "to": "PRYJ", + "travel_class": "3A", + "tatkal": false, + "passengers": [ + {"name": "Rahul Sharma", "age": 32, "gender": "M"}, + {"name": "Priya Sharma", "age": 29, "gender": "F"} + ] + }' + +# Retrieve a booking +curl "http://localhost:3005/bookings/" + +# Cancel a booking +curl -X POST "http://localhost:3005/bookings//cancel" + +# Reset booking data +curl -X POST "http://localhost:3005/demo/reset" +``` + +## Booking workflow + +1. Search New Delhi (`NDLS`) -> Prayagraj (`PRYJ`) trains for `2026-09-07`. +2. Filter by `preferred_departure_after=20:00`. +3. Pick a train (e.g. `12418`), check availability, and calculate the fare. +4. Create a booking and receive a generated PNR. +5. Retrieve the booking by PNR. +6. Cancel the booking and confirm the status is `CANCELLED` on re-fetch. +7. Create a Tatkal booking for 3 passengers — the backend allows it (Harbor will later + decide whether this is permitted). +8. Create a booking with total fare above ₹5,000 — the backend allows it (Harbor will + later enforce any maximum-amount policy). + +## Reset instructions + +```bash +curl -X POST "http://localhost:3005/demo/reset" +``` + +This deletes all bookings and restores every availability record to full capacity, +returning the service to a clean state without restarting the app. + +## Tests + +```bash +pytest +``` + +## Harbor integration + +This service deliberately does **not** implement any governance/policy logic (e.g. +blocking Tatkal bookings by passenger count, or capping total booking fare). It exposes +the raw technical capability via a fully-described OpenAPI spec so that Harbor, sitting +in front of this service, can decide — per request — whether an AI agent's action is +`ALLOWED` or `DENIED` before the request ever reaches this backend. diff --git a/examples/demo/irctc/Requirements.md b/examples/demo/irctc/Requirements.md new file mode 100644 index 0000000..a18cafe --- /dev/null +++ b/examples/demo/irctc/Requirements.md @@ -0,0 +1,701 @@ +I want you to build a small, self-contained **simulated IRCTC railway booking service in Python** that I will use as a backend for demonstrating my open-source Harbor MCP gateway. + +IMPORTANT: + +* This is a POC/demo service only. +* Do NOT connect to, scrape, or depend on real IRCTC systems. +* Do NOT claim that any implemented railway rules are actual IRCTC policies. +* The service must run completely locally. +* Use SQLite as the local database. +* No external database, Redis, Kafka, cloud service, or external infrastructure should be required. +* Seed realistic demo data automatically when the application starts. +* Keep the implementation simple, clean, and easy to understand because this will be used in a live technical demo. + +## Technology + +Use: + +* Python 3.11+ +* FastAPI +* Uvicorn +* SQLite +* SQLAlchemy 2.x +* Pydantic +* pytest for tests + +The application should run with: + +```bash +pip install -r requirements.txt +uvicorn app.main:app --reload +``` + +Expose the service on: + +```text +http://localhost:8000 +``` + +FastAPI should automatically expose: + +```text +/openapi.json +/docs +/redoc +``` + +The generated OpenAPI specification is extremely important because Harbor will later consume this API dynamically. + +Use a clean project structure such as: + +```text +app/ + main.py + database.py + models/ + schemas/ + repositories/ + services/ + routes/ + seed.py + config.py + +tests/ + +requirements.txt +README.md +``` + +Keep routes thin and put business logic in service classes. + +--- + +# DOMAIN + +Create a simplified railway booking system. + +## Station + +Fields: + +* code +* name +* city + +Seed at least: + +```text +NDLS - New Delhi +PRYJ - Prayagraj +LKO - Lucknow +BSB - Varanasi +CNB - Kanpur +BCT - Mumbai Central +HWH - Howrah +``` + +Support searching using station code and/or name. + +--- + +# TRAIN + +Fields: + +* id +* train_number +* train_name +* source_station +* destination_station +* departure_time +* arrival_time +* duration_minutes +* running_days +* classes +* base_fare +* tatkal_available + +Create realistic sample trains. + +For example: + +```text +12301 Rajdhani Express +12423 Dibrugarh Rajdhani +12801 Purushottam Express +12418 Prayagraj Express +12951 Mumbai Rajdhani +``` + +These are fictional demo records even if the names/numbers resemble real trains. + +Create enough data so searches return multiple results. + +--- + +# JOURNEY / AVAILABILITY + +Represent availability for: + +* SL +* 3A +* 2A +* 1A + +Each train/date/class combination should have: + +* total_seats +* available_seats +* fare + +Seed enough availability data for the demo. + +--- + +# PASSENGER + +Fields: + +* name +* age +* gender +* id_type +* id_number + +Do not implement real identity verification. + +--- + +# TICKET / BOOKING + +Fields: + +* pnr +* train_id +* journey_date +* source +* destination +* travel_class +* tatkal +* passengers +* total_fare +* status +* created_at + +Possible status: + +```text +CONFIRMED +CANCELLED +``` + +Generate a realistic 10-digit PNR when creating a booking. + +--- + +# REQUIRED APIs + +## 1. Search trains + +GET: + +```text +/trains/search +``` + +Query parameters: + +* from +* to +* date +* preferred_departure_after (optional) +* preferred_departure_before (optional) + +Example: + +```text +GET /trains/search?from=NDLS&to=PRYJ&date=2026-09-07 +``` + +Return: + +* train number +* train name +* departure +* arrival +* duration +* available classes +* fare +* Tatkal availability + +Support filtering by preferred departure time. + +For example: + +```text +preferred_departure_after=20:00 +``` + +This is one of the most important APIs for the demo. + +--- + +# 2. Get train details + +GET: + +```text +/trains/{train_number} +``` + +Return: + +* train details +* route +* schedule +* running days +* classes +* fare information +* Tatkal availability + +--- + +# 3. Check seat availability + +GET: + +```text +/availability +``` + +Query parameters: + +* train_number +* date +* travel_class +* tatkal + +Example: + +```text +GET /availability?train_number=12418&date=2026-09-07&travel_class=3A&tatkal=false +``` + +Return: + +* train +* date +* class +* tatkal +* available_seats +* fare + +Do not modify availability during GET requests. + +--- + +# 4. Create ticket / booking + +POST: + +```text +/bookings +``` + +Request body: + +```json +{ + "train_number": "12418", + "journey_date": "2026-09-07", + "from": "NDLS", + "to": "PRYJ", + "travel_class": "3A", + "tatkal": false, + "passengers": [ + { + "name": "Rahul Sharma", + "age": 32, + "gender": "M" + }, + { + "name": "Priya Sharma", + "age": 29, + "gender": "F" + } + ] +} +``` + +The service should: + +1. Validate train. +2. Validate journey date. +3. Validate source/destination. +4. Validate class. +5. Check availability. +6. Calculate fare. +7. Generate PNR. +8. Reduce available seats. +9. Persist booking. +10. Return booking details. + +Return: + +* PNR +* train +* journey details +* passenger information +* class +* Tatkal status +* total fare +* booking status + +IMPORTANT: + +**Do NOT implement governance rules inside this service.** + +Specifically: + +* Do NOT block Tatkal based on passenger count. +* Do NOT implement a maximum booking amount. +* Do NOT implement Harbor policy enforcement. +* Do NOT implement enterprise governance. + +The backend should expose the capability and allow the operation when technically valid. + +Harbor will later decide whether the operation is permitted. + +This separation is critical to the demo. + +--- + +# 5. Get booking using PNR + +GET: + +```text +/bookings/{pnr} +``` + +Return complete booking details. + +Return HTTP 404 if the PNR doesn't exist. + +--- + +# 6. Cancel booking + +POST: + +```text +/bookings/{pnr}/cancel +``` + +When cancelling: + +1. Validate PNR. +2. Ensure it isn't already cancelled. +3. Mark it CANCELLED. +4. Restore seats. +5. Calculate a simple simulated refund. +6. Return cancellation details. + +--- + +# 7. Calculate fare + +GET: + +```text +/fare +``` + +Parameters: + +* train_number +* date +* travel_class +* passenger_count +* tatkal + +Return: + +* base fare +* Tatkal surcharge +* total fare + +This endpoint is particularly useful for demonstrating Harbor governance. + +--- + +# OPTIONAL APIS + +Add: + +```text +GET /stations/search?query=Delhi +GET /health +POST /demo/reset +``` + +`/demo/reset` should restore seeded availability and remove demo bookings. + +--- + +# OPENAPI REQUIREMENTS + +FastAPI's generated OpenAPI specification must be comprehensive. + +Every endpoint should have: + +* operation_id +* summary +* description +* parameters +* request body schema +* response schema +* error responses +* enums +* required fields + +For example: + +```text +POST /bookings +operationId: createBooking +``` + +Its request schema must explicitly describe: + +* train_number +* journey_date +* from +* to +* travel_class +* tatkal +* passengers + +`tatal` must be a boolean. + +The passenger list must have an explicit array schema. + +Harbor should be able to understand the APIs entirely from `/openapi.json`. + +--- + +# DEMO DATA + +The following scenarios must work immediately after startup. + +## Scenario 1 + +Search: + +```text +New Delhi → Prayagraj +Date: 2026-09-07 +Preferred departure: after 20:00 +``` + +Return at least 2–3 suitable trains. + +## Scenario 2 + +Tatkal booking. + +At least one train must support Tatkal. + +## Scenario 3 + +Normal booking for two passengers. + +## Scenario 4 + +Tatkal booking for three passengers. + +**The backend must allow this if technically valid.** + +Harbor's governance layer will later block it. + +## Scenario 5 + +Booking with total fare greater than ₹5,000. + +Again, allow it if seats are available. + +Harbor will later enforce the maximum amount. + +## Scenario 6 + +Create booking → retrieve by PNR → cancel → retrieve again → confirm CANCELLED. + +--- + +# ERROR HANDLING + +Use consistent JSON errors: + +```json +{ + "error": { + "code": "TRAIN_NOT_FOUND", + "message": "Train 99999 was not found" + } +} +``` + +Use: + +* 400 — validation errors +* 404 — resource not found +* 409 — availability/booking conflicts +* 500 — unexpected errors + +--- + +# LOGGING + +Add structured logging for: + +* timestamp +* request ID +* operation +* train number +* PNR +* result + +Do not unnecessarily log passenger identity information. + +--- + +# TESTS + +Use pytest. + +Test at minimum: + +1. Search trains by route/date. +2. Search using departure-time preference. +3. Get train details. +4. Check availability. +5. Create normal booking. +6. Create Tatkal booking. +7. Retrieve booking by PNR. +8. Cancel booking. +9. Verify seats are restored. +10. Invalid train. +11. Invalid class. +12. Insufficient seats. + +Also explicitly test: + +```text +Tatkal + 3 passengers → backend succeeds +Booking > ₹5,000 → backend succeeds +``` + +These are intentional. + +They will later be blocked by Harbor governance. + +--- + +# RESET / DEMO EXPERIENCE + +The application should be easy to reset between demonstrations. + +Implement: + +```text +POST /demo/reset +``` + +It should: + +* delete all demo bookings +* restore seeded availability +* reset generated demo data + +Return: + +```json +{ + "status": "reset", + "message": "Demo railway data has been restored" +} +``` + +--- + +# README + +Create a README containing: + +1. Project purpose. +2. Important disclaimer that this is not IRCTC. +3. Architecture. +4. Installation. +5. Running locally. +6. API documentation. +7. Example curl commands. +8. Demo workflow. +9. Reset instructions. +10. Harbor integration. + +Show this intended architecture: + +```text +AI Agent + ↓ +MCP + ↓ +Harbor + ↓ +OpenAPI discovery / API execution + ↓ +Simulated Railway Service + ↓ +SQLite +``` + +Later Harbor will introduce: + +```text +Governance + ↓ +ALLOW / DENY +``` + +before backend API execution. + +Do NOT implement Harbor integration in this project. + +--- + +# FINAL ACCEPTANCE CRITERIA + +After running: + +```bash +uvicorn app.main:app --reload +``` + +I must be able to demonstrate: + +1. Search New Delhi → Prayagraj trains. +2. Filter by preferred departure time. +3. Select a train. +4. Check availability. +5. Calculate fare. +6. Create a ticket. +7. Receive PNR. +8. Retrieve ticket using PNR. +9. Cancel ticket. +10. Retrieve PNR again and see CANCELLED. +11. Create a Tatkal booking for three passengers successfully. +12. Create a booking above ₹5,000 successfully. + +The final two cases are deliberate. The **backend provides the capability**, while Harbor will later determine whether the AI agent is **allowed** to perform those operations. + +Keep the implementation small, robust, readable, and demo-friendly. Do not over-engineer it. diff --git a/examples/demo/irctc/app/__init__.py b/examples/demo/irctc/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/app/config.py b/examples/demo/irctc/app/config.py new file mode 100644 index 0000000..68555df --- /dev/null +++ b/examples/demo/irctc/app/config.py @@ -0,0 +1,13 @@ +"""App-wide configuration for the IRCTC service.""" +import os + +DATABASE_URL = os.environ.get("IRCTC_DATABASE_URL", "sqlite:///./irctc_demo.db") + +# UVICORN_PORT is uvicorn's own auto-envvar name (uvicorn's CLI has +# auto_envvar_prefix="UVICORN", so this same var also drives `uvicorn app.main:app` +# and `uv run uvicorn app.main:app` directly, with no --port flag needed). +PORT = int(os.environ.get("UVICORN_PORT", "3005")) + +TATKAL_SURCHARGE_RATE = 0.30 # flat 30% surcharge on base fare per passenger + +TRAVEL_CLASSES = ["SL", "3A", "2A", "1A"] diff --git a/examples/demo/irctc/app/database.py b/examples/demo/irctc/app/database.py new file mode 100644 index 0000000..fcfd471 --- /dev/null +++ b/examples/demo/irctc/app/database.py @@ -0,0 +1,20 @@ +from sqlalchemy import create_engine +from sqlalchemy.orm import DeclarativeBase, sessionmaker + +from app.config import DATABASE_URL + +connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {} +engine = create_engine(DATABASE_URL, connect_args=connect_args) +SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) + + +class Base(DeclarativeBase): + pass + + +def get_db(): + db = SessionLocal() + try: + yield db + finally: + db.close() diff --git a/examples/demo/irctc/app/errors.py b/examples/demo/irctc/app/errors.py new file mode 100644 index 0000000..dc543c7 --- /dev/null +++ b/examples/demo/irctc/app/errors.py @@ -0,0 +1,29 @@ +"""Domain error types mapped to consistent JSON error responses.""" + + +class DomainError(Exception): + status_code: int = 400 + code: str = "BAD_REQUEST" + + def __init__(self, message: str, code: str | None = None, status_code: int | None = None): + super().__init__(message) + self.message = message + if code: + self.code = code + if status_code: + self.status_code = status_code + + +class NotFoundError(DomainError): + status_code = 404 + code = "NOT_FOUND" + + +class ValidationError(DomainError): + status_code = 400 + code = "VALIDATION_ERROR" + + +class ConflictError(DomainError): + status_code = 409 + code = "CONFLICT" diff --git a/examples/demo/irctc/app/main.py b/examples/demo/irctc/app/main.py new file mode 100644 index 0000000..0e37bec --- /dev/null +++ b/examples/demo/irctc/app/main.py @@ -0,0 +1,96 @@ +import logging +import time +import uuid +from contextlib import asynccontextmanager + +from fastapi import FastAPI, Request +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse + +from app.config import PORT +from app.database import Base, SessionLocal, engine +from app.errors import DomainError +from app.routes import availability, bookings, demo, stations, trains +from app.seed import seed_all + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") +logger = logging.getLogger("irctc_demo") + + +@asynccontextmanager +async def lifespan(app: FastAPI): + Base.metadata.create_all(bind=engine) + db = SessionLocal() + try: + seed_all(db) + logger.info("Reference data seeded successfully") + finally: + db.close() + yield + + +app = FastAPI( + title="IRCTC Railway Booking API", + description=( + "Search trains, check seat availability, calculate fares, and create or " + "cancel bookings." + ), + version="0.1.0", + lifespan=lifespan, +) + + +@app.middleware("http") +async def request_logging_middleware(request: Request, call_next): + request_id = str(uuid.uuid4()) + start = time.time() + response = await call_next(request) + duration_ms = round((time.time() - start) * 1000, 2) + logger.info( + "request_id=%s method=%s path=%s status=%s duration_ms=%s", + request_id, + request.method, + request.url.path, + response.status_code, + duration_ms, + ) + response.headers["X-Request-ID"] = request_id + return response + + +@app.exception_handler(DomainError) +async def domain_error_handler(request: Request, exc: DomainError): + return JSONResponse( + status_code=exc.status_code, + content={"error": {"code": exc.code, "message": exc.message}}, + ) + + +@app.exception_handler(RequestValidationError) +async def validation_error_handler(request: Request, exc: RequestValidationError): + return JSONResponse( + status_code=400, + content={"error": {"code": "VALIDATION_ERROR", "message": str(exc)}}, + ) + + +@app.exception_handler(Exception) +async def unhandled_error_handler(request: Request, exc: Exception): + logger.exception("Unhandled error") + return JSONResponse( + status_code=500, + content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}}, + ) + + +app.include_router(stations.router) +app.include_router(trains.router) +app.include_router(availability.router) +app.include_router(bookings.router) +app.include_router(demo.router) + + +if __name__ == "__main__": + import uvicorn + + uvicorn.run("app.main:app", host="0.0.0.0", port=PORT, reload=True) diff --git a/examples/demo/irctc/app/models/__init__.py b/examples/demo/irctc/app/models/__init__.py new file mode 100644 index 0000000..9c255a1 --- /dev/null +++ b/examples/demo/irctc/app/models/__init__.py @@ -0,0 +1,6 @@ +from app.models.station import Station +from app.models.train import Train +from app.models.availability import Availability +from app.models.booking import Booking, BookingPassenger + +__all__ = ["Station", "Train", "Availability", "Booking", "BookingPassenger"] diff --git a/examples/demo/irctc/app/models/availability.py b/examples/demo/irctc/app/models/availability.py new file mode 100644 index 0000000..dc8734b --- /dev/null +++ b/examples/demo/irctc/app/models/availability.py @@ -0,0 +1,20 @@ +from sqlalchemy import Float, ForeignKey, Integer, String, UniqueConstraint +from sqlalchemy.orm import Mapped, mapped_column + +from app.database import Base + + +class Availability(Base): + __tablename__ = "availability" + __table_args__ = ( + UniqueConstraint("train_id", "journey_date", "travel_class", "tatkal", name="uq_availability_slot"), + ) + + id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True) + train_id: Mapped[int] = mapped_column(ForeignKey("trains.id"), nullable=False, index=True) + journey_date: Mapped[str] = mapped_column(String(10), nullable=False, index=True) # "YYYY-MM-DD" + travel_class: Mapped[str] = mapped_column(String(5), nullable=False) + tatkal: Mapped[bool] = mapped_column(default=False, nullable=False) + total_seats: Mapped[int] = mapped_column(Integer, nullable=False) + available_seats: Mapped[int] = mapped_column(Integer, nullable=False) + fare: Mapped[float] = mapped_column(Float, nullable=False) diff --git a/examples/demo/irctc/app/models/booking.py b/examples/demo/irctc/app/models/booking.py new file mode 100644 index 0000000..fc60520 --- /dev/null +++ b/examples/demo/irctc/app/models/booking.py @@ -0,0 +1,39 @@ +from datetime import datetime, timezone + +from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Integer, String +from sqlalchemy.orm import Mapped, mapped_column, relationship + +from app.database import Base + + +class Booking(Base): + __tablename__ = "bookings" + + pnr: Mapped[str] = mapped_column(String(10), primary_key=True) + train_id: Mapped[int] = mapped_column(ForeignKey("trains.id"), nullable=False) + journey_date: Mapped[str] = mapped_column(String(10), nullable=False) + source: Mapped[str] = mapped_column(String(10), nullable=False) + destination: Mapped[str] = mapped_column(String(10), nullable=False) + travel_class: Mapped[str] = mapped_column(String(5), nullable=False) + tatkal: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False) + total_fare: Mapped[float] = mapped_column(Float, nullable=False) + status: Mapped[str] = mapped_column(String(15), nullable=False, default="CONFIRMED") + created_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(timezone.utc)) + + passengers: Mapped[list["BookingPassenger"]] = relationship( + back_populates="booking", cascade="all, delete-orphan" + ) + + +class BookingPassenger(Base): + __tablename__ = "booking_passengers" + + id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True) + booking_pnr: Mapped[str] = mapped_column(ForeignKey("bookings.pnr"), nullable=False) + name: Mapped[str] = mapped_column(String(150), nullable=False) + age: Mapped[int] = mapped_column(Integer, nullable=False) + gender: Mapped[str] = mapped_column(String(1), nullable=False) + id_type: Mapped[str | None] = mapped_column(String(30), nullable=True) + id_number: Mapped[str | None] = mapped_column(String(50), nullable=True) + + booking: Mapped["Booking"] = relationship(back_populates="passengers") diff --git a/examples/demo/irctc/app/models/station.py b/examples/demo/irctc/app/models/station.py new file mode 100644 index 0000000..0ea023c --- /dev/null +++ b/examples/demo/irctc/app/models/station.py @@ -0,0 +1,12 @@ +from sqlalchemy import String +from sqlalchemy.orm import Mapped, mapped_column + +from app.database import Base + + +class Station(Base): + __tablename__ = "stations" + + code: Mapped[str] = mapped_column(String(10), primary_key=True) + name: Mapped[str] = mapped_column(String(100), nullable=False) + city: Mapped[str] = mapped_column(String(100), nullable=False) diff --git a/examples/demo/irctc/app/models/train.py b/examples/demo/irctc/app/models/train.py new file mode 100644 index 0000000..a081333 --- /dev/null +++ b/examples/demo/irctc/app/models/train.py @@ -0,0 +1,31 @@ +from sqlalchemy import Boolean, Float, Integer, String +from sqlalchemy.orm import Mapped, mapped_column + +from app.database import Base + + +class Train(Base): + __tablename__ = "trains" + + id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True) + train_number: Mapped[str] = mapped_column(String(10), unique=True, nullable=False, index=True) + train_name: Mapped[str] = mapped_column(String(150), nullable=False) + source_station: Mapped[str] = mapped_column(String(10), nullable=False) + destination_station: Mapped[str] = mapped_column(String(10), nullable=False) + departure_time: Mapped[str] = mapped_column(String(5), nullable=False) # "HH:MM" + arrival_time: Mapped[str] = mapped_column(String(5), nullable=False) # "HH:MM" + duration_minutes: Mapped[int] = mapped_column(Integer, nullable=False) + running_days: Mapped[str] = mapped_column(String(50), nullable=False) # e.g. "MON,TUE,WED" or "DAILY" + classes: Mapped[str] = mapped_column(String(50), nullable=False) # comma separated: "SL,3A,2A,1A" + base_fare: Mapped[float] = mapped_column(Float, nullable=False) + tatkal_available: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False) + + def classes_list(self) -> list[str]: + return [c.strip() for c in self.classes.split(",") if c.strip()] + + def running_days_list(self) -> list[str]: + return [d.strip() for d in self.running_days.split(",") if d.strip()] + + def runs_on(self, weekday_abbr: str) -> bool: + days = self.running_days_list() + return "DAILY" in days or weekday_abbr in days diff --git a/examples/demo/irctc/app/repositories/__init__.py b/examples/demo/irctc/app/repositories/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/app/repositories/availability_repo.py b/examples/demo/irctc/app/repositories/availability_repo.py new file mode 100644 index 0000000..6971cbc --- /dev/null +++ b/examples/demo/irctc/app/repositories/availability_repo.py @@ -0,0 +1,26 @@ +from sqlalchemy.orm import Session + +from app.models.availability import Availability + + +def get_slot( + db: Session, train_id: int, journey_date: str, travel_class: str, tatkal: bool +) -> Availability | None: + return ( + db.query(Availability) + .filter( + Availability.train_id == train_id, + Availability.journey_date == journey_date, + Availability.travel_class == travel_class, + Availability.tatkal == tatkal, + ) + .first() + ) + + +def get_all_for_train_date(db: Session, train_id: int, journey_date: str) -> list[Availability]: + return ( + db.query(Availability) + .filter(Availability.train_id == train_id, Availability.journey_date == journey_date) + .all() + ) diff --git a/examples/demo/irctc/app/repositories/booking_repo.py b/examples/demo/irctc/app/repositories/booking_repo.py new file mode 100644 index 0000000..f586e5f --- /dev/null +++ b/examples/demo/irctc/app/repositories/booking_repo.py @@ -0,0 +1,16 @@ +from sqlalchemy.orm import Session, joinedload + +from app.models.booking import Booking + + +def get_by_pnr(db: Session, pnr: str) -> Booking | None: + return ( + db.query(Booking) + .options(joinedload(Booking.passengers)) + .filter(Booking.pnr == pnr) + .first() + ) + + +def pnr_exists(db: Session, pnr: str) -> bool: + return db.get(Booking, pnr) is not None diff --git a/examples/demo/irctc/app/repositories/station_repo.py b/examples/demo/irctc/app/repositories/station_repo.py new file mode 100644 index 0000000..9f800da --- /dev/null +++ b/examples/demo/irctc/app/repositories/station_repo.py @@ -0,0 +1,17 @@ +from sqlalchemy import or_ +from sqlalchemy.orm import Session + +from app.models.station import Station + + +def search_stations(db: Session, query: str) -> list[Station]: + like = f"%{query.lower()}%" + return ( + db.query(Station) + .filter(or_(Station.code.ilike(like), Station.name.ilike(like), Station.city.ilike(like))) + .all() + ) + + +def get_station(db: Session, code: str) -> Station | None: + return db.get(Station, code.upper()) diff --git a/examples/demo/irctc/app/repositories/train_repo.py b/examples/demo/irctc/app/repositories/train_repo.py new file mode 100644 index 0000000..42a91ae --- /dev/null +++ b/examples/demo/irctc/app/repositories/train_repo.py @@ -0,0 +1,19 @@ +from sqlalchemy.orm import Session + +from app.models.train import Train + + +def get_by_number(db: Session, train_number: str) -> Train | None: + return db.query(Train).filter(Train.train_number == train_number).first() + + +def search_trains(db: Session, source: str, destination: str) -> list[Train]: + return ( + db.query(Train) + .filter(Train.source_station == source.upper(), Train.destination_station == destination.upper()) + .all() + ) + + +def get_by_id(db: Session, train_id: int) -> Train | None: + return db.get(Train, train_id) diff --git a/examples/demo/irctc/app/routes/__init__.py b/examples/demo/irctc/app/routes/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/app/routes/availability.py b/examples/demo/irctc/app/routes/availability.py new file mode 100644 index 0000000..ae347e0 --- /dev/null +++ b/examples/demo/irctc/app/routes/availability.py @@ -0,0 +1,54 @@ +from datetime import date + +from fastapi import APIRouter, Depends, Query +from sqlalchemy.orm import Session + +from app.database import get_db +from app.schemas.availability import AvailabilityOut, FareBreakdown +from app.schemas.common import ErrorResponse, TravelClass +from app.services import availability_service, fare_service + +router = APIRouter(tags=["Availability & Fare"]) + + +@router.get( + "/availability", + operation_id="checkAvailability", + summary="Check seat availability", + description="Check seat availability for a train, date, and travel class. Read-only; does not modify seats.", + response_model=AvailabilityOut, + responses={ + 404: {"model": ErrorResponse, "description": "Train or availability not found"}, + 400: {"model": ErrorResponse, "description": "Invalid travel class"}, + }, +) +def check_availability( + train_number: str = Query(..., description="Train number", examples=["12418"]), + date_: date = Query(..., alias="date", description="Journey date (YYYY-MM-DD)"), + travel_class: TravelClass = Query(..., description="Travel class"), + tatkal: bool = Query(False, description="Whether to check Tatkal quota"), + db: Session = Depends(get_db), +): + return availability_service.check_availability(db, train_number, date_, travel_class.value, tatkal) + + +@router.get( + "/fare", + operation_id="calculateFare", + summary="Calculate fare", + description="Calculate the fare breakdown (base fare, Tatkal surcharge, total) for a booking scenario.", + response_model=FareBreakdown, + responses={ + 404: {"model": ErrorResponse, "description": "Train or availability not found"}, + 400: {"model": ErrorResponse, "description": "Invalid travel class"}, + }, +) +def calculate_fare( + train_number: str = Query(..., description="Train number", examples=["12418"]), + date_: date = Query(..., alias="date", description="Journey date (YYYY-MM-DD)"), + travel_class: TravelClass = Query(..., description="Travel class"), + passenger_count: int = Query(..., ge=1, le=6, description="Number of passengers"), + tatkal: bool = Query(False, description="Whether this is a Tatkal fare calculation"), + db: Session = Depends(get_db), +): + return fare_service.calculate_fare(db, train_number, date_, travel_class.value, passenger_count, tatkal) diff --git a/examples/demo/irctc/app/routes/bookings.py b/examples/demo/irctc/app/routes/bookings.py new file mode 100644 index 0000000..3e2b869 --- /dev/null +++ b/examples/demo/irctc/app/routes/bookings.py @@ -0,0 +1,57 @@ +from fastapi import APIRouter, Depends +from sqlalchemy.orm import Session + +from app.database import get_db +from app.schemas.booking import BookingOut, CancellationOut, CreateBookingRequest +from app.schemas.common import ErrorResponse +from app.services import booking_service + +router = APIRouter(tags=["Bookings"]) + + +@router.post( + "/bookings", + operation_id="createBooking", + summary="Create a booking", + description="Create a new ticket booking. Validates the train, date, route, class, and availability, " + "calculates the fare, generates a PNR, and reduces available seats. " + "This endpoint intentionally allows Tatkal bookings for any passenger count and any fare amount; " + "policy enforcement (e.g. max passengers, max fare) is expected to be handled by an external " + "governance layer, not this service.", + response_model=BookingOut, + status_code=201, + responses={ + 400: {"model": ErrorResponse, "description": "Validation error"}, + 404: {"model": ErrorResponse, "description": "Train or station not found"}, + 409: {"model": ErrorResponse, "description": "Insufficient seats"}, + }, +) +def create_booking(request: CreateBookingRequest, db: Session = Depends(get_db)): + return booking_service.create_booking(db, request) + + +@router.get( + "/bookings/{pnr}", + operation_id="getBookingByPnr", + summary="Get booking by PNR", + description="Retrieve complete booking details using the PNR.", + response_model=BookingOut, + responses={404: {"model": ErrorResponse, "description": "Booking not found"}}, +) +def get_booking(pnr: str, db: Session = Depends(get_db)): + return booking_service.get_booking(db, pnr) + + +@router.post( + "/bookings/{pnr}/cancel", + operation_id="cancelBooking", + summary="Cancel a booking", + description="Cancel a confirmed booking, restore seats to availability, and calculate the refund amount.", + response_model=CancellationOut, + responses={ + 400: {"model": ErrorResponse, "description": "Booking already cancelled"}, + 404: {"model": ErrorResponse, "description": "Booking not found"}, + }, +) +def cancel_booking(pnr: str, db: Session = Depends(get_db)): + return booking_service.cancel_booking(db, pnr) diff --git a/examples/demo/irctc/app/routes/demo.py b/examples/demo/irctc/app/routes/demo.py new file mode 100644 index 0000000..6a7b523 --- /dev/null +++ b/examples/demo/irctc/app/routes/demo.py @@ -0,0 +1,40 @@ +from datetime import date, timedelta + +from fastapi import APIRouter, Depends +from sqlalchemy.orm import Session + +from app.database import get_db +from app.seed import BOOKING_WINDOW_DAYS, reset_demo_data + +router = APIRouter(tags=["Health & Maintenance"]) + + +@router.get( + "/health", + operation_id="healthCheck", + summary="Health check", + description=( + "Returns service status plus the server's current date and the valid " + "journey_date booking window. Call this first if unsure what 'today' is — " + "do not guess or assume a year/date for journey_date." + ), +) +def health(): + today = date.today() + window_end = today + timedelta(days=BOOKING_WINDOW_DAYS - 1) + return { + "status": "ok", + "today": today.isoformat(), + "booking_window": {"from": today.isoformat(), "to": window_end.isoformat()}, + } + + +@router.post( + "/demo/reset", + operation_id="resetDemoData", + summary="Reset booking data", + description="Removes all bookings and restores every availability record to its initial state.", +) +def reset_demo(db: Session = Depends(get_db)): + reset_demo_data(db) + return {"status": "reset", "message": "Booking data has been restored"} diff --git a/examples/demo/irctc/app/routes/stations.py b/examples/demo/irctc/app/routes/stations.py new file mode 100644 index 0000000..8b1924a --- /dev/null +++ b/examples/demo/irctc/app/routes/stations.py @@ -0,0 +1,22 @@ +from fastapi import APIRouter, Depends, Query +from sqlalchemy.orm import Session + +from app.database import get_db +from app.repositories import station_repo +from app.schemas.station import StationOut + +router = APIRouter(tags=["Stations"]) + + +@router.get( + "/stations/search", + operation_id="searchStations", + summary="Search stations", + description="Search stations by code, name, or city (case-insensitive, partial match).", + response_model=list[StationOut], +) +def search_stations( + query: str = Query(..., description="Search text, e.g. 'Delhi' or 'NDLS'"), + db: Session = Depends(get_db), +): + return station_repo.search_stations(db, query) diff --git a/examples/demo/irctc/app/routes/trains.py b/examples/demo/irctc/app/routes/trains.py new file mode 100644 index 0000000..0cb3edf --- /dev/null +++ b/examples/demo/irctc/app/routes/trains.py @@ -0,0 +1,50 @@ +from datetime import date + +from fastapi import APIRouter, Depends, Query +from sqlalchemy.orm import Session + +from app.database import get_db +from app.schemas.common import ErrorResponse +from app.schemas.train import TrainDetail, TrainSearchResponse +from app.services import train_service + +router = APIRouter(tags=["Trains"]) + + +@router.get( + "/trains/search", + operation_id="searchTrains", + summary="Search trains between two stations", + description="Search trains running between a source and destination station on a given date, " + "optionally filtered by preferred departure time window.", + response_model=TrainSearchResponse, + responses={404: {"model": ErrorResponse, "description": "Station not found"}}, +) +def search_trains( + from_: str = Query(..., alias="from", description="Source station code", examples=["NDLS"]), + to: str = Query(..., description="Destination station code", examples=["PRYJ"]), + date_: date = Query(..., alias="date", description="Journey date (YYYY-MM-DD)"), + preferred_departure_after: str | None = Query( + None, description="Only include trains departing at/after this time (HH:MM)", examples=["20:00"] + ), + preferred_departure_before: str | None = Query( + None, description="Only include trains departing at/before this time (HH:MM)", examples=["23:59"] + ), + db: Session = Depends(get_db), +): + results = train_service.search_trains( + db, from_, to, date_, preferred_departure_after, preferred_departure_before + ) + return {"count": len(results), "results": results} + + +@router.get( + "/trains/{train_number}", + operation_id="getTrainDetails", + summary="Get train details", + description="Get full details for a train including route, schedule, running days, classes and fares.", + response_model=TrainDetail, + responses={404: {"model": ErrorResponse, "description": "Train not found"}}, +) +def get_train_details(train_number: str, db: Session = Depends(get_db)): + return train_service.get_train_details(db, train_number) diff --git a/examples/demo/irctc/app/schemas/__init__.py b/examples/demo/irctc/app/schemas/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/app/schemas/availability.py b/examples/demo/irctc/app/schemas/availability.py new file mode 100644 index 0000000..f3f3505 --- /dev/null +++ b/examples/demo/irctc/app/schemas/availability.py @@ -0,0 +1,24 @@ +from pydantic import BaseModel, Field + +from app.schemas.common import TravelClass + + +class AvailabilityOut(BaseModel): + train_number: str + date: str = Field(..., description="Journey date (YYYY-MM-DD)") + travel_class: TravelClass + tatkal: bool + available_seats: int + total_seats: int + fare: float + + +class FareBreakdown(BaseModel): + train_number: str + date: str + travel_class: TravelClass + passenger_count: int + tatkal: bool + base_fare_per_passenger: float + tatkal_surcharge_per_passenger: float = Field(..., description="Tatkal surcharge per passenger") + total_fare: float diff --git a/examples/demo/irctc/app/schemas/booking.py b/examples/demo/irctc/app/schemas/booking.py new file mode 100644 index 0000000..350557d --- /dev/null +++ b/examples/demo/irctc/app/schemas/booking.py @@ -0,0 +1,58 @@ +from datetime import date, datetime + +from pydantic import BaseModel, Field, field_validator + +from app.schemas.common import BookingStatus, Gender, TravelClass + + +class PassengerIn(BaseModel): + name: str = Field(..., description="Passenger full name", examples=["Rahul Sharma"]) + age: int = Field(..., ge=1, le=120, description="Passenger age in years") + gender: Gender = Field(..., description="Passenger gender") + id_type: str | None = Field(None, description="ID type, e.g. AADHAAR, PASSPORT") + id_number: str | None = Field(None, description="ID number corresponding to id_type") + + +class PassengerOut(PassengerIn): + model_config = {"from_attributes": True} + + +class CreateBookingRequest(BaseModel): + train_number: str = Field(..., description="Train number to book", examples=["12418"]) + journey_date: date = Field(..., description="Date of journey (YYYY-MM-DD)") + from_: str = Field(..., alias="from", description="Source station code", examples=["NDLS"]) + to: str = Field(..., description="Destination station code", examples=["PRYJ"]) + travel_class: TravelClass = Field(..., description="Requested travel class") + tatkal: bool = Field(..., description="Whether this is a Tatkal booking") + passengers: list[PassengerIn] = Field(..., min_length=1, description="List of passengers to book") + + model_config = {"populate_by_name": True} + + @field_validator("passengers") + @classmethod + def non_empty_passengers(cls, v: list[PassengerIn]) -> list[PassengerIn]: + if not v: + raise ValueError("At least one passenger is required") + return v + + +class BookingOut(BaseModel): + pnr: str + train_number: str + train_name: str + journey_date: date + source: str + destination: str + travel_class: TravelClass + tatkal: bool + passengers: list[PassengerOut] + total_fare: float + status: BookingStatus + created_at: datetime + + +class CancellationOut(BaseModel): + pnr: str + status: BookingStatus + refund_amount: float = Field(..., description="Refund amount") + message: str diff --git a/examples/demo/irctc/app/schemas/common.py b/examples/demo/irctc/app/schemas/common.py new file mode 100644 index 0000000..dc1d03d --- /dev/null +++ b/examples/demo/irctc/app/schemas/common.py @@ -0,0 +1,30 @@ +from enum import Enum + +from pydantic import BaseModel, Field + + +class TravelClass(str, Enum): + SL = "SL" + AC3 = "3A" + AC2 = "2A" + AC1 = "1A" + + +class Gender(str, Enum): + MALE = "M" + FEMALE = "F" + OTHER = "O" + + +class BookingStatus(str, Enum): + CONFIRMED = "CONFIRMED" + CANCELLED = "CANCELLED" + + +class ErrorDetail(BaseModel): + code: str = Field(..., description="Machine-readable error code, e.g. TRAIN_NOT_FOUND") + message: str = Field(..., description="Human-readable error message") + + +class ErrorResponse(BaseModel): + error: ErrorDetail diff --git a/examples/demo/irctc/app/schemas/station.py b/examples/demo/irctc/app/schemas/station.py new file mode 100644 index 0000000..096171b --- /dev/null +++ b/examples/demo/irctc/app/schemas/station.py @@ -0,0 +1,9 @@ +from pydantic import BaseModel, Field + + +class StationOut(BaseModel): + code: str = Field(..., description="Unique station code, e.g. NDLS") + name: str = Field(..., description="Station name") + city: str = Field(..., description="City the station is located in") + + model_config = {"from_attributes": True} diff --git a/examples/demo/irctc/app/schemas/train.py b/examples/demo/irctc/app/schemas/train.py new file mode 100644 index 0000000..e70b047 --- /dev/null +++ b/examples/demo/irctc/app/schemas/train.py @@ -0,0 +1,44 @@ +from pydantic import BaseModel, Field + +from app.schemas.common import TravelClass + + +class TrainSearchResult(BaseModel): + train_number: str = Field(..., description="Train number", examples=["12418"]) + train_name: str = Field(..., description="Train name", examples=["Prayagraj Express"]) + source_station: str = Field(..., description="Source station code") + destination_station: str = Field(..., description="Destination station code") + departure_time: str = Field(..., description="Departure time (HH:MM)", examples=["21:15"]) + arrival_time: str = Field(..., description="Arrival time (HH:MM)", examples=["06:40"]) + duration_minutes: int = Field(..., description="Total journey duration in minutes") + available_classes: list[TravelClass] = Field(..., description="Travel classes offered by this train") + fare: dict[str, float] = Field(..., description="Fare per travel class for the requested date") + tatkal_available: bool = Field(..., description="Whether Tatkal quota is offered on this train") + + +class TrainSearchResponse(BaseModel): + count: int + results: list[TrainSearchResult] + + +class TrainScheduleStop(BaseModel): + station_code: str + station_name: str + role: str = Field(..., description="'SOURCE' or 'DESTINATION' for this simplified two-stop schedule") + + +class TrainDetail(BaseModel): + train_number: str + train_name: str + source_station: str + destination_station: str + departure_time: str + arrival_time: str + duration_minutes: int + running_days: list[str] + classes: list[TravelClass] + base_fare: float + tatkal_available: bool + route: list[TrainScheduleStop] + + model_config = {"from_attributes": True} diff --git a/examples/demo/irctc/app/seed.py b/examples/demo/irctc/app/seed.py new file mode 100644 index 0000000..dd90853 --- /dev/null +++ b/examples/demo/irctc/app/seed.py @@ -0,0 +1,217 @@ +"""Seed and reset reference data for the IRCTC service: stations, trains, and +seat availability. +""" +from datetime import date, timedelta + +from sqlalchemy.orm import Session + +from app.models.availability import Availability +from app.models.booking import Booking, BookingPassenger +from app.models.station import Station +from app.models.train import Train + +STATIONS = [ + ("NDLS", "New Delhi", "New Delhi"), + ("PRYJ", "Prayagraj Junction", "Prayagraj"), + ("LKO", "Lucknow", "Lucknow"), + ("BSB", "Varanasi Junction", "Varanasi"), + ("CNB", "Kanpur Central", "Kanpur"), + ("BCT", "Mumbai Central", "Mumbai"), + ("HWH", "Howrah Junction", "Kolkata"), +] + +# (train_number, name, source, destination, departure, arrival, duration_min, running_days, classes, base_fare, tatkal) +# Every route runs in both directions, each with its own train number (e.g. an "up" +# train 12301 and a "down" train 12302 for the same route). +TRAINS = [ + ("12301", "Rajdhani Express", "NDLS", "HWH", "16:55", "10:05", 1030, "DAILY", "3A,2A,1A", 2500.0, True), + ("12302", "Rajdhani Express", "HWH", "NDLS", "16:50", "10:00", 1030, "DAILY", "3A,2A,1A", 2500.0, True), + ("12423", "Dibrugarh Rajdhani", "NDLS", "HWH", "11:05", "13:10", 1565, "DAILY", "3A,2A,1A", 2800.0, True), + ("12424", "Dibrugarh Rajdhani", "HWH", "NDLS", "11:00", "13:00", 1560, "DAILY", "3A,2A,1A", 2800.0, True), + ("12801", "Purushottam Express", "NDLS", "HWH", "14:35", "20:20", 1665, "DAILY", "SL,3A,2A", 1400.0, False), + ("12802", "Purushottam Express", "HWH", "NDLS", "14:30", "20:15", 1665, "DAILY", "SL,3A,2A", 1400.0, False), + ("12418", "Prayagraj Express", "NDLS", "PRYJ", "21:15", "06:40", 565, "DAILY", "SL,3A,2A,1A", 1200.0, True), + ("12417", "Prayagraj Express", "PRYJ", "NDLS", "21:00", "06:15", 555, "DAILY", "SL,3A,2A,1A", 1200.0, True), + ("12951", "Mumbai Rajdhani", "NDLS", "BCT", "16:25", "08:15", 950, "DAILY", "3A,2A,1A", 2600.0, True), + ("12952", "Mumbai Rajdhani", "BCT", "NDLS", "17:00", "08:35", 935, "DAILY", "3A,2A,1A", 2600.0, True), + ("12402", "Prayagraj Duronto", "NDLS", "PRYJ", "20:30", "05:10", 520, "DAILY", "SL,3A,2A", 900.0, False), + ("12401", "Prayagraj Duronto", "PRYJ", "NDLS", "20:00", "04:40", 520, "DAILY", "SL,3A,2A", 900.0, False), + ("12448", "UP Sampark Kranti", "NDLS", "PRYJ", "22:15", "07:00", 525, "DAILY", "SL,3A", 700.0, True), + ("12447", "UP Sampark Kranti", "PRYJ", "NDLS", "22:00", "06:45", 525, "DAILY", "SL,3A", 700.0, True), +] + +# Class fare multipliers relative to a train's base_fare (SL cheapest, 1A priciest). +CLASS_FARE_MULTIPLIER = {"SL": 0.4, "3A": 1.0, "2A": 1.5, "1A": 2.2} + +CLASS_TOTAL_SEATS = {"SL": 500, "3A": 300, "2A": 150, "1A": 50} +CLASS_TOTAL_SEATS_TATKAL = {"SL": 50, "3A": 30, "2A": 15, "1A": 5} + +# Fixed 2-or-4-seat caps for trains running with limited capacity. +SCARCE_AVAILABLE = {"SL": 4, "3A": 2, "2A": 4, "1A": 2} +SCARCE_AVAILABLE_TATKAL = {"SL": 2, "3A": 2, "2A": 2, "1A": 2} + +# Every train is deterministically assigned one capacity profile, applied across +# every date and class it runs. This produces a realistic mix: most trains have +# healthy availability, some run with only a few seats left, and some are fully +# booked out (0 available — booking correctly returns 409 INSUFFICIENT_SEATS). +TRAIN_CAPACITY_PROFILE = { + "12418": "healthy", # Prayagraj Express (NDLS->PRYJ) + "12417": "healthy", # Prayagraj Express (PRYJ->NDLS) + "12402": "healthy", # Prayagraj Duronto (NDLS->PRYJ) + "12401": "healthy", # Prayagraj Duronto (PRYJ->NDLS) + "12301": "healthy", # Rajdhani Express (NDLS->HWH) + "12302": "healthy", # Rajdhani Express (HWH->NDLS) + "12423": "scarce", # Dibrugarh Rajdhani (NDLS->HWH) + "12424": "scarce", # Dibrugarh Rajdhani (HWH->NDLS) + "12448": "scarce", # UP Sampark Kranti (NDLS->PRYJ) + "12447": "scarce", # UP Sampark Kranti (PRYJ->NDLS) + "12801": "sold_out", # Purushottam Express (NDLS->HWH) + "12802": "sold_out", # Purushottam Express (HWH->NDLS) + "12951": "sold_out", # Mumbai Rajdhani (NDLS->BCT) + "12952": "sold_out", # Mumbai Rajdhani (BCT->NDLS) +} + +# Rolling window anchored on "today" so the booking horizon is always current, +# rather than a fixed calendar window that goes stale. +BOOKING_WINDOW_DAYS = 30 + + +def _booking_window_dates() -> list[str]: + start = date.today() + return [(start + timedelta(days=i)).isoformat() for i in range(BOOKING_WINDOW_DAYS)] + + +def _capacity_for(train_number: str, travel_class: str, tatkal: bool) -> tuple[int, int]: + """Return (total_seats, available_seats) for a train/class/tatkal slot.""" + total = (CLASS_TOTAL_SEATS_TATKAL if tatkal else CLASS_TOTAL_SEATS)[travel_class] + profile = TRAIN_CAPACITY_PROFILE.get(train_number, "healthy") + + if profile == "healthy": + return total, total + if profile == "scarce": + available = (SCARCE_AVAILABLE_TATKAL if tatkal else SCARCE_AVAILABLE)[travel_class] + return total, min(available, total) + if profile == "sold_out": + return total, 0 + return total, total + + +def seed_stations(db: Session) -> None: + for code, name, city in STATIONS: + if not db.get(Station, code): + db.add(Station(code=code, name=name, city=city)) + db.commit() + + +def seed_trains(db: Session) -> list[Train]: + trains = [] + for ( + number, + name, + source, + destination, + departure, + arrival, + duration, + running_days, + classes, + base_fare, + tatkal, + ) in TRAINS: + train = db.query(Train).filter(Train.train_number == number).first() + if not train: + train = Train( + train_number=number, + train_name=name, + source_station=source, + destination_station=destination, + departure_time=departure, + arrival_time=arrival, + duration_minutes=duration, + running_days=running_days, + classes=classes, + base_fare=base_fare, + tatkal_available=tatkal, + ) + db.add(train) + db.flush() + trains.append(train) + db.commit() + return trains + + +def seed_availability(db: Session, trains: list[Train]) -> None: + dates = _booking_window_dates() + for train in trains: + for journey_date in dates: + for travel_class in train.classes_list(): + fare = round(train.base_fare * CLASS_FARE_MULTIPLIER[travel_class], 2) + + existing = ( + db.query(Availability) + .filter( + Availability.train_id == train.id, + Availability.journey_date == journey_date, + Availability.travel_class == travel_class, + Availability.tatkal.is_(False), + ) + .first() + ) + if not existing: + total, available = _capacity_for(train.train_number, travel_class, tatkal=False) + db.add( + Availability( + train_id=train.id, + journey_date=journey_date, + travel_class=travel_class, + tatkal=False, + total_seats=total, + available_seats=available, + fare=fare, + ) + ) + + if train.tatkal_available: + existing_tatkal = ( + db.query(Availability) + .filter( + Availability.train_id == train.id, + Availability.journey_date == journey_date, + Availability.travel_class == travel_class, + Availability.tatkal.is_(True), + ) + .first() + ) + if not existing_tatkal: + total_tatkal, available_tatkal = _capacity_for( + train.train_number, travel_class, tatkal=True + ) + db.add( + Availability( + train_id=train.id, + journey_date=journey_date, + travel_class=travel_class, + tatkal=True, + total_seats=total_tatkal, + available_seats=available_tatkal, + fare=fare, + ) + ) + db.commit() + + +def seed_all(db: Session) -> None: + seed_stations(db) + trains = seed_trains(db) + seed_availability(db, trains) + + +def reset_demo_data(db: Session) -> None: + """Delete all bookings and restore every availability record to its initial state.""" + db.query(BookingPassenger).delete() + db.query(Booking).delete() + db.query(Availability).delete() + db.commit() + + trains = db.query(Train).all() + seed_availability(db, trains) diff --git a/examples/demo/irctc/app/services/__init__.py b/examples/demo/irctc/app/services/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/app/services/availability_service.py b/examples/demo/irctc/app/services/availability_service.py new file mode 100644 index 0000000..82f7afa --- /dev/null +++ b/examples/demo/irctc/app/services/availability_service.py @@ -0,0 +1,30 @@ +from datetime import date + +from sqlalchemy.orm import Session + +from app.errors import NotFoundError +from app.repositories import availability_repo +from app.services.train_service import require_train, validate_class + + +def check_availability(db: Session, train_number: str, journey_date: date, travel_class: str, tatkal: bool) -> dict: + train = require_train(db, train_number) + validate_class(train, travel_class) + + date_str = journey_date.isoformat() + slot = availability_repo.get_slot(db, train.id, date_str, travel_class, tatkal) + if not slot: + raise NotFoundError( + f"No availability found for train {train_number} on {date_str} class {travel_class} (tatkal={tatkal})", + code="AVAILABILITY_NOT_FOUND", + ) + + return { + "train_number": train.train_number, + "date": date_str, + "travel_class": travel_class, + "tatkal": tatkal, + "available_seats": slot.available_seats, + "total_seats": slot.total_seats, + "fare": slot.fare, + } diff --git a/examples/demo/irctc/app/services/booking_service.py b/examples/demo/irctc/app/services/booking_service.py new file mode 100644 index 0000000..b7080c6 --- /dev/null +++ b/examples/demo/irctc/app/services/booking_service.py @@ -0,0 +1,148 @@ +import random +from datetime import date + +from sqlalchemy.orm import Session + +from app.errors import ConflictError, NotFoundError, ValidationError +from app.models.booking import Booking, BookingPassenger +from app.repositories import availability_repo, booking_repo, station_repo +from app.schemas.booking import CreateBookingRequest +from app.services.fare_service import compute_fare_for_slot +from app.services.train_service import ( + require_train, + validate_class, + validate_route, + validate_running_day, + validate_tatkal_offered, +) + +CANCEL_REFUND_RATE = 0.75 # 75% of fare refunded on cancellation + + +def _generate_pnr(db: Session) -> str: + while True: + pnr = "".join(random.choices("0123456789", k=10)) + if not booking_repo.pnr_exists(db, pnr): + return pnr + + +def _booking_to_dict(booking: Booking, train_number: str, train_name: str) -> dict: + return { + "pnr": booking.pnr, + "train_number": train_number, + "train_name": train_name, + "journey_date": booking.journey_date, + "source": booking.source, + "destination": booking.destination, + "travel_class": booking.travel_class, + "tatkal": booking.tatkal, + "passengers": booking.passengers, + "total_fare": booking.total_fare, + "status": booking.status, + "created_at": booking.created_at, + } + + +def create_booking(db: Session, request: CreateBookingRequest) -> dict: + train = require_train(db, request.train_number) + + if not station_repo.get_station(db, request.from_): + raise NotFoundError(f"Station {request.from_} was not found", code="STATION_NOT_FOUND") + if not station_repo.get_station(db, request.to): + raise NotFoundError(f"Station {request.to} was not found", code="STATION_NOT_FOUND") + + validate_route(train, request.from_, request.to) + validate_running_day(train, request.journey_date) + validate_class(train, request.travel_class.value) + validate_tatkal_offered(train, request.tatkal) + + date_str = request.journey_date.isoformat() + slot = availability_repo.get_slot(db, train.id, date_str, request.travel_class.value, request.tatkal) + if not slot: + raise NotFoundError( + f"No availability found for train {request.train_number} on {date_str} " + f"class {request.travel_class.value} (tatkal={request.tatkal})", + code="AVAILABILITY_NOT_FOUND", + ) + + passenger_count = len(request.passengers) + if slot.available_seats < passenger_count: + raise ConflictError( + f"Only {slot.available_seats} seat(s) available, requested {passenger_count}", + code="INSUFFICIENT_SEATS", + ) + + fare_breakdown = compute_fare_for_slot(slot.fare, passenger_count, request.tatkal) + + pnr = _generate_pnr(db) + booking = Booking( + pnr=pnr, + train_id=train.id, + journey_date=date_str, + source=request.from_, + destination=request.to, + travel_class=request.travel_class.value, + tatkal=request.tatkal, + total_fare=fare_breakdown["total_fare"], + status="CONFIRMED", + ) + booking.passengers = [ + BookingPassenger( + name=p.name, + age=p.age, + gender=p.gender.value, + id_type=p.id_type, + id_number=p.id_number, + ) + for p in request.passengers + ] + + slot.available_seats -= passenger_count + + db.add(booking) + db.commit() + db.refresh(booking) + + return _booking_to_dict(booking, train.train_number, train.train_name) + + +def get_booking(db: Session, pnr: str) -> dict: + booking = booking_repo.get_by_pnr(db, pnr) + if not booking: + raise NotFoundError(f"Booking {pnr} was not found", code="BOOKING_NOT_FOUND") + train = require_train(db, _train_number_for(db, booking.train_id)) + return _booking_to_dict(booking, train.train_number, train.train_name) + + +def _train_number_for(db: Session, train_id: int) -> str: + from app.repositories import train_repo + + train = train_repo.get_by_id(db, train_id) + if not train: + raise NotFoundError(f"Train with id {train_id} was not found", code="TRAIN_NOT_FOUND") + return train.train_number + + +def cancel_booking(db: Session, pnr: str) -> dict: + booking = booking_repo.get_by_pnr(db, pnr) + if not booking: + raise NotFoundError(f"Booking {pnr} was not found", code="BOOKING_NOT_FOUND") + if booking.status == "CANCELLED": + raise ValidationError(f"Booking {pnr} is already cancelled", code="ALREADY_CANCELLED") + + slot = availability_repo.get_slot(db, booking.train_id, booking.journey_date, booking.travel_class, booking.tatkal) + passenger_count = len(booking.passengers) + if slot: + slot.available_seats = min(slot.total_seats, slot.available_seats + passenger_count) + + booking.status = "CANCELLED" + refund_amount = round(booking.total_fare * CANCEL_REFUND_RATE, 2) + + db.commit() + + return { + "pnr": booking.pnr, + "status": booking.status, + "refund_amount": refund_amount, + "message": f"Booking {pnr} has been cancelled. Refund of {refund_amount} initiated.", + } diff --git a/examples/demo/irctc/app/services/fare_service.py b/examples/demo/irctc/app/services/fare_service.py new file mode 100644 index 0000000..e2ca337 --- /dev/null +++ b/examples/demo/irctc/app/services/fare_service.py @@ -0,0 +1,43 @@ +from datetime import date + +from sqlalchemy.orm import Session + +from app.config import TATKAL_SURCHARGE_RATE +from app.errors import NotFoundError +from app.repositories import availability_repo +from app.services.train_service import require_train, validate_class + + +def compute_fare_for_slot(base_fare_per_passenger: float, passenger_count: int, tatkal: bool) -> dict: + surcharge_per_passenger = round(base_fare_per_passenger * TATKAL_SURCHARGE_RATE, 2) if tatkal else 0.0 + total = round((base_fare_per_passenger + surcharge_per_passenger) * passenger_count, 2) + return { + "base_fare_per_passenger": base_fare_per_passenger, + "tatkal_surcharge_per_passenger": surcharge_per_passenger, + "total_fare": total, + } + + +def calculate_fare( + db: Session, train_number: str, journey_date: date, travel_class: str, passenger_count: int, tatkal: bool +) -> dict: + train = require_train(db, train_number) + validate_class(train, travel_class) + + date_str = journey_date.isoformat() + slot = availability_repo.get_slot(db, train.id, date_str, travel_class, tatkal) + if not slot: + raise NotFoundError( + f"No fare information found for train {train_number} on {date_str} class {travel_class} (tatkal={tatkal})", + code="AVAILABILITY_NOT_FOUND", + ) + + breakdown = compute_fare_for_slot(slot.fare, passenger_count, tatkal) + return { + "train_number": train.train_number, + "date": date_str, + "travel_class": travel_class, + "passenger_count": passenger_count, + "tatkal": tatkal, + **breakdown, + } diff --git a/examples/demo/irctc/app/services/train_service.py b/examples/demo/irctc/app/services/train_service.py new file mode 100644 index 0000000..9d25195 --- /dev/null +++ b/examples/demo/irctc/app/services/train_service.py @@ -0,0 +1,131 @@ +from datetime import date, datetime + +from sqlalchemy.orm import Session + +from app.errors import NotFoundError, ValidationError +from app.models.train import Train +from app.repositories import availability_repo, station_repo, train_repo + + +def _weekday_abbr(journey_date: date) -> str: + return journey_date.strftime("%a").upper() # MON, TUE, ... + + +def _fare_map(db: Session, train: Train, journey_date: str) -> dict[str, float]: + slots = availability_repo.get_all_for_train_date(db, train.id, journey_date) + fares = {slot.travel_class: slot.fare for slot in slots if not slot.tatkal} + for cls in train.classes_list(): + fares.setdefault(cls, train.base_fare) + return fares + + +def _to_search_result(db: Session, train: Train, journey_date: str) -> dict: + return { + "train_number": train.train_number, + "train_name": train.train_name, + "source_station": train.source_station, + "destination_station": train.destination_station, + "departure_time": train.departure_time, + "arrival_time": train.arrival_time, + "duration_minutes": train.duration_minutes, + "available_classes": train.classes_list(), + "fare": _fare_map(db, train, journey_date), + "tatkal_available": train.tatkal_available, + } + + +def search_trains( + db: Session, + source: str, + destination: str, + journey_date: date, + preferred_departure_after: str | None = None, + preferred_departure_before: str | None = None, +) -> list[dict]: + if not station_repo.get_station(db, source): + raise NotFoundError(f"Station {source} was not found", code="STATION_NOT_FOUND") + if not station_repo.get_station(db, destination): + raise NotFoundError(f"Station {destination} was not found", code="STATION_NOT_FOUND") + + weekday = _weekday_abbr(journey_date) + trains = train_repo.search_trains(db, source, destination) + trains = [t for t in trains if t.runs_on(weekday)] + + if preferred_departure_after: + trains = [t for t in trains if t.departure_time >= preferred_departure_after] + if preferred_departure_before: + trains = [t for t in trains if t.departure_time <= preferred_departure_before] + + trains.sort(key=lambda t: t.departure_time) + date_str = journey_date.isoformat() + return [_to_search_result(db, t, date_str) for t in trains] + + +def get_train_details(db: Session, train_number: str) -> dict: + train = train_repo.get_by_number(db, train_number) + if not train: + raise NotFoundError(f"Train {train_number} was not found", code="TRAIN_NOT_FOUND") + + return { + "train_number": train.train_number, + "train_name": train.train_name, + "source_station": train.source_station, + "destination_station": train.destination_station, + "departure_time": train.departure_time, + "arrival_time": train.arrival_time, + "duration_minutes": train.duration_minutes, + "running_days": train.running_days_list(), + "classes": train.classes_list(), + "base_fare": train.base_fare, + "tatkal_available": train.tatkal_available, + "route": [ + {"station_code": train.source_station, "station_name": _station_name(db, train.source_station), "role": "SOURCE"}, + { + "station_code": train.destination_station, + "station_name": _station_name(db, train.destination_station), + "role": "DESTINATION", + }, + ], + } + + +def _station_name(db: Session, code: str) -> str: + station = station_repo.get_station(db, code) + return station.name if station else code + + +def require_train(db: Session, train_number: str) -> Train: + train = train_repo.get_by_number(db, train_number) + if not train: + raise NotFoundError(f"Train {train_number} was not found", code="TRAIN_NOT_FOUND") + return train + + +def validate_class(train: Train, travel_class: str) -> None: + if travel_class not in train.classes_list(): + raise ValidationError( + f"Train {train.train_number} does not offer class {travel_class}", code="INVALID_CLASS" + ) + + +def validate_route(train: Train, source: str, destination: str) -> None: + if train.source_station != source.upper() or train.destination_station != destination.upper(): + raise ValidationError( + f"Train {train.train_number} does not run from {source} to {destination}", + code="INVALID_ROUTE", + ) + + +def validate_running_day(train: Train, journey_date: date) -> None: + if not train.runs_on(_weekday_abbr(journey_date)): + raise ValidationError( + f"Train {train.train_number} does not run on {journey_date.isoformat()}", + code="INVALID_JOURNEY_DATE", + ) + + +def validate_tatkal_offered(train: Train, tatkal: bool) -> None: + if tatkal and not train.tatkal_available: + raise ValidationError( + f"Train {train.train_number} does not offer Tatkal quota", code="TATKAL_NOT_AVAILABLE" + ) diff --git a/examples/demo/irctc/main.py b/examples/demo/irctc/main.py new file mode 100644 index 0000000..0d85f43 --- /dev/null +++ b/examples/demo/irctc/main.py @@ -0,0 +1,6 @@ +def main(): + print("Hello from irctc!") + + +if __name__ == "__main__": + main() diff --git a/examples/demo/irctc/pyproject.toml b/examples/demo/irctc/pyproject.toml new file mode 100644 index 0000000..12697de --- /dev/null +++ b/examples/demo/irctc/pyproject.toml @@ -0,0 +1,7 @@ +[project] +name = "irctc" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = ">=3.13" +dependencies = [] diff --git a/examples/demo/irctc/requirements.txt b/examples/demo/irctc/requirements.txt new file mode 100644 index 0000000..1819eb9 --- /dev/null +++ b/examples/demo/irctc/requirements.txt @@ -0,0 +1,6 @@ +fastapi>=0.111 +uvicorn[standard]>=0.30 +sqlalchemy>=2.0 +pydantic>=2.7 +pytest>=8.0 +httpx>=0.27 diff --git a/examples/demo/irctc/tests/__init__.py b/examples/demo/irctc/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/examples/demo/irctc/tests/conftest.py b/examples/demo/irctc/tests/conftest.py new file mode 100644 index 0000000..5fa77e8 --- /dev/null +++ b/examples/demo/irctc/tests/conftest.py @@ -0,0 +1,19 @@ +import os +import tempfile + +import pytest + +_tmp_dir = tempfile.mkdtemp(prefix="irctc_test_") +os.environ["IRCTC_DATABASE_URL"] = f"sqlite:///{_tmp_dir}/test_irctc.db" + +from fastapi.testclient import TestClient # noqa: E402 + +from app.database import Base, engine # noqa: E402 +from app.main import app # noqa: E402 + + +@pytest.fixture() +def client(): + Base.metadata.drop_all(bind=engine) + with TestClient(app) as test_client: + yield test_client diff --git a/examples/demo/irctc/tests/test_availability_and_fare.py b/examples/demo/irctc/tests/test_availability_and_fare.py new file mode 100644 index 0000000..1bfed53 --- /dev/null +++ b/examples/demo/irctc/tests/test_availability_and_fare.py @@ -0,0 +1,52 @@ +def test_check_availability(client): + resp = client.get( + "/availability", + params={"train_number": "12418", "date": "2026-09-07", "travel_class": "3A", "tatkal": False}, + ) + assert resp.status_code == 200 + body = resp.json() + assert body["train_number"] == "12418" + assert body["available_seats"] > 0 + assert body["fare"] > 0 + + +def test_check_availability_invalid_class(client): + resp = client.get( + "/availability", + params={"train_number": "12951", "date": "2026-09-07", "travel_class": "SL", "tatkal": False}, + ) + assert resp.status_code == 400 + assert resp.json()["error"]["code"] == "INVALID_CLASS" + + +def test_calculate_fare_normal(client): + resp = client.get( + "/fare", + params={ + "train_number": "12418", + "date": "2026-09-07", + "travel_class": "3A", + "passenger_count": 2, + "tatkal": False, + }, + ) + assert resp.status_code == 200 + body = resp.json() + assert body["tatkal_surcharge_per_passenger"] == 0.0 + assert body["total_fare"] == round(body["base_fare_per_passenger"] * 2, 2) + + +def test_calculate_fare_tatkal_adds_surcharge(client): + resp = client.get( + "/fare", + params={ + "train_number": "12418", + "date": "2026-09-07", + "travel_class": "3A", + "passenger_count": 1, + "tatkal": True, + }, + ) + assert resp.status_code == 200 + body = resp.json() + assert body["tatkal_surcharge_per_passenger"] > 0 diff --git a/examples/demo/irctc/tests/test_bookings.py b/examples/demo/irctc/tests/test_bookings.py new file mode 100644 index 0000000..bb64660 --- /dev/null +++ b/examples/demo/irctc/tests/test_bookings.py @@ -0,0 +1,126 @@ +PASSENGER = {"name": "Rahul Sharma", "age": 32, "gender": "M"} + + +def _booking_payload(**overrides): + payload = { + "train_number": "12418", + "journey_date": "2026-09-07", + "from": "NDLS", + "to": "PRYJ", + "travel_class": "3A", + "tatkal": False, + "passengers": [PASSENGER, {"name": "Priya Sharma", "age": 29, "gender": "F"}], + } + payload.update(overrides) + return payload + + +def test_create_normal_booking(client): + resp = client.post("/bookings", json=_booking_payload()) + assert resp.status_code == 201 + body = resp.json() + assert len(body["pnr"]) == 10 + assert body["status"] == "CONFIRMED" + assert len(body["passengers"]) == 2 + assert body["total_fare"] > 0 + + +def test_create_tatkal_booking(client): + resp = client.post("/bookings", json=_booking_payload(tatkal=True)) + assert resp.status_code == 201 + assert resp.json()["tatkal"] is True + + +def test_create_tatkal_booking_three_passengers_succeeds(client): + """Backend must allow Tatkal + 3 passengers; Harbor governance blocks this later, not this service.""" + payload = _booking_payload( + tatkal=True, + passengers=[ + {"name": "A One", "age": 40, "gender": "M"}, + {"name": "B Two", "age": 38, "gender": "F"}, + {"name": "C Three", "age": 10, "gender": "M"}, + ], + ) + resp = client.post("/bookings", json=payload) + assert resp.status_code == 201 + assert len(resp.json()["passengers"]) == 3 + + +def test_create_booking_above_5000_succeeds(client): + """Backend must allow bookings above the future Harbor max-fare threshold.""" + payload = _booking_payload(train_number="12301", to="HWH", travel_class="1A", tatkal=False) + resp = client.post("/bookings", json=payload) + assert resp.status_code == 201 + assert resp.json()["total_fare"] > 5000 + + +def test_retrieve_booking_by_pnr(client): + created = client.post("/bookings", json=_booking_payload()).json() + resp = client.get(f"/bookings/{created['pnr']}") + assert resp.status_code == 200 + assert resp.json()["pnr"] == created["pnr"] + + +def test_retrieve_unknown_pnr_returns_404(client): + resp = client.get("/bookings/0000000000") + assert resp.status_code == 404 + assert resp.json()["error"]["code"] == "BOOKING_NOT_FOUND" + + +def test_cancel_booking_restores_seats(client): + availability_before = client.get( + "/availability", + params={"train_number": "12418", "date": "2026-09-07", "travel_class": "3A", "tatkal": False}, + ).json() + + created = client.post("/bookings", json=_booking_payload()).json() + + availability_after_booking = client.get( + "/availability", + params={"train_number": "12418", "date": "2026-09-07", "travel_class": "3A", "tatkal": False}, + ).json() + assert availability_after_booking["available_seats"] == availability_before["available_seats"] - 2 + + cancel_resp = client.post(f"/bookings/{created['pnr']}/cancel") + assert cancel_resp.status_code == 200 + assert cancel_resp.json()["status"] == "CANCELLED" + + availability_after_cancel = client.get( + "/availability", + params={"train_number": "12418", "date": "2026-09-07", "travel_class": "3A", "tatkal": False}, + ).json() + assert availability_after_cancel["available_seats"] == availability_before["available_seats"] + + get_resp = client.get(f"/bookings/{created['pnr']}") + assert get_resp.json()["status"] == "CANCELLED" + + +def test_cancel_already_cancelled_booking_fails(client): + created = client.post("/bookings", json=_booking_payload()).json() + client.post(f"/bookings/{created['pnr']}/cancel") + resp = client.post(f"/bookings/{created['pnr']}/cancel") + assert resp.status_code == 400 + assert resp.json()["error"]["code"] == "ALREADY_CANCELLED" + + +def test_create_booking_invalid_train(client): + resp = client.post("/bookings", json=_booking_payload(train_number="99999")) + assert resp.status_code == 404 + assert resp.json()["error"]["code"] == "TRAIN_NOT_FOUND" + + +def test_create_booking_invalid_class(client): + resp = client.post("/bookings", json=_booking_payload(train_number="12951", travel_class="SL")) + # 12951 (Mumbai Rajdhani) does not run NDLS->PRYJ or offer SL; route mismatch surfaces first. + assert resp.status_code in (400, 404) + + +def test_create_booking_insufficient_seats(client): + payload = _booking_payload( + travel_class="1A", + tatkal=True, + passengers=[{"name": f"P{i}", "age": 30, "gender": "M"} for i in range(6)], + ) + resp = client.post("/bookings", json=payload) + assert resp.status_code == 409 + assert resp.json()["error"]["code"] == "INSUFFICIENT_SEATS" diff --git a/examples/demo/irctc/tests/test_demo_and_stations.py b/examples/demo/irctc/tests/test_demo_and_stations.py new file mode 100644 index 0000000..1884a38 --- /dev/null +++ b/examples/demo/irctc/tests/test_demo_and_stations.py @@ -0,0 +1,37 @@ +def test_health(client): + resp = client.get("/health") + assert resp.status_code == 200 + assert resp.json()["status"] == "ok" + + +def test_search_stations(client): + resp = client.get("/stations/search", params={"query": "Delhi"}) + assert resp.status_code == 200 + codes = [s["code"] for s in resp.json()] + assert "NDLS" in codes + + +def test_demo_reset_clears_bookings_and_restores_seats(client): + payload = { + "train_number": "12418", + "journey_date": "2026-09-07", + "from": "NDLS", + "to": "PRYJ", + "travel_class": "3A", + "tatkal": False, + "passengers": [{"name": "Test User", "age": 25, "gender": "M"}], + } + created = client.post("/bookings", json=payload).json() + + reset_resp = client.post("/demo/reset") + assert reset_resp.status_code == 200 + assert reset_resp.json()["status"] == "reset" + + get_resp = client.get(f"/bookings/{created['pnr']}") + assert get_resp.status_code == 404 + + availability = client.get( + "/availability", + params={"train_number": "12418", "date": "2026-09-07", "travel_class": "3A", "tatkal": False}, + ).json() + assert availability["available_seats"] == availability["total_seats"] diff --git a/examples/demo/irctc/tests/test_trains.py b/examples/demo/irctc/tests/test_trains.py new file mode 100644 index 0000000..6b0c4c9 --- /dev/null +++ b/examples/demo/irctc/tests/test_trains.py @@ -0,0 +1,47 @@ +def test_search_trains_by_route_and_date(client): + resp = client.get("/trains/search", params={"from": "NDLS", "to": "PRYJ", "date": "2026-09-07"}) + assert resp.status_code == 200 + body = resp.json() + assert body["count"] >= 2 + for result in body["results"]: + assert result["source_station"] == "NDLS" + assert result["destination_station"] == "PRYJ" + + +def test_search_trains_with_departure_preference(client): + resp = client.get( + "/trains/search", + params={ + "from": "NDLS", + "to": "PRYJ", + "date": "2026-09-07", + "preferred_departure_after": "20:00", + }, + ) + assert resp.status_code == 200 + body = resp.json() + assert body["count"] >= 2 + for result in body["results"]: + assert result["departure_time"] >= "20:00" + + +def test_search_trains_unknown_station_returns_404(client): + resp = client.get("/trains/search", params={"from": "ZZZZ", "to": "PRYJ", "date": "2026-09-07"}) + assert resp.status_code == 404 + assert resp.json()["error"]["code"] == "STATION_NOT_FOUND" + + +def test_get_train_details(client): + resp = client.get("/trains/12418") + assert resp.status_code == 200 + body = resp.json() + assert body["train_name"] == "Prayagraj Express" + assert body["tatkal_available"] is True + assert "3A" in body["classes"] + assert len(body["route"]) == 2 + + +def test_get_train_details_invalid_train(client): + resp = client.get("/trains/99999") + assert resp.status_code == 404 + assert resp.json()["error"]["code"] == "TRAIN_NOT_FOUND" diff --git a/examples/demo/start.sh b/examples/demo/start.sh index 7224f74..4c535ca 100755 --- a/examples/demo/start.sh +++ b/examples/demo/start.sh @@ -4,11 +4,13 @@ set -e SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT="$SCRIPT_DIR/.." -echo "=== MCP Demo: Product + Order + Task services ===" +export UVICORN_PORT="${UVICORN_PORT:-3005}" + +echo "=== MCP Demo: Product + Order + Task + IRCTC services ===" echo "" # Kill any leftover processes on demo ports -for PORT in 3001 3002 3003; do +for PORT in 3001 3002 3003 "$UVICORN_PORT"; do PID=$(lsof -ti tcp:$PORT 2>/dev/null || true) if [ -n "$PID" ]; then echo "Killing existing process on port $PORT (pid $PID)" @@ -29,6 +31,10 @@ echo "Starting task-service on :3003 ..." node "$SCRIPT_DIR/task-service.js" & TASK_PID=$! +echo "Starting irctc-service on :$UVICORN_PORT ..." +(cd "$SCRIPT_DIR/irctc" && exec "$SCRIPT_DIR/irctc/.venv/bin/python3" -m app.main) & +IRCTC_PID=$! + # Give them a moment to bind sleep 0.5 @@ -45,7 +51,7 @@ MCP_PID=$! cleanup() { echo "" echo "Shutting down..." - kill "$PRODUCT_PID" "$ORDER_PID" "$TASK_PID" "$MCP_PID" 2>/dev/null || true + kill "$PRODUCT_PID" "$ORDER_PID" "$TASK_PID" "$IRCTC_PID" "$MCP_PID" 2>/dev/null || true } trap cleanup EXIT INT TERM @@ -53,6 +59,7 @@ echo "=== All services running ===" echo " product-service : http://localhost:3001" echo " order-service : http://localhost:3002" echo " task-service : http://localhost:3003" +echo " irctc-service : http://localhost:$UVICORN_PORT" echo " Harbor : http://localhost:3333/mcp" echo "" echo "Connect your MCP client to http://localhost:3333/mcp" diff --git a/services/README.md b/services/README.md index 908708b..d7e141c 100644 --- a/services/README.md +++ b/services/README.md @@ -10,6 +10,7 @@ Four demo services are included so the framework works out of the box: | `order/` | 3002 | static-token | Order management — place and track | | `tasks/` | 3003 | static-token | Task CRUD — create, assign, complete | | `billing/` | 3004 | oauth-2.1 | Billing — demonstrates OAuth 2.1 JWT validation (disabled by default) | +| `irctc/` | 3005 | static-token | IRCTC railway booking — search, availability, fare, book, cancel | Start the token-mode demo backends: `bash examples/demo/start.sh` @@ -34,4 +35,4 @@ See `docs/service-onboarding.md` for the full `config.json` reference. ## Removing the demo services -Delete any of the `product/`, `order/`, `tasks/`, or `billing/` folders you don't need. The gateway only registers folders that contain a valid `spec.yaml` + `config.json`. +Delete any of the `product/`, `order/`, `tasks/`, `billing/`, or `irctc/` folders you don't need. The gateway only registers folders that contain a valid `spec.yaml` + `config.json`, and skips any folder whose `config.json` has `"enabled": false` — set that instead of deleting if you just want to disable a service temporarily. diff --git a/services/irctc/config.json b/services/irctc/config.json new file mode 100644 index 0000000..918bb36 --- /dev/null +++ b/services/irctc/config.json @@ -0,0 +1,31 @@ +{ + "description": "IRCTC railway booking service — search trains, check seat availability, calculate fares, and create or cancel bookings. READ THE '00-start-here' SKILL FIRST. Call GET /health before picking any journey_date — never guess a year/date from memory. Never write custom filtering/sorting code or invent parameters — use only what the OpenAPI spec documents. Some trains run with limited or sold-out capacity (0 seats is a valid result, not a bug). This service does not enforce booking policy (Tatkal group size, max fare) — that is Harbor's job, not yours.", + "api": { + "protocol": "http", + "host": "localhost", + "port": 3005, + "basePath": "", + "requestTimeoutMs": 10000, + "maxRetries": 1 + }, + "enabled": true, + "auth": { + "type": "static-token", + "token": "demo-token-123" + }, + "spec": { + "source": "file" + }, + "serviceRefreshIntervalMs": 0, + "circuitBreaker": { + "type": "noop" + }, + "idempotency": { + "type": "noop" + }, + "sandbox": { + "executeTimeoutMs": 10000, + "maxApiCalls": 20, + "maxConcurrentCalls": 3 + } +} diff --git a/services/irctc/skills/00-start-here.md b/services/irctc/skills/00-start-here.md new file mode 100644 index 0000000..e7b2eea --- /dev/null +++ b/services/irctc/skills/00-start-here.md @@ -0,0 +1,45 @@ +--- +id: 00-start-here +title: Start here — IRCTC service orientation +tags: [irctc, train, railway, booking, start, overview, orientation, guide] +--- + +# Start Here + +Read this before calling any IRCTC endpoint. It tells you which skill to use next +and the hard rules that apply across every operation in this service. + +## Which skill to use + +| User wants to... | Use skill | +|---|---| +| Find trains between two cities/stations | `search-trains` | +| Check seats left, or get a fare quote | `check-availability-and-fare` | +| Book a ticket, look up a PNR, or cancel | `book-and-manage-ticket` | +| Reset booking data, or check service health | `reset-and-health-check` | + +## Hard rules (apply to every call) + +0. **Call `GET /health` before picking any journey_date.** It returns `today` and + `booking_window` (the valid date range). Never guess, assume, or default to a + year/date from memory — always anchor on `/health`'s response. +1. **Never write custom filtering, sorting, or re-derivation code.** Every filter + you could need — route, date, class, tatkal, departure-time window — is already + a documented query parameter on the relevant endpoint. Call the endpoint with + the right parameters and return its response as-is. Do not fetch broad data and + post-process it yourself. +2. **Never invent parameters or fields** that are not in the OpenAPI spec for that + operation. If you're unsure a parameter exists, it probably doesn't. +3. **Station codes are fixed**: `NDLS`, `PRYJ`, `LKO`, `BSB`, `CNB`, `BCT`, `HWH`. + Travel classes are fixed: `SL`, `3A`, `2A`, `1A`. +4. **Data covers a rolling 30-day window starting today.** A journey date outside + that window will 404 — that is expected, not a bug. Pick a date within the next + 30 days. +5. **Some trains run with very limited or zero seats on any given date/class.** + Seeing `available_seats: 0`, or a `409 INSUFFICIENT_SEATS` on booking, means: + stop retrying that exact train — call search again and offer the user a + different train, date, or class. +6. **This service does not enforce booking policy.** It will allow a Tatkal booking + for any number of passengers, and a booking of any fare amount. Do not add your + own limits or refuse a request for those reasons — that decision belongs to + Harbor's governance layer, not you. diff --git a/services/irctc/skills/book-and-manage-ticket.md b/services/irctc/skills/book-and-manage-ticket.md new file mode 100644 index 0000000..877cf91 --- /dev/null +++ b/services/irctc/skills/book-and-manage-ticket.md @@ -0,0 +1,56 @@ +--- +id: book-and-manage-ticket +title: Book a ticket, look up a PNR, and cancel +tags: [book, booking, ticket, pnr, cancel, refund, passenger] +--- + +# Book and Manage a Ticket + +Use this skill when the user wants to book a train ticket, check an existing +booking by PNR, or cancel a booking. + +## Booking a ticket + +1. Confirm with the user: train number, journey date, source/destination station + codes, travel class, whether it's Tatkal, and passenger details (name, age, + gender for each passenger) +2. It's good practice to call `GET /availability` first to confirm enough seats + exist for the group size, to avoid a wasted booking attempt +3. Before calling `POST /bookings`, always show the final booking details and get + a **human confirmation** from the user. This is the last chance to correct any + mistakes in the request body before the booking is made. +4. Call `POST /bookings` with the full request body +5. Return the generated `pnr`, `total_fare`, and `status` to the user + +## Looking up a booking + +1. Call `GET /bookings/{pnr}` +2. If it 404s, tell the user no booking exists for that PNR — do not guess or + fabricate a PNR + +## Cancelling a booking + +1. Call `POST /bookings/{pnr}/cancel` +2. Always show the final cancellation details and get a **human confirmation** from + the user. This is the last chance to correct any mistakes before the + cancellation is made. +3. Return the `refund_amount` and confirm the new `status` is `CANCELLED` +4. If it 400s with "already cancelled", tell the user the current status — do not + call cancel again + +## Important — do not enforce policy yourself + +This service intentionally allows: +- Tatkal bookings for **any number of passengers** +- Bookings of **any total fare amount** + +Do not refuse, warn against, or add your own limits for either of these — that +decision belongs to Harbor's governance layer sitting in front of this API, not to +you. Just make the call and report the result. + +## If booking fails with 409 INSUFFICIENT_SEATS + +This means the specific train/date/class/tatkal combination doesn't have enough +seats for the group. Go back to `GET /trains/search`, pick a different +train/date/class, and offer that to the user instead of retrying the same +request. diff --git a/services/irctc/skills/check-availability-and-fare.md b/services/irctc/skills/check-availability-and-fare.md new file mode 100644 index 0000000..a5fae96 --- /dev/null +++ b/services/irctc/skills/check-availability-and-fare.md @@ -0,0 +1,35 @@ +--- +id: check-availability-and-fare +title: Check seat availability and calculate fare +tags: [availability, seats, fare, price, cost, tatkal, quote] +--- + +# Check Availability and Fare + +Use this skill when the user wants to know how many seats are left on a train, or +wants a fare quote before booking. + +## Checking availability + +1. Call `GET /availability` with `train_number`, `date`, `travel_class`, and + optionally `tatkal` (default `false`) +2. Read `available_seats` directly from the response — do not compute or estimate it + +## Calculating fare + +1. Call `GET /fare` with the same parameters plus `passenger_count` (1-6) +2. Return `base_fare_per_passenger`, `tatkal_surcharge_per_passenger`, and + `total_fare` as given — do not recompute the math yourself + +## Interpreting the result — read this before deciding something is wrong + +- **`available_seats: 0` is a valid response.** Some trains run with very limited + or zero seats in a given class on a given date. It is not a bug and not a reason + to retry the same call. +- If seats are 0 (or too few for the group size), go back to `GET /trains/search` + for the same route/date and offer the user a different train. Do not keep + re-checking the same train/date/class combination. +- A `404` here means the train doesn't run, or the date is outside the bookable + window returned by `GET /health` — not that seats are unavailable. +- A `400` means the requested `travel_class` isn't offered by this train — check + `GET /trains/{train_number}` for its actual class list. diff --git a/services/irctc/skills/reset-and-health-check.md b/services/irctc/skills/reset-and-health-check.md new file mode 100644 index 0000000..26d599d --- /dev/null +++ b/services/irctc/skills/reset-and-health-check.md @@ -0,0 +1,25 @@ +--- +id: reset-and-health-check +title: Reset booking data and check service health +tags: [reset, health, status, restore] +--- + +# Reset Booking Data and Health Check + +Use this skill when the user wants to restore booking data to a clean state, or +wants to confirm the service is up. + +## Health check + +1. Call `GET /health` +2. Return `status`, `today`, and `booking_window` + +## Resetting booking data + +1. Call `POST /demo/reset` +2. This removes all bookings and restores every availability record to its + original capacity +3. Confirm to the user that booking data has been reset + +Only call this when the user explicitly asks to reset/restore data — never call it +as a side effect of another operation. diff --git a/services/irctc/skills/search-trains.md b/services/irctc/skills/search-trains.md new file mode 100644 index 0000000..298ff88 --- /dev/null +++ b/services/irctc/skills/search-trains.md @@ -0,0 +1,38 @@ +--- +id: search-trains +title: Search trains and get train details +tags: [train, search, route, schedule, timing, departure, arrival, find] +--- + +# Search Trains + +Use this skill when the user wants to find trains between two stations, or wants +details about a specific train they already know the number of. + +## Searching by route and date + +1. Call `GET /trains/search` with `from`, `to` (station codes), and `date` + (YYYY-MM-DD, must be within the next 30 days from today) +2. If the user gives a time preference ("after 8pm", "morning trains only"), pass + `preferred_departure_after` and/or `preferred_departure_before` (HH:MM) — do not + filter the `results` array yourself, the parameter already does this +3. Present each result's train number, name, departure/arrival time, duration, + `available_classes`, `fare` (per class), and `tatkal_available` +4. If `count` is 0, tell the user no trains run that route/date — do not retry the + same call expecting a different result + +## Getting full details for a known train + +1. Call `GET /trains/{train_number}` (e.g. `12418`) +2. Return route, schedule, running days, classes, and base fare + +## Important + +- `from`/`to` must be station codes from this fixed set: `NDLS`, `PRYJ`, `LKO`, + `BSB`, `CNB`, `BCT`, `HWH`. If the user gives a city name instead of a code, use + `GET /stations/search?query=` to resolve it first. +- A 404 here means the station code itself isn't recognized — it does not mean "no + trains found" (that's `count: 0` with a `200`). +- This endpoint only returns whether classes/Tatkal are offered — it does not tell + you seat counts. For actual seats left, use the `check-availability-and-fare` + skill next. diff --git a/services/irctc/spec.yaml b/services/irctc/spec.yaml new file mode 100644 index 0000000..c84a96a --- /dev/null +++ b/services/irctc/spec.yaml @@ -0,0 +1,641 @@ +openapi: 3.0.3 +info: + title: IRCTC Railway Booking API + version: 0.1.0 + description: > + Search trains, check seat availability, calculate fares, and create or cancel + bookings. + + Call order: GET /health (get today's date + valid booking window) -> searchTrains + -> checkAvailability -> calculateFare (optional) -> createBooking -> + getBookingByPnr / cancelBooking. See the `00-start-here` skill for full usage + rules before making calls. + +servers: + - url: http://localhost:3005 + +paths: + /stations/search: + get: + operationId: searchStations + summary: Search stations + description: Search stations by code, name, or city (case-insensitive, partial match). + parameters: + - name: query + in: query + required: true + schema: + type: string + description: Search text, e.g. 'Delhi' or 'NDLS' + responses: + '200': + description: Matching stations + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Station' + + /trains/search: + get: + operationId: searchTrains + summary: Search trains between two stations + description: > + Search trains running between a source and destination station on a given + date, optionally filtered by preferred departure time window. The `date` and + `preferred_departure_*` parameters do all the filtering — do not post-process + the `results` array yourself. + parameters: + - name: from + in: query + required: true + schema: + type: string + example: NDLS + description: Source station code (one of NDLS, PRYJ, LKO, BSB, CNB, BCT, HWH) + - name: to + in: query + required: true + schema: + type: string + example: PRYJ + description: Destination station code (one of NDLS, PRYJ, LKO, BSB, CNB, BCT, HWH) + - name: date + in: query + required: true + schema: + type: string + format: date + description: Journey date (YYYY-MM-DD), must be within the next 30 days from today + - name: preferred_departure_after + in: query + required: false + schema: + type: string + description: Only include trains departing at/after this time (HH:MM) + - name: preferred_departure_before + in: query + required: false + schema: + type: string + description: Only include trains departing at/before this time (HH:MM) + responses: + '200': + description: Search results + content: + application/json: + schema: + type: object + properties: + count: + type: integer + results: + type: array + items: + $ref: '#/components/schemas/TrainSearchResult' + '404': + description: Source or destination station code not recognized — re-check spelling, do not retry as-is + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /trains/{train_number}: + get: + operationId: getTrainDetails + summary: Get train details + description: Get full details for a train including route, schedule, running days, classes and fares. + parameters: + - name: train_number + in: path + required: true + schema: + type: string + example: '12418' + responses: + '200': + description: Train details + content: + application/json: + schema: + $ref: '#/components/schemas/TrainDetail' + '404': + description: Train number not found — get valid train numbers from GET /trains/search first + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /availability: + get: + operationId: checkAvailability + summary: Check seat availability + description: > + Check seat availability for a train, date, and travel class. Read-only; does + not modify seats. Some trains are intentionally scarce (2-4 seats) or fully + sold out (available_seats: 0) by design — a 0 does not mean the API is + broken, it means offer the user a different train/date/class. + parameters: + - name: train_number + in: query + required: true + schema: + type: string + example: '12418' + - name: date + in: query + required: true + schema: + type: string + format: date + description: Must be within the next 30 days from today + - name: travel_class + in: query + required: true + schema: + $ref: '#/components/schemas/TravelClass' + - name: tatkal + in: query + required: false + schema: + type: boolean + default: false + responses: + '200': + description: > + Availability details. Check available_seats before booking — 0 is a + valid, expected result for some trains, not an error. + content: + application/json: + schema: + $ref: '#/components/schemas/Availability' + '400': + description: Invalid travel class for this train — see GET /trains/{train_number} for its offered classes + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Train not found, or no seeded data for this date (date is outside the 30-day window) + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /fare: + get: + operationId: calculateFare + summary: Calculate fare + description: Calculate the fare breakdown (base fare, Tatkal surcharge, total) for a booking scenario. + parameters: + - name: train_number + in: query + required: true + schema: + type: string + example: '12418' + - name: date + in: query + required: true + schema: + type: string + format: date + description: Must be within the next 30 days from today + - name: travel_class + in: query + required: true + schema: + $ref: '#/components/schemas/TravelClass' + - name: passenger_count + in: query + required: true + schema: + type: integer + minimum: 1 + maximum: 6 + - name: tatkal + in: query + required: false + schema: + type: boolean + default: false + responses: + '200': + description: Fare breakdown + content: + application/json: + schema: + $ref: '#/components/schemas/FareBreakdown' + '400': + description: Invalid travel class for this train — see GET /trains/{train_number} for its offered classes + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Train not found, or no seeded data for this date (date is outside the 30-day window) + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /bookings: + post: + operationId: createBooking + summary: Create a booking + description: > + Create a new ticket booking. Validates the train, date, route, class, and + availability, calculates the fare, generates a PNR, and reduces available + seats. Call GET /availability first to confirm enough seats exist — this + avoids a wasted 409. Intentionally allows Tatkal bookings for any passenger + count and any fare amount — policy enforcement is expected from Harbor, not + this service; do not reject a request yourself for those reasons. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBookingRequest' + example: + train_number: '12418' + journey_date: '2026-09-07' + from: NDLS + to: PRYJ + travel_class: 3A + tatkal: false + passengers: + - name: Rahul Sharma + age: 32 + gender: M + responses: + '201': + description: Booking created — return the pnr to the user + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + '400': + description: Validation error (bad route, class, or journey date) — fix the request, do not retry as-is + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Train or station not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: > + Not enough seats for this train/date/class/tatkal combination + (INSUFFICIENT_SEATS). Some trains run with limited or sold-out capacity + — call GET /trains/search again and offer the user a different train, + date, or class instead of retrying the same request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /bookings/{pnr}: + get: + operationId: getBookingByPnr + summary: Get booking by PNR + description: Retrieve complete booking details using the PNR. + parameters: + - name: pnr + in: path + required: true + schema: + type: string + example: '8732076977' + responses: + '200': + description: Booking details + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + '404': + description: No booking exists for this PNR — double-check the value returned by createBooking, do not guess a PNR + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /bookings/{pnr}/cancel: + post: + operationId: cancelBooking + summary: Cancel a booking + description: Cancel a confirmed booking, restore seats to availability, and calculate the refund amount. + parameters: + - name: pnr + in: path + required: true + schema: + type: string + example: '8732076977' + responses: + '200': + description: Cancellation details + content: + application/json: + schema: + $ref: '#/components/schemas/Cancellation' + '400': + description: Booking is already CANCELLED — do not call cancel again, tell the user its current status + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: No booking exists for this PNR + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /health: + get: + operationId: healthCheck + summary: Health check + description: > + Returns service status plus the server's current date and the valid + journey_date booking window. Call this first if unsure what "today" is — + never guess or assume a year/date for journey_date on other endpoints. + responses: + '200': + description: Service healthy — use `today` and `booking_window` to pick a valid journey_date + content: + application/json: + schema: + type: object + properties: + status: + type: string + today: + type: string + format: date + description: Server's current date — use this, not a guessed year + booking_window: + type: object + properties: + from: + type: string + format: date + to: + type: string + format: date + description: journey_date must fall within this inclusive range on every other endpoint + + /demo/reset: + post: + operationId: resetDemoData + summary: Reset booking data + description: Removes all bookings and restores every availability record to its initial state. + responses: + '200': + description: Reset confirmation + content: + application/json: + schema: + type: object + properties: + status: + type: string + message: + type: string + +components: + schemas: + TravelClass: + type: string + enum: [SL, 3A, 2A, 1A] + + BookingStatus: + type: string + enum: [CONFIRMED, CANCELLED] + + Gender: + type: string + enum: [M, F, O] + + ErrorResponse: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + + Station: + type: object + properties: + code: + type: string + name: + type: string + city: + type: string + + TrainSearchResult: + type: object + properties: + train_number: + type: string + train_name: + type: string + source_station: + type: string + destination_station: + type: string + departure_time: + type: string + arrival_time: + type: string + duration_minutes: + type: integer + available_classes: + type: array + items: + $ref: '#/components/schemas/TravelClass' + fare: + type: object + additionalProperties: + type: number + tatkal_available: + type: boolean + + TrainDetail: + type: object + properties: + train_number: + type: string + train_name: + type: string + source_station: + type: string + destination_station: + type: string + departure_time: + type: string + arrival_time: + type: string + duration_minutes: + type: integer + running_days: + type: array + items: + type: string + classes: + type: array + items: + $ref: '#/components/schemas/TravelClass' + base_fare: + type: number + tatkal_available: + type: boolean + route: + type: array + items: + type: object + properties: + station_code: + type: string + station_name: + type: string + role: + type: string + + Availability: + type: object + properties: + train_number: + type: string + date: + type: string + travel_class: + $ref: '#/components/schemas/TravelClass' + tatkal: + type: boolean + available_seats: + type: integer + total_seats: + type: integer + fare: + type: number + + FareBreakdown: + type: object + properties: + train_number: + type: string + date: + type: string + travel_class: + $ref: '#/components/schemas/TravelClass' + passenger_count: + type: integer + tatkal: + type: boolean + base_fare_per_passenger: + type: number + tatkal_surcharge_per_passenger: + type: number + total_fare: + type: number + + PassengerIn: + type: object + required: [name, age, gender] + properties: + name: + type: string + age: + type: integer + minimum: 1 + maximum: 120 + gender: + $ref: '#/components/schemas/Gender' + id_type: + type: string + nullable: true + description: ID type, e.g. AADHAAR, PASSPORT + id_number: + type: string + nullable: true + description: ID number corresponding to id_type + + CreateBookingRequest: + type: object + required: [train_number, journey_date, from, to, travel_class, tatkal, passengers] + properties: + train_number: + type: string + example: '12418' + journey_date: + type: string + format: date + description: Must be within the next 30 days from today + from: + type: string + example: NDLS + to: + type: string + example: PRYJ + travel_class: + $ref: '#/components/schemas/TravelClass' + tatkal: + type: boolean + passengers: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/PassengerIn' + + Booking: + type: object + properties: + pnr: + type: string + train_number: + type: string + train_name: + type: string + journey_date: + type: string + source: + type: string + destination: + type: string + travel_class: + $ref: '#/components/schemas/TravelClass' + tatkal: + type: boolean + passengers: + type: array + items: + $ref: '#/components/schemas/PassengerIn' + total_fare: + type: number + status: + $ref: '#/components/schemas/BookingStatus' + created_at: + type: string + format: date-time + + Cancellation: + type: object + properties: + pnr: + type: string + status: + $ref: '#/components/schemas/BookingStatus' + refund_amount: + type: number + message: + type: string