@frontmcp/skills 1.3.0 → 1.4.1

package/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md

@@ -2,18 +2,25 @@
 name: remote-enterprise-oauth
 reference: configure-auth-modes
 level: advanced
-description: 'Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.'
+description: 'Proxy authentication to one mandatory upstream IdP, mint a FrontMCP session, and read the upstream token in tools.'
 tags: [config, oauth, auth, redis, remote, auth-modes]
 features:
-  - "Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server"
+  - "Using `mode: 'remote'` to proxy authentication to a single mandatory upstream IdP"
   - 'Loading `clientId` and `clientSecret` from environment variables (never hardcoded)'
   - 'Configuring Redis-backed token storage for production persistence'
-  - 'Full OAuth flow: clients are redirected to the provider and return with an authorization code'
+  - '`GET /oauth/authorize` redirects straight to the upstream IdP (no in-tree login page)'
+  - 'Session identity (sub/email/name) is derived from the upstream user'
+  - 'Tools read the upstream token via `this.orchestration.getToken(providerId)`'
 ---
 
 # Remote Enterprise OAuth
 
-Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.
+Proxy authentication to one mandatory upstream IdP, mint a FrontMCP session, and read the upstream token in tools.
+
+FrontMCP runs a local OAuth 2.1 server: `GET /oauth/authorize` redirects straight
+to the IdP (no FrontMCP login page), exchanges the returned code, stores the
+upstream tokens encrypted in Redis, derives the session identity from the upstream
+user, and mints its own HS256 session token.
 
 ## Code
 
@@ -23,23 +30,34 @@ import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'query_data',
-  description: 'Query enterprise data warehouse',
+  description: 'Query the enterprise data warehouse on behalf of the user',
   inputSchema: { sql: z.string() },
   outputSchema: { rows: z.array(z.record(z.string(), z.unknown())), rowCount: z.number() },
 })
 class QueryDataTool extends ToolContext {
   async execute(input: { sql: string }) {
+    // The upstream IdP token is stored server-side (encrypted) and read by id.
+    // 'enterprise-idp' is providerConfig.id below (defaults to the provider host).
+    const token = await this.orchestration.tryGetToken('enterprise-idp');
+    if (!token) {
+      // Once the upstream token expires the user must re-authenticate
+      // (upstream auto-refresh is not yet wired).
+      throw new Error('Upstream token unavailable — please re-authenticate');
+    }
+    // A real tool would call the warehouse API with `token`.
     return { rows: [{ id: 1, name: 'example' }], rowCount: 1 };
   }
 }
 
-@App({
-  name: 'enterprise-api',
+@FrontMcp({
+  info: { name: 'enterprise-server', version: '1.0.0' },
+  apps: [{ name: 'enterprise-api', tools: [QueryDataTool] }],
   auth: {
     mode: 'remote',
     provider: 'https://auth.example.com',
-    clientId: process.env['OAUTH_CLIENT_ID']!,
+    clientId: process.env['OAUTH_CLIENT_ID']!, // pre-registered (DCR not yet wired)
     clientSecret: process.env['OAUTH_CLIENT_SECRET'],
+    scopes: ['openid', 'profile', 'email'],
     tokenStorage: {
       redis: {
         host: process.env['REDIS_HOST'] ?? 'redis.internal',
@@ -47,19 +65,8 @@ class QueryDataTool extends ToolContext {
         password: process.env['REDIS_PASSWORD'],
       },
     },
-  },
-  tools: [QueryDataTool],
-})
-class EnterpriseApi {}
-
-@FrontMcp({
-  info: { name: 'enterprise-server', version: '1.0.0' },
-  apps: [EnterpriseApi],
-  redis: {
-    provider: 'redis',
-    host: process.env['REDIS_HOST'] ?? 'redis.internal',
-    port: Number(process.env['REDIS_PORT'] ?? 6379),
-    password: process.env['REDIS_PASSWORD'],
+    // Pin a stable provider id (and override endpoints for non-standard IdPs).
+    providerConfig: { id: 'enterprise-idp' },
   },
 })
 class Server {}
@@ -67,10 +74,17 @@ class Server {}
 
 ## What This Demonstrates
 
-- Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server
+- Using `mode: 'remote'` to proxy authentication to a single mandatory upstream IdP
 - Loading `clientId` and `clientSecret` from environment variables (never hardcoded)
 - Configuring Redis-backed token storage for production persistence
-- Full OAuth flow: clients are redirected to the provider and return with an authorization code
+- `GET /oauth/authorize` redirects straight to the upstream IdP (no in-tree login page)
+- Session identity (sub/email/name) is derived from the upstream user
+- Tools read the upstream token via `this.orchestration.getToken(providerId)`
+
+## Not Yet Wired
+
+- **Dynamic Client Registration** (`providerConfig.dcrEnabled`): a pre-registered `clientId` is required.
+- **Upstream token auto-refresh**: when the upstream access token expires the user must re-authenticate (FrontMCP's own session token still refreshes via the `refresh_token` grant).
 
 ## Related
 

package/catalog/frontmcp-config/examples/configure-http/custom-http-routes.md

@@ -0,0 +1,98 @@
+---
+name: custom-http-routes
+reference: configure-http
+level: intermediate
+description: 'Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes.'
+tags: [config, http, routes, custom, webhook, download, auth]
+features:
+  - 'Registering custom HTTP endpoints with `http.routes` — no tool/resource/prompt needed'
+  - 'A POST endpoint that validates a user-entered secret server-side (the `/connect-env` pattern)'
+  - 'Overriding the default `application/json` Content-Type for binary/HTML delivery'
+  - 'Gating a route behind the MCP `session:verify` flow with `auth: true`'
+  - 'Avoiding reserved paths (`/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, `/metrics`)'
+---
+
+# Custom HTTP Routes
+
+Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes.
+
+## Code
+
+```typescript
+// src/server.ts
+import { App, FrontMcp, type ServerRequest, type ServerResponse } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'routes-server', version: '1.0.0' },
+  apps: [MyApp],
+  auth: { mode: 'public', sessionTtl: 3600, anonymousScopes: ['anonymous'] },
+  http: {
+    port: Number(process.env['PORT']) || 3000,
+    routes: [
+      // 1. Public binary download. The adapter defaults responses to JSON, so a
+      //    binary/HTML handler MUST set its own Content-Type before sending.
+      {
+        method: 'GET',
+        path: '/download/:id',
+        handler: (req: ServerRequest, res: ServerResponse) => {
+          res.setHeader('Content-Type', 'application/pdf');
+          res.status(200).send(loadPdfBytes(req.params['id']));
+        },
+      },
+
+      // 2. The `/connect-env` pattern: validate a user-entered secret against a
+      //    backend WITHOUT finalizing an OAuth exchange. The shared
+      //    express.json() middleware parses req.body (subject to http.bodyLimit).
+      {
+        method: 'POST',
+        path: '/connect-env',
+        handler: async (req: ServerRequest, res: ServerResponse) => {
+          const secret = (req.body as { secret?: string } | undefined)?.secret;
+          if (!secret || !(await isValidSecret(secret))) {
+            res.status(400).json({ ok: false, error: 'invalid secret' });
+            return;
+          }
+          res.status(200).json({ ok: true, connected: true });
+        },
+      },
+
+      // 3. Auth-gated webhook. With auth: true the request runs the MCP
+      //    session:verify flow first; req.authSession is populated on success.
+      {
+        method: 'POST',
+        path: '/webhooks/billing',
+        auth: true,
+        handler: (req: ServerRequest, res: ServerResponse) => {
+          res.status(202).json({ accepted: true, user: req.authSession?.user?.sub });
+        },
+      },
+    ],
+  },
+})
+class Server {}
+
+declare function loadPdfBytes(id: string): Buffer;
+declare function isValidSecret(secret: string): Promise<boolean>;
+```
+
+## What This Demonstrates
+
+- Registering custom HTTP endpoints with `http.routes` — no tool/resource/prompt needed
+- A POST endpoint that validates a user-entered secret server-side (the `/connect-env` pattern)
+- Overriding the default `application/json` Content-Type for binary/HTML delivery
+- Gating a route behind the MCP `session:verify` flow with `auth: true`
+- Avoiding reserved paths (`/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, `/metrics`)
+
+## Gotchas
+
+- Reserved paths fail-fast at startup: the resolved MCP entry path and its `/sse` + `/message` siblings, anything under `/oauth/*` and `/.well-known/*`, and `/health` + `/metrics`.
+- For large payloads, prefer a custom GET route + a `resource_link` over a `@Resource` — a resource rides the JSON-RPC channel and is not out-of-band.
+- A custom `hostFactory` owns its Express app (body limits, CORS, Content-Type defaults); `http.routes` and `bodyLimit` are consumed only by the built-in `ExpressHostAdapter`.
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-auth-modes` for how `auth: true` behaves under each auth mode

package/catalog/frontmcp-config/examples/configure-skills-http/audit-log-redis.md

@@ -19,7 +19,7 @@ Production-grade audit log with the Redis-backed StorageAdapterAuditStore and th
 
 ```typescript
 // src/server.ts — must be an ES module (`"type": "module"` in package.json,
-// or `.mts` extension) so the top-level `await createStorageAdapter(...)`
+// or `.mts` extension) so the top-level `await createStorage(...)`
 // below is allowed. CommonJS consumers should wrap the bootstrap inside an
 // `async function init() { ... }` and await it before constructing the
 // FrontMcp class.
@@ -33,7 +33,7 @@ import {
   StorageAdapterAuditStore,
 } from '@frontmcp/adapters/skills';
 import { FrontMcp } from '@frontmcp/sdk';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
 import { MainApp } from './main.app';
 
@@ -48,11 +48,16 @@ setSkillAuditFactory(() => ({
   MemoryAuditStore,
 }));
 
-const auditStorage = await createStorageAdapter({
-  provider: 'redis',
-  host: process.env.REDIS_HOST!,
-  port: 6379,
-  keyPrefix: 'mcp:skill-audit:',
+// createStorage() returns a RootStorage, which is a StorageAdapter. Note this
+// is the @frontmcp/utils storage-adapter config shape (`redis.config`), which
+// is distinct from the SDK `RedisOptions` (`{ provider, host, port }`) used by
+// `@FrontMcp({ redis })` and `skillsConfig.cache.redis` below.
+const auditStorage = await createStorage({
+  type: 'redis',
+  redis: {
+    config: { host: process.env.REDIS_HOST!, port: 6379 },
+    keyPrefix: 'mcp:skill-audit:',
+  },
 });
 
 // Constructor signature: new Rs256AuditSigner(privateJwk, keyId).
@@ -86,9 +91,12 @@ export default class ProductionServer {}
 ```typescript
 // scripts/verify-audit-chain.ts — run in CI
 import { defaultAuditSignatureVerifier, StorageAdapterAuditStore, verifyChain } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
-const storage = await createStorageAdapter({ provider: 'redis', host: process.env.REDIS_HOST!, port: 6379 });
+const storage = await createStorage({
+  type: 'redis',
+  redis: { config: { host: process.env.REDIS_HOST!, port: 6379 } },
+});
 const store = new StorageAdapterAuditStore(storage);
 const records = await store.iterate();
 

package/catalog/frontmcp-config/references/configure-auth-modes.md

@@ -29,64 +29,127 @@ auth: {
   mode: 'transparent',
   provider: 'https://auth.example.com',
   expectedAudience: 'my-api',
-  clientId: 'my-client-id',
+  // clientId is OPTIONAL and unused for pure JWT validation — transparent mode
+  // never runs an OAuth code exchange, it only verifies tokens against the
+  // provider's JWKS. Omit it unless you have a specific reason to set it.
 }
 ```
 
 **Use when:** Behind an API gateway or reverse proxy that handles auth.
 
+> Transparent also accepts `allowAnonymous` (default `false`) + `anonymousScopes` (default `['anonymous']`) to admit tokenless requests as anonymous, and `requiredScopes` to reject tokens missing a scope. `expectedAudience` is shared across transparent/local/remote, not transparent-only.
+
 ## Local Mode
 
-Server signs its own JWT tokens. Full control over token lifecycle.
+Built-in OAuth 2.1 server that signs its own JWT tokens. Full control over token lifecycle.
 
 ```typescript
 auth: {
   mode: 'local',
   local: {
-    issuer: 'my-server',
+    issuer: 'https://mcp.example.com', // optional; request-host-derived otherwise
   },
   expectedAudience: 'my-api',
-  tokenStorage: { redis: { host: process.env['REDIS_HOST'] ?? 'localhost', port: 6379 } },
-  consent: { enabled: true },
-  incrementalAuth: { enabled: true },
+  // 'memory' (default, lost on restart) | { sqlite: { path } } | { redis: { ... } }
+  tokenStorage: { sqlite: { path: './data/auth.sqlite' } },
+  consent: { enabled: true }, // tool-selection screen at login + call-time enforcement
+  incrementalAuth: { enabled: true }, // app-level gating + progressive expansion (opt-in)
 }
 ```
 
-**Use when:** Standalone servers with full auth control, development with local OAuth.
+Signing is **HS256 with a symmetric `JWT_SECRET`** (no key pair). Set a stable `JWT_SECRET` or tokens are invalidated on every restart. For a single operator (e.g. Claude Code), add `requireEmail: false` to skip the email prompt (a stable `sub` is derived from `anonymousSubject`, default `'local-operator'`).
+
+Local mode also accepts `allowDefaultPublic` (default `false` — set `true` to admit tokenless requests as anonymous instead of returning 401), `anonymousScopes` (default `['anonymous']` — scopes for those anonymous sessions), and `expectedAudience` (reject tokens minted for a different `aud`).
+
+**Progressive / incremental authorization** (opt-in via `incrementalAuth`): when enabled, the minted token carries an `authorized_apps` claim and a `tools/call` for an app NOT in that claim resolves to a `CallToolResult` with `isError: true` and `_meta.code === 'AUTHORIZATION_REQUIRED'` (fields: `authorization_required: true`, `app`, `tool`, `auth_url`, `required_scopes`, `session_mode`, `supports_incremental`). The client declares the initial grant on `/oauth/authorize?…&apps=crm` (omit `apps` to grant all apps) and expands it later via an incremental authorize `…&mode=incremental&app=slack&apps=crm` — the new token's claim is the **union** of the prior apps plus the target (the user identity and already-granted apps are preserved; upstream tokens stay server-side). Without an `incrementalAuth` block, no claim is minted and there is **no** app-level gating (allow-all preserved). `consent` (tool-level) and `incrementalAuth` (app-level) are independent.
+
+To collect and verify your own credentials, add a declarative `login` (custom page fields / title / subject strategy) and an `authenticate(input, ctx)` verifier that returns `{ ok: true, sub?, claims? }` (custom claims are embedded in the token; reserved claims are stripped) or `{ ok: false, message }` (re-renders the login page; no code issued). Both are optional and default to the built-in email login. See `configure-auth.md` for a full example.
+
+To orchestrate **multiple upstream OAuth providers** (GitHub, Slack, Jira, …) declare a `providers` array — FrontMCP federates them at `/oauth/authorize`, refuses to mint a JWT until `federatedAuth.minProviders` (default `1`) are linked, stores each provider's tokens encrypted server-side, and exposes them to tools via `this.orchestration.getToken(id)`:
+
+```typescript
+auth: {
+  mode: 'local',
+  providers: [
+    { id: 'github', authorizeUrl: '…', tokenUrl: '…', clientId: '…', scopes: ['repo'] },
+    { id: 'slack', authorizeUrl: '…', tokenUrl: '…', clientId: '…' },
+  ],
+  federatedAuth: { minProviders: 1, requiredProviders: ['github'] }, // no JWT until linked
+}
+```
+
+See `configure-auth.md` → "Multi-provider orchestration" for the full provider schema and the `this.orchestration` tool API.
+
+**Use when:** Standalone servers with full auth control, development with local OAuth, orchestrating several upstream OAuth providers behind one MCP server.
 
 ## Remote Mode
 
-Server delegates to an upstream auth orchestrator for token management.
+FrontMCP runs a local OAuth 2.1 server that **proxies user authentication to one
+mandatory upstream IdP**. `GET /oauth/authorize` redirects **straight to the
+upstream IdP** — there is no FrontMCP login page and no provider-selection page.
+After the IdP returns to `/oauth/provider/{id}/callback`, FrontMCP exchanges the
+code, stores the upstream tokens encrypted (server-side), derives the session
+identity (`sub`/`email`/`name`) from the **upstream user**, and mints its own
+HS256 session token. Tools read the upstream token via
+`this.orchestration.getToken('<provider-id>')`.
 
 ```typescript
 auth: {
   mode: 'remote',
   provider: 'https://auth.example.com',
-  clientId: 'my-client-id',
+  clientId: 'my-client-id', // pre-registered (DCR not yet wired)
   clientSecret: process.env.AUTH_SECRET,
+  scopes: ['openid', 'profile', 'email'],
   tokenStorage: { redis: { host: process.env['REDIS_HOST'] ?? 'localhost', port: 6379 } },
+  // The provider id defaults to the `provider` hostname; pin a stable id (and/or
+  // override non-standard endpoints) with providerConfig:
+  providerConfig: { id: 'idp' },
 }
 ```
 
-**Use when:** Enterprise deployments with centralized identity management.
+Endpoints are derived from `provider` using standard OIDC paths
+(`/authorize`, `/token`, `/userinfo`, `/.well-known/jwks.json`). For
+non-standard IdPs, override them with
+`providerConfig.{authEndpoint,tokenEndpoint,userInfoEndpoint,jwksUri}`.
+
+**Deferred (not yet wired):** upstream **Dynamic Client Registration**
+(`providerConfig.dcrEnabled` / `registrationEndpoint`) — a pre-registered
+`clientId` is required; and upstream **token auto-refresh** — once the upstream
+access token expires the user must re-authenticate (FrontMCP's own session token
+still refreshes via the `refresh_token` grant).
+
+**Use when:** Enterprise deployments delegating user authentication to a single
+centralized IdP that may not support DCR, while keeping FrontMCP-issued sessions,
+upstream-token access in tools, and an optional consent layer.
 
 ## Comparison Table
 
-| Feature          | Public        | Transparent     | Local       | Remote       |
-| ---------------- | ------------- | --------------- | ----------- | ------------ |
-| Token issuance   | Anonymous JWT | None (upstream) | Self-signed | Orchestrator |
-| Token refresh    | No            | No              | Yes         | Yes          |
-| PKCE support     | No            | No              | Yes         | Yes          |
-| Credential vault | No            | No              | Yes         | Yes          |
-| Consent flow     | No            | No              | Optional    | Optional     |
-| Federated auth   | No            | No              | Optional    | Optional     |
+| Feature                  | Public        | Transparent     | Local                           | Remote                            |
+| ------------------------ | ------------- | --------------- | ------------------------------- | --------------------------------- |
+| Token issuance           | Anonymous JWT | None (upstream) | Self-signed (HS256)             | Self-signed (HS256)               |
+| Signing                  | HS256 secret  | Upstream JWKS   | HS256 secret (`JWT_SECRET`)     | HS256 secret (`JWT_SECRET`)       |
+| Session-token refresh    | No            | No              | Yes                             | Yes                               |
+| Upstream-token refresh   | n/a           | n/a             | On-demand (when wired)          | Not yet wired (re-auth on expiry) |
+| Identity source          | Anonymous     | Upstream token  | Login form / `authenticate()`   | Upstream IdP user                 |
+| PKCE support             | No            | No              | Yes                             | Yes                               |
+| Token persistence        | n/a           | n/a             | memory / sqlite / redis         | memory / sqlite / redis           |
+| Consent (tool selection) | No            | No              | Optional (screen + enforcement) | Optional (screen + enforcement)   |
+| Upstream OAuth providers | No            | No              | 0..N (declared `providers[]`)   | Exactly 1 (mandatory)             |
+
+> "Remote" still issues its own HS256 session token to the MCP client; it delegates **user authentication** to a single upstream IdP rather than delegating token signing. `GET /oauth/authorize` redirects straight to that IdP (no in-tree login page), and tools read the upstream token via `this.orchestration.getToken(id)`.
 
 ## Examples
 
-| Example                                                                                        | Level        | Description                                                                                 |
-| ---------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
-| [`local-self-signed-tokens`](../examples/configure-auth-modes/local-self-signed-tokens.md)     | Intermediate | Configure a server that signs its own JWT tokens with consent and incremental auth enabled. |
-| [`remote-enterprise-oauth`](../examples/configure-auth-modes/remote-enterprise-oauth.md)       | Advanced     | Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.  |
-| [`transparent-jwt-validation`](../examples/configure-auth-modes/transparent-jwt-validation.md) | Basic        | Validate externally-issued JWTs without managing token lifecycle on the server.             |
+| Example                                                                                                        | Level        | Description                                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`local-minimal`](../examples/configure-auth-modes/local-minimal.md)                                           | Basic        | Stand up the built-in local OAuth 2.1 server with the minimum configuration: HS256 signing via JWT_SECRET and in-memory token storage.                                                                      |
+| [`local-self-signed-tokens`](../examples/configure-auth-modes/local-self-signed-tokens.md)                     | Intermediate | Configure a local-mode server that signs its own HS256 JWTs and persists auth state across restarts with SQLite or Redis.                                                                                   |
+| [`local-single-operator`](../examples/configure-auth-modes/local-single-operator.md)                           | Basic        | Run local mode for a single operator (e.g. Claude Code) by skipping the email prompt and minting a stable anonymous subject.                                                                                |
+| [`local-consent-enforcement`](../examples/configure-auth-modes/local-consent-enforcement.md)                   | Intermediate | Enable consent in local mode to render a tool-selection screen at login and enforce the chosen tools at call time, keeping essential tools always available via excludedTools.                              |
+| [`local-behind-tunnel`](../examples/configure-auth-modes/local-behind-tunnel.md)                               | Intermediate | Expose a local-mode server through a tunnel or TLS proxy by aligning the token issuer with the public URL clients actually reach.                                                                           |
+| [`local-multi-provider-orchestration`](../examples/configure-auth-modes/local-multi-provider-orchestration.md) | Advanced     | Orchestrate multiple upstream OAuth providers (GitHub + Slack) in local mode, gate the JWT until they are linked, and read downstream tokens in tools via this.orchestration.                               |
+| [`local-dcr-control`](../examples/configure-auth-modes/local-dcr-control.md)                                   | Intermediate | Lock down the built-in Dynamic Client Registration endpoint with the auth.dcr control surface: disable open registration, allowlist redirect URIs and client ids, and seed a pre-registered trusted client. |
+| [`remote-enterprise-oauth`](../examples/configure-auth-modes/remote-enterprise-oauth.md)                       | Advanced     | Proxy authentication to one mandatory upstream IdP, mint a FrontMCP session, and read the upstream token in tools.                                                                                          |
+| [`transparent-jwt-validation`](../examples/configure-auth-modes/transparent-jwt-validation.md)                 | Basic        | Validate externally-issued JWTs without managing token lifecycle on the server.                                                                                                                             |
 
 > See all examples in [`examples/configure-auth-modes/`](../examples/configure-auth-modes/)