[Task] Add Additional AuthKit Security Scheme Types

[rian-be]

Summary

Extend AuthKitSecuritySchemeType with additional first class authentication scheme types so that the contract can explicitly represent authentication mechanisms that are currently approximated using strings or overloaded existing values.

This removes ambiguity between session-based authentication, API keys transported through HTTP headers or gRPC metadata, generic HTTP authentication, HTTP Basic authentication, and built-in or plugin defined mechanisms.

Background

The current enum covers relatively small fixed set of authentication mechanisms, such as ApiKey, OAuth2, and OpenIdConnect.

Additional authentication mechanisms are currently forced into string-based configuration or approximated using existing values. This reduces type safety, limits IDE discoverability, and makes it difficult for the AuthKit host to distinguish between authentication mechanisms.

Proposed Contract

public enum AuthKitSecuritySchemeType
{
    // Existing values — MUST NOT CHANGE
    ApiKey = 0,
    OAuth2 = 1,
    OpenIdConnect = 2,
// New values (F1–F4)

/// <summary>
/// Mutual TLS authentication using client certificate.
/// </summary>
MutualTls = 3,

/// <summary>
/// Session-based authentication.
/// A cookie may be used as transport mechanism but does not define the authentication mechanism itself.
/// </summary>
Session = 4,

/// <summary>
/// A plugin defined authentication mechanism that is not covered by the built-in security scheme types.
/// </summary>
Custom = 5,

/// <summary>
/// HTTP Basic authentication using the Authorization header.
/// </summary>
Basic = 6

}

Scope

• Add MutualTls
• Add Session
• Add Custom
• Add Basic

Per Value Specification

Value	Semantics	Host / Swagger Acceptance	Notes
MutualTls	Mutual TLS authentication using client certificate	The host validates the client certificate using configured trust material, such as CA or certificate thumbprint. Swagger/OpenAPI maps it to mutualTLS security scheme where supported, or explicitly rejects it.	No silent fallback. Requires trust store configuration.
Session	Session based authentication	Must be distinguishable from ApiKey transported using cookie. Swagger/OpenAPI should represent it as session authentication where supported or explicitly reject unsupported mapping.	A cookie is transport mechanism session is the authentication mechanism. Existing ApiKey behavior must not change.
Custom	Authentication mechanism defined by plugin	The host treats it as non built-in mechanism. Unsupported or incomplete configuration must result in an explicit error rather than mapping it to another scheme.	XML documentation must clearly describe its intended purpose.
Basic	HTTP Basic authentication using Authorization: Basic	Must be distinguishable from Bearer and generic HTTP authentication. Swagger/OpenAPI maps it explicitly to HTTP authentication with the basic scheme.	Must preserve compatibility with existing generic HTTP authentication.

Requirements

• All new enum values must include XML documentation.
• Existing enum values and their numeric values must remain unchanged.
• The change must be additive and backward compatible.
• Existing plugins, including DevTokens, must compile without modification.
• The host and Swagger/OpenAPI mapper must explicitly support or explicitly reject every new value.
• No authentication scheme may silently fall back to another scheme.
• Session must remain semantically distinct from ApiKey using Cookie as its transport location.
• Basic must be distinguishable from generic HTTP authentication and Bearer authentication.
• Custom must never silently resolve to another built-in security scheme.

Edge Cases

Unknown Future Enum Value

If plugin provides an enum value that is unknown to the current host version, the host must explicitly reject it.
Unknown values must not automatically map to Custom.

Unsupported Session Authentication

If plugin declares Session authentication but the host does not support session authentication, configuration validation must fail explicitly.
The scheme must not be ignored or silently downgraded.

Basic and Bearer Authentication

Basic authentication and an existing Bearer or generic HTTP authentication configuration may coexist where the descriptor model allows it.
They must remain distinguishable through their explicit authentication scheme.

Custom Without Usage Documentation

If plugin declares Custom authentication without sufficient documentation or configuration describing how the mechanism is intended to be used, PluginContractValidator should emit warning.
The warning must not cause Custom to be silently mapped to another scheme.

Validation

• dotnet build completes with zero warnings.
• XML documentation is complete for all newly added enum values.
• Unit tests verify that every new value is explicitly recognized by the host and Swagger/OpenAPI mapper.
• Positive and negative mapping tests exist for every new value.
• Test confirms that Session is semantically distinct from ApiKey using Cookie.
• Test confirms that Custom does not silently map to another security scheme.
• Test confirms that Basic is distinguishable from Bearer and generic HTTP authentication.
• Test confirms that Basic is distinguishable from Bearer and generic HTTP authentication. Unknown future enum values are explicitly rejected.
• Unsupported Session authentication produces an explicit configuration error.
• PluginContractValidator successfully validates DevTokens.
• The DevTokens plugin loads and operates without modification.

Acceptance Criteria

• All F1–F4 values are added with complete XML documentation.
• Existing enum values remain unchanged, including their numeric values.
• The host and Swagger/OpenAPI mapper explicitly support or reject every new value.
• No new security scheme silently falls back to another scheme.
• Session, Basic, and Custom are explicitly distinguished from their potentially ambiguous alternatives.
• Tests cover positive behavior, unsupported mappings, unknown enum values, and the specified edge cases.
• Existing plugins, including DevTokens, continue to compile and load without changes.

Parent

Part of: #F Extend Security Scheme Enums

[#F1](https://github.com/AuthKits/AuthKit.Server/issues/new#F1)–F4

Summary

Extend AuthKitSecuritySchemeType with additional first class authentication scheme types so that the contract can explicitly represent authentication mechanisms that are currently approximated using strings or overloaded existing values.

This removes ambiguity between session-based authentication, API keys transported through HTTP headers or gRPC metadata, generic HTTP authentication, HTTP Basic authentication, and built-in or plugin defined mechanisms.

Background

The current enum covers relatively small fixed set of authentication mechanisms, such as ApiKey, OAuth2, and OpenIdConnect.

Additional authentication mechanisms are currently forced into string-based configuration or approximated using existing values. This reduces type safety, limits IDE discoverability, and makes it difficult for the AuthKit host to distinguish between authentication mechanisms.

Proposed Contract

public enum AuthKitSecuritySchemeType
{
    // Existing values — MUST NOT CHANGE
    ApiKey = 0,
    OAuth2 = 1,
    OpenIdConnect = 2,

    // New values (F1–F4)

    /// <summary>
    /// Mutual TLS authentication using client certificate.
    /// </summary>
    MutualTls = 3,

    /// <summary>
    /// Session-based authentication.
    /// A cookie may be used as transport mechanism but does not define the authentication mechanism itself.
    /// </summary>
    Session = 4,

    /// <summary>
    /// A plugin defined authentication mechanism that is not covered by the built-in security scheme types.
    /// </summary>
    Custom = 5,

    /// <summary>
    /// HTTP Basic authentication using the Authorization header.
    /// </summary>
    Basic = 6
}

Scope

• F1 Add MutualTls
• F2 Add Session
• F3 Add Custom
• F4 Add Basic

Per Value Specification

Value	Semantics	Host / Swagger Acceptance	Notes
MutualTls	Mutual TLS authentication using client certificate	The host validates the client certificate using configured trust material, such as CA or certificate thumbprint. Swagger/OpenAPI maps it to mutualTLS security scheme where supported, or explicitly rejects it.	No silent fallback. Requires trust store configuration.
Session	Session based authentication	Must be distinguishable from ApiKey transported using cookie. Swagger/OpenAPI should represent it as session authentication where supported or explicitly reject unsupported mapping.	A cookie is transport mechanism session is the authentication mechanism. Existing ApiKey behavior must not change.
Custom	Authentication mechanism defined by plugin	The host treats it as non built-in mechanism. Unsupported or incomplete configuration must result in an explicit error rather than mapping it to another scheme.	XML documentation must clearly describe its intended purpose.
Basic	HTTP Basic authentication using Authorization: Basic	Must be distinguishable from Bearer and generic HTTP authentication. Swagger/OpenAPI maps it explicitly to HTTP authentication with the basic scheme.	Must preserve compatibility with existing generic HTTP authentication.

Requirements

• All new enum values must include XML documentation.
• Existing enum values and their numeric values must remain unchanged.
• The change must be additive and backward compatible.
• Existing plugins, including DevTokens, must compile without modification.
• The host and Swagger/OpenAPI mapper must explicitly support or explicitly reject every new value.
• No authentication scheme may silently fall back to another scheme.
• Session must remain semantically distinct from ApiKey using Cookie as its transport location.
• Basic must be distinguishable from generic HTTP authentication and Bearer authentication.
• Custom must never silently resolve to another built-in security scheme.

Edge Cases

Unknown Future Enum Value

If plugin provides an enum value that is unknown to the current host version, the host must explicitly reject it.
Unknown values must not automatically map to Custom.

Unsupported Session Authentication

If plugin declares Session authentication but the host does not support session authentication, configuration validation must fail explicitly.
The scheme must not be ignored or silently downgraded.

Basic and Bearer Authentication

Basic authentication and an existing Bearer or generic HTTP authentication configuration may coexist where the descriptor model allows it.
They must remain distinguishable through their explicit authentication scheme.

Custom Without Usage Documentation

If plugin declares Custom authentication without sufficient documentation or configuration describing how the mechanism is intended to be used, PluginContractValidator should emit warning.
The warning must not cause Custom to be silently mapped to another scheme.

Validation

• dotnet build completes with zero warnings.
• XML documentation is complete for all newly added enum values.
• Unit tests verify that every new value is explicitly recognized by the host and Swagger/OpenAPI mapper.
• Positive and negative mapping tests exist for every new value.
• Test confirms that Session is semantically distinct from ApiKey using Cookie.
• Test confirms that Custom does not silently map to another security scheme.
• Test confirms that Basic is distinguishable from Bearer and generic HTTP authentication.
• Test confirms that Basic is distinguishable from Bearer and generic HTTP authentication. Unknown future enum values are explicitly rejected.
• Unsupported Session authentication produces an explicit configuration error.
• PluginContractValidator successfully validates DevTokens.
• The DevTokens plugin loads and operates without modification.

Acceptance Criteria

• All F1–F4 values are added with complete XML documentation.
• Existing enum values remain unchanged, including their numeric values.
• The host and Swagger/OpenAPI mapper explicitly support or reject every new value.
• No new security scheme silently falls back to another scheme.
• Session, Basic, and Custom are explicitly distinguished from their potentially ambiguous alternatives.
• Tests cover positive behavior, unsupported mappings, unknown enum values, and the specified edge cases.
• Existing plugins, including DevTokens, continue to compile and load without changes.