@stigmer/react 0.0.77 → 0.0.79

package/src/mcp-server/OAuthCallbackHandler.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { cn } from "@stigmer/theme";
+import { OAUTH_CALLBACK_MESSAGE_TYPE } from "./useMcpServerOAuthConnect";
+import type { OAuthCallbackMessage } from "./useMcpServerOAuthConnect";
+
+/** Parameters extracted from the OAuth callback URL. */
+export interface OAuthCallbackParams {
+  /** The authorization code returned by the OAuth provider. */
+  readonly code: string;
+  /** The opaque state token used to correlate the callback with the originating request. */
+  readonly state: string;
+}
+
+/** Props for {@link OAuthCallbackHandler}. */
+export interface OAuthCallbackHandlerProps {
+  /**
+   * Fallback callback invoked when the page was opened as a regular
+   * navigation (no `window.opener`), meaning the popup `postMessage`
+   * path cannot be used.
+   *
+   * Receives the extracted `code` and `state` so the host application
+   * can complete the OAuth flow via its own routing logic.
+   *
+   * When omitted and `window.opener` is unavailable, the component
+   * renders an instructional message asking the user to close the tab.
+   */
+  readonly onFallback?: (params: OAuthCallbackParams) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Lightweight component for OAuth callback pages.
+ *
+ * Render this component at the URL configured as your OAuth redirect
+ * URI (`STIGMER_OAUTH_REDIRECT_URI`). It extracts the `code` and
+ * `state` query parameters from the current URL, posts them back to
+ * the opener window via `window.postMessage`, and closes the popup.
+ *
+ * The component handles three scenarios:
+ * 1. **Popup with opener** (primary): posts the message and closes.
+ * 2. **No opener, `onFallback` provided**: calls the fallback with
+ *    the extracted parameters so the host app can handle them.
+ * 3. **No opener, no fallback**: shows a message asking the user to
+ *    return to the main window.
+ *
+ * Platform builders create a route in their application that renders
+ * this component:
+ *
+ * @example
+ * ```tsx
+ * // app/auth/oauth/callback/page.tsx (Next.js)
+ * import { OAuthCallbackHandler } from "@stigmer/react";
+ *
+ * export default function OAuthCallbackPage() {
+ *   return <OAuthCallbackHandler />;
+ * }
+ * ```
+ */
+export function OAuthCallbackHandler({
+  onFallback,
+  className,
+}: OAuthCallbackHandlerProps) {
+  const [status, setStatus] = useState<"processing" | "done" | "no-opener" | "error">("processing");
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const didRun = useRef(false);
+
+  useEffect(() => {
+    if (didRun.current) return;
+    didRun.current = true;
+
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+
+    const oauthError = params.get("error");
+    if (oauthError) {
+      const description = params.get("error_description") || oauthError;
+      setErrorMessage(`Authentication failed: ${description}`);
+      setStatus("error");
+      return;
+    }
+
+    if (!code || !state) {
+      setErrorMessage(
+        "Missing authorization code or state parameter. " +
+          "This page should only be reached via an OAuth redirect.",
+      );
+      setStatus("error");
+      return;
+    }
+
+    const opener = window.opener as Window | null;
+    if (opener && !opener.closed) {
+      const message: OAuthCallbackMessage = {
+        type: OAUTH_CALLBACK_MESSAGE_TYPE,
+        code,
+        state,
+      };
+
+      try {
+        opener.postMessage(message, window.location.origin);
+        setStatus("done");
+        window.close();
+      } catch {
+        setErrorMessage(
+          "Could not communicate with the parent window. " +
+            "Please close this tab and try again.",
+        );
+        setStatus("error");
+      }
+      return;
+    }
+
+    if (onFallback) {
+      onFallback({ code, state });
+      setStatus("done");
+      return;
+    }
+
+    setStatus("no-opener");
+  }, [onFallback]);
+
+  return (
+    <div
+      className={cn(
+        "flex min-h-[200px] items-center justify-center p-8",
+        className,
+      )}
+    >
+      <div className="max-w-sm text-center">
+        {status === "processing" && (
+          <>
+            <Spinner />
+            <p className="mt-3 text-sm text-muted-foreground">
+              Completing authentication...
+            </p>
+          </>
+        )}
+
+        {status === "done" && (
+          <p className="text-sm text-muted-foreground">
+            Authentication complete. You can close this window.
+          </p>
+        )}
+
+        {status === "no-opener" && (
+          <>
+            <CheckIcon />
+            <p className="mt-3 text-sm font-medium text-foreground">
+              Authentication successful
+            </p>
+            <p className="mt-1 text-xs text-muted-foreground">
+              Please close this tab and return to the application to continue.
+            </p>
+          </>
+        )}
+
+        {status === "error" && (
+          <>
+            <WarningIcon />
+            <p className="mt-3 text-sm font-medium text-destructive">
+              Authentication failed
+            </p>
+            {errorMessage && (
+              <p className="mt-1 text-xs text-muted-foreground">
+                {errorMessage}
+              </p>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons -- inline SVGs (no external icon dependency, matches SDK pattern)
+// ---------------------------------------------------------------------------
+
+function Spinner() {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      className="mx-auto animate-spin text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="mx-auto text-success"
+      aria-hidden="true"
+    >
+      <path d="m3 8.5 3.5 3.5 6.5-8" />
+    </svg>
+  );
+}
+
+function WarningIcon() {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="mx-auto text-destructive"
+      aria-hidden="true"
+    >
+      <path d="M8 1.5 1 14h14L8 1.5Z" />
+      <path d="M8 6v3.5" />
+      <circle cx="8" cy="11.5" r="0.5" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}

package/src/mcp-server/index.ts

@@ -32,6 +32,7 @@ export { McpServerConfigPanel } from "./McpServerConfigPanel";
 export type {
   McpServerConfigPanelProps,
   McpServerCredentialsProps,
+  McpServerOAuthSignInProps,
 } from "./McpServerConfigPanel";
 
 export { useMcpServerSetup, toServerKey } from "./useMcpServerSetup";
@@ -52,5 +53,20 @@ export type {
 export { useMcpServerConnect } from "./useMcpServerConnect";
 export type { UseMcpServerConnectReturn } from "./useMcpServerConnect";
 
+export { useMcpServerOAuthConnect } from "./useMcpServerOAuthConnect";
+export type {
+  UseMcpServerOAuthConnectReturn,
+  OAuthConnectPhase,
+} from "./useMcpServerOAuthConnect";
+
+export { OAuthCallbackHandler } from "./OAuthCallbackHandler";
+export type {
+  OAuthCallbackHandlerProps,
+  OAuthCallbackParams,
+} from "./OAuthCallbackHandler";
+
 export { useMcpServerCredentials } from "./useMcpServerCredentials";
-export type { UseMcpServerCredentialsReturn } from "./useMcpServerCredentials";
+export type {
+  UseMcpServerCredentialsReturn,
+  McpServerAuthMode,
+} from "./useMcpServerCredentials";

package/src/mcp-server/useMcpServerConnect.ts

@@ -6,6 +6,7 @@ import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/
 import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import type { EnvVarInput } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
+import { resolveSystemEnvVarValues } from "../environment/systemEnvVars";
 import { toError } from "../internal/toError";
 
 /** Return value of {@link useMcpServerConnect}. */
@@ -18,13 +19,15 @@ export interface UseMcpServerConnectReturn {
    * agent-runner. The RPC blocks until the workflow completes
    * (typically 5-15 seconds, ~30s timeout).
    *
-   * When `runtimeEnv` is provided, the values are sent directly to
-   * the backend as one-time credentials (not persisted to any
-   * environment). When omitted, the backend resolves credentials from
-   * the authenticated user's personal environment.
+   * Platform system env vars (`STIGMER_SERVER_ADDRESS`,
+   * `STIGMER_API_KEY`) are always injected automatically from
+   * the current SDK context. When `runtimeEnv` is also provided,
+   * those values are merged on top (caller values win). The backend
+   * merges the result on top of the user's personal environment so
+   * saved credentials (e.g., OAuth tokens) are still resolved.
    *
    * @param mcpServerId - System-generated ID of the MCP server (metadata.id).
-   * @param runtimeEnv - Optional one-time environment variables.
+   * @param runtimeEnv - Optional additional environment variables.
    * @returns The updated McpServer with populated status.discovered_capabilities
    *          and status.tool_approvals.
    */
@@ -48,13 +51,14 @@ export interface UseMcpServerConnectReturn {
  * server's tools and resource templates, then classifies each tool's
  * approval policy via a structured-output LLM call.
  *
- * Supports two credential modes:
- * - **Saved credentials** (default): Credentials are pre-saved to the
- *   user's personal environment, then `connect(id)` is called without
- *   `runtimeEnv`. The backend resolves them automatically.
- * - **One-time use**: `connect(id, runtimeEnv)` passes credentials
- *   directly to the backend. They are used for this connect only and
- *   not persisted.
+ * Platform system env vars (`STIGMER_SERVER_ADDRESS`,
+ * `STIGMER_API_KEY`) are always injected from the current SDK
+ * context. The backend merges these on top of the caller's personal
+ * environment, so saved credentials (e.g., OAuth tokens) are still
+ * resolved while platform addresses are always up to date.
+ *
+ * Additional one-time credentials can be passed via `runtimeEnv`
+ * and will override both system vars and personal env values.
  *
  * @example
  * ```tsx
@@ -90,21 +94,20 @@ export function useMcpServerConnect(): UseMcpServerConnectReturn {
       setError(null);
 
       try {
+        const systemEnv = await resolveSystemEnvVarValues(stigmer);
+        const mergedEnv = { ...systemEnv, ...(runtimeEnv ?? {}) };
+
         const runtimeEnvMap: Record<string, { value: string; isSecret: boolean }> = {};
-        if (runtimeEnv) {
-          for (const [key, input] of Object.entries(runtimeEnv)) {
-            runtimeEnvMap[key] = {
-              value: input.value,
-              isSecret: input.isSecret ?? false,
-            };
-          }
+        for (const [key, envInput] of Object.entries(mergedEnv)) {
+          runtimeEnvMap[key] = {
+            value: envInput.value,
+            isSecret: envInput.isSecret ?? false,
+          };
         }
 
         const input = create(ConnectInputSchema, {
           mcpServerId,
-          ...(Object.keys(runtimeEnvMap).length > 0 && {
-            runtimeEnv: runtimeEnvMap,
-          }),
+          runtimeEnv: runtimeEnvMap,
         });
 
         return await stigmer.mcpServer.connect(input);

package/src/mcp-server/useMcpServerCredentials.ts

@@ -8,17 +8,59 @@ import { diffEnvSpec } from "../environment/diffEnvSpec";
 import { SYSTEM_ENV_VAR_KEYS } from "../environment/systemEnvVars";
 import type { EnvVarFormVariable } from "../environment/EnvVarForm";
 
+/**
+ * Credential acquisition mode for an MCP server.
+ *
+ * - `"manual"` — all env vars are entered by the user via a form.
+ * - `"oauth"` — at least one env var (`target_env_var`) is acquired
+ *   via OAuth. Additional manual vars may still be required (mixed mode).
+ */
+export type McpServerAuthMode = "manual" | "oauth";
+
 /** Return value of {@link useMcpServerCredentials}. */
 export interface UseMcpServerCredentialsReturn {
+  /**
+   * Credential acquisition mode derived from `spec.auth`.
+   *
+   * - `"manual"` when `spec.auth` is absent: all env vars are user-entered.
+   * - `"oauth"` when `spec.auth` is present: the `target_env_var` is
+   *   acquired via OAuth. Check {@link missingVariables} for any
+   *   additional manual vars that are also needed (mixed mode).
+   */
+  readonly authMode: McpServerAuthMode;
+  /**
+   * The env var name managed by OAuth, or `null` when `authMode` is `"manual"`.
+   * Corresponds to `spec.auth.target_env_var`.
+   */
+  readonly oauthTargetEnvVar: string | null;
+  /**
+   * `true` when the OAuth-managed env var exists in the personal
+   * environment. Always `false` when `authMode` is `"manual"`.
+   */
+  readonly isOAuthConnected: boolean;
+  /**
+   * Informational hint about expected token lifetime, or `null`.
+   * Sourced from `spec.auth.token_lifetime_hint`.
+   */
+  readonly tokenLifetimeHint: string | null;
   /**
    * Variables required by the MCP server that are missing from the
    * user's personal environment. Empty when all variables are present
    * or the server has no `env_spec`.
    *
+   * When `authMode` is `"oauth"`, the OAuth-managed `target_env_var`
+   * is excluded from this list — it is acquired via the OAuth flow,
+   * not via a manual form. Only additional non-OAuth vars appear here.
+   *
    * Suitable as direct input to {@link EnvVarForm}.
    */
   readonly missingVariables: EnvVarFormVariable[];
-  /** `true` when all required credentials are available. */
+  /**
+   * `true` when all required credentials are available — both
+   * OAuth-managed and manual variables. For OAuth servers this means
+   * the OAuth token is in the personal env AND any additional manual
+   * vars are also present.
+   */
   readonly isReady: boolean;
   /** `true` while the personal environment is being fetched. */
   readonly isLoading: boolean;
@@ -47,6 +89,12 @@ export interface UseMcpServerCredentialsReturn {
  * computes the missing set and exposes `saveCredentials` to persist
  * them.
  *
+ * **Auth-mode-aware**: when `spec.auth` is configured, the hook
+ * identifies the OAuth-managed variable (`target_env_var`) and
+ * excludes it from `missingVariables` — that variable is acquired
+ * via {@link useMcpServerOAuthConnect}, not a manual form. Additional
+ * non-OAuth vars still appear in `missingVariables` (mixed mode).
+ *
  * Unlike {@link useMcpServerSetup} which manages multi-server setup
  * for session creation, this hook is scoped to a single server and
  * always persists to the personal environment (no one-time option).
@@ -55,15 +103,20 @@ export interface UseMcpServerCredentialsReturn {
  *
  * @example
  * ```tsx
- * const { missingVariables, isReady, saveCredentials, isSaving } =
- *   useMcpServerCredentials("acme", mcpServer);
+ * const creds = useMcpServerCredentials("acme", mcpServer);
  *
- * if (!isReady) {
+ * // OAuth server — sign-in button + optional manual form
+ * if (creds.authMode === "oauth" && !creds.isOAuthConnected) {
+ *   return <button onClick={startOAuth}>Sign in</button>;
+ * }
+ *
+ * // Manual vars still needed (mixed mode or manual-only)
+ * if (creds.missingVariables.length > 0) {
  *   return (
  *     <EnvVarForm
- *       variables={missingVariables}
- *       onSubmit={(values) => saveCredentials(values)}
- *       isSubmitting={isSaving}
+ *       variables={creds.missingVariables}
+ *       onSubmit={(values) => creds.saveCredentials(values)}
+ *       isSubmitting={creds.isSaving}
  *       hideSaveToggle
  *     />
  *   );
@@ -76,21 +129,37 @@ export function useMcpServerCredentials(
 ): UseMcpServerCredentialsReturn {
   const personalEnv = usePersonalEnvironment(org);
 
-  const missingVariables = useMemo(() => {
+  const auth = mcpServer?.spec?.auth;
+  const authMode: McpServerAuthMode = auth ? "oauth" : "manual";
+  const oauthTargetEnvVar = auth?.targetEnvVar || null;
+  const tokenLifetimeHint = auth?.tokenLifetimeHint || null;
+
+  const existingKeys = useMemo(
+    () => new Set(Object.keys(personalEnv.environment?.spec?.data ?? {})),
+    [personalEnv.environment],
+  );
+
+  const isOAuthConnected = authMode === "oauth"
+    && oauthTargetEnvVar !== null
+    && existingKeys.has(oauthTargetEnvVar);
+
+  const allMissingVariables = useMemo(() => {
     if (!mcpServer) return [];
     const envSpecData = mcpServer.spec?.envSpec?.data;
     if (!envSpecData || Object.keys(envSpecData).length === 0) return [];
 
-    const existingKeys = new Set(
-      Object.keys(personalEnv.environment?.spec?.data ?? {}),
-    );
     return diffEnvSpec(envSpecData, existingKeys).filter(
       (v) => !SYSTEM_ENV_VAR_KEYS.has(v.key),
     );
-  }, [mcpServer, personalEnv.environment]);
+  }, [mcpServer, existingKeys]);
+
+  const missingVariables = useMemo(() => {
+    if (!oauthTargetEnvVar) return allMissingVariables;
+    return allMissingVariables.filter((v) => v.key !== oauthTargetEnvVar);
+  }, [allMissingVariables, oauthTargetEnvVar]);
 
   const isReady =
-    !personalEnv.isLoading && missingVariables.length === 0;
+    !personalEnv.isLoading && allMissingVariables.length === 0;
 
   const saveCredentials = useCallback(
     async (values: Record<string, EnvVarInput>): Promise<void> => {
@@ -101,6 +170,10 @@ export function useMcpServerCredentials(
   );
 
   return {
+    authMode,
+    oauthTargetEnvVar,
+    isOAuthConnected,
+    tokenLifetimeHint,
     missingVariables,
     isReady,
     isLoading: personalEnv.isLoading,