Allow GitHub App private-key providers without making BWS mandatory

[cbeaulieu-gt]

Problem

The GitHub App is a core Harness authority and must remain required. Bitwarden Secrets Manager is currently coupled to that authority as the only App-private-key source:

• sandbox configuration requires BWS_PEM_SECRET_ID;
• startup fetches the PEM only through bws;
• setup and doctor treat the BWS CLI and access token as mandatory.

That prevents a lightweight development/candidate lane from using a dedicated GitHub App unless it also provisions BWS. BWS is desirable for the accepted managed deployment, but it should be a secret provider rather than part of the GitHub App protocol.

Goal

Keep GitHub App authentication mandatory while supporting an explicit, fail-closed choice of App-private-key provider.

Proposed provider contract

Support exactly one of:

1. bws: the existing BWS_PEM_SECRET_ID plus BWS_ACCESS_TOKEN flow.
2. file: a mode-restricted private-key file, including a path supplied by a systemd credential mount.

Do not accept the PEM contents directly in an environment variable or repository configuration.

Provider-composition clarification (2026-09-05)

The App-key provider selector controls only the GitHub App PEM source. When the App key uses file, the independent optional settings BWS_GH_TOKEN_SECRET_ID and BWS_HEARTBEAT_PING_URL_SECRET_ID remain usable. The bws executable and BWS_ACCESS_TOKEN are required whenever the selected App-key provider or either configured optional secret uses BWS; a file-only deployment with no optional BWS locators is fully BWS-free.

Acceptance criteria

• Configuration selects one recognized App-key provider and rejects missing, ambiguous, or multiple providers.
• The BWS provider preserves the current immediate access-token scrubbing and in-memory installation-token behavior.
• The file provider reads a regular, non-symlink, non-group/world-readable PEM file once, validates that it can sign the App JWT, and never prints its path contents.
• App-key material and provider bootstrap variables are stripped from every worker subprocess environment.
• bws, BWS_ACCESS_TOKEN, and BWS_PEM_SECRET_ID are required only when a configured secret uses BWS.
• Setup, sandbox configuration, doctor checks, ruleset provisioning, and documentation use the same provider-selection rules.
• The GitHub App ID, installation ID, required repository permissions, token refresh, and worker/App identity separation remain mandatory and unchanged.
• Tests cover both providers plus missing, conflicting, insecure-file, unreadable-file, malformed-PEM, and subprocess-leak failures.

Deployment intent

The rapid-development lane can use a dedicated GitHub App installed only on a throwaway sandbox repository with a restricted PEM file. The accepted managed deployment can continue to require BWS. This change must not introduce a GitHub-App-free operating mode.

🤖 Generated by Codex on behalf of @cbeaulieu-gt