Operation level authentication and scopes

Resolves microsoft#2624

docs/libraries/http/reference/data-types.md

@@ -174,6 +174,15 @@ The URL of the requested resource has been changed permanently. The new URL is g
 model TypeSpec.Http.MovedResponse
 ```
 
+### `NoAuth` {#TypeSpec.Http.NoAuth}
+
+This authentication option signifies that API is not secured at all.
+It might be useful when overriding authentication on interface of operation level.
+
+```typespec
+model TypeSpec.Http.NoAuth
+```
+
 ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}
 
 There is no content to send for this request, but the headers may be useful.

docs/libraries/http/reference/decorators.md

@@ -402,15 +402,15 @@ op create(): {@statusCode: 201 | 202}
 
 ### `@useAuth` {#@TypeSpec.Http.useAuth}
 
-Specify this service authentication. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
+Specify authentication for a whole service or specific methods. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
 
 ```typespec
 @TypeSpec.Http.useAuth(auth: {} | Union | {}[])
 ```
 
 #### Target
 
-`Namespace`
+`union Namespace | Interface | Operation`
 
 #### Parameters
 

docs/libraries/http/reference/index.mdx

@@ -69,6 +69,7 @@ npm install --save-peer @typespec/http
 - [`ImplicitFlow`](./data-types.md#TypeSpec.Http.ImplicitFlow)
 - [`LocationHeader`](./data-types.md#TypeSpec.Http.LocationHeader)
 - [`MovedResponse`](./data-types.md#TypeSpec.Http.MovedResponse)
+- [`NoAuth`](./data-types.md#TypeSpec.Http.NoAuth)
 - [`NoContentResponse`](./data-types.md#TypeSpec.Http.NoContentResponse)
 - [`NotFoundResponse`](./data-types.md#TypeSpec.Http.NotFoundResponse)
 - [`NotModifiedResponse`](./data-types.md#TypeSpec.Http.NotModifiedResponse)

packages/http/README.md

@@ -447,15 +447,15 @@ op create(): {@statusCode: 201 | 202}
 
 #### `@useAuth`
 
-Specify this service authentication. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
+Specify authentication for a whole service or specific methods. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
 
 ```typespec
 @TypeSpec.Http.useAuth(auth: {} | Union | {}[])
 ```
 
 ##### Target
 
-`Namespace`
+`union Namespace | Interface | Operation`
 
 ##### Parameters
 

packages/http/lib/auth.tsp

@@ -13,6 +13,9 @@ enum AuthType {
 
   @doc("OpenID connect")
   openIdConnect,
+
+  @doc("Empty auth")
+  noAuth,
 }
 
 /**
@@ -212,3 +215,12 @@ model OpenIdConnectAuth<ConnectUrl extends valueof string> {
   /** Connect url. It can be specified relative to the server URL */
   openIdConnectUrl: ConnectUrl;
 }
+
+/**
+ * This authentication option signifies that API is not secured at all.
+ * It might be useful when overriding authentication on interface of operation level.
+ */
+@doc("")
+model NoAuth {
+  type: AuthType.noAuth;
+}

packages/http/lib/http-decorators.tsp

@@ -202,7 +202,7 @@ extern dec server(
 );
 
 /**
- * Specify this service authentication. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
+ * Specify authentication for a whole service or specific methods. See the [documentation in the Http library](https://typespec.io/docs/libraries/http/authentication) for full details.
  *
  * @param auth Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together)
  * @example
@@ -213,7 +213,7 @@ extern dec server(
  * namespace PetStore;
  * ```
  */
-extern dec useAuth(target: Namespace, auth: {} | Union | {}[]);
+extern dec useAuth(target: Namespace | Interface | Operation, auth: {} | Union | {}[]);
 
 /**
  * Specify if inapplicable metadata should be included in the payload for the given entity.

packages/http/src/auth.ts

@@ -0,0 +1,15 @@
+import { Operation, Program } from "@typespec/compiler";
+import { HttpStateKeys } from "./lib.js";
+import { Authentication } from "./types.js";
+
+export function getAuthenticationForOperation(
+  program: Program,
+  operation: Operation
+): Authentication | undefined {
+  const operationAuth = program.stateMap(HttpStateKeys.authentication).get(operation);
+  if (operationAuth === undefined && operation.interface !== undefined) {
+    const interfaceAuth = program.stateMap(HttpStateKeys.authentication).get(operation.interface);
+    return interfaceAuth;
+  }
+  return operationAuth;
+}

packages/http/src/decorators.ts

@@ -2,6 +2,7 @@ import {
   DecoratorContext,
   Diagnostic,
   DiagnosticTarget,
+  Interface,
   Model,
   ModelProperty,
   Namespace,
@@ -25,6 +26,7 @@ import { HttpStateKeys, createDiagnostic, reportDiagnostic } from "./lib.js";
 import { setRoute, setSharedRoute } from "./route.js";
 import { getStatusCodesFromType } from "./status-codes.js";
 import {
+  Authentication,
   AuthenticationOption,
   HeaderFieldOptions,
   HttpAuth,
@@ -33,7 +35,6 @@ import {
   HttpVerb,
   PathParameterOptions,
   QueryParameterOptions,
-  ServiceAuthentication,
 } from "./types.js";
 import { extractParamsFromPath } from "./utils.js";
 
@@ -432,28 +433,28 @@ setTypeSpecNamespace("Private", $plainData);
 
 export function $useAuth(
   context: DecoratorContext,
-  serviceNamespace: Namespace,
+  entity: Namespace | Interface | Operation,
   authConfig: Model | Union | Tuple
 ) {
-  const [auth, diagnostics] = extractServiceAuthentication(context.program, authConfig);
+  const [auth, diagnostics] = extractAuthentication(context.program, authConfig);
   if (diagnostics.length > 0) context.program.reportDiagnostics(diagnostics);
   if (auth !== undefined) {
-    setAuthentication(context.program, serviceNamespace, auth);
+    setAuthentication(context.program, entity, auth);
   }
 }
 
 export function setAuthentication(
   program: Program,
-  serviceNamespace: Namespace,
-  auth: ServiceAuthentication
+  entity: Namespace | Interface | Operation,
+  auth: Authentication
 ) {
-  program.stateMap(HttpStateKeys.authentication).set(serviceNamespace, auth);
+  program.stateMap(HttpStateKeys.authentication).set(entity, auth);
 }
 
-function extractServiceAuthentication(
+function extractAuthentication(
   program: Program,
   type: Model | Union | Tuple
-): [ServiceAuthentication | undefined, readonly Diagnostic[]] {
+): [Authentication | undefined, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
 
   switch (type.kind) {
@@ -473,7 +474,7 @@ function extractHttpAuthenticationOptions(
   program: Program,
   tuple: Union,
   diagnosticTarget: DiagnosticTarget
-): [ServiceAuthentication, readonly Diagnostic[]] {
+): [Authentication, readonly Diagnostic[]] {
   const options: AuthenticationOption[] = [];
   const diagnostics = createDiagnosticCollector();
   for (const variant of tuple.variants.values()) {
@@ -578,9 +579,9 @@ function extractOAuth2Auth(data: any): HttpAuth {
 
 export function getAuthentication(
   program: Program,
-  namespace: Namespace
-): ServiceAuthentication | undefined {
-  return program.stateMap(HttpStateKeys.authentication).get(namespace);
+  entity: Namespace | Interface | Operation
+): Authentication | undefined {
+  return program.stateMap(HttpStateKeys.authentication).get(entity);
 }
 
 /**

packages/http/src/operations.ts

@@ -15,6 +15,8 @@ import {
   Program,
   SyntaxKind,
 } from "@typespec/compiler";
+import { getAuthenticationForOperation } from "./auth.js";
+import { getAuthentication } from "./decorators.js";
 import { createDiagnostic, reportDiagnostic } from "./lib.js";
 import { getResponsesForOperation } from "./responses.js";
 import { isSharedRoute, resolvePathAndParameters } from "./route.js";
@@ -95,13 +97,15 @@ export function getHttpService(
       },
     })
   );
+  const authentication = getAuthentication(program, serviceNamespace);
 
   validateProgram(program, diagnostics);
   validateRouteUnique(program, diagnostics, httpOperations);
 
   const service: HttpService = {
     namespace: serviceNamespace,
     operations: httpOperations,
+    authentication: authentication,
   };
   return diagnostics.wrap(service);
 }
@@ -213,15 +217,17 @@ function getHttpOperationInternal(
     resolvePathAndParameters(program, operation, overloading, options ?? {})
   );
   const responses = diagnostics.pipe(getResponsesForOperation(program, operation));
+  const authentication = getAuthenticationForOperation(program, operation);
 
   const httpOperation: HttpOperation = {
     path: route.path,
     pathSegments: route.pathSegments,
     verb: route.parameters.verb,
     container: operation.interface ?? operation.namespace ?? program.getGlobalNamespaceType(),
     parameters: route.parameters,
-    operation,
     responses,
+    operation,
+    authentication,
   };
   Object.assign(httpOperationRef, httpOperation);
 

packages/http/src/types.ts

@@ -16,7 +16,7 @@ export type OperationDetails = HttpOperation;
 
 export type HttpVerb = "get" | "put" | "post" | "patch" | "delete" | "head";
 
-export interface ServiceAuthentication {
+export interface Authentication {
   /**
    * Either one of those options can be used independently to authenticate.
    */
@@ -35,7 +35,8 @@ export type HttpAuth =
   | BearerAuth
   | ApiKeyAuth<ApiKeyLocation, string>
   | Oauth2Auth<OAuth2Flow[]>
-  | OpenIDConnectAuth;
+  | OpenIDConnectAuth
+  | NoAuth;
 
 export interface HttpAuthBase {
   /**
@@ -184,6 +185,14 @@ export interface OpenIDConnectAuth extends HttpAuthBase {
   openIdConnectUrl: string;
 }
 
+/**
+ * This authentication option signifies that API is not secured at all.
+ * It might be useful when overriding authentication on interface of operation level.
+ */
+export interface NoAuth extends HttpAuthBase {
+  type: "noAuth";
+}
+
 export type OperationContainer = Namespace | Interface;
 
 export type OperationVerbSelector = (
@@ -287,6 +296,7 @@ export interface HttpOperationParameters {
 export interface HttpService {
   namespace: Namespace;
   operations: HttpOperation[];
+  authentication?: Authentication;
 }
 
 export interface HttpOperation {
@@ -325,6 +335,11 @@ export interface HttpOperation {
    */
   operation: Operation;
 
+  /**
+   * Operation authentication. Overrides HttpService authentication
+   */
+  authentication?: Authentication;
+
   /**
    * Overload this operation
    */

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

@@ -623,20 +623,6 @@ describe("http: decorators", () => {
   });
 
   describe("@useAuth", () => {
-    it("emit diagnostics when @useAuth is not used on namespace", async () => {
-      const diagnostics = await runner.diagnose(`
-          @useAuth(BasicAuth) op test(): string;
-        `);
-
-      expectDiagnostics(diagnostics, [
-        {
-          code: "decorator-wrong-target",
-          message:
-            "Cannot apply @useAuth decorator to test since it is not assignable to Namespace",
-        },
-      ]);
-    });
-
     it("emit diagnostics when config is not a model, tuple or union", async () => {
       const diagnostics = await runner.diagnose(`
           @useAuth(anOp)
@@ -792,6 +778,26 @@ describe("http: decorators", () => {
       });
     });
 
+    it("can specify NoAuth", async () => {
+      const { Foo } = (await runner.compile(`
+        @useAuth(NoAuth)
+        @test namespace Foo {}
+      `)) as { Foo: Namespace };
+
+      deepStrictEqual(getAuthentication(runner.program, Foo), {
+        options: [
+          {
+            schemes: [
+              {
+                id: "NoAuth",
+                type: "noAuth",
+              },
+            ],
+          },
+        ],
+      });
+    });
+
     it("can specify multiple auth options", async () => {
       const { Foo } = (await runner.compile(`
         @useAuth(BasicAuth | BearerAuth)
@@ -853,6 +859,50 @@ describe("http: decorators", () => {
         ],
       });
     });
+
+    it("can override auth schemes on interface", async () => {
+      const { Foo } = (await runner.compile(`
+        alias ServiceKeyAuth = ApiKeyAuth<ApiKeyLocation.header, "X-API-KEY">;
+        @useAuth(ServiceKeyAuth)
+        @test namespace Foo {
+          @useAuth(BasicAuth | BearerAuth)
+          interface Bar { }
+        }
+      `)) as { Foo: Namespace };
+
+      deepStrictEqual(getAuthentication(runner.program, Foo.interfaces.get("Bar")!), {
+        options: [
+          {
+            schemes: [{ id: "BasicAuth", type: "http", scheme: "basic" }],
+          },
+          {
+            schemes: [{ id: "BearerAuth", type: "http", scheme: "bearer" }],
+          },
+        ],
+      });
+    });
+
+    it("can override auth schemes on operation", async () => {
+      const { Foo } = (await runner.compile(`
+        alias ServiceKeyAuth = ApiKeyAuth<ApiKeyLocation.header, "X-API-KEY">;
+        @useAuth(ServiceKeyAuth)
+        @test namespace Foo {
+          @useAuth([BasicAuth, BearerAuth])
+          op bar(): void;
+        }
+      `)) as { Foo: Namespace };
+
+      deepStrictEqual(getAuthentication(runner.program, Foo.operations.get("bar")!), {
+        options: [
+          {
+            schemes: [
+              { id: "BasicAuth", type: "http", scheme: "basic" },
+              { id: "BearerAuth", type: "http", scheme: "bearer" },
+            ],
+          },
+        ],
+      });
+    });
   });
 
   describe("@visibility", () => {