Make store auth scopes additive

[dmerand]

What

Make shopify store auth preserve existing app-install scopes when adding new access.

Before starting OAuth, CLI now resolves the current granted scope set from the store when it can, falls back to locally stored scopes when it can't, and merges the new requested scopes onto that set.

Why

store auth currently behaves like a replace operation.

That means an agent can request a narrower scope set for one task and accidentally remove scopes another agent, tab, or user was already relying on. Using local state alone also leaves us vulnerable to stale scope data when the install has already changed remotely.

How

• reuse stored store auth to read the current app-install scopes from /admin/oauth/access_scopes.json
• refresh the stored session first when needed by reusing the existing store auth loading path
• treat remote scopes as the baseline when available
• fall back to locally stored scopes if the remote lookup fails
• treat that local fallback as non-authoritative so stale cached scopes do not block re-auth
• extract stored session loading/refresh into a shared internal module so store auth does not depend on the Admin GraphQL context module for generic session lifecycle behavior

Considered

• Require fallback local scopes to still be granted: rejected. If the cache is stale and remote scope lookup is unavailable, that can turn a recoverable re-auth into a hard failure.
• Keep shared session loading in admin-graphql-context.ts: rejected. That made an Admin GraphQL module the accidental owner of generic stored-session lifecycle behavior.
• Extract all scope-reconciliation policy into its own module in this PR: deferred. The current refactor fixes the misleading ownership seam without reopening the broader design.

Testing

pnpm run shopify store auth --store <shop.myshopify.com> --scopes read_orders
pnpm run shopify store auth --store <shop.myshopify.com> --scopes read_products
pnpm run shopify store execute --store <shop.myshopify.com> --query 'query { orders(first: 1) { nodes { id } } }'
pnpm run shopify store execute --store <shop.myshopify.com> --query 'query { products(first: 1) { nodes { id } } }'

# terminal A
pnpm run shopify store auth --store <shop.myshopify.com> --scopes read_orders

# terminal B / another checkout
pnpm run shopify store auth --store <shop.myshopify.com> --scopes read_customers

# back on terminal A
pnpm run shopify store auth --store <shop.myshopify.com> --scopes read_products
pnpm run shopify store execute --store <shop.myshopify.com> --query 'query { customers(first: 1) { nodes { id } } }'
pnpm run shopify store execute --store <shop.myshopify.com> --query 'query { products(first: 1) { nodes { id } } }'

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[dmerand]

• Make store auth scopes additive #7172 : 2 dependent PRs (#7184 , #7187 ) 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[Copilot]

Pull request overview

This PR changes shopify store auth to behave additively by preserving existing app-install scopes when requesting additional scopes, preferring remote (store-reported) scopes when available and falling back to locally cached scopes when not.

Changes:

• Added a shared stored-session loader/refresh module and reused it across store services.
• Implemented scope reconciliation for store auth by merging newly requested scopes with existing scopes (remote-first, local fallback).
• Added tests covering remote-scope resolution, fallback behavior, and additive scope requests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
packages/cli/src/cli/services/store/stored-session.ts	New shared helper to load/refresh a stored store app session.
packages/cli/src/cli/services/store/auth.ts	Resolves existing scopes (remote-first), merges requested scopes additively, and adjusts validation/persistence behavior.
packages/cli/src/cli/services/store/auth.test.ts	Adds unit tests for scope resolution and additive auth behavior.
packages/cli/src/cli/services/store/admin-graphql-context.ts	Refactors to use the shared stored-session loader instead of owning refresh logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When tokenResponse.scope is missing, resolveGrantedScopes falls back to its requestedScopes argument. In the non-authoritative fallback path, you pass validationScopes (which excludes cached existing scopes), so a successful auth with a scope-less token response would persist only the newly requested scopes and unintentionally drop previously stored scopes. Consider validating against validationScopes when tokenResponse.scope is present, but falling back to the actual OAuth-requested scopes when it isn’t, so additive behavior is preserved even without a scope field.

Suggested change

	scopes: resolveGrantedScopes(tokenResponse, validationScopes),
	scopes: resolveGrantedScopes(tokenResponse, tokenResponse.scope ? validationScopes : scopes),

[Copilot]

On non-OK responses, the thrown error includes the full response body (HTTP ${status}: ${body || statusText}), which is later surfaced in debug logs during the fallback path. This can produce extremely large debug output (HTML error pages, etc.). Consider truncating/sanitizing the body similarly to the token-refresh path (e.g., first N chars) while still retaining status and a small snippet for troubleshooting.

[ryancbahan]

it'd be nice to split out the data fetching concern and the storage get/set concerns, wdyt?

[dmerand]

I agree, I'm gonna pursue more cleanup upstack. Extracting StoredSession in this PR felt like the right size for this particular move.