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

* fix(oauth): let the owner decide what a connected app may do

An OAuth connection was pinned to saddle:read at consent time and could
never be raised. get_tier() returns min(site tier, credential ceiling),
so a site set to "Managing the site" still ran every ChatGPT call at read
and tools/list withheld every write tool — 83 of 160 offered, with the
agent able to draft an SEO title and description and unable to save it.

Three places named saddle:read as a constant. normalize_scope() fell back
to it when the client sent no scope, and ChatGPT sends none: it registers
dynamically and starts the flow without a scope parameter, so that was
the live cause. The 401 challenge advertised it regardless of the site's
level. The consent screen rendered Allow/Deny with no control that could
grant more than was asked for. Reconnecting produced an identical grant.

Now: tier_to_scope()/site_scope() derive the scope from the site's own
level; the challenge advertises it; the authorize endpoint falls back to
it ONLY when the client sent no scope at all, because widening a request
a client actually made is both a spec violation and a safety regression;
the consent screen offers the levels up to the site tier and clamps the
posted choice server-side; and set_grant_scope() plus POST
/oauth-connections/<id> repair a connection that already exists.

The ceiling now takes the lower of the token's scope and its grant's, so
lowering a connection's level lands on the next request instead of
whenever its hour-long access token happens to expire. Raising still
needs the token rewritten, which is the safe direction to be strict in.
$grant was renamed $token_record because it never held a grant, and
mistaking one for the other is exactly what makes this fail quietly.

Also hardens update_settings(), which read JSON params only: a
form-encoded tier passed the enum, passed can_manage, returned 200 and
saved nothing.

Refs #107

* feat(admin): change a connected app's level, and say when one is behind

Connect now carries a level picker per signed-in app, capped at the site
tier, so the connection that shipped at read can be raised without a
reconnect — which would not have helped anyway, since an app that
requests no scope comes back at the same level every time.

Permissions names any connection sitting below the level saved there.
That gap was invisible from the one screen where someone sets the level,
which is how "I set this to Managing the site and my app still can't save
anything" happens.

The apply-bar note said already-connected apps keep the old tool list
"until they reconnect". Wrong for apps that sign in themselves:
reconnecting re-runs consent and re-grants the same level. They need a
refresh, not a reconnect.

Refs #107

* chore: rebuild the admin bundle, refresh the pot, changelog the fix

The pot had gone stale again — it was generated against 1.0.0-rc3 and was
missing most of a release's worth of msgids, not only this change's.

Refs #107

* docs(status): the OAuth read-pin, its two traps, and the live-test question

Refs #107

Author: ifahimreza

STATUS.md

@@ -1,4 +1,19 @@
 ## Last session
+2026-08-17 (**an OAuth connection could be pinned to `read` forever — root-caused, fixed, and the repair path built**) — Fahim's report: Permissions set to "Managing the site", ChatGPT reporting `read` access and **83 of 160** tools, every Waggle write tool missing, and "edit operation fails" on `waggle-update-seo-meta`. Refreshing the connector changed nothing. **It was ours, on both sides.** → [#107](https://github.com/plugpressco/saddle/issues/107) / PR [#108](https://github.com/plugpressco/saddle/pull/108), and waggle [#181](https://github.com/plugpressco/waggle/issues/181) / PR [#182](https://github.com/plugpressco/waggle/pull/182). 594 tests (was 577), 0 lint errors. **Both PRs open, not merged** — over the 400-line ask-first threshold and OAuth code.
+
+**The chain, in order.** `get_tier()` is `min(site tier, credential ceiling)`; site tier was `admin`, ceiling was `read`, so `filter_adapter_tools_list()` dropped every ability above `read` at dispatch. The ceiling was `read` because **three** places named `saddle:read` as a constant, and the live one is the least obvious: `normalize_scope()` fell back to `DEFAULT_SCOPE` when the client sent no scope — and **ChatGPT sends none at all**, it registers via DCR and starts the flow with no `scope` parameter ([confirmed in OpenAI's own developer forum](https://community.openai.com/t/how-are-the-scopes-that-the-chatgpt-connector-requests-when-authorizing-the-mcp-server-determined/1363723)). The 401 challenge advertised `saddle:read` regardless of the site's level, and the consent screen had a branch for "asked for more than the site allows" and none for "asked for less". So every ChatGPT grant landed on read, permanently, and **reconnecting produced an identical grant** — the one remedy the UI suggested was the one that could not work.
+
+**The fix keeps the guardrail it looks like it breaks.** A scope still only ever *lowers* the site tier (pinned by a test). What changed is who proposes it: the consent screen now offers the levels up to `get_site_tier()` and clamps the posted choice server-side, and the authorize endpoint falls back to the site's scope **only when the client sent no scope at all** — an explicit `saddle:read` is still granted exactly that, because widening a request a client actually made is a spec violation and some clients compare the scope they get back. Plus `set_grant_scope()` + `POST /oauth-connections/<id>` + a level picker on Connect, so the connection that already exists is repairable without a reconnect.
+
+**Two traps found inside the fix.** `Saddle_OAuth_Bearer::$grant` never held a grant — it held the access-token record, whose `scope` is frozen for `ACCESS_TTL`. Rewriting only the grant would have made a level change appear to do nothing for an hour, so `set_grant_scope()` rewrites both and the property is now `$token_record`. And `tier_ceiling()` now takes the *lower* of token and grant scope, so lowering a level lands on the next request while raising still needs the token rewritten — strict in the safe direction.
+
+**Waggle's half.** The bundled `seo-write-article` skill told the agent to call `waggle/update-seo-meta` and six more like it. Saddle re-registers Waggle's abilities wrapped, so the only callable name is `saddle/waggle-*` — the agent was looking up tools that were not in its list, and would have failed even at the write tier. The existing test could not have caught it: every bare name is a substring of its wrapped form, so `assertStringContainsString( 'waggle/get-aeo-score' )` passed before and after. There is now one that checks for the bare form directly.
+
+**Also swept:** `update_settings()` read `get_json_params()` only, so a form-encoded `tier` passed the enum, passed `can_manage`, returned 200 and saved nothing — invisible from the dashboard, indistinguishable from "it didn't stick", and this codebase already works around one host that rewrites bodies. The `.pot` was stale against 1.0.0-rc3 again, missing far more than this change.
+
+**Open question for the live test, not a Saddle bug:** OpenAI's [developer-mode docs](https://developers.openai.com/api/docs/guides/developer-mode) say write actions work on every eligible plan with confirmation; several secondary sources and this file's own line below say fully write-capable custom connectors are Business/Enterprise/Edu only. The Connect tab now says so out loud. Settle it on the round-trip and record the answer here.
+
+## Previous session
 2026-08-16 (**the four pillars swept, Mark's ChatGPT bug root-caused and fixed, and every open PR resolved**) — Fahim's ask opened as "context, guardrails, tools and a system must work smoothly", turned into Mark Roach's ChatGPT report mid-session, and ended with "merge now" on the whole open-PR backlog. Eleven PRs merged (#90, #92, #94, #96, #98, #99, #66, #68, #69, #100, #101, #102); #70 closed as already-landed; **zero open PRs**. 575 tests, 0 lint errors.
 
 **Mark's bug is fixed, and it was ours.** His two-client experiment isolated it: Claude Desktop via mcp-remote worked end to end against staging.kesuk.net while ChatGPT completed OAuth and then reported no callable actions. That rules out abilities, tiers, OAuth and the endpoint, leaving the handshake. `Saddle_MCP` violated three Streamable-HTTP MUSTs, and one sits between "connected" and `tools/list`: a notification must be answered **202 with no body**, and Saddle answered `200` with the JSON literal `null`. mcp-remote shrugs; a strict client treats the handshake as unfinished and never asks what tools exist. Also fixed: GET now 405 (was 404), DELETE 405, unsupported `MCP-Protocol-Version` 400, unparseable body 400, and `resources/*`/`prompts/list` answer empty lists instead of Method-not-found. **This was never only Mark** — since `bff1a99` the .org zip has no adapter, so that transport is the only one a .org install will ever have.
@@ -269,7 +284,7 @@ Earlier 2026-07-12 — **Audit-backlog execution (P0–P4)**. Cleared the audit
 - **Delete the v1.1.0 GitHub release + tag (one command):** `gh release delete v1.1.0 --repo plugpressco/saddle --cleanup-tag --yes && git tag -d v1.1.0`. Still outstanding, and #69 tried to reintroduce 1.1.0 this session — reverted in four places, including a `Stable tag` that was not a conflict and would have shipped silently.
 - **Run `php scripts/revendor-wp-mcp.php --check` before any release.** New pre-release guard: it exits non-zero if the vendored library was refreshed without re-applying Saddle's text domain.
 - **SUBMIT to WordPress.org.** Everything code-side is done and this session removed one of the reviewer-facing surfaces (#86). Fahim's three steps are in `WPORG-SUBMISSION.md`. Rebuild first: `npm run build && npx grunt build` — never `grunt release`, it bumps the version.
-- **Live ChatGPT round-trip on plugpress.co** — still the real gate for the OAuth work, and now also the confirmation that the handshake fix holds against the client that exposed it.
+- **Live ChatGPT round-trip on plugpress.co** — still the real gate for the OAuth work, and now carrying three questions at once: the handshake fix against the client that exposed it, [#108](https://github.com/plugpressco/saddle/pull/108)'s level picker (set the existing connection to "Managing the site" on Connect, refresh the connector, expect ~160 tools and `saddle-waggle-update-seo-meta` present), and the plan question — if the write tools are *listed* and ChatGPT still declines to call them, that is the Business/Enterprise/Edu gate, not us. Record the answer in this file either way.
 - **CI PHPUnit still red on GitHub Actions** (no WP core in the runner). Worth its own PR so future PRs get a real green; "green" currently means someone ran the suite locally and said so.
 
 ## Blockers / open questions

admin/build/index.asset.php

@@ -1 +1 @@
-<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-element', 'wp-hooks', 'wp-i18n'), 'version' => 'c85823a67cb3c40b8700');
+<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-element', 'wp-hooks', 'wp-i18n'), 'version' => '410d31640c83864208ef');

admin/build/index.js

@@ -642,6 +642,7 @@ export default function App() {
 										onConnect={ openWizard }
 										onClientsChanged={ refreshClients }
 										onClientRemoved={ removeClient }
+										siteTier={ tier }
 									/>
 								) }
 								{ tab === 'integrations' && (

admin/src/App.jsx

@@ -22,11 +22,12 @@ import {
 	Card,
 	CardContent,
 	HelpTip,
+	NativeSelect,
 	useConfirm,
 	toast,
 } from '@plugpress/ui';
 import { __, sprintf } from '@wordpress/i18n';
-import { saddleData, api } from '../api';
+import { saddleData, api, LEVELS, tierUnlocks } from '../api';
 import ConnectionHealth from './ConnectionHealth';
 import McpDiagnostics from './McpDiagnostics';
 import SetupGuideDrawer from './SetupGuideDrawer';
@@ -60,12 +61,16 @@ const isStaleNeverUsed = ( c ) =>
 	c.created &&
 	Date.now() / 1000 - c.created > NEVER_USED_STALE_SECONDS;
 
+const levelTitle = ( key ) =>
+	( LEVELS.find( ( l ) => l.key === key ) || {} ).title || key;
+
 export default function Apps( {
 	clients,
 	loading,
 	onConnect,
 	onClientsChanged,
 	onClientRemoved,
+	siteTier,
 } ) {
 	const confirm = useConfirm();
 	const [ showAdvanced, setShowAdvanced ] = useState( false );
@@ -120,6 +125,44 @@ export default function Apps( {
 			} );
 	};
 
+	// Apps that sign in themselves are granted a level once, at the consent
+	// screen, and used to be stuck with it — an app that requests no scope
+	// (ChatGPT does not request one) landed on read and no screen anywhere could
+	// raise it. This is that screen.
+	const changeOauthLevel = ( c, level ) => {
+		if ( level === c.level ) {
+			return;
+		}
+
+		// Optimistic, then reconcile — the same pattern revoke uses above.
+		setOauthConnections( ( list ) =>
+			list.map( ( x ) => ( x.id === c.id ? { ...x, level } : x ) )
+		);
+
+		api( `oauth-connections/${ c.id }`, {
+			method: 'POST',
+			data: { level },
+		} )
+			.then( () => {
+				toast.success(
+					sprintf(
+						/* translators: 1: the app name, 2: its new access level. */
+						__(
+							'“%1$s” is now set to “%2$s”. Refresh or reopen the app to pick up its new tools — apps don’t notice on their own.',
+							'saddle'
+						),
+						c.name,
+						levelTitle( level )
+					)
+				);
+				refreshOauth();
+			} )
+			.catch( ( e ) => {
+				toast.error( e.message );
+				refreshOauth();
+			} );
+	};
+
 	const askRotate = async ( c ) => {
 		const ok = await confirm( {
 			title: sprintf(
@@ -447,15 +490,56 @@ export default function Apps( {
 														{ c.name }
 													</>
 												}
-												description={ sprintf(
-													/* translators: 1: access level, 2: WordPress username. */
-													__(
-														'%1$s access, acting as %2$s',
-														'saddle'
-													),
-													c.level,
-													c.user_login
-												) }
+												description={
+													<>
+														<NativeSelect
+															value={ c.level }
+															aria-label={ sprintf(
+																/* translators: %s: the app name. */
+																__(
+																	'Access level for %s',
+																	'saddle'
+																),
+																c.name
+															) }
+															onChange={ ( e ) =>
+																changeOauthLevel(
+																	c,
+																	e.target
+																		.value
+																)
+															}
+														>
+															{ LEVELS.filter(
+																( l ) =>
+																	tierUnlocks(
+																		siteTier ||
+																			c.level,
+																		l.key
+																	)
+															).map( ( l ) => (
+																<option
+																	key={
+																		l.key
+																	}
+																	value={
+																		l.key
+																	}
+																>
+																	{ l.title }
+																</option>
+															) ) }
+														</NativeSelect>{ ' ' }
+														{ sprintf(
+															/* translators: %s: WordPress username. */
+															__(
+																'acting as %s',
+																'saddle'
+															),
+															c.user_login
+														) }
+													</>
+												}
 												actions={
 													<>
 														<Badge

admin/src/components/ConnectedClients.jsx

@@ -5,11 +5,12 @@
  * 18 tools lives behind a disclosure for anyone who wants to verify exactly
  * what's included — invisible for everyone else. Nothing saves until you apply.
  */
-import { useState, useMemo } from '@wordpress/element';
+import { useState, useMemo, useEffect } from '@wordpress/element';
 import {
 	CardRadioGroup,
 	Collapsible,
 	ApplyBar,
+	Notice,
 	toast,
 	PageHeader,
 	Tooltip,
@@ -60,6 +61,25 @@ export default function Permissions( {
 		savedDisabledSet( caps )
 	);
 
+	// Apps that signed in themselves carry a level of their own, granted once at
+	// the consent screen, and it can sit below the site's. From this screen that
+	// gap is invisible — which is exactly how "I set this to Managing the site
+	// and my app still can't save anything" happens. Name the app here instead of
+	// leaving it to be discovered as a string of refusals.
+	const [ underLevelled, setUnderLevelled ] = useState( [] );
+
+	useEffect( () => {
+		api( 'oauth-connections' )
+			.then( ( res ) =>
+				setUnderLevelled(
+					( res || [] ).filter(
+						( c ) => ! tierUnlocks( c.level, savedTier )
+					)
+				)
+			)
+			.catch( () => setUnderLevelled( [] ) );
+	}, [ savedTier ] );
+
 	// Free text filter across a tool's name/id/description. Empty matches all.
 	const q = query.trim().toLowerCase();
 	const matchesQuery = ( c ) =>
@@ -211,6 +231,31 @@ export default function Permissions( {
 				} ) ) }
 			/>
 
+			{ underLevelled.length > 0 && (
+				<Notice tone="warning">
+					{ sprintf(
+						/* translators: 1: comma-separated app names, 2: the level each app is stuck at, 3: the site's level. */
+						_n(
+							'%1$s is connected at “%2$s”, so it is not offered the tools this “%3$s” level unlocks. Change it on the Connect tab — apps that sign in themselves keep the level they were approved with.',
+							'%1$s are connected at “%2$s” or lower, so they are not offered the tools this “%3$s” level unlocks. Change them on the Connect tab — apps that sign in themselves keep the level they were approved with.',
+							underLevelled.length,
+							'saddle'
+						),
+						underLevelled.map( ( c ) => c.name ).join( ', ' ),
+						(
+							LEVELS.find(
+								( l ) => l.key === underLevelled[ 0 ].level
+							) || {}
+						).title || underLevelled[ 0 ].level,
+						(
+							LEVELS.find(
+								( l ) => l.key === levelKey( savedTier )
+							) || {}
+						).title || savedTier
+					) }
+				</Notice>
+			) }
+
 			<Collapsible
 				className="saddle-perm__all"
 				open={ showAll }
@@ -416,11 +461,15 @@ export default function Permissions( {
 								: null,
 							// Most AI apps read the tool list once, when they
 							// connect. Saving a change they can't see until
-							// they reconnect is the kind of thing that reads
-							// as "it didn't work".
+							// they look again is the kind of thing that reads
+							// as "it didn't work". "Reconnect" was the old
+							// wording and was wrong for apps that sign in
+							// themselves — reconnecting one re-runs consent and
+							// re-grants whatever level it had, which is not
+							// what this change did.
 							dirty || abilitiesDirty
 								? __(
-										'Already-connected apps keep the old tool list until they reconnect.',
+										'Already-connected apps keep the old tool list until you refresh or reopen them.',
 										'saddle'
 								  )
 								: null,

admin/src/components/Permissions.jsx

@@ -51,8 +51,13 @@ export const APPS = [
 			'In ChatGPT on the web: turn on Developer mode (Settings → Apps & Connectors → Advanced settings), then create a connector. Paste the address, choose OAuth, and leave the client ID and secret blank. ChatGPT sends you here to approve it — the connector then works in the desktop app too.',
 			'saddle'
 		),
+		// Worth saying on the screen rather than in a support email: OpenAI has
+		// gated write-capable custom connectors to Business, Enterprise and Edu
+		// workspaces at various points, and on a personal plan ChatGPT can end up
+		// offered every tool and still decline to use the ones that change
+		// anything. That looks identical to a Saddle permission problem.
 		next: __(
-			'Enable the connector in a ChatGPT chat and ask it about your site.',
+			'Enable the connector in a ChatGPT chat and ask it about your site. If it can read but refuses to change anything, check your ChatGPT plan — write-capable custom connectors have been limited to Business, Enterprise and Edu workspaces.',
 			'saddle'
 		),
 	},