Allow for scope descriptions

This makes a small change to the code introduced in #849 to allow for models to be used as OAuth scopes.
Without this check, an object like `{value: "foo", description: "bar"}` gets wrapped in an additional `value` key.
When the OpenAPI3 emitter tries to print out the `securitySchemes`, it sees `{value: {...}}` and produces a scope with value `[object Object]` and no description.

This also introduces a base `SecurityScheme` model that allows for more specific type checking on the `@useAuth` decorator.

We need to remove an `openapi3` test that checks for an error when providing an unsupported auth type.
Now the compiler enforces that the auth type is `AuthType`, and `openapi3` supports all of the types in `AuthType`, it should not be possible to trigger this condition in TSP.

Author: steverice

.chronus/changes/fix-allow-scope-descriptions-2025-11-2-12-5-39.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http"
+---
+
+Allow for OAuth2 scopes to be properly specified with descriptions

packages/http/lib/auth.tsp

@@ -1,5 +1,9 @@
 namespace TypeSpec.Http;
 
+model SecurityScheme {
+  type: AuthType;
+}
+
 @doc("Authentication type")
 enum AuthType {
   @doc("HTTP")
@@ -27,7 +31,7 @@ enum AuthType {
  * ```
  */
 @doc("")
-model BasicAuth {
+model BasicAuth extends SecurityScheme {
   @doc("Http authentication")
   type: AuthType.http;
 
@@ -44,7 +48,7 @@ model BasicAuth {
  * ```
  */
 @doc("")
-model BearerAuth {
+model BearerAuth extends SecurityScheme {
   @doc("Http authentication")
   type: AuthType.http;
 
@@ -89,7 +93,7 @@ enum ApiKeyLocation {
  * @template Name The name of the API key
  */
 @doc("")
-model ApiKeyAuth<Location extends ApiKeyLocation, Name extends string> {
+model ApiKeyAuth<Location extends ApiKeyLocation, Name extends string> extends SecurityScheme {
   @doc("API key authentication")
   type: AuthType.apiKey;
 
@@ -100,6 +104,16 @@ model ApiKeyAuth<Location extends ApiKeyLocation, Name extends string> {
   name: Name;
 }
 
+model OAuth2Scope {
+  @doc("The scope identifier")
+  value: string;
+
+  @doc("A description of the scope")
+  description?: string;
+}
+
+alias ScopeList = string[] | OAuth2Scope[];
+
 /**
  * OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
  *
@@ -111,7 +125,7 @@ model ApiKeyAuth<Location extends ApiKeyLocation, Name extends string> {
  * @template Scopes The list of OAuth2 scopes, which are common for every flow from `Flows`. This list is combined with the scopes defined in specific OAuth2 flows.
  */
 @doc("")
-model OAuth2Auth<Flows extends OAuth2Flow[], Scopes extends string[] = []> {
+model OAuth2Auth<Flows extends OAuth2Flow[], Scopes extends ScopeList = []> extends SecurityScheme {
   @doc("OAuth2 authentication")
   type: AuthType.oauth2;
 
@@ -154,7 +168,7 @@ model AuthorizationCodeFlow {
   refreshUrl?: string;
 
   @doc("list of scopes for the credential")
-  scopes?: string[];
+  scopes?: ScopeList;
 }
 
 @doc("Implicit flow")
@@ -169,7 +183,7 @@ model ImplicitFlow {
   refreshUrl?: string;
 
   @doc("list of scopes for the credential")
-  scopes?: string[];
+  scopes?: ScopeList;
 }
 
 @doc("Resource Owner Password flow")
@@ -184,7 +198,7 @@ model PasswordFlow {
   refreshUrl?: string;
 
   @doc("list of scopes for the credential")
-  scopes?: string[];
+  scopes?: ScopeList;
 }
 
 @doc("Client credentials flow")
@@ -199,7 +213,7 @@ model ClientCredentialsFlow {
   refreshUrl?: string;
 
   @doc("list of scopes for the credential")
-  scopes?: string[];
+  scopes?: ScopeList;
 }
 
 /**
@@ -212,7 +226,7 @@ model ClientCredentialsFlow {
  * https://server.com/.well-known/openid-configuration
  * ```
  */
-model OpenIdConnectAuth<ConnectUrl extends string> {
+model OpenIdConnectAuth<ConnectUrl extends string> extends SecurityScheme {
   /** Auth type */
   type: AuthType.openIdConnect;
 
@@ -225,6 +239,6 @@ model OpenIdConnectAuth<ConnectUrl extends string> {
  * It might be useful when overriding authentication on interface of operation level.
  */
 @doc("")
-model NoAuth {
+model NoAuth extends SecurityScheme {
   type: AuthType.noAuth;
 }

packages/http/lib/decorators.tsp

@@ -374,7 +374,10 @@ extern dec server(
  * namespace PetStore;
  * ```
  */
-extern dec useAuth(target: Namespace | Interface | Operation, auth: {} | Union | {}[]);
+extern dec useAuth(
+  target: Namespace | Interface | Operation,
+  auth: SecurityScheme | Union | SecurityScheme[]
+);
 
 /**
  * Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)

packages/http/src/decorators.ts

@@ -52,6 +52,9 @@ import {
   HttpStatusCodeRange,
   HttpStatusCodes,
   HttpVerb,
+  OAuth2Flow,
+  OAuth2Scope,
+  Oauth2Auth,
   PathParameterOptions,
   QueryParameterOptions,
 } from "./types.js";
@@ -621,7 +624,11 @@ function extractHttpAuthentication(
   ];
 }
 
-function extractOAuth2Auth(modelType: Model, data: any): HttpAuth {
+function normalizeScope(scope: string | OAuth2Scope): OAuth2Scope {
+  return typeof scope === "string" ? { value: scope } : scope;
+}
+
+function extractOAuth2Auth(modelType: Model, data: any): Oauth2Auth<OAuth2Flow[]> {
   // Validation of OAuth2Flow models in this function is minimal because the
   // type system already validates whether the model represents a flow
   // configuration.  This code merely avoids runtime errors.
@@ -630,16 +637,19 @@ function extractOAuth2Auth(modelType: Model, data: any): HttpAuth {
       ? data.flows
       : [];
 
-  const defaultScopes = Array.isArray(data.defaultScopes) ? data.defaultScopes : [];
+  const defaultScopes: Array<string | OAuth2Scope> = Array.isArray(data.defaultScopes)
+    ? data.defaultScopes
+    : [];
+
   return {
     id: data.id,
     type: data.type,
     model: modelType,
-    flows: flows.map((flow: any) => {
-      const scopes: Array<string> = flow.scopes ? flow.scopes : defaultScopes;
+    flows: flows.map((flow: OAuth2Flow) => {
+      const scopes = flow.scopes ? flow.scopes : defaultScopes;
       return {
         ...flow,
-        scopes: scopes.map((x: string) => ({ value: x })),
+        scopes: scopes.map(normalizeScope),
       };
     }),
   };

packages/http/test/http-decorators.test.ts

@@ -897,6 +897,47 @@ describe("http: decorators", () => {
       });
     });
 
+    it("can specify OAuth2 with object scopes", async () => {
+      const { Foo, program } = await Tester.compile(t.code`
+        model MyFlow {
+          type: OAuth2FlowType.implicit;
+          authorizationUrl: "https://api.example.com/oauth2/authorize";
+          refreshUrl: "https://api.example.com/oauth2/refresh";
+          scopes: [
+            {value: "read", description: "read data"},
+            {value: "write", description: "write data"},
+          ];
+        }
+        @useAuth(OAuth2Auth<[MyFlow]>)
+        namespace ${t.namespace("Foo")} {}
+      `);
+
+      expect(getAuthentication(program, Foo)).toEqual({
+        options: [
+          {
+            schemes: [
+              {
+                id: "OAuth2Auth",
+                type: "oauth2",
+                flows: [
+                  {
+                    type: "implicit",
+                    authorizationUrl: "https://api.example.com/oauth2/authorize",
+                    refreshUrl: "https://api.example.com/oauth2/refresh",
+                    scopes: [
+                      { value: "read", description: "read data" },
+                      { value: "write", description: "write data" },
+                    ],
+                  },
+                ],
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
+          },
+        ],
+      });
+    });
+
     it("can specify OAuth2 with scopes, which are default for every flow", async () => {
       const { Foo, program } = await Tester.compile(t.code`
         alias MyAuth<T extends string[]> = OAuth2Auth<Flows=[{

packages/openapi3/test/security.test.ts

@@ -247,19 +247,6 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => {
     deepStrictEqual(res.security, [{ OpenIdConnectAuth: [] }]);
   });
 
-  it("set a unsupported auth", async () => {
-    const diagnostics = await diagnoseOpenApiFor(
-      `
-      @service
-      @useAuth({})
-      namespace MyService {}
-      `,
-    );
-    expectDiagnostics(diagnostics, {
-      code: "@typespec/openapi3/unsupported-auth",
-    });
-  });
-
   it("can specify custom auth name with description", async () => {
     const res = await openApiFor(
       `