ucpify 1.1.0 → 1.2.1

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Generate UCP-compliant servers for merchants from a simple schema",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     "init": "ts-node src/cli.ts init",
     "serve": "ts-node src/cli.ts serve",
     "validate": "ts-node src/cli.ts validate",
-    "test": "vitest run",
+    "test": "node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"",
     "test:watch": "vitest"
   },
   "keywords": [
@@ -32,27 +32,27 @@
   "homepage": "https://github.com/hemanth/ucpify#readme",
   "type": "commonjs",
   "dependencies": {
-    "@paypal/paypal-server-sdk": "^2.2.0",
-    "better-sqlite3": "^12.6.2",
-    "commander": "^14.0.2",
-    "dotenv": "^17.2.3",
+    "@paypal/paypal-server-sdk": "^2.5.0",
+    "better-sqlite3": "^13.0.3",
+    "commander": "^15.0.0",
+    "dotenv": "^18.0.5",
     "express": "^5.2.1",
-    "express-rate-limit": "^8.2.1",
-    "pino": "^10.3.0",
-    "stripe": "^20.3.0",
-    "uuid": "^13.0.0",
-    "zod": "^4.3.6"
+    "express-rate-limit": "^8.7.0",
+    "pino": "^10.4.0",
+    "stripe": "^23.0.0",
+    "uuid": "^14.0.2",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.1.0",
-    "@types/supertest": "^6.0.3",
-    "@types/uuid": "^10.0.0",
+    "@types/node": "^26.6.4",
+    "@types/supertest": "^7.2.1",
+    "@types/uuid": "^11.0.0",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "name": "ucpify"
-}
+}

package/src/cli.ts

@@ -115,6 +115,9 @@ program
       const app = createExpressApp(config, { useDb });
       const port = config.port;
       const storageType = useDb ? 'SQLite' : 'In-memory';
+      const oauthStatus = config.oauth
+        ? config.oauth.provider === 'built-in' ? 'Built-in' : `External (${config.oauth.issuer})`
+        : 'Disabled';
 
       app.listen(port, () => {
         console.log(`
@@ -125,6 +128,7 @@ program
 ║  Domain:   ${config.domain.padEnd(49)}║
 ║  Port:     ${String(port).padEnd(49)}║
 ║  Storage:  ${storageType.padEnd(49)}║
+║  OAuth:    ${oauthStatus.padEnd(49)}║
 ╠══════════════════════════════════════════════════════════════╣
 ║  Endpoints:                                                  ║
 ║  • GET  /.well-known/ucp              - UCP Profile          ║
@@ -136,7 +140,11 @@ program
 ║  • GET  /ucp/v1/orders                - List Orders          ║
 ║  • GET  /ucp/v1/orders/:id            - Get Order            ║
 ║  • GET  /ucp/v1/items                 - Product Catalog      ║
-║  • GET  /health                       - Health Check         ║
+║  • GET  /health                       - Health Check         ║${config.oauth ? `
+║  • GET  /.well-known/oauth-...        - OAuth Metadata       ║` : ''}${config.oauth?.provider === 'built-in' ? `
+║  • GET  /oauth2/authorize             - Authorization        ║
+║  • POST /oauth2/token                 - Token Exchange       ║
+║  • POST /oauth2/revoke                - Token Revocation     ║` : ''}
 ╚══════════════════════════════════════════════════════════════╝
 
 🔗 UCP Profile: http://localhost:${port}/.well-known/ucp
@@ -144,6 +152,7 @@ program
 🚚 Shipping: ${config.shipping_options.length} options available
 💳 Payment Handlers: ${config.payment_handlers.length} configured
 💾 Storage: ${storageType}${useDb ? ' (./data/ucp.db)' : ''}
+🔐 OAuth: ${oauthStatus}
         `);
       });
     } catch (error) {
@@ -176,10 +185,30 @@ program
       console.log(`   • Products: ${config.items.length}`);
       console.log(`   • Shipping Options: ${config.shipping_options.length}`);
       console.log(`   • Payment Handlers: ${config.payment_handlers.length}`);
+      console.log(`   • OAuth: ${config.oauth ? config.oauth.provider : 'Disabled'}`);
     } catch (error) {
       console.error('❌ Validation failed:', error);
       process.exit(1);
     }
   });
 
+program
+  .command('oauth:add-client')
+  .description('Register a new OAuth client (built-in provider only)')
+  .argument('<name>', 'Client application name')
+  .option('-r, --redirect-uri <uri>', 'Redirect URI', 'http://localhost:3000/callback')
+  .action((name, options) => {
+    const { OAuthManager } = require('./oauth');
+    const oauthManager = new OAuthManager();
+    const client = oauthManager.createClient(name, [options.redirectUri]);
+
+    console.log(`\n✅ OAuth client created!\n`);
+    console.log(`   Client ID:     ${client.client_id}`);
+    console.log(`   Client Secret: ${client.client_secret}`);
+    console.log(`   Redirect URI:  ${options.redirectUri}`);
+    console.log(`\n⚠️  Save the client secret. It cannot be retrieved later.`);
+    console.log(`\n📝 Add to your merchant-config.json:`);
+    console.log(JSON.stringify({ oauth: { provider: 'built-in' } }, null, 2));
+  });
+
 program.parse();

package/src/db.ts

@@ -71,9 +71,44 @@ CREATE TABLE IF NOT EXISTS inventory (
   updated_at TEXT NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS oauth_clients (
+  client_id TEXT PRIMARY KEY,
+  client_secret_hash TEXT NOT NULL,
+  name TEXT NOT NULL,
+  redirect_uris_json TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS oauth_codes (
+  code TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  code_challenge TEXT,
+  code_challenge_method TEXT,
+  expires_at INTEGER NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (client_id) REFERENCES oauth_clients(client_id)
+);
+
+CREATE TABLE IF NOT EXISTS oauth_tokens (
+  token TEXT PRIMARY KEY,
+  token_type TEXT NOT NULL,
+  client_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  parent_token TEXT,
+  expires_at INTEGER NOT NULL,
+  revoked INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (client_id) REFERENCES oauth_clients(client_id)
+);
+
 CREATE INDEX IF NOT EXISTS idx_line_items_checkout ON line_items(checkout_id);
 CREATE INDEX IF NOT EXISTS idx_orders_checkout ON orders(checkout_id);
 CREATE INDEX IF NOT EXISTS idx_checkouts_status ON checkouts(status);
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_client ON oauth_tokens(client_id);
+CREATE INDEX IF NOT EXISTS idx_oauth_codes_client ON oauth_codes(client_id);
 `;
 
 db.exec(schema);

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;
 
@@ -34,6 +35,12 @@ export function createExpressApp(config: MerchantConfig, options?: { useDb?: boo
     : 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,7 +58,7 @@ 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': {
@@ -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());

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`,
+        };
+    }
+}