Extract GraphiQL client-credentials token provider

[gonzaloriestra]

WHY are these changes introduced?

The app dev GraphiQL auth code should stay isolated from process startup details.

WHAT is this pull request doing?

Extracts the app dev GraphiQL client-credentials token provider into its own module and covers it with focused tests.

How to test your changes?

Open GraphiQL from shopify app dev

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[gonzaloriestra]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Extract GraphiQL client-credentials token provider #7381 👈 (View in Graphite)
• Make GraphiQL server auth-agnostic #7380 : 1 other dependent PR (#7382 )
• Extract GraphiQL server to @shopify/cli-kit #7379
• main

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

[github-actions]

This PR seems inactive. If it's still relevant, please add a comment saying so. Otherwise, take no action.
→ If there's no activity within a week, then a bot will automatically close this.
Thanks for helping to improve Shopify's dev tooling and experience.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/graphql.d.ts

/**
 * Returns true if the GraphQL document contains a mutation operation that
 * would actually be executed for the given (optional) operation name.
 *
 * - When `operationName` is provided, only the matching operation is checked.
 * - When `operationName` is omitted and the document has a single operation,
 * that operation is checked.
 * - When the document has multiple operations and no operation name is given,
 * any mutation in the document is treated as a mutation request (the GraphQL
 * server would reject the ambiguous request anyway).
 *
 * Returns false for queries, subscriptions, fragment-only documents, and any
 * input that fails to parse as GraphQL.
 *
 * @param query - The GraphQL document to inspect.
 * @param operationName - Optional name of the operation to check; when set, only that operation is considered.
 * @returns True if the relevant operation is a mutation; false otherwise.
 */
export declare function containsMutation(query: string, operationName?: string): boolean;

packages/cli-kit/dist/public/node/graphiql/server.d.ts

import { Server } from 'http';
import { Writable } from 'stream';
/**
 * Derives a deterministic GraphiQL authentication key from the app's API secret and store FQDN.
 * The key is stable across dev server restarts (so browser tabs survive restarts)
 * but is not guessable without the app secret.
 *
 * @param apiSecret - The Partners app's client secret used as the HMAC key.
 * @param storeFqdn - The myshopify.com domain the GraphiQL session targets.
 * @returns A 64-character hex string suitable for use as the `?key=` query param.
 */
export declare function deriveGraphiQLKey(apiSecret: string, storeFqdn: string): string;
/**
 * Resolves the GraphiQL authentication key. Uses the explicitly provided key
 * if non-empty, otherwise derives one deterministically from the app secret.
 *
 * @param providedKey - An explicit key supplied by the caller; takes precedence when non-empty.
 * @param apiSecret - The Partners app's client secret, used to derive a stable key as a fallback.
 * @param storeFqdn - The myshopify.com domain the GraphiQL session targets.
 * @returns The resolved key.
 */
export declare function resolveGraphiQLKey(providedKey: string | undefined, apiSecret: string, storeFqdn: string): string;
/**
 * Pluggable strategy for obtaining and refreshing the Admin API access token
 * that the GraphiQL proxy injects into every request.
 *
 * - `getToken` may return a cached token; the proxy calls it for every request.
 * - `refreshToken` (optional) is invoked when the upstream Admin API returns 401.
 * When omitted, the proxy falls back to calling `getToken` again on 401.
 *
 * Implementations must throw `TokenRefreshError` (or any thrown error) when the
 * token cannot be obtained; the proxy renders the unauthorized template in that case.
 */
export interface TokenProvider {
    getToken: () => Promise<string>;
    refreshToken?: () => Promise<string>;
}
/**
 * Optional app-specific context, used to render the app pill and scopes note in the
 * GraphiQL header and to drive the deterministic key derivation. Pass when the GraphiQL
 * server is hosted as part of `shopify app dev`; omit for app-less use cases such as
 * `shopify store execute`.
 */
export interface GraphiQLAppContext {
    appName: string;
    appUrl: string;
    apiSecret: string;
}
export interface SetupGraphiQLServerOptions {
    stdout: Writable;
    port: number;
    storeFqdn: string;
    tokenProvider: TokenProvider;
    /**
     * Authentication key required as a `?key=` query string on every request. When omitted:
     * - if `appContext` is provided, derived deterministically from `apiSecret` + `storeFqdn`
     * so browser tabs survive dev server restarts.
     * - otherwise, generated randomly per process.
     */
    key?: string;
    appContext?: GraphiQLAppContext;
    /**
     * When true, the proxy rejects mutation operations with HTTP 400 before forwarding
     * them to the Admin API. Use this to mirror non-interactive safety guarantees in the
     * interactive UI.
     */
    protectMutations?: boolean;
}
/**
 * Starts a local HTTP server that hosts the GraphiQL UI and proxies requests to the
 * Admin API for the configured store. Authentication is delegated to the supplied
 * `tokenProvider`, so the same server can serve both `shopify app dev` and stored-session
 * use cases.
 *
 * @param options - Configuration for the server, including the target store, the
 * pluggable token provider, and the local port to bind to.
 * @returns The underlying Node `http.Server` instance, already listening on `options.port`.
 */
export declare function setupGraphiQLServer(options: SetupGraphiQLServerOptions): Server;

packages/cli-kit/dist/public/node/graphiql/utilities.d.ts

/**
 * Filters request headers to extract only custom headers that are safe to forward.
 * Blocked headers and non-string values are excluded.
 *
 * @param headers - The raw incoming request headers.
 * @returns The subset of headers that are safe to forward to the Admin API.
 */
export declare function filterCustomHeaders(headers: {
    [key: string]: string | string[] | undefined;
}): {
    [key: string]: string;
};

packages/cli-kit/dist/public/node/graphiql/templates/graphiql.d.ts

export declare const defaultQuery: string;
interface GraphiQLTemplateOptions {
    apiVersion: string;
    apiVersions: string[];
    appName?: string;
    appUrl?: string;
    key: string;
    storeFqdn: string;
    protectMutations?: boolean;
}
export declare function graphiqlTemplate({ apiVersion, apiVersions, appName, appUrl, key, storeFqdn, protectMutations, }: GraphiQLTemplateOptions): string;
export {};

packages/cli-kit/dist/public/node/graphiql/templates/unauthorized.d.ts

interface UnauthorizedTemplateOptions {
    hasAppContext: boolean;
}
export declare function unauthorizedTemplate({ hasAppContext }: UnauthorizedTemplateOptions): string;
export {};

Existing type declarations

We found no diffs with existing type declarations

[gonzaloriestra]

Folded into #7380 so the auth-agnostic GraphiQL server and app dev token-provider cleanup review together.