ProGuide sound-harvester auth

Translator Series · champion capture gate for the ideal-sounds bank. This page is the public HTML surface (raw .md under /docs/ is blocked by design).

What this unblocks

Authorized POST /api/sound-harvester/recording captures feed champion storage and can publish into ideal_sounds. An empty bank is expected until a real authorized session uploads — not proof the route is missing.

Auth model (from source)

Path	Auth
`POST /api/sound-harvester/recording`	Either `X-Field-Token` matching server env `FIELD_INGEST_TOKEN`, or a non-expired ProGuide magic-link token via body `proguide_token`, header `X-Proguide-Token`, or query `token`.
Field ingest bridge routes	Same field token, or admin Bearer JWT on selected paths.

Empty field-token env fails closed (401). This page never lists token values.

Live control probes (how to read results)

Request	Expected	Implies
`POST …/recording` with no token	401	Auth middleware on the recording path is live.
`POST …/this-path-does-not-exist-xyz`	404	Auth is route-scoped — a 401 alone does not prove a path exists.
`GET /api/sound-harvester`	404	No bare index; use documented subpaths.
`GET /api/ideal-sounds`	200 JSON array (may be empty `[]`)	Empty array ≠ missing route. Control: a fake API path must return 404, not the same body as ideals.

Operator flow (no secrets)

Ensure FIELD_INGEST_TOKEN is set on the live tsiapp process or issue a non-expired ProGuide magic-link for the guide.
Studio / field client: multipart field audio + metadata (species, vocalization, proguide_slug, …) + one auth channel above.
Successful write lands under champion capture storage and can feed POST /api/ideal-sounds/create.
Published ideals appear on GET /api/ideal-sounds?animal=&call_type= for rookie detector / librarian.

Magic-link issuance

Issuance is an operator / product action (token mint + guide invite). This page documents the verify contract only. Guide invites and external mail remain human-gated.

Honesty: never treat /api/health 200 as proof a new Express route is live — probe the exact path and a deliberately fake control path. Practice UIs must label mock ideals until the server bank is non-empty. No champion language on client-mock.