Merge branch 'f_vault4' into f_complementation

Co-authored-by: d2dyno1 <53011783+d2dyno1@users.noreply.github.com>

Author: Copilot

README.md

@@ -50,7 +50,7 @@ This ensures that your data will always remain secure.
 
 > [!TIP]
 > The purpose of SecureFolderFS is to provide a professional, usable 'safe folder' experience that supports all major platforms with a consistent feature set.
-> SecureFolderFS can run on a huge range of devices (as supported by Uno Platform, MAUI and the .NET Runtime).
+> SecureFolderFS can run on a huge range of devices (as supported by Uno Platform, .NET MAUI, and the .NET Runtime).
 
 ### How to use SecureFolderFS
 
@@ -69,8 +69,8 @@ From the app's UI, you can create new vaults to store items securely.
 </p>
 
 > *Upon entering the correct password, the vault will then open.*
-> *You can press 'View vault' to open the vault's mounted file-system in your file manager of choice.*
-> *When you're done accessing your files, you can press the 'Lock vault' button and the vault file-system will close.*
+> *You can press 'View vault' to open the vault's mounted file system in your file manager of choice.*
+> *When you're done accessing your files, you can press the 'Lock vault' button, and the vault file system will close.*
 > *The vault remains on your disk and your data is encrypted in a way that cannot be accessed by any program, past, present or future.*
 
 ## Contributing
@@ -83,15 +83,17 @@ Take a look at our *[contributing guidelines](CONTRIBUTING.md)* to learn about b
 
 You can update existing localization strings by heading to our *[Crowdin project page](https://crowdin.com/project/securefolderfs)*.
 To add a new language to the list, please request it to be added *[here](https://github.com/securefolderfs-community/SecureFolderFS/issues/50)*.
-New translations will be synchronized periodically to the source code, and new releases will always contain the latest translations.
+New translations will be synchronized periodically with the source code, and new releases will always contain the latest translations.
+
+For help with translating custom-format strings with pluralization support, refer to the [Localization Playground](https://github.com/securefolderfs-community/LocalizationPlayground) repository. 
 
 ---
 
 ## Building from source
 
 > [!NOTE]
 > Below are the instructions for building SecureFolderFS for a cross-platform target.
-> For other projects, such as the SDK, libraries and CLI program, you can build as normal with the latest .NET SDK, without the prerequisites listed below.
+> For other projects, such as the SDK, libraries, and CLI program, you can build as normal with the latest .NET SDK, without the prerequisites listed below.
 
 ### 1. Prerequisites
 
@@ -104,7 +106,7 @@ New translations will be synchronized periodically to the source code, and new r
 - For iOS builds:
   - Xcode 26.2 (on macOS)
 
-### 2. Set up IDE
+### 2. Set up the IDE
 
 > [!TIP]
 > *Using Visual Studio 2026 is recommended for SecureFolderFS development.*
@@ -130,7 +132,7 @@ New translations will be synchronized periodically to the source code, and new r
 ### 3. Run `Uno.Check`
 
 > [!TIP]
-> *This step is optional, but is good practice to check you installed all the necessary dependencies to build SecureFolderFS on your computer.*
+> *This step is optional, but it is good practice to check that you installed all the necessary dependencies to build SecureFolderFS on your computer.*
 
 Run the following command and follow all of its instructions (you need to have `Uno.Check` installed!)
 
@@ -154,13 +156,13 @@ cd SecureFolderFS
 ### 5. Build the project
 
 - Open the solution `SecureFolderFS.Public.slnx`
-- Set `SecureFolderFS.Uno` as the startup project if you are building for desktop targets (i.e. macOS, Linux or Windows)
-- Set `SecureFolderFS.Maui` as the startup project if you are building for mobile targets (i.e. Android, iOS or iPadOS)
-- Select the appropriate target device / platform
+- Set `SecureFolderFS.Uno` as the startup project if you are building for desktop targets (i.e., macOS, Linux, or Windows)
+- Set `SecureFolderFS.Maui` as the startup project if you are building for mobile targets (i.e., Android, iOS, or iPadOS)
+- Select the appropriate target device/platform
 - Run with debugger
 
 ---
 
 <p align="center">
   <img src=".github/assets/SecureFolderFS_Hero.png" />
-</p>
+</p>

src/Core/SecureFolderFS.Core.Cryptography/Cipher/SecombaBase4K.cs

@@ -0,0 +1,265 @@
+// Some parts of the following code were used from Secomba/Base4K on the MIT License basis.
+// See the associated license file for more information.
+
+using System;
+using System.Buffers;
+using System.IO;
+using System.Runtime.CompilerServices;
+using System.Text;
+
+namespace SecureFolderFS.Core.Cryptography.Cipher
+{
+    public enum Base4KVersion
+    {
+        V1,
+        V2
+    }
+
+    public static class SecombaBase4K
+    {
+        // Base addresses for mapping regions
+        private const int BASE_FLAG_START = 0x04000;
+        private const int BASE1_START = 0x06000;
+        private const int BASE1_START_LEGACY = 0x05000;
+
+        // Sizes of each mapping region
+        private const int BASE_FLAG_SIZE = 0x100;
+        private const int BASE1_SIZE = 0x01000;
+
+        private static readonly UTF8Encoding Utf8Encoding = new UTF8Encoding(true, true);
+
+        /// <summary>
+        /// Encodes the specified raw bytes as a Base4K string, mapping each group of bits
+        /// to Unicode characters in a specific range, suitable for use as file names.
+        /// </summary>
+        /// <param name="raw">The raw bytes to encode.</param>
+        /// <param name="version">The version of Base4K encoding to use. Defaults to <see cref="Base4KVersion.V2"/>.</param>
+        /// <returns>A Base4K-encoded string representation of the input bytes.</returns>
+        /// <exception cref="ArgumentException">Thrown when <paramref name="raw"/> is empty or too short to encode.</exception>
+        [SkipLocalsInit]
+        public static string Encode(ReadOnlySpan<byte> raw, Base4KVersion version = Base4KVersion.V2)
+        {
+            if (raw.Length <= 1)
+                throw new ArgumentException("Input must be at least 2 bytes long.", nameof(raw));
+
+            var maxByteCount = (raw.Length + 1) * 3;
+            var rentedBuffer = ArrayPool<byte>.Shared.Rent(maxByteCount);
+            try
+            {
+                var buffer = rentedBuffer.AsSpan();
+                var bufferPos = 0;
+                Span<byte> utf8Buffer = stackalloc byte[4];
+                int offset;
+
+                for (var i = 0; i < raw.Length * 2 - 2; i += 3)
+                {
+                    offset = i % 2 == 0
+                        ? ((raw[i / 2] << 4) | ((raw[i / 2 + 1] >> 4) & 0x0f)) & 0x0fff
+                        : ((raw[i / 2] << 8) | (raw[i / 2 + 1] & 0xff)) & 0x0fff;
+
+                    offset += version == Base4KVersion.V1 ? BASE1_START_LEGACY : BASE1_START;
+
+                    var written = ToUtf8(offset, utf8Buffer);
+                    utf8Buffer.Slice(0, written).CopyTo(buffer.Slice(bufferPos));
+                    bufferPos += written;
+                }
+
+                if ((raw.Length * 2) % 3 == 2)
+                {
+                    offset = (raw[^1] & 0xff) + BASE_FLAG_START;
+                    var written = ToUtf8(offset, utf8Buffer);
+                    utf8Buffer.Slice(0, written).CopyTo(buffer.Slice(bufferPos));
+                    bufferPos += written;
+                }
+                else if ((raw.Length * 2) % 3 == 1)
+                {
+                    offset = (raw[^1] & 0x0f) + BASE_FLAG_START;
+                    var written = ToUtf8(offset, utf8Buffer);
+                    utf8Buffer.Slice(0, written).CopyTo(buffer.Slice(bufferPos));
+                    bufferPos += written;
+                }
+
+                return Utf8Encoding.GetString(buffer.Slice(0, bufferPos));
+            }
+            finally
+            {
+                ArrayPool<byte>.Shared.Return(rentedBuffer);
+            }
+        }
+
+        /// <summary>
+        /// Decodes a Base4K-encoded string back to the original raw bytes.
+        /// Attempts decoding with both V2 and V1 (legacy) base addresses automatically.
+        /// </summary>
+        /// <param name="encoded">The Base4K-encoded string to decode.</param>
+        /// <returns>The decoded bytes, or <see langword="null"/> if decoding failed due to invalid or malformed input.</returns>
+        public static byte[]? Decode(ReadOnlySpan<char> encoded)
+        {
+            return DecodeInternal(encoded, BASE1_START) ?? DecodeInternal(encoded, BASE1_START_LEGACY);
+        }
+
+        private static byte[]? DecodeInternal(ReadOnlySpan<char> encoded, int base1Start)
+        {
+            var byteCount = Utf8Encoding.GetByteCount(encoded);
+            var encBytes = new byte[byteCount];
+            var written = Utf8Encoding.GetBytes(encoded, encBytes);
+
+            using var memoryStream = new MemoryStream();
+            var rentedCollector = ArrayPool<int>.Shared.Rent(written / 3 + 1);
+            var collectorCount = 0;
+            try
+            {
+                for (var i = 0; i < written;)
+                {
+                    int nrOfBytes;
+                    if ((encBytes[i] & 0x80) == 0)
+                    {
+                        // 1 byte
+                        nrOfBytes = 1;
+                    }
+                    else if ((encBytes[i] & 0x40) == 0)
+                    {
+                        // Continuation byte — invalid as a leading byte
+                        return null;
+                    }
+                    else if ((encBytes[i] & 0x20) == 0)
+                    {
+                        // 2 bytes
+                        nrOfBytes = 2;
+                    }
+                    else if ((encBytes[i] & 0x10) == 0)
+                    {
+                        // 3 bytes
+                        nrOfBytes = 3;
+                    }
+                    else if ((encBytes[i] & 0x08) == 0)
+                    {
+                        // 4 bytes
+                        nrOfBytes = 4;
+                    }
+                    else
+                    {
+                        // Invalid leading byte
+                        return null;
+                    }
+
+                    var code = ToCode(encBytes, i, nrOfBytes);
+                    i += nrOfBytes;
+
+                    if (!(code >= base1Start && code < base1Start + BASE1_SIZE))
+                    {
+                        if (i < written || !(code >= BASE_FLAG_START && code < BASE_FLAG_START + BASE_FLAG_SIZE))
+                            return null;
+                    }
+
+                    rentedCollector[collectorCount++] = code;
+                }
+
+                for (var i = 0; i < collectorCount; i++)
+                {
+                    if (rentedCollector[i] >= base1Start)
+                        rentedCollector[i] -= base1Start;
+                    else
+                    {
+                        rentedCollector[i] -= BASE_FLAG_START;
+                        if (i % 2 == 0)
+                            memoryStream.WriteByte((byte)rentedCollector[i]);
+                        else
+                            memoryStream.WriteByte((byte)(((rentedCollector[i - 1] << 4) | ((rentedCollector[i] & 0x0f)) & 0xff)));
+
+                        break;
+                    }
+
+                    if (i % 2 == 0)
+                        memoryStream.WriteByte((byte)(rentedCollector[i] >> 4));
+                    else
+                    {
+                        memoryStream.WriteByte((byte)(((rentedCollector[i - 1] << 4) | ((rentedCollector[i] & 0x0f00) >> 8)) & 0xff));
+                        memoryStream.WriteByte((byte)(rentedCollector[i] & 0xff));
+                    }
+                }
+            }
+            finally
+            {
+                ArrayPool<int>.Shared.Return(rentedCollector);
+            }
+
+            return memoryStream.ToArray();
+        }
+
+        private static int ToUtf8(int code, Span<byte> destination)
+        {
+            switch (code)
+            {
+                case > 0xffff:
+                {
+                    destination[0] = (byte)(0xf0 | ((code >> 18) & 0x07));
+                    destination[1] = (byte)(0x80 | ((code >> 12) & 0x3f));
+                    destination[2] = (byte)(0x80 | ((code >> 6) & 0x3f));
+                    destination[3] = (byte)(0x80 | (code & 0x3f));
+                    return 4;
+                }
+
+                case > 0x7ff:
+                {
+                    destination[0] = (byte)(0xe0 | ((code >> 12) & 0x0f));
+                    destination[1] = (byte)(0x80 | ((code >> 6) & 0x3f));
+                    destination[2] = (byte)(0x80 | (code & 0x3f));
+                    return 3;
+                }
+
+                case > 0x7f:
+                {
+                    destination[0] = (byte)(0xc0 | ((code >> 6) & 0x1f));
+                    destination[1] = (byte)(0x80 | (code & 0x3f));
+                    return 2;
+                }
+
+                default:
+                {
+                    destination[0] = (byte)(code & 0x7f);
+                    return 1;
+                }
+            }
+        }
+
+        private static int ToCode(ReadOnlySpan<byte> utf8Char, int offset, int length)
+        {
+            var result = 0;
+            switch (length)
+            {
+                case 1:
+                {
+                    result |= utf8Char[offset];
+                    break;
+                }
+
+                case 2:
+                {
+                    result |= (utf8Char[offset + 0] & 0x1f) << 6;
+                    result |= (utf8Char[offset + 1] & 0x3f);
+                    break;
+                }
+
+                case 3:
+                {
+                    result |= (utf8Char[offset + 0] & 0x0f) << 12;
+                    result |= (utf8Char[offset + 1] & 0x3f) << 6;
+                    result |= (utf8Char[offset + 2] & 0x3f);
+                    break;
+                }
+
+                case 4:
+                {
+                    result |= (utf8Char[offset + 0] & 0x07) << 18;
+                    result |= (utf8Char[offset + 1] & 0x3f) << 12;
+                    result |= (utf8Char[offset + 2] & 0x3f) << 6;
+                    result |= (utf8Char[offset + 3] & 0x3f);
+                    break;
+                }
+            }
+
+            return result;
+        }
+    }
+}

src/Core/SecureFolderFS.Core.Cryptography/Constants.cs

@@ -9,10 +9,10 @@ public static class KeyTraits
             public const int DEK_KEY_LENGTH = 32;
             public const int MAC_KEY_LENGTH = 32;
             public const int ARGON2_KEK_LENGTH = 32;
-            public const int CHALLENGE_KEY_PART_LENGTH_32 = 32;
-            public const int CHALLENGE_KEY_PART_LENGTH_64 = 64;
-            public const int CHALLENGE_KEY_PART_LENGTH_128 = 128;
-            public const int ECIES_SHA256_AESGCM_STDX963_KEY_LENGTH = CHALLENGE_KEY_PART_LENGTH_32;
+            public const int KEY_PART_LENGTH_32 = 32;
+            public const int KEY_PART_LENGTH_64 = 64;
+            public const int KEY_PART_LENGTH_128 = 128;
+            public const int ECIES_SHA256_AESGCM_STDX963_KEY_LENGTH = KEY_PART_LENGTH_32;
             public const int HMAC_SHA1_HASH_LENGTH = 20;
         }
 

src/Core/SecureFolderFS.Core.Cryptography/Helpers/CryptHelpers.cs

@@ -10,7 +10,7 @@ namespace SecureFolderFS.Core.Cryptography.Helpers
 {
     public static class CryptHelpers
     {
-        public static IKeyBytes GenerateChallenge(string vaultId, int challengeSize = Constants.KeyTraits.CHALLENGE_KEY_PART_LENGTH_128)
+        public static IKeyBytes GenerateChallenge(string vaultId, int challengeSize = Constants.KeyTraits.KEY_PART_LENGTH_128)
         {
             var encodedVaultIdLength = Encoding.ASCII.GetByteCount(vaultId);
             var challenge = new byte[challengeSize + encodedVaultIdLength];