Add NuGet configuration for publishing SensitiveString

.github/workflows/build_and_test.yaml

@@ -0,0 +1,29 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request_target:
+    branches: [ main, develop ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build solution
+        run: dotnet build --configuration Release --no-restore
+
+      - name: Run tests
+        run: dotnet test --no-restore

.github/workflows/publish.yaml

@@ -0,0 +1,44 @@
+name: Publish a NuGet Package
+
+on:
+  release:
+    types: [ published ]
+
+env:
+  BRANCH: main
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build solution
+        run: dotnet build --configuration Release --no-restore
+
+      - name: Run tests
+        run: dotnet test --no-restore
+
+      - shell: pwsh
+        name: Create SNK File
+        env:
+          SNK: ${{ secrets.snk }}
+        run: |
+          $snk = [Convert]::FromBase64String("$env:SNK")
+          Set-Content "src\SensitiveString\SensitiveString.snk" -Value $snk -AsByteStream
+
+      - name: Build NuGet Package
+        run: dotnet pack src\SensitiveString\SensitiveString.csproj --configuration Publish -p:Repository=${{ github.repository }} -p:Branch=${{ env.BRANCH }} -p:Commit=${{ github.sha }}
+
+      - name: Publish NuGet Package
+        run: dotnet nuget push src\SensitiveString\bin\Publish\SensitiveString.*.nupkg --source https://api.nuget.org/v3/index.json --api-key ${{ secrets.nuget_api_key }}

Directory.Packages.props

@@ -5,11 +5,22 @@
   <ItemGroup>
     <PackageVersion Include="HotChocolate" Version="13.9.0" />
     <PackageVersion Include="HotChocolate.Data" Version="13.9.0" />
-    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.3" />
+    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.4" />
     <PackageVersion Include="NSwag.Generation.AspNetCore" Version="14.0.7" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.6.0"/>
-    <PackageVersion Include="xunit" Version="2.4.2"/>
-    <PackageVersion Include="xunit.runner.visualstudio" Version="2.4.5"/>
-    <PackageVersion Include="coverlet.collector" Version="6.0.0"/>
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+    <PackageVersion Include="xunit" Version="2.7.0" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageVersion>
+    <PackageVersion Include="coverlet.collector" Version="6.0.2">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageVersion>
+    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <PackageVersion Include="SauceControl.InheritDoc" Version="2.0.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageVersion>
   </ItemGroup>
 </Project>

README.md

@@ -1,2 +1,123 @@
 # SensitiveString
-A proof of concept to deliver a solution that mitigates the risk of sensitive information leaking into application logs
+Introducing SensitiveString, your shield against inadvertent exposure of sensitive information in application logs and beyond.
+
+This lightweight NuGet package wraps strings in a protective layer, ensuring that sensitive data remains secure and inaccessible without explicit handling.
+
+Safeguard your users' privacy and your application's integrity effortlessly with SensitiveString.
+
+## Example
+
+Let's try to initialize and print a simple record with personal information:
+
+```c#
+internal record PersonDto(string Name, SensitiveString PhoneNumber, SensitiveEmail Email);
+```
+
+```c#
+using SensitiveString;
+
+var person = new PersonDto(
+    "John Doe",
+    "(800) 555‑0123".AsSensitive(),
+    "[email protected]".AsSensitiveEmail()
+);
+
+Console.WriteLine($"Person info: {person}");
+```
+
+What we get in the console is:
+
+```
+Person info: PersonDto { Name = John Doe, PhoneNumber = ***, Email = ***@example.com }
+```
+
+Now let's try to access the original information:
+
+```c#
+Console.WriteLine($"Phone number: {person.PhoneNumber.Reveal()}");
+Console.WriteLine($"Email: {person.Email.Reveal()}");
+```
+
+And what we now get in the console is:
+
+```
+Phone number: (800) 555‑0123
+Email: [email protected]
+```
+
+## How it works?
+
+The `SensitiveString` and `SensitiveEmail` types are straightforward string wrappers. Without special handling, their content remains hidden from standard stringifiers and serializers. So if you're afraid some sensitive data may leak into application logs when stringified implicitly, use one of these two types to prevent that.
+
+`SensitiveEmail` differs from `SensitiveString` only in how it masks the original value. If you prefer having emails fully masked rather than the login part before @, use the `SensitiveString` instead.
+
+
+
+## Serialization/deserialization
+
+In client-server communication we want the information in its original form present in the data being transmitted between the parties. Because, however, of how the types are designed, without explicit handling, serializers will output nothing but an empty object.
+
+Therefore, to use the type in DTOs, you'll need to extend your serializers in use with special converters to handle these types. Converters for the `System.Text.Json.JsonSerializer` are available in this repository and are part of the associated NuGet package. See below how serialization behaves with and without them.
+
+Let's use the same person object as in the example used earlier:
+
+```c#
+using System.Text.Json;
+...
+
+var serialized = JsonSerializer.Serialize(person);
+Console.WriteLine($"Serialized: {serialized}");
+```
+
+This is what we will get as the output:
+
+```
+Serialized: {"Name":"John Doe","PhoneNumber":{},"Email":{}}
+```
+
+As you can see, the sensitive strings are just empty JSON objects `{}`.
+
+Now let's add appropriate converters to serializer options:
+
+```c#
+using System.Text.Json;
+using SensitiveString.Json;
+...
+
+var serializerOptions = new JsonSerializerOptions();
+serializerOptions.AddSensitiveStringSupport();
+
+var serialized = JsonSerializer.Serialize(person, serializerOptions);
+Console.WriteLine($"Serialized: {serialized}");
+```
+
+Now the output is complete:
+
+```
+Serialized: {"Name":"John Doe","PhoneNumber":"(800) 555\u20110123","Email":"[email protected]"}
+```
+
+The same options should be used for deserialization.
+
+## REST API
+
+To make sure your web API handles the types correctly, call this on startup:
+
+```c#
+builder.Services
+   .AddControllers()
+   .AddJsonOptions(
+        o => o.JsonSerializerOptions.AddSensitiveStringSupport()
+    );
+
+builder.Services.ConfigureHttpJsonOptions(
+    o => o.SerializerOptions.AddSensitiveStringSupport()
+);
+```
+
+
+
+## Disclaimer
+
+This is a proof of concept. If you find any issues using the package or have any thoughts on it, your comments reported as issues are more than welcome!
+

SensitiveString.sln

@@ -14,6 +14,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{21EB174C-CED
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{654EFDB6-8ECD-42CB-A3D6-F7DE361A692B}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SensitiveString.Examples", "src\SensitiveString.Examples\SensitiveString.Examples.csproj", "{BA642BF0-1C73-469C-9902-FDDD301DA73C}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -40,12 +42,17 @@ Global
 		{C0B98D42-F2BB-4D5D-A2C2-EA137D9FBF3F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{C0B98D42-F2BB-4D5D-A2C2-EA137D9FBF3F}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C0B98D42-F2BB-4D5D-A2C2-EA137D9FBF3F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BA642BF0-1C73-469C-9902-FDDD301DA73C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BA642BF0-1C73-469C-9902-FDDD301DA73C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BA642BF0-1C73-469C-9902-FDDD301DA73C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BA642BF0-1C73-469C-9902-FDDD301DA73C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{BFACD806-7D36-4ED7-8FE1-E7457299A6E3} = {21EB174C-CED8-40DB-AD4E-E3BF9D9D3EC7}
 		{39BBD349-62C1-4989-BE0B-52B3A5DFC4C8} = {21EB174C-CED8-40DB-AD4E-E3BF9D9D3EC7}
 		{EA5EA98A-75F8-422F-8858-F9857075584E} = {21EB174C-CED8-40DB-AD4E-E3BF9D9D3EC7}
 		{C3B8ED7F-E680-4364-B9AE-C12019E782E3} = {21EB174C-CED8-40DB-AD4E-E3BF9D9D3EC7}
 		{C0B98D42-F2BB-4D5D-A2C2-EA137D9FBF3F} = {654EFDB6-8ECD-42CB-A3D6-F7DE361A692B}
+		{BA642BF0-1C73-469C-9902-FDDD301DA73C} = {21EB174C-CED8-40DB-AD4E-E3BF9D9D3EC7}
 	EndGlobalSection
-EndGlobal
+EndGlobal

src/SensitiveString.Examples/PersonDto.cs

@@ -0,0 +1,3 @@
+namespace SensitiveString.Examples;
+
+internal record PersonDto(string Name, SensitiveString PhoneNumber, SensitiveEmail Email);

src/SensitiveString.Examples/Program.cs

@@ -0,0 +1,24 @@
+using System.Text.Json;
+using SensitiveString;
+using SensitiveString.Examples;
+using SensitiveString.Json;
+
+var person = new PersonDto(
+    "John Doe",
+    "(800) 555‑0123".AsSensitive(),
+    "[email protected]".AsSensitiveEmail()
+);
+
+
+// --- stringification ---
+Console.WriteLine($"Person info: {person}");
+Console.WriteLine($"Phone number: {person.PhoneNumber.Reveal()}");
+Console.WriteLine($"Email: {person.Email.Reveal()}");
+
+
+// --- JSON serialization ---
+var serializerOptions = new JsonSerializerOptions();
+serializerOptions.AddSensitiveStringSupport();
+
+var serialized = JsonSerializer.Serialize(person, serializerOptions);
+Console.WriteLine($"Serialized: {serialized}");

src/SensitiveString.Examples/SensitiveString.Examples.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net8.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\SensitiveString\SensitiveString.csproj" />
+    </ItemGroup>
+
+</Project>

src/SensitiveString/Json/JsonSerializerOptionsExtensions.cs

@@ -4,6 +4,12 @@ namespace SensitiveString.Json;
 
 public static class JsonSerializerOptionsExtensions
 {
+    /// <summary>
+    ///     Adds <see cref="SensitiveString" /> and <see cref="SensitiveEmail" /> to the serializer options.
+    /// </summary>
+    /// <param name="options">
+    ///     The serializer options to add sensitive string support to.
+    /// </param>
     public static void AddSensitiveStringSupport(this JsonSerializerOptions options)
     {
         options.Converters.Add(new SensitiveStringJsonConverter());

src/SensitiveString/SensitiveString.csproj

@@ -1 +1,72 @@
-<Project Sdk="Microsoft.NET.Sdk" />
+<Project Sdk="Microsoft.NET.Sdk">
+    <!-- https://www.meziantou.net/creating-reproducible-build-in-dotnet.htm -->
+
+    <PropertyGroup>
+        <TargetFramework>net8.0</TargetFramework>
+        <Configurations>Debug;Release;Publish</Configurations>
+        <Platforms>AnyCPU</Platforms>
+
+        <!-- <ApplicationIcon>..\..\assets\icon.ico</ApplicationIcon> -->
+        <GenerateAssemblyInfo>true</GenerateAssemblyInfo>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+
+        <IncludeSymbols>true</IncludeSymbols>
+        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+
+        <!-- to include generated files in the NuGet package -->
+        <EmbedUntrackedSources>true</EmbedUntrackedSources>
+
+        <Deterministic>true</Deterministic>
+
+        <Version>0.1.0</Version>
+        <IncludeSourceRevisionInInformationalVersion>true</IncludeSourceRevisionInInformationalVersion>
+
+        <PackageId>SensitiveString</PackageId>
+        <Title>SensitiveString</Title>
+        <Product>SensitiveString</Product>
+        <Description>Introducing SensitiveString, your shield against inadvertent exposure of sensitive information in application logs and beyond. This lightweight NuGet package wraps strings in a protective layer, ensuring that sensitive data remains secure and inaccessible without explicit handling. Safeguard your users' privacy and your application's integrity effortlessly with SensitiveString.</Description>
+        <Authors>Mariusz Schimke</Authors>
+        <Copyright>Copyright © 2024 Mariusz Schimke</Copyright>
+        <PackageTags>sensitive strings privacy</PackageTags>
+
+        <PackageProjectUrl>https://github.com/$(Repository)</PackageProjectUrl>
+        <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
+        <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+        <!-- <PackageIcon>icon.png</PackageIcon> -->
+        <EnablePackageValidation>true</EnablePackageValidation>
+
+        <PublishRepositoryUrl>true</PublishRepositoryUrl>
+        <RepositoryType>git</RepositoryType>
+        <RepositoryUrl>https://github.com/$(Repository).git</RepositoryUrl>
+        <RepositoryBranch>$(Branch)</RepositoryBranch>
+        <RepositoryCommit>$(Commit)</RepositoryCommit>
+
+        <PackageReleaseNotes>This initial package release is presented as a proof of concept. All comments and suggestions are warmly welcomed and encouraged to be reported as issues on GitHub. Your input is highly valued to help refine and improve this offering.
+
+            See also https://github.com/$(Repository)/releases</PackageReleaseNotes>
+    </PropertyGroup>
+
+    <PropertyGroup Condition="'$(Configuration)' == 'Publish'">
+        <SignAssembly>true</SignAssembly>
+        <AssemblyOriginatorKeyFile>SensitiveString.snk</AssemblyOriginatorKeyFile>
+        <Optimize>true</Optimize>
+    </PropertyGroup>
+
+    <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
+        <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All" />
+        <PackageReference Include="SauceControl.InheritDoc">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+
+    <!-- <ItemGroup>
+        <None Include="../../assets/icon.png" Pack="true" Visible="false" PackagePath="/" />
+    </ItemGroup> -->
+
+</Project>