docs: authenticated catalogue probes and when a digest pin rots

Two registry questions that look settled and are not.

A 401 from an authenticated registry is a transport answer: it is returned for
every repository, so an anonymous probe cannot tell "not published" from "not
logged in". The reference shows the realm discovery, the token exchange using
the credential docker login already stored, and the discipline that makes a 404
mean something -- run a positive control in the same loop, or the run is
measuring your credentials rather than the catalogue.

A digest pin freezes the base as well as the application, which is the point
while upstream is publishing and inverts when upstream resumes rebuilding the
same release. Measured on one image: 1461 fixable findings on a digest pinned
ten months earlier against 293 on the floating tag it came from, same
application version. The reference gives the timestamp check to run before
claiming either "pinned, therefore safe" or "upstream never rebuilds".

It closes with the two ways a floating-tag exemption for self-rebuilt images
gets written wrongly: scoping it to a registry host rather than to ownership,
and testing the tag against the literal string latest, which lets
latest-rolling through.

SKILL.md gains the reference row; the one-line restatement of the frontmatter
description above Core Principles is dropped to stay inside the word cap.

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>

Author: CybotTM

skills/docker-development/SKILL.md

@@ -18,8 +18,6 @@ allowed-tools:
 
 # Docker Development
 
-Patterns for building, testing, and deploying Docker containers.
-
 ## Core Principles
 
 1. **Minimal** -- Alpine/distroless, multi-stage
@@ -134,3 +132,4 @@ Exclude: `.git`, `node_modules`/`vendor`, `.env*`, `*.pem`, `*.key`
 - `references/dind-testing-patterns.md` -- Docker-in-Docker testing patterns
 - `references/bind-mount-ownership.md` -- root-owned bind-mount artifacts
 - `references/gpg-verification.md` -- gpgv patterns; stale keybox locks
+- `references/registry-catalogue-and-pin-rot.md` -- catalogue probes; pin rot

skills/docker-development/references/registry-catalogue-and-pin-rot.md

@@ -0,0 +1,80 @@
+# Registry Catalogue Probing and Pin Rot
+
+Two questions that look settled and are not: *does this registry publish image
+X?* and *is a digest pin still the careful choice?*
+
+## A 401 is a transport answer, not an absence
+
+Authenticated registries refuse anonymous requests for **every** repository, so
+an anonymous probe cannot distinguish "not published" from "not logged in":
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' https://dhi.io/v2/mariadb/tags/list      # 401
+curl -s -o /dev/null -w '%{http_code}\n' https://dhi.io/v2/phpmyadmin/tags/list   # 401
+```
+
+Both 401. Neither says anything about the catalogue. Ask the registry which
+realm it wants, then authenticate against it — the credential is already on the
+machine if `docker login` has run:
+
+```bash
+curl -sI https://dhi.io/v2/mariadb/tags/list | grep -i www-authenticate
+# Bearer realm="https://dhi.io/token",service="registry.docker.io",scope="repository:mariadb:pull"
+
+AUTH=$(jq -r '.auths["dhi.io"].auth' ~/.docker/config.json)      # never echo this
+tok=$(curl -s -H "Authorization: Basic $AUTH" \
+  "https://dhi.io/token?service=registry.docker.io&scope=repository:mariadb:pull" \
+  | jq -r '.token')
+curl -s -o /dev/null -w '%{http_code}\n' \
+  -H "Authorization: Bearer $tok" https://dhi.io/v2/mariadb/tags/list            # 200
+```
+
+Now 200 versus 404 discriminates, and the probe has demonstrated it can return
+both — which is what makes a 404 evidence. Run the positive control (an image
+you know exists) in the same loop as the question you are actually asking; a
+run that returns 404 for everything is measuring your credentials.
+
+`.auths[…].auth` is base64 `user:token`, so treat the value as the secret it
+is: pass it through a variable, never into displayed output. With a
+`credsStore` configured there is no `auth` field — read the credential from the
+helper instead.
+
+## A digest pin can rot into the worse choice
+
+Pinning a third-party image to a digest freezes the application *and* the base
+underneath it. That is the point while upstream is publishing; it inverts the
+moment upstream resumes rebuilding the same release. Measured on one image
+during a single afternoon, counting only findings that have a fix:
+
+| reference | with a fix | CRITICAL+HIGH |
+|---|---:|---:|
+| digest pinned ten months earlier | 1461 | 258 |
+| the floating tag it was pinned from | 293 | 59 |
+
+Same application version in both. The tag moved with the rebuild; the pin did
+not. Before writing "pinned, therefore safe" — or the opposite, "upstream never
+rebuilds, so there is no update path" — read the tag's timestamp:
+
+```bash
+curl -s "https://hub.docker.com/v2/repositories/library/<image>/tags?page_size=10&ordering=last_updated" \
+  | jq -r '.results[] | "\(.name)\t\(.last_updated)\t\(.digest[0:19])"'
+```
+
+Equal digests across `:latest` and `:X.Y.Z` mean the release tag *is* latest, so
+waiting for an upstream rebuild is not a plan. A moved `last_updated` means any
+claim resting on staleness has expired and needs re-measuring, not repeating.
+
+## Floating tags are correct for images you rebuild
+
+The pinning rule is about trust, not about syntax: an image your own CI rebuilds
+daily should float, because a pin pins the fix out too. Two failure modes when
+that exemption is written down:
+
+- **Scoping it to a registry host.** Ownership is what earns the exemption, not
+  which host serves the bytes. An organisation publishing to both a private
+  registry and `ghcr.io/<org>` needs both recognised — compared as path
+  components, never as substrings, or `ghcr.io/someone/<org>-lookalike` and
+  `evil.com/<your-registry>/x` qualify.
+- **Testing the tag against the literal string `latest`.** `latest-rolling`,
+  `latest-alpine` and friends float exactly as much and sail through. Treat a
+  `latest-*` or `edge-*` prefix as floating.