# Gateway Authentication The gateway authentication subsystem verifies inbound API key credentials against a SQLite-backed key store, hashes secrets with a configurable pepper, and records administrative and verification events to an audit trail. ## Token Format API keys travel in the HTTP `Authorization` header as a bearer token shaped `mxgw__`. The `mxgw_` prefix scopes parsing to gateway tokens, the `` segment is the public identifier used for lookup, and `` is the high-entropy portion that the gateway verifies against a stored hash. `ApiKeyParser` enforces the format and rejects malformed tokens before any database round-trip: ```csharp public bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey) { apiKey = null; if (string.IsNullOrWhiteSpace(authorizationHeader) || !authorizationHeader.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase)) { return false; } string token = authorizationHeader[BearerPrefix.Length..].Trim(); if (!token.StartsWith(TokenPrefix, StringComparison.OrdinalIgnoreCase)) { return false; } ``` A successful parse produces a `ParsedApiKey(KeyId, Secret)` record. The `IApiKeyParser` interface exists so verification consumers can be tested without depending on header-format details. ## Parsing and Secrets ### Secret generation `ApiKeySecretGenerator.Generate()` is the single source of new secret material. It uses 32 bytes from `RandomNumberGenerator.Fill` and encodes with URL-safe base64 (no padding) so secrets can be embedded in headers without escaping: ```csharp public static string Generate() { Span bytes = stackalloc byte[32]; RandomNumberGenerator.Fill(bytes); return Convert.ToBase64String(bytes) .TrimEnd('=') .Replace('+', '-') .Replace('/', '_'); } ``` ### Peppered hashing `ApiKeySecretHasher` (registered behind `IApiKeySecretHasher`) hashes secrets with `HMACSHA256` keyed by a server-side pepper. The pepper lives outside the database and is resolved by `IConfiguration` lookup against the configured `PepperSecretName`: ```csharp public byte[] HashSecret(string secret) { string pepper = GetPepper(); byte[] pepperBytes = Encoding.UTF8.GetBytes(pepper); byte[] secretBytes = Encoding.UTF8.GetBytes(secret); using HMACSHA256 hmac = new(pepperBytes); return hmac.ComputeHash(secretBytes); } ``` The pepper is intentionally not stored alongside the hash: an attacker who exfiltrates only the SQLite file holds the hashes but lacks the keying material to brute-force candidate secrets, even if the stored hash algorithm and salt scheme are known. If the pepper is missing the hasher throws `ApiKeyPepperUnavailableException`, which the verifier converts to a distinct failure code rather than treating it as a credential mismatch. ## Verification `ApiKeyVerifier` (`IApiKeyVerifier`) implements the verification flow: 1. Parse the `Authorization` header into a `ParsedApiKey`. 2. Look up the `ApiKeyRecord` by `KeyId` through `IApiKeyStore.FindByKeyIdAsync`. 3. Reject revoked records (`RevokedUtc is not null`). 4. Hash the presented secret with the configured pepper. 5. Compare hashes with `CryptographicOperations.FixedTimeEquals` to avoid timing oracles. 6. Record a `LastUsedUtc` timestamp via `MarkKeyUsedAsync` and return an `ApiKeyIdentity`. ```csharp if (!CryptographicOperations.FixedTimeEquals(presentedHash, storedKey.SecretHash)) { return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch); } await keyStore.MarkKeyUsedAsync(storedKey.KeyId, DateTimeOffset.UtcNow, cancellationToken) .ConfigureAwait(false); return ApiKeyVerificationResult.Success(new ApiKeyIdentity( KeyId: storedKey.KeyId, KeyPrefix: storedKey.KeyPrefix, DisplayName: storedKey.DisplayName, Scopes: storedKey.Scopes, Constraints: storedKey.Constraints)); ``` `ApiKeyVerificationResult` carries either an `ApiKeyIdentity` or a discriminated `ApiKeyVerificationFailure` value. The failure enum distinguishes parse errors, missing pepper, missing or revoked keys, and secret mismatch so the calling middleware can emit precise audit detail without leaking which check failed to the client. `ApiKeyIdentity` exposes only non-secret fields (`KeyId`, `KeyPrefix`, `DisplayName`, `Scopes`, and `Constraints`) and is the type downstream authorization code consumes. ## Storage The gateway keeps API key state in a dedicated SQLite database. SQLite is sufficient because credential volume is small, the gateway runs as a single process, and the file is straightforward to back up and rotate independently of the main application data. ### Connection factory `AuthSqliteConnectionFactory` reads `GatewayOptions.Authentication.SqlitePath`, ensures the parent directory exists, and opens the connection in `ReadWriteCreate` mode so first-run installations can create the file without manual provisioning: ```csharp public SqliteConnection CreateConnection() { string sqlitePath = options.Value.Authentication.SqlitePath; string? directory = Path.GetDirectoryName(sqlitePath); if (!string.IsNullOrWhiteSpace(directory)) { Directory.CreateDirectory(directory); } SqliteConnectionStringBuilder builder = new() { DataSource = sqlitePath, Mode = SqliteOpenMode.ReadWriteCreate }; return new SqliteConnection(builder.ToString()); } ``` ### Schema `SqliteAuthSchema` declares table names and the current schema version as constants. Three tables are involved: - `api_keys` stores `key_id`, `key_prefix`, the `secret_hash` blob, `display_name`, serialized `scopes`, optional serialized `constraints`, and the `created_utc`, `last_used_utc`, and `revoked_utc` timestamps. - `api_key_audit` is an append-only log keyed by an autoincrement `audit_id` with `key_id`, `event_type`, `remote_address`, `created_utc`, and `details` columns. - `schema_version` carries a single row whose `version` column is matched against `SqliteAuthSchema.CurrentVersion`. ### Read paths `SqliteApiKeyStore` (`IApiKeyStore`) handles the two reads needed at request time: `FindByKeyIdAsync` returns any record (so revoked keys can be reported distinctly) and `FindActiveByKeyIdAsync` filters to non-revoked rows. `MarkKeyUsedAsync` updates `last_used_utc` only for non-revoked rows so a freshly revoked key cannot have its timestamp refreshed by a racing verification. `ApiKeyRecord` is the in-memory projection. `ApiKeyRecordReader.Read` is shared by every read path so column ordering is defined in one place: ```csharp public static ApiKeyRecord Read(SqliteDataReader reader) { return new ApiKeyRecord( KeyId: reader.GetString(0), KeyPrefix: reader.GetString(1), SecretHash: (byte[])reader["secret_hash"], DisplayName: reader.GetString(3), Scopes: ApiKeyScopeSerializer.Deserialize(reader.GetString(4)), Constraints: ApiKeyConstraintSerializer.Deserialize(reader.IsDBNull(5) ? null : reader.GetString(5)), CreatedUtc: DateTimeOffset.Parse(reader.GetString(6), System.Globalization.CultureInfo.InvariantCulture), LastUsedUtc: ReadNullableDateTimeOffset(reader, 7), RevokedUtc: ReadNullableDateTimeOffset(reader, 8)); } ``` ### Write paths `SqliteApiKeyAdminStore` (`IApiKeyAdminStore`) implements administrative mutations: `CreateAsync` accepts an `ApiKeyCreateRequest`, `RevokeAsync` sets `revoked_utc` only when not already revoked, and `RotateAsync` replaces `secret_hash`, clears `last_used_utc`, and clears `revoked_utc` so a rotated key is immediately usable. ### Audit trail `SqliteApiKeyAuditStore` (`IApiKeyAuditStore`) appends `ApiKeyAuditEntry` values to the `api_key_audit` table and stamps each row with a UTC timestamp inside the store rather than trusting the caller. `ListRecentAsync` returns the most recent rows ordered by `audit_id` descending and projects them into `ApiKeyAuditRecord`. Rows are kept even after the referenced key is revoked because the audit history is the durable record of administrative action; the `key_id` column is nullable to accommodate non-key-scoped events such as `init-db`. ## Migration Schema bring-up is centralised behind `IAuthStoreMigrator`. `SqliteAuthStoreMigrator` executes the migration inside a single transaction so a partial failure leaves the database untouched, refuses to start when the on-disk schema version is newer than the binary supports, and idempotently creates the v1 schema: ```csharp if (existingVersion > SqliteAuthSchema.CurrentVersion) { throw new AuthStoreMigrationException( $"Auth database schema version {existingVersion} is newer than supported version {SqliteAuthSchema.CurrentVersion}."); } await ApplyVersionOneAsync(connection, transaction, cancellationToken).ConfigureAwait(false); await transaction.CommitAsync(cancellationToken).ConfigureAwait(false); ``` `AuthStoreMigrationHostedService` runs the migrator at startup, but only when API-key authentication is enabled and `RunMigrationsOnStartup` is true. Operators who manage schema out-of-band can disable the hosted run and use the admin CLI's `init-db` command instead. `AuthStoreMigrationException` is a sealed `InvalidOperationException` so it can be caught precisely without swallowing unrelated failures. ## Admin CLI `ApiKeyAdminCommandLineParser.Parse` recognises a leading `apikey` argument and dispatches to one of the subcommands declared by `ApiKeyAdminCommandKind`. Each parsed invocation produces an `ApiKeyAdminCommand` (or an `ApiKeyAdminParseResult` carrying an error). `ApiKeyAdminCliRunner` then executes the command, runs the migrator first, calls the relevant store method, appends an audit row, and writes either text or JSON output via `ApiKeyAdminOutput`. The returned `ApiKeyAdminListedKey` projection deliberately omits the `secret_hash` so listing a database does not surface hash material. The supported subcommands match `ApiKeyAdminCommandKind` exactly: | Subcommand | Required options | Behaviour | |------------|------------------|-----------| | `init-db` | none | Runs the migrator and records an audit entry. | | `create-key` | `--key-id`, `--display-name` | Generates a new secret, stores its peppered hash and optional constraints, and prints the assembled `mxgw__` token. | | `list-keys` | none | Lists every stored key with its scopes, constraints, and revocation state. | | `revoke-key` | `--key-id` | Sets `revoked_utc` if the key is currently active. | | `rotate-key` | `--key-id` | Replaces the secret hash and prints the new token. | Examples: ```bash mxgateway apikey init-db mxgateway apikey create-key --key-id ops.alice --display-name "Alice (ops)" --scopes read,write mxgateway apikey create-key --key-id area1.reader --display-name "Area 1 reader" --scopes invoke:read,metadata:read --read-subtree "Area1/*" --browse-subtree "Area1/*" mxgateway apikey list-keys --json mxgateway apikey revoke-key --key-id ops.alice mxgateway apikey rotate-key --key-id ops.alice ``` Constraint flags are optional. `--read-subtree`, `--write-subtree`, `--read-tag-glob`, `--write-tag-glob`, and `--browse-subtree` are repeatable. `--max-write-classification` accepts one integer. `--read-alarm-only` and `--read-historized-only` are boolean flags. Existing rows with null constraints remain fully unconstrained after migration. Key ids are restricted by the parser to ASCII letters, digits, periods, and hyphens so they remain safe to embed in the token format and in URL paths used by administrative tooling. ## Scope Serialization Scopes are persisted as a single TEXT column rather than a join table because the set is small, never queried by membership at the database level, and changes atomically with the owning row. `ApiKeyScopeSerializer.Serialize` writes a JSON array sorted with `StringComparer.Ordinal` so equivalent scope sets produce byte-identical column values, which makes audit diffing and database comparisons deterministic: ```csharp public static string Serialize(IReadOnlySet scopes) { return JsonSerializer.Serialize(scopes.Order(StringComparer.Ordinal)); } public static IReadOnlySet Deserialize(string value) { if (string.IsNullOrWhiteSpace(value)) { return new HashSet(StringComparer.Ordinal); } string[]? scopes = JsonSerializer.Deserialize(value); return new HashSet(scopes ?? [], StringComparer.Ordinal); } ``` `Deserialize` tolerates an empty column by returning an empty set so older rows or hand-edited records do not crash the verifier. ## Registration `AuthStoreServiceCollectionExtensions.AddSqliteAuthStore` wires every service in this subsystem as a singleton and registers the migration hosted service: ```csharp public static IServiceCollection AddSqliteAuthStore(this IServiceCollection services) { services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddSingleton(); services.AddHostedService(); return services; } ``` Singletons are safe because each operation opens its own short-lived `SqliteConnection` through the factory; there is no shared mutable state inside the services. ## Related Documentation - [Gateway Configuration](./GatewayConfiguration.md) - [Authorization](./Authorization.md) - [Diagnostics](./Diagnostics.md)