sneak
4e6a782edf
All checks were successful
check / check (push) Successful in 16s
The HTTP hardening section ends with "when in doubt, harden", which as written authorises adding HMAC signing or a shared secret on top of an endpoint already gated by an unguessable per-entrypoint UUID URL. That has been ruled against twice, and inbound signature verification was removed from webhooker on exactly that reasoning; until now the only text contradicting the policy was webhooker's own README. Adds one scoped carve-out immediately after that sentence: such a URL is a complete credential and gets no second factor, not even as defence in depth. The consequences that do follow — keep it out of logs and tickets, rotate by minting a new entrypoint — are stated, as is what to do with a sender that only supports signed payloads. Nothing in the surrounding hardening guidance is removed or weakened.
162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# Workflow
|
|
|
|
- branch (from `main`)
|
|
- do the work in Next Step
|
|
- move Next Step to the top of Completed Steps
|
|
- move the top item of Future Steps into Next Step
|
|
- commit (`TODO.md` changes in the same commit as the work)
|
|
- merge to `main` if the branch is not protected, otherwise open a PR
|
|
- push
|
|
|
|
# Status
|
|
|
|
pre-1.0
|
|
|
|
# Next Step
|
|
|
|
Finish the two draft prompt documents in the working tree and commit them:
|
|
prompts/FIXUP_CLEAN.md (currently a near-empty stub) and prompts/FIXUP_REPORT.md
|
|
(a rough draft). Write the missing content, run `make fmt` so they pass
|
|
fmt-check, and commit.
|
|
|
|
# Completed Steps
|
|
|
|
- 2026-08-25: Carved capability-URL services out of "when in doubt, harden" in
|
|
REPO_POLICIES.md: an unguessable per-entrypoint UUID URL is a complete
|
|
credential and gets no second authentication factor.
|
|
- 2026-08-10: Moved every lint run into a container. `script/lint` now runs the
|
|
linter directly when `LINT_IN_CONTAINER=1` and otherwise builds
|
|
`Dockerfile.lint`, so the linter never runs on a developer host — closing the
|
|
content-keyed result cache that produced a confirmed false green, the
|
|
host-global `$TMPDIR/golangci-lint.lock`, and host/container version skew.
|
|
Detection is on that marker alone: a false negative inside a container fails
|
|
loudly on the missing daemon, while a false positive on a host would silently
|
|
restore host linting, so `/.dockerenv` is rejected outright — measured absent
|
|
inside BuildKit `RUN` steps and present on hosts that are themselves
|
|
containers. Everything else keeps its existing shape: `make check` still runs
|
|
in the image, `script/cibuild` is still one build, and the Go multistage lint
|
|
stage survives with `ENV LINT_IN_CONTAINER=1`. `Dockerfile.lint` carries the
|
|
same `CHECK_EPOCH` guard, with the `ARG` below the dependency layer so only
|
|
the lint re-runs. The `script/bootstrap` golangci-lint install and the
|
|
per-checkout cache/lock/`.lint-cache` wrapper are deleted as superseded; a JS
|
|
repo's `yarn install` stays, since the rule is about where a verdict comes
|
|
from, not about which binaries exist. `golangci-lint config verify` was kept
|
|
on measurement: a bogus config key passes `golangci-lint run` with `0 issues`
|
|
and fails `config verify`, and every case reproduced byte-identically under
|
|
`--network none`, so the schema is embedded and the line costs no network.
|
|
Comment blocks across the touched files were cut hard in the same pass.
|
|
- 2026-08-09: Made a golangci-lint result belong to the tree that asked for it.
|
|
REPO_POLICIES.md now carries the canonical Go `script/lint`, which gives the
|
|
linter per-checkout `GOLANGCI_LINT_CACHE` and per-checkout `TMPDIR`. The two
|
|
are separate defects and the second is the one that gets dropped: the result
|
|
cache is keyed on file content rather than location, so checkouts holding
|
|
identical files serve each other's findings under the other's path, while the
|
|
concurrency lock is `$TMPDIR/golangci-lint.lock` — host-global, independent of
|
|
the cache, and unaffected by isolating it. Moving workers from worktrees to
|
|
their own clones does not help either half; it only removes the foreign-path
|
|
artefact that made the defect visible. The lock error is retried rather than
|
|
surfaced, because it is not a result: it exits non-zero exactly as findings
|
|
do, and reporting it as findings sends a correct branch back for rework.
|
|
Detection is on the stderr stream and never on exit status, so a finding
|
|
quoting the lock message in source cannot be retried away, and exhaustion
|
|
exits 75 with a VOID message rather than passing or failing quietly.
|
|
`--allow-serial-runners` (which keeps the guard and queues) covers the
|
|
same-checkout overlap that `TMPDIR` scoping cannot; `--allow-parallel-runners`
|
|
is rejected outright. The stdout and stderr capture files are per invocation
|
|
rather than per checkout, because serialising the linter does not serialise
|
|
the shell's redirections: two runs in one checkout — the overlap the flag
|
|
exists to support — would otherwise truncate and read each other's output,
|
|
which is the same defect one layer above where it was fixed. Both checklists
|
|
gained the corresponding items, since a half-fix that sets only the cache
|
|
reads as complete. `GOCACHE` was measured and does not need isolating.
|
|
Verified with the snippet extracted from the committed document and executed
|
|
as a consuming repo would adopt it, against paired controls: contamination
|
|
reproduced on the pre-fix form and absent on the adopted one, retry engaged,
|
|
exhaustion loud, a genuine finding still reported, and a held host lock
|
|
failing the pre-fix script while leaving the adopted one untouched.
|
|
- 2026-08-09: Kept in-repo agent scratch out of the Docker build context and out
|
|
of version control. `.claude/` holds one worktree — an entire additional
|
|
checkout of the repo — per in-flight agent, and under `COPY . .` all of it was
|
|
reaching the image: another session's unreviewed, sometimes uncommitted work,
|
|
inflating the context by a multiple of the repo and invalidating `COPY` for
|
|
reasons unrelated to the repo's own content. The `.dockerignore` entry is
|
|
root-anchored, because the directory occurs exactly once where agents run at
|
|
the repo root and the `**/` form additionally deletes any nested directory of
|
|
that name — with the residual gap that follows from anchoring (a monorepo
|
|
running agents in subdirectories still ships `services/api/.claude/`) stated
|
|
in the canonical `.dockerignore`, the policy and the existing-repo checklist,
|
|
since consuming repos receive the files rather than the tracker; the
|
|
`.gitignore` entry is unanchored, because `.gitignore` patterns already match
|
|
at every depth, and each file is written to its own semantics rather than
|
|
derived from the other. Also closed the consequence that ships broken
|
|
silently: excluding `.git` means `git describe` cannot run in any build stage
|
|
and yields an empty version without erroring, so `script/docker` and
|
|
`script/cibuild` now compute the version on the host and pass
|
|
`--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
|
|
from instead of leaving the reader to fill the gap with `git describe` inside
|
|
the build. The two Go documents that carry the `GOLDFLAGS` pattern were
|
|
corrected in the same pass, from `:=` to `?=`, since a `$(shell git describe)`
|
|
evaluated inside a build stage is exactly the empty version this closes.
|
|
Verified by enumerating a probe image before, after, and against the
|
|
`**/`-prefixed form, with a positive control and the `CHECK_EPOCH` cache
|
|
verification re-run under the changed build context.
|
|
- 2026-08-09: Closed the secret exposure in the canonical `.dockerignore`: a
|
|
developer's local `.env`, `*.pem` or `*.key` was reaching the Docker build
|
|
context under `COPY . .`, invisible to every git-based check because
|
|
`.gitignore` covers it. The patterns are written to `.dockerignore`'s own
|
|
`moby/patternmatcher` semantics — `**/`-prefixed so they hold at every depth,
|
|
which also fixes nested `node_modules` — rather than transplanted from
|
|
`.gitignore`, whose unprefixed form protects only the repository root while
|
|
reading as solved. Coverage extends past the `.env`/`.pem`/`.key` trio to the
|
|
`prod.env` convention, `.envrc`, PKCS#12 bundles and extensionless SSH keys,
|
|
every one of them case-folded with character ranges because matching is
|
|
case-sensitive and an ALL-CAPS twin per pattern still misses `Server.Key`.
|
|
`REPO_POLICIES.md` and both repo checklists now state that asymmetry and
|
|
require verification by enumerating the image rather than by reading the
|
|
patterns. Verified with a probe image before, against three naive forms
|
|
(unprefixed, lowercase-only, ALL-CAPS-doubled), and after.
|
|
- 2026-08-09: Made the pinned golangci-lint actually propagate: REPO_POLICIES.md
|
|
now carries the canonical `script/bootstrap` snippet for Go repos, which
|
|
installs when the installed version does not match the pin (the old
|
|
`if missing` guard tested PATH presence only, so pins were inert on any
|
|
provisioned machine and CI silently disagreed with local) and then re-resolves
|
|
the binary through `PATH` and fails loudly, naming the shadowing path, when
|
|
the install did not take effect — the failure mode the naive
|
|
compare-then-install fix leaves behind while reporting success.
|
|
- 2026-08-09: Fixed the false green in the canonical CI gate: `script/cibuild`
|
|
and `script/docker` now pass a per-invocation `CHECK_EPOCH` nonce, and the
|
|
`Dockerfile` (plus the Go multistage template in REPO_POLICIES.md, in both its
|
|
lint and builder stages) declares `ARG CHECK_EPOCH` with a guard that makes a
|
|
bare `docker build .` fail closed. Corrected the org-canonical text that
|
|
asserted a successful build implies all checks pass, across every document
|
|
carrying it: `REPO_POLICIES.md`, both repo checklists (which still told agents
|
|
to write the pre-fix `script/cibuild` and ended on an acceptance item the
|
|
guard makes unsatisfiable), and the Go styleguide.
|
|
- 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
|
|
config already deployed byte-identical across the org's Go repos (settings
|
|
under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually
|
|
apply under golangci-lint v2). Recorded the canonical golangci-lint version
|
|
(v2.12.2, commit-pinned) in REPO_POLICIES.md.
|
|
- 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
|
|
styleguide.
|
|
- 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test
|
|
rerun patterns in REPO_POLICIES.md.
|
|
- 2026-03-11: Added HTTP service hardening policy for 1.0 releases.
|
|
- 2026-03-10: Added policy: no build artifacts in repos.
|
|
- 2026-03-04: Added LLM prose tells reference and copyediting checklist, then
|
|
several self-applied revision passes.
|
|
- 2026-02-28: Expanded the pre-1.0 schema migration rule; added clawpub
|
|
reference.
|
|
- 2026-02-23: Added Go style rules (no type-only packages, Stringer for
|
|
string-based types); template repos section in README.
|
|
- 2026-02-22: Initial policy corpus: REPO_POLICIES.md, code styleguides
|
|
(general, Go, JS, Python), repo checklists, CI policy, hash pinning, Go HTTP
|
|
server conventions, repo scaffolding.
|
|
|
|
# Future Steps
|
|
|
|
- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
|
|
- Commit this TODO.md at the repo root; it is the last missing policy file.
|
|
- Decide the fate of untracked resume.sh: commit it or delete it.
|
|
- Add more prompt templates for common development tasks (from README TODO).
|