Seed GraphQL auth methods from the registry's declared credential

The registry now says how a GraphQL surface authenticates — credential kind, header pattern, and a note — because a GraphQL endpoint has no spec document to say it itself. Adding Linear from the picker seeds the auth-method editor with 'Authorization: {api_key}' (no Bearer prefix, which is the whole point) and shows the note; the same facts ride along when a preset owns the add flow. The detected-method footer says 'Declared by this API' rather than 'Read from the spec', which was untrue for spec-less surfaces.

Rhys Sullivan committed 2 months ago

Commit d3acfe31 parent 325389c9 files · +129 −12Browse files

Unified · Split

9 files

packages/core/sdk/src/client.ts +6 −0
packages/plugins/graphql/src/react/AddGraphqlIntegration.tsx +18 −1
packages/react/src/components/auth-method-list-editor.tsx +5 −2
packages/react/src/lib/auth-placements.test.ts +23 −1
packages/react/src/lib/auth-placements.tsx +16 −0
packages/react/src/lib/integrations-sh-catalog.ts +17 −0
packages/react/src/pages/integration-add.tsx +5 −1
packages/react/src/pages/integration-browse.tsx +25 −5
packages/react/src/routes/integrations.add.$pluginKey.tsx +14 −2

packages/core/sdk/src/client.ts+6−0

     readonly initialUrl?: string;
     readonly initialPreset?: string;
     readonly initialNamespace?: string;
+    /** Registry-declared credential placement for the surface, e.g.
+     *  "Authorization: {api_key}" — the pattern Linear's no-Bearer personal
+     *  keys need. Plugins whose surfaces can't self-describe auth (GraphQL)
+     *  seed their auth-method editor from it. */
+    readonly initialAuthHeader?: string;
+    readonly initialAuthNote?: string;
   }>;
   /** Legacy full-page edit surface. No host renders this anymore — plugin
    *  configuration lives in the integration Edit sheet via `editSheet`. */

packages/plugins/graphql/src/react/AddGraphqlIntegration.tsx+18−1

   type AuthMethodRow,
   type AuthMethodSeed,
 } from "@executor-js/react/components/auth-method-list-editor";
+import { placementFromHeaderPattern } from "@executor-js/react/lib/auth-placements";
 import { FloatActions } from "@executor-js/react/components/float-actions";
 import {
   addIntegrationErrorMessage,
   onComplete: (slug?: string) => void;
   onCancel: () => void;
   initialUrl?: string;
+  initialAuthHeader?: string;
+  initialAuthNote?: string;
 }) {
   const [endpoint, setEndpoint] = useState(props.initialUrl ?? "");
   const [description, setDescription] = useState("");
   const identity = useIntegrationIdentity({
     fallbackName: integrationDisplayNameFromUrl(endpoint, "GraphQL") ?? "",
   });
-  const authMethodList = useAuthMethodList(NO_SEEDS);
+  // GraphQL has no add-time detection, but the registry can declare the
+  // credential placement ("Authorization: {api_key}" — Linear's no-Bearer
+  // personal keys). A declared placement seeds the method list the same way a
+  // spec's security scheme would.
+  const registrySeeds = useMemo<readonly AuthMethodSeed[]>(() => {
+    const placement = props.initialAuthHeader
+      ? placementFromHeaderPattern(props.initialAuthHeader)
+      : null;
+    return placement ? [{ value: { kind: "apikey", placements: [placement] } }] : NO_SEEDS;
+  }, [props.initialAuthHeader]);
+  const authMethodList = useAuthMethodList(registrySeeds);
   const [adding, setAdding] = useState(false);
   const [addError, setAddError] = useState<string | null>(null);
         footerHint="Nothing here takes your credential. Add the integration first, then connect an account on its page."
       />
+      {props.initialAuthNote ? (
+        <p className="text-xs leading-relaxed text-muted-foreground">{props.initialAuthNote}</p>
+      ) : null}
       {slugAlreadyExists && !adding && <SlugCollisionAlert slug={resolvedSlug} />}
       {addError && <FormErrorAlert message={addError} />}

packages/react/src/components/auth-method-list-editor.tsx+5−2

           from its own page. Saying so is the difference between a confident
           next click and hunting for a field that is not here. */}
       <p className="text-[11px] text-muted-foreground">
+        {/* "Declared by this API", not "read from the spec": GraphQL surfaces
+            have no spec — their methods arrive from the registry record — and
+            the claim that matters is the same either way. */}
         {value.kind === "oauth"
-          ? "Read from the spec. You'll sign in after adding this integration."
+          ? "Declared by this API. You'll sign in after adding this integration."
-          : "Read from the spec. You'll enter your key after adding this integration."}
+          : "Declared by this API. You'll enter your key after adding this integration."}
       </p>
     </div>
   );

packages/react/src/lib/auth-placements.test.ts+23−1

@@ -1,7 +1,7 @@
1	import { describe, expect, it } from "@effect/vitest";	1	import { describe, expect, it } from "@effect/vitest";
2	import type { AuthMethodDescriptor } from "@executor-js/sdk/shared";	2	import type { AuthMethodDescriptor } from "@executor-js/sdk/shared";
3		3
4	import { authMethodsFromDescriptors } from "./auth-placements";	4	import { authMethodsFromDescriptors, placementFromHeaderPattern } from "./auth-placements";
5		5
6	describe("authMethodsFromDescriptors", () => {	6	describe("authMethodsFromDescriptors", () => {
7	it("maps an oauth descriptor and carries discoveryUrl + supportsDynamicRegistration", () => {	7	it("maps an oauth descriptor and carries discoveryUrl + supportsDynamicRegistration", () => {
@@ -101,3 +101,25 @@ describe("authMethodsFromDescriptors", () => { · 93 unmodified lines
101	expect(authMethodsFromDescriptors([])).toEqual([]);	101	expect(authMethodsFromDescriptors([])).toEqual([]);
102	});	102	});
103	});	103	});
		104
		105	describe("placementFromHeaderPattern", () => {
		106	it("keeps a Bearer prefix, space included", () => {
		107	expect(placementFromHeaderPattern("Authorization: Bearer {token}")).toEqual({
		108	carrier: "header",
		109	name: "Authorization",
		110	prefix: "Bearer ",
		111	});
		112	});
		113
		114	it("an empty prefix is meaningful: Linear's keys take no Bearer", () => {
		115	expect(placementFromHeaderPattern("Authorization: {api_key}")).toEqual({
		116	carrier: "header",
		117	name: "Authorization",
		118	prefix: "",
		119	});
		120	});
		121
		122	it("rejects text that is not a header pattern", () => {
		123	expect(placementFromHeaderPattern("just some prose")).toBeNull();
		124	});
		125	});

packages/react/src/lib/auth-placements.tsx+16−0

@@ -40,6 +40,22 @@ export interface Placement { · 39 unmodified lines
40	/** A fresh, empty header placement — the default first row in an editor. */	40	/** A fresh, empty header placement — the default first row in an editor. */
41	export const emptyPlacement = (): Placement => ({ carrier: "header", name: "", prefix: "" });	41	export const emptyPlacement = (): Placement => ({ carrier: "header", name: "", prefix: "" });
42		42
		43	/** Parses a registry header pattern — `"Authorization: Bearer {token}"` — into
		44	* a placement. The literal text between the colon and the `{variable}` is the
		45	* prefix, and its ABSENCE is load-bearing: `"Authorization: {api_key}"` is how
		46	* the registry says Linear's personal keys take no Bearer prefix. */
		47	export function placementFromHeaderPattern(pattern: string): Placement \| null {
		48	const match = /^([A-Za-z0-9-]+):\s(.)$/.exec(pattern.trim());
		49	if (!match) return null;
		50	const rest = match[2] ?? "";
		51	const brace = rest.indexOf("{");
		52	return {
		53	carrier: "header",
		54	name: match[1] ?? "",
		55	prefix: brace >= 0 ? rest.slice(0, brace) : "",
		56	};
		57	}
		58
43	/** What an auth method is, presentationally. `kind` drives the credential UI:	59	/** What an auth method is, presentationally. `kind` drives the credential UI:
44	* `oauth` shows a Connect button, `none` creates a connection with no	60	* `oauth` shows a Connect button, `none` creates a connection with no
45	* credential inputs, and apikey/custom fill secrets across `placements`.	61	* credential inputs, and apikey/custom fill secrets across `placements`.

packages/react/src/lib/integrations-sh-catalog.ts+17−0

    *  machine-readable locator, in which case the surface document still has to
    *  be fetched on click. */
   readonly url?: string;
+  /** How to authenticate, for surfaces whose connect target cannot describe
+   *  it itself — a GraphQL endpoint has no spec document, so the registry is
+   *  the only carrier of facts like Linear's no-Bearer-prefix header. */
+  readonly auth?: {
+    readonly kind?: string;
+    /** Header pattern, e.g. "Authorization: Bearer {token}". */
+    readonly header?: string;
+    readonly note?: string;
+  };
 }
 export interface CatalogSearchEntry {
             kind: Schema.String,
             slug: Schema.String,
             url: Schema.optional(Schema.String),
+            auth: Schema.optional(
+              Schema.Struct({
+                kind: Schema.optional(Schema.String),
+                header: Schema.optional(Schema.String),
+                note: Schema.optional(Schema.String),
+              }),
+            ),
           }),
         ),
       ),
                     kind: surface.kind,
                     slug: surface.slug,
                     ...(surface.url ? { url: surface.url } : {}),
+                    ...(surface.auth ? { auth: surface.auth } : {}),
                   },
                 ]
               : [],

packages/react/src/pages/integration-add.tsx+5−1

   url?: string;
   preset?: string;
   namespace?: string;
+  authHeader?: string;
+  authNote?: string;
 }) {
   useExecutorDocumentTitle("Add integration");
-  const { pluginKey, url, preset, namespace } = props;
+  const { pluginKey, url, preset, namespace, authHeader, authNote } = props;
   const navigate = useNavigate();
   const integrationPlugins = useIntegrationPlugins();
   const refreshIntegrations = useAtomRefresh(integrationsOptimisticAtom);
             initialUrl={url}
             initialPreset={preset}
             initialNamespace={namespace}
+            initialAuthHeader={authHeader}
+            initialAuthNote={authNote}
             onComplete={(slug?: string) => {
               trackEvent("integration_added", {
                 plugin_key: pluginKey,

packages/react/src/pages/integration-browse.tsx+25−5

       readonly url: string;
       readonly slug?: string;
       readonly domain: string;
+      readonly auth?: CatalogSurface["auth"];
     }) => {
       trackEvent("integration_add_started", {
         plugin_key: input.kind,
       void navigate({
         to: "/{-$orgSlug}/integrations/add/$pluginKey",
         params: { pluginKey: input.kind },
-        search: { url: input.url, ...(input.slug ? { namespace: input.slug } : {}) },
+        search: {
+          url: input.url,
+          ...(input.slug ? { namespace: input.slug } : {}),
+          ...(input.auth?.header ? { authHeader: input.auth.header } : {}),
+          ...(input.auth?.note ? { authNote: input.auth.note } : {}),
+        },
       });
     },
     [navigate],
           url: knownUrl,
           domain: entry.domain,
           ...(surface ? { slug: surface.slug } : {}),
+          ...(surface?.auth ? { auth: surface.auth } : {}),
         });
         return;
       }
   );
   const pickPreset = useCallback(
-    (entry: PresetEntry) => {
+    (entry: PresetEntry, auth?: CatalogSurface["auth"]) => {
       trackEvent("integration_add_started", {
         plugin_key: entry.pluginKey,
         via: "preset",
       });
       const search: Record<string, string> = { preset: entry.preset.id };
       if (entry.preset.url) search.url = entry.preset.url;
+      // The registry's credential facts ride along even when the preset owns
+      // the flow — the preset knows the endpoint, the registry knows the
+      // header pattern.
+      if (auth?.header) search.authHeader = auth.header;
+      if (auth?.note) search.authNote = auth.note;
       void navigate({
         to: "/{-$orgSlug}/integrations/add/$pluginKey",
         params: { pluginKey: entry.pluginKey },
   // other result, and the preset only supplies the better add flow. Keyed by
   // the rendered title, the same match the dedupe below uses.
   const catalogIdentityByTitle = useMemo(() => {
-    const map = new Map<string, { readonly domain: string }>();
+    const map = new Map<
+      string,
+      { readonly domain: string; readonly auth?: CatalogSurface["auth"] }
+    >();
     for (const entry of catalogEntries) {
       const pretty = entry.name ?? domainDisplayName(entry.domain);
       const surfaces =
       for (const surface of surfaces) {
         const word = SURFACE_WORD[surface.kind] ?? CATALOG_KIND_LABEL[surface.kind];
         const title = withSurface(pretty, word).toLowerCase();
-        if (!map.has(title)) map.set(title, { domain: entry.domain });
+        if (!map.has(title)) {
+          map.set(title, {
+            domain: entry.domain,
+            ...("auth" in surface && surface.auth ? { auth: surface.auth } : {}),
+          });
+        }
       }
     }
     return map;
         ...(identity ? { domain: identity.domain } : {}),
         ...(entry.preset.summary ? { description: entry.preset.summary } : {}),
         ...(entry.preset.icon ? { iconUrl: entry.preset.icon } : {}),
-        onSelect: () => pickPreset(entry),
+        onSelect: () => pickPreset(entry, identity?.auth),
         added: isAdded(entry.pluginKey, entry.preset.defaultSlug, entry.preset.name),
         busy: false,
       });

packages/react/src/routes/integrations.add.$pluginKey.tsx+14−2

     url: Schema.optional(Schema.String),
     preset: Schema.optional(Schema.String),
     namespace: Schema.optional(Schema.String),
+    // Registry-declared credential placement, e.g. "Authorization: {api_key}".
+    // Carried for surfaces whose connect target can't describe its own auth
+    // (GraphQL endpoints have no spec document).
+    authHeader: Schema.optional(Schema.String),
+    authNote: Schema.optional(Schema.String),
   }),
 );
   validateSearch: SearchParams,
   component: () => {
     const { pluginKey } = Route.useParams();
-    const { url, preset, namespace } = Route.useSearch();
+    const { url, preset, namespace, authHeader, authNote } = Route.useSearch();
     return (
-      <AddIntegrationPage pluginKey={pluginKey} url={url} preset={preset} namespace={namespace} />
+      <AddIntegrationPage
+        pluginKey={pluginKey}
+        url={url}
+        preset={preset}
+        namespace={namespace}
+        authHeader={authHeader}
+        authNote={authNote}
+      />
     );
   },
 });

Seed GraphQL auth methods from the registry's declared credential

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code