alirezarezvani/claude-skills / engineering/skills/mcp-oauth-triage
mcp-oauth-triage
FlaggedUse when an MCP connector that used to authenticate now fails (tool calls 401 after a good token exchange, breaks after refresh, returns another account's data), before changing code. Classifies the fault with oauth_triage.py.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 3.8 KB |
| SKILL.md | skill md | 14.2 KB |
| assets/fixtures/binding_record.json | config | 220 B |
| assets/fixtures/clean_events.jsonl | other | 174 B |
| assets/fixtures/clean_record.json | config | 236 B |
| assets/fixtures/envelope_record.json | config | 179 B |
| assets/fixtures/expiry_record.json | config | 123 B |
| assets/fixtures/negative_cache_events.jsonl | other | 139 B |
| assets/fixtures/negative_cache_record.json | config | 128 B |
| assets/fixtures/rotation_events.jsonl | other | 300 B |
| assets/fixtures/rotation_record.json | config | 109 B |
| examples/rotation-clobber-walkthrough.md | markdown | 4.8 KB |
| expected_outputs/verdicts.json | config | 1.3 KB |
| references/failure-classes.md | markdown | 7.1 KB |
| references/verification-recipes.md | markdown | 3.8 KB |
| scripts/oauth_triage.py | script | 19.8 KB |
| scripts/run_fixtures.py | script | 5.2 KB |
references/failure-classes.md
View on GitHub# Failure Classes: Decision Table and Log Signatures
Companion to `SKILL.md`. Use this file when the classifier returns a class you need to argue for, or
when it returns `none` against a live symptom and you have to decide which artifact is missing.
## The single question that separates the five classes
Ask: **did the token exchange succeed?**
| Answer | Then ask | Class |
|---|---|---|
| Exchange failed | Was the failure transient (5xx, timeout) or permanent (400, invalid_grant)? | Transient is not a class, retry with backoff. Permanent is class D or a registration fault |
| Exchange succeeded | Does the stored record carry the token the exchange returned? | No: class A. Yes: next row |
| Stored correctly | Does the epoch the record claims match the provider's view? | No: class B. Yes: next row |
| Expiry agrees | Did a second refresher write between the exchange and the store? | Yes: class C. No: next row |
| No clobber | Does the failing surface accept this token from another client? | Yes: class D. No: next row |
| Surface rejects it there too | Does an auth marker survive a successful login? | Yes: class E |
Transient failures are deliberately not a class. They matter only because a retry loop around a
transient failure creates class C, which is permanent. That is the most common way a provider blip
becomes a multi-day outage.
## Class A: Envelope mismatch
**Log signature**
```
exchange 200 {"tokens": {"access_token": "..."}}
store 200 wrote keys: ["tokens"]
load 200 keys present: false
call 401 missing access_token
```
The store and the reader disagree about depth. The token exists, the reader cannot see it, and every
health check that reads the file directly reports success.
**Second variant:** the writer stores flat keys and a newer reader was written against a nested schema.
Same symptom, opposite direction, and the fix belongs in the reader, not the writer.
**Third variant worth knowing:** the writer serialises a dataclass whose fields are snake_case while
the reader deserialises a model with camelCase aliases and no fallback. The record looks correct to a
human and empty to the parser.
**Worked example.** A connector worked for three months and broke on a dependency upgrade that changed
the serialiser. The stored file still contained a valid token. The only change was a wrapper key. The
correct response was to normalise the write path and delete the old reader in the same commit, not to
teach the reader both shapes.
## Class B: Expiry semantics
**Log signature**
```
exchange 200 expires_in: 3599.999
store 200 expires_at: 1793113293.123
load 200 expires_at: 1793113293 (truncated)
call 401 at t+3599.5
```
Or, for the sentinel variant:
```
store 200 expires_at: 0
load 200 treating expires_at 0 as no expiry
call 401 immediately after the next provider-side rotation
```
The dangerous variant is the falsy sentinel, because `if not expires_at: skip refresh` reads as
defensive code and is wrong. Zero means "expired at the epoch", never "unknown" and never "forever".
**Clock variant.** Two hosts, one skewed forward by minutes, sharing a credential store. The skewed host
writes an expiry in its own future, the honest host reads it as already past and refreshes constantly,
which then triggers class C.
**Confirmation arithmetic.** First failure timestamp minus issuance timestamp, compared with the token
lifetime the provider advertises. If those agree to within clock skew, the class is B. If the failure
arrives much earlier, keep looking.
## Class C: Rotation clobber
**Log signature**
```
exchange 200 refresh_token -> A
exchange 200 refresh_token -> B (same credential, 40ms later)
store 200 refresh_token: A (losing writer)
refresh 400 invalid_grant
refresh 400 invalid_grant
```
Providers that rotate refresh tokens invalidate the previous value on every exchange. Two callers, one
store, and the loser's write decides which token survives. The result is a credential that is dead on
both sides while each component believes it did the right thing.
**Where it comes from.** Startup warm-up plus the first real request; wake-from-sleep plus a scheduled
refresh; a retry decorator around the exchange without idempotence; a tool-call fan-out where several
handlers notice the same expiry at once.
**The mitigation that works.** One refresher per credential, a lock held across both the exchange and
the store write, and every other caller waiting on that result. A refresh that completes without
writing, or a write that happens outside the lock, reintroduces the class.
**The mitigation that does not work.** Comparing token strings before writing. It closes the window only
if the compare and the write are atomic, which they usually are not.
## Class D: Binding fault
**Log signature**
```
exchange 200 aud: https://api.other.example.com
call 401 {"error": "invalid_token", "error_description": "audience mismatch"}
```
Binding faults fail one surface while another accepts the same token. That is the discriminator: a
storage or expiry fault is indifferent to which endpoint you call.
**Sub-classes**
| Sub-class | Discriminator | Fix |
|---|---|---|
| Audience mismatch | token `aud` does not cover the failing surface's protected-resource metadata | request the advertised resource |
| Issuer mismatch | token `iss` names a different environment or tenant | point the client at the issuer that matches the surface |
| Scope under-grant | 403 with `insufficient_scope` while other calls succeed | request the scope the failing tool needs, at consent time |
| Account collision | data belongs to another account, no error at all | key credentials on a stable account id, never on email or display name |
Account collision is the one that produces no error and therefore no incident. It only surfaces when
someone notices a record that should not be there.
## Class E: Poisoned negative cache
**Log signature**
```
helper 502 preflight failed
store 200 needs_auth: true
login 200 user completed consent
call 401 connector disabled: needs auth
call 401 connector disabled: needs auth
```
A negative result was cached at a scope broader than the thing that failed. Fixing the cause does not
clear the effect, so re-authenticating appears to work and changes nothing visible.
**Where the marker usually lives.** A user-level settings file, a workspace-level cache, an
organization policy record, a keychain item separate from the credential, or a row in a database that
outlives the process.
**Confirmation that costs nothing.** Clear only the marker, leave credentials untouched, retry. Recovery
proves the class without a single new login. If clearing the marker restores service and the next
transient failure re-poisons it, the class is confirmed twice over.
## Reporting a verdict
Lead with three lines and stop:
1. Class, with confidence.
2. The one artifact or probe that confirmed it.
3. The single next action.
Mechanism, history, and the alternative classes you ruled out belong in an appendix that most readers
will never open. A report that opens with a narrative of the investigation invites a second round of
questions; a report that opens with a class invites a fix.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |