Skip to content

docs(user.js): correct claims that do not hold - #305

Draft
netravnen wants to merge 1 commit into
fix/build-include-marker-guardfrom
docs/correct-stale-claims
Draft

docs(user.js): correct claims that do not hold#305
netravnen wants to merge 1 commit into
fix/build-include-marker-guardfrom
docs/correct-stale-claims

Conversation

@netravnen

Copy link
Copy Markdown
Contributor

Merging to master is the deploy for this repo -- Tampermonkey auto-updates
every admin from raw.githubusercontent.com -- so these documents are the
control, not commentary. Four claims in them were wrong, and two were
wrong in the direction that discourages fixing the underlying problem.

ARCHITECTURE.md described CP as matching
/cp/peeringdb_server/*/*/change/*. The actual header is /cp/*, the
whole Django admin site. The narrower claim materially understates the
injection surface, and the source already carries a comment saying so.

CONCERNS.md's coverage row claimed every high-risk pure-logic target was
covered and advised expanding only opportunistically. In fact the retry
wrappers had zero coverage, and the shim could not have exercised them:
its fake response had no headers.get(), so the Retry-After branch
threw on contact. That is how a policy of retrying PUT and DELETE on any
429/5xx shipped unnoticed -- the row asserting completeness is part of
why nobody looked.

CONCERNS.md's @connect * row described CP's cross-origin capability as
anonymous: true GET-only. That holds for the IX-F fetch alone. Both
pdbFetch and pdbPost fall back to gmRequestWithRetry with
withCredentials: true, anonymous: false for non-same-origin URLs, and
pdbPost's fallback carries whatever method it was given -- PUT and DELETE
included. No current call site sends a write to a non-PeeringDB origin,
so this is latent rather than live, but it is a credentialed
arbitrary-method capability, not a read-only one.

Changes:

  • ARCHITECTURE.md: correct CP's @match and note that route scoping lives
    in the modules[] registry, not the header.
  • CONCERNS.md coverage row: state plainly that "complete" was wrong and
    why, list what has since been covered, and name what genuinely remains
    (DOM-heavy modules the shim's FakeElement cannot drive at all).
  • CONCERNS.md @connect row: qualify the GET-only claim to the IX-F path,
    describe the credentialed fallback with file references, and note that
    scoping that fallback to the PeeringDB origins is possible and not done.
    Reword the write mitigation now that writes are no longer auto-retried.
  • AGENTS.md Testing: add the five test files this series introduced, and
    replace the "every pure-logic target is now covered" sentence with the
    lesson instead.

Security:

  • Documents a wider cross-origin capability than the @connect *
    justification previously described. No code change here; the gap is now
    recorded rather than implicitly denied.

Testing:

  • node --test: 535 tests, 534 pass, 1 skipped (live tests are opt-in).
  • Every corrected claim re-verified against current code before rewriting:
    the @match headers, the anonymous/withCredentials call sites at
    peeringdb-cp-consolidated-tools.src.js:2939/:6143/:6300, and the
    coverage state after this series.
  • Markdown table column counts confirmed unchanged in CONCERNS.md.

Backwards Compatibility:

  • Documentation only.

Assisted-by: Claude:claude-opus-5


Stack created with GitHub Stacks CLIGive Feedback 💬

@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from 3d3bd6f to 538e75d Compare August 19, 2026 22:27
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from 538e75d to be3af0f Compare August 19, 2026 22:28
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from be3af0f to b87e8ea Compare August 19, 2026 22:29
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from b87e8ea to e36416a Compare August 19, 2026 22:31
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from e36416a to 3be984f Compare August 19, 2026 23:05
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from 3be984f to 0c38d1c Compare August 19, 2026 23:06
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from 0c38d1c to d3bcacf Compare August 19, 2026 23:07
Merging to master is the deploy for this repo -- Tampermonkey auto-updates
every admin from raw.githubusercontent.com -- so these documents are the
control, not commentary. Four claims in them were wrong, and two were
wrong in the direction that discourages fixing the underlying problem.

ARCHITECTURE.md described CP as matching
`/cp/peeringdb_server/*/*/change/*`. The actual header is `/cp/*`, the
whole Django admin site. The narrower claim materially understates the
injection surface, and the source already carries a comment saying so.

CONCERNS.md's coverage row claimed every high-risk pure-logic target was
covered and advised expanding only opportunistically. In fact the retry
wrappers had zero coverage, and the shim could not have exercised them:
its fake response had no `headers.get()`, so the `Retry-After` branch
threw on contact. That is how a policy of retrying PUT and DELETE on any
429/5xx shipped unnoticed -- the row asserting completeness is part of
why nobody looked.

CONCERNS.md's `@connect *` row described CP's cross-origin capability as
`anonymous: true` GET-only. That holds for the IX-F fetch alone. Both
`pdbFetch` and `pdbPost` fall back to `gmRequestWithRetry` with
`withCredentials: true, anonymous: false` for non-same-origin URLs, and
pdbPost's fallback carries whatever method it was given -- PUT and DELETE
included. No current call site sends a write to a non-PeeringDB origin,
so this is latent rather than live, but it is a credentialed
arbitrary-method capability, not a read-only one.

Changes:
- ARCHITECTURE.md: correct CP's @match and note that route scoping lives
  in the modules[] registry, not the header.
- CONCERNS.md coverage row: state plainly that "complete" was wrong and
  why, list what has since been covered, and name what genuinely remains
  (DOM-heavy modules the shim's FakeElement cannot drive at all).
- CONCERNS.md @connect row: qualify the GET-only claim to the IX-F path,
  describe the credentialed fallback with file references, and note that
  scoping that fallback to the PeeringDB origins is possible and not done.
  Reword the write mitigation now that writes are no longer auto-retried.
- AGENTS.md Testing: add the five test files this series introduced, and
  replace the "every pure-logic target is now covered" sentence with the
  lesson instead.

Security:
- Documents a wider cross-origin capability than the `@connect *`
  justification previously described. No code change here; the gap is now
  recorded rather than implicitly denied.

Testing:
- node --test: 535 tests, 534 pass, 1 skipped (live tests are opt-in).
- Every corrected claim re-verified against current code before rewriting:
  the @match headers, the anonymous/withCredentials call sites at
  peeringdb-cp-consolidated-tools.src.js:2939/:6143/:6300, and the
  coverage state after this series.
- Markdown table column counts confirmed unchanged in CONCERNS.md.

Backwards Compatibility:
- Documentation only.

Assisted-by: Claude:claude-opus-5
@netravnen
netravnen force-pushed the docs/correct-stale-claims branch from d3bcacf to 72f9c6a Compare August 19, 2026 23:09
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