Security, Privacy, and Service Protection

Relevant source files

The following files were used as context for generating this wiki page:

• services/circuitBreakerService.ts
• MAJOR_FIX_UPDATE_SUMMARY.md
• SANITY_CHECK_REPORT.md
• README.md
• GITHUB_INTEGRATION_COMPLETE.md
• 12-2-todo.md
• DEPLOYMENT_CHECKLIST.md
• Issues_by_Severity.md

BMSview incorporates several layers of security, privacy, and service protection to ensure data integrity, prevent abuse, and manage access. The application's core privacy model is "public by default," where analysis data is shared globally based on screenshot content hashes. This design choice necessitates robust server-side protections and clear user-facing privacy notices.

The protection strategy focuses on several key areas: a clear privacy model, stringent data validation to prevent processing of erroneous data, service protection mechanisms like rate limiting and circuit breakers to ensure availability, and secure access control for sensitive operations and integrations. Administrative functions are protected via Google OAuth, while specific integrations like the GitHub API employ a strict allowlist-based access model.

Sources: README.md, MAJOR_FIX_UPDATE_SUMMARY.md, GITHUB_INTEGRATION_COMPLETE.md

Privacy and Data Isolation

The application's privacy model is explicitly stated in the README.md. Analysis data is not tied to a user account but is identified by the SHA-256 hash of the uploaded screenshot. This means anyone uploading an identical image will see the same analysis results. Users are warned not to upload screenshots containing sensitive information.

While the primary analysis flow is unauthenticated, administrative access to the dashboard requires Google OAuth. There is an ongoing effort to improve multi-tenancy and data isolation. A critical security flaw was partially addressed where database updates lacked user/tenant scoping, potentially allowing one user to overwrite another's data. The fix involves conditionally adding a userId to database queries when it's available, ensuring that data is properly scoped in multi-tenant scenarios while maintaining backward compatibility.

Sources: README.md, 12-2-todo.md

Data Integrity and Validation

A critical layer of security is the data integrity validation that runs after AI-based OCR extraction and before data is stored in the database. This prevents corrupted or nonsensical data from populating the system. The validation is non-blocking; if it fails, the analysis is still saved but flagged with needsReview: true and a list of warnings.

Sources: SANITY_CHECK_REPORT.md

Validation Pipeline

The following diagram shows the flow of data through the validation process.

Sources: SANITY_CHECK_REPORT.md

Validation Checks

The system performs a comprehensive set of checks across multiple categories.

Category	Check Description	Criticality
State of Charge (SOC)	SOC must be between 0 and 100.	Critical
Cell Voltage Range	Each cell voltage must be between 2.0V and 4.5V.	Critical
Physics Check	The sum of cell voltages must be within a tolerance (0.5V) of the overall voltage.	Critical if > 1.0V diff
Temperature Range	Battery temperature must be between 0°C and 100°C.	Critical
MOS Logical Consistency	Checks if MOS gates (Charge/Discharge) are open when current is flowing.	Not Critical (Warning)
Power Calculation	Power must be within 10% tolerance of Voltage * Current.	Critical if > 50% diff
Capacity Consistency	RemainingCapacity cannot exceed FullCapacity by more than 5%.	Critical
SOC Calculation	The reported SOC must be within 10% of the calculated (Remaining / Full) * 100.	Critical if >= 25% diff
Cell Voltage Statistics	Verifies that reported highest, lowest, average, and difference match calculated values.	Not Critical (Warning)
Edge Cases	Handles null, undefined, empty arrays, and division by zero.	N/A

Sources: SANITY_CHECK_REPORT.md

Additionally, the /systems endpoint uses Zod schemas to validate POST and PUT requests, ensuring that fields like chemistry, voltage, and capacity fall within valid ranges before being stored.

Sources: MAJOR_FIX_UPDATE_SUMMARY.md

Service Protection Mechanisms

To ensure availability and prevent abuse, the backend functions are protected by several mechanisms.

CORS (Cross-Origin Resource Sharing)

To prevent unauthorized domains from making requests to the API, a centralized CORS utility was implemented. This replaces a permissive * configuration with a strict, environment-based allowlist.

Key Features:

• Environment-based Allowlist: The ALLOWED_ORIGINS environment variable dictates which origins are permitted.
• Automatic URLs: Automatically includes Netlify deployment URLs and localhost for development.
• Strict Production Mode: In production, the origin must be in the allowlist.

This flow is applied to sensitive endpoints like analyze.cjs and generate-insights-with-tools.cjs.

Sources: MAJOR_FIX_UPDATE_SUMMARY.md, Issues_by_Severity.md

Rate Limiting

The system uses a token bucket algorithm for rate limiting, configured via environment variables. This is intended to prevent abuse and manage costs associated with external API calls (e.g., Gemini).

Configuration	Environment Variable	Default	Description
Tokens per Minute	RATE_LIMIT_TOKENS_PER_MINUTE	60	The number of requests allowed per minute.

Sources: DEPLOYMENT_CHECKLIST.md

Circuit Breaker

A circuit breaker pattern is used to handle failures when interacting with external services. This prevents the application from repeatedly trying to call a service that is down, improving resilience.

The CircuitBreaker class has three states:

• CLOSED: Normal operation. Requests are allowed.
• OPEN: The service is considered down. Requests are blocked for a resetTimeout period.
• HALF_OPEN: After the timeout, a limited number of trial requests are allowed. If they succeed, the circuit moves to CLOSED. If they fail, it returns to OPEN.

Sources: services/circuitBreakerService.ts, DEPLOYMENT_CHECKLIST.md

Configuration:

Configuration	Environment Variable	Default	Description
Failure Threshold	CIRCUIT_BREAKER_THRESHOLD	5	Number of failures to trip the circuit to OPEN.

Sources: DEPLOYMENT_CHECKLIST.md

Access Control and Authorization

Beyond the global protections, specific features implement their own fine-grained access control.

GitHub API Integration Security

The integration with the GitHub API for issue creation and code searching is secured with a multi-layered approach to prevent unauthorized access to the repository.

Security Architecture:

1. Path Validation: Normalizes paths and blocks directory traversal attempts (../).
2. Allowlist Check: Only allows access to files and directories explicitly defined in an ALLOWED_PATHS list.
3. Blocklist Check: Explicitly denies access to sensitive files and directories like .git, .env, and node_modules.
4. File Size Limit: Limits fetched files to a maximum of 15KB to prevent abuse.
5. Token Validation: Requires a valid GITHUB_TOKEN.

Sources: GITHUB_INTEGRATION_COMPLETE.md

Audit and Traceability

To improve security forensics and track important events, structured audit logging is implemented for certain actions. For example, when a user forces a re-analysis (bypassing the duplicate check), an audit event is logged with the content hash and a _forceReanalysis flag is stored in the record. This creates a clear trail for potentially malicious or unusual activity.

Sources: MAJOR_FIX_UPDATE_SUMMARY.md

Conclusion

The security and protection strategy for BMSview is a multi-layered defense-in-depth approach. It acknowledges the public nature of its core data model with clear privacy notices while implementing robust server-side controls. These include comprehensive data validation to maintain integrity, service protection mechanisms like CORS, rate limiting, and circuit breakers to ensure availability, and strict, allowlist-based access control for sensitive integrations. The system is continuously evolving, with ongoing work to improve multi-tenancy and add further audit capabilities.