[Task] Extend AuthKitApiKeyLocation with gRPC Metadata and Body

[rian-be]

Extend AuthKitApiKeyLocation with explicit credential transport locations (GrpcMetadata, Body) so that the contract can distinguish transports that are currently approximated using existing values or string-based configuration.

Background

The current AuthKitApiKeyLocation contract covers a limited set of credential transport locations (e.g. Header, Query, Cookie).

Additional transports, such as gRPC metadata and request bodies, may currently be forced into approximations. This reduces type safety and makes it difficult for hosts and plugins to distinguish between HTTP headers, gRPC metadata, request bodies, query parameters, cookies, and other transport locations.

The change is additive and must not alter the semantics or numeric values of existing locations.

Proposed Contract

public enum AuthKitApiKeyLocation
{
    // Existing values - MUST NOT CHANGE
    Header = ...,
    Query = ...,
    Cookie = ...,
    // New values (F5–F6)
/// <summary>
/// Credential transported through gRPC metadata.
/// </summary>
GrpcMetadata = <next-available-value>,

/// <summary>
/// Credential supplied through the request body.
/// </summary>
Body = <next-available-value>

}

Scope

• GrpcMetadata (F5)
• Body (F6)

Per Value Specification

Value	Semantics	Host Acceptance	Notes
GrpcMetadata	Credentials transported through gRPC metadata	The host explicitly supports extraction from gRPC metadata or explicitly rejects the configuration.	Must remain distinct from Header; no silent GrpcMetadata -> Header conversion.
Body	Credentials supplied through the request body	The host explicitly supports body based credential extraction or explicitly rejects the configuration.	Must not silently fall back to Header, Query, Cookie, or another location.

GrpcMetadata

GrpcMetadata represents credentials transported through gRPC metadata.

It is intentionally distinct from:

AuthKitApiKeyLocation.Header

GrpcMetadata must not be treated as equivalent to Header merely because gRPC metadata may use key/value metadata fields at the protocol level.

A host that does not support gRPC metadata credential extraction must explicitly reject the configuration.

The host must never silently convert:

GrpcMetadata → Header

or to any other location.

Body

Body represents credentials supplied through the request body.
A host that does not support body based credential extraction must explicitly reject the configuration.

The host must never silently convert:

Body → Header
Body → Query
Body → Cookie

or to any other location.
Body defines only the credential transport location. It does not define or change the authentication mechanism.

For example:

Security Scheme:
    ApiKey
Location:

Body

means that the API key credential is transported through the request body.

Requirements

Backward Compatibility

• Existing enum values, including their names and numeric values, MUST NOT CHANGE.
• Existing plugin behavior must remain unchanged.
• DevTokens must compile without modification.
• Existing locations such as Header, Query, and Cookie must retain their current semantics.

Explicit Transport Semantics

Each AuthKitApiKeyLocation value represents a specific credential transport location.
The host must not infer one location from another.

In particular:

Header       ≠ GrpcMetadata
Body         ≠ Header
Body         ≠ Query
Body         ≠ Cookie

No Silent Fallback

Unsupported locations must result in an explicit configuration or contract error.
They must never silently fall back to another location.

For example:

GrpcMetadata

must never silently behave as:

Header

and:

Body

must never silently behave as:

Header

Unknown Future Enum Values

If plugin provides an AuthKitApiKeyLocation value unknown to the current host version, the host must explicitly reject it.

Unknown values must not automatically map to an existing location.

For example:

default:
    throw new UnsupportedApiKeyLocationException(...);

must be preferred over:

default:
    return Header;

Edge Cases

Host Without gRPC Metadata Support

If host does not support gRPC metadata credential extraction and plugin declares:

AuthKitApiKeyLocation.GrpcMetadata

the host must explicitly reject the configuration.

Host Without Body Support

If host does not support body based credential extraction and plugin declares:

AuthKitApiKeyLocation.Body

the host must explicitly reject the configuration.

Body + ApiKey

The combination:

Security Scheme: ApiKey
Location: Body

means that the API key is transported through the request body.
The transport location must not change or redefine the authentication mechanism.

Validation

• GrpcMetadata and Body are present and include complete XML documentation.
• Existing enum names and numeric values remain unchanged.
• GrpcMetadata receives the next available numeric value.
• Body receives the next available numeric value.
• The host explicitly recognizes or rejects each new location.
• Positive test: GrpcMetadata is accepted by host that supports gRPC metadata.
• Negative test: GrpcMetadata is rejected by host that does not support gRPC metadata.
• Positive test: Body is accepted by host that supports body-based credential extraction.
• Negative test: Body is rejected by host that does not support body-based credential extraction.
• Test verifies GrpcMetadata is distinct from Header.
• Test verifies Body is distinct from Header, Query, and Cookie.
• Test verifies unknown future enum values are explicitly rejected.
• PluginContractValidator passes.
• DevTokens loads successfully without modification.
• Relevant existing location tests continue to pass.

Acceptance Criteria

• GrpcMetadata and Body are added to AuthKitApiKeyLocation.
• Existing enum values remain completely unchanged.
• Both new values include complete XML documentation.
• GrpcMetadata is explicitly distinct from Header.
• Body is explicitly distinct from all existing transport locations.
• The host explicitly supports or rejects every new location.
• Unsupported locations never silently fall back to another location.
• Unknown future enum values are explicitly rejected.
• Positive and negative tests exist for both new locations.
• Tests verify the required transport distinctions.
• PluginContractValidator passes.
• DevTokens continues to compile and load without modification.

Parent

# [Task]: F5–F6 — Extend `AuthKitApiKeyLocation` (Add `GrpcMetadata`, `Body`)

Open
Task
#F5-F6

Summary

Extend AuthKitApiKeyLocation with explicit credential transport locations (GrpcMetadata, Body) so that the contract can distinguish transports that are currently approximated using existing values or string-based configuration.

Background

The current AuthKitApiKeyLocation contract covers a limited set of credential transport locations (e.g. Header, Query, Cookie).

Additional transports, such as gRPC metadata and request bodies, may currently be forced into approximations. This reduces type safety and makes it difficult for hosts and plugins to distinguish between HTTP headers, gRPC metadata, request bodies, query parameters, cookies, and other transport locations.

The change is additive and must not alter the semantics or numeric values of existing locations.

Proposed Contract

public enum AuthKitApiKeyLocation
{
    // Existing values - MUST NOT CHANGE
    Header = ...,
    Query = ...,
    Cookie = ...,
    // New values (F5–F6)

    /// <summary>
    /// Credential transported through gRPC metadata.
    /// </summary>
    GrpcMetadata = <next-available-value>,

    /// <summary>
    /// Credential supplied through the request body.
    /// </summary>
    Body = <next-available-value>
}

Scope

• GrpcMetadata (F5)
• Body (F6)

Per Value Specification

Value	Semantics	Host Acceptance	Notes
GrpcMetadata	Credentials transported through gRPC metadata	The host explicitly supports extraction from gRPC metadata or explicitly rejects the configuration.	Must remain distinct from Header; no silent GrpcMetadata -> Header conversion.
Body	Credentials supplied through the request body	The host explicitly supports body based credential extraction or explicitly rejects the configuration.	Must not silently fall back to Header, Query, Cookie, or another location.

GrpcMetadata

GrpcMetadata represents credentials transported through gRPC metadata.

It is intentionally distinct from:

AuthKitApiKeyLocation.Header

GrpcMetadata must not be treated as equivalent to Header merely because gRPC metadata may use key/value metadata fields at the protocol level.

A host that does not support gRPC metadata credential extraction must explicitly reject the configuration.

The host must never silently convert:

GrpcMetadata → Header

or to any other location.

Body

Body represents credentials supplied through the request body.
A host that does not support body based credential extraction must explicitly reject the configuration.

The host must never silently convert:

Body → Header
Body → Query
Body → Cookie

or to any other location.
Body defines only the credential transport location. It does not define or change the authentication mechanism.

For example:

Security Scheme:
    ApiKey

Location:
    Body

means that the API key credential is transported through the request body.

Requirements

Backward Compatibility

• Existing enum values, including their names and numeric values, MUST NOT CHANGE.
• Existing plugin behavior must remain unchanged.
• DevTokens must compile without modification.
• Existing locations such as Header, Query, and Cookie must retain their current semantics.

Explicit Transport Semantics

Each AuthKitApiKeyLocation value represents a specific credential transport location.
The host must not infer one location from another.

In particular:

Header       ≠ GrpcMetadata
Body         ≠ Header
Body         ≠ Query
Body         ≠ Cookie

No Silent Fallback

Unsupported locations must result in an explicit configuration or contract error.
They must never silently fall back to another location.

For example:

GrpcMetadata

must never silently behave as:

Header

and:

Body

must never silently behave as:

Header

Unknown Future Enum Values

If plugin provides an AuthKitApiKeyLocation value unknown to the current host version, the host must explicitly reject it.

Unknown values must not automatically map to an existing location.

For example:

default:
    throw new UnsupportedApiKeyLocationException(...);

must be preferred over:

default:
    return Header;

Edge Cases

Host Without gRPC Metadata Support

If host does not support gRPC metadata credential extraction and plugin declares:

AuthKitApiKeyLocation.GrpcMetadata

the host must explicitly reject the configuration.

Host Without Body Support

If host does not support body based credential extraction and plugin declares:

AuthKitApiKeyLocation.Body

the host must explicitly reject the configuration.

Body + ApiKey

The combination:

Security Scheme: ApiKey
Location: Body

means that the API key is transported through the request body.
The transport location must not change or redefine the authentication mechanism.

Validation

• GrpcMetadata and Body are present and include complete XML documentation.
• Existing enum names and numeric values remain unchanged.
• GrpcMetadata receives the next available numeric value.
• Body receives the next available numeric value.
• The host explicitly recognizes or rejects each new location.
• Positive test: GrpcMetadata is accepted by host that supports gRPC metadata.
• Negative test: GrpcMetadata is rejected by host that does not support gRPC metadata.
• Positive test: Body is accepted by host that supports body-based credential extraction.
• Negative test: Body is rejected by host that does not support body-based credential extraction.
• Test verifies GrpcMetadata is distinct from Header.
• Test verifies Body is distinct from Header, Query, and Cookie.
• Test verifies unknown future enum values are explicitly rejected.
• PluginContractValidator passes.
• DevTokens loads successfully without modification.
• Relevant existing location tests continue to pass.

Acceptance Criteria

• GrpcMetadata and Body are added to AuthKitApiKeyLocation.
• Existing enum values remain completely unchanged.
• Both new values include complete XML documentation.
• GrpcMetadata is explicitly distinct from Header.
• Body is explicitly distinct from all existing transport locations.
• The host explicitly supports or rejects every new location.
• Unsupported locations never silently fall back to another location.
• Unknown future enum values are explicitly rejected.
• Positive and negative tests exist for both new locations.
• Tests verify the required transport distinctions.
• PluginContractValidator passes.
• DevTokens continues to compile and load without modification.

Parent