autoreg-skills-max/skills/hacktoberfest-perks/SKILL.md

name, description

name	description
hacktoberfest-perks	Claim MLH/Hacktoberfest perks via raw-HTTP Inertia OAuth.

Hacktoberfest / MLH Developer Perks — Raw Claim Pipeline

Trigger

User asks to claim MLH/Hacktoberfest perks (Backboard, Render, .tech, Thinking Machines, ElevenLabs, etc.).

Procedure

0. Accounts and Bank

• Accounts live in C:/Users/User/tmp/mlh_farm_accounts.jsonl (one JSON object per line).
• MLH sessions in C:/Users/User/tmp/hf_mlh_sessions.json: {email: {cookies, ...}}.
• Claim bank (resumable JSONL): C:/Users/User/tmp/hf_claim_bank.jsonl.
• HF tokens cache: C:/Users/User/tmp/hf_hf_tokens.json ({email: {accessToken, refreshToken, user, ...}}).

1. Reauth (when mlh_token is missing or stale)

Script: C:/Users/User/tmp/hf_reauth2.py.

• POST https://www.mlh.com/signin with email + Turnstile token.
• Turnstile sitekey 0x4AAAAAAARi-8xgLgfKOXIb — MLH siteverify rejects plain sidecar tokens; use real_page=true (Camoufox) or 2captcha fallback.
• Parse otpId from response (ULID-like, regex [A-Za-z0-9_\-]+ — NOT numeric-only).
• POST https://www.mlh.com/signin/<otpId>/otp with 6-digit code from IMAP.
• OTP code regex in email body: Login Code is\s*(\d{6}).
• Before OTP POST, re-GET the OTP page to refresh X-Inertia-Version — stale version → 409.
• Save session cookies (especially mlh_token) to hf_mlh_sessions.json.

2. OAuth (raw HTTP, no browser)

Script: C:/Users/User/tmp/hf_raw_claim.py.

The full flow against https://hacktoberfest-api.mlh.com (API) and https://www.mlh.com (Laravel/Inertia):

1. Seed only mlh_token into a fresh cookie jar. Stale full session cookies cause 422 transaction-invalid on authorize.
2. GET API/oauth/mlh → Inertia authorize page, parse data-page props:
   • authorizationTransactionId, state, redirectUri, scopesDetail, version.
3. POST https://www.mlh.com/oauth/authorize (Inertia JSON):
   • Headers: X-Inertia: true, X-Requested-With: XMLHttpRequest, X-Inertia-Version, X-XSRF-TOKEN (from cookie jar), Referer.
   • Body: {redirect_uri, response_type: 'code', scope, state, authorization_transaction_id, consented_scopes, auth_token: ''}.
   • 409 + x-inertia-location is a SUCCESS, not an error — Inertia's external-redirect convention. The Location contains the external OAuth code.
   • The header name is lowercase (x-inertia-location) via CF/HTTP2 — always use case-insensitive lookup (hdr() in hf_raw_claim.py).
   • Bare 409 with NO Location = stale X-Inertia-Version — re-GET the authorize page and retry.
4. External code from callback URL: GET API/oauth/mlh/callback?code=<external>&state=<state> (NO auto-redirect) → 302 Location: https://hacktoberfest.com/auth/callback?code=<INTERNAL_64_HEX>.
   • The external code does NOT work for token exchange. Extract the internal 64-hex code from the 302 Location.
5. POST API/auth/token with {code: <internal>}, headers: Content-Type, Origin: https://hacktoberfest.com, Referer: https://hacktoberfest.com/ → {accessToken, refreshToken, user}.

3. Offers and Claim-Links

• GET /api/me/offers (Bearer accessToken, Origin + Referer) → list of sponsor offers.
• Each offer has company.name and is keyed by poolId (some offers have promo: null — challenges without a redeemable pool; skip them).
• POST /api/me/offers/claim-link with {poolId, eventId?} → claimLink (a www.mlh.com/events/… URL).

4. Redeem

• GET claimLink (with MLH session cookies) → Inertia page, parse data-page props:
  • token: the redeem token.
  • redeemUrl: the Inertia POST path (e.g. /events/hacktoberfest-2026/partners/backboard/promo_codes).
  • unmetClaimRequirements: list of blocking requirements (e.g. verified_phone, github_oauth, github_account_age).
  • promoCode: if already claimed.
• If promoCode is absent and unmet is empty → Inertia POST https://www.mlh.com{redeemUrl} with {token}, version header, XSRF → promoCode in response props or via X-Inertia-Location redirect.
• Bank result per sponsor per email.

5. Applying Perks

• Backboard ($5): code is HACKTOBER (universal). Redeem at backboard.io/hackathons — sign up, enter code on Billing page. No credit card.
• Render ($50): portal credits-portal-mmdm.onrender.com/claim/<slug> (slug hacktoberfest-2026-dev-challenge-tie-in). FULLY AUTOMATED via GitHub OAuth per GH account — see §6. One code per GitHub identity, expires Nov 15. Code lifecycle: Claimed in portal → Applied on Render (attached to a Render account) → credit spent.
• .tech domain (1yr free): needs verified_phone + github_oauth + github_account_age.
• Thinking Machines ($10): needs verified_phone + github_oauth.

6. Render Portal Mass Claim (raw HTTP, no browser)

Script: C:/Users/User/tmp/render_claim.py [start [count [workers]]] — bank render_claim_bank.jsonl, codes dump render_codes.txt (code|claimId|gh_login).

Flow per GH account (from pool C:/Users/User/tmp/gh_accounts.json, keys login/email/password/totp):

1. GET PORTAL/auth/login?redirect=%2Fclaim%2F<slug>&intent=claim&slug=<slug> (no-redirect opener) → 302 to github.com/login/oauth/authorize?client_id=Ov23liIdibz7fFGRUEvN&state=… — capture state + client_id, keep portal cookie jar (csrf nonce).
2. gh_http.GHSession(bind=False) → login(login, password, totp) → oauth_code(client_id, state, scope='user:email') (helper handles consent POST and returns the code).
3. GET PORTAL/auth/callback?code=<code>&state=<state> in the SAME portal jar → 302 = session established.
4. GET PORTAL/auth/me?for=claim&slug=<slug> → 200 JSON identity (confirms session).
5. POST PORTAL/api/v1/claim/<slug> body {"attribution":{}} → 200 {data:{status:"claimed",claimId,code:"HTHON-XXXXXX",valueCents:5000}}.

Result semantics:

• HTTP 200 status:"claimed" → personal $50 code.
• HTTP 202 {"data":{"status":"awaiting_codes"}} → NOT a failure: campaign code pool exhausted, request queued for portal-admin issuance ("Request received, watch your email"). Re-poll later; do not burn accounts retrying.
• /api/v1/claims is 401 for regular users (admin-only) — no self-service status endpoint.
• Codes are applied to Render accounts (render.com/register → billing); the claim portal tracks renderAppliedAt separately.

Proven scale: ~11s/account single worker, 3 workers stable from one IP; 411 codes claimed from 672-account pool before code exhaustion.

7. Render Account Signup + Promo Redemption (E2E verified, raw HTTP)

Script: C:/Users/User/tmp/render_reg.py N [start_idx] — GH login → OAuth → Render signup → apply HTHON code → verify $50. Bank render_accounts.jsonl (gh_login, render_user, owner_id, idToken, code, promo status, balance), state render_state.json.

• GraphQL endpoint: https://api.render.com/graphql. Auth = Authorization: Bearer <idToken> (tokens look like rnd_...), plus Origin: https://dashboard.render.com and Referer.
• Prod GitHub App client_id = Iv1.558507eb9b186639 (title "Authorize Render"), redirect_uri https://dashboard.render.com/oauth/github. The bundle embeds THREE client_ids (dev Iv1.0383c45eb880b349, staging Iv1.7cbda7e3eeb22392, prod) selected by env flags — the first match in JS is NOT necessarily prod. Wrong id → 200 page titled Invalid Redirect URI and zero codes. Probe each candidate: GET github.com/login/oauth/authorize?client_id=<id>&state=x with a logged-in GH session and read <title>.
• Code extraction: already-authorized account → 200 page titled OAuth application authorized with meta-refresh url=<redirect>?code=<hex>; fresh account → consent form (authenticity_token) → POST authorize=1 → code in the FULL response body (search all of it — the meta-refresh can sit past the first 3KB). Codes are single-use; a second OAuth round-trip yields a fresh code.
• Mutations: githubSignUp(accessCode) → {idToken, user{id email}, userExists, workspaces[{id name}]}. If userExists and no idToken → get a NEW code → githubSignIn(accessCode).
• Redeem: addPromotionWithOwner(ownerId, promotionCode) where ownerId = workspaces[0].id → returns only status:"ACTIVE" reliably (other fields empty).
• Verify balance separately — the promo mutation response proves nothing: customerInfo(ownerId){promotions{id name details status valueRemaining expirationDate}} → expect valueRemaining: "$50.00", name "Hackathon Participant". (Field AmountRedeemed is capital-A in unbilledInvoiceForOwner.promotionRedemptions.)
• Keep idToken + owner_id in the bank — service/node creation later reuses them without re-auth.
• Scale: ~20-25s/account single worker, pacing 5-12s, stable from one home IP. GraphQL 422 GRAPHQL_VALIDATION_FAILED with a column number = wrong field name; extract exact query/fragment documents from dashboard asset chunks (e.g. SignInOutcome-*.js contains fragment promotionFragment).

Perk Status (tested)

Sponsor	Value	Auto-claimed	Blockers
Backboard	$5	✅	—
Render	$50	✅ §6 claim + §7 auto signup/redeem/verify	one code per GH identity; code pool exhausts (~411)
.tech domain	1 yr free	🔒	verified_phone, github_oauth, github_account_age
Thinking Machines	$10	🔒	verified_phone, github_oauth
ElevenLabs	challenges	⏭️	no promo pool
SpaceXAI	Cursor challenges	⏭️	no promo pool

Key Files

• C:/Users/User/tmp/hf_raw_claim.py — main claim pipeline (stdlib, no browser).
• C:/Users/User/tmp/hf_reauth2.py — MLH OTP reauth (IMAP credentials in code; not for public repo).
• C:/Users/User/tmp/hf_mass_claim.py — legacy browser-based mass claim (for backup/full flow).
• C:/Users/User/tmp/render_claim.py — Render portal mass claim via GH OAuth (§6); rc_accounts.json loader also accepts JSON account lists.
• C:/Users/User/tmp/render_reg.py — Render account mass signup + promo apply + $50 verify (§7); bank render_accounts.jsonl.
• C:/Users/User/tmp/gh_accounts.json — working GH pool (672, login/email/password/totp).
• C:/Users/User/tmp/mlh_farm_accounts.jsonl — account database.
• Public toolkit repo: github.com/gbonnet65923/hf-mlh-toolkit (sanitized, env-var-based).

GHW Phone Verification (tested 2026-10-12, global-hack-week-open-source-90)

• MLH settings API (Laravel, NOT Yii): CSRF = XSRF-TOKEN cookie echoed back as X-XSRF-TOKEN header (URL-decoded), plus meta csrf-token as X-CSRF-Token. XSRF rotates per response: do a fresh GET of the referer page before EVERY mutating request. Seed cookie jar with mlh_token + _mlh_core_session ONLY (never seed XSRF-TOKEN — duplicate domain cookies cause bogus "Your session expired" 422).
• Turnstile token field name is cf-turnstile-response (not token) — wrong name gives 400 Turnstile token is missing. Send both keys to be safe.
• Phone endpoints: POST /api/phone_numbers {phone_number:{number}, cf-turnstile-response} → 201 (auto-sends SMS); POST /api/phone_numbers/<uuid>/reverify (rate-limited: "too many verification codes" right after add); POST /api/phone_numbers/<uuid>/confirm {code, cf-turnstile-response}; DELETE /api/phone_numbers/<uuid> (required before adding another while an unverified one exists). Phone UUID lives in settings page props phoneNumbers (regex from raw HTML: "phoneNumbers":\[(.*?)\]).
• hero-sms (and likely all cheap VoIP SMS services) NEVER receive MLH's Twilio SMS: tested 6 countries (ID/KG/ZA/MA/PH/CO), add 201 + reverify 200 "code sent" every time, zero deliveries in 420s windows. Only real SIM numbers work. Don't burn money retrying VoIP.
• Claim flow after phone verified: GET claim link → Inertia props {token, redeemUrl, unmetClaimRequirements, promoCode} → POST redeemUrl with {token} → promoCode.

Pitfalls

• Inertia x-inertia-location is lowercase via CF/HTTP2 — always case-insensitive header lookup.
• External OAuth code ≠ token-exchange code — must extract internal 64-hex code from api callback 302 Location.
• Seed only mlh_token into fresh CookieJar — stale session cookies → 422 transaction-invalid on authorize.
• Stale X-Inertia-Version → bare 409 with no Location → re-GET the page before POST.
• 409 on Inertia POST is NORMAL when it carries X-Inertia-Location — it's the external redirect, not an error.
• data-page parsing might fail on first candidate — always try all: re.findall(r'data-page="([^"]+)"', h) then re.findall(r'type="application/json">(.*?)</script>', h, re.S) with html.unescape.
• ElevenLabs/SpaceXAI have promo: null — they are challenge-only offers with no poolId; the promo_ids() walker finds nothing, yielding pool_x no_pool in the bank. Expected, not an error.
• GH pool selection for OAuth claims: prototype 1 account from each pool before scaling — some pools (regkit alive_pat) silently 302 authorize → github.com/dashboard with no code (flagged/suspended-for-OAuth identities), while gh_accounts.json pool returns a code via the consent flow. The dashboard-redirect signature = account-level flag, not app-level.
• gh_http.GHSession(bind=True) requires the ZTE proxy interface (192.168.0.4) — WinError 10049 when the modem is off; use bind=False (direct) for GH OAuth flows.
• Edit tools mask regex capture groups: write_file/patch can turn ([a-f0-9]+) into *** (secret-masking false positive) producing invalid syntax — after any patch touching a regex with a capture group, py_compile the file and repair via terminal python str.replace, not another patch.
• Minified bundles may embed dev/staging/prod OAuth client_ids selected by env flags — the first client_id match in JS can be the dev app (symptom: authorize page titled Invalid Redirect URI, or title Authorize <App> Dev); probe each candidate's authorize page title with a logged-in session before mass runs.
• Backticks in python -c inline code break git-bash quoting (unexpected EOF while looking for matching) — write the probe to a .py file and run it instead.

Related

• github.com/gbonnet65923/hf-mlh-toolkit — public toolkit repo.
• MLH sign-in: https://www.mlh.com/signin; OTP path /signin/<otpId>/otp.
• Hacktoberfest API: https://hacktoberfest-api.mlh.com.
• Turnstile sitekey: 0x4AAAAAAARi-8xgLgfKOXIb (reauth only).
• Sidecar: http://127.0.0.1:8877 (real_page=true required for MLH).