feat(security): explicit security scheme contract, API key extraction, and plugin validation

[rian-be]

Summary

This PR extends the AuthKit plugin contract and host with an explicit security scheme model: additive security scheme and API key location enums, host side API key credential extraction, plugin contract validation, and explicit OpenAPI mapping. Every contract value is handled explicitly by the host and by the OpenAPI mapper.

Security Scheme Contract

• extends AuthKitSecuritySchemeType with MutualTls, Session, Custom, and Basic, and makes OpenIdConnect a distinct value (the historical OAuth2 alias is removed)
• extends AuthKitApiKeyLocation with GrpcMetadata and Body
• declares numeric enum values part of the plugin contract: existing values stay unchanged and must never be reused or renumbered
• stabilizes the scheme enums and metadata so old plugins, including DevTokens, compile and load unmodified

API Key Extraction

• introduces the API key credential extraction pipeline: header, query, cookie, gRPC metadata, and body location extractors
• adds JSON and form URL encoded body parsers for body located API keys
• adds API key credential normalization through ApiKeyValueNormalizer and validator/principal types (IApiKeyValidator, ApiKeyPrincipal)
• exposes extraction through ApiKeyCredentialExtractor middleware with ApiKeyCredentialExtractorOptions and SecurityServiceCollectionExtensions registration

Plugin Validation

• introduces PluginContractValidator with supported scheme types and API key locations, validating every declared scheme and location against them
• defined but unsupported and unknown future values raise InvalidPluginContractException; unknown values are identified by numeric identity and never resolved to Custom or any known value
• Custom requires plugin supplied Description; missing description produces a validation warning
• supports per host extensions through PluginContractValidator.CreateCustom

OpenAPI Mapping

• introduces AuthKitOpenApiSecuritySchemeMapper that maps every value explicitly: semantically correct OpenAPI representations for ApiKey, Http, OAuth2, OpenIdConnect, and Basic
• throws NotSupportedException for values with no correct 3.0 representation (MutualTls, Session, Custom; GrpcMetadata and Body as API key locations) and ArgumentOutOfRangeException for unknown values
• RestfulConfiguration catches mapper failures and logs a warning while skipping the definition it never emits a generic substitute and never crashes document generation
• the host accepts only OpenApi:SpecVersion 3.0; 3.1 is rejected with InvalidOperationException instead of silently emitting a 3.0 document

Host

• keeps header/query/cookie/gRPC metadata/body credential extraction supported at runtime through AuthenticateApiKey counterparts even though OpenAPI 3.0 cannot describe some of them
• runtime support and OpenAPI representability are orthogonal: supported locations extract at runtime (ADR-017) though OpenAPI 3.0 cannot describe body/gRPC metadata
• refractors OpenAPI serving configuration to consume the mapper

Tests

• adds host and plugin security scheme tests covering every contract value
• prevents OAuth2 and OpenID Connect enum aliasing regression
• adds security-scheme tests and updates package configuration
• covers mandated/unknown value handling and no-fallback behavior

Documentation

• records the security scheme decisions as ADRs (ADR-017 API key credential extraction strategies, ADR-018 security scheme contract explicit handling)

Result

Two explicit contract guarantees now exist: no silent fallback between schemes or locations, and unknown future values are always rejected. Plugins that declare unsupported mechanisms fail contract validation at startup; per-host extensions use PluginContractValidator.CreateCustom. Old plugins compile and load unmodified, and persisted descriptors keep their meaning.

Closes #4
Closes #5
Closes #6
Closes #7