@silkweave/auth 2.6.1 → 3.0.0

package/README.md

@@ -1,6 +1,9 @@
 # @silkweave/auth
 
-OAuth 2.1 authentication for [Silkweave](https://github.com/silkweave/silkweave) MCP servers. Acts as an OAuth proxy between MCP clients and upstream identity providers (Google, etc.), handling PKCE, refresh tokens, dynamic client registration (CIMD), and protected resource metadata (RFC 9728).
+Auth for [Silkweave](https://github.com/silkweave/silkweave) MCP servers, in two layers:
+
+- **Resource-server core** (the package root, `@silkweave/auth`) - the spec-required surface for an MCP server: bearer-token validation + protected resource metadata (RFC 9728). `jose`-only. Most servers need only this and delegate token issuance to an external IdP (Auth0/WorkOS/Stytch/Keycloak/Google).
+- **OAuth authorization server** (the opt-in subpath, `@silkweave/auth/oauth`) - a full OAuth 2.1 proxy between MCP clients and an upstream IdP: PKCE, refresh tokens, dynamic client registration (CIMD), and persistence stores. Import this only when you want Silkweave itself to *be* the authorization server, so a pure resource server never pulls the issuer machinery into its dependency graph.
 
 ## Install
 
@@ -8,12 +11,14 @@ OAuth 2.1 authentication for [Silkweave](https://github.com/silkweave/silkweave)
 pnpm add @silkweave/auth
 ```
 
+> The OAuth-proxy helpers (`google`, `createOAuthProxy`, `createJsonStore`/`createRedisStore`/`createMemoryStore`, `OAuthStore`) are imported from `@silkweave/auth/oauth`. Bearer validation (`validateToken`) and `generateProtectedResourceMetadata` - plus the `AuthConfig`/`AuthInfo`/`OAuthRequest`/`OAuthResponse`/`OAuthProvider` types - live at the package root.
+
 ## Quick Start with Google OAuth
 
 The `google()` helper returns a complete `AuthConfig` ready to pass to the `http()` adapter:
 
 ```typescript
-import { google, createJsonStore } from '@silkweave/auth'
+import { google, createJsonStore } from '@silkweave/auth/oauth'
 import { silkweave } from '@silkweave/core'
 import { http } from '@silkweave/mcp'
 
@@ -52,7 +57,7 @@ await silkweave({ name: 'my-server', description: 'My MCP Server', version: '1.0
 For providers other than Google, use `createOAuthProxy()` directly. It returns an `OAuthProvider` that implements the full OAuth 2.1 proxy flow:
 
 ```typescript
-import { createOAuthProxy } from '@silkweave/auth'
+import { createOAuthProxy } from '@silkweave/auth/oauth'
 
 const provider = createOAuthProxy({
   authorizeUrl: 'https://provider.example.com/authorize',
@@ -139,6 +144,36 @@ if (result.error) {
 console.log(result.auth?.clientId)
 ```
 
+### Recommended: front with an external IdP (resource-server only)
+
+The MCP 2026 spec direction is for servers to be **pure OAuth resource servers**
+that delegate token issuance to a dedicated authorization server. For most
+deployments, point `authorizationServers` at an external IdP (Auth0, WorkOS,
+Stytch, Keycloak, Google, ...), have `verifyToken` validate that IdP's JWTs (e.g.
+with `jose`'s `jwtVerify` against the IdP JWKS), and skip the `@silkweave/auth/oauth`
+proxy entirely:
+
+```typescript
+import { validateToken } from '@silkweave/auth'
+
+const auth = {
+  resourceUrl: 'https://mcp.example.com',
+  authorizationServers: ['https://idp.example.com'],
+  issuer: 'https://idp.example.com',     // RFC 9207 - bind the token to this issuer
+  audience: 'https://mcp.example.com',   // RFC 8707 - reject tokens minted for another resource
+  requiredScopes: ['mcp:tools'],         // advertised in the 403 step-up challenge (SEP-2350)
+  verifyToken: async (token) => {
+    const { payload } = await jwtVerify(token, JWKS, { issuer: 'https://idp.example.com', audience: 'https://mcp.example.com' })
+    return { token, clientId: payload.sub, scopes: String(payload.scope ?? '').split(' '), iss: payload.iss, aud: payload.aud, expiresAt: payload.exp }
+  }
+}
+```
+
+`validateToken` then enforces, in order: expiry, **issuer** binding (`issuer`),
+**audience** binding (`audience`, defaults to `resourceUrl`; set `false` to skip),
+and **required scopes** - emitting a `WWW-Authenticate` challenge with `scope="..."`
+on insufficient scope so the client knows what to step up to.
+
 ## Protected Resource Metadata (RFC 9728)
 
 Generate the `/.well-known/oauth-protected-resource` document for your server:
@@ -148,11 +183,13 @@ import { generateProtectedResourceMetadata } from '@silkweave/auth'
 
 const metadata = generateProtectedResourceMetadata(
   'https://my-server.example.com',
-  ['https://my-server.example.com']
+  ['https://idp.example.com'],
+  ['mcp:tools'] // optional scopes_supported - the adapters pass auth.requiredScopes here
 )
 // {
 //   resource: 'https://my-server.example.com',
-//   authorization_servers: ['https://my-server.example.com'],
+//   authorization_servers: ['https://idp.example.com'],
+//   scopes_supported: ['mcp:tools'],
 //   bearer_methods_supported: ['header']
 // }
 ```
@@ -166,7 +203,7 @@ The OAuth proxy needs persistent storage for auth codes, client registrations, P
 In-memory storage -- data is lost on restart. Good for development:
 
 ```typescript
-import { createMemoryStore } from '@silkweave/auth'
+import { createMemoryStore } from '@silkweave/auth/oauth'
 
 const store = createMemoryStore()
 ```
@@ -176,7 +213,7 @@ const store = createMemoryStore()
 Persists to a JSON file on disk. Suitable for single-process deployments:
 
 ```typescript
-import { createJsonStore } from '@silkweave/auth'
+import { createJsonStore } from '@silkweave/auth/oauth'
 
 const store = createJsonStore('oauth-store.json')
 ```
@@ -186,7 +223,7 @@ const store = createJsonStore('oauth-store.json')
 For production multi-process deployments. Accepts any Redis client with `get`/`set`/`del` methods (compatible with `ioredis` and `redis`):
 
 ```typescript
-import { createRedisStore } from '@silkweave/auth'
+import { createRedisStore } from '@silkweave/auth/oauth'
 import Redis from 'ioredis'
 
 const store = createRedisStore({
@@ -200,7 +237,7 @@ const store = createRedisStore({
 Implement the `OAuthStore` interface for your own backend:
 
 ```typescript
-import type { OAuthStore } from '@silkweave/auth'
+import type { OAuthStore } from '@silkweave/auth/oauth'
 
 const store: OAuthStore = {
   saveAuthCode(code, data) { /* ... */ },

package/build/index.d.mts

@@ -1,3 +1,4 @@
+import { a as OAuthRequest, i as OAuthProvider, n as VerifyToken, o as OAuthResponse, r as AuthInfo, t as AuthConfig } from "./types-BFhAEzlP.mjs";
 import { SilkweaveContext } from "@silkweave/core";
 
 //#region src/errors.d.ts
@@ -11,7 +12,7 @@ declare function insufficientScope(message?: string): AuthError;
 //#endregion
 //#region src/extract.d.ts
 declare function extractBearerToken(header: string | null | undefined): string | null;
-declare function buildWWWAuthenticate(error?: string, description?: string, resourceMetadataUrl?: string): string;
+declare function buildWWWAuthenticate(error?: string, description?: string, resourceMetadataUrl?: string, scope?: string): string;
 //#endregion
 //#region src/metadata.d.ts
 interface ProtectedResourceMetadata {
@@ -20,155 +21,7 @@ interface ProtectedResourceMetadata {
   scopes_supported?: string[];
   bearer_methods_supported?: string[];
 }
-declare function generateProtectedResourceMetadata(resourceUrl: string, authorizationServers: string[]): ProtectedResourceMetadata;
-//#endregion
-//#region src/provider/types.d.ts
-interface AuthInfo {
-  token: string;
-  clientId?: string;
-  scopes?: string[];
-  expiresAt?: number;
-  [key: string]: unknown;
-}
-interface OAuthRequest {
-  method: string;
-  url: URL;
-  headers: Record<string, string | undefined>;
-  body?: Record<string, string>;
-}
-interface OAuthResponse {
-  status: number;
-  headers: Record<string, string>;
-  body?: string | Record<string, unknown>;
-}
-interface OAuthProvider {
-  authorize(req: OAuthRequest): Promise<OAuthResponse>;
-  callback(req: OAuthRequest): Promise<OAuthResponse>;
-  token(req: OAuthRequest): Promise<OAuthResponse>;
-  register(req: OAuthRequest): Promise<OAuthResponse>;
-  metadata(): OAuthResponse;
-  verifyToken(token: string): Promise<AuthInfo | undefined>;
-}
-//#endregion
-//#region src/types.d.ts
-type VerifyToken = (token: string, context: SilkweaveContext) => Promise<AuthInfo | undefined>;
-interface AuthConfig {
-  verifyToken: VerifyToken;
-  required?: boolean;
-  resourceUrl?: string;
-  authorizationServers?: string[];
-  requiredScopes?: string[];
-  provider?: OAuthProvider;
-  callbackPath?: string;
-}
-//#endregion
-//#region src/provider/store.d.ts
-interface AuthCodeData {
-  clientId: string;
-  redirectUri: string;
-  codeChallenge: string;
-  codeChallengeMethod: string;
-  scopes: string[];
-  upstreamAccessToken: string;
-  upstreamIdToken?: string;
-  email?: string;
-  sub?: string;
-  expiresAt: number;
-}
-interface PendingAuthData {
-  clientId: string;
-  redirectUri: string;
-  codeChallenge: string;
-  codeChallengeMethod: string;
-  scope: string;
-  clientState: string;
-  resource?: string;
-  expiresAt: number;
-}
-interface ClientRegistration {
-  clientId: string;
-  clientSecret: string;
-  redirectUris: string[];
-  clientName?: string;
-  createdAt: number;
-}
-interface RefreshTokenData {
-  clientId: string;
-  scopes: string[];
-  email?: string;
-  sub?: string;
-  expiresAt: number;
-}
-interface OAuthStore {
-  saveAuthCode(code: string, data: AuthCodeData): Promise<void>;
-  getAuthCode(code: string): Promise<AuthCodeData | undefined>;
-  deleteAuthCode(code: string): Promise<void>;
-  savePendingAuth(state: string, data: PendingAuthData): Promise<void>;
-  getPendingAuth(state: string): Promise<PendingAuthData | undefined>;
-  deletePendingAuth(state: string): Promise<void>;
-  savePkceVerifier(state: string, verifier: string): Promise<void>;
-  getPkceVerifier(state: string): Promise<string | undefined>;
-  deletePkceVerifier(state: string): Promise<void>;
-  saveClient(clientId: string, data: ClientRegistration): Promise<void>;
-  getClient(clientId: string): Promise<ClientRegistration | undefined>;
-  saveRefreshToken(token: string, data: RefreshTokenData): Promise<void>;
-  getRefreshToken(token: string): Promise<RefreshTokenData | undefined>;
-  deleteRefreshToken(token: string): Promise<void>;
-}
-//#endregion
-//#region src/provider/google.d.ts
-interface GoogleOAuthOptions {
-  clientId: string;
-  clientSecret: string;
-  resourceUrl: string;
-  redirectUris: string[];
-  requiredScopes?: string[];
-  callbackPath?: string;
-  signingKey?: string;
-  tokenTtl?: number;
-  store?: OAuthStore;
-}
-declare function google(options: GoogleOAuthOptions): AuthConfig;
-//#endregion
-//#region src/provider/proxy.d.ts
-interface OAuthProxyConfig {
-  authorizeUrl: string;
-  tokenUrl: string;
-  userinfoUrl?: string;
-  clientId: string;
-  clientSecret: string;
-  resourceUrl: string;
-  redirectUris: string[];
-  requiredScopes?: string[];
-  callbackPath?: string;
-  signingKey?: string;
-  tokenTtl?: number;
-  store?: OAuthStore;
-}
-declare function createOAuthProxy(config: OAuthProxyConfig): OAuthProvider;
-//#endregion
-//#region src/provider/uri.d.ts
-declare function matchRedirectUri(uri: string, patterns: string[]): boolean;
-//#endregion
-//#region src/store/json-store.d.ts
-declare function createJsonStore(path: string): OAuthStore;
-//#endregion
-//#region src/store/memory-store.d.ts
-declare function createMemoryStore(): OAuthStore;
-//#endregion
-//#region src/store/redis-store.d.ts
-interface RedisClient {
-  get(key: string): Promise<unknown>;
-  set(key: string, value: string, options?: {
-    ex?: number;
-  }): Promise<unknown>;
-  del(key: string): Promise<unknown>;
-}
-interface RedisStoreOptions {
-  client: RedisClient;
-  prefix?: string;
-}
-declare function createRedisStore(options: RedisStoreOptions): OAuthStore;
+declare function generateProtectedResourceMetadata(resourceUrl: string, authorizationServers: string[], scopesSupported?: string[]): ProtectedResourceMetadata;
 //#endregion
 //#region src/validate.d.ts
 interface ValidateResult {
@@ -184,5 +37,5 @@ interface ValidateResult {
 }
 declare function validateToken(authorizationHeader: string | null | undefined, config: AuthConfig, context: SilkweaveContext): Promise<ValidateResult>;
 //#endregion
-export { AuthCodeData, AuthConfig, AuthError, type AuthInfo, ClientRegistration, GoogleOAuthOptions, OAuthProvider, OAuthProxyConfig, OAuthRequest, OAuthResponse, OAuthStore, PendingAuthData, ProtectedResourceMetadata, RedisClient, RedisStoreOptions, RefreshTokenData, ValidateResult, VerifyToken, buildWWWAuthenticate, createJsonStore, createMemoryStore, createOAuthProxy, createRedisStore, extractBearerToken, generateProtectedResourceMetadata, google, insufficientScope, invalidToken, matchRedirectUri, validateToken };
+export { AuthConfig, AuthError, AuthInfo, type OAuthProvider, type OAuthRequest, type OAuthResponse, ProtectedResourceMetadata, ValidateResult, VerifyToken, buildWWWAuthenticate, extractBearerToken, generateProtectedResourceMetadata, insufficientScope, invalidToken, validateToken };
 //# sourceMappingURL=index.d.mts.map

package/build/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/extract.ts","../src/metadata.ts","../src/provider/types.ts","../src/types.ts","../src/provider/store.ts","../src/provider/google.ts","../src/provider/proxy.ts","../src/provider/uri.ts","../src/store/json-store.ts","../src/store/memory-store.ts","../src/store/redis-store.ts","../src/validate.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/extract.ts","../src/metadata.ts","../src/validate.ts"],"mappings":";;;;cAAa,SAAA,SAAkB,KAAA;EAAA,SAGX,IAAA;EAAA,SACA,UAAA;cAFhB,OAAA,UACgB,IAAA,UACA,UAAA;AAAA;AAAA,iBAOJ,YAAA,CAAa,OAAA,YAAyB,SAAA;AAAA,iBAItC,iBAAA,CAAkB,OAAA,YAA8B,SAAA;;;iBCfhD,kBAAA,CAAmB,MAAA;AAAA,iBAMnB,oBAAA,CACd,KAAA,WACA,WAAA,WACA,mBAAA,WACA,KAAA;;;UCVe,yBAAA;EACf,QAAA;EACA,qBAAA;EACA,gBAAA;EACA,wBAAA;AAAA;AAAA,iBAGc,iCAAA,CACd,WAAA,UACA,oBAAA,YACA,eAAA,cACC,yBAAA;;;UCNc,cAAA;EACf,IAAA,GAAO,QAAA;EACP,KAAA;IACE,UAAA;IACA,OAAA,EAAS,MAAA;IACT,IAAA;MAAQ,KAAA;MAAe,iBAAA;IAAA;EAAA;AAAA;AAAA,iBAIL,aAAA,CACpB,mBAAA,6BACA,MAAA,EAAQ,UAAA,EACR,OAAA,EAAS,gBAAA,GACR,OAAA,CAAQ,cAAA"}