Deliver pre-generated REST API tokens by email

[lingwei-gu]

Summary

• add an opt-in anonymous POST /v1/token endpoint requiring real name and email
• claim credentials from a protected pre-generated JSON pool; the API server never generates a token
• persist the claimed token and identity in the existing YAML registry and activate it without restart
• deliver the credential to the submitted email address and four explicitly configured individual operator mailboxes
• require at least one individual CC and reject Google Groups recipients so credentials cannot fan out to subscribers
• identify the message as no-reply and direct support questions to the CC'd administrators through Reply all
• return only a generic 202 acceptance response; no credential appears in the HTTP response or request logs
• enforce independent client-IP and normalized-email cooldowns and one lifetime token per normalized email
• preserve existing Bearer and X-API-Key credentials and reserve legacy/partially populated pool rows
• retain optional academic trace fields (qid, question, run_id, agent, step, and retrieval query metadata)
• document the full token lifecycle, production Gmail SMTP setup, BM25 contract, logging, failure behavior, and deployment invariants
• reject non-finite BM25 k1 and b values consistently with the public API contract

Configuration and security

Token delivery remains disabled unless the server starts with --enable-token-issuance, a writable --config, --token-pool, SMTP host/sender settings, at least one individual --token-email-cc, and TLS email delivery. SMTP passwords must come from an owner-only file. Production should expose the identity-bearing endpoint over HTTPS.

The pre-generated inventory is prepared separately in private castorini/trec26-rag#30. Blank pool credentials are not accepted for authentication until a row is claimed and activated.

Tests

• 93 focused tests pass on the API host: tests.core.test_server_config, tests.core.test_token_delivery, and tests.core.test_rest
• SMTP unit coverage verifies STARTTLS with and without authentication, user + four individual-operator recipients, mailing-list rejection, private password-file enforcement, and no-reply Reply-all wording
• isolated host integration against the real ClimbMix index verifies generic 202, in-memory email capture, no response credential, new-token BM25 200, existing-token BM25 200, identity persistence, and an unchanged production config
• git diff --check