auth.tsp

namespace TypeSpec.Http;

@doc("Authentication type")
enum AuthType {
  @doc("HTTP")
  http,

  @doc("API key")
  apiKey,

  @doc("OAuth2")
  oauth2,

  @doc("OpenID connect")
  openIdConnect,
}

/**
 *  Basic authentication is a simple authentication scheme built into the HTTP protocol.
 *  The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
 *  For example, to authorize as demo / `p@55w0rd` the client would send
 *  ```
 *  Authorization: Basic ZGVtbzpwQDU1dzByZA==
 *  ```
 */
@doc("")
model BasicAuth {
  @doc("Http authentication")
  type: AuthType.http;

  @doc("basic auth scheme")
  scheme: "basic";
}

/**
 * Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
 * The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request.
 * The client must send this token in the Authorization header when making requests to protected resources:
 * ```
 *   Authorization: Bearer <token>
 * ```
 */
@doc("")
model BearerAuth {
  @doc("Http authentication")
  type: AuthType.http;

  @doc("bearer auth scheme")
  scheme: "bearer";
}

@doc("Describes the location of the API key")
enum ApiKeyLocation {
  @doc("API key is a header value")
  header,

  @doc("API key is a query parameter")
  query,

  @doc("API key is found in a cookie")
  cookie,
}

/**
 * An API key is a token that a client provides when making API calls. The key can be sent in the query string:
 *
 * ```
 * GET /something?api_key=abcdef12345
 * ```
 *
 * or as a request header
 *
 * ```
 * GET /something HTTP/1.1
 * X-API-Key: abcdef12345
 * ```
 *
 * or as a cookie
 *
 * ```
 * GET /something HTTP/1.1
 * Cookie: X-API-KEY=abcdef12345
 * ```
 *
 * @template Location The location of the API key
 * @template Name The name of the API key
 */
@doc("")
model ApiKeyAuth<Location extends ApiKeyLocation, Name extends string> {
  @doc("API key authentication")
  type: AuthType.apiKey;

  @doc("location of the API key")
  in: Location;

  @doc("name of the API key")
  name: Name;
}

/**
 * OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
 *
 * OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials.
 * For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
 * For more information about OAuth 2.0, see oauth.net and RFC 6749.
 *
 * @template Flows The list of supported OAuth2 flows
 */
@doc("")
model OAuth2Auth<Flows extends OAuth2Flow[]> {
  @doc("OAuth2 authentication")
  type: AuthType.oauth2;

  @doc("Supported OAuth2 flows")
  flows: Flows;
}

@doc("Describes the OAuth2 flow type")
enum OAuth2FlowType {
  @doc("authorization code flow")
  authorizationCode,

  @doc("implcit flow")
  implicit,

  @doc("password flow")
  password,

  @doc("client credential flow")
  clientCredentials,
}

alias OAuth2Flow = AuthorizationCodeFlow | ImplicitFlow | PasswordFlow | ClientCredentialsFlow;

@doc("Authorization Code flow")
model AuthorizationCodeFlow {
  @doc("authorization code flow")
  type: OAuth2FlowType.authorizationCode;

  @doc("the authorization URL")
  authorizationUrl: string;

  @doc("the token URL")
  tokenUrl: string;

  @doc("the refresh URL")
  refreshUrl?: string;

  @doc("list of scopes for the credential")
  scopes: string[];
}

@doc("Implicit flow")
model ImplicitFlow {
  @doc("implicit flow")
  type: OAuth2FlowType.implicit;

  @doc("the authorization URL")
  authorizationUrl: string;

  @doc("the refresh URL")
  refreshUrl?: string;

  @doc("list of scopes for the credential")
  scopes: string[];
}

@doc("Resource Owner Password flow")
model PasswordFlow {
  @doc("password flow")
  type: OAuth2FlowType.password;

  @doc("the authorization URL")
  authorizationUrl: string;

  @doc("the refresh URL")
  refreshUrl?: string;

  @doc("list of scopes for the credential")
  scopes: string[];
}

@doc("Client credentials flow")
model ClientCredentialsFlow {
  @doc("client credential flow")
  type: OAuth2FlowType.clientCredentials;

  @doc("the token URL")
  tokenUrl: string;

  @doc("the refresh URL")
  refreshUrl?: string;

  @doc("list of scopes for the credential")
  scopes: string[];
}