REPO_POLICIES: carve out capability-URL services from "when in doubt, harden" #52

New Issue

clawbot · 2026-08-25T22:41:37+02:00

clawbot commented

2026-08-25 22:41:37 +02:00

Problem

REPO_POLICIES.md is synced into every managed repo. Its HTTP hardening section
closes with:

> This list is non-exhaustive. Apply defense-in-depth: if a standard security
> hardening measure exists for HTTP services and is not listed here, it is still
> expected. When in doubt, harden.

As written, that authorises exactly what has now been ruled against twice: adding
HMAC signature verification / shared secrets on top of an endpoint whose
credential is already an unguessable capability URL. Inbound signature
verification was removed from webhooker entirely in
sneak/webhooker#279 on that reasoning. Today the only
place that contradicts the policy is webhooker's own README.md, so a future
contributor will propose HMAC in good faith and be able to cite the policy for
it.

Definition of done

A short addition to the HTTP hardening section of REPO_POLICIES.md, placed so a
reader hits it in the same breath as the "When in doubt, harden." sentence — not
in a distant section. It must establish:

An unguessable URL (a v4 UUID path segment minted per entrypoint) is a
complete credential, not a partial one.
Do not add HMAC signing, shared secrets, bearer tokens or other second factors
to such an endpoint, including as defence in depth. This has been considered
and rejected.
The consequences that DO apply, because a capability URL is a secret: keep it
out of logs, tickets and screenshots; rotate by minting a new entrypoint
rather than by changing a key.
A sender that cannot accept a secret URL and only supports signed payloads is
a constraint on that integration, to be raised — not grounds to reintroduce
shared secrets.

Constraints:

One precisely scoped carve-out. Do not delete or weaken any surrounding
hardening guidance.
make fmt applied; make check green.
TODO.md updated per its Workflow section in the same commit.
Branch off next, PR based on next, commit subject ends (closes #N).

## Problem `REPO_POLICIES.md` is synced into every managed repo. Its HTTP hardening section closes with: > This list is non-exhaustive. Apply defense-in-depth: if a standard security > hardening measure exists for HTTP services and is not listed here, it is still > expected. When in doubt, harden. As written, that authorises exactly what has now been ruled against twice: adding HMAC signature verification / shared secrets on top of an endpoint whose credential is already an unguessable capability URL. Inbound signature verification was removed from `webhooker` entirely in https://git.eeqj.de/sneak/webhooker/pulls/279 on that reasoning. Today the only place that contradicts the policy is `webhooker`'s own `README.md`, so a future contributor will propose HMAC in good faith and be able to cite the policy for it. ## Definition of done A short addition to the HTTP hardening section of `REPO_POLICIES.md`, placed so a reader hits it in the same breath as the "When in doubt, harden." sentence — not in a distant section. It must establish: - An unguessable URL (a v4 UUID path segment minted per entrypoint) is a complete credential, not a partial one. - Do not add HMAC signing, shared secrets, bearer tokens or other second factors to such an endpoint, including as defence in depth. This has been considered and rejected. - The consequences that DO apply, because a capability URL is a secret: keep it out of logs, tickets and screenshots; rotate by minting a new entrypoint rather than by changing a key. - A sender that cannot accept a secret URL and only supports signed payloads is a constraint on that integration, to be raised — not grounds to reintroduce shared secrets. Constraints: - One precisely scoped carve-out. Do not delete or weaken any surrounding hardening guidance. - `make fmt` applied; `make check` green. - `TODO.md` updated per its Workflow section in the same commit. - Branch off `next`, PR based on `next`, commit subject ends ` (closes #N)`.

clawbot referenced this issue from a commit

2026-08-25 22:44:00 +02:00

An unguessable capability URL is the whole credential (closes #52)

clawbot referenced a pull request that will close this issue

2026-08-25 22:44:08 +02:00

An unguessable capability URL is the whole credential (closes #52) #53

clawbot commented

2026-08-25 22:44:38 +02:00

PR: #53

Carve-out sits in the same indented block as "When in doubt, harden.", directly
below it, so the reader cannot reach the sentence without reaching the
exception.

Disclosures:

Branched from and based on next, not main. This repo's TODO.md Workflow
section still says "branch (from main)", which predates the next-branch
model; next is currently six commits ahead of main.
TODO.md: added a Completed Steps entry only. The Workflow rotation
(Next Step to Completed, promote from Future Steps) was left alone because
this work is not the recorded Next Step.
Also bumped the document's last_modified front matter, outside the literal
scope of this issue, because the repo's own cross-project-docs rule requires
it on any change to that file.
Went straight to implementation without a separate plan comment: the issue
body above is the plan, and repeating it would duplicate.

PR: https://git.eeqj.de/sneak/prompts/pulls/53 Carve-out sits in the same indented block as "When in doubt, harden.", directly below it, so the reader cannot reach the sentence without reaching the exception. Disclosures: - Branched from and based on `next`, not `main`. This repo's `TODO.md` Workflow section still says "branch (from `main`)", which predates the `next`-branch model; `next` is currently six commits ahead of `main`. - `TODO.md`: added a Completed Steps entry only. The Workflow rotation (Next Step to Completed, promote from Future Steps) was left alone because this work is not the recorded Next Step. - Also bumped the document's `last_modified` front matter, outside the literal scope of this issue, because the repo's own cross-project-docs rule requires it on any change to that file. - Went straight to implementation without a separate plan comment: the issue body above is the plan, and repeating it would duplicate.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/prompts#52