PR-I2: useXaaResourceApps hook + resource-app types (#2658)

Vu-John · claude · web-flow · commit 55de588c8501 · 2026-06-12T20:38:56.000-07:00
Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/mcpjam-inspector/client/src/hooks/__tests__/useXaaResourceApps.test.ts b/mcpjam-inspector/client/src/hooks/__tests__/useXaaResourceApps.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// ── Mocks ──────────────────────────────────────────────────────────────
+let convexAuth = { isAuthenticated: true, isLoading: false };
+let queryReturn: unknown = undefined;
+let hostedMode = true;
+const upsertAction = vi.fn(async () => ({ id: "app_new" }));
+const removeAction = vi.fn(async () => undefined);
+let lastQueryArgs: unknown;
+
+vi.mock("convex/react", () => ({
+  useConvexAuth: () => convexAuth,
+  useQuery: (_name: unknown, args: unknown) => {
+    lastQueryArgs = args;
+    return args === "skip" ? undefined : queryReturn;
+  },
+  useAction: (name: unknown) =>
+    name === "xaaResourceApps:upsert" ? upsertAction : removeAction,
+}));
+
+vi.mock("@/lib/config", () => ({
+  get HOSTED_MODE() {
+    return hostedMode;
+  },
+}));
+
+// Import AFTER mocks are set up.
+import { useXaaResourceApps } from "../useXaaResourceApps";
+
+const ORG_ID = "org_test";
+
+const VALID_ROW = {
+  id: "app_1",
+  name: "My Resource",
+  resourceType: "mcp",
+  resourceUrl: "https://resource.example.com/mcp",
+  authServerMode: "own",
+  tokenEndpoint: "https://as.example.com/oauth/token",
+  hasSecret: true,
+  createdAt: 100,
+  updatedAt: 200,
+};
+
+describe("useXaaResourceApps", () => {
+  beforeEach(() => {
+    convexAuth = { isAuthenticated: true, isLoading: false };
+    queryReturn = undefined;
+    hostedMode = true;
+    lastQueryArgs = undefined;
+    upsertAction.mockClear();
+    removeAction.mockClear();
+  });
+
+  describe("auth + hosted gate", () => {
+    it("fetches and reports isAuthenticated when authenticated, org-scoped, hosted", () => {
+      queryReturn = { resourceApps: [VALID_ROW] };
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.isAuthenticated).toBe(true);
+      expect(lastQueryArgs).toEqual({ organizationId: ORG_ID });
+      expect(result.current.resourceApps).toHaveLength(1);
+    });
+
+    it("skips the query and reports isAuthenticated=false when not hosted", () => {
+      hostedMode = false;
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(lastQueryArgs).toBe("skip");
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    it("skips when unauthenticated", () => {
+      convexAuth = { isAuthenticated: false, isLoading: false };
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(lastQueryArgs).toBe("skip");
+    });
+
+    it("skips when no organization is selected", () => {
+      const { result } = renderHook(() => useXaaResourceApps(null));
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(lastQueryArgs).toBe("skip");
+    });
+
+    it("reports isLoading while the gated query is in flight", () => {
+      queryReturn = undefined; // query returns undefined => still loading
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.isLoading).toBe(true);
+    });
+
+    it("reports isLoading during the auth-bootstrap window (hosted)", () => {
+      convexAuth = { isAuthenticated: false, isLoading: true };
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.isLoading).toBe(true);
+      expect(result.current.isAuthenticated).toBe(false);
+    });
+  });
+
+  describe("normalize", () => {
+    it("accepts a bare array as well as a wrapped envelope", () => {
+      queryReturn = [VALID_ROW];
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.resourceApps).toHaveLength(1);
+      expect(result.current.resourceApps[0]).toMatchObject({
+        id: "app_1",
+        resourceType: "mcp",
+        authServerMode: "own",
+        hasSecret: true,
+      });
+    });
+
+    it("drops malformed rows (bad enum / missing id)", () => {
+      queryReturn = {
+        resourceApps: [
+          VALID_ROW,
+          { ...VALID_ROW, id: "app_2", resourceType: "grpc" },
+          { ...VALID_ROW, id: undefined },
+        ],
+      };
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      expect(result.current.resourceApps).toHaveLength(1);
+      expect(result.current.resourceApps[0].id).toBe("app_1");
+    });
+
+    it("never surfaces a secret value even if the wire carried one", () => {
+      queryReturn = {
+        resourceApps: [{ ...VALID_ROW, secret: "leaked", vaultObjectId: "v" }],
+      };
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      const app = result.current.resourceApps[0] as Record<string, unknown>;
+      expect(app).not.toHaveProperty("secret");
+      expect(app).not.toHaveProperty("vaultObjectId");
+    });
+  });
+
+  describe("mutations", () => {
+    it("upsert forwards organizationId and the input", async () => {
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      await act(async () => {
+        await result.current.upsert({
+          name: "New",
+          resourceType: "rest",
+          resourceUrl: "https://r.example.com/api",
+          authServerMode: "mcpjam",
+        });
+      });
+      expect(upsertAction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          organizationId: ORG_ID,
+          name: "New",
+          authServerMode: "mcpjam",
+        }),
+      );
+    });
+
+    it("remove forwards id + organizationId", async () => {
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      await act(async () => {
+        await result.current.remove("app_1");
+      });
+      expect(removeAction).toHaveBeenCalledWith({
+        id: "app_1",
+        organizationId: ORG_ID,
+      });
+    });
+
+    it("captures the error message when a mutation throws", async () => {
+      upsertAction.mockRejectedValueOnce(new Error("boom"));
+      const { result } = renderHook(() => useXaaResourceApps(ORG_ID));
+      await act(async () => {
+        await expect(
+          result.current.upsert({
+            name: "x",
+            resourceType: "rest",
+            resourceUrl: "https://r.example.com/api",
+            authServerMode: "mcpjam",
+          }),
+        ).rejects.toThrow("boom");
+      });
+      expect(result.current.error).toBe("boom");
+    });
+  });
+});
diff --git a/mcpjam-inspector/client/src/hooks/useXaaResourceApps.ts b/mcpjam-inspector/client/src/hooks/useXaaResourceApps.ts
@@ -0,0 +1,156 @@
+import { useAction, useConvexAuth, useQuery } from "convex/react";
+import { useCallback, useMemo, useState } from "react";
+import { HOSTED_MODE } from "@/lib/config";
+import type {
+  XaaAuthServerMode,
+  XaaResourceApp,
+  XaaResourceAppInput,
+  XaaResourceType,
+} from "@/lib/xaa/types";
+
+const RESOURCE_TYPES: ReadonlySet<XaaResourceType> = new Set(["rest", "mcp"]);
+const AUTH_SERVER_MODES: ReadonlySet<XaaAuthServerMode> = new Set([
+  "mcpjam",
+  "own",
+]);
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const strings = value.filter((v): v is string => typeof v === "string");
+  return strings.length > 0 ? strings : undefined;
+}
+
+// The backend already sanitizes (no vaultObjectId/secret ever leaves the
+// wire); this normalizer just coerces the loose `as any` query result into the
+// typed shape and drops anything malformed.
+function normalizeResourceApp(raw: unknown): XaaResourceApp | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.id !== "string" || typeof r.name !== "string") return null;
+  if (!RESOURCE_TYPES.has(r.resourceType as XaaResourceType)) return null;
+  if (!AUTH_SERVER_MODES.has(r.authServerMode as XaaAuthServerMode))
+    return null;
+
+  return {
+    id: r.id,
+    name: r.name,
+    resourceType: r.resourceType as XaaResourceType,
+    resourceUrl: typeof r.resourceUrl === "string" ? r.resourceUrl : "",
+    authServerMode: r.authServerMode as XaaAuthServerMode,
+    tokenEndpoint: optionalString(r.tokenEndpoint),
+    issuer: optionalString(r.issuer),
+    targetClientId: optionalString(r.targetClientId),
+    scopes: optionalStringArray(r.scopes),
+    healthCheckUrl: optionalString(r.healthCheckUrl),
+    hasSecret: r.hasSecret === true,
+    createdAt: typeof r.createdAt === "number" ? r.createdAt : 0,
+    updatedAt: typeof r.updatedAt === "number" ? r.updatedAt : 0,
+  };
+}
+
+function normalizeList(raw: unknown): XaaResourceApp[] {
+  // Accept either a wrapped `{ resourceApps: [...] }` or a bare array, so a
+  // future shape tweak on the backend doesn't break the consumer.
+  const list = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === "object"
+      ? (raw as { resourceApps?: unknown }).resourceApps
+      : undefined;
+  if (!Array.isArray(list)) return [];
+  return list
+    .map(normalizeResourceApp)
+    .filter((app): app is XaaResourceApp => app !== null);
+}
+
+export interface UseXaaResourceAppsResult {
+  resourceApps: XaaResourceApp[];
+  isLoading: boolean;
+  /**
+   * The full gate the hook uses internally to fetch — registration is a hosted
+   * feature, so consumers get `true` only when authenticated, scoped to an
+   * org, AND in hosted mode. Never a half-gate.
+   */
+  isAuthenticated: boolean;
+  error: string | null;
+  upsert: (input: XaaResourceAppInput) => Promise<{ id: string }>;
+  remove: (id: string) => Promise<void>;
+}
+
+export function useXaaResourceApps(
+  organizationId: string | null,
+): UseXaaResourceAppsResult {
+  const { isAuthenticated: hasConvexIdentity, isLoading: isAuthLoading } =
+    useConvexAuth();
+
+  const enabled = hasConvexIdentity && !!organizationId && HOSTED_MODE;
+
+  const raw = useQuery(
+    "xaaResourceApps:list" as any,
+    enabled ? ({ organizationId } as any) : "skip",
+  ) as unknown | undefined;
+
+  const resourceApps = useMemo(() => normalizeList(raw), [raw]);
+
+  // Cast the new function names `as any` until backend `_generated` types
+  // regenerate after the CRUD layer deploys.
+  const upsertAction = useAction("xaaResourceApps:upsert" as any);
+  const removeAction = useAction("xaaResourceApps:remove" as any);
+
+  const [error, setError] = useState<string | null>(null);
+
+  const upsert = useCallback(
+    async (input: XaaResourceAppInput): Promise<{ id: string }> => {
+      if (!organizationId) throw new Error("Organization is required");
+      setError(null);
+      try {
+        const result = await upsertAction({
+          organizationId,
+          ...input,
+        } as any);
+        return result as { id: string };
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : "Failed to save resource app";
+        setError(message);
+        throw err;
+      }
+    },
+    [organizationId, upsertAction],
+  );
+
+  const remove = useCallback(
+    async (id: string): Promise<void> => {
+      if (!organizationId) throw new Error("Organization is required");
+      setError(null);
+      try {
+        await removeAction({ id, organizationId } as any);
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : "Failed to delete resource app";
+        setError(message);
+        throw err;
+      }
+    },
+    [organizationId, removeAction],
+  );
+
+  // Registration is hosted-only, so non-hosted renders never report loading.
+  // Inside hosted mode, treat the auth-bootstrap window as loading so the list
+  // shows a skeleton instead of flashing an empty state.
+  const isLoading = HOSTED_MODE
+    ? isAuthLoading || (enabled && raw === undefined)
+    : false;
+
+  return {
+    resourceApps,
+    isLoading,
+    isAuthenticated: enabled,
+    error,
+    upsert,
+    remove,
+  };
+}
diff --git a/mcpjam-inspector/client/src/lib/xaa/types.ts b/mcpjam-inspector/client/src/lib/xaa/types.ts
@@ -158,6 +158,47 @@ export interface XAAStateMachine {
   resetFlow: () => void;
 }
 
+// ---------------------------------------------------------------------------
+// Registered resource apps (hosted test bench). The wire shape mirrors the
+// backend's sanitized projection: the client secret is never returned, only a
+// `hasSecret` boolean.
+// ---------------------------------------------------------------------------
+
+export type XaaResourceType = "rest" | "mcp";
+export type XaaAuthServerMode = "mcpjam" | "own";
+
+export interface XaaResourceApp {
+  id: string;
+  name: string;
+  resourceType: XaaResourceType;
+  resourceUrl: string;
+  authServerMode: XaaAuthServerMode;
+  tokenEndpoint?: string;
+  issuer?: string;
+  targetClientId?: string;
+  scopes?: string[];
+  healthCheckUrl?: string;
+  hasSecret: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Args accepted by the upsert action. `id` present = update. */
+export interface XaaResourceAppInput {
+  id?: string;
+  name: string;
+  resourceType: XaaResourceType;
+  resourceUrl: string;
+  authServerMode: XaaAuthServerMode;
+  tokenEndpoint?: string;
+  issuer?: string;
+  targetClientId?: string;
+  /** Plaintext secret; sent only when set/changed, never returned. */
+  secret?: string;
+  scopes?: string[];
+  healthCheckUrl?: string;
+}
+
 export const EMPTY_XAA_FLOW_STATE: XAAFlowState = {
   isBusy: false,
   currentStep: "idle",
