interface authentication {
    use headers.{headers};
    use error.{error-response, error};
    use token.{token};
    use shared-context.{shared-context};

    /// An HTTP endpoint exposed publicly on the Gateway. This is typically used to return metadata for authentication purposes, for example with the [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) spec.
    record public-metadata-endpoint {
        /// The absolute path (without domain) of the endpoint. Example: "/.well-known/oauth-protected-resource".
        path: string,
        /// The contents of the response body that the endpoint will return.
        response-body: list<u8>,
        /// The headers sent from with the response by the public endpoint. Example: "Content-Type: application/json".
        response-headers: headers,
    }

    /// Authenticates a request using the provided headers.
    ///
    /// This function validates authentication credentials found in the request headers
    /// and returns an authentication token if successful.
    ///
    /// # Parameters
    /// - `headers`: Immutable HTTP headers
    ///
    /// # Returns
    /// - `Ok(token)`: Authentication successful, returns a valid token
    /// - `Err(error-response)`: Authentication failed, returns error details
    authenticate: func(
        context: shared-context,
        headers: headers,
    ) -> result<token, error-response>;

    /// Define endpoints on the gateway that expose authentication related metadata. This can be used to implement [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728), for example.
    ///
    /// See the docs on [`public-metadata-endpoint`](public-metadata-endpoint) for details.
    public-metadata: func() -> result<list<public-metadata-endpoint>, error>;
}
