Skip to content

Document the security model of the secrets path - #42

Merged
czpython merged 1 commit into
mainfrom
dru-405-security-model
Sep 7, 2026
Merged

Document the security model of the secrets path#42
czpython merged 1 commit into
mainfrom
dru-405-security-model

Conversation

@czpython

@czpython czpython commented Sep 6, 2026

Copy link
Copy Markdown
Owner

What changes

docs/security.md gets the secrets path under three headings, in short sentences with one fact each:

  • Which field to use: env for configuration, secrets for a credential, with the encryption and the key rotation.
  • What the proxy protects: the placeholder's scope, the one header swapped, the refused destinations, where the real value lives, what deletion removes, and what the CA in the box means.
  • What env is and is not: plaintext by design, with the PAM rules. No secrets in env, ever.

The provider material paragraphs, the Tailscale auth key and IMDS, keep their facts under a heading of their own. Every other section of the document is unchanged.

Where this differs from the ticket

  • The ticket lists five sections, "What none of this fixes" among them. The document has three. The host-side caveats are out. The CA and the teardown facts sit under "What the proxy protects".
  • The ticket says the CA key lives on the exchange host next to SECRETS_KEY. The key lives in the proxy's volume. The document says the volume, and says to guard it like SECRETS_KEY.
  • The ticket names the field hosts.env. The field is env on POST /hosts, and the document names it that way.
  • Proxy internals that architecture.md and deploy.md already carry, the 403 answer, flow_detail, and the SSH remote rewrite, are not repeated here.

Names

None new.

Gates

uv run ruff check, uv run ruff format --check, uv run pyright, and uv run pytest are green.

Acceptance

A documentation change. The facts were checked against the code and the deploy doc while writing.

Review

The adversarial review reported six overstatements in the prose, applied in an earlier revision. Three of them are still in the text after the cut:

  • The CA key permits impersonation of any host to the box, since the CA sits in the system trust store.
  • A placeholder works until the host row is deleted. The lease schedules that deletion and revokes nothing on its own.
  • The swap applies to HTTPS the proxy terminates. Plain HTTP is forwarded unchanged.

The review also noted that the exchange answers for a host past its lease until the row is deleted. That is how the code works today. A check of expires_at in the exchange would be a product change for its own ticket.

@czpython
czpython force-pushed the dru-405-security-model branch 2 times, most recently from f9ed5ef to 5faff7c Compare September 6, 2026 17:20
@czpython
czpython force-pushed the dru-462-acceptance-kit branch from 5f71a52 to 1427d9e Compare September 7, 2026 06:09
@czpython
czpython changed the base branch from dru-462-acceptance-kit to main September 7, 2026 07:07
@czpython
czpython force-pushed the dru-405-security-model branch from 5faff7c to 682e2f8 Compare September 7, 2026 07:07
The security doc says which field to use, what the proxy protects, and
what env is and is not, in short sentences with one fact each. The
facts were spread over one long section. They now sit under one heading
each, so a reader can find the answer without asking.
@czpython
czpython force-pushed the dru-405-security-model branch from 682e2f8 to 3f268e0 Compare September 7, 2026 07:23
@czpython
czpython merged commit ec2d3cf into main Sep 7, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant