Merge pull request #539 from abraham/copilot/consolidate-oauth2-flows

abraham · web-flow · commit 41018558a454 · 2025-11-24T18:15:17.000-06:00
Consolidate OAuth2 security schemes into single scheme with multiple flows
diff --git a/dist/schema.json b/dist/schema.json
@@ -156,7 +156,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "write:accounts"
             ]
           }
@@ -5552,7 +5552,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": []
+            "OAuth2": []
           }
         ]
       }
@@ -25644,7 +25644,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "read:statuses"
             ]
           }
@@ -25807,7 +25807,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "read:statuses"
             ]
           }
@@ -29967,7 +29967,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "read:statuses"
             ]
           }
@@ -30356,7 +30356,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "read:statuses"
             ]
           }
@@ -30571,7 +30571,7 @@
         },
         "security": [
           {
-            "OAuth2ClientCredentials": [
+            "OAuth2": [
               "read:statuses"
             ]
           }
@@ -39193,11 +39193,11 @@
     "securitySchemes": {
       "OAuth2": {
         "type": "oauth2",
-        "description": "OAuth 2.0 authentication for user tokens (authorization code flow)",
+        "description": "OAuth 2.0 authentication",
         "flows": {
           "authorizationCode": {
-            "authorizationUrl": "https://mastodon.example/oauth/authorize",
-            "tokenUrl": "https://mastodon.example/oauth/token",
+            "authorizationUrl": "/oauth/authorize",
+            "tokenUrl": "/oauth/token",
             "scopes": {
               "profile": "Access to the current user profile information only",
               "read": "Read access",
@@ -39245,15 +39245,9 @@
               "admin:write:ip_blocks": "Administrative write access to ip_blocks",
               "admin:write:reports": "Administrative write access to reports"
             }
-          }
-        }
-      },
-      "OAuth2ClientCredentials": {
-        "type": "oauth2",
-        "description": "OAuth 2.0 authentication for app tokens (client credentials flow)",
-        "flows": {
+          },
           "clientCredentials": {
-            "tokenUrl": "https://mastodon.example/oauth/token",
+            "tokenUrl": "/oauth/token",
             "scopes": {
               "read": "Read access",
               "write": "Write access",
diff --git a/src/__tests__/generators/MethodConverter.bearer-token-security.test.ts b/src/__tests__/generators/MethodConverter.bearer-token-security.test.ts
@@ -31,12 +31,12 @@ describe('MethodConverter Bearer Token Security', () => {
             description: 'OAuth 2.0 authentication',
             flows: {
               authorizationCode: {
-                authorizationUrl: 'https://mastodon.example/oauth/authorize',
-                tokenUrl: 'https://mastodon.example/oauth/token',
+                authorizationUrl: '/oauth/authorize',
+                tokenUrl: '/oauth/token',
                 scopes: {},
               },
               clientCredentials: {
-                tokenUrl: 'https://mastodon.example/oauth/token',
+                tokenUrl: '/oauth/token',
                 scopes: {},
               },
             },
@@ -143,10 +143,8 @@ describe('MethodConverter Bearer Token Security', () => {
 
       const operation = spec.paths['/api/v1/accounts']?.post;
       expect(operation).toBeDefined();
-      // Should require app token (client credentials flow)
-      expect(operation?.security).toEqual([
-        { OAuth2ClientCredentials: ['write:accounts'] },
-      ]);
+      // Should require app token (client credentials flow via OAuth2 security scheme)
+      expect(operation?.security).toEqual([{ OAuth2: ['write:accounts'] }]);
     });
 
     test('should handle app token with multiple scopes', () => {
@@ -163,7 +161,7 @@ describe('MethodConverter Bearer Token Security', () => {
       const operation = spec.paths['/api/v1/admin/action']?.post;
       expect(operation).toBeDefined();
       expect(operation?.security).toEqual([
-        { OAuth2ClientCredentials: ['admin:write', 'write:accounts'] },
+        { OAuth2: ['admin:write', 'write:accounts'] },
       ]);
     });
   });
@@ -182,11 +180,8 @@ describe('MethodConverter Bearer Token Security', () => {
 
       const operation = spec.paths['/api/v1/flexible']?.get;
       expect(operation).toBeDefined();
-      // Should support both user token and app token
-      expect(operation?.security).toEqual([
-        { OAuth2: ['read'] }, // User token
-        { OAuth2ClientCredentials: ['read'] }, // App token
-      ]);
+      // Mixed token types use the same OAuth2 security scheme with both flows available
+      expect(operation?.security).toEqual([{ OAuth2: ['read'] }]);
     });
 
     test('should handle token without scopes', () => {
diff --git a/src/__tests__/generators/SpecBuilder.test.ts b/src/__tests__/generators/SpecBuilder.test.ts
@@ -123,5 +123,76 @@ describe('SpecBuilder', () => {
         /\(https:\/\/github\.com\/mastodon\/documentation\/commit\/test123commit456\)\./
       );
     });
+
+    it('should have a single OAuth2 security scheme with both flows', () => {
+      const mockConfig = {
+        mastodonDocsCommit: 'test123commit456',
+      };
+
+      mockReadFileSync.mockReturnValue(JSON.stringify(mockConfig));
+
+      const spec = specBuilder.buildInitialSpec();
+
+      // Check that there is only one OAuth2 security scheme
+      expect(spec.components?.securitySchemes).toBeDefined();
+      expect(spec.components?.securitySchemes?.OAuth2).toBeDefined();
+      expect(
+        spec.components?.securitySchemes?.OAuth2ClientCredentials
+      ).toBeUndefined();
+
+      // Check the OAuth2 security scheme has both flows
+      const oauth2 = spec.components?.securitySchemes?.OAuth2 as any;
+      expect(oauth2.type).toBe('oauth2');
+      expect(oauth2.description).toBe('OAuth 2.0 authentication');
+      expect(oauth2.flows?.authorizationCode).toBeDefined();
+      expect(oauth2.flows?.clientCredentials).toBeDefined();
+    });
+
+    it('should use path-only URLs for OAuth2 flows', () => {
+      const mockConfig = {
+        mastodonDocsCommit: 'test123commit456',
+      };
+
+      mockReadFileSync.mockReturnValue(JSON.stringify(mockConfig));
+
+      const spec = specBuilder.buildInitialSpec();
+
+      const oauth2 = spec.components?.securitySchemes?.OAuth2 as any;
+
+      // Check authorizationCode flow URLs are path-only
+      expect(oauth2.flows?.authorizationCode?.authorizationUrl).toBe(
+        '/oauth/authorize'
+      );
+      expect(oauth2.flows?.authorizationCode?.tokenUrl).toBe('/oauth/token');
+
+      // Check clientCredentials flow URL is path-only
+      expect(oauth2.flows?.clientCredentials?.tokenUrl).toBe('/oauth/token');
+    });
+
+    it('should include scopes for both OAuth2 flows', () => {
+      const mockConfig = {
+        mastodonDocsCommit: 'test123commit456',
+      };
+
+      mockReadFileSync.mockReturnValue(JSON.stringify(mockConfig));
+
+      const spec = specBuilder.buildInitialSpec();
+
+      const oauth2 = spec.components?.securitySchemes?.OAuth2 as any;
+
+      // Check authorizationCode flow has scopes (from mock: read, write)
+      expect(oauth2.flows?.authorizationCode?.scopes).toBeDefined();
+      expect(oauth2.flows?.authorizationCode?.scopes.read).toBe('Read access');
+      expect(oauth2.flows?.authorizationCode?.scopes.write).toBe(
+        'Write access'
+      );
+
+      // Check clientCredentials flow has scopes
+      expect(oauth2.flows?.clientCredentials?.scopes).toBeDefined();
+      expect(oauth2.flows?.clientCredentials?.scopes.read).toBe('Read access');
+      expect(oauth2.flows?.clientCredentials?.scopes.write).toBe(
+        'Write access'
+      );
+    });
   });
 });
diff --git a/src/generators/MethodConverter.ts b/src/generators/MethodConverter.ts
@@ -1009,13 +1009,13 @@ class MethodConverter {
 
       case 'app':
         // Required app token (client credentials flow)
-        securityRequirements.push({ OAuth2ClientCredentials: config.scopes });
+        securityRequirements.push({ OAuth2: config.scopes });
         break;
 
       case 'mixed':
-        // Supports both user and app tokens
-        securityRequirements.push({ OAuth2: config.scopes }); // User token
-        securityRequirements.push({ OAuth2ClientCredentials: config.scopes }); // App token
+        // Supports both user and app tokens - both use the same OAuth2 security scheme
+        // with different flows (authorizationCode for user tokens, clientCredentials for app tokens)
+        securityRequirements.push({ OAuth2: config.scopes });
         break;
 
       case 'unknown':
diff --git a/src/generators/SpecBuilder.ts b/src/generators/SpecBuilder.ts
@@ -92,23 +92,15 @@ class SpecBuilder {
         securitySchemes: {
           OAuth2: {
             type: 'oauth2',
-            description:
-              'OAuth 2.0 authentication for user tokens (authorization code flow)',
+            description: 'OAuth 2.0 authentication',
             flows: {
               authorizationCode: {
-                authorizationUrl: 'https://mastodon.example/oauth/authorize',
-                tokenUrl: 'https://mastodon.example/oauth/token',
+                authorizationUrl: '/oauth/authorize',
+                tokenUrl: '/oauth/token',
                 scopes: scopesObject,
               },
-            },
-          },
-          OAuth2ClientCredentials: {
-            type: 'oauth2',
-            description:
-              'OAuth 2.0 authentication for app tokens (client credentials flow)',
-            flows: {
               clientCredentials: {
-                tokenUrl: 'https://mastodon.example/oauth/token',
+                tokenUrl: '/oauth/token',
                 scopes: clientCredentialsScopes,
               },
             },

Original file line number	Diff line number	Diff line change
`@@ -156,7 +156,7 @@`
`156`	`156`	`},`
`157`	`157`	`"security": [`
`158`	`158`	`{`
`159`		`- "OAuth2ClientCredentials": [`
	`159`	`+ "OAuth2": [`
`160`	`160`	`"write:accounts"`
`161`	`161`	`]`
`162`	`162`	`}`
`@@ -5552,7 +5552,7 @@`
`5552`	`5552`	`},`
`5553`	`5553`	`"security": [`
`5554`	`5554`	`{`
`5555`		`- "OAuth2ClientCredentials": []`
	`5555`	`+ "OAuth2": []`
`5556`	`5556`	`}`
`5557`	`5557`	`]`
`5558`	`5558`	`}`
`@@ -25644,7 +25644,7 @@`
`25644`	`25644`	`},`
`25645`	`25645`	`"security": [`
`25646`	`25646`	`{`
`25647`		`- "OAuth2ClientCredentials": [`
	`25647`	`+ "OAuth2": [`
`25648`	`25648`	`"read:statuses"`
`25649`	`25649`	`]`
`25650`	`25650`	`}`
`@@ -25807,7 +25807,7 @@`
`25807`	`25807`	`},`
`25808`	`25808`	`"security": [`
`25809`	`25809`	`{`
`25810`		`- "OAuth2ClientCredentials": [`
	`25810`	`+ "OAuth2": [`
`25811`	`25811`	`"read:statuses"`
`25812`	`25812`	`]`
`25813`	`25813`	`}`
`@@ -29967,7 +29967,7 @@`
`29967`	`29967`	`},`
`29968`	`29968`	`"security": [`
`29969`	`29969`	`{`
`29970`		`- "OAuth2ClientCredentials": [`
	`29970`	`+ "OAuth2": [`
`29971`	`29971`	`"read:statuses"`
`29972`	`29972`	`]`
`29973`	`29973`	`}`
`@@ -30356,7 +30356,7 @@`
`30356`	`30356`	`},`
`30357`	`30357`	`"security": [`
`30358`	`30358`	`{`
`30359`		`- "OAuth2ClientCredentials": [`
	`30359`	`+ "OAuth2": [`
`30360`	`30360`	`"read:statuses"`
`30361`	`30361`	`]`
`30362`	`30362`	`}`
`@@ -30571,7 +30571,7 @@`
`30571`	`30571`	`},`
`30572`	`30572`	`"security": [`
`30573`	`30573`	`{`
`30574`		`- "OAuth2ClientCredentials": [`
	`30574`	`+ "OAuth2": [`
`30575`	`30575`	`"read:statuses"`
`30576`	`30576`	`]`
`30577`	`30577`	`}`
`@@ -39193,11 +39193,11 @@`
`39193`	`39193`	`"securitySchemes": {`
`39194`	`39194`	`"OAuth2": {`
`39195`	`39195`	`"type": "oauth2",`
`39196`		`- "description": "OAuth 2.0 authentication for user tokens (authorization code flow)",`
	`39196`	`+ "description": "OAuth 2.0 authentication",`
`39197`	`39197`	`"flows": {`
`39198`	`39198`	`"authorizationCode": {`
`39199`		`- "authorizationUrl": "https://mastodon.example/oauth/authorize",`
`39200`		`- "tokenUrl": "https://mastodon.example/oauth/token",`
	`39199`	`+ "authorizationUrl": "/oauth/authorize",`
	`39200`	`+ "tokenUrl": "/oauth/token",`
`39201`	`39201`	`"scopes": {`
`39202`	`39202`	`"profile": "Access to the current user profile information only",`
`39203`	`39203`	`"read": "Read access",`
`@@ -39245,15 +39245,9 @@`
`39245`	`39245`	`"admin:write:ip_blocks": "Administrative write access to ip_blocks",`
`39246`	`39246`	`"admin:write:reports": "Administrative write access to reports"`
`39247`	`39247`	`}`
`39248`		`- }`
`39249`		`- }`
`39250`		`- },`
`39251`		`- "OAuth2ClientCredentials": {`
`39252`		`- "type": "oauth2",`
`39253`		`- "description": "OAuth 2.0 authentication for app tokens (client credentials flow)",`
`39254`		`- "flows": {`
	`39248`	`+ },`
`39255`	`39249`	`"clientCredentials": {`
`39256`		`- "tokenUrl": "https://mastodon.example/oauth/token",`
	`39250`	`+ "tokenUrl": "/oauth/token",`
`39257`	`39251`	`"scopes": {`
`39258`	`39252`	`"read": "Read access",`
`39259`	`39253`	`"write": "Write access",`