Version: 1.0
Date: March 28, 2026
Status: Draft
Reference: SRS v1.0, HLD v1.0, API v1.0

1. Introduction
2. Security Objectives
3. Authentication and Authorization
4. Data Protection
5. API Security
6. Input Validation and Injection Prevention
7. Session Management
8. AI Component Security
9. Infrastructure Security
10. Monitoring and Incident Response
11. Security Checklist
12. Revision History

This Security Design document defines the security controls, policies, and implementation guidelines for FinTrack AI. It addresses authentication, authorization, data protection, communication security, input handling, infrastructure hardening, and incident response. It is intended to ensure that user financial data is protected from unauthorized access, disclosure, tampering, and loss.

This document covers all layers of the FinTrack AI system: frontend, backend API, database, AI integration, and deployment infrastructure. It applies to all engineers, DevOps personnel, and third-party integrations involved in the system.

Security controls are designed in alignment with the following references:

• OWASP Top 10 (2021 edition)
• OWASP API Security Top 10
• General data privacy principles applicable in India (DPDP Act 2023 awareness)
• NIST Cybersecurity Framework (informative reference)

All user passwords must satisfy the following requirements at the time of registration and on every password change:

• Minimum length: 8 characters
• Must contain at least one uppercase letter (A-Z)
• Must contain at least one lowercase letter (a-z)
• Must contain at least one digit (0-9)
• Must contain at least one special character (!@#$%^&*...)
• Must not be the same as the previous password
• Must not match common password patterns (validated against a blocklist of the 10,000 most common passwords)

Passwords are never stored in plaintext or in reversibly encrypted form. The bcrypt hashing algorithm is used with a work factor (cost) of 12. This value must be reviewed annually and increased as hardware performance improves.

The stored hash format is: $2b$12$<salt><hash> (bcrypt output).

The password_hash column in the users table stores this value exclusively. No intermediate values, temporary hashes, or plaintext representations are written to logs, error messages, or any other storage medium.

Access tokens are issued on successful login using the RS256 or HS256 algorithm with a secret of at least 256 bits.

Access tokens must never be logged, included in URL parameters, or stored in browser storage accessible to JavaScript.

Refresh tokens allow obtaining new access tokens without re-authentication.

Rotation prevents refresh token reuse attacks. If a previously used refresh token is presented, the server invalidates all refresh tokens for that user (token theft indicator).

FinTrack AI uses resource-level ownership authorization. There are no roles beyond authenticated user and system administrator.

Rules:

• Every API request to a protected endpoint must include a valid access token.
• The authenticated userId is extracted from the token and used as a filter on all database queries. A user can only read or modify their own resources.
• System administrators access the database directly and do not have a privileged API role in v1.0.
• Category ownership is checked before any transaction is associated with a category.
• Attempts to access another user's resource return HTTP 404 (not 403) to prevent resource enumeration.

To protect against brute-force login attacks:

• After 5 consecutive failed login attempts within 10 minutes for a given email, the account is locked for 15 minutes.
• The lockout duration doubles with each subsequent lockout for the same account within a 24-hour window.
• A notification email is sent to the account owner when a lockout occurs.
• Lockout state is tracked in Redis: key = "lockout:{email}", value = { attempts, lockedUntil }.

• All client-to-server communication uses TLS 1.2 or higher. TLS 1.0 and 1.1 are explicitly disabled on the Nginx configuration.
• HTTP requests on port 80 are redirected to HTTPS via a 301 response.
• Recommended cipher suites prioritize forward secrecy (ECDHE-based key exchange).
• TLS certificates are obtained via Let's Encrypt and renewed automatically before expiry.

• The PostgreSQL database volume is encrypted at the infrastructure level using the cloud provider's disk encryption (AES-256).
• Backups stored in cloud object storage are encrypted using server-side encryption with provider-managed keys.
• No application-level column encryption is applied in v1.0. Sensitive columns (password_hash, token_hash) are protected through hashing rather than encryption.

The following data is classified as sensitive and subject to strict handling rules:

API responses include only the fields required by the client. Internal fields such as password_hash, verification_token, and token_hash columns are never included in API responses. The repository layer explicitly selects only required columns for each query.

The Nginx reverse proxy enforces HTTPS. The backend application server listens only on the internal network and is not directly accessible from the internet.

Cross-Origin Resource Sharing is configured on the backend to allow requests only from the registered frontend domain:

Access-Control-Allow-Origin: https://fintrack.ai
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true

Wildcard origins (*) are strictly prohibited.

The following HTTP security headers are set on all responses by the Nginx layer:

Rate limiting is enforced at the API Gateway layer using express-rate-limit backed by Redis. Limits are defined per endpoint group in the API Specification document. On limit breach, HTTP 429 is returned with a Retry-After header.

Since the application uses stateless JWT authentication passed in the Authorization header (not cookies), traditional CSRF attacks are not applicable to API endpoints.

If cookies are used for refresh token storage, the httpOnly and SameSite=Strict attributes are set to prevent JavaScript access and cross-site submission.

All input is validated at two layers:

Layer 1 - Controller (Request Entry): Jakarta Bean Validation (Hibernate Validator) annotations (e.g., @NotBlank, @Email, @Positive) on DTOs validate request bodies before business logic executes. Invalid requests are rejected with HTTP 422 by the global exception handler.

Layer 2 - Persistence (Database Entry): Spring Data JPA (Hibernate) uses prepared statements and parameterized queries exclusively. No raw string concatenation is used to build SQL queries.

Spring Data JPA generates parameterized SQL for all database interactions. Prohibited pattern:

// NEVER do this
String query = "SELECT * FROM transactions WHERE user_id = '" + userId + "'";

Required pattern:

// Always use parameterized queries or derived query methods
@Query("SELECT t FROM Transaction t WHERE t.user.id = :userId")
List<Transaction> findByUserId(@Param("userId") Long userId);

• The frontend uses React, which escapes all rendered values by default. Direct DOM manipulation using innerHTML is prohibited.
• The backend does not render HTML. All API responses are JSON. The Content-Type header is always application/json.
• The Content-Security-Policy header restricts the execution of inline scripts.
• User-supplied text (descriptions, names) is stored and returned as-is. Sanitization for display is the responsibility of the React rendering layer (handled automatically by JSX).

API endpoints accept only explicitly whitelisted fields. Zod schemas define the exact set of accepted fields per endpoint. Any additional fields in the request body are stripped before processing. The userId is always sourced from the verified JWT token, never from the request body.

FinTrack AI v1.0 does not support file uploads. The CSV export feature streams data to the client; no files are uploaded by users.

• The access token is stored in JavaScript memory (React state / Redux store) only. It is not written to localStorage, sessionStorage, or cookies.
• The refresh token is stored in an httpOnly, Secure, SameSite=Strict cookie. This prevents JavaScript access while allowing automatic inclusion in refresh token requests.

• Access tokens expire after 1 hour.
• Refresh tokens expire after 7 days.
• If a user is inactive and the access token expires, the client silently attempts a refresh using the refresh token cookie. If the refresh token is also expired or revoked, the user is redirected to the login screen.

On logout:

1. The backend deletes the refresh token record from the database.
2. The httpOnly cookie is cleared by setting it with an expired date.
3. The frontend clears the access token from memory and Redux state.
4. The user is redirected to the login screen.

In v1.0, multiple simultaneous sessions are permitted (e.g., mobile and desktop). Each session has its own refresh token stored in the database. Logout from one session does not invalidate others. A "logout all devices" feature is planned for v1.1 and will be implemented by deleting all refresh tokens for the user.

FinTrack AI uses Ollama for local AI processing. This provides a significant security and privacy advantage over cloud-based LLMs:

• Data Sovereignty: Financial data never leaves the controlled infrastructure. No data is sent to third-party AI providers (e.g., Anthropic, OpenAI).
• Network Isolation: The Ollama service runs in a container accessible only to the backend on the internal Docker network. It is not exposed to the internet.
• Privacy by Design: User transaction descriptions used for NLP parsing and history used for insights remain within the application's secure boundary.

• Only official, verified model weights (e.g., Llama3, Mistral) from the Ollama library are used.
• Model versions are pinned in the deployment configuration to ensure consistent and predictable behavior.

AI responses are treated as untrusted input and validated before use:

• NLP Parsing: The JSON response from Ollama is parsed and validated against the DraftTransactionDTO schema. Invalid or malicious JSON is rejected.
• Insights: AI-generated text is rendered as plain text or safe Markdown on the frontend. No executable code or scripts are ever extracted from AI responses.
• Prompt Injection: User input is treated as data within a structured prompt template. System instructions are separated from user data to prevent prompt injection attacks.

All secrets and configuration values are stored as environment variables. They are never hardcoded in source code or committed to version control.

Required environment variables:

Environment files (.env) are listed in .gitignore and are never committed.

The production server follows these baseline hardening steps:

• SSH access is restricted to key-based authentication only. Password-based SSH login is disabled.
• The root user login is disabled over SSH.
• A non-root user with sudo access is used for application deployment.
• Unnecessary services and ports are disabled. Only ports 80, 443, and 22 (SSH) are exposed externally.
• Unattended security updates are enabled on Ubuntu.
• A firewall (ufw) is configured to allow only the above ports.

• Docker containers run as non-root users.
• Official base images from Docker Hub are used with pinned versions.
• The Docker socket is not exposed to application containers.
• No secrets are baked into Docker images. Secrets are injected at runtime via environment variables.

• PostgreSQL is not exposed externally. It listens only on the internal Docker network.
• The application connects using a dedicated database user with SELECT, INSERT, UPDATE, DELETE permissions on application tables only. It does not have CREATE TABLE, DROP, or SUPERUSER privileges.
• The PostgreSQL superuser password is set and documented in the internal secrets vault.

• Backend: Maven or Gradle pins all dependencies. Maven Enforcer plugin is used to ensure no dependency version conflicts.
• Frontend: npm or yarn pins all packages in package-lock.json or yarn.lock.
• Scanning: Snyk or GitHub Dependabot scans for vulnerabilities in both Java and JavaScript dependencies. High/critical issues block the build pipeline.

The following events are logged with timestamp, userId (if authenticated), IP address, and user agent:

• Successful login
• Failed login attempt
• Account lockout triggered
• Password change
• Password reset requested and completed
• Email verification
• Transaction creation and deletion
• Budget threshold alerts triggered
• AI API errors and timeouts

Logs do not contain passwords, tokens, or raw financial amounts.

The following conditions trigger an automated alert to the system administrator:

• More than 100 failed login attempts from a single IP within 5 minutes
• More than 10 accounts locked within 1 hour
• AI API key usage exceeds a configured daily token limit threshold
• Database connection pool exhaustion
• HTTP 500 error rate exceeds 1% of requests in a 5-minute window

Step 1 - Detection: Alert triggered via monitoring system or user report.

Step 2 - Containment: Depending on severity, actions include blocking the offending IP, revoking all active tokens for affected users, or taking the service offline.

Step 3 - Investigation: Review structured logs to determine the scope and vector of the incident.

Step 4 - Remediation: Apply patches, rotate compromised secrets, and restore from backup if data integrity is affected.

Step 5 - Notification: Notify affected users within 72 hours of a confirmed data breach, in accordance with applicable data protection regulations.

Step 6 - Post-Incident Review: Document the incident, root cause, and corrective actions taken.

The following checklist must be verified before every production deployment.

Authentication

• Passwords validated against strength policy on registration and change
• bcrypt work factor is 12 or higher
• JWT secrets are at least 256 bits and stored as environment variables
• Refresh tokens are hashed before DB storage
• Account lockout is active and tested
• Email verification is required before first login

API

• All protected routes require valid JWT
• CORS is restricted to the frontend domain
• All security headers are present and correct
• Rate limiting is active on all endpoints
• Input validation (Zod) is applied on all routes

Data

• No sensitive fields (password_hash, tokens) returned in API responses
• All DB queries use parameterized statements
• Aggregated data only is sent to the AI API

Infrastructure

• TLS 1.2+ is enforced; older versions disabled
• HTTP redirects to HTTPS
• .env files are in .gitignore
• No secrets in Docker images
• DB is not externally accessible
• npm audit passes with no high/critical issues

Monitoring

• Security events are logged
• Alerting thresholds are configured