Csag.Blueprint.Infrastructure 0.5.0

Csag.Blueprint.Infrastructure

Overview

This package provides the shared infrastructure implementation layer for CSAG Blueprint-based applications.

It contains the reusable EF Core persistence backbone, session/auth infrastructure, localization infrastructure, tenancy helpers, authorization transformation, and table-view execution components that consuming applications compose into their own host.

What this package owns

Persistence backbone

Data isolation topology

ConfigureBlueprintMultiTenancy implements the pooled topology: every entity implementing IMustHaveTenant gets a global query filter on TenantId, an index on that column, and a foreign key to the tenant table.

modelBuilder.ConfigureBlueprintMultiTenancy<ApplicationTenant, ApplicationDbContext>(this);

Because isolation is enforced by the filter and not the database, any table that cannot carry a tenant discriminator — the user table, since identity is shared — is a permanent sharp edge that must be scoped by membership on every query.

Moving to database-per-tenant. Pass addTenantForeignKey: false when tenant-owned data lives in a different database from the tenant table; a foreign key cannot cross databases, so emitting one there produces an invalid model. The filter and index still apply — only referential integrity moves from the database to the application.

modelBuilder.ConfigureBlueprintMultiTenancy<ApplicationTenant, BusinessDbContext>(
    this, addTenantForeignKey: false);

Note that IMustHaveTenant is not a synonym for "shardable". Some tenant-owned entities are identity concerns — a service account is tenant-scoped but authentication needs it, so it must stay in the central database. Classify each entity by plane before splitting anything.

Interceptors

Both are registered as singletons by AddBlueprintTenancyRuntime(). Resolve them from the container when wiring the pooled DbContext factory rather than constructing them — they are singleton-safe because they read ambient AsyncLocal state and a singleton TimeProvider, never scoped services. AuditableTimestampInterceptor stamps from that TimeProvider, so a FakeTimeProvider registered before AddBlueprintTenancyRuntime() controls the timestamps it writes.

Session and authorization infrastructure

Cookie sessions

The packages own the cookie session lifecycle; the application registers it and states intents.

services.AddBlueprintSessionInfrastructure<ApplicationUser, ApplicationDbContext>(options =>
    options.ClientIpHeader = "X-Client-IP");
services.AddBlueprintCookieSessions(cookie =>
{
    cookie.SecurePolicy = securitySettings.CookieSecurePolicy;
    cookie.SameSite = SameSiteMode.Lax;
});

AddBlueprintCookieSessions turns the Identity application cookie into the session cookie, after every other Configure (including AddIdentity's) in either registration order. The callback shapes the cookie; the package then applies what it owns:

• the ticket store, with the session tracked server-side and the cookie carrying only its key;
• an HTTP-only, persistent cookie whose lifetime is BlueprintSessionOptions.Lifetime — set from Blueprint:Security:SessionExpirationHours by Csag.Blueprint.Web — with sliding expiration, so sign-in code sets no expiry;
• 401 and 403 instead of login and access-denied redirects;
• no Identity security-stamp validation: the session principal carries no stamp, and sessions end through the lifecycle instead;
• ISessionEligibility asked at every sign-in and sliding renewal.

Cookie event handlers the application assigns on CookieAuthenticationOptions.Events keep running, before the package's. A scheme that sets EventsType, or whose events object overrides the events the package relies on, fails when its options are built.

The tracking row records the client address with the rule the rate limiter uses: ClientIpHeader when present and parseable, otherwise the connection's remote address. A sign-in on a request that still carries a live session cookie reuses that cookie's key; the row is then attributed to the signing-in account.

Applications report what happened through ISessionLifecycle, after their database commit:

Hooks the application keeps: ISessionRevocationParticipants for its own credentials, an ISessionEligibility, the cookie callback, its own cookie event handlers, and decorators around ITicketStore or IActiveSessionTracker (resolve DistributedCacheTicketStore or ActiveSessionTracker<TContext> as the inner instance). The expired-session cleanup runs hourly by default; set ExpiredSessionCleanup.Interval, or turn it off with ExpiredSessionCleanup.Enabled = false.

Service-account credentials

The packages own a service account's credentials from end to end: the secret and its hash, issuing bearer tokens, the lockout, rotation, revocation, and validating the tokens. The application keeps its endpoints (route, rate limit, OpenAPI text) and the validation of the account data it accepts, and states intents.

services.AddBlueprintServiceAccountAuthentication<ApplicationDbContext>();

The settings come from Blueprint:Security:Jwt and Blueprint:Security:ServiceAccountLockout, which Csag.Blueprint.Web applies to BlueprintServiceAccountOptions. The registration needs no signing key, so it can run unconditionally — also in a host started only to export its OpenAPI document. A configured key must have at least 32 characters besides surrounding white space, checked at startup; a missing key fails the first issuance or validation.

Issuance verifies every secret with the same key derivation, unknown clients included. A wrong secret counts towards the lockout in one statement, so concurrent attempts all count; a locked account is refused whatever secret it is given. Every time — issuance, expiry, lockout — comes from the injected TimeProvider. Rotation, deactivation and deletion tell the ISessionRevocationParticipants, with a service-account SessionSubject.

Each token refers to a server-side session and carries only ServiceAccountClaimTypes claims (sub, name, type, sid). The service-account scheme pins HS256, validates issuer, audience and lifetime with no clock skew, signs and validates over the key's UTF-8 bytes, and does not map inbound claims. Every request resolves the token's session and builds the principal from the account's current name, tenant, roles and permissions; register IServiceAccountClaimsEnrichers to add the application's own claims.

Secrets are hashed in ASP.NET Core Identity's PasswordHasher format with fixed parameters, so hashes the application wrote with a default PasswordHasher keep verifying. A data seed sets a known secret with serviceAccount.SetClientSecret(secret).

Three authentication schemes are registered. Each request is authenticated by exactly one scheme:

Expired service-account sessions are deleted by the job AddBlueprintSessionInfrastructure registers.

Tenancy and localization infrastructure

Table view infrastructure

Ownership Boundary

This package owns reusable infrastructure, not application composition.

The consuming application still owns:

• the concrete ApplicationDbContext
• DI composition and host setup
• app-specific options and policies
• app-specific entities and migrations