Tharga.Team.Service 3.10.0

Tharga Team Service

Server-side API-key authentication, authorization enforcement, controller registration, OpenAPI/Swagger setup, and audit logging for ASP.NET Core projects. Targets .NET 9.0 and .NET 10.0.

Features

• API key authentication - Reads the X-API-KEY header, validates against a store, and populates TeamKey, AccessLevel, and scope claims.
• Access level authorization - AccessLevelProxy<T> enforces [RequireAccessLevel] on service methods via DispatchProxy.
• Scope authorization - ScopeProxy<T> enforces [RequireScope] with audit logging.
• Works in API and interactive Blazor - the proxies resolve the caller via ITeamPrincipalAccessor (default: IHttpContextAccessor). AddThargaTeamBlazor swaps in a circuit-aware accessor (HttpContext when present, else AuthenticationStateProvider), so one [RequireScope]/[RequireAccessLevel] enforces both surfaces. Register a custom ITeamPrincipalAccessor to plug in another principal source.
• Controller + Swagger registration - Single-call setup for MVC controllers, OpenAPI document with API key security scheme, and Swagger UI.
• API key management - Default MongoDB-backed ApiKeyAdministrationService with key hashing. Configurable via ApiKeyOptions — see API key options.
• Audit logging - CompositeAuditLogger with ILogger and MongoDB backends. ⚠️ Stores to ILogger only by default — see Audit logging.
• API-key lifecycle hook - Capture the private token on create/recycle (plus a delete signal) via IApiKeyLifecycleHandler — see Capturing the private token.
• Pluggable - Implement IApiKeyAdministrationService (from Tharga.Team) to bring your own storage backend.

Quick start

using Tharga.Team;
using Tharga.Team.Service;

// Program.cs
builder.Services.AddThargaControllers();
builder.Services.AddAuthentication()
    .AddThargaApiKeyAuthentication();
builder.Services.AddThargaApiKeys();

var app = builder.Build();
app.UseThargaControllers();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

Reading the audit log over REST

AddThargaControllers registers one controller of its own — GET /api/audit — so audit data is reachable from a script or an agent, not only from the Blazor view.

GET /api/audit?teamKey=ABC123&from=2026-01-01&take=100
X-API-KEY: <key>

Filters: teamKey, from, to, feature, action, success, skip, take (capped at 500). Omitting teamKey reads across all teams and requires a system audit:read grant.

Authorization is the same AuditAccess.CanRead rule the Blazor AuditLogView uses, so the two surfaces cannot drift. A team grant reaches only its own team; audit:read is registered at AccessLevel.Administrator, so Viewer- and User-level callers are refused even for their own team. Denials are 403 rather than 404, so they do not reveal whether a team exists.

Which credentials reach the API

ThargaControllerOptions.AuthenticationSchemes lists the schemes Tharga's controllers accept, defaulting to the API-key scheme. Add your own to also admit a signed-in user:

using Microsoft.AspNetCore.Authentication.Cookies;

builder.Services.AddThargaControllers(o =>
    o.AuthenticationSchemes.Add(CookieAuthenticationDefaults.AuthenticationScheme));

A policy naming no scheme falls back to the application's default scheme — OIDC in a Blazor host — so an unauthenticated API call gets a 302 to a login page rather than a 401, and an agent following it receives HTML with a 200. Naming schemes explicitly is what avoids that.

Customizing the OpenAPI document

AddThargaControllers owns the OpenAPI document (it registers the API-key security scheme on it). To add your own IOpenApiDocumentTransformer / IOpenApiOperationTransformer — for example, to filter the generated spec down to the operations the current caller is authorized for — use the ConfigureOpenApi hook instead of calling AddOpenApi("v1", …) yourself:

builder.Services.AddThargaControllers(o =>
    o.ConfigureOpenApi(api => api.AddDocumentTransformer<ScopeFilteringDocumentTransformer>()));

The callback receives the same OpenApiOptions Tharga configures, so your transformers run against the document Tharga already manages. Multiple ConfigureOpenApi calls compose (each runs, in registration order). This avoids a second AddOpenApi("v1", …) registration — which would leave it ambiguous whether your document composes with or overrides Tharga's, and, in .NET 10, forces the OpenAPI XML-comment source generator to emit an interceptor into your project (requiring <InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated</InterceptorsNamespaces> just to compile).

.NET 10+ only. On .NET 9 the document is built by Swashbuckle and this hook is not present; use Swashbuckle's IDocumentFilter / IOperationFilter there.

System API keys

For infrastructure-level credentials that aren't tied to a team (MCP gatekeepers, CI/CD callers, cross-team admin tooling), use system keys — API keys with no TeamKey.

Create and manage them via the <SystemApiKeyView /> component in Tharga.Team.Blazor (gated by the Developer role), or programmatically via IApiKeyAdministrationService.CreateSystemKeyAsync(name, scopes, expiryDate, createdBy).

System keys authenticate through the same X-API-KEY header. The principal they produce carries the IsSystemKey=true claim and the explicit scopes granted at creation time — no TeamKey claim.

Protect system-only endpoints with the system policy:

app.UseThargaMcp().RequireAuthorization(ApiKeyConstants.SystemPolicyName);

The two policies are mutually exclusive: ApiKeyPolicy rejects system keys, SystemApiKeyPolicy rejects team keys.

What a key can reach

The boundary between the two kinds of key is a security guarantee, not a convention, and it is worth knowing precisely before handing either one out:

Two properties follow, and both are covered by tests:

• The team a key acts for comes from the key record, never the request. Knowing a team's key is not authority over it — naming another team is futile rather than merely refused.
• A team grant never satisfies a system check. The scope claim carries its provenance, so a team key holding audit:read cannot use it to read across teams. This is why the two claim types exist.

Access level still applies within the team. audit:read is registered at AccessLevel.Administrator, so a Viewer-level key holding a team's credential is refused its own team's audit log — holding a team's key is not the same as holding every grant inside it.

Which team service to inject

A component, controller or MCP provider should inject one of these — never ITeamService.

ITeamService is the contract you implement, not the one you inject

It is the host's own storage seam and is deliberately unchecked — framework code reads through it while constructing the very claims that would authorize the read, so gating it would be circular and break sign-in.

A first-level surface injecting it bypasses authorization entirely. That is not hypothetical: it is how team:read came to be registered, documented, granted — and checked by nothing.

It is marked [EditorBrowsable(Never)], so it no longer appears in IntelliSense. An architecture test fails the build if a component or MCP provider in this repo injects it; nothing yet protects a consumer project, which is what the planned Roslyn analyzer is for.

Three categories, not two, and only the first is marked by an attribute:

An entry point's check need not be a scope. An invitation is authorized by its invite code, because the invitee is not yet a member and holds nothing. The rule is that a first-level call is checked, not that it is checked by a scope.

Which policy to gate an endpoint with

Three are registered. The first two are disjoint, not a hierarchy — SystemApiKeyPolicy is not "ApiKeyPolicy plus more", and the naming invites that reading.

app.MapGet("/reports", …).RequireAuthorization(ApiKeyConstants.AnyKeyPolicyName);

MCP endpoints need none of these. UseThargaMcp() builds its own policy from ThargaMcpOptions.AuthenticationSchemes, asserting nothing about IsSystemKey, so it already admits both kinds — provided a bridge has contributed a scheme, which mcp.AddTeam() does. Naming a policy there would narrow the endpoint rather than secure it.

Team API keys

Protect endpoints with the built-in policy:

[Authorize(Policy = ApiKeyConstants.PolicyName)]
[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        var teamKey = User.FindFirst(TeamClaimTypes.TeamKey)?.Value;
        return Ok(new { teamKey });
    }
}

Enforce access levels on services:

public interface IMyService
{
    [RequireAccessLevel(AccessLevel.Viewer)]
    IAsyncEnumerable<Item> GetAsync();

    [RequireAccessLevel(AccessLevel.User)]
    Task<Item> AddAsync(string name);
}

// Program.cs
builder.Services.AddScopedWithAccessLevel<IMyService, MyService>();

API key options

API key behaviour is configured via ApiKeyOptions (passed to AddThargaApiKeyAuthentication, or o.ApiKey under AddThargaTeam):

Audit logging

AddThargaAuditLogging records mutations (team-service operations and API-key management) and authorization events via CompositeAuditLogger.

builder.Services.AddThargaAuditLogging(o =>
{
    o.StorageMode = AuditStorageMode.MongoDB;   // see gotcha below
    o.RetentionDays = 90;                       // null (or <= 0) = keep forever
});

⚠️ Gotcha: StorageMode defaults to Logger only, so the MongoDB-backed AuditLogView stays empty until you set AuditStorageMode.MongoDB (or Logger | MongoDB). AuditStorageMode is a [Flags] enum.

Auditing background work

Code with no HTTP request behind it — a hosted service, a message handler, a scheduled job — has no principal to attribute. It used to be recorded as CallerType.User with a null identity, i.e. a row claiming a person did it. It now records Unknown unless you declare an actor:

using var _ = auditContext.Push(new AuditActor("nightly-retention", CorrelationId: runId));
auditLogger.Log(auditEntryFactory.Create("retention", "sweep", teamKey: teamKey));
// CallerType.System, CallerSource.Background, that identity and correlation id

Build the entry with IAuditEntryFactory: IAuditLogger.Log takes a pre-built entry and does not consult the ambient actor, so one you construct by hand will not carry it. Tharga.Team.Sample has a working example in SampleBackgroundJob.

IAuditContextAccessor is registered by AddThargaAuditLogging() regardless of storage mode. The scope is AsyncLocal, so it survives await and nested calls, and restores the outer actor on dispose. An authenticated caller always wins over an ambient actor, so a scope left open on a pooled thread cannot relabel a real user's action; an anonymous request does not win.

CallerFilter and background entries. A source that is neither Api nor Web is matched against Api | Web, so background entries are recorded under the default filter — and, less obviously, under a filter narrowed to just one of them. There is no Background flag to include or exclude them independently. If you need that distinction, say so and it can be added; the current behaviour errs toward recording.

Operation metadata

Audited operations record what changed on AuditEntry.Metadata — create captures the team name, rename the old and new name, a role change the old and new access level, consent the old and new level and roles, and so on (keys are defined on AuditMetadataKeys). Capturing a "before" value is best-effort and never fails the operation. Metadata is shown as an expandable row in AuditLogView, in CSV export (a JSON-encoded Metadata column), JSON export, and the Logger output.

Adding your own metadata

Register an IAuditEnricher to attach host-defined metadata to every entry the toolkit writes:

public sealed class RequestIdAuditEnricher(IHttpContextAccessor http) : IAuditEnricher
{
    public void Enrich(AuditEntry entry, IDictionary<string, string> metadata)
    {
        if (http.HttpContext?.TraceIdentifier is { } id) metadata["request.id"] = id;
    }
}

builder.Services.AddThargaAuditEnricher<RequestIdAuditEnricher>();

Enrichers run in registration order for every entry that passes the filters. The merge is add-only — an enricher cannot overwrite a key the toolkit (or an earlier enricher) set — is resolved as a singleton (read request state via IHttpContextAccessor), and one that throws is logged and skipped so enrichment can never fail the audited operation.

See the implementation guide for the full reference.

Capturing the private token

The private token is shown once and never persisted, logged, or exposed over an API. To capture it (e.g. to re-deliver a minted key), register an IApiKeyLifecycleHandler — it receives the token on create and recycle/regenerate, plus a tokenless delete signal:

public class MyHandler(ISecretProtector protector, IMyStore store) : IApiKeyLifecycleHandler
{
    public Task OnApiKeyLifecycleAsync(ApiKeyLifecycleContext ctx) => ctx.Reason switch
    {
        ApiKeyLifecycleReason.Deleted => store.RemoveAsync(ctx.ApiKeyId),
        _ => store.SaveAsync(ctx.ApiKeyId, protector.Protect(ctx.PrivateToken), ctx.TeamKey, ctx.Tags),
    };
}

builder.AddThargaTeam(o => o.AddApiKeyLifecycleHandler<MyHandler>());

A throwing handler propagates out of the originating operation (capture failures are not swallowed). You own whatever you capture — encrypt it at rest.

Dependencies

• Tharga.Team - Domain models, authorization primitives, and service abstractions.
• Tharga.MongoDB - MongoDB repository infrastructure.
• Tharga.Toolkit - Shared utilities including API key hashing.
• Swashbuckle.AspNetCore - Swagger UI generation.

Related packages

Links

• GitHub repository
• Report an issue