Files
CodingSandbox/winforms_security_sandbox.md
2026-05-31 15:54:46 +03:00

291 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 📄 .NET 4.8.1 WinForms Authentication & Security Sandbox Manual
Welcome to the technical documentation of the C# WinForms Authentication & Security Sandbox. This manual is organized into two complete sections: **Section 1 in English** and **Bölüm 2 in Turkish**.
---
# SECTION 1: English (Technical Manual)
A premium, modern desktop authentication and user management sandbox designed for C# WinForms targeting **.NET Framework 4.8.1**.
## 🏗 Architecture & Design
The application utilizes a clean Separation of Concerns (SoC) model with shared service layers and event-driven updates.
```mermaid
graph TD
classDef main fill:#1E293B,stroke:#0EA5E9,stroke-width:2px,color:#fff;
classDef service fill:#0F172A,stroke:#6366F1,stroke-width:2px,color:#fff;
classDef model fill:#1E293B,stroke:#10B981,stroke-width:2px,color:#fff;
MainForm[MainForm<br/>Dashboard]:::main
LoginDialog[LoginDialog<br/>Sign In]:::main
UserSettings[UserSettings<br/>Directory Manager]:::main
SessionManager[SessionManager<br/>State & Events]:::service
User[User Model]:::model
MainForm -->|Subscribes to Events| SessionManager
MainForm -->|Opens dialog| LoginDialog
MainForm -->|Opens dialog| UserSettings
LoginDialog -->|Authenticates| SessionManager
UserSettings -->|Modifies directories| SessionManager
SessionManager -->|Manages| User
```
---
## 📂 Project Directory Structure
Here are the key files created for this project in [UserPermissionTest_CS_WinForms](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms):
* 📄 **[UserPermissionTest_CS_WinForms.csproj](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserPermissionTest_CS_WinForms.csproj)**: SDK-style project file configured for `net481` with Windows Forms enabled and `Newtonsoft.Json` package installed.
* 📄 **[Program.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/Program.cs)**: Main execution entry point.
* 📄 **[User.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/User.cs)**: Object model for users holding Username, Full Name, Password (hashed), and Permissions list (ID-based, List<int>).
* 📄 **[Permission.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/Permission.cs)**: Object model for system permissions holding Id (int) and Name (string).
* 📄 **[SessionManager.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/SessionManager.cs)**: Dynamic state and session service utilizing cross-form event notifications (`SessionStateChanged`, `UsersUpdated`).
* 📄 **[PasswordHasher.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PasswordHasher.cs)**: Cryptographic utility providing one-way SHA-256 password hashing and validation.
* 🖥 **MainForm**:
* [MainForm.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/MainForm.cs): Event listener updates for active sessions.
* [MainForm.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/MainForm.Designer.cs): Beautiful dashboard designer controls.
* 🖥 **LoginDialog**:
* [LoginDialog.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/LoginDialog.cs): Modal sign-in form verification logic with password visibility toggle.
* [LoginDialog.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/LoginDialog.Designer.cs): Compact slate-themed form controls.
* 🖥 **UserSettings**:
* [UserSettings.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserSettings.cs): Directory editor, user details modifier, and dynamic system permissions register. Supports secure password placeholders and toggles.
* [UserSettings.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserSettings.Designer.cs): Side-by-side catalog and profile fields.
---
## 🗄️ Repository Pattern & PostgreSQL Database Integration
To address enterprise-level data persistence, the data layer has been decoupled using the **Repository Pattern** and is **fully integrated with PostgreSQL** using the `Npgsql` database driver:
```mermaid
graph LR
SessionManager -->|Uses| IUserRepository
IUserRepository <|.. JsonUserRepository
IUserRepository <|.. PostgreSqlUserRepository
style IUserRepository fill:#1E293B,stroke:#F59E0B,stroke-width:2px,color:#fff
style JsonUserRepository fill:#1E293B,stroke:#10B981,stroke-width:2px,stroke-dasharray: 5 5
style PostgreSqlUserRepository fill:#1E293B,stroke:#0EA5E9,stroke-width:2px
```
### Decoupled Implementations:
* **[IUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/IUserRepository.cs)**: Contract layer. Declares `LoadUsers`, `SaveUsers`, `LoadPermissions`, and `SavePermissions`.
* **[PostgreSqlUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PostgreSqlUserRepository.cs)**: **Active Production Provider**. Connects to a local PostgreSQL instance, handles automatic schema initialization (tables `users`, `user_permissions`, `available_permissions`), and uses robust atomic transactions for synchronization.
* **[JsonUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/JsonUserRepository.cs)**: Alternative file-based (JSON) storage provider using `Newtonsoft.Json`. Writes/reads database parameters to local files `users.json` / `permissions.json` inside output build directories.
### 🐘 Active PostgreSQL Configuration:
The database connection is managed directly via Dependency Injection in **[SessionManager.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/SessionManager.cs)**:
```csharp
private static readonly IUserRepository UserRepository = new PostgreSqlUserRepository("Host=127.0.0.1;Port=5432;Database=postgres;Username=postgres;Password=postgres");
```
* **Seamless Interchangeability**: Switching back to JSON file storage is as simple as commenting out the PostgreSQL line and uncommenting the JSON class. None of the Windows Forms (`MainForm`, `LoginDialog`, `UserSettings`) require any code edits.
---
## 🔒 Role-Based Access Control (RBAC)
The application enforces fine-grained authorization constraints on dashboard actions based on active session permissions:
* **Locked State (Not Logged In)**:
* The `Manage Users` button is completely disabled and marked as `🔒 Manage Users`.
* **Unauthorized State (Logged In without privilege)**:
* If a user logs in (e.g., `user`) but does not have the **`Manage Users`** or **`Full Control`** permission:
* The directory button is locked and updated to `🔒 Manage Users (Locked)`.
* Client-side defensive checks verify permissions upon any attempt to click the control, displaying a security alert if breached.
* **Authorized State (Logged In with privilege)**:
* If a user logs in (e.g., `admin`) and has the **`Manage Users`** or **`Full Control`** permission:
* The directory button becomes fully active and updates to `👥 Manage Users`.
---
## 🔐 Cryptographic Security & Password UX
The application implements enterprise-level password security and high-fidelity visibility controls:
* **SHA-256 One-Way Hashing**:
* Passwords are never stored or processed in plain text. **[PasswordHasher.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PasswordHasher.cs)** computes a secure SHA-256 hash using `System.Security.Cryptography` for database-compatible security.
* **On-the-Fly Hashing Migration**:
* The file parser in **`JsonUserRepository`** dynamically intercepts old plain-text database profiles on startup. If a legacy plain-text password is encountered, it hashes it instantly and saves the migrated database back to disk transparently.
* **Secure Administrator Directory Workflows**:
* When loading user profiles in `UserSettings`, the password is never sent to the UI. Instead, a protective bullet mask `●●●●●●●●` is shown.
* If the administrator edits other details but leaves the password field containing the mask `●●●●●●●●`, the system detects this and keeps the current hashed password completely intact.
* If the administrator writes a new string, it hashes and overrides it.
* **Interactive Password Toggles (Show/Hide)**:
* An elegant, borderless eye button (`btnTogglePassword` with `👁`/`🙈` states) is added adjacent to password boxes in `LoginDialog` and `UserSettings` to dynamically toggle characters between masked bullets `'•'` and plain text.
---
## 🎨 Visual Design Choices
* **Harmonious Palettes**:
* Header Panels: Slate Navy (`#1E293B`)
* Buttons: Indigo Purple (`#6366F1`) and Emerald Green (`#10B981`)
* Backgrounds: White (`#FFFFFF`) with contrasting light slate fills (`#F8FAFC`, `#F1F5F9`)
* **Typography**: Clean `Segoe UI` fonts utilizing structured bold/semi-bold weight hierarchy for high legibility.
* **Badges & Lists**: Green/Red status badge for signed-in sessions and bulleted checklists displaying privileges.
---
## 🧪 Pre-Configured Test Credentials
For quick testing, the sandbox initializes with the following default users:
1. **Administrator User**
* **Username**: `admin`
* **Password**: `admin`
* **Permissions**: `View Dashboard`, `Edit Settings`, `Manage Users`, `Full Control`
2. **Standard User**
* **Username**: `user`
* **Password**: `user`
* **Permissions**: `View Dashboard`
---
---
# BÖLÜM 2: Türkçe (Teknik Kılavuz)
C# WinForms ortamında geliştirilen ve **.NET Framework 4.8.1** sürümünü hedefleyen modern, yüksek güvenlikli kullanıcı oturum ve yetki yönetim laboratuvarı belgesidir.
## 🏗 Mimari Tasarım ve Akış
Uygulama, veri katmanını kullanıcı arayüzünden tamamen ayıran temiz bir Sorumlulukların Ayrılması (SoC) mimarisi ve olay güdümlü (event-driven) güncelleme akışları kullanır.
```mermaid
graph TD
classDef main fill:#1E293B,stroke:#0EA5E9,stroke-width:2px,color:#fff;
classDef service fill:#0F172A,stroke:#6366F1,stroke-width:2px,color:#fff;
classDef model fill:#1E293B,stroke:#10B981,stroke-width:2px,color:#fff;
MainForm[MainForm<br/>Dashboard / Panel]:::main
LoginDialog[LoginDialog<br/>Giriş Ekranı]:::main
UserSettings[UserSettings<br/>Dizin ve Ayarlar]:::main
SessionManager[SessionManager<br/>Durum ve Olaylar]:::service
User[User Modeli]:::model
MainForm -->|Olaylara Abone Olur| SessionManager
MainForm -->|Açılır Dialog| LoginDialog
MainForm -->|Açılır Dialog| UserSettings
LoginDialog -->|Kimlik Doğrular| SessionManager
UserSettings -->|Dizini Düzenler| SessionManager
SessionManager -->|Yönetir| User
```
---
## 📂 Proje Dizin Yapısı
[UserPermissionTest_CS_WinForms](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms) dizininde oluşturulan temel bileşenler şunlardır:
* 📄 **[UserPermissionTest_CS_WinForms.csproj](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserPermissionTest_CS_WinForms.csproj)**: `net481` hedefleyen, Windows Forms etkinleştirilmiş ve `Newtonsoft.Json` bağımlılığı yüklenmiş SDK stili modern proje dosyası.
* 📄 **[Program.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/Program.cs)**: Uygulamanın ana giriş noktası.
* 📄 **[User.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/User.cs)**: Kullanıcı adı, Ad Soyad, Parola (Hash formatında) ve İzin listesini (ID tabanlı, List<int>) barındıran veri sınıfı.
* 📄 **[Permission.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/Permission.cs)**: Sistemdeki yetkilerin benzersiz kimliğini (Id) ve metnini (Name) barındıran veri sınıfı.
* 📄 **[SessionManager.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/SessionManager.cs)**: Formlar arasında gerçek zamanlı olay bildirimleri (`SessionStateChanged`, `UsersUpdated`) sunan merkezi statik oturum yöneticisi.
* 📄 **[PasswordHasher.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PasswordHasher.cs)**: SHA-256 tek yönlü parola kriptolama ve doğrulama yardımcı sınıfı.
* 🖥 **MainForm**:
* [MainForm.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/MainForm.cs): Aktif oturum ve yetki durumu değişikliklerini dinleyen ana panel kodları.
* [MainForm.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/MainForm.Designer.cs): Tasarım arayüzü ve yerleşim bileşenleri.
* 🖥 **LoginDialog**:
* [LoginDialog.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/LoginDialog.cs): Şifre gizleme/gösterme özellikli modern kullanıcı giriş doğrulama mantığı.
* [LoginDialog.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/LoginDialog.Designer.cs): Slate temalı giriş formu tasarım detayları.
* 🖥 **UserSettings**:
* [UserSettings.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserSettings.cs): Kullanıcı listeleme, ekleme, silme ve dinamik izin tanımlama kodları. Maskelenmiş yönetici şifre düzenleme korumasını barındırır.
* [UserSettings.Designer.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/UserSettings.Designer.cs): Yan yana katalog ve profil giriş alanları.
---
## 🗄️ Depo Tasarım Deseni (Repository Pattern) & Aktif PostgreSQL Entegrasyonu
Veri erişim katmanı tamamen **Repository Deseni** ile soyutlaştırılmış ve `Npgsql` veritabanı sürücüsü kullanılarak **aktif olarak PostgreSQL veritabanına bağlanmıştır**:
```mermaid
graph LR
SessionManager -->|Kullanır| IUserRepository
IUserRepository <|.. JsonUserRepository
IUserRepository <|.. PostgreSqlUserRepository
style IUserRepository fill:#1E293B,stroke:#F59E0B,stroke-width:2px,color:#fff
style JsonUserRepository fill:#1E293B,stroke:#10B981,stroke-width:2px,stroke-dasharray: 5 5
style PostgreSqlUserRepository fill:#1E293B,stroke:#0EA5E9,stroke-width:2px
```
### Depo Gerçekleştirmeleri:
* **[IUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/IUserRepository.cs)**: Tanım arayüzüdür. `LoadUsers`, `SaveUsers`, `LoadPermissions` ve `SavePermissions` imzalarını içerir.
* **[PostgreSqlUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PostgreSqlUserRepository.cs)**: **Aktif Veritabanı Sağlayıcısı**. PostgreSQL servisine bağlanır, sistem tablolarını (`users`, `user_permissions`, `available_permissions`) başlangıçta otomatik olarak oluşturur ve güvenli veritabanı işlemleri için `Transaction` tabanlı veri senkronizasyonu yapar.
* **[JsonUserRepository.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/JsonUserRepository.cs)**: Alternatif dosya tabanlı (JSON) veri saklayıcıdır. Çıktı dizinindeki `users.json` ve `permissions.json` dosyalarını okur/yazar.
### 🐘 Aktif PostgreSQL Yapılandırması:
Veritabanı bağlantısı **[SessionManager.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/SessionManager.cs)** dosyasında tek bir satır üzerinden Dependency Injection ile yönetilir:
```csharp
private static readonly IUserRepository UserRepository = new PostgreSqlUserRepository("Host=127.0.0.1;Port=5432;Database=postgres;Username=postgres;Password=postgres");
```
* **Kusursuz Değiştirilebilirlik**: JSON tabanlı dosya saklama modülüne geri geçmek isterseniz, PostgreSQL satırını yorum satırı yapıp JSON satırını açmanız yeterlidir. Arayüz kodlarında (`MainForm`, `LoginDialog` veya `UserSettings`) tek bir satır dahi değişmez.
---
## 🔒 Rol Tabanlı Yetki Kontrolü (RBAC)
Uygulama, giriş yapan kullanıcının aktif izinlerine göre arayüzdeki işlemleri dinamik olarak kısıtlar:
* **Oturum Yokken (Kilitli Durum)**:
* Kullanıcı yönetim butonu devre dışı kalır ve `🔒 Manage Users` metniyle gösterilir.
* **Oturum Var Ancak İzin Yetersizken (Yetkisiz Durum)**:
* Giriş yapan kullanıcının yetkileri arasında `Manage Users` veya `Full Control` **yoksa**:
* Buton pasif kalır ve durum bilgisini belli etmek için `🔒 Manage Users (Locked)` olarak güncellenir.
* Tıklama olayında arka planda yetki kontrolü tekrarlanır ve yetkisiz erişim teşebbüslerinde güvenlik uyarısı verilir.
* **Oturum Var ve Yetki Yeterliyken (Yetkili Durum)**:
* Kullanıcı yetkili ise buton anında aktifleşir, simgesi ve metni `👥 Manage Users` olarak güncellenir ve tıklanabilir hale gelir.
---
## 🔐 Kriptografik Güvenlik & Parola Deneyimi (UX)
Uygulama üst düzey parola güvenliği standartları ve gelişmiş gizleme/gösterme yetenekleriyle donatılmıştır:
* **SHA-256 Tek Yönlü Kriptolama**:
* Şifreler diskte asla düz metin olarak saklanmaz. **[PasswordHasher.cs](file:///D:/02_Programming/CSharp/CodingSandbox/UserPermissionTest_CS_WinForms/PasswordHasher.cs)** sınıfı, `System.Security.Cryptography` kütüphanesini kullanarak parolaları SHA-256 formatında şifreler.
* **Arka Planda Dinamik Otomatik Göç (Auto Hashing Migration)**:
* `JsonUserRepository` dosya okuma aşamasında eski/açık metin parola kayıtları algılarsa, bunları **arka planda otomatik olarak SHA-256 hash formatına dönüştürür** ve diske güvenli şekilde geri yazar.
* **Güvenli Yönetim Ekranı Parola İşlemleri**:
* Kullanıcı detayları yüklendiğinde gerçek şifre hash'i arayüze gönderilmez; yerine `●●●●●●●●` şeklinde güvenli bir maske gösterilir.
* Şifre alanını `●●●●●●●●` olarak bıraktığınızda sistem şifrenin değiştirilmediğini algılar ve **mevcut hash'i aynen korur**. Yeni bir şifre yazıldığında ise bunu şifreleyerek kaydeder.
* **Şifre Göster/Gizle Butonları (Eye Toggles)**:
* `LoginDialog` ve `UserSettings` şifre kutularının sağına eklenen modern kenarlıksız göz butonu (`btnTogglePassword` ile `👁`/`🙈` durumları) şifrenin maskelenmesi `'•'` ve düz metin gösterilmesi arasında dinamik geçiş sağlar.
---
## 🎨 Görsel Tasarım Tercihleri
* **Özel Uyumlu Renk Paleti**:
* Üst Bilgi Panelleri: Modern Koyu Lacivert/Siyah (`#1E293B`)
* Etkin Butonlar: İndigo Moru (`#6366F1`) ve Zümrüt Yeşili (`#10B981`)
* Form Zeminleri: Beyaz (`#FFFFFF`) ve kontrast açık gri/slate dolgular (`#F8FAFC`, `#F1F5F9`)
* **Tipografi**: Browser varsayılanları yerine temiz, okunaklılığı yüksek yarı kalın/kalın yapılandırılmış `Segoe UI` yazı tipleri kullanılmıştır.
* **Durum Bildirimleri**: Oturum durumunu gösteren Yeşil/Kırmızı dinamik rozetler ve izin listesinde zengin onay sembolleri (`✓`).
---
## 🧪 Hazır Test Kullanıcı Bilgileri
Hızlı test işlemleri için sistem başlangıçta şu hesapları barındırır:
1. **Yönetici Kullanıcı (Tüm Yetkilere Sahip)**
* **Kullanıcı Adı**: `admin`
* **Parola**: `admin`
* **Yetkileri**: `View Dashboard`, `Edit Settings`, `Manage Users`, `Full Control`
2. **Standart Kullanıcı**
* **Kullanıcı Adı**: `user`
* **Parola**: `user`
* **Yetkileri**: `View Dashboard`