Secrets Management

Relevant source files

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

• ARCHITECTURE.md
• DEPLOYMENT.md
• README.md
• apps/worker/src/env.ts
• status.config.example.yml
• apps/worker/src/sentry-webhook.handler.test.ts

Secrets Management in StatusBeam is designed around Cloudflare's edge primitives, ensuring that sensitive credentials never enter the application bundle or public source control. The system distinguishes between environment-level secrets (like API tokens) and configuration-level secrets (like notification webhooks).

The primary mechanism for managing these sensitive values is through wrangler secret, which injects values into the Worker's environment at runtime. This ensures that the application is configuration-independent, allowing the same build to be deployed across different environments without baking in sensitive data.

Sources: ARCHITECTURE.md:148-151, DEPLOYMENT.md:8-12

Architecture and Storage

StatusBeam utilizes three primary locations for sensitive data, depending on the scope and usage of the secret:

1. Cloudflare Worker Secrets: Used for infrastructure-level credentials such as Cloudflare API tokens for cache purging.
2. KV Store (Private Config): While the status.config.yml is the primary configuration file, sensitive fields (like Slack Webhook URLs) are intended to be kept in the version of the config uploaded to KV, rather than the committed example file.
3. CI/CD Secrets: GitHub Actions secrets are used to store credentials required for the deployment pipeline.

Infrastructure Secrets Flow

The following diagram illustrates how secrets are provisioned and accessed by the Check Worker.

Key Secrets and Identifiers

The system relies on several critical secrets to maintain functionality across different layers.

Deployment Secrets

These are required for the CLI and CI/CD workflows to provision and deploy the Workers.

Secret Name	Purpose	Usage
CLOUDFLARE_API_TOKEN	Authentication for deployment	Used by statusbeam setup and GitHub Actions
CLOUDFLARE_ACCOUNT_ID	Targets specific CF account	Used by GitHub Actions

Sources: DEPLOYMENT.md:38-42, DEPLOYMENT.md:46-52

Runtime Worker Secrets

These are set via wrangler secret put and are accessible within the Env object of the Worker.

Secret Name	Purpose	Impact if Unset
CF_API_TOKEN	Permission to purge Workers Cache	Status changes take ~60s to reflect (TTL-bound)
CF_ZONE_ID	Target Zone for cache invalidation	Cache purge is skipped
WEBHOOK_SECRET	Validates inbound provider webhooks	Inbound webhooks (Sentry/Statuspage) will fail with 401
SENTRY_AUTH_TOKEN	Polls Sentry Issues API	Sentry backstop polling is disabled

Sources: DEPLOYMENT.md:112-115, status.config.example.yml:58-61, apps/worker/src/sentry-webhook.handler.test.ts:74-78

Implementation Details

Environment Definition

The Worker's environment is typed to ensure secrets are handled correctly within the code.

// apps/worker/src/env.ts (Derived)
export interface Env {
  STATUS_KV: KVNamespace;
  DB: D1Database;
  CF_API_TOKEN?: string;
  CF_ZONE_ID?: string;
  WEBHOOK_SECRET?: string;
  SENTRY_AUTH_TOKEN?: string;
}

Sources: apps/worker/src/env.ts:1-10, apps/worker/src/sentry-webhook.handler.test.ts:14-20

Webhook Authentication Logic

For inbound webhooks, such as those from Sentry or Atlassian Statuspage, StatusBeam uses a token query parameter compared against the WEBHOOK_SECRET. If the secret is unset in the environment, the system "fails closed" and returns a 401 Unauthorized response to prevent unauthenticated status updates.

Sources: apps/worker/src/sentry-webhook.handler.test.ts:74-83

Deployment Pipeline Security

The deployment process follows a specific security model:

• User API Tokens: It is recommended to use User-scoped tokens rather than account-owned tokens. Account-owned tokens often lack the User -> Memberships -> Read permission required for D1 schema execution.
• Environment Scoping: GitHub Actions are configured with environment-specific secrets (e.g., production environment) to gate deployments behind required reviews.
• Redaction: URLs and sensitive metadata are redacted to their origin before being logged by the system to prevent accidental leakage in Cloudflare Logs.

Sources: ARCHITECTURE.md:143-144, DEPLOYMENT.md:46-52, DEPLOYMENT.md:41-45

Conclusion

StatusBeam enforces a strict separation between code and secrets. By leveraging Cloudflare's native secret management and recommending that users keep sensitive webhook URLs out of version-controlled YAML files, the system maintains a high security posture while remaining easy to deploy and update. Significant operational features, such as instant cache purging, are optionally enabled through the provision of these secrets.

Sources: ARCHITECTURE.md:148-151, DEPLOYMENT.md:116-118