Concierge.Auth.Client.Keys 2.2.0

Concierge.Auth.Client.Keys

JWKS signing-key retrieval and peer public-key lookup against AuthService. Two separate, unrelated key systems (contract assumption #100) — kept in separate interfaces, separate storage, separate in-process caches. There is no shared "get a key" abstraction spanning both, and no code path by which a peer key could reach human-token verification.

Install and register

JWKS (IJwksKeyProvider) and peer public keys (IPeerKeyClient) register independently — pick the one(s) this consumer actually needs.

JWKS only — human-token verification (the common case, no credential needed)

services.AddConciergeAuthClient(configuration, db => db.UseNpgsql(cs, npgsql =>
    npgsql.MigrationsHistoryTable("__EFMigrationsHistory", "concierge"))); // base package — required first
services.AddConciergeAuthClientJwks(configuration);     // binds "Concierge:AuthClient:Keys"

No Concierge.Auth.Client.Secrets registration, no client-service credential. A consumer that only ever calls IJwksKeyProvider — e.g. an admin UI backend validating human JWTs — should stop here.

Peer public keys — service-to-service, requires a credential and an admin-issued grant

services.AddConciergeAuthClient(configuration, db => db.UseNpgsql(cs, npgsql =>
    npgsql.MigrationsHistoryTable("__EFMigrationsHistory", "concierge")));
services.AddConciergeSecretManagement(configuration);       // Secrets package — required first
services.AddConciergeAuthClientPeerKeys(configuration);      // binds "Concierge:AuthClient:Keys"

AddConciergeAuthClientPeerKeys fails closed at this call, synchronously, if AddConciergeSecretManagement(...) has not already been registered — peer-key lookup authenticates with this service's own credential from IClientCredentialStore via ConciergeClientCredentialHandler on the configured per-client header (default X-Api-Key, from ConciergeSecretRotationOptions.HeaderName) — never a Bearer JWT and never the keypair mechanism itself.

Both

services.AddConciergeSecretManagement(configuration);
services.AddConciergeAuthClientKeys(configuration);   // convenience: registers JWKS + peer keys

AddConciergeAuthClientKeys is unchanged from before this split — it still registers both key systems under one call, for a consumer that genuinely needs both. It also requires AddConciergeSecretManagement to be registered first, same as AddConciergeAuthClientPeerKeys alone.

JWKS — IJwksKeyProvider

var keys = await jwksKeyProvider.GetSigningKeysAsync(cancellationToken);
var key = await jwksKeyProvider.GetSigningKeyAsync(kid, cancellationToken);

Two cache layers: in-process (hot path) and the client's own jwks_keys table (so a cold process start does not stampede AuthService — contract §5). TTL defaults to 1 hour (cacheMaxAge), fetch rate is capped at 5/minute (jwksRequestsPerMinute) — applied to EVERY fetch trigger, including an unknown kid, which is treated as a rotation signal (AuthService serves both keys during rotation) rather than an immediate rejection. Concurrent callers during a cold cache are coalesced into a single HTTP fetch.

Failure codes: JWKS_KEY_NOT_FOUND (kid unknown even after a permitted refresh), JWKS_UNAVAILABLE (AuthService unreachable/unusable and no cache to fall back on).

Optional background warming

services.AddConciergeAuthClientJwks(o =>
{
    o.EnableBackgroundRefresh = true;             // default false
    o.BackgroundRefreshInterval = TimeSpan.FromMinutes(15);
});

A plain IHostedService + PeriodicTimer — no Quartz.NET/Hangfire. Purely a cold-start optimisation; lazy refresh on GetSigningKeysAsync/GetSigningKeyAsync is correct on its own.

Peer public keys — IPeerKeyClient

var result = await peerKeyClient.GetPeerPublicKeyAsync(targetClientKey, cancellationToken);
if (result.IsFailure)
{
    // result.Error.Code is one of:
    //   PEER_KEY_DENIED      — unknown target, no grant, revoked grant, or revoked key.
    //                           ALL FOUR collapse to this SAME code (contract §10.4/§10.5) —
    //                           do not attempt to distinguish which one occurred, and do not
    //                           build retry logic assuming a denial had any server-side effect
    //                           (denials stamp nothing).
    //   PEER_KEY_UNAVAILABLE — AuthService unreachable/unusable response, or local persist failed.
}

Authenticates with this service's own credential (ConciergeClientCredentialHandler attaches the active secret from IClientCredentialStore on the configured per-client header, default X-Api-Key) — never a Bearer JWT and never the keypair mechanism. A successful fetch persists the target's public key to peer_keypairs with is_own = false and no private-key material, and is served from an in-process TTL cache on subsequent lookups.

PeerPublicKey.TenantScope surfaces the tenant scope from the admin grant (contract §10.4): null means unscoped (ALL tenants); a non-empty list restricts to those org-node ids. The field is omitted on the wire for unscoped grants. Ids are opaque — enforce scope in your service, not in this package.

Own peer keypair — IPeerKeypairStore

For outbound signing, import this service's own keypair after Auth admin provisioning (Flow A or B):

await peerKeypairStore.ImportOwnPeerKeypairAsync(publicKeyPem, privateKeyPem, cancellationToken);
var own = await peerKeypairStore.GetActiveOwnPeerKeypairAsync(cancellationToken);

Registered by AddConciergeAuthClientJwks / AddConciergeAuthClientPeerKeys / AddConciergeAuthClientKeys. Private key is encrypted at rest (is_own = true); fingerprint is computed inside the store (SHA-256 of SPKI). See libs/dotnet/docs/peer-key-onboarding.md.

Out of scope here

Token validation middleware and the Redis deny-list, credential rotation (see Concierge.Auth.Client.Secrets), profile operations. No ASP.NET Core dependency in this package.