API Authentication
Relevant source files
The following files were used as context for generating this wiki page:
API Authentication in the FOSSBilling API Worker is primarily used to protect sensitive administrative endpoints, specifically those involving cache invalidation and manual data updates. While many endpoints for versioning and alerts are public, the system employs a token-based security model to ensure that only authorized entities can trigger heavy operations like refreshing GitHub release data.
The authentication logic is integrated into the Hono-based routing structure, utilizing environment bindings for secure storage of credentials. This ensures that the worker remains lightweight while maintaining necessary security boundaries for operations that consume external API rate limits or modify internal state.
Sources: README.md, src/services/versions/v1/index.ts, AGENTS.md
Bearer Token Authentication
The primary authentication mechanism is a Bearer Token strategy. This is specifically enforced on the /versions/v1/update endpoint. Requests to this endpoint must include an Authorization header formatted as Bearer <UPDATE_TOKEN>. The system validates the provided token against a secret value stored in the platform's Key-Value (KV) storage.
Sources: README.md:32-34, test/services/versions/v1/middleware.test.ts:182-192
Authentication Flow
The following sequence diagram illustrates the validation process when a client attempts to access a protected update route.
Configuration and Storage
Authentication secrets are managed through platform-specific bindings. This allows the application logic to remain runtime-agnostic while the actual secrets are provided by the environment (Cloudflare Workers or local development).
| Component | Type | Description |
|---|---|---|
AUTH_KV | KV Namespace | A Cloudflare KV binding used to store authentication-related keys. |
UPDATE_TOKEN | Secret Key | The specific key within AUTH_KV containing the valid bearer token. |
GITHUB_TOKEN | Env Variable | A Personal Access Token used by the service to authenticate against the GitHub API. |
Sources: README.md:43-51, AGENTS.md:38-40
Token Caching and Rotation
To optimize performance, the system may cache the UPDATE_TOKEN retrieved from KV. The implementation includes a resetUpdateTokenCache() utility to handle scenarios where the token needs to be re-validated or rotated, preventing stale tokens from remaining valid beyond their intended TTL.
Sources: src/services/versions/v1/index.ts, test/services/versions/v1/index.test.ts:290-330
Error Handling
The authentication middleware provides specific feedback based on the nature of the request failure.
- 400 Bad Request: Returned if the
Authorizationheader is present but malformed (e.g., missing the "Bearer " prefix or containing only whitespace). - 401 Unauthorized: Returned if the
Authorizationheader is missing or if the provided token does not match the value stored inAUTH_KV. - 500 Internal Server Error: Returned if the authentication middleware cannot access the necessary KV storage or if the
UPDATE_TOKENkey is missing from the configuration.
Sources: test/services/versions/v1/errors.test.ts:70-112, test/integration/app.test.ts:130-140
Security Implementation Details
// Example of how the token is validated in tests (reflecting implementation logic)
it("should reject Authorization without Bearer prefix", async () => {
const ctx = createExecutionContext();
const response = await app.request(
"/versions/v1/update",
{
headers: {
Authorization: "test-update-token-12345"
}
},
env,
ctx
);
await waitOnExecutionContext(ctx);
expect(response.status).toBe(400);
});
Sources: test/services/versions/v1/errors.test.ts:88-100
The API also implements CORS (Cross-Origin Resource Sharing) middleware, ensuring that even during authentication failures, the appropriate Access-Control-Allow-Origin: * headers are set, allowing frontend applications to handle these errors correctly.
Sources: test/services/versions/v1/middleware.test.ts:250-258