@scalar/mock-server 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/mock-server
 
+## 0.14.3
+
+## 0.14.2
+
+### Patch Changes
+
+- [#10179](https://github.com/scalar/scalar/pull/10179): Serve OAuth2 authorization server metadata at the declared oauth2MetadataUrl, advertising local mock endpoints and the configured grants and scopes.
+
+  Normalize absolute OAuth token URLs to route paths when registering mock authentication routes.
+
+- [#10179](https://github.com/scalar/scalar/pull/10179): Warn when OAuth2 metadata routes collide with declared API paths. Keep the OAuth2 metadata field in OpenAPI 3.2 schemas and document the HTTP exception for local development.
+
 ## 0.14.1
 
 ### Patch Changes

package/dist/utils/get-oauth2-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+/** The RFC8414 fields exposed by the mock authorization server. */
+type OAuth2Metadata = {
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    scopes_supported: string[];
+};
+/** Advertises local mock endpoints instead of sending clients to the real authorization server. */
+export declare const getOAuth2Metadata: (flows: OpenAPIV3_2.OAuth2SecurityScheme["flows"], origin: string) => OAuth2Metadata;
+export {};
+//# sourceMappingURL=get-oauth2-metadata.d.ts.map

package/dist/utils/get-oauth2-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-oauth2-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/get-oauth2-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,mEAAmE;AACnE,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wBAAwB,EAAE,MAAM,EAAE,CAAA;IAClC,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,QAAQ,MAAM,KAAG,cAqBpG,CAAA"}

package/dist/utils/get-oauth2-metadata.js

@@ -0,0 +1,23 @@
+import { getPathFromUrl } from './get-open-auth-token-urls.js';
+/** Advertises local mock endpoints instead of sending clients to the real authorization server. */
+export const getOAuth2Metadata = (flows, origin) => {
+    const authorizationFlow = flows?.authorizationCode ?? flows?.implicit;
+    const tokenFlow = flows?.authorizationCode ?? flows?.clientCredentials ?? flows?.password;
+    const localUrl = (url) => new URL(getPathFromUrl(url), origin).href;
+    const supportedFlows = [
+        { flow: flows?.authorizationCode, grant: 'authorization_code', response: 'code' },
+        { flow: flows?.implicit, grant: 'implicit', response: 'token' },
+        { flow: flows?.clientCredentials, grant: 'client_credentials' },
+        { flow: flows?.password, grant: 'password' },
+    ].filter(({ flow }) => flow);
+    return {
+        issuer: origin,
+        ...(authorizationFlow
+            ? { authorization_endpoint: localUrl(authorizationFlow.authorizationUrl ?? '/oauth/authorize') }
+            : {}),
+        ...(tokenFlow ? { token_endpoint: localUrl(tokenFlow.tokenUrl ?? '/oauth/token') } : {}),
+        response_types_supported: supportedFlows.flatMap(({ response }) => (response ? [response] : [])),
+        grant_types_supported: supportedFlows.map(({ grant }) => grant),
+        scopes_supported: [...new Set(supportedFlows.flatMap(({ flow }) => Object.keys(flow?.scopes ?? {})))],
+    };
+};

package/dist/utils/get-open-auth-token-urls.d.ts

@@ -1,7 +1,10 @@
 import type { OpenAPI } from '@scalar/openapi-types';
 /**
- * Extract path from URL
+ * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
+ * preserve trailing slashes instead of using the token-route normalization.
  */
-export declare function getPathFromUrl(url: string): string;
+export declare function getPathFromUrl(url: string, { preserveTrailingSlash }?: {
+    preserveTrailingSlash?: boolean;
+}): string;
 export declare function getOpenAuthTokenUrls(schema?: OpenAPI.Document): string[];
 //# sourceMappingURL=get-open-auth-token-urls.d.ts.map

package/dist/utils/get-open-auth-token-urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}
+{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,EAAE,qBAA6B,EAAE,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,MAAM,CAYR;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}

package/dist/utils/get-open-auth-token-urls.js

@@ -1,14 +1,15 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 /**
- * Extract path from URL
+ * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
+ * preserve trailing slashes instead of using the token-route normalization.
  */
-export function getPathFromUrl(url) {
+export function getPathFromUrl(url, { preserveTrailingSlash = false } = {}) {
     try {
         // Handle relative URLs by prepending a base
         const urlObject = url.startsWith('http') ? new URL(url) : new URL(url, 'http://example.com');
         // Normalize: remove trailing slash except for root path
         const path = urlObject.pathname;
-        return path === '/' ? path : path.replace(/\/$/, '');
+        return preserveTrailingSlash || path === '/' ? path : path.replace(/\/$/, '');
     }
     catch {
         // If URL is invalid, return the original string

package/dist/utils/log-authentication-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAwHpD"}
+{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAiIpD"}

package/dist/utils/log-authentication-instructions.js

@@ -66,6 +66,13 @@ export function logAuthenticationInstructions(securitySchemes, log = (line) => c
                 }
                 break;
             case 'oauth2':
+                if ('oauth2MetadataUrl' in scheme &&
+                    typeof scheme.oauth2MetadataUrl === 'string' &&
+                    scheme.oauth2MetadataUrl.trim()) {
+                    log('✅ OAuth 2.0 Authorization Server Metadata');
+                    log(`   GET ${getPathFromUrl(scheme.oauth2MetadataUrl, { preserveTrailingSlash: true })}`);
+                    log('');
+                }
                 if (scheme.flows) {
                     Object.keys(scheme.flows).forEach((flow) => {
                         switch (flow) {

package/dist/utils/set-up-authentication-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAOhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QAmG7E"}
+{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QA+G7E"}

package/dist/utils/set-up-authentication-routes.js

@@ -1,6 +1,7 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { respondWithAuthorizePage } from '../routes/respond-with-authorize-page.js';
 import { respondWithToken } from '../routes/respond-with-token.js';
+import { getOAuth2Metadata } from './get-oauth2-metadata.js';
 import { getOpenAuthTokenUrls, getPathFromUrl } from './get-open-auth-token-urls.js';
 /**
  * Helper function to set up authentication routes for OAuth 2.0 flows
@@ -36,11 +37,20 @@ export function setUpAuthenticationRoutes(app, schema) {
             return;
         }
         if (scheme.type === 'oauth2') {
+            if ('oauth2MetadataUrl' in scheme &&
+                typeof scheme.oauth2MetadataUrl === 'string' &&
+                scheme.oauth2MetadataUrl.trim()) {
+                const metadataPath = getPathFromUrl(scheme.oauth2MetadataUrl, { preserveTrailingSlash: true });
+                if (schema?.paths && Object.hasOwn(schema.paths, metadataPath)) {
+                    console.warn(`OAuth2 metadata route "${metadataPath}" collides with a declared API path.`);
+                }
+                app.get(metadataPath, (c) => c.json(getOAuth2Metadata(scheme.flows, new URL(c.req.url).origin)));
+            }
             if (scheme.flows?.authorizationCode) {
                 const authorizeRoute = scheme.flows.authorizationCode.authorizationUrl ?? '/oauth/authorize';
                 const tokenRoute = scheme.flows.authorizationCode.tokenUrl ?? '/oauth/token';
                 authorizeUrls.add(getPathFromUrl(authorizeRoute));
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
             if (scheme.flows?.implicit) {
                 const authorizeRoute = scheme.flows.implicit.authorizationUrl ?? '/oauth/authorize';
@@ -48,11 +58,11 @@ export function setUpAuthenticationRoutes(app, schema) {
             }
             if (scheme.flows?.password) {
                 const tokenRoute = scheme.flows.password.tokenUrl ?? '/oauth/token';
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
             if (scheme.flows?.clientCredentials) {
                 const tokenRoute = scheme.flows.clientCredentials.tokenUrl ?? '/oauth/token';
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
         }
         else if (scheme.type === 'openIdConnect') {
@@ -74,7 +84,7 @@ export function setUpAuthenticationRoutes(app, schema) {
                 const authorizeRoute = '/oauth/authorize';
                 const tokenRoute = '/oauth/token';
                 authorizeUrls.add(getPathFromUrl(authorizeRoute));
-                tokenUrls.add(tokenRoute);
+                tokenUrls.add(getPathFromUrl(tokenRoute));
             }
         }
     });

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.14.1",
+  "version": "0.14.3",
   "engines": {
     "node": ">=22"
   },
@@ -53,17 +53,17 @@
   "dependencies": {
     "@faker-js/faker": "10.4.0",
     "@hono/node-ws": "^1.2.0",
+    "@scalar/helpers": "0.12.0",
+    "@scalar/json-magic": "0.14.0",
+    "@scalar/openapi-types": "0.9.6",
+    "@scalar/openapi-upgrader": "0.2.17",
+    "@scalar/types": "0.20.0",
+    "@scalar/workspace-store": "0.63.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "hono": "^4.13.7",
     "quickjs-emscripten": "0.32.0",
-    "yaml": "^2.9.0",
-    "@scalar/helpers": "0.12.0",
-    "@scalar/json-magic": "0.13.5",
-    "@scalar/openapi-types": "0.9.6",
-    "@scalar/openapi-upgrader": "0.2.16",
-    "@scalar/workspace-store": "0.61.0",
-    "@scalar/types": "0.20.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",