@silkweave/auth 1.3.0

package/.turbo/turbo-build.log

@@ -0,0 +1,18 @@
+
+
+> @silkweave/auth@1.3.0 build /Users/atomic/projects/ai/silkweave/packages/auth
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /Users/atomic/projects/ai/silkweave/packages/auth/tsup.config.ts
+CLI Target: node18
+CLI Cleaning output folder
+ESM Build start
+ESM build/index.js     25.84 KB
+ESM build/index.js.map 46.97 KB
+ESM ⚡️ Build success in 9ms
+DTS Build start
+DTS ⚡️ Build success in 447ms
+DTS build/index.d.ts 5.81 KB

package/.turbo/turbo-check.log

@@ -0,0 +1,13 @@
+
+
+> @silkweave/auth@1.3.0 check /Users/atomic/projects/ai/silkweave/packages/auth
+> pnpm lint && pnpm typecheck
+
+
+> @silkweave/auth@1.3.0 lint /Users/atomic/projects/ai/silkweave/packages/auth
+> eslint
+
+
+> @silkweave/auth@1.3.0 typecheck /Users/atomic/projects/ai/silkweave/packages/auth
+> tsc --noEmit
+

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+
+> @silkweave/auth@1.3.0 lint /Users/atomic/projects/ai/silkweave/packages/auth
+> eslint
+

package/.turbo/turbo-prepack.log

@@ -0,0 +1,26 @@
+
+
+> @silkweave/auth@1.3.0 prepack /Users/atomic/projects/ai/mcphero/packages/auth
+> pnpm clean && pnpm build
+
+
+> @silkweave/auth@1.3.0 clean /Users/atomic/projects/ai/mcphero/packages/auth
+> rimraf build
+
+
+> @silkweave/auth@1.3.0 build /Users/atomic/projects/ai/mcphero/packages/auth
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /Users/atomic/projects/ai/mcphero/packages/auth/tsup.config.ts
+CLI Target: node18
+CLI Cleaning output folder
+ESM Build start
+ESM build/index.js     25.84 KB
+ESM build/index.js.map 46.97 KB
+ESM ⚡️ Build success in 10ms
+DTS Build start
+DTS ⚡️ Build success in 434ms
+DTS build/index.d.ts 5.81 KB

package/README.md

@@ -0,0 +1,245 @@
+# @silkweave/auth
+
+OAuth 2.1 authentication for [Silkweave](https://github.com/atomicbi/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).
+
+Standalone package -- only depends on `jose` for JWT signing/verification.
+
+## Install
+
+```bash
+pnpm add @silkweave/auth
+```
+
+## 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 { silkweave } from '@silkweave/core'
+import { http } from '@silkweave/mcp'
+
+const auth = google({
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  resourceUrl: 'http://localhost:8080',
+  redirectUris: ['http://localhost:*', 'https://claude.ai/*'],
+  requiredScopes: ['openid', 'https://www.googleapis.com/auth/userinfo.email'],
+  signingKey: 'your-signing-secret',
+  store: createJsonStore('oauth-store.json')
+})
+
+await silkweave({ name: 'my-server', description: 'My MCP Server', version: '1.0.0' })
+  .adapter(http({ host: 'localhost', port: 8080, auth }))
+  .action(MyAction)
+  .start()
+```
+
+### `GoogleOAuthOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `clientId` | `string` | -- | Google OAuth client ID |
+| `clientSecret` | `string` | -- | Google OAuth client secret |
+| `resourceUrl` | `string` | -- | Public URL of your MCP server |
+| `redirectUris` | `string[]` | -- | Allowed redirect URI patterns (supports `*` wildcards) |
+| `requiredScopes` | `string[]` | `['openid', 'email']` | Scopes to request from Google |
+| `callbackPath` | `string` | `'/auth/callback'` | Path for the OAuth callback endpoint |
+| `signingKey` | `string` | random | Secret for signing JWTs (random per-process if omitted) |
+| `tokenTtl` | `number` | `3600` | Access token lifetime in seconds |
+| `store` | `OAuthStore` | memory | Store adapter for OAuth state |
+
+## Custom Providers with `createOAuthProxy()`
+
+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'
+
+const provider = createOAuthProxy({
+  authorizeUrl: 'https://provider.example.com/authorize',
+  tokenUrl: 'https://provider.example.com/token',
+  userinfoUrl: 'https://provider.example.com/userinfo',
+  clientId: process.env.OAUTH_CLIENT_ID!,
+  clientSecret: process.env.OAUTH_CLIENT_SECRET!,
+  resourceUrl: 'https://my-server.example.com',
+  redirectUris: ['https://claude.ai/*'],
+  requiredScopes: ['openid', 'email']
+})
+```
+
+### `OAuthProxyConfig`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `authorizeUrl` | `string` | -- | Upstream authorization endpoint |
+| `tokenUrl` | `string` | -- | Upstream token endpoint |
+| `userinfoUrl` | `string` | -- | Upstream userinfo endpoint (optional, best-effort) |
+| `clientId` | `string` | -- | Your client ID with the upstream provider |
+| `clientSecret` | `string` | -- | Your client secret with the upstream provider |
+| `resourceUrl` | `string` | -- | Public URL of your MCP server |
+| `redirectUris` | `string[]` | -- | Allowed redirect URI patterns |
+| `requiredScopes` | `string[]` | `[]` | Scopes to request upstream |
+| `callbackPath` | `string` | `'/auth/callback'` | Path for the OAuth callback endpoint |
+| `signingKey` | `string` | random | Secret for signing JWTs |
+| `tokenTtl` | `number` | `3600` | Access token lifetime in seconds |
+| `store` | `OAuthStore` | memory | Store adapter for OAuth state |
+
+### `OAuthProvider` interface
+
+The provider returned by `createOAuthProxy()` exposes:
+
+```typescript
+interface OAuthProvider {
+  metadata(): OAuthResponse
+  register(req: OAuthRequest): Promise<OAuthResponse>
+  authorize(req: OAuthRequest): Promise<OAuthResponse>
+  callback(req: OAuthRequest): Promise<OAuthResponse>
+  token(req: OAuthRequest): Promise<OAuthResponse>
+  verifyToken(token: string): Promise<AuthInfo | undefined>
+}
+```
+
+To build a full `AuthConfig` from a custom provider:
+
+```typescript
+const auth: AuthConfig = {
+  verifyToken: (token) => provider.verifyToken(token),
+  required: true,
+  resourceUrl: 'https://my-server.example.com',
+  authorizationServers: ['https://my-server.example.com'],
+  provider
+}
+```
+
+## Token Validation
+
+Use `validateToken()` to verify bearer tokens in your own middleware or custom adapters:
+
+```typescript
+import { validateToken } from '@silkweave/auth'
+
+const result = await validateToken(request.headers.authorization, {
+  verifyToken: async (token) => {
+    // Your verification logic -- return AuthInfo or undefined
+    return { token, clientId: 'user-123', scopes: ['read'] }
+  },
+  required: true,
+  resourceUrl: 'https://my-server.example.com',
+  requiredScopes: ['read']
+})
+
+if (result.error) {
+  // result.error.statusCode, result.error.headers, result.error.body
+  return new Response(JSON.stringify(result.error.body), {
+    status: result.error.statusCode,
+    headers: result.error.headers
+  })
+}
+
+// result.auth contains the verified AuthInfo
+console.log(result.auth?.clientId)
+```
+
+## Protected Resource Metadata (RFC 9728)
+
+Generate the `/.well-known/oauth-protected-resource` document for your server:
+
+```typescript
+import { generateProtectedResourceMetadata } from '@silkweave/auth'
+
+const metadata = generateProtectedResourceMetadata(
+  'https://my-server.example.com',
+  ['https://my-server.example.com']
+)
+// {
+//   resource: 'https://my-server.example.com',
+//   authorization_servers: ['https://my-server.example.com'],
+//   bearer_methods_supported: ['header']
+// }
+```
+
+## Store Adapters
+
+The OAuth proxy needs persistent storage for auth codes, client registrations, PKCE verifiers, and refresh tokens. Three built-in adapters are available:
+
+### Memory (default)
+
+In-memory storage -- data is lost on restart. Good for development:
+
+```typescript
+import { createMemoryStore } from '@silkweave/auth'
+
+const store = createMemoryStore()
+```
+
+### JSON File
+
+Persists to a JSON file on disk. Suitable for single-process deployments:
+
+```typescript
+import { createJsonStore } from '@silkweave/auth'
+
+const store = createJsonStore('oauth-store.json')
+```
+
+### Redis
+
+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 Redis from 'ioredis'
+
+const store = createRedisStore({
+  client: new Redis(),
+  prefix: 'silkweave:oauth:'  // default prefix
+})
+```
+
+### Custom Store
+
+Implement the `OAuthStore` interface for your own backend:
+
+```typescript
+import type { OAuthStore } from '@silkweave/auth'
+
+const store: OAuthStore = {
+  saveAuthCode(code, data) { /* ... */ },
+  getAuthCode(code) { /* ... */ },
+  deleteAuthCode(code) { /* ... */ },
+  savePendingAuth(state, data) { /* ... */ },
+  getPendingAuth(state) { /* ... */ },
+  deletePendingAuth(state) { /* ... */ },
+  savePkceVerifier(state, verifier) { /* ... */ },
+  getPkceVerifier(state) { /* ... */ },
+  deletePkceVerifier(state) { /* ... */ },
+  saveClient(clientId, data) { /* ... */ },
+  getClient(clientId) { /* ... */ },
+  saveRefreshToken(token, data) { /* ... */ },
+  getRefreshToken(token) { /* ... */ },
+  deleteRefreshToken(token) { /* ... */ }
+}
+```
+
+## How It Works
+
+The OAuth proxy sits between MCP clients and the upstream identity provider:
+
+1. MCP client calls `/authorize` -- the proxy generates its own PKCE pair and redirects to the upstream provider
+2. User authenticates with the upstream provider (e.g., Google)
+3. Upstream redirects back to the proxy's callback path with an authorization code
+4. Proxy exchanges the upstream code for tokens, then issues its own authorization code to the MCP client
+5. MCP client exchanges that code at `/token` (with PKCE verification) and receives a signed JWT access token + refresh token
+6. Subsequent requests include the JWT as a Bearer token, verified locally via `jose`
+
+The proxy also supports:
+- **Dynamic client registration** at `/register` (RFC 7591)
+- **Client Information Metadata Documents (CIMD)** -- clients with HTTPS URLs as `client_id` are auto-registered by fetching their metadata document
+- **Refresh tokens** with 30-day expiry for long-lived sessions
+
+## See Also
+
+- [Silkweave README](https://github.com/atomicbi/silkweave) -- Full documentation
+- [`@silkweave/core`](https://www.npmjs.com/package/@silkweave/core) -- Core library
+- [`@silkweave/mcp`](https://www.npmjs.com/package/@silkweave/mcp) -- MCP stdio and HTTP adapters

package/build/index.d.ts

@@ -0,0 +1,173 @@
+declare class AuthError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode?: number);
+}
+declare function invalidToken(message?: string): AuthError;
+declare function insufficientScope(message?: string): AuthError;
+declare function missingToken(message?: string): AuthError;
+
+declare function extractBearerToken(header: string | null | undefined): string | null;
+declare function buildWWWAuthenticate(error?: string, description?: string, resourceMetadataUrl?: string): string;
+
+interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported?: string[];
+    bearer_methods_supported?: string[];
+}
+declare function generateProtectedResourceMetadata(resourceUrl: string, authorizationServers: string[]): ProtectedResourceMetadata;
+
+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>;
+}
+
+declare function createMemoryStore(): OAuthStore;
+
+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>;
+}
+
+interface AuthInfo {
+    token: string;
+    clientId?: string;
+    scopes?: string[];
+    expiresAt?: number;
+    [key: string]: unknown;
+}
+type VerifyToken = (token: string) => Promise<AuthInfo | undefined>;
+interface AuthConfig {
+    verifyToken: VerifyToken;
+    required?: boolean;
+    resourceUrl?: string;
+    authorizationServers?: string[];
+    requiredScopes?: string[];
+    provider?: OAuthProvider;
+    callbackPath?: string;
+}
+
+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;
+
+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;
+
+declare function matchRedirectUri(uri: string, patterns: string[]): boolean;
+
+declare function createJsonStore(path: string): OAuthStore;
+
+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;
+
+interface ValidateResult {
+    auth?: AuthInfo;
+    error?: {
+        statusCode: number;
+        headers: Record<string, string>;
+        body: {
+            error: string;
+            error_description: string;
+        };
+    };
+}
+declare function validateToken(authorizationHeader: string | null | undefined, config: AuthConfig): Promise<ValidateResult>;
+
+export { type AuthCodeData, type AuthConfig, AuthError, type AuthInfo, type ClientRegistration, type GoogleOAuthOptions, type OAuthProvider, type OAuthProxyConfig, type OAuthRequest, type OAuthResponse, type OAuthStore, type PendingAuthData, type ProtectedResourceMetadata, type RedisClient, type RedisStoreOptions, type RefreshTokenData, type ValidateResult, type VerifyToken, buildWWWAuthenticate, createJsonStore, createMemoryStore, createOAuthProxy, createRedisStore, extractBearerToken, generateProtectedResourceMetadata, google, insufficientScope, invalidToken, matchRedirectUri, missingToken, validateToken };