@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/.mcp-broker.example/README.md

@@ -7,6 +7,11 @@ broker, then adapt to your needs:
 cp -r .mcp-broker.example .mcp-broker
 ```
 
+Property-by-property educational guides:
+
+- [English](CONFIGURATION-EN.md)
+- [Français](CONFIGURATION-FR.md)
+
 ## Layout
 
 ```
@@ -26,7 +31,7 @@ cp -r .mcp-broker.example .mcp-broker
     └── index.html
 ```
 
-A ready-made instance UI lives at [`node/web/`](../web/) — point a `www`
+A ready-made instance UI lives at [`node/web/`](../web/), point a `www`
 mount at it (`"dir": "../web"`) to serve it. See [`node/web/README.md`](../web/README.md).
 
 ## Path resolution
@@ -36,14 +41,14 @@ config file** (i.e. `.mcp-broker/`). So `"certs/cert.pem"` in the config
 points at `.mcp-broker/certs/cert.pem`. The folder is self-contained.
 
 Env vars (`MCP_BROKER_TLS_CERT`, `MCP_BROKER_WWW_DIR`, ...) are still
-resolved against `process.cwd()` — they are the deploy-time override
+resolved against `process.cwd()`: they are the deploy-time override
 mechanism and not tied to the config file's location.
 
 ## `.mcpb` bundles
 
 `mcpbBundles` entries load local `.mcpb` bundles as stdio provider slots.
 Each bundle is verified against a **detached signature** before it is
-unpacked and run — the broker never spawns an unverified bundle.
+unpacked and run: the broker never spawns an unverified bundle.
 
 1. Generate a signing key pair (once):
    `node ../scripts/sign-bundle.mjs keygen bundles`

package/.mcp-broker.example/config.json

@@ -22,6 +22,92 @@
         ]
     },
 
+    "auth": {
+        "enabled": true,
+        "publicBaseUrl": "https://mcp.factory.local",
+        "authorizationServers": [
+            "https://identity.factory.local"
+        ],
+        "jwks": "https://identity.factory.local/.well-known/jwks.json",
+        "requiredScopes": ["mcp:call"],
+        "perSlotScopes": {
+            "_broker": ["broker:admin"]
+        },
+        "subjectMapping": {
+            "userClaim": "sub",
+            "groupClaims": ["groups"],
+            "clientClaim": "client_id"
+        },
+        "roles": {
+            "viewer": {
+                "capabilities": [
+                    "mcp.resources.read",
+                    "mcp.tools.list",
+                    "mcp.prompts.read"
+                ]
+            },
+            "maintenance": {
+                "inherits": ["viewer"],
+                "capabilities": [
+                    "mcp.tools.call",
+                    "mcp.tools.diagnose",
+                    "mcp.tools.configure-analysis"
+                ]
+            },
+            "operator": {
+                "inherits": ["viewer"],
+                "capabilities": ["mcp.tools.operate"]
+            },
+            "administrator": {
+                "capabilities": ["*"]
+            }
+        },
+        "assignments": [
+            {
+                "id": "maintenance-area-a",
+                "subject": "group:maintenance-area-a",
+                "role": "maintenance",
+                "resource": "/enterprise-a/site-paris/area-a/**"
+            },
+            {
+                "id": "energy-team",
+                "subject": "group:energy-team",
+                "role": "viewer",
+                "resource": "/enterprise-a/site-paris/**"
+            }
+        ],
+        "denies": [
+            {
+                "id": "protect-critical-furnace",
+                "subject": "group:maintenance-area-a",
+                "capabilities": [
+                    "mcp.tools.configure-analysis",
+                    "mcp.tools.operate"
+                ],
+                "resource": "/enterprise-a/site-paris/area-a/line-2/cell-4/critical-furnace"
+            }
+        ],
+        "slotResources": {
+            "spoony-00452": "/enterprise-a/site-paris/area-a/line-3/cell-2/motor-7",
+            "site-energy": "/enterprise-a/site-paris"
+        },
+        "toolCapabilities": {
+            "get_electrical_state": "mcp.resources.read",
+            "diagnose_motor": "mcp.tools.diagnose",
+            "reset_baseline": "mcp.tools.configure-analysis",
+            "start_motor": "mcp.tools.operate"
+        },
+        "providerToolCapabilities": {
+            "/enterprise-a/site-paris/area-a/**": {
+                "start_motor": "mcp.tools.operate"
+            }
+        },
+        "audit": {
+            "logAllowed": false
+        },
+        "providerSecret": "change-me"
+    },
+
     "stdioUpstreams": [
         {
             "name":    "fs",

package/README.md

@@ -32,7 +32,7 @@ The broker starts on `http://localhost:3000` by default.
 
 Two sources, env vars **always win** over the file. The file is the static baseline you ship with the broker; env vars are deploy-specific overrides.
 
-### Option A — `.mcp-broker/` folder (recommended)
+### Option A: `.mcp-broker/` folder (recommended)
 
 Drop a `.mcp-broker/` folder next to where you launch the broker. Paths
 inside `config.json` are resolved against this folder, so it stays
@@ -79,7 +79,7 @@ cp -r node_modules/@cyanmycelium/mcp-broker/.mcp-broker.example .mcp-broker
 
 Full reference (every field, defaults, recipes, grammar overrides): **[docs/config.md](docs/config.md)**.
 
-### Option B — Environment variables
+### Option B: Environment variables
 
 | Variable | Default | Notes |
 |---|---|---|
@@ -96,6 +96,85 @@ Full reference (every field, defaults, recipes, grammar overrides): **[docs/conf
 | `MCP_BROKER_TLS_KEY` | (unset) | Path to a PEM private key. Enables HTTPS/WSS |
 | `MCP_BROKER_PROTOCOL` | auto | `http` forces plain, `https` forces TLS, unset auto-detects from cert+key |
 | `MCP_BROKER_STDIO_PROVIDER` | (unset) | When set, bridge stdin/stdout JSON-RPC to this provider (Claude Desktop integration) |
+| `MCP_BROKER_AUTH_ENABLED` | (unset) | `1` to turn on the OAuth 2.1 resource server (requires the three below) |
+| `MCP_BROKER_PUBLIC_BASE_URL` | (unset) | Public origin used to build canonical resource URIs, e.g. `https://mcp.example.com` |
+| `MCP_BROKER_JWKS` | (unset) | Authorization server's JWKS URL, used to verify token signatures |
+| `MCP_BROKER_ISSUER` | (unset) | Expected token issuer (defaults to the sole authorization server) |
+| `MCP_BROKER_PROVIDER_SECRET` | (unset) | Shared secret every provider must present to occupy a slot |
+
+## Authorization (OAuth 2.1)
+
+By default the broker performs **no** authentication. That is fine behind a
+trusted network boundary, but do not expose it publicly as-is. Turn on the OAuth 2.1
+resource server to require a bearer token on every client request, authenticate
+providers, and filter the `_all` aggregate per caller.
+
+Enabled via the `auth` config block (or env vars). Minimal `.mcp-broker/config.json`:
+
+The resource paths below use a compact ISA-95 / IEC 62264-aligned industrial
+profile. The engine remains domain-neutral, does not claim full ISA-95
+compliance, and can map UMD-style namespaces through `slotResources`.
+
+```json
+{
+    "auth": {
+        "enabled": true,
+        "publicBaseUrl": "https://mcp.example.com",
+        "authorizationServers": ["https://auth.example.com"],
+        "jwks": "https://auth.example.com/.well-known/jwks.json",
+        "requiredScopes": ["mcp:call"],
+        "perSlotScopes": { "_broker": ["broker:admin"] },
+        "subjectMapping": {
+            "userClaim": "sub",
+            "groupClaims": ["groups"],
+            "clientClaim": "client_id"
+        },
+        "roles": {
+            "viewer": {
+                "capabilities": ["mcp.tools.list", "mcp.resources.read"]
+            },
+            "maintenance": {
+                "inherits": ["viewer"],
+                "capabilities": ["mcp.tools.diagnose"]
+            }
+        },
+        "assignments": [
+            {
+                "subject": "group:maintenance-site-a",
+                "role": "maintenance",
+                "resource": "/enterprise/site-a/**"
+            }
+        ],
+        "slotResources": {
+            "motor-7": "/enterprise/site-a/area-a/line-3/cell-2/motor-7"
+        },
+        "toolCapabilities": {
+            "diagnose_motor": "mcp.tools.diagnose"
+        },
+        "providerSecret": "change-me"
+    }
+}
+```
+
+With this on:
+
+- `POST /<slot>/mcp` (and `/sse`, `/messages`, `ws://…/<slot>`) require
+  `Authorization: Bearer <token>`; the token's audience must be
+  `https://mcp.example.com/<slot>/mcp`.
+- Clients discover the authorization server via
+  `GET /.well-known/oauth-protected-resource/<slot>/mcp` (RFC 9728), advertised
+  in the `401` challenge.
+- Providers must present `providerSecret` (via `X-Provider-Token` or
+  `Authorization: Bearer`) to connect to `/provider/<slot>` or `/providers`.
+- `_all` only shows providers allowed by the caller's hierarchical policy.
+- Explicit denies override inherited role grants.
+- Structured provider principals can publish only inside their allowed resource
+  namespace.
+
+Full model, flows, scopes, and endpoints: **[../docs/authorization.md](../docs/authorization.md)**.
+Roles, resource paths, denies, and migration:
+**[../docs/hierarchical-authorization.md](../docs/hierarchical-authorization.md)**.
+Config field reference: **[docs/config.md](docs/config.md#auth-oauth-21-authorization)**.
 
 ## Programmatic API
 
@@ -111,12 +190,52 @@ const broker = new WsTunnelBuilder()
     .withStdioUpstream("my-server", "node", ["./my-server.js"])
     // Optional: serve a dev harness at /
     .withStaticMount("/", "/abs/path/to/www")
+    // Optional: enable the OAuth 2.1 resource server + provider auth
+    .withJwtAuth({
+        publicBaseUrl: "https://mcp.example.com",
+        authorizationServers: ["https://auth.example.com"],
+        jwksUri: "https://auth.example.com/.well-known/jwks.json",
+        requiredScopes: ["mcp:call"],
+        roles: {
+            viewer: { capabilities: ["mcp.tools.list"] },
+        },
+        assignments: [
+            {
+                subject: "group:operators",
+                role: "viewer",
+                resource: "/enterprise/site-a/**",
+            },
+        ],
+        subjectMapping: { groupClaims: ["groups"] },
+    })
+    .withProviderSecret(process.env.PROVIDER_SECRET!)
     .build();
 
 await broker.start();
 ```
 
-All builder methods are documented inline. The full options interface is `WsTunnelOptions`, also exported.
+All builder methods are documented inline. The full options interface is
+`IWsTunnelOptions`, also exported. Use `withAuthorizationPolicy` for a
+standalone policy configuration, `withPolicyEngine` for a custom engine, and
+`withSlotResourceResolver` for a custom namespace mapping. For a custom token
+validator (for example RFC 7662 introspection) or provider authenticator, use
+`withAuth(resolvedAuth)` or `withProviderAuth(authenticator)` with your own
+`ITokenValidator` or `IProviderAuthenticator`.
+
+## Interactive OAuth demo
+
+The bundled [OAuth Policy Lab](web/demos/oauth-lab/) runs a complete local
+Authorization Code and PKCE flow with signed JWTs, JWKS validation,
+audience-bound tokens, hierarchical policies, explicit denies, and a live
+audit:
+
+```sh
+npm run demo:oauth
+```
+
+The page opens at `http://127.0.0.1:3001/demos/oauth-lab/`. See the
+[demo README](web/demos/oauth-lab/README.md) for its identities, policy matrix,
+and automated smoke test.
 
 ## TLS for local development
 

package/dist/bin.d.ts

@@ -1,2 +1 @@
 #!/usr/bin/env node
-export {};