ASP.NET Core で UUIDv7 のタイムスタンプ部を UUIDv47 アルゴリズムでマスクし、可逆的に変換するライブラリ
$ dotnet add package MaskedUUID.AspNetCoreASP.NET Core で UUIDv7 のタイムスタンプ部を UUIDv47 アルゴリズムでマスクし、可逆的に変換するライブラリです。
このライブラリは UUIDv47Sharp (C#実装)を使用して、GUID を可逆的にマスク化します。
UUIDv47 は UUIDv7 のタイムスタンプ部を隠蔽するための可逆エンコーディング形式です。
IMaskedUUIDKeyProvider でキーを提供(テナントごとに異なるキーなど柔軟に対応可能)UUIDv7 は先頭48ビットにタイムスタンプを含むため、そのまま公開すると リソースの作成日時が暴露 されてしまいます。
これにより以下のような情報漏洩リスクがあります:
このライブラリは、以下のタイミングで自動的に UUIDv7 ↔ UUIDv47 変換を行います:
MaskedGuid 型のプロパティが JSON に出力される際、UUIDv47 に変換/items/{id} のような URL で UUIDv47 の ID を受け取り、自動復元MaskedGuid 型のプロパティを自動変換MaskedGuid は JSON の入出力のみ でマスク(エンコード/デコード)されます。MaskedGuid.ToString() は 生の Guid 文字列 を返します(マスク文字列ではありません)。MaskedGuid は JSON 変換時に IMaskedUUIDService を使ってマスク化します。Guid.Empty(空 GUID) は JSON 出力で になります。nullnull / ""(空文字)は Guid.Empty として扱われます。MaskedGuid 用の JSON 変換は HttpContext から IMaskedUUIDService を解決します。MaskedGuid を JSON シリアライズ/デシリアライズすると例外になります。MaskedGuid / MaskedGuid? 型のみ 対象です。[MaskedUUID] 属性は使用しません(属性ベースの処理はありません)。MaskedGuid? はデコード結果が Guid.Empty の場合 null として扱われます。MaskedGuid はデコード結果が Guid.Empty の場合 Guid.Empty のまま扱われます。
Guid.Empty は null として出力され、読み込み時は Guid.Empty として扱われます。IMaskedUUIDKeyProvider を登録IMaskedUUIDService を登録AddMaskedUUID() と AddMaskedUUIDModelBinder() を追加サンプルは samples/MaskedUUID.Sample を参照してください。
// KeyProviderを登録(Singleton推奨、Scopedも可)
builder.Services.AddSingleton<IMaskedUUIDKeyProvider, MyKeyProvider>();
// MaskedUUID対応を追加
builder.Services.AddMaskedUUID();
// ModelBinderを追加(URL/クエリパラメータ用)
mvcBuilder.AddMaskedUUIDModelBinder();
// または一括で
mvcBuilder.AddMaskedUUIDControllers();SignalR対応には AddMaskedUUID() 拡張メソッドを使用します。
// KeyProviderを登録
builder.Services.AddSingleton<IMaskedUUIDKeyProvider, MyKeyProvider>();
// SignalRにMaskedUUID対応を追加
builder.Services.AddSignalR().AddMaskedUUID();SignalR用のコンバーターは以下の優先順位でサービスを解決します:
これにより、KeyProvider/Serviceが Singleton / Scoped / Transient のいずれでも正しく動作します。
// 開発/テスト用に参照キーを使用(本番では使用しないでください)
builder.Services.AddSignalR().AddMaskedUUIDWithReferenceKeys();.NET 10以降 / .NET 9 に対応しています。
// OpenAPIスキーマトランスフォーマーを追加
builder.Services.AddOpenApi(options => options.AddMaskedGuidSchemaTransformer());.NET 10以降では JsonSchemaType enum、.NET 9では文字列ベースの型指定に自動的に対応します。