Skip to content

docs: record the user-service /verify/ endpoint and the formidable v2 trap - #1479

Merged
olsonanl merged 1 commit into
BV-BRC:alphafrom
olsonanl:docs/claude-md-verify-endpoint-and-formidable
Oct 29, 2026
Merged

olsonanl merged 1 commit into
BV-BRC:alphafrom
olsonanl:docs/claude-md-verify-endpoint-and-formidable

Conversation

@olsonanl

Copy link
Copy Markdown
Contributor

Summary

Two pieces of hard-won detail that existed only in an uncommitted working tree.
Documentation only — 40 insertions, 0 deletions, no code touched.

User service /verify/ endpoint

The resend-verification-email call. Its only caller is UserProfileForm.js:86
(onResendEmail), shown when a logged-in user's account email is unverified.

Two curl pitfalls, both of which produce the same unhelpful 406 "Missing User ID":

  • the body needs an explicit Content-Type: application/json — curl -d defaults to
    form-encoded, so the server's JSON parser never populates id
  • the id is the bare username (olson), not the full olson@patricbrc.org

Also warns against confusing it with the Express /verify_refresh and /verify_failure
routes, which are web-app landing pages for the email round-trip, not the user-service API.

Email routes and the formidable v2 rename

routes/reportProblem.js and routes/notifySubmitSequence.js parse multipart posts via
express-formidable. formidable is never imported directly — the root-level dependency
exists only to pin what the unmaintained wrapper resolves.

formidable v2 renamed file.name → file.originalFilename and file.path →
file.filepath. Code written against v1 silently gets undefined, which had broken
problem-report attachments with fs.createReadStream(undefined). Includes the
forward-looking note that v3 is ESM and turns every req.fields value into an array.

Verified, not transcribed

Every claim checked against the current tree:

claim result
UserProfileForm.js:86 is the sole /verify/ caller ✅ only hit in public/js/p3/
sends {id: localStorage.userid} with explicit JSON content-type ✅ confirmed in source
neither route requires formidable directly ✅ zero direct requires
both read f.originalFilename || f.name, f.filepath || f.path ✅ reportProblem.js:55-56
express-formidable ^1.2.0, formidable ^2.1.2 pinned at root ✅ 2.1.5 installed
v3 is ESM ✅ registry says latest 3.5.4, "type": "module"

That last one matters: the ESM warning is a live hazard, not speculation — the same
CJS/ESM trap that took prod down via sanitize-html on Node 22.

🤖 Generated with Claude Code

… trap

Two more pieces of hard-won detail that existed only in an uncommitted working
tree. Documentation only, 40 insertions, no code touched.

**User service `/verify/`.** The resend-verification-email call, whose only
caller is `UserProfileForm.js:86` (`onResendEmail`). Two curl pitfalls that
both produce the same unhelpful `406 "Missing User ID"`: the body must carry
`Content-Type: application/json` (curl -d defaults to form-encoded, so the
server's JSON parser never populates `id`), and the id is the **bare**
username (`olson`), not the full `olson@patricbrc.org`. Also warns against
confusing it with the Express `/verify_refresh` and `/verify_failure` landing
pages, which are a different thing entirely.

**Email routes and formidable.** `reportProblem.js` and
`notifySubmitSequence.js` parse multipart via **express-formidable**, and
`formidable` is never imported directly — the root-level dep exists only to
pin what the unmaintained wrapper resolves. formidable v2 renamed
`file.name`->`file.originalFilename` and `file.path`->`file.filepath`, so v1-era
code silently gets `undefined` and attachments break with
`fs.createReadStream(undefined)`. Includes the forward-looking warning that v3
is ESM and turns every field value into an array.

Verified against the tree rather than transcribed:
  - UserProfileForm.js:86 is the sole /verify/ caller; the request really does
    send {id: localStorage.userid} with an explicit JSON content-type
  - neither route requires formidable directly; both read
    `f.originalFilename || f.name` and `f.filepath || f.path`
  - express-formidable ^1.2.0 with formidable ^2.1.2 pinned at root, 2.1.5
    installed
  - formidable latest is 3.5.4 with "type": "module", confirming the ESM
    warning is current rather than speculative

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@olsonanl
olsonanl merged commit 831b858 into BV-BRC:alpha Oct 29, 2026
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