# Auth Investigation — Shared Rules

Common rules for `investigate-auth-oauth2` and `investigate-auth-custom`. Each skill's SKILL.md links here instead of restating these blocks. Skill-specific details (GitHub search queries, grant-type/auth-type tables, output schemas) stay in the individual SKILL.md files.

---

## Fetch strategy (in order)

Always try in order; stop when content is found.

1. `WebFetch(auth_docs_url, "Extract every authentication detail — URLs, credential fields, headers, scopes, token behaviour")` — try first
2. `crwl crawl "<url>" -c "wait_until=networkidle,delay_before_return_html=3.0" -o markdown` — if WebFetch returns empty/nav-only (JS-rendered docs)
3. Playwright `browser_navigate` + `browser_evaluate` — last resort (interactive portals)
4. GitHub search via `WebSearch` (`site:github.com` queries) — **always run**, even when a docs fetch succeeded. The queries are skill-specific; see the invoking SKILL.md's Fetch Strategy section.

Failure signal for steps 1–2: fetched markdown has no auth-related field names, only nav links, or body is under 500 chars. Also apply the soft-404 markers from `../fetch-endpoint-parts/references/fetch-strategies.md → Soft-404 detection` — an HTTP 200 whose body says "page not found" is a fetch failure, not a source.

---

## Scope extraction search strategy

Always actively search before concluding no scopes exist. Try all steps in order before setting `scopes: []`:

1. Check the main `auth_docs_url` page for a scopes table or list
2. Search for a dedicated scopes page: `WebSearch("<provider> <auth flavour> scopes list site:<docs_domain>")`
3. Check the GitHub search results from the fetch strategy step for scope references
4. Look for scopes embedded in auth URL / token-creation examples (e.g. `scope=read:users write:users`)

**Extract for each scope:** name, description, required/optional, category, tier restriction.

**Only set `scopes: []` and `scope_strategy: null`** if all 4 steps find nothing — and note the absence in `quirks`.

---

## Credential field properties

For every field the user must provide when connecting (`config_fields` in custom auth, `setup_fields` in OAuth2), capture:

| Property | What to capture |
|----------|----------------|
| `key` | camelCase field name used in Falcon YAML (e.g. `apiKey`, `clientId`, `apiUrl`) |
| `label` | Human label shown in UI |
| `type` | `text` or `password` |
| `required` | true / false |
| `secret` | true for tokens/keys/secrets, false for URLs/IDs |
| `placeholder` | Example value shown in UI — use exactly the format the provider shows, never invent |
| `description` | What it is and how it's used |
| `where_to_find` | Navigation path in the provider UI |

---

## Shared anti-patterns

- ❌ Leave `where_to_find` as null if it can be found anywhere in the docs or GitHub findings
- ❌ Mark `type: "password"` for non-secret fields like `apiUrl` or `accountId`
- ❌ Never infer `placeholder` — use exactly the format the provider shows in examples
- ❌ Skip scope extraction when scopes do exist — run all 4 search-strategy steps first
- ❌ Omit `scopes` / `scope_strategy` keys — always present, `[]` / `null` when not applicable
- ❌ Hardcode a sandbox URL without confirming it from docs — set `null` if uncertain