Guid74 1.0.0

Guid74

Lightweight .NET library to generate UUIDv7 and present them as UUIDv4 facades using a keyed SipHash mask. Useful when you need time-ordered IDs internally but want identifiers that look like random v4 UUIDs for external consumption.

Install

Install from NuGet (replace with actual package id if published):

dotnet add package Guid74

Quick start

Register the library in your application's DI container and configure a seed Guid:

services.AddGuid74();
services.Configure<Guid74Options>(o => o.SeedGuid = Guid.Parse("11111111-2222-3333-4444-555555555555"));

Resolve the service and use it:

var svc = provider.GetRequiredService<Guid74Service>();
var v7 = svc.NewV7();                // generate UUIDv7
var facade = svc.EncodeFacade(v7);   // produce a v4-looking facade
var original = svc.DecodeFacade(facade); // recover v7 (requires same seed)

API

Types

• Guid74Options

  • SeedGuid (Guid) � required seed used to derive SipHash keys.

• Guid74Service

  • NewV7() → Guid
  • NewV4() → Guid
  • EncodeFacade(Guid v7) → Guid
  • DecodeFacade(Guid facadeV4) → Guid

• Guid74Codec

  • Same public methods as Guid74Service (NewV7, NewV4, EncodeFacade, DecodeFromFacade)

How it works

• UUIDv7 generation: writes a 48-bit Unix epoch milliseconds timestamp into bytes 0..5 (RFC byte order), fills remaining bytes with randomness, and sets version/variant bits.
• Facade encoding: builds a 10-byte message from the UUID fields (excluding timestamp), computes a SipHash keyed by a seed-derived key, takes the low 48 bits of the hash as a mask, XORs the mask with the timestamp, then marks the UUID as version 4.
• Decoding reverses the mask using the same seed to recover the original timestamp and restores version 7.

Configuration and secrets

• SeedGuid must be set via Guid74Options. The seed is used to derive SipHash K0/K1 and is critical to decoding facades.
• You may use an Azure GUID such as TenantId or Application (Client)Id as the seed for convenience. Note that these IDs are often public; if the seed must remain secret, store a dedicated GUID in a secret store (Key Vault, environment variable, etc.).

Notes on security

• The facade masks only the 48-bit timestamp. It is not a general-purpose encryption mechanism.
• The library pins and zeros seed bytes when deriving keys to reduce memory leakage, but you should still manage the seed securely.

Dependencies

• PinnedMemory
• SipHash

Contributing

PRs welcome. Please include tests and keep behavior backwards compatible.