ucpify 1.0.1 → 1.2.0

package/src/express-app.ts

@@ -7,6 +7,7 @@ import { isDbHealthy, db } from './db';
 import { logger } from './logger';
 import { constructWebhookEvent, isStripeConfigured } from './stripe';
 import { getPayPalOrder, capturePayPalOrder } from './paypal';
+import { OAuthManager } from './oauth';
 
 type UCPServerType = UCPServer | UCPServerDB;
 
@@ -29,11 +30,17 @@ const checkoutLimiter = rateLimit({
 
 export function createExpressApp(config: MerchantConfig, options?: { useDb?: boolean }): express.Application {
   const app = express();
-  const ucpServer: UCPServerType = options?.useDb 
-    ? new UCPServerDB(config) 
+  const ucpServer: UCPServerType = options?.useDb
+    ? new UCPServerDB(config)
     : new UCPServer(config);
   const useDb = options?.useDb ?? false;
 
+  // OAuth setup (built-in or external)
+  const oauthEnabled = !!config.oauth;
+  const oauthManager = oauthEnabled && config.oauth?.provider === 'built-in'
+    ? new OAuthManager()
+    : null;
+
   // Apply rate limiting to API routes
   app.use('/ucp/v1/', apiLimiter);
 
@@ -51,14 +58,14 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
       return;
     }
 
-    logger.info({ eventType: event.type, eventId: event.id }, 'Stripe webhook received');
+    logger.info({ type: event.type }, 'Stripe webhook received');
 
     switch (event.type) {
       case 'payment_intent.succeeded': {
         const paymentIntent = event.data.object as { id: string; metadata?: { checkout_id?: string; order_id?: string } };
         const checkoutId = paymentIntent.metadata?.checkout_id;
         const orderId = paymentIntent.metadata?.order_id;
-        
+
         if (checkoutId && useDb) {
           db.prepare(`UPDATE checkouts SET payment_status = 'succeeded', updated_at = ? WHERE id = ?`)
             .run(new Date().toISOString(), checkoutId);
@@ -73,16 +80,16 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
         const paymentIntent = event.data.object as { id: string; metadata?: { checkout_id?: string; order_id?: string }; last_payment_error?: { message?: string } };
         const checkoutId = paymentIntent.metadata?.checkout_id;
         const orderId = paymentIntent.metadata?.order_id;
-        
+
         if (checkoutId && useDb) {
           db.prepare(`UPDATE checkouts SET payment_status = 'failed', updated_at = ? WHERE id = ?`)
             .run(new Date().toISOString(), checkoutId);
           if (orderId) {
             db.prepare(`UPDATE orders SET payment_status = 'failed' WHERE id = ?`).run(orderId);
           }
-          logger.error({ 
+          logger.error({
             checkoutId, orderId, paymentIntentId: paymentIntent.id,
-            error: paymentIntent.last_payment_error?.message 
+            error: paymentIntent.last_payment_error?.message
           }, 'Payment failed');
         }
         break;
@@ -107,7 +114,7 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
           // Get the checkout ID from the order
           const orderDetails = await getPayPalOrder(resource.id);
           const checkoutId = orderDetails?.customId;
-          
+
           if (checkoutId && useDb) {
             const now = new Date().toISOString();
             db.prepare(`UPDATE checkouts SET payment_status = 'succeeded', updated_at = ? WHERE paypal_order_id = ?`)
@@ -158,6 +165,204 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
     next();
   });
 
+  // ─── OAuth 2.0 Identity Linking ─────────────────────────────────────
+
+  // RFC 8414: OAuth Authorization Server Metadata
+  app.get('/.well-known/oauth-authorization-server', (_req: Request, res: Response) => {
+    if (!oauthEnabled) {
+      res.status(404).json({ error: 'OAuth not configured' });
+      return;
+    }
+
+    if (config.oauth?.provider === 'external') {
+      // Proxy the merchant's external OAuth metadata
+      res.json({
+        issuer: config.oauth.issuer,
+        authorization_endpoint: config.oauth.authorization_endpoint,
+        token_endpoint: config.oauth.token_endpoint,
+        revocation_endpoint: config.oauth.revocation_endpoint,
+        jwks_uri: config.oauth.jwks_uri,
+        scopes_supported: ['ucp:scopes:checkout_session'],
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        token_endpoint_auth_methods_supported: ['client_secret_basic'],
+      });
+    } else if (oauthManager) {
+      res.json(oauthManager.getServerMetadata(config.domain));
+    }
+  });
+
+  // Built-in OAuth endpoints (only when provider is "built-in")
+  if (oauthManager) {
+    // Authorization endpoint - renders consent screen
+    app.get('/oauth2/authorize', (req: Request, res: Response) => {
+      const { client_id, redirect_uri, scope, state, response_type, code_challenge, code_challenge_method } = req.query;
+
+      if (response_type !== 'code') {
+        res.status(400).json({ error: 'unsupported_response_type' });
+        return;
+      }
+
+      const client = oauthManager.getClient(client_id as string);
+      if (!client) {
+        res.status(400).json({ error: 'invalid_client' });
+        return;
+      }
+
+      if (!client.redirect_uris.includes(redirect_uri as string)) {
+        res.status(400).json({ error: 'invalid_redirect_uri' });
+        return;
+      }
+
+      // Render a minimal consent page
+      res.send(`<!DOCTYPE html>
+<html><head><title>Authorize - ${config.name}</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 400px; margin: 80px auto; padding: 0 20px; }
+h2 { margin-bottom: 4px; }
+p { color: #666; }
+.scope { background: #f0f0f0; padding: 8px 12px; border-radius: 6px; font-family: monospace; }
+button { padding: 10px 24px; border: none; border-radius: 6px; cursor: pointer; font-size: 14px; margin-right: 8px; }
+.allow { background: #000; color: #fff; }
+.deny { background: #e5e5e5; }
+</style></head>
+<body>
+<h2>${config.name}</h2>
+<p><strong>${client.name}</strong> wants to access your account.</p>
+<div class="scope">${scope || 'ucp:scopes:checkout_session'}</div>
+<p>This will allow the app to manage checkout sessions on your behalf.</p>
+<form method="POST" action="/oauth2/authorize">
+  <input type="hidden" name="client_id" value="${client_id}">
+  <input type="hidden" name="redirect_uri" value="${redirect_uri}">
+  <input type="hidden" name="scope" value="${scope || 'ucp:scopes:checkout_session'}">
+  <input type="hidden" name="state" value="${state || ''}">
+  <input type="hidden" name="code_challenge" value="${code_challenge || ''}">
+  <input type="hidden" name="code_challenge_method" value="${code_challenge_method || ''}">
+  <input type="hidden" name="user_id" value="user_1">
+  <button type="submit" name="action" value="allow" class="allow">Allow</button>
+  <button type="submit" name="action" value="deny" class="deny">Deny</button>
+</form>
+</body></html>`);
+    });
+
+    // Handle consent form submission
+    app.post('/oauth2/authorize', express.urlencoded({ extended: false }), (req: Request, res: Response) => {
+      const { client_id, redirect_uri, scope, state, action, user_id, code_challenge, code_challenge_method } = req.body;
+
+      if (action === 'deny') {
+        const url = new URL(redirect_uri);
+        url.searchParams.set('error', 'access_denied');
+        if (state) url.searchParams.set('state', state);
+        res.redirect(url.toString());
+        return;
+      }
+
+      const code = oauthManager.createAuthorizationCode(
+        client_id, user_id, scope,
+        redirect_uri,
+        code_challenge || undefined,
+        code_challenge_method || undefined,
+      );
+
+      const url = new URL(redirect_uri);
+      url.searchParams.set('code', code);
+      if (state) url.searchParams.set('state', state);
+      res.redirect(url.toString());
+    });
+
+    // Token endpoint
+    app.post('/oauth2/token', (req: Request, res: Response) => {
+      // Client auth via HTTP Basic (RFC 7617)
+      const authHeader = req.headers.authorization;
+      let clientId = req.body.client_id;
+      let clientSecret = req.body.client_secret;
+
+      if (authHeader && authHeader.startsWith('Basic ')) {
+        const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const [id, secret] = decoded.split(':');
+        clientId = id;
+        clientSecret = secret;
+      }
+
+      if (!oauthManager.authenticateClient(clientId, clientSecret)) {
+        res.status(401).json({ error: 'invalid_client' });
+        return;
+      }
+
+      const grantType = req.body.grant_type;
+
+      if (grantType === 'authorization_code') {
+        const result = oauthManager.exchangeCode(
+          req.body.code,
+          clientId,
+          req.body.redirect_uri,
+          req.body.code_verifier,
+        );
+        if ('error' in result) {
+          res.status(400).json(result);
+          return;
+        }
+        res.json({ ...result, token_type: 'Bearer' });
+      } else if (grantType === 'refresh_token') {
+        const result = oauthManager.refreshAccessToken(req.body.refresh_token, clientId);
+        if ('error' in result) {
+          res.status(400).json(result);
+          return;
+        }
+        res.json({ ...result, token_type: 'Bearer' });
+      } else {
+        res.status(400).json({ error: 'unsupported_grant_type' });
+      }
+    });
+
+    // Token revocation (RFC 7009)
+    app.post('/oauth2/revoke', (req: Request, res: Response) => {
+      const authHeader = req.headers.authorization;
+      let clientId = req.body.client_id;
+      let clientSecret = req.body.client_secret;
+
+      if (authHeader && authHeader.startsWith('Basic ')) {
+        const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const [id, secret] = decoded.split(':');
+        clientId = id;
+        clientSecret = secret;
+      }
+
+      if (!oauthManager.authenticateClient(clientId, clientSecret)) {
+        res.status(401).json({ error: 'invalid_client' });
+        return;
+      }
+
+      oauthManager.revokeToken(req.body.token);
+      // RFC 7009: always respond 200, even if token was invalid
+      res.status(200).json({});
+    });
+  }
+
+  // Bearer token middleware for UCP routes (when OAuth is enabled)
+  if (oauthEnabled && oauthManager) {
+    app.use('/ucp/v1', (req: Request, res: Response, next: NextFunction) => {
+      const authHeader = req.headers.authorization;
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        res.status(401).json({ error: 'missing_token', message: 'Authorization: Bearer <token> required' });
+        return;
+      }
+
+      const token = authHeader.slice(7);
+      const validToken = oauthManager.validateAccessToken(token);
+      if (!validToken) {
+        res.status(401).json({ error: 'invalid_token', message: 'Token is expired, revoked, or invalid' });
+        return;
+      }
+
+      // Attach user info to request
+      (req as any).oauthUserId = validToken.user_id;
+      (req as any).oauthClientId = validToken.client_id;
+      (req as any).oauthScope = validToken.scope;
+      next();
+    });
+  }
+
   // UCP Discovery endpoint
   app.get('/.well-known/ucp', (_req: Request, res: Response) => {
     res.json(ucpServer.getProfile());
@@ -267,17 +472,17 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
       const checkoutStats = db.prepare(`
         SELECT status, COUNT(*) as count FROM checkouts GROUP BY status
       `).all() as { status: string; count: number }[];
-      
+
       const orderStats = db.prepare(`
         SELECT payment_status, payment_provider, COUNT(*) as count 
         FROM orders GROUP BY payment_status, payment_provider
       `).all() as { payment_status: string; payment_provider: string; count: number }[];
-      
+
       const revenueResult = db.prepare(`
         SELECT SUM(json_extract(totals_json, '$[?(@.type=="total")].amount')) as total
         FROM orders WHERE payment_status = 'succeeded'
       `).get() as { total: number | null };
-      
+
       const todayOrders = db.prepare(`
         SELECT COUNT(*) as count FROM orders 
         WHERE date(created_at) = date('now')
@@ -302,6 +507,17 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
 
   // Admin dashboard HTML
   app.get('/admin', (_req: Request, res: Response) => {
+    const statsScript = useDb
+      ? `fetch('/admin/stats').then(r=>r.json()).then(d=>{
+  document.getElementById('stats').innerHTML = \`
+    <div class="card"><div class="stat">\${Object.values(d.checkouts).reduce((a,b)=>a+b,0)}</div><div class="label">Total Checkouts</div></div>
+    <div class="card"><div class="stat">\${d.checkouts.completed||0}</div><div class="label">Completed</div></div>
+    <div class="card"><div class="stat">\${d.orders.today||0}</div><div class="label">Orders Today</div></div>
+    <div class="card"><div class="stat">$\${(d.revenue.total_succeeded/100).toFixed(2)}</div><div class="label">Revenue</div></div>
+  \`;
+}).catch(e=>document.getElementById('stats').innerHTML='Error loading stats');`
+      : `document.getElementById('stats').innerHTML = '<div class="card" style="grid-column:1/-1"><div class="label">Running in <strong>in-memory mode</strong>. Stats require <code>--db</code> mode.</div><div style="margin-top:8px;font-size:0.85em;color:#999">Restart with: <code>ucpify serve config.json</code> (DB is on by default)</div></div>';`;
+
     res.send(`<!DOCTYPE html>
 <html><head><title>UCP Admin</title>
 <style>
@@ -311,20 +527,12 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
   .label { color: #666; font-size: 0.9em; }
   .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 15px; }
   h1 { color: #333; }
+  code { background: #e5e5e5; padding: 2px 6px; border-radius: 3px; font-size: 0.85em; }
 </style>
 </head><body>
 <h1>🛒 UCP Server Admin</h1>
 <div class="grid" id="stats">Loading...</div>
-<script>
-fetch('/admin/stats').then(r=>r.json()).then(d=>{
-  document.getElementById('stats').innerHTML = \`
-    <div class="card"><div class="stat">\${Object.values(d.checkouts).reduce((a,b)=>a+b,0)}</div><div class="label">Total Checkouts</div></div>
-    <div class="card"><div class="stat">\${d.checkouts.completed||0}</div><div class="label">Completed</div></div>
-    <div class="card"><div class="stat">\${d.orders.today||0}</div><div class="label">Orders Today</div></div>
-    <div class="card"><div class="stat">$\${(d.revenue.total_succeeded/100).toFixed(2)}</div><div class="label">Revenue</div></div>
-  \`;
-}).catch(e=>document.getElementById('stats').innerHTML='Error loading stats');
-</script>
+<script>${statsScript}</script>
 </body></html>`);
   });
 
@@ -332,8 +540,8 @@ fetch('/admin/stats').then(r=>r.json()).then(d=>{
   app.get('/health', (_req: Request, res: Response) => {
     const dbHealthy = isDbHealthy();
     const status = dbHealthy ? 'ok' : 'degraded';
-    res.status(dbHealthy ? 200 : 503).json({ 
-      status, 
+    res.status(dbHealthy ? 200 : 503).json({
+      status,
       ucp_version: UCP_VERSION,
       database: dbHealthy ? 'connected' : 'disconnected',
       timestamp: new Date().toISOString(),

package/src/oauth.ts

@@ -0,0 +1,270 @@
+import crypto from 'crypto';
+import { logger } from './logger';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface OAuthClient {
+    client_id: string;
+    client_secret: string;
+    client_secret_hash: string;
+    name: string;
+    redirect_uris: string[];
+    created_at: string;
+}
+
+export interface AuthorizationCode {
+    code: string;
+    client_id: string;
+    user_id: string;
+    scope: string;
+    redirect_uri: string;
+    code_challenge?: string;
+    code_challenge_method?: string;
+    expires_at: number;
+    used: boolean;
+}
+
+export interface OAuthToken {
+    token: string;
+    token_type: 'access' | 'refresh';
+    client_id: string;
+    user_id: string;
+    scope: string;
+    parent_token?: string;
+    expires_at: number;
+    revoked: boolean;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+export const UCP_SCOPES = ['ucp:scopes:checkout_session'] as const;
+const ACCESS_TOKEN_TTL = 60 * 60;         // 1 hour
+const REFRESH_TOKEN_TTL = 60 * 60 * 24 * 30; // 30 days
+const AUTH_CODE_TTL = 60 * 10;            // 10 minutes
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function generateToken(bytes = 32): string {
+    return crypto.randomBytes(bytes).toString('hex');
+}
+
+function hashSecret(secret: string): string {
+    return crypto.createHash('sha256').update(secret).digest('hex');
+}
+
+function nowEpoch(): number {
+    return Math.floor(Date.now() / 1000);
+}
+
+// ─── OAuth Manager ───────────────────────────────────────────────────
+
+export class OAuthManager {
+    private clients: Map<string, OAuthClient> = new Map();
+    private codes: Map<string, AuthorizationCode> = new Map();
+    private accessTokens: Map<string, OAuthToken> = new Map();
+    private refreshTokens: Map<string, OAuthToken> = new Map();
+
+    // ── Client Management ──
+
+    createClient(name: string, redirectUris: string[]): OAuthClient {
+        const clientId = `ucp_${generateToken(16)}`;
+        const clientSecret = `ucp_secret_${generateToken(24)}`;
+        const client: OAuthClient = {
+            client_id: clientId,
+            client_secret: clientSecret,
+            client_secret_hash: hashSecret(clientSecret),
+            name,
+            redirect_uris: redirectUris,
+            created_at: new Date().toISOString(),
+        };
+        this.clients.set(clientId, client);
+        logger.info({ clientId, name }, 'OAuth client created');
+        return client;
+    }
+
+    getClient(clientId: string): OAuthClient | undefined {
+        return this.clients.get(clientId);
+    }
+
+    authenticateClient(clientId: string, clientSecret: string): boolean {
+        const client = this.clients.get(clientId);
+        if (!client) return false;
+        return client.client_secret_hash === hashSecret(clientSecret);
+    }
+
+    // ── Authorization Code ──
+
+    createAuthorizationCode(
+        clientId: string,
+        userId: string,
+        scope: string,
+        redirectUri: string,
+        codeChallenge?: string,
+        codeChallengeMethod?: string,
+    ): string {
+        const code = generateToken(32);
+        const authCode: AuthorizationCode = {
+            code,
+            client_id: clientId,
+            user_id: userId,
+            scope,
+            redirect_uri: redirectUri,
+            code_challenge: codeChallenge,
+            code_challenge_method: codeChallengeMethod,
+            expires_at: nowEpoch() + AUTH_CODE_TTL,
+            used: false,
+        };
+        this.codes.set(code, authCode);
+        logger.info({ clientId, userId, scope }, 'Authorization code created');
+        return code;
+    }
+
+    exchangeCode(
+        code: string,
+        clientId: string,
+        redirectUri: string,
+        codeVerifier?: string,
+    ): { access_token: string; refresh_token: string; expires_in: number; scope: string } | { error: string } {
+        const authCode = this.codes.get(code);
+
+        if (!authCode) return { error: 'invalid_grant' };
+        if (authCode.used) return { error: 'invalid_grant' };
+        if (authCode.client_id !== clientId) return { error: 'invalid_grant' };
+        if (authCode.redirect_uri !== redirectUri) return { error: 'invalid_grant' };
+        if (authCode.expires_at < nowEpoch()) return { error: 'invalid_grant' };
+
+        // PKCE verification
+        if (authCode.code_challenge) {
+            if (!codeVerifier) return { error: 'invalid_grant' };
+            const method = authCode.code_challenge_method || 'S256';
+            let computed: string;
+            if (method === 'S256') {
+                computed = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+            } else {
+                computed = codeVerifier;
+            }
+            if (computed !== authCode.code_challenge) return { error: 'invalid_grant' };
+        }
+
+        // Mark code as used
+        authCode.used = true;
+        this.codes.set(code, authCode);
+
+        // Generate tokens
+        const accessToken = this.createAccessToken(clientId, authCode.user_id, authCode.scope);
+        const refreshToken = this.createRefreshToken(clientId, authCode.user_id, authCode.scope);
+
+        logger.info({ clientId, userId: authCode.user_id }, 'Authorization code exchanged for tokens');
+
+        return {
+            access_token: accessToken,
+            refresh_token: refreshToken,
+            expires_in: ACCESS_TOKEN_TTL,
+            scope: authCode.scope,
+        };
+    }
+
+    // ── Token Management ──
+
+    private createAccessToken(clientId: string, userId: string, scope: string): string {
+        const token = generateToken(32);
+        this.accessTokens.set(token, {
+            token,
+            token_type: 'access',
+            client_id: clientId,
+            user_id: userId,
+            scope,
+            expires_at: nowEpoch() + ACCESS_TOKEN_TTL,
+            revoked: false,
+        });
+        return token;
+    }
+
+    private createRefreshToken(clientId: string, userId: string, scope: string): string {
+        const token = generateToken(32);
+        this.refreshTokens.set(token, {
+            token,
+            token_type: 'refresh',
+            client_id: clientId,
+            user_id: userId,
+            scope,
+            expires_at: nowEpoch() + REFRESH_TOKEN_TTL,
+            revoked: false,
+        });
+        return token;
+    }
+
+    refreshAccessToken(
+        refreshToken: string,
+        clientId: string,
+    ): { access_token: string; expires_in: number; scope: string } | { error: string } {
+        const rt = this.refreshTokens.get(refreshToken);
+        if (!rt) return { error: 'invalid_grant' };
+        if (rt.revoked) return { error: 'invalid_grant' };
+        if (rt.client_id !== clientId) return { error: 'invalid_grant' };
+        if (rt.expires_at < nowEpoch()) return { error: 'invalid_grant' };
+
+        const accessToken = this.createAccessToken(clientId, rt.user_id, rt.scope);
+        logger.info({ clientId, userId: rt.user_id }, 'Access token refreshed');
+
+        return {
+            access_token: accessToken,
+            expires_in: ACCESS_TOKEN_TTL,
+            scope: rt.scope,
+        };
+    }
+
+    validateAccessToken(token: string): OAuthToken | null {
+        const t = this.accessTokens.get(token);
+        if (!t) return null;
+        if (t.revoked) return null;
+        if (t.expires_at < nowEpoch()) return null;
+        return t;
+    }
+
+    revokeToken(token: string): boolean {
+        // Check access tokens
+        const at = this.accessTokens.get(token);
+        if (at) {
+            at.revoked = true;
+            this.accessTokens.set(token, at);
+            logger.info({ tokenType: 'access', clientId: at.client_id }, 'Token revoked');
+            return true;
+        }
+
+        // Check refresh tokens - also revoke all associated access tokens
+        const rt = this.refreshTokens.get(token);
+        if (rt) {
+            rt.revoked = true;
+            this.refreshTokens.set(token, rt);
+            // Revoke all access tokens for same client+user
+            for (const [key, accessToken] of this.accessTokens) {
+                if (accessToken.client_id === rt.client_id && accessToken.user_id === rt.user_id) {
+                    accessToken.revoked = true;
+                    this.accessTokens.set(key, accessToken);
+                }
+            }
+            logger.info({ tokenType: 'refresh', clientId: rt.client_id }, 'Refresh token and associated access tokens revoked');
+            return true;
+        }
+
+        return false;
+    }
+
+    // ── Metadata ──
+
+    getServerMetadata(issuer: string): Record<string, unknown> {
+        return {
+            issuer,
+            authorization_endpoint: `${issuer}/oauth2/authorize`,
+            token_endpoint: `${issuer}/oauth2/token`,
+            revocation_endpoint: `${issuer}/oauth2/revoke`,
+            scopes_supported: [...UCP_SCOPES],
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['client_secret_basic'],
+            code_challenge_methods_supported: ['S256'],
+            service_documentation: `${issuer}/docs/oauth2`,
+        };
+    }
+}

package/src/schema.ts

@@ -30,6 +30,23 @@ export const PaymentHandlerSchema = z.object({
   config: z.record(z.string(), z.unknown()).optional(),
 });
 
+// OAuth Configuration Schema
+export const OAuthConfigSchema = z.discriminatedUnion('provider', [
+  z.object({
+    provider: z.literal('built-in'),
+  }),
+  z.object({
+    provider: z.literal('external'),
+    issuer: z.string().url(),
+    authorization_endpoint: z.string().url(),
+    token_endpoint: z.string().url(),
+    revocation_endpoint: z.string().url().optional(),
+    jwks_uri: z.string().url().optional(),
+  }),
+]);
+
+export type OAuthConfig = z.infer<typeof OAuthConfigSchema>;
+
 // Merchant Configuration Schema
 export const MerchantConfigSchema = z.object({
   name: z.string(),
@@ -42,6 +59,7 @@ export const MerchantConfigSchema = z.object({
   payment_handlers: z.array(PaymentHandlerSchema).default([]),
   tax_rate: z.number().min(0).max(1).default(0), // e.g., 0.08 for 8%
   port: z.number().default(3000),
+  oauth: OAuthConfigSchema.optional(),
 });
 
 export type Item = z.infer<typeof ItemSchema>;