oauth-login-debug
Debug live OAuth/OIDC login failures via probes.
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- oauth-login-debug
- description
- Debug live OAuth/OIDC login failures via probes.
02 资源文件 4
- 参考文档references/profile-scoped-release-home.md2.1 KB
- 参考文档references/reverse-proxy-origin-guard.md2.8 KB
- 参考文档references/telegram-id-claim-normalization.md2.0 KB
- 参考文档references/telegram-oidc-quirks.md3.7 KB
03 SKILL.md 正文
OAuth Login Debug
Live login failures (provider error page, state rejected, redirect back to login, origin errors) are protocol-level: fix them with live probes and the actual library source, not by guessing from docs.
Loop
-
Reproduce against the live site first. Capture the exact outgoing authorization request. Headless Playwright with a request listener is the reliable way:
page.on("request", (r) => { if (r.url().includes(PROVIDER_HOST)) log(r.url()); }); // open login page, click the sign-in button, waitForURL(/provider|error/)Log every query param's presence and length (
redirect_uri,scope,state,nonce,code_challenge). The failing param is usually visible by shape, not by name. -
Read the bundled library, not the docs. What the framework actually sends lives in
node_modulesinside the deployed image or local checkout. Auth.js example:@auth/core/lib/actions/signin/authorization-url.js(what goes into the URL),.../callback/oauth/checks.js(create/use/decode of state/pkce/nonce),.../callback/index.jsandoauth/callback.js(callback validation). Grep for the provider config (checks:,issuer,authorization) to find the site's provider file, then trace from there. -
Probe the live provider for the real limit. Providers enforce undocumented constraints. Find them empirically with a curl sweep against the real authorization endpoint, classifying the response body:
for len in 64 128 200 255 256 257 300; do body=$(curl -sS "https://<auth-endpoint>?client_id=$CID&redirect_uri=$URI&response_type=code&scope=openid+profile&state=$(head -c $len /dev/zero | tr '\0' 'a')") printf '%s %s %s\n' "$len" "${#body}" "$(printf '%s' "$body" | head -c 40)" doneError bodies are typically a short distinct page; success is the full login UI. A binary sweep pins the exact boundary. Keep
client_id/redirect_urireal so the probe reaches the same validation. -
Fix at the root. If the framework's payload exceeds a provider limit, reconfigure the framework (drop a check, shorten the payload) — never fork the library. Verify the fix keeps equivalent protection: dropping OIDC
stateis compensated by PKCEcode_verifier(HttpOnly cookie) +nonceclaim verification, which holds when no redirect-proxy flow is used. -
Prove it end-to-end. Run the repo's own browser e2e with its OIDC fixture if one exists (full login included); otherwise script the same Playwright repro against a staging/local stack. Unit tests that pin the provider
checksarray must be updated in the same commit.
Pitfalls
- Deployed revision ≠ repo HEAD. Read the running container's image label/revision (
docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}') and compare withorigin/main. Fixes are not live until the new revision is deployed, and the live bug may already be fixed on main — check branch history before re-fixing. - Auth.js specifics: with
checks: [..., "state", ...]thestateparameter is an encrypted JWE (~430+ chars), far longer than a random nonce. Dropping"state"fromchecksis behaviorally clean:checks.state.createreturns without emitting the param,useCookieshort-circuits on the callback, andoauth4webapi.validateAuthResponsereceivesundefinedand skips state validation. Butcreatethrows iforigindata is passed without the check (redirect-proxy flow) — keep that in mind. Also checkAUTH_URL/trustHost: a missing public origin makes Auth.js emithttp://internal redirect URIs andorigin_forbiddenerrors, which can stack with the provider error. - Provider docs understate limits. Telegram documents
stateas a random string with no length cap; the real cap had to be measured. Trust the probe over the docs for boundary values. - Don't conclude from the unit layer alone.
statewas green in the test suite while production login was broken; only a live repro exposed it.
References
references/telegram-oidc-quirks.md— Telegram OIDC endpoint facts, the measuredstatelimit, and the Auth.js JWE-state fix.
04 同仓库更多 Skills
writing-for-agents
Use for delegate_task, Kanban, and all agent-facing text.
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
vue-best-practices
Use for Vue 3, .vue files, Vue Router, or Pinia. Skip when the repo has no Vue.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
tailwind-v4
Use when writing or reviewing Tailwind CSS v4 classes or migrating v3 syntax.
react-best-practices
Mastra React subset only. Generic React or Next uses vercel-react-best-practices.