SecureSharp (C#)

Offline-only, cross-platform Avalonia vault that keeps every byte of your data on-device, anchored to the OS keystore and hardened with Argon2id + AES-GCM.

Table of contents

• What makes SecureSharp different
• Security model at a glance
• Project layout
• Runtime behavior
• Data locations
• Quick start (dev)
• Build & publish
• Installers
• Testing & quality gates
• Release checklist
• Reset / data wipe
• Troubleshooting tips

What makes SecureSharp different

• Offline by design: No sync, no telemetry, no background calls. Network namespaces are blocked at build time.
• Device-bound secrets: Master key material is wrapped by the OS keystore (DPAPI/CredMan on Windows, Keychain on macOS, Secret Service on Linux) before vault encryption.
• Strong crypto defaults: Argon2id for KDF, AES-GCM for envelope encryption, integrity manifests on every vault write.
• Guided onboarding: Generates a strong recovery password, stores it as a first entry, and enforces distinct master vs. recovery passwords.
• User-safety UX: TOTP prompts guard profile changes, master rotation, exports/imports, and backups.
• Portable UI: Avalonia 11 shell with Fluent styling and compiled bindings for perf.
• Release ready: Single-file, self-contained publish targets for Windows, macOS, and Linux.

If you're new to the codebase: start with SecureSharp.UI to see the navigation/view models, then open SecureSharp.VaultCore to understand orchestration, and finally skim SecureSharp.Crypto for the cryptographic glue.

Security model at a glance

1. Master password -> Argon2id calibration (device-performance tuned) -> derived key.
2. Derived key is wrapped with the platform keystore and combined with per-vault salts.
3. Vault contents are encrypted with AES-GCM; manifests track fingerprints and integrity.
4. Build gate: build/OfflineScanner fails compilation if System.Net* appears anywhere. Hooked via Directory.Build.targets and runs before every project build.

Diagram: encryption and key flow

flowchart TD
    A[Master password] --> B[Argon2id calibration<br/>per-device tuned]
    B --> C[Derived key]
    C --> D[Wrap with OS keystore<br/>DPAPI/CredMan / Keychain / Secret Service]
    D --> E[Vault root key + salts]
    E --> F[AES-GCM encrypt/decrypt<br/>entries + manifests]
    F --> G[Integrity manifest<br/>fingerprints]
    G --> H[Offline scanner gate<br/>fails build on System.Net*]

Loading

Project layout

• src/SecureSharp.UI - Avalonia desktop shell (navigation, theming, UX, TOTP/QR support).
• src/SecureSharp.VaultCore - vault orchestration, key wrapping, backup + integrity pipelines.
• src/SecureSharp.Crypto - Argon2id KDF + AES-GCM helpers.
• src/SecureSharp.Persistence - file-based storage layout and manifest handling.
• src/SecureSharp.OSIntegration - keystore bindings (Windows DPAPI/CredMan, macOS Keychain, Linux Secret Service).
• build/OfflineScanner - MSBuild task to enforce offline posture.
• build/SecureSharp.ps1 / build/SecureSharp.sh - dev build + run helpers.
• tests/SecureSharp.Tests - integration and regression coverage for onboarding, unlock, vault entries, transfers/backups, keystore/crypto, and settings.

Diagram: component overview

flowchart TD
    subgraph UI[SecureSharp.UI<br/>Avalonia shell]
    end
    subgraph Core[SecureSharp.VaultCore<br/>Vault orchestration]
    end
    subgraph Crypto[SecureSharp.Crypto<br/>Argon2id / AES-GCM]
    end
    subgraph Persist[SecureSharp.Persistence<br/>File storage + manifests]
    end
    subgraph OSI[SecureSharp.OSIntegration<br/>OS keystores]
    end
    subgraph Tests[Tests<br/>Integration/regression]
    end
    DBT[Directory.Build.targets<br/>Offline scanner hook]

    UI --> Core
    Core --> Crypto
    Core --> Persist
    Core --> OSI
    Tests -. exercise .-> Core
    DBT -. build gate .-> UI
    DBT -. build gate .-> Core

Loading

Runtime behavior

• Offline posture: no telemetry, sync, or update checks; any System.Net* usage fails the build via OfflineScanner.
• Auto-lock: UI enforces re-authentication on inactivity (configurable inside app settings).
• TOTP-guarded operations: profile edits, exports/imports, backups, and master rotations prompt for TOTP.
• Recovery-first onboarding: generates a recovery password, saves it as the first vault entry (favorite + tagged), and requires master != recovery.
• Integrity-first writes: each save updates a manifest fingerprint; mismatches surface before decrypt attempts.

Data locations

• Windows: %AppData%\\SecureSharp\\vault\\ (vault data) and %AppData%\\SecureSharp\\walkthrough.seen (onboarding marker).
• macOS/Linux: $XDG_DATA_HOME/SecureSharp/vault/ (or ~/.local/share/SecureSharp/vault/ fallback).
• Publish outputs: src/SecureSharp.UI/bin/Release/net10.0/<rid>/publish/.

Quick start (dev)

Follow these three steps to get the UI running locally:

1. Install .NET 10 SDK
   • Windows: winget install --id Microsoft.DotNet.SDK.10
   • macOS: /bin/bash -c "$(curl -fsSL https://aka.ms/install-dotnet.sh)" -- --channel 10.0 --install-dir /usr/local/share/dotnet then symlink dotnet into PATH.
   • Ubuntu/Debian: sudo wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O /tmp/packages-microsoft-prod.deb && sudo dpkg -i /tmp/packages-microsoft-prod.deb && sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0
   • Fedora/RHEL/CentOS: sudo rpm -Uvh https://packages.microsoft.com/config/centos/8/packages-microsoft-prod.rpm && sudo dnf install -y dotnet-sdk-10.0
   • Verify: dotnet --info
2. Clone and enter the repo: git clone <repo> && cd SecureSharp-CSharp
3. Run the dev script (build + launch UI):
   • Windows: powershell -ExecutionPolicy Bypass -File .\build\SecureSharp.ps1
   • macOS/Linux: bash ./build/SecureSharp.sh (first run: chmod +x ./build/SecureSharp.sh)
   • Both scripts will verify/install .NET 10 and dotnet-format automatically (Homebrew/apt/winget where available; otherwise they fall back to the official dotnet-install script).

Build & publish

• Windows x64: dotnet publish src/SecureSharp.UI/SecureSharp.UI.csproj -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true /p:UseAppHost=true
• macOS x64: dotnet publish src/SecureSharp.UI/SecureSharp.UI.csproj -c Release -r osx-x64 --self-contained true /p:PublishSingleFile=true /p:UseAppHost=true
• Linux x64: dotnet publish src/SecureSharp.UI/SecureSharp.UI.csproj -c Release -r linux-x64 --self-contained true /p:PublishSingleFile=true /p:UseAppHost=true
• Outputs land in src/SecureSharp.UI/bin/Release/net10.0/<rid>/publish.
• Supported RIDs (current scripts): win-x64, osx-x64, linux-x64. Add -r <rid> variants (e.g., linux-arm64) as needed.
• Common toggles: drop --self-contained true for framework-dependent publish; add /p:PublishReadyToRun=true for faster cold start; leave trimming off for now (Avalonia + reflection-heavy UI).
• Notes: warnings are treated as errors (Directory.Build.props), nullable + latest language features are on by default.

Installers

• Windows (.exe/.msi): Point WiX/MSIX/Inno/Advanced Installer at .../win-x64/publish/ with entry SecureSharp.UI.exe. Example (Inno Setup):

  [Setup]
  AppName=SecureSharp
  AppVersion=1.0.0
  DefaultDirName={pf}\SecureSharp
  OutputBaseFilename=SecureSharp-Setup
  [Files]
  Source: "src\SecureSharp.UI\bin\Release\net10.0\win-x64\publish\*"; DestDir: "{app}"; Flags: recursesubdirs
  [Icons]
  Name: "{group}\SecureSharp"; Filename: "{app}\SecureSharp.UI.exe"

• macOS (.dmg):

  mkdir -p SecureSharp.app/Contents/MacOS
  cp src/SecureSharp.UI/bin/Release/net10.0/osx-x64/publish/SecureSharp.UI SecureSharp.app/Contents/MacOS/
  hdiutil create -volname SecureSharp -srcfolder SecureSharp.app -ov -format UDZO SecureSharp.dmg

  Sign + notarize with your Developer ID.

• Linux (.AppImage/.deb/.rpm): Wrap .../linux-x64/publish with your preferred packager (e.g., appimagetool or fpm). Entry point: ./SecureSharp.UI.

Testing & quality gates

• Unit/integration suite: dotnet test tests/SecureSharp.Tests/SecureSharp.Tests.csproj
  • Coverage areas: onboarding + unlock, vault CRUD, transfers/backups, crypto/keystore bindings, settings/regression checks.
• Offline enforcement: runs automatically before every build via Directory.Build.targets; build fails if System.Net* is referenced.
• Analyzer posture: TreatWarningsAsErrors=true, nullable enabled, AnalysisLevel=latest.
• Optional local checks: dotnet format (code style) and dotnet build /p:RunAnalyzers=true for quick static analysis.

Release checklist

• Bump version and changelog (if applicable); verify app icon and signing assets are current.
• Clean + rebuild: dotnet clean then publish for each target RID.
• Run tests: dotnet test tests/SecureSharp.Tests/SecureSharp.Tests.csproj.
• Verify offline gate: insert a dummy using System.Net; locally to confirm the build fails, then revert.
• Smoke test artifacts: launch each published binary, confirm onboarding, unlock, and backup/import paths offline.
• Package/sign: wrap outputs per platform (Inno/WiX/MSIX, dmg with notarization, AppImage/deb/rpm) and sign where required.

Reset / data wipe

All vault data is stored under %AppData%\SecureSharp. Close the app, delete that folder (including vault/* and walkthrough.seen), then re-run onboarding to start fresh.

Troubleshooting tips

• Build fails with offline scanner: remove any System.Net, System.Net.Http, or System.Net.Sockets references/imports.
• First run on Unix: ensure ./build/SecureSharp.sh is executable (chmod +x).
• Publish size: single-file self-contained builds embed the runtime; disable --self-contained if you prefer framework-dependent output.
• Keystore errors on Linux: confirm a Secret Service provider (e.g., gnome-keyring) is running for the current session.