>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588763. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The migrate-site skill now has API-first paths for many operations that used to be browser-only &mdash; menu management, site settings, content types, page templates &mdash; gated by OAuth scopes (<code>menu:administer</code>, <code>site_settings:administer</code>, <code>content_type:administer</code>, etc.). Those paths only work if the OAuth client on the user's Acquia Source instance has the required scopes configured AND the server has corresponding API endpoints.</p> <p>Without a preflight check, the first failure surfaces deep inside a phase: a 403 on <code>/jsonapi/menu_link_content/menu_link_content</code> during Phase 6, or a silent empty response when <code>content_type:administer</code> is missing. Debugging a "mysterious API failure" takes 5&ndash;10 minutes per occurrence.</p> <p>Worse: an empirical probe revealed that several scopes mint valid tokens but have NO corresponding API endpoints on the current Acquia Source release. <code>menu:administer</code> issues a token (HTTP 200) but <code>POST /api/menu_link_content/menu_link_content</code> returns 404. An agent calling this path would burn turns debugging an endpoint that simply doesn't exist. A preflight that distinguishes "token issued + endpoint confirmed" from "token issued + endpoint missing" prevents this entire class of failure.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Configure an OAuth client on Acquia Source with various scopes including <code>menu:administer</code>.</li> <li>Run the migrate-site skill end-to-end.</li> <li>Observe Phase 6: agents request a token with <code>menu:administer</code> (succeeds), POST to <code>/api/menu_link_content/menu_link_content</code> (404), then loop through retry/diagnostic logic for an endpoint that doesn't exist on this release.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Define a scope manifest</strong> listing every scope to verify with the endpoint to probe:</p> <pre>const SCOPES_TO_VERIFY = [ { scope: 'canvas:js_component', probe: { method: 'GET', path: '/canvas/api/v0/config/js_component' } }, { scope: 'canvas:asset_library', probe: { method: 'GET', path: '/canvas/api/v0/config/asset_library' } }, { scope: 'canvas:page:read', probe: { method: 'GET', path: '/api/page' } }, { scope: 'canvas:brand_kit', probe: { method: 'GET', path: '/canvas/api/v0/config/brand_kit' } }, { scope: 'menu:administer', probe: { method: 'POST', path: '/api/menu_link_content/menu_link_content' } }, { scope: 'site_settings:administer', probe: { method: 'GET', path: '/api/config/system.site' } }, { scope: 'content_type:administer', probe: { method: 'GET', path: '/api/node_type/node_type' } }, { scope: 'taxonomy:administer', probe: { method: 'GET', path: '/api/taxonomy_vocabulary/taxonomy_vocabulary' } }, { scope: 'page_template:administer', probe: { method: 'GET', path: '/api/page_template' } }, ];</pre><p><strong>Step 2 &mdash; Write <code>scripts/verify-scopes.mjs</code></strong> in two phases:</p> <ul> <li><strong>Phase A &mdash; Token issuance:</strong> for each scope, request a token. Log <code>token_issued: true|false</code>.</li> <li><strong>Phase B &mdash; Endpoint probe:</strong> for each scope that issued a token, probe its endpoint. Distinguish three states: <code>confirmed</code> (200/201/204), <code>issuance-only</code> (token works but endpoint 404/405), <code>denied</code> (token issued but 403 on endpoint).</li> </ul> <p>Output: <code>docs/migration/workflow/scope-availability.json</code> with one entry per scope showing its state and the probed endpoint.</p> <p><strong>Step 3 &mdash; Add Phase 0.5 to <code>SKILL.md</code></strong>:</p> <pre>PHASE 0.5 &mdash; Scope verification preflight Run: node scripts/verify-scopes.mjs Read: docs/migration/workflow/scope-availability.json For each phase, check scope-availability.json before dispatching agents: - Phase 6 (menus): if menu:administer is "confirmed" &rarr; API-first; else browser-fallback - Phase 6 (site config): if site_settings:administer "confirmed" &rarr; API-first - Phase 1.5: if content_type:administer + taxonomy:administer "confirmed" &rarr; API-first - Phase 4.5: if page_template:administer "confirmed" &rarr; API path; else browser-session DO NOT abort the migration if scopes are denied. Log which paths are available and continue.</pre><p><strong>Step 4 &mdash; Persist verified endpoint URLs to <code>gotchas.md</code></strong> (1-07) so the verified map survives compaction.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Productionize <code>RESEARCH-2026-04-28/scripts/scope-probe.sh</code> as <code>scripts/verify-scopes.mjs</code> (or extend existing <code>verify-browser-session.mjs</code>).</li> <li>Define the scope manifest including all canvas_oauth and Acquia Source-specific scopes used by the skill.</li> <li>Add the Phase 0.5 block to <code>SKILL.md</code>.</li> <li>Wire downstream agents (menu-builder, site-configurator, content-modeler, page-template-builder) to read <code>scope-availability.json</code> before choosing API-first vs. browser-fallback.</li> <li>Verify on the test instance: known-confirmed scopes show <code>confirmed</code>; known-issuance-only scopes show <code>issuance-only</code> with a clear warning.</li> <li>Append confirmed endpoints to <code>gotchas.md</code> after the script runs.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>The script consumes (does not introduce):</p> <ul> <li><code>POST /oauth/token</code> with various <code>scope=</code> values for token issuance probe.</li> <li><code>GET</code>/<code>POST</code> on the candidate endpoint per scope for endpoint probe.</li> </ul> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact: <code>docs/migration/workflow/scope-availability.json</code>. New section in <code>gotchas.md</code>: "OAuth Scopes &mdash; verified endpoint map" populated by this preflight.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-1-Foundations/08-NEW-11-verify-scopes-preflight.md</code> (id: NEW-11)</li> <li>Scope reference: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code> (full table; open questions Q1, Q3, Q4)</li> <li>Empirical probe results: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect;&sect; 2-7 (which scopes mint tokens but have no endpoints)</li> <li>Prototype script: <code>RESEARCH-2026-04-28/scripts/scope-probe.sh</code> (Phase B implementation to productionize)</li> <li>Downstream consumers: Sprint 2 issues 2-05 (NEW-7), 2-06 (NEW-8); Sprint 8 issue 8-07 (NEW-9)</li> <li>Compaction-persistence target: 1-07 (gotchas.md)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Empirical probe found no rate limit on <code>/oauth/token</code> (12 token requests in ~9 seconds, all 200, no <code>X-RateLimit-*</code> headers). Individual-token-per-scope design is fine. If a future tighter limit is observed, fall back to a single multi-scope token with JWT scope-claim parsing.</li> <li>Does Acquia Source provide a dedicated scope-listing endpoint (<code>/jsonapi/oauth2_scope/oauth2_scope</code>)? If yes, use it as a faster alternative to per-scope token probing.</li> <li>Should scope verification cache results per migration run, or re-probe every session? Caching is faster but stale-after-config-change.</li> <li>Drupal #3584714 install-order gotcha: does it apply to scopes other than <code>canvas:media:image:create</code>? If yes, the preflight should distinguish <code>not_registered</code> ("update the Drupal module") from <code>denied</code> ("configure the OAuth client").</li> </ul>