Kodevy.Platform.API 4.4.1

Kodevy Platform

Shared .NET 8 libraries for building microservices with Clean Architecture. These packages provide the foundational plumbing so your microservices stay consistent, production-ready, and free of boilerplate.

Packages

Installation

dotnet add package Kodevy.Platform.API
dotnet add package Kodevy.Platform.Application
dotnet add package Kodevy.Platform.Domain
dotnet add package Kodevy.Platform.Infra

Install only the layers your project needs. In a Clean Architecture setup:

• API project — Kodevy.Platform.API
• Application project — Kodevy.Platform.Application
• Domain project — Kodevy.Platform.Domain
• Infrastructure project — Kodevy.Platform.Infra

What's Included

Kodevy.Platform.API

• Global exception handling middleware
• Request context middleware
• JWT authentication strategy (configurable)
• Claims-based authorization strategy
• ToHttpResult mapping that returns consistent API envelope metadata (statusCode, path, timestamp, and development stackTrace)
• API versioning via URL segment (/api/v{version}/...)
• Swagger / OpenAPI configuration with per-version documents and JWT bearer support
• Health check extensions (including EF Core database checks)
• Serilog integration, including GET /api/v1/logs (host grants access via AddPlatformLogsAccess)
• Optional OpenTelemetry wiring (traces + metrics, OTLP/console exporters)
• Reusable OAuth options validation and tenant-role authorization filter primitives

Kodevy.Platform.Application

• ApiClientBase — typed HTTP client with built-in auth token handling
• ApiResult / ServiceResponseWrapper / PaginatedResponseWrapper — standard response wrappers
• ICurrentUserService — access to current authenticated user context (UserId, Email, SessionId, Roles)
• GetRequiredUserId() — helper extension for strict user-id retrieval
• IUnitOfWork — persistence contract
• BaseApplicationSettings / AuthConfiguration / JwtSettings / OAuthSettings / OpenTelemetrySettings — configuration models
• OAuthStateCodec — signed OAuth state payload helper
• OAuthRedirectGuard / OAuthRedirectSettings — strict redirect allowlist guard for OAuth callbacks
• ITenantContextAccessor / ITenantMembershipAuthorizationService — tenant role authorization extension points
• IApplicationLogQuery / ApplicationLogEntryDto — log query contract and DTOs

Kodevy.Platform.Domain

• IAuditableEntity — interface for entities with created/modified tracking

Kodevy.Platform.Infra

• DatabaseConnection / DatabaseProvider — multi-provider database setup (SQL Server, PostgreSQL, MySQL)
• AddDatabaseConfiguration / DatabaseConfigurationValidator — bind + validate DatabaseConfiguration once (database optional; logging connection required when EnableLogging is true)
• AuditSaveChangesInterceptor — automatic audit field population on save
• RelationalDatabaseExtensions — EF Core registration with environment-based migration behavior
• Serilog database sinks (SQL Server, PostgreSQL) and ApplicationLogQuery to read recent rows from the sink table

Configuration

Authentication & Authorization

Configure in appsettings.json:

{
  "AuthConfiguration": {
    "AuthenticationStrategy": "Jwt",
    "AuthorizationStrategy": "Claims"
  },
  "JwtSettings": {
    "Secret": "your-secret-key",
    "Issuer": "your-issuer",
    "Audience": "your-audience",
    "SigningAlgorithm": "HS256",
    "Authority": "",
    "JwksUri": "",
    "RequireHttpsMetadata": true,
    "RefreshOnIssuerKeyNotFound": true,
    "ValidAlgorithms": [],
    "PrivateKeyPem": "",
    "KeyId": "identity-key-1"
  }
}

Compatibility notes:

• Existing HS256 consumers continue to work with SigningAlgorithm: HS256 (default).
• For RS256, set SigningAlgorithm: RS256 and configure either Authority or JwksUri.
• Services validate tokens locally using cached signing keys; no per-request network call is required.
• JWT claim names are left as issued (roles, sub, email). Inbound WS-* rewriting is disabled (MapInboundClaims = false) so RequireRole works for Kodevy services and other backends that consume the same tokens.
• ICurrentUserService reads both issued names and mapped WS-* URIs (sub / NameIdentifier, roles / ClaimTypes.Role, email / ClaimTypes.Email).

HS256 mode requirements:

• SigningAlgorithm = HS256 (or omitted, default)
• Secret (minimum 32 chars), Issuer, Audience

RS256 mode requirements:

• SigningAlgorithm = RS256
• Issuer, Audience
• one of Authority or JwksUri
• Secret is not required in RS256 mode

Token issuer extras (for auth/identity services):

• PrivateKeyPem - RS256 private key (PEM) used for signing
• KeyId - JWKS key identifier (kid) published with issued tokens

API Versioning (URL Segment)

In your API project startup:

builder.Services.AddControllers();
builder.Services.AddSwaggerConfiguration();

app.UseSwaggerConfiguration();
app.MapControllers();

Controller convention (template standard):

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public sealed class WeatherController : ControllerBase
{
}

Kodevy.Platform.API configures:

• URL segment version reader (/api/v1/...)
• default API version fallback to 1.0 when unspecified
• one Swagger document per API version at /swagger/{groupName}/swagger.json

Database

{
  "DatabaseConfiguration": {
    "Provider": "PostgreSql",
    "ConnectionString": "Host=localhost;Database=mydb;Username=user;Password=pass",
    "EnableLogging": false,
    "LoggingConnectionString": ""
  }
}

Supported providers: SqlServer, PostgreSql, MySql

When EnableLogging is true and LoggingConnectionString is set, Serilog writes Information+ events to:

• PostgreSQL table logs (message, level, timestamp, exception, properties, service)
• SQL Server table dbo.Logs (default Serilog columns)

AddBaseConfiguration() binds and validates this section. Hosts do not need to call AddOptions<DatabaseConfiguration>() again.

Validation:

• omitting the section (or leaving Provider and ConnectionString empty) is allowed — for services with no database
• when Provider is set, ConnectionString is required
• when EnableLogging is true, LoggingConnectionString is required (MySQL logging is not supported)

Application logs API

Every service that calls AddApiPlumbing() and AddBaseAuthenticationAuthorization() exposes:

GET /api/v1/logs?level=Error&search=todoist&from=2026-08-17T00:00:00Z&to=2026-08-17T23:59:59Z&limit=50

The endpoint always uses Platform policy platform_logs. Platform registers that policy as deny-all. The host replaces it with the roles that may read logs:

options.AddPlatformLogsAccess(Roles.SuperAdmin);

A non-Kodevy host passes whatever privileged role it uses (Admin, ops, …). If the host never calls AddPlatformLogsAccess, every request to /logs returns 403.

• Reads from LoggingConnectionString when set, otherwise ConnectionString
• Returns an empty list (not an error) when logging is off or the table has not been created yet
• Default limit is 50; maximum is 200

OpenTelemetry (Optional)

Platform can bootstrap OpenTelemetry via AddBaseOpenTelemetry() when OpenTelemetry:Enabled is true. It supports:

• ASP.NET Core tracing/metrics instrumentation
• Outbound HTTP client instrumentation
• Runtime metrics
• OTLP exporter and/or console exporter

Configuration behavior:

• If the OpenTelemetry section is omitted, Enabled defaults to false and no OpenTelemetry pipeline is registered (safe for local dev and services that do not need tracing yet).
• To disable explicitly, set "Enabled": false in appsettings or environment-specific overrides.
• Do not set "OtlpEndpoint": "". Prefer omitting OtlpEndpoint until you have a real collector URL (e.g. http://localhost:4317 or your vendor endpoint). Empty strings were invalid with earlier annotation-based validation; Platform 4.3.1+ validates the URL only when the value is non-empty.
• OTLP export in code is still skipped unless both EnableOtlpExporter is enabled and OtlpEndpoint is non-empty (existing wireup).

OAuth Redirect Allowlist (Security)

Use OAuthRedirect config and OAuthRedirectGuard.TryBuildSafeRedirect(...) in OAuth callback flows to prevent open-redirect vulnerabilities.

Security defaults:

• absolute redirects are denied unless origin is in AllowedOrigins
• only http/https schemes are considered
• path must match AllowedPathPrefixes when configured

Migration behavior:

• Development — migrations are automatically applied on startup
• Production — migrations are not applied automatically. Set RUN_MIGRATIONS_ONLY=true to apply migrations and exit

Used By

These packages are consumed by microservices generated with the Kodevy Microservice Templates:

dotnet new install Kodevy.Templates.Microservice.Init
dotnet new kodevy-microservice-init \
  --organization Contoso \
  --system Platform \
  --microservice Identity

License

MIT