State the UUID-is-the-credential rule as a rule (closes #301) #302

clawbot · 2026-08-25T22:39:11+02:00

clawbot commented

2026-08-25 22:39:11 +02:00

Closes #301. Docs-only apart from one test comment; no behaviour change.

The receiver has authenticated on the entrypoint UUID alone since inbound signature verification was removed in #279. The README described that as the current state. It did not say it is the decision, which leaves a future contributor free to propose HMAC as an improvement rather than as a reversal.

What changed:

## The entrypoint URL is the authentication secret now states the rule: the v4 UUID at /webhook/{uuid} is the credential and the only one; no shared secret, HMAC signature, bearer token or second factor will be added, including as defence in depth. It names the removal that settled it, and it says explicitly that signature headers a sender sends anyway are stored and forwarded but never checked — the previous text left that ambiguous.
The same section carries the two consequences an operator has to act on: the URL is a capability, so keep it out of logs, tickets and screenshots; and rotation means minting a new entrypoint, not changing a key.
It also handles the case the rule will next be argued from: a sender that only supports signed payloads to a well-known URL is a constraint on that integration, to be raised on its own terms, not grounds to reintroduce shared secrets.
The rule is reachable without scrolling 1,100 lines: a pointer in the intro, a new first bullet under Authentication (which previously listed the web UI, the API and /metrics and said nothing about the receiver at all), and a sharpened bullet under Security.

Stale language found and corrected: one, in internal/delivery/redirect_test.go. Its comment justified same-origin header retention partly by "the inbound signature the receiver verifies" — in this repo's vocabulary "the receiver" is /webhook/{uuid}, which verifies nothing. The endpoint that verifies it is the delivery target's, and the comment now says so.

Two places that read like stale signing language were checked and left alone as accurate: internal/delivery/redirect.go and internal/server/sentry.go describe signature headers senders put on the receiver route, which do arrive and are forwarded — neither claims webhooker checks them.

REPO_POLICIES.md was deliberately not touched. It is the cross-project policy document synced from sneak/prompts and carries last_modified front matter for that purpose, so a webhooker-specific carve-out does not belong in it. Worth knowing: its hardening section ends "if a standard security hardening measure exists for HTTP services and is not listed here, it is still expected. When in doubt, harden" — that is the sentence a future HMAC proposal will cite, and only the README now answers it.

TODO.md is untouched per its own Workflow section (issue branches do not touch it).

Closes https://git.eeqj.de/sneak/webhooker/issues/301. Docs-only apart from one test comment; no behaviour change. The receiver has authenticated on the entrypoint UUID alone since inbound signature verification was removed in https://git.eeqj.de/sneak/webhooker/pulls/279. The README described that as the current state. It did not say it is the decision, which leaves a future contributor free to propose HMAC as an improvement rather than as a reversal. What changed: - `## The entrypoint URL is the authentication secret` now states the rule: the v4 UUID at `/webhook/{uuid}` is the credential and the only one; no shared secret, HMAC signature, bearer token or second factor will be added, including as defence in depth. It names the removal that settled it, and it says explicitly that signature headers a sender sends anyway are stored and forwarded but never checked — the previous text left that ambiguous. - The same section carries the two consequences an operator has to act on: the URL is a capability, so keep it out of logs, tickets and screenshots; and rotation means minting a new entrypoint, not changing a key. - It also handles the case the rule will next be argued from: a sender that only supports signed payloads to a well-known URL is a constraint on that integration, to be raised on its own terms, not grounds to reintroduce shared secrets. - The rule is reachable without scrolling 1,100 lines: a pointer in the intro, a new first bullet under Authentication (which previously listed the web UI, the API and `/metrics` and said nothing about the receiver at all), and a sharpened bullet under Security. Stale language found and corrected: one, in `internal/delivery/redirect_test.go`. Its comment justified same-origin header retention partly by "the inbound signature the receiver verifies" — in this repo's vocabulary "the receiver" is `/webhook/{uuid}`, which verifies nothing. The endpoint that verifies it is the delivery target's, and the comment now says so. Two places that read like stale signing language were checked and left alone as accurate: `internal/delivery/redirect.go` and `internal/server/sentry.go` describe signature headers senders put on the receiver route, which do arrive and are forwarded — neither claims webhooker checks them. `REPO_POLICIES.md` was deliberately not touched. It is the cross-project policy document synced from `sneak/prompts` and carries `last_modified` front matter for that purpose, so a webhooker-specific carve-out does not belong in it. Worth knowing: its hardening section ends "if a standard security hardening measure exists for HTTP services and is not listed here, it is still expected. When in doubt, harden" — that is the sentence a future HMAC proposal will cite, and only the README now answers it. `TODO.md` is untouched per its own Workflow section (issue branches do not touch it).

clawbot added 1 commit 2026-08-25 22:39:11 +02:00

State the UUID-is-the-credential rule as a rule (closes #301 )

check / check (push) Successful in 3m35s

Details

def52ae092

The receiver has authenticated on the entrypoint UUID alone since
inbound signature verification was removed in #279. The README
described that as the current state; it did not say it is the
decision. Restate it as the rule, so a proposal to add HMAC, a shared
secret or a bearer token to the receiver is contradicted by the docs
rather than merely unimplemented.

The rule now appears in the intro, in its own section, and in the
Authentication and Security lists, and carries the two consequences an
operator has to act on: the URL is a capability to be kept out of logs
and tickets, and rotation means minting a new entrypoint rather than
changing a key.

Also corrects one stale comment: a redirect test said the inbound
signature was one "the receiver verifies", which in this repo's
vocabulary names webhooker's own receiver. The endpoint that verifies
it is the delivery target's.

clawbot added the needs-review label 2026-08-25 22:39:21 +02:00

clawbot self-assigned this 2026-08-25 22:39:25 +02:00

clawbot referenced this pull request

2026-08-25 22:39:33 +02:00

Document that the entrypoint UUID is the authentication and shared secrets are never used #301

check / check (push) Successful in 3m35s

Details

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin clawbot/docs-uuid-is-the-secret:clawbot/docs-uuid-is-the-secret

git checkout clawbot/docs-uuid-is-the-secret

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/webhooker#302