Initial commit: scadaproj umbrella — sister-project index, auth component normalization (design + GAPS), and the built ZB.MOM.WW.Auth shared library (0.1.0, flattened in).

2026-06-01 03:59:23 -04:00
commit 37e23cf9f2
73 changed files with 6836 additions and 0 deletions
@@ -0,0 +1,87 @@
+using Microsoft.Data.Sqlite;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>
+/// Factory for creating and opening SQLite connections to the API-key store.
+/// </summary>
+public sealed class AuthSqliteConnectionFactory
+{
+    /// <summary>
+    /// Busy timeout applied to every connection. SQLite retries a busy database for
+    /// this long before surfacing <c>SQLITE_BUSY</c>, so the concurrent
+    /// mark-used / audit-append writers degrade gracefully under load instead of
+    /// failing the request path.
+    /// </summary>
+    private static readonly TimeSpan BusyTimeout = TimeSpan.FromSeconds(5);
+
+    private readonly string _sqlitePath;
+
+    /// <summary>Creates a factory targeting the database at <paramref name="sqlitePath"/>.</summary>
+    /// <param name="sqlitePath">Filesystem path of the SQLite database file.</param>
+    public AuthSqliteConnectionFactory(string sqlitePath)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(sqlitePath);
+        _sqlitePath = sqlitePath;
+    }
+
+    /// <summary>
+    /// Creates an unopened SQLite connection (Mode=ReadWriteCreate). Prefer
+    /// <see cref="OpenConnectionAsync"/>, which also applies WAL journaling and the
+    /// busy timeout.
+    /// </summary>
+    public SqliteConnection CreateConnection()
+    {
+        string? directory = Path.GetDirectoryName(_sqlitePath);
+
+        if (!string.IsNullOrWhiteSpace(directory))
+        {
+            Directory.CreateDirectory(directory);
+        }
+
+        SqliteConnectionStringBuilder builder = new()
+        {
+            DataSource = _sqlitePath,
+            Mode = SqliteOpenMode.ReadWriteCreate,
+            Pooling = true,
+            DefaultTimeout = (int)BusyTimeout.TotalSeconds,
+        };
+
+        return new SqliteConnection(builder.ToString());
+    }
+
+    /// <summary>
+    /// Creates a SQLite connection, opens it, and configures WAL journaling and a
+    /// non-zero busy timeout so concurrent readers and writers degrade gracefully
+    /// rather than surfacing <c>SQLITE_BUSY</c> as a hard failure.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An opened and configured SQLite connection.</returns>
+    public async Task<SqliteConnection> OpenConnectionAsync(CancellationToken cancellationToken)
+    {
+        SqliteConnection connection = CreateConnection();
+        try
+        {
+            await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+            await ConfigureConnectionAsync(connection, cancellationToken).ConfigureAwait(false);
+            return connection;
+        }
+        catch
+        {
+            await connection.DisposeAsync().ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    private static async Task ConfigureConnectionAsync(
+        SqliteConnection connection,
+        CancellationToken cancellationToken)
+    {
+        // WAL is a persistent, database-level setting; re-applying it per connection
+        // is cheap and a no-op once set. busy_timeout is per-connection state.
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText =
+            $"PRAGMA journal_mode=WAL; PRAGMA busy_timeout={(int)BusyTimeout.TotalMilliseconds};";
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+}
@@ -0,0 +1,35 @@
+using System.Text.Json;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>
+/// Serializes API-key scope sets to a canonical JSON array. Scopes are sorted with
+/// <see cref="StringComparer.Ordinal"/> so that equal sets always produce identical
+/// column text, regardless of insertion order.
+/// </summary>
+public static class ScopeSerializer
+{
+    /// <summary>Serializes scopes to an ordinal-sorted JSON array.</summary>
+    /// <param name="scopes">The scopes to serialize.</param>
+    /// <returns>A JSON array string with elements sorted ordinally.</returns>
+    public static string Serialize(IReadOnlySet<string> scopes)
+    {
+        ArgumentNullException.ThrowIfNull(scopes);
+        return JsonSerializer.Serialize(scopes.Order(StringComparer.Ordinal));
+    }
+
+    /// <summary>Deserializes scopes from a JSON array string.</summary>
+    /// <param name="value">The JSON string to deserialize; may be null or empty.</param>
+    /// <returns>An ordinal-compared set of scopes; empty when the input is null/blank.</returns>
+    public static IReadOnlySet<string> Deserialize(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return new HashSet<string>(StringComparer.Ordinal);
+        }
+
+        string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
+
+        return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
+    }
+}
@@ -0,0 +1,143 @@
+using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>
+/// SQLite-backed administration store for API keys (create, revoke, rotate, delete).
+/// </summary>
+public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAdminStore
+{
+    /// <inheritdoc />
+    public async Task CreateAsync(ApiKeyRecord record, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(record);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            INSERT INTO api_keys (
+                key_id, key_prefix, secret_hash, display_name, scopes,
+                constraints, created_utc, last_used_utc, revoked_utc)
+            VALUES (
+                $key_id, $key_prefix, $secret_hash, $display_name, $scopes,
+                $constraints, $created_utc, $last_used_utc, $revoked_utc);
+            """;
+        command.Parameters.AddWithValue("$key_id", record.KeyId);
+        command.Parameters.AddWithValue("$key_prefix", record.KeyPrefix);
+        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = record.SecretHash;
+        command.Parameters.AddWithValue("$display_name", record.DisplayName);
+        command.Parameters.AddWithValue("$scopes", ScopeSerializer.Serialize(record.Scopes));
+        command.Parameters.AddWithValue("$constraints", (object?)record.ConstraintsJson ?? DBNull.Value);
+        command.Parameters.AddWithValue("$created_utc", record.CreatedUtc.ToString("O"));
+        command.Parameters.AddWithValue("$last_used_utc", (object?)record.LastUsedUtc?.ToString("O") ?? DBNull.Value);
+        command.Parameters.AddWithValue("$revoked_utc", (object?)record.RevokedUtc?.ToString("O") ?? DBNull.Value);
+
+        await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> RevokeAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET revoked_utc = $revoked_utc
+            WHERE key_id = $key_id AND revoked_utc IS NULL;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.AddWithValue("$revoked_utc", whenUtc.ToString("O"));
+
+        int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> RotateAsync(string keyId, byte[] newSecretHash, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        ArgumentNullException.ThrowIfNull(newSecretHash);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET secret_hash = $secret_hash,
+                last_used_utc = NULL,
+                revoked_utc = NULL
+            WHERE key_id = $key_id;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = newSecretHash;
+
+        int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> DeleteAsync(string keyId, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            DELETE FROM api_keys
+            WHERE key_id = $key_id AND revoked_utc IS NOT NULL;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+
+        int rows = await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct)
+    {
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+
+        // Deliberately omits secret_hash so listing can never leak secret material.
+        command.CommandText = """
+            SELECT key_id, key_prefix, display_name, scopes, constraints,
+                   created_utc, last_used_utc, revoked_utc
+            FROM api_keys
+            ORDER BY created_utc DESC, key_id DESC;
+            """;
+
+        List<ApiKeyListItem> items = [];
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            items.Add(new ApiKeyListItem(
+                KeyId: reader.GetString(0),
+                KeyPrefix: reader.GetString(1),
+                DisplayName: reader.GetString(2),
+                Scopes: ScopeSerializer.Deserialize(reader.GetString(3)),
+                ConstraintsJson: reader.IsDBNull(4) ? null : reader.GetString(4),
+                CreatedUtc: SqliteValueParsing.ParseUtc(reader.GetString(5)),
+                LastUsedUtc: SqliteValueParsing.ReadNullableUtc(reader, 6),
+                RevokedUtc: SqliteValueParsing.ReadNullableUtc(reader, 7)));
+        }
+
+        return items;
+    }
+}
@@ -0,0 +1,67 @@
+using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>SQLite-backed, append-only audit store for API-key events.</summary>
+public sealed class SqliteApiKeyAuditStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAuditStore
+{
+    /// <inheritdoc />
+    public async Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            INSERT INTO api_key_audit (key_id, event_type, remote_address, created_utc, details)
+            VALUES ($key_id, $event_type, $remote_address, $created_utc, $details);
+            """;
+        command.Parameters.AddWithValue("$key_id", (object?)entry.KeyId ?? DBNull.Value);
+        command.Parameters.AddWithValue("$event_type", entry.EventType);
+        command.Parameters.AddWithValue("$remote_address", (object?)entry.RemoteAddress ?? DBNull.Value);
+        command.Parameters.AddWithValue("$created_utc", entry.CreatedUtc.ToString("O"));
+        command.Parameters.AddWithValue("$details", (object?)entry.Details ?? DBNull.Value);
+
+        await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct)
+    {
+        if (limit <= 0)
+        {
+            return [];
+        }
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            SELECT key_id, event_type, remote_address, created_utc, details
+            FROM api_key_audit
+            ORDER BY audit_id DESC
+            LIMIT $limit;
+            """;
+        command.Parameters.AddWithValue("$limit", limit);
+
+        List<ApiKeyAuditEntry> entries = [];
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            entries.Add(new ApiKeyAuditEntry(
+                KeyId: reader.IsDBNull(0) ? null : reader.GetString(0),
+                EventType: reader.GetString(1),
+                RemoteAddress: reader.IsDBNull(2) ? null : reader.GetString(2),
+                CreatedUtc: SqliteValueParsing.ParseUtc(reader.GetString(3)),
+                Details: reader.IsDBNull(4) ? null : reader.GetString(4)));
+        }
+
+        return entries;
+    }
+}
@@ -0,0 +1,76 @@
+using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>SQLite-backed read store for API-key records.</summary>
+public sealed class SqliteApiKeyStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyStore
+{
+    private const string SelectColumns =
+        "key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc";
+
+    /// <inheritdoc />
+    public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        return FindAsync(keyId, requireActive: false, ct);
+    }
+
+    /// <inheritdoc />
+    public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        return FindAsync(keyId, requireActive: true, ct);
+    }
+
+    /// <inheritdoc />
+    public async Task MarkUsedAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(keyId);
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET last_used_utc = $last_used_utc
+            WHERE key_id = $key_id AND revoked_utc IS NULL;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.AddWithValue("$last_used_utc", whenUtc.ToString("O"));
+
+        await command.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+    }
+
+    private async Task<ApiKeyRecord?> FindAsync(string keyId, bool requireActive, CancellationToken ct)
+    {
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(ct).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = requireActive
+            ? $"SELECT {SelectColumns} FROM api_keys WHERE key_id = $key_id AND revoked_utc IS NULL;"
+            : $"SELECT {SelectColumns} FROM api_keys WHERE key_id = $key_id;";
+        command.Parameters.AddWithValue("$key_id", keyId);
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        if (!await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            return null;
+        }
+
+        return ReadRecord(reader);
+    }
+
+    internal static ApiKeyRecord ReadRecord(SqliteDataReader reader) => new(
+        KeyId: reader.GetString(0),
+        KeyPrefix: reader.GetString(1),
+        SecretHash: reader.GetFieldValue<byte[]>(2),
+        DisplayName: reader.GetString(3),
+        Scopes: ScopeSerializer.Deserialize(reader.GetString(4)),
+        ConstraintsJson: reader.IsDBNull(5) ? null : reader.GetString(5),
+        CreatedUtc: SqliteValueParsing.ParseUtc(reader.GetString(6)),
+        LastUsedUtc: SqliteValueParsing.ReadNullableUtc(reader, 7),
+        RevokedUtc: SqliteValueParsing.ReadNullableUtc(reader, 8));
+}
@@ -0,0 +1,64 @@
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>
+/// Schema constants and table DDL for the API-key SQLite store.
+/// </summary>
+public static class SqliteAuthSchema
+{
+    /// <summary>The schema version this build creates and supports.</summary>
+    public const int CurrentVersion = 1;
+
+    /// <summary>Name of the single-row table tracking the applied schema version.</summary>
+    public const string SchemaVersionTable = "schema_version";
+
+    /// <summary>Name of the table storing API-key records.</summary>
+    public const string ApiKeysTable = "api_keys";
+
+    /// <summary>Name of the append-only audit table.</summary>
+    public const string ApiKeyAuditTable = "api_key_audit";
+
+    /// <summary>DDL creating the single-row schema-version table.</summary>
+    public const string CreateSchemaVersionTable = """
+        CREATE TABLE IF NOT EXISTS schema_version (
+            id INTEGER PRIMARY KEY CHECK (id = 1),
+            version INTEGER NOT NULL,
+            applied_utc TEXT NOT NULL
+        );
+        """;
+
+    /// <summary>DDL creating the API-key record table.</summary>
+    public const string CreateApiKeysTable = """
+        CREATE TABLE IF NOT EXISTS api_keys (
+            key_id TEXT PRIMARY KEY,
+            key_prefix TEXT NOT NULL,
+            secret_hash BLOB NOT NULL,
+            display_name TEXT NOT NULL,
+            scopes TEXT NOT NULL,
+            constraints TEXT NULL,
+            created_utc TEXT NOT NULL,
+            last_used_utc TEXT NULL,
+            revoked_utc TEXT NULL
+        );
+        """;
+
+    /// <summary>DDL creating the append-only audit table.</summary>
+    public const string CreateApiKeyAuditTable = """
+        CREATE TABLE IF NOT EXISTS api_key_audit (
+            audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
+            key_id TEXT NULL,
+            event_type TEXT NOT NULL,
+            remote_address TEXT NULL,
+            created_utc TEXT NOT NULL,
+            details TEXT NULL
+        );
+        """;
+
+    /// <summary>DDL creating supporting indexes (idempotent).</summary>
+    public const string CreateIndexes = """
+        CREATE INDEX IF NOT EXISTS ix_api_keys_revoked_utc
+            ON api_keys (revoked_utc);
+
+        CREATE INDEX IF NOT EXISTS ix_api_key_audit_key_id_created_utc
+            ON api_key_audit (key_id, created_utc);
+        """;
+}
@@ -0,0 +1,130 @@
+using System.Globalization;
+using Microsoft.Data.Sqlite;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>Thrown when the auth store cannot be migrated to the supported schema.</summary>
+public sealed class AuthStoreMigrationException(string message) : InvalidOperationException(message);
+
+/// <summary>
+/// Creates the API-key store schema and records the applied version. Idempotent: it
+/// is safe to run repeatedly. Refuses to run against a database whose on-disk version
+/// is newer than this build supports.
+/// </summary>
+public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory)
+{
+    /// <summary>Applies the schema migration to the auth store.</summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <exception cref="AuthStoreMigrationException">
+    /// The on-disk schema version is newer than <see cref="SqliteAuthSchema.CurrentVersion"/>.
+    /// </exception>
+    public async Task MigrateAsync(CancellationToken cancellationToken)
+    {
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
+
+        await using SqliteTransaction transaction =
+            (SqliteTransaction)await connection.BeginTransactionAsync(System.Data.IsolationLevel.Serializable, cancellationToken).ConfigureAwait(false);
+
+        int existingVersion =
+            await ReadExistingSchemaVersionAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+
+        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 WriteSchemaVersionAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+
+        await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task<int> ReadExistingSchemaVersionAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        CancellationToken cancellationToken)
+    {
+        await using SqliteCommand tableExistsCommand = connection.CreateCommand();
+        tableExistsCommand.Transaction = transaction;
+        tableExistsCommand.CommandText = """
+            SELECT COUNT(*)
+            FROM sqlite_master
+            WHERE type = 'table' AND name = $table_name;
+            """;
+        tableExistsCommand.Parameters.AddWithValue("$table_name", SqliteAuthSchema.SchemaVersionTable);
+
+        long tableCount =
+            (long)(await tableExistsCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false) ?? 0L);
+
+        if (tableCount == 0)
+        {
+            return 0;
+        }
+
+        await using SqliteCommand versionCommand = connection.CreateCommand();
+        versionCommand.Transaction = transaction;
+        versionCommand.CommandText = """
+            SELECT version
+            FROM schema_version
+            WHERE id = 1;
+            """;
+
+        object? version = await versionCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+
+        return version is null || version == DBNull.Value
+            ? 0
+            : Convert.ToInt32(version, CultureInfo.InvariantCulture);
+    }
+
+    private static async Task ApplyVersionOneAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        CancellationToken cancellationToken)
+    {
+        await ExecuteNonQueryAsync(
+            connection,
+            transaction,
+            string.Join(
+                "\n",
+                SqliteAuthSchema.CreateSchemaVersionTable,
+                SqliteAuthSchema.CreateApiKeysTable,
+                SqliteAuthSchema.CreateApiKeyAuditTable,
+                SqliteAuthSchema.CreateIndexes),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task WriteSchemaVersionAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        CancellationToken cancellationToken)
+    {
+        await using SqliteCommand versionCommand = connection.CreateCommand();
+        versionCommand.Transaction = transaction;
+        versionCommand.CommandText = """
+            INSERT INTO schema_version (id, version, applied_utc)
+            VALUES (1, $version, $applied_utc)
+            ON CONFLICT(id) DO UPDATE SET
+                version = excluded.version,
+                applied_utc = excluded.applied_utc;
+            """;
+        versionCommand.Parameters.AddWithValue("$version", SqliteAuthSchema.CurrentVersion);
+        versionCommand.Parameters.AddWithValue("$applied_utc", DateTimeOffset.UtcNow.ToString("O"));
+
+        await versionCommand.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task ExecuteNonQueryAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        string commandText,
+        CancellationToken cancellationToken)
+    {
+        await using SqliteCommand command = connection.CreateCommand();
+        command.Transaction = transaction;
+        command.CommandText = commandText;
+
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+}
@@ -0,0 +1,20 @@
+using System.Globalization;
+using Microsoft.Data.Sqlite;
+
+namespace ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+/// <summary>
+/// Shared helpers for reading round-trippable timestamps out of the SQLite stores.
+/// All timestamps are persisted with the round-trip ("O") format, so parsing is centralized
+/// here to keep the three stores DRY and consistent.
+/// </summary>
+internal static class SqliteValueParsing
+{
+    /// <summary>Parses a round-trip ("O") formatted timestamp written by the stores.</summary>
+    internal static DateTimeOffset ParseUtc(string value) =>
+        DateTimeOffset.Parse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind);
+
+    /// <summary>Reads a nullable round-trip timestamp at <paramref name="ordinal"/>.</summary>
+    internal static DateTimeOffset? ReadNullableUtc(SqliteDataReader reader, int ordinal) =>
+        reader.IsDBNull(ordinal) ? null : ParseUtc(reader.GetString(ordinal));
+}