This document describes the security measures, architecture, and best practices implemented in OpenCashFlow.
It is intended as a reference for contributors, auditors, and operators.

┌─────────────────────────────────────────────────────┐
│                  Internet / Users                   │
└──────────────────┬──────────────────────────────────┘
                   │
          ┌────────▼────────┐
          │   HTTPS / TLS   │ ← Encryption in transit
          └────────┬────────┘
                   │
     ┌─────────────▼───────────────┐
     │   Rate Limiting             │ ← DDoS protection
     └─────────────┬───────────────┘
                   │
     ┌─────────────▼───────────────┐
     │   CORS Policy               │ ← Cross‑origin control
     └─────────────┬───────────────┘
                   │
     ┌─────────────▼───────────────┐
     │   JWT Authentication        │ ← User authentication
     └─────────────┬───────────────┘
                   │
     ┌─────────────▼───────────────┐
     │   Role‑Based Authorization  │ ← Permission enforcement
     └─────────────┬───────────────┘
                   │
     ┌─────────────▼───────────────┐
     │   Business Logic            │
     └─────────────┬───────────────┘
                   │
     ┌─────────────▼───────────────┐
     │   PostgreSQL Database       │ ← Encryption at rest
     └─────────────────────────────┘

Implementation: ASP.NET Core Identity + JWT

Example configuration (OpenCashFlow.API/Program.cs):

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = jwtSettings.Issuer,
            ValidAudience = jwtSettings.Audience,
            IssuerSigningKey = new SymmetricSecurityKey(...)
        };
    });

Token Storage

• Stored in HTTP‑only cookies
• Not accessible from JavaScript (XSS mitigation)
• Secure flag enabled in production
• SameSite policy configured

Token Lifecycle

• Lifetime: configurable (default 24h)
• Refresh: manual (re‑login required)
• Revocation: client‑side logout (server‑side blacklist not implemented)

Model

• AspNetUser – User
• AspNetRole – Role (InstanceAdmin, CompanyAdmin, Employee)
• AspNetUserRole – User ↔ Role mapping
• AspNetUserPermission – Explicit permissions
• AspNetUserDeniedPermission – Explicitly denied permissions

Default Roles

• InstanceAdmin – Self-hosted instance administration and global maintenance.
• CompanyAdmin – Company/workspace administration, payments, staff, reports and configuration.
• Employee – Daily operational access inside a company/workspace.

Usage

[Authorize(Policy = "InstanceAdmin")]
public IActionResult InstanceAdminOnly() { }

[Authorize(Roles = "CompanyAdmin")]
public IActionResult CompanyAdminOnly() { }

Implementation

• Each user belongs to a Company via Company_Staff
• TenantID stored in JWT claims
• All queries are automatically filtered by tenant

Service Pattern

var tenantId = _authenticationService.GetTenantID();
var payments = await _repository.GetPaymentsAsync(tenantId, filters);

Isolation Rules

• No cross‑company queries
• Admin users may bypass isolation via explicit flags

Purpose

• SaaS-era Billing/Stripe access control is not part of the community core runtime.

Removed From Core Runtime

• Subscription authorization middleware
• Billing API endpoints
• Stripe webhook endpoints
• Stripe client registration
• Pricing, upgrade and customer portal UI

Legacy Schema

• Some historical plan, subscription and Stripe columns/tables may remain until a migration-backed cleanup.
• They must not be used to authorize access to dashboard, company, payments or cash.
• Any future external Billing module needs a separate threat model and security review.

Before a public release, run:

dotnet restore OpenCashFlow.sln
dotnet list OpenCashFlow.sln package --vulnerable --include-transitive
dotnet build OpenCashFlow.sln
dotnet test OpenCashFlow.sln --no-build

Release builds must not ship with unresolved NU1902 or NU1903 advisories unless a documented exception exists.

The July 2026 dependency audit remediated:

• AutoMapper from 14.0.0 to 16.2.0.
• MailKit from 4.12.1 to 4.17.0.
• MimeKit from 4.12.0 to 4.17.0.
• Removed unused Microsoft.EntityFrameworkCore.Sqlite from the test project to eliminate the vulnerable transitive SQLitePCLRaw.lib.e_sqlite3 dependency.

SMTP remains optional. Password reset token creation must continue to work even when email delivery is not configured.

The .NET 10 migration updates the supported runtime baseline to:

• net10.0 for all core and test projects.
• Microsoft ASP.NET Core, EF Core and Extensions packages 10.0.9.
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.2.
• System.IdentityModel.Tokens.Jwt 8.19.1.
• System.Linq.Dynamic.Core 1.7.2.
• Microsoft.OpenApi 2.10.0.
• Swashbuckle.AspNetCore 10.2.3.

Swashbuckle.AspNetCore was upgraded across a major version because the .NET 10 OpenAPI graph otherwise resolved a vulnerable Microsoft.OpenApi package and was not source-compatible with the safe Microsoft.OpenApi 2.x namespace layout.

The WebApp emits security headers from OpenCashFlow.WebApp/Program.cs:

• Content-Security-Policy
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy

The CSP uses a per-request nonce for Razor-rendered <script> and <style> elements through the WebApp CSP nonce tag helper. The policy intentionally avoids unsafe-inline and unsafe-eval. External script/style sources must be explicit; broad wildcard sources are not allowed.

Shared layout scripts/styles and several small auth page scripts have been moved into static assets. Some legacy Razor views still use nonce-backed inline blocks while they are migrated page by page; runtime CDN usage is explicitly limited and tracked in Docs/architecture/frontend-csp-cleanup.md.

The ZAP Baseline workflow parses JSON reports and fails on any non-accepted Medium/High finding. CSP findings are not allowlisted.

In Transit

• HTTPS/TLS 1.2+
• HSTS enabled in production

At Rest

• Passwords: hashed via ASP.NET Identity (PBKDF2)
• Database: encryption at rest (infrastructure‑level)
• Secrets: stored in secure vaults or environment variables

Sensitive Data Rules

• ❌ Never log passwords, tokens, or API keys
• ❌ Never commit secrets to Git
• ✅ Mask sensitive values in logs
• ✅ Exclude sensitive fields from DTO serialization

Secret Rotation

• Rotate JWT_SECRET immediately after a suspected leak and force users to log in again.
• Rotate database and SMTP credentials by changing the environment variables, restarting the services and revoking the old credentials at the provider/database layer.
• Treat reset tokens, fast-login cookies and PINs as credentials. They must not be logged or copied into support tickets.

Model Validation

[Required, EmailAddress]
public string Email { get; set; }

[Range(0, 999999)]
public decimal Amount { get; set; }

SQL Injection

• Entity Framework parameterized queries
• Raw SQL only with parameters

XSS Protection

• Automatic Razor encoding
• CSP headers
• Avoid Html.Raw unless sanitized

Logged Events

• User login / logout
• Administrative actions
• Subscription changes
• Security‑related events
• External webhook processing

Retention

• Configurable (default example: 90 days)

Examples

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Permissions-Policy: geolocation=(), camera=(), microphone=()
Strict-Transport-Security: max-age=31536000; includeSubDomains

Example Limits

• Global: 100 requests/minute per user
• Authentication endpoints: stricter limits
• Company‑scoped API usage

Response

• HTTP 429 – Too Many Requests

Rules

• Explicit allow‑list of origins
• Credentials allowed
• No wildcard origins in production

Webhook Verification

• Signature validation required
• Idempotency enforced
• Duplicate event detection

Secrets Management

• Environment variables or secret vaults
• No secrets in source code

• Multi‑Factor Authentication (TOTP)
• Advanced audit log storage
• Automated security alerts
• Anomaly detection on login patterns

1. Isolate affected systems
2. Revoke compromised credentials
3. Analyze logs and scope
4. Patch vulnerabilities
5. Notify affected users if required
6. Document and review the incident

• OWASP Top 10
• ASP.NET Core Security Documentation
• GDPR / Data Protection Regulations

Last updated: 2026‑01‑04 Maintained by: OpenCashFlow contributors
Review cycle: Quarterly