fix(auth): ApiKeyVerifier reports store faults as StoreUnavailable (Auth-010)

A key-store lookup that threw (shared SQL Server unreachable, SQLite I/O
fault) escaped VerifyAsync despite the "only exception path is cancellation"
contract, surfacing as an unaudited 500 / gRPC Unknown. ApiKeyFailure gains
StoreUnavailable (appended; numeric values unchanged) and the lookup maps any
non-cancellation exception to it. Unit theory and an offline refused-port
SqlServerApiKeyStore test fail pre-fix.

(scadaproj#46)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 15:21:00 -05:00
parent b8d3fa2ba1
commit c4366539ca
6 changed files with 153 additions and 6 deletions
@@ -8,7 +8,35 @@ public sealed record ApiKeyOptions
public bool RunMigrationsOnStartup { get; init; } = true;
}
public enum ApiKeyFailure { MissingOrMalformed, KeyNotFound, KeyRevoked, PepperUnavailable, SecretMismatch, KeyExpired }
/// <summary>Why an API-key verification failed. New values are only ever appended, so stored or logged numeric values keep their meaning.</summary>
public enum ApiKeyFailure
{
/// <summary>No credential, or one that does not parse as <c>&lt;prefix&gt;_&lt;keyId&gt;_&lt;secret&gt;</c>.</summary>
MissingOrMalformed,
/// <summary>No key with the presented key id exists.</summary>
KeyNotFound,
/// <summary>The key exists but has been revoked.</summary>
KeyRevoked,
/// <summary>The pepper could not be resolved, so no key can be verified.</summary>
PepperUnavailable,
/// <summary>The presented secret does not match the stored hash.</summary>
SecretMismatch,
/// <summary>The key exists but its absolute expiry has passed.</summary>
KeyExpired,
/// <summary>
/// The key store could not be queried (database unreachable, misconfigured, I/O fault), so the
/// credential could be neither accepted nor rejected on its merits. Added in 0.4.4 (Auth-010);
/// before it, the store's exception escaped <c>VerifyAsync</c>. A host may answer it with 503
/// rather than 401, since the caller did nothing wrong.
/// </summary>
StoreUnavailable,
}
public sealed record ApiKeyIdentity(string KeyId, string DisplayName, IReadOnlySet<string> Scopes, object? Constraints);
@@ -10,7 +10,8 @@ namespace ZB.MOM.WW.Auth.ApiKeys;
/// <remarks>
/// The failure reason is discriminated for the caller/audit pipeline, but the verifier returns a
/// structured result rather than throwing (the caller decides the opaque client-facing message).
/// The only exception path is cancellation. A successful identity carries the key's scopes and the
/// The only exception path is cancellation: a key-store lookup that faults is reported as
/// <see cref="ApiKeyFailure.StoreUnavailable"/> (since 0.4.4), and a failed last-used write is ignored. A successful identity carries the key's scopes and the
/// opaque <c>ConstraintsJson</c> blob (which the verifier does not interpret); it never carries the
/// presented secret, the pepper, or the stored secret hash.
/// </remarks>
@@ -44,7 +45,24 @@ public sealed class ApiKeyVerifier(
}
// 3. Look up the record (including revoked ones) so we can discriminate not-found vs revoked.
ApiKeyRecord? record = await store.FindByKeyIdAsync(parsed.KeyId, ct).ConfigureAwait(false);
// A store fault is a structured StoreUnavailable failure, not an exception (Auth-010): the
// store may be a shared network database, so "unreachable" is an operating condition, and
// consumers map Succeeded == false to their auth-failure path (and audit it) — an escaping
// SqlException became an unaudited 500 / gRPC Unknown instead. Cancellation still throws.
ApiKeyRecord? record;
try
{
record = await store.FindByKeyIdAsync(parsed.KeyId, ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
throw;
}
catch (Exception)
{
return Fail(ApiKeyFailure.StoreUnavailable);
}
if (record is null)
{
return Fail(ApiKeyFailure.KeyNotFound);