Environment Variables & Secrets
Relevant source files
The following files were used as context for generating this wiki page:
The FOSSBilling API uses environment variables and secrets to manage platform-specific configurations, sensitive credentials, and resource bindings. The system is designed to be platform-agnostic, separating core application logic from the underlying runtime environment (Cloudflare Workers or Node.js) through a dedicated platform layer and adapters.
Sources: README.md:14-22, AGENTS.md:5-10
Configuration Management
Configuration is handled through two primary mechanisms: environment variables for static configuration and secrets/KV storage for sensitive tokens. In development, local secrets are managed via a .dev.vars file.
Key Environment Variables & Bindings
The following table summarizes the primary environment variables and resource bindings used across the API services:
| Name | Type | Purpose | File References |
|---|---|---|---|
GITHUB_TOKEN | Secret | Personal Access Token for GitHub API access. | README.md:46, src/services/stats/v1/index.ts:168 |
UPDATE_TOKEN | Secret (KV) | Bearer token for authorizing /versions/v1/update. | README.md:44, test/services/versions/v1/errors.test.ts:70 |
DB_CENTRAL_ALERTS | Binding | Cloudflare D1 database for central alerts. | README.md:41, AGENTS.md:38 |
CACHE_KV | Binding | KV Namespace for caching GitHub API responses. | README.md:42, src/services/stats/v1/index.ts:167 |
AUTH_KV | Binding | KV Namespace for storing authentication tokens. | README.md:43, test/services/versions/v1/errors.test.ts:71 |
Sources: README.md:40-46, AGENTS.md:37-39, src/services/stats/v1/index.ts:166-168
Authentication Flow
The API utilizes a Bearer token authentication scheme specifically for the versions update endpoint. The token value is retrieved from the AUTH_KV storage at runtime.
Explanation: This diagram illustrates the authentication check performed during a cache update request, where the environment secret is verified against the client-provided header.
Sources: README.md:33-35, test/services/versions/v1/errors.test.ts:70-134
Platform Adapters
To maintain runtime agnosticism, the project implements environment variable access through adapters. This allows the same logic to function on Cloudflare Workers and Node.js environments.
Node.js Adapter
The NodeEnvironmentAdapter provides methods to interact with standard Node process.env. It supports basic operations to retrieve or verify the existence of variables.
Sources: test/lib/adapters/node/environment.test.ts:1-85
Cloudflare Adapter
On Cloudflare, variables and bindings are accessed via the env object passed to the worker's fetch handler. These include D1 database bindings and KV namespaces.
Sources: AGENTS.md:38, src/services/stats/v1/index.ts:14-16
Security and Logging
The system includes built-in safeguards to prevent the accidental exposure of secrets in logs. The logging utility automatically redacts sensitive keys and patterns.
Log Redaction Rules
The logger targets specific keywords and header patterns for redaction before outputting to the console:
- Keys:
api_token,secret_key,password,token,secret. - Patterns: Any string starting with
Bearerhas the subsequent token replaced with[REDACTED].
Sources: test/lib/logger.test.ts:39-160
Explanation: The flowchart details the logic used by the internal logger to ensure environment secrets and user tokens do not leak into system logs.
Sources: test/lib/logger.test.ts:39-160
Conclusion
Environment variables and secrets are central to the FOSSBilling API's operation, facilitating secure communication with the GitHub API and authorizing administrative actions. By utilizing platform adapters and automated log redaction, the architecture ensures that sensitive credentials remain protected across different deployment environments.