Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
7ab71c8
build(deps): adopt MCP SDK v2 packages for 2026-07-28
Jul 17, 2026
1af8aa3
refactor(tools): migrate tool layer to @modelcontextprotocol/server
Jul 17, 2026
fe1e181
refactor(runtime): adopt createMcpHandler and serveStdio for 2026-07-28
Jul 17, 2026
772f9ab
test(unit): update tests for MCP SDK v2 handler wiring
Jul 17, 2026
8791e81
test(e2e): exercise MCP 2026-07-28 protocol in demo smoke test
Jul 17, 2026
3d363c6
build(deps): upgrade zod to v4 for MCP SDK v2 compatibility
Jul 17, 2026
bf84dbf
fix(tools): wrap inputSchema with z.object for SDK v2 registerTool
Jul 17, 2026
2217cc6
test(unit): align tool tests with ServerContext and Zod v4 schemas
Jul 17, 2026
a6e77bd
docs: document Harbor 1.0 MCP 2026-07-28 protocol and release notes
Jul 17, 2026
bc86d54
build(deps): regenerate package-lock after MCP SDK v2 cherry-pick
Aug 26, 2026
b2f1249
feat(meta): response _meta with serverInfo + app-metadata channel
Aug 26, 2026
b72516f
feat(meta): advisory request _meta reader for protocol version/client…
Aug 26, 2026
faa6b5c
feat(discover): advertise real capabilities + conservative cache hints
Aug 26, 2026
d272f8f
feat(http): surface normalized MCP request identity from headers
Aug 26, 2026
a4b3c78
feat(auth): enforce token resource binding on OAuth 2.1 path (§17)
Aug 26, 2026
e98d76f
feat(http): advertise single supported protocol version on /health (§20)
Aug 26, 2026
f542678
docs(mcp): compatibility matrix + OAuth 2.1 resource-binding requirement
Aug 26, 2026
af62fe1
test(e2e): live OAuth 2.1 resource-binding coverage via billing api_e…
Aug 26, 2026
cd8c3e0
ci: bump actions to v5 and clear high-severity npm audit vulns
Aug 27, 2026
6e74e72
docs(changelog): record oauth-2.1 resource-binding breaking change
Aug 27, 2026
1ce0d6b
updated with latest stable sdk and fixes
Sep 13, 2026
a3c60f0
added new tests for real auth
Sep 13, 2026
e935971
updated gitignore
Sep 13, 2026
13ba342
fixed postman collection auth defaults
Sep 13, 2026
3bee88c
add irctc demo service example
Sep 13, 2026
0dc3286
Merge branch 'main' into feature/harbor-1.0-mcp-2026-07-28
vijaydeepsinha Sep 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

- uses: actions/setup-node@v4.4.0
- uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
with:
node-version: '22'
cache: 'npm'
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -39,3 +39,5 @@ coverage/
.internal/
reviews/
__pycache__/
pr_reviews/
postman/
19 changes: 17 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,32 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm

---

## [Unreleased]
## [1.0.0] — Unreleased

> 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:** 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:** 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.
- 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
Expand Down
30 changes: 27 additions & 3 deletions adapters/auth/strategies/jwt-validation.strategy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string>
Expand All @@ -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), {
Expand All @@ -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<string, unknown>, 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')
Expand Down
20 changes: 18 additions & 2 deletions adapters/auth/strategies/oauth-discovery.strategy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,19 @@ 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
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<string, string>
Expand All @@ -27,6 +36,13 @@ 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.
requireResourceBindingAudience(
config.audience,
'OAuth 2.1 auth requires `audience` (resource binding) under MCP 2026-07-28'
)
this.config = config
this.logger = config.logger
}
Expand Down Expand Up @@ -54,7 +70,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 } : {}),
Expand Down
33 changes: 33 additions & 0 deletions adapters/auth/strategies/oauth-introspection.strategy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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'
Expand All @@ -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)
Expand Down Expand Up @@ -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<string, unknown> = {}
Expand Down
19 changes: 19 additions & 0 deletions adapters/auth/strategies/resource-binding.ts
Original file line number Diff line number Diff line change
@@ -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)
}
}
50 changes: 50 additions & 0 deletions core/constants.ts
Original file line number Diff line number Diff line change
@@ -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 = {
Expand Down Expand Up @@ -103,6 +110,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'
Expand Down Expand Up @@ -182,3 +194,41 @@ 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). 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'
6 changes: 3 additions & 3 deletions core/types/config.types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ 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<string, string>; metadataMapping?: Record<string, string> }
| { type: 'jwt-validation'; jwksUri: string; issuer: string; audience?: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record<string, string> }
| { type: 'oauth-2.1'; authorizationServer: string; audience?: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record<string, string>; discoveryTimeoutMs?: 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<string, string>; metadataMapping?: Record<string, string>; audience?: string }
| { type: 'jwt-validation'; jwksUri: string; issuer: string; audience: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record<string, string> }
| { type: 'oauth-2.1'; authorizationServer: string; audience: string; clockToleranceSec?: number; scopeClaim?: string; metadataMapping?: Record<string, string>; discoveryTimeoutMs?: number }

export type ServiceCircuitBreakerConfig =
| { type: 'noop' }
Expand Down
Loading