fix: an OAuth connection can no longer be pinned to read forever (#107)

[ifahimreza]

Closes #107

What

An app that signs in through Saddle's OAuth screen — ChatGPT is the only client that must — was granted saddle:read once, at consent, and could never be raised. On a site set to Managing the site the connector still ran at read, was offered 83 of 160 tools, and could draft an SEO title and description with no way to save it. Reconnecting produced an identical grant.

You now pick the level on the approval screen, and you can change it afterwards for an app that is already connected.

Why

Saddle_Capabilities::get_tier() returns min(site tier, credential ceiling). The ceiling was read because three separate places named saddle:read as a constant:

1. The live cause — normalize_scope() fell back to DEFAULT_SCOPE when the client sent no scope. ChatGPT sends none: it registers via DCR and starts the flow without a scope parameter at all (OpenAI developer community).
2. Saddle_OAuth_Bearer::challenge() advertised it in WWW-Authenticate regardless of the site's level, so a spec-following client was told to ask for read-only.
3. The consent screen handled "asked for more than the site allows" and had no branch, and no control, for "asked for less".

filter_adapter_tools_list() then dropped every ability above the ceiling at dispatch, which is why the tools vanished rather than failing loudly. Application-Password clients carry no ceiling and were never affected.

How

• tier_to_scope() / site_scope() derive a cumulative scope string from the site's own level. The challenge advertises it.
• normalize_scope( $requested, $fallback ) — the authorize endpoint passes site_scope() only when the client sent no scope at all. An explicit saddle:read is still granted exactly saddle:read: widening a request a client actually made is a spec violation, and some clients compare the granted scope against what they asked for. A fallback is re-run through the same intersection so it cannot introduce a scope Saddle does not grant.
• The consent screen renders the levels up to get_site_tier(), preselected at what the client asked for (or the site's level when it asked for nothing), and handle() re-clamps the posted value server-side. The granted level is now recorded in the activity log.
• Saddle_OAuth_Store::set_grant_scope() rewrites the grant and every token bound to it, behind POST /oauth-connections/<id> (manage_options, clamped to the site tier).
• tier_ceiling() now takes the lower of the token's scope and its grant's current one, so lowering a level lands on the next request rather than up to ACCESS_TTL later. Raising still requires the token rewritten — the safe direction to be strict in.
• Renamed Saddle_OAuth_Bearer::$grant to $token_record. It never held a grant, and mistaking one for the other is precisely what makes this feature fail silently.
• Hardened update_settings(), which read get_json_params() only: a form-encoded tier passed the route enum, passed can_manage, returned 200 and saved nothing.

Guardrails — unchanged

• Fresh installs still default to read.
• A scope still only ever lowers the site tier, never raises it. Pinned by test_a_scope_still_cannot_exceed_the_site_tier.
• Every widening still takes an explicit administrator click on the consent screen; there is still no "don't ask again".
• PKCE S256-only, exact-string redirect matching, refresh rotation and replay revocation are untouched.

Testing

• composer test — 594 tests, 1986 assertions, green (577 before; 17 new in tests/oauth-scope-test.php, which pins the reported symptom first, then the fix, then its limits)
• composer lint — clean; new files scoped-linted explicitly
• npm run lint:js — clean; npm run build run, committed bundle matches
• .pot regenerated (it was stale against 1.0.0-rc3, missing far more than this change)
• Live round-trip on the affected site — the real gate, not yet run

Note for the live test

If the write tools are now listed and ChatGPT still declines to call them, that is client-side, not Saddle. OpenAI's developer-mode docs say write actions work on every eligible plan with confirmation, while several secondary sources and our own STATUS.md:266 say fully write-capable custom connectors are limited to Business/Enterprise/Edu. The Connect tab now says so. Worth settling in STATUS.md once we have a definitive answer from the live test.

Version

No version bump. The plugin header, SADDLE_VERSION, readme.txt stable tag and package.json are untouched; changelog entries went under the existing unreleased = 1.0.0 =.

Ask before merge

Over the ~400-line threshold (~570 lines of source, plus the pot regeneration and the rebuilt bundle), and it touches OAuth. Yours to merge.