Add CryptoOptions.GenerateSalt() and DeriveKey() helpers; fix encryption documentation by Copilot · Pull Request #128 · EntglDb/BLite

Copilot · 2026-07-08T22:01:00Z

The published encryption docs referenced using BLite.Core.Crypto; (wrong namespace), CryptoOptions.GenerateSalt(), and CryptoOptions.DeriveKey() — none of which existed in BLite.Core 5.0.2.

API additions (`CryptoOptions`)

GenerateSalt() — static, returns byte[32] of cryptographically random bytes via RandomNumberGenerator.Fill
DeriveKey(string passphrase, byte[] salt, int iterations = 600_000) — static PBKDF2-SHA256 wrapper; result is suitable for CryptoOptions.FromMasterKey(key)

These make the documented "external salt file" pattern functional:

using BLite.Core.Encryption; // correct namespace

// One-time setup
byte[] salt = CryptoOptions.GenerateSalt();
File.WriteAllBytes("secure.salt", salt);

// Subsequent opens
byte[] storedSalt = File.ReadAllBytes("secure.salt");
byte[] key        = CryptoOptions.DeriveKey("my-passphrase", storedSalt);
using var engine  = new BLiteEngine("secure.blite", CryptoOptions.FromMasterKey(key));

README encryption section rewrite

Correct namespace (using BLite.Core.Encryption;)
Simple passphrase mode (recommended) — new CryptoOptions("passphrase") with salt auto-managed in the 64-byte file header; no salt file needed
DocumentDbContext with encryption example
Advanced salt-file workflow using the new helpers
Master-key mode (KMS/HSM) and migration/rotation examples retained

…ion docs - Add CryptoOptions.GenerateSalt() returning 32 cryptographically random bytes - Add CryptoOptions.DeriveKey(passphrase, salt, iterations) for external key derivation - Update README.md encryption section with correct namespace (BLite.Core.Encryption), simple passphrase examples, DocumentDbContext pattern, and advanced salt-file workflow - Update doc comments to remove OWASP year reference - Add 8 new tests covering the new static helpers Fixes #127

mrdevrobot · 2026-07-08T22:44:11Z

@copilot the documentation mentioned is the one published in the public website (please see https://github.com/EntglDb/BLite.Website) we'd rather check if there are other wrong assumptions in the documentation and plan the fix in the source code (if makes sense) or open an issue in the documentation repo

…nings

Copilot · 2026-07-08T22:55:54Z

@copilot the documentation mentioned is the one published in the public website (please see https://github.com/EntglDb/BLite.Website) we'd rather check if there are other wrong assumptions in the docu...

I've reviewed the BLite.Website docs page by page against the source code. Here's the full picture:

Source code fixes applied in this PR

Gap	Fix
`CryptoOptions.GenerateSalt()` missing	✅ Added (already in this PR)
`CryptoOptions.DeriveKey()` missing	✅ Added (already in this PR)
`DocumentCollection<TId,T>.SetRetentionPolicy()` was `internal`, but `DynamicCollection.SetRetentionPolicy()` is `public`	✅ Made public (commit `$(git rev-parse --short HEAD)`)

Issues to track in BLite.Website

Encryption.vue — 3 mismatches:

using BLite.Core.Crypto; → correct namespace is using BLite.Core.Encryption;
new CryptoOptions { Key = key } / IBLiteCryptoProvider / new CryptoOptions { Provider = ... } — these types/properties don't exist. The correct patterns are the passphrase constructor new CryptoOptions("passphrase"), CryptoOptions.FromMasterKey(key), and ICryptoProvider (not IBLiteCryptoProvider); custom provider injection via CryptoOptions is not currently supported.

AuditTrail.vue — BLiteMetrics example references metrics.TotalUpdates, metrics.TotalDeletes, and metrics.StorageSizeBytes — none of which exist. The actual counters are TotalInserts, TotalQueriesIndexScan, TotalQueriesBsonScan, TotalQueriesFullScan, TotalCommits.

GDPR.vue — 3 mismatches:

engine.GetOrCreateCollection<ObjectId, AuditEntry>(mapper) — typed collections come from DocumentDbContext, not BLiteEngine.
col.HasRetentionPolicy(...) — correct name is col.SetRetentionPolicy(...) (now public after this PR).
await col.PruneAsync() → correct name is await col.ForceApplyRetentionPolicyAsync().

TimeSeries.vue — ForcePrune() → ForcePruneAsync().

CDC.vue — sample references type name DocumentDb → correct name is DocumentDbContext.

Spatial.vue — EnsureSpatialIndex(...) and GetCollection<T>() are not present in the current source; the correct methods are HasSpatialIndex(...) on the model builder and GetOrCreateCollection(name) on BLiteEngine.

Copilot

Pull request overview

This PR aligns the published encryption documentation with the actual BLite.Core.Encryption API by adding the missing CryptoOptions.GenerateSalt() and CryptoOptions.DeriveKey() helpers and updating the README encryption guidance accordingly.

Changes:

Add CryptoOptions.GenerateSalt() and CryptoOptions.DeriveKey(...) helpers and corresponding unit tests.
Rewrite/expand README encryption section with correct namespace and multiple usage modes (simple passphrase, salt-file workflow, master-key mode).
Update WAL encryption tests to use async Task + await instead of blocking on async calls.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/BLite.Tests/EncryptionTests.cs	Adds coverage for the new `CryptoOptions` helpers and modernizes WAL tests to be properly async.
src/BLite.Core/Encryption/CryptoOptions.cs	Introduces `GenerateSalt()` and `DeriveKey()` and updates KDF documentation wording.
src/BLite.Core/Collections/DocumentCollection.cs	Changes retention-policy setter visibility and updates its XML docs.
README.md	Rewrites the encryption documentation with corrected namespace and new helper-based examples.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    /// <summary>
+    /// Generates a cryptographically random 32-byte salt suitable for use with
+    /// <see cref="DeriveKey(string, byte[])"/> or manual PBKDF2 key derivation via
+    /// <see cref="System.Security.Cryptography.Rfc2898DeriveBytes"/>.
+    /// </summary>


+    public static byte[] DeriveKey(string passphrase, byte[] salt, int iterations = 600_000)
+    {
+        if (string.IsNullOrEmpty(passphrase))
+            throw new ArgumentNullException(nameof(passphrase));
+        if (salt is null || salt.Length < 16)
+            throw new ArgumentException("Salt must be at least 16 bytes.", nameof(salt));
+        if (iterations < 1)
+            throw new ArgumentOutOfRangeException(nameof(iterations), "Iterations must be at least 1.");
+
+        return KeyDerivation.DeriveKeyPbkdf2(passphrase, salt, iterations);
+    }


    /// <summary>
    /// Configures a generalized retention policy for this collection.
    /// The policy is persisted in collection metadata and survives engine restarts.
-    /// Called internally from <see cref="DocumentDbContext"/> when applying builder configuration.
+    /// Can be called directly on the collection or via the model builder in
+    /// <see cref="DocumentDbContext"/> configuration.
    /// </summary>
-    internal void SetRetentionPolicy(RetentionPolicy policy)
+    /// <param name="policy">The retention policy to apply. Must not be null.</param>
+    public void SetRetentionPolicy(RetentionPolicy policy)


Initial plan

90459d6

Copilot AI assigned Copilot and mrdevrobot Jul 8, 2026

Copilot AI linked an issue Jul 8, 2026 that may be closed by this pull request

Encryption Documentation Issues #127

Closed

Copilot started work on behalf of mrdevrobot July 8, 2026 22:01 View session

Copilot AI changed the title ~~[WIP] Update encryption documentation for BLite.Core 5.02~~ Add CryptoOptions.GenerateSalt() and DeriveKey() helpers; fix encryption documentation Jul 8, 2026

Copilot AI requested a review from mrdevrobot July 8, 2026 22:10

Copilot finished work on behalf of mrdevrobot July 8, 2026 22:10

Copilot started work on behalf of mrdevrobot July 8, 2026 22:44 View session

Make DocumentCollection.SetRetentionPolicy public; fix async test war…

82e3cd6

…nings

Copilot finished work on behalf of mrdevrobot July 8, 2026 22:56

PazienzaApp approved these changes Jul 9, 2026

View reviewed changes

mrdevrobot approved these changes Jul 9, 2026

View reviewed changes

mrdevrobot marked this pull request as ready for review July 9, 2026 07:08

Copilot AI review requested due to automatic review settings July 9, 2026 07:08

mrdevrobot merged commit 4dd5bc6 into main Jul 9, 2026
5 checks passed

Copilot started reviewing on behalf of mrdevrobot July 9, 2026 07:12 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add CryptoOptions.GenerateSalt() and DeriveKey() helpers; fix encryption documentation#128

Add CryptoOptions.GenerateSalt() and DeriveKey() helpers; fix encryption documentation#128
mrdevrobot merged 3 commits into
mainfrom
copilot/update-encryption-documentation

Copilot AI commented Jul 8, 2026 •

edited

Loading

Uh oh!

mrdevrobot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Copilot AI commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API additions (CryptoOptions)

README encryption section rewrite

Uh oh!

mrdevrobot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Source code fixes applied in this PR

Issues to track in BLite.Website

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jul 8, 2026 •

edited

Loading

API additions (`CryptoOptions`)