fix: inject security information for server generated code (#88)

Author: dotkas

crates/oapi-codegen/src/emit/axum.rs

@@ -5,6 +5,7 @@ use quote::format_ident;
 use quote::quote;
 
 use crate::emit::doc_attr;
+use crate::emit::doc_lines;
 use crate::emit::emit_type;
 use crate::error::Result;
 use crate::ir::BodyKind;
@@ -23,6 +24,8 @@ use crate::ir::ResponseCase;
 use crate::ir::ResponseHeader;
 use crate::ir::ResponseStatus;
 use crate::ir::RustType;
+use crate::ir::SecurityScheme;
+use crate::ir::SecuritySchemeKind;
 use crate::ir::Service;
 use crate::naming::operations::axum_handler_name;
 
@@ -127,7 +130,7 @@ fn emit_trait(service: &Service) -> Result<TokenStream> {
     let mut methods = Vec::with_capacity(service.operations.len());
     for operation in &service.operations {
         let name = operation.name.to_token();
-        let doc = doc_attr(&operation.doc);
+        let doc = method_doc(operation, &service.security_schemes);
         let response = operation.response_enum.to_token();
         let args = emit_method_args(operation)?;
         methods.push(quote! {
@@ -143,6 +146,74 @@ fn emit_trait(service: &Service) -> Result<TokenStream> {
     });
 }
 
+/// The doc comment of a trait method: the operation's own description, then the
+/// security the document names for it.
+///
+/// The generator emits no check for that security, because verifying a
+/// credential needs application knowledge it does not have: which key, which
+/// issuer, and which claim names which user. Naming the schemes is what it can
+/// do, so an implementer does not have to read the document to tell a public
+/// operation from a protected one.
+fn method_doc(operation: &Operation, schemes: &[SecurityScheme]) -> TokenStream {
+    if operation.security.is_empty() {
+        return doc_attr(&operation.doc);
+    }
+
+    let mut lines: Vec<String> = Vec::new();
+    if let Some(text) = &operation.doc {
+        lines.push(text.clone());
+        lines.push(String::new());
+    }
+    lines.push("# Security".to_owned());
+    lines.push(String::new());
+    lines.push("The document names these security schemes for this operation:".to_owned());
+    lines.push(String::new());
+    for key in &operation.security {
+        lines.push(format!("- {}", requirement_line(key, schemes)));
+    }
+    lines.push(String::new());
+    if operation.security.len() > 1 {
+        // `security::required_keys` unions the alternatives and the
+        // conjunctions, so past one key the list no longer says which it was.
+        lines.push(
+            "This list is the union of every alternative the document gives, so it may be a choice between schemes rather than all of them. Read `security` in the document for the exact rule."
+                .to_owned(),
+        );
+        lines.push(String::new());
+    }
+    lines.push(
+        "This generator emits no check. Enforce it in a layer around the router: this method receives only the parameters the operation declares, not the credential."
+            .to_owned(),
+    );
+    return doc_lines(&lines);
+}
+
+/// One security scheme, named and located.
+///
+/// Where the credential sits is the part a server needs, because it has to read
+/// the credential itself.
+fn requirement_line(key: &str, schemes: &[SecurityScheme]) -> String {
+    let Some(scheme) = schemes.iter().find(|scheme| return scheme.key == key) else {
+        // The document names a scheme it never declares. The client rejects
+        // that; a server has nothing to reject, so the doc says what it knows.
+        return format!("`{key}`, which `components.securitySchemes` does not declare");
+    };
+    let location = match &scheme.kind {
+        SecuritySchemeKind::HttpBearer => "a bearer token in the `Authorization` header".to_owned(),
+        SecuritySchemeKind::HttpBasic => "basic credentials in the `Authorization` header".to_owned(),
+        SecuritySchemeKind::ApiKeyHeader(name) => format!("an API key in the `{name}` header"),
+        SecuritySchemeKind::ApiKeyQuery(name) => format!("an API key in the `{name}` query parameter"),
+        SecuritySchemeKind::ApiKeyCookie(name) => format!("an API key in the `{name}` cookie"),
+        // The reason held here is written for the client, which refuses to send
+        // such a credential. A server reads credentials rather than sending
+        // them, so the key alone is what this can honestly state.
+        SecuritySchemeKind::Unsupported(_) => {
+            return format!("`{key}`, a scheme this generator has no built-in support for");
+        }
+    };
+    return format!("`{key}`: {location}");
+}
+
 /// The typed arguments (path parameters, query struct, header struct, then JSON
 /// body) of an operation method.
 fn emit_method_args(operation: &Operation) -> Result<Vec<TokenStream>> {
@@ -892,3 +963,64 @@ fn request_content_type_test(kind: BodyKind) -> TokenStream {
         }
     };
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::naming::Case;
+    use crate::naming::to_ident;
+
+    fn scheme(key: &str, kind: SecuritySchemeKind) -> SecurityScheme {
+        return SecurityScheme {
+            key: key.to_owned(),
+            field: to_ident(key, Case::Snake),
+            kind,
+            doc: None,
+        };
+    }
+
+    #[test]
+    fn every_scheme_kind_says_where_the_credential_sits() {
+        let schemes = vec![
+            scheme("bearerAuth", SecuritySchemeKind::HttpBearer),
+            scheme("basicAuth", SecuritySchemeKind::HttpBasic),
+            scheme("headerKey", SecuritySchemeKind::ApiKeyHeader("X-API-Key".to_owned())),
+            scheme("queryKey", SecuritySchemeKind::ApiKeyQuery("api_key".to_owned())),
+            scheme("cookieKey", SecuritySchemeKind::ApiKeyCookie("SESSION".to_owned())),
+        ];
+        let cases = [
+            (
+                "bearerAuth",
+                "`bearerAuth`: a bearer token in the `Authorization` header",
+            ),
+            (
+                "basicAuth",
+                "`basicAuth`: basic credentials in the `Authorization` header",
+            ),
+            ("headerKey", "`headerKey`: an API key in the `X-API-Key` header"),
+            ("queryKey", "`queryKey`: an API key in the `api_key` query parameter"),
+            ("cookieKey", "`cookieKey`: an API key in the `SESSION` cookie"),
+        ];
+        for (key, expected) in cases {
+            assert_eq!(requirement_line(key, &schemes), expected);
+        }
+    }
+
+    /// The client rejects a scheme the document never declares. A server has
+    /// nothing to reject, so the note has to stand on the key alone.
+    #[test]
+    fn an_undeclared_scheme_is_still_named() {
+        let line = requirement_line("ghost", &[]);
+        assert_eq!(line, "`ghost`, which `components.securitySchemes` does not declare");
+    }
+
+    #[test]
+    fn an_unsupported_scheme_drops_the_client_side_reason() {
+        let schemes = vec![scheme(
+            "oauth2",
+            SecuritySchemeKind::Unsupported("the client cannot send this".to_owned()),
+        )];
+        let line = requirement_line("oauth2", &schemes);
+        assert_eq!(line, "`oauth2`, a scheme this generator has no built-in support for");
+    }
+}

crates/oapi-codegen/src/emit/mod.rs

@@ -224,6 +224,27 @@ pub(crate) fn doc_attr(doc: &Option<String>) -> TokenStream {
     return tokens;
 }
 
+/// Render one doc attribute per line, which rustdoc reads as one comment.
+///
+/// A blank line stays blank, so a caller can separate paragraphs with one. An
+/// entry that already holds line breaks, such as a multi-line `description` from
+/// the document, is split on them: a `#[doc]` carrying a `\n` prints as a
+/// `/** */` block, which would sit unevenly among its `///` siblings.
+pub(crate) fn doc_lines(lines: &[String]) -> TokenStream {
+    let attrs = lines.iter().flat_map(|entry| return entry.split('\n')).map(|line| {
+        // Leading space matches the `/// text` desugaring rustfmt produces. A
+        // blank line takes none, so no trailing space reaches the output.
+        let trimmed = line.trim_end();
+        let spaced = if trimmed.is_empty() {
+            String::new()
+        } else {
+            format!(" {trimmed}")
+        };
+        return quote! { #[doc = #spaced] };
+    });
+    return quote! { #(#attrs)* };
+}
+
 /// Render a Rust type expression.
 pub(crate) fn emit_type(ty: &RustType) -> Result<TokenStream> {
     let tokens = match ty {

crates/oapi-codegen/src/lower/security.rs

@@ -1,11 +1,12 @@
-//! Lowering OpenAPI security schemes and requirements into the client IR.
+//! Lowering OpenAPI security schemes and requirements into the IR.
 //!
 //! Only the shared lowering pass runs here: it catalogues the document's
 //! `components.securitySchemes` and resolves each operation's *effective*
-//! security requirement. The server emitter ignores the result (server-side
-//! auth is not generated yet). The client emitter turns supported schemes into
-//! credential fields and rejects operations that require an
-//! [`crate::ir::SecuritySchemeKind::Unsupported`] scheme.
+//! security requirement. Both emitters read the result. The client turns
+//! supported schemes into credential fields and rejects operations that require
+//! an [`crate::ir::SecuritySchemeKind::Unsupported`] scheme. The server names
+//! the requirement in each trait method's doc comment, but emits no check: only
+//! the application knows how to verify a credential.
 
 use openapiv3::APIKeyLocation;
 use openapiv3::ReferenceOr;

crates/oapi-codegen/tests/coverage.rs

@@ -432,6 +432,7 @@ const SERVER_FIXTURES: &[&str] = &[
     "server_prune",
     "server_filtering",
     "server_urls",
+    "server_auth",
 ];
 
 /// Server fixtures whose generation must fail with a documented error, covering
@@ -733,6 +734,7 @@ server_generated_tests!(
     server_prune,
     server_filtering,
     server_urls,
+    server_auth,
 );
 
 /// The server `#[test]`s must cover exactly the supported server fixtures.

crates/oapi-codegen/tests/fixtures/server_auth.yaml

@@ -0,0 +1,132 @@
+openapi: 3.0.3
+info:
+  title: Authenticated server
+  version: 1.0.0
+security:
+  - bearerAuth: []
+paths:
+  /profile:
+    get:
+      operationId: getProfile
+      summary: Fetch the caller's profile, which the global bearer scheme protects.
+      responses:
+        "200":
+          description: The caller's profile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+  /public:
+    get:
+      operationId: getPublic
+      summary: Fetch a public resource, which needs no credential.
+      security: []
+      responses:
+        "200":
+          description: The public resource.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+  /reports:
+    get:
+      operationId: getReports
+      # Two schemes at once, so the note lists both.
+      security:
+        - apiKeyHeader: []
+          basicAuth: []
+      responses:
+        "200":
+          description: The reports.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+  /session:
+    get:
+      operationId: getSession
+      # A description over several lines. The trait method splits it into `///`
+      # lines, because a `/** */` block would sit unevenly among the `///` lines
+      # the security section adds. `GetSessionResponse` keeps the block, since
+      # nothing follows its description.
+      description: |
+        Fetch session data, which an API key cookie protects.
+
+        The cookie is set at login and expires with the session.
+      security:
+        - apiKeyCookie: []
+      responses:
+        "200":
+          description: The session data.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+  /search:
+    get:
+      operationId: search
+      summary: Search, which an API key query parameter protects.
+      security:
+        - apiKeyQuery: []
+      responses:
+        "200":
+          description: The search results.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+  /audit:
+    get:
+      operationId: getAudit
+      summary: Fetch the audit log, which OAuth2 protects.
+      # The client refuses to send an OAuth2 credential. A server reads
+      # credentials instead of sending them, so this only names the scheme.
+      security:
+        - oauth2: []
+      responses:
+        "200":
+          description: The audit log.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Message"
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: A JSON Web Token passed as a bearer credential.
+    basicAuth:
+      type: http
+      scheme: basic
+      description: HTTP basic username and password.
+    apiKeyHeader:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key sent in a request header.
+    apiKeyQuery:
+      type: apiKey
+      in: query
+      name: api_key
+      description: API key sent as a query parameter.
+    apiKeyCookie:
+      type: apiKey
+      in: cookie
+      name: SESSION
+      description: API key sent as a cookie.
+    oauth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://example.com/token
+          scopes: {}
+  schemas:
+    Message:
+      type: object
+      required:
+        - text
+      properties:
+        text:
+          type: string

crates/oapi-codegen/tests/generated.rs

@@ -110,6 +110,9 @@ mod generated {
     pub mod server_text_body;
     #[path = "server_urls.rs"]
     pub mod server_urls;
+
+    #[path = "server_auth.rs"]
+    pub mod server_auth;
     #[path = "server_xfile_refs.rs"]
     pub mod server_xfile_refs;
     #[path = "string_enum.rs"]