feat(userspace): install-time permission consent dialog (#1579)

Adds the PermissionConsent dialog for userspace app installs: lists each
requested capability with a plain-English description mirrored from
tinyagentos/userspace/capabilities.py, flags the gated ones (app.net,
app.agent, app.llm, app.memory), and Allow/Deny grants or skips them via
POST /api/userspace-apps/{app_id}/permissions.

Wires it into the Store's Apps tab via a new ImportAppButton that installs
a .taosapp package and shows the dialog whenever the install response sets
needs_consent.

Docs-Reviewed: frontend-only Store components (install-consent dialog + .taosapp import button); no README app-list or route surface change, userspace install/consent tracked under App Runtime epic #196

Author: jaylfc

desktop/src/apps/StoreApp/ImportAppButton.test.tsx

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { ImportAppButton } from "./ImportAppButton";
+
+function mockFetchSequence(responses: Array<{ url: string; body: unknown; ok?: boolean }>) {
+  return vi.fn((url: string) => {
+    const match = responses.find((r) => url.includes(r.url));
+    if (!match) throw new Error(`unexpected fetch: ${url}`);
+    return Promise.resolve({ ok: match.ok ?? true, json: async () => match.body });
+  });
+}
+
+describe("ImportAppButton", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("installing a package requesting a gated capability shows the consent dialog", async () => {
+    const mockFetch = mockFetchSequence([
+      {
+        url: "/api/userspace-apps/install",
+        body: { app_id: "todo", permissions_requested: ["app.net", "app.kv"], needs_consent: true, new_permissions: ["app.net"] },
+      },
+      {
+        url: "/api/userspace-apps",
+        body: [{ app_id: "todo", name: "Todo", icon: "", app_type: "web", version: "1", enabled: 1, permissions_requested: ["app.net", "app.kv"], permissions_granted: [] }],
+      },
+    ]);
+    vi.stubGlobal("fetch", mockFetch);
+
+    render(<ImportAppButton />);
+    const file = new File(["data"], "todo.taosapp");
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { files: [file] } });
+
+    const dialog = await screen.findByRole("dialog", { name: /permissions for todo/i });
+    expect(dialog).toBeInTheDocument();
+    expect(screen.getByText(/connect to the internet/i)).toBeInTheDocument();
+  });
+
+  it("installing a package with no new permissions never shows the dialog", async () => {
+    const mockFetch = mockFetchSequence([
+      {
+        url: "/api/userspace-apps/install",
+        body: { app_id: "todo", permissions_requested: ["app.kv"], needs_consent: false, new_permissions: [] },
+      },
+      { url: "/api/userspace-apps", body: [] },
+    ]);
+    vi.stubGlobal("fetch", mockFetch);
+
+    render(<ImportAppButton />);
+    const file = new File(["data"], "todo.taosapp");
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { files: [file] } });
+
+    await waitFor(() => expect(mockFetch).toHaveBeenCalled());
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("Deny in the dialog dismisses it without granting", async () => {
+    const mockFetch = mockFetchSequence([
+      {
+        url: "/api/userspace-apps/install",
+        body: { app_id: "todo", permissions_requested: ["app.net"], needs_consent: true, new_permissions: ["app.net"] },
+      },
+      {
+        url: "/api/userspace-apps",
+        body: [{ app_id: "todo", name: "Todo", icon: "", app_type: "web", version: "1", enabled: 1, permissions_requested: ["app.net"], permissions_granted: [] }],
+      },
+    ]);
+    vi.stubGlobal("fetch", mockFetch);
+
+    render(<ImportAppButton />);
+    const file = new File(["data"], "todo.taosapp");
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { files: [file] } });
+
+    await screen.findByRole("dialog");
+    fireEvent.click(screen.getByRole("button", { name: /deny/i }));
+    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(mockFetch).not.toHaveBeenCalledWith(expect.stringContaining("/permissions"), expect.anything());
+  });
+});

desktop/src/apps/StoreApp/ImportAppButton.tsx

@@ -0,0 +1,96 @@
+import { useCallback, useRef, useState } from "react";
+import { Upload, Loader2 } from "lucide-react";
+import {
+  installUserspaceApp,
+  fetchUserspaceAppRow,
+  USERSPACE_APPS_CHANGED,
+  type InstallResult,
+} from "@/lib/userspace-apps";
+import { emitAppEvent } from "@/lib/app-event-bus";
+import { PermissionConsent } from "./PermissionConsent";
+
+/** Import a .taosapp package from disk and install it as a userspace app.
+ * When the install requests new permissions, the consent dialog shows before
+ * anything sensitive is granted -- the app itself is already installed at
+ * that point (with only its free capabilities usable) so it can never be
+ * blocked on a decision the user hasn't made yet. */
+export function ImportAppButton() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [consent, setConsent] = useState<{
+    appId: string;
+    appName: string;
+    requested: string[];
+    alreadyGranted: string[];
+  } | null>(null);
+
+  const handleFile = useCallback(async (file: File) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const result: InstallResult = await installUserspaceApp(file);
+      const row = await fetchUserspaceAppRow(result.app_id);
+      // The row is now enabled and visible regardless of consent -- only its
+      // gated capabilities are withheld until the user answers below.
+      emitAppEvent(USERSPACE_APPS_CHANGED);
+      if (result.needs_consent) {
+        setConsent({
+          appId: result.app_id,
+          appName: row?.name ?? result.app_id,
+          requested: result.new_permissions,
+          alreadyGranted: row?.permissions_granted ?? [],
+        });
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Install failed");
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        type="file"
+        accept=".taosapp,.zip"
+        className="hidden"
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          e.target.value = "";
+          if (file) void handleFile(file);
+        }}
+      />
+      <button
+        type="button"
+        onClick={() => inputRef.current?.click()}
+        disabled={busy}
+        className="flex items-center gap-1.5 h-8 px-3 rounded-lg text-[12px] font-semibold border border-shell-border text-shell-text-secondary hover:text-shell-text hover:bg-white/[0.04] transition-colors disabled:opacity-60"
+      >
+        {busy ? <Loader2 className="w-3.5 h-3.5 animate-spin" /> : <Upload className="w-3.5 h-3.5" />}
+        Import app package
+      </button>
+      {error && (
+        <div role="alert" className="mt-2 text-[11px] text-red-300 bg-red-500/10 border border-red-500/20 rounded px-2 py-1">
+          {error}
+        </div>
+      )}
+      {consent && (
+        <PermissionConsent
+          appId={consent.appId}
+          appName={consent.appName}
+          requested={consent.requested}
+          alreadyGranted={consent.alreadyGranted}
+          onAllow={() => {
+            emitAppEvent(USERSPACE_APPS_CHANGED);
+            setConsent(null);
+          }}
+          onDeny={() => setConsent(null)}
+        />
+      )}
+    </>
+  );
+}
+
+export default ImportAppButton;

desktop/src/apps/StoreApp/PermissionConsent.test.tsx

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { PermissionConsent, GATED_CAPS } from "./PermissionConsent";
+
+describe("PermissionConsent", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("renders as a labelled dialog listing each requested capability", () => {
+    render(
+      <PermissionConsent
+        appId="todo"
+        appName="Todo"
+        requested={["app.net", "app.kv"]}
+        onAllow={() => {}}
+        onDeny={() => {}}
+      />,
+    );
+    const dialog = screen.getByRole("dialog", { name: /permissions for todo/i });
+    expect(dialog).toBeInTheDocument();
+    expect(screen.getByText(/connect to the internet/i)).toBeInTheDocument();
+    expect(screen.getByText(/store and read its own app data/i)).toBeInTheDocument();
+  });
+
+  it("visually flags gated/sensitive capabilities but not free ones", () => {
+    expect(GATED_CAPS.has("app.net")).toBe(true);
+    expect(GATED_CAPS.has("app.kv")).toBe(false);
+
+    render(
+      <PermissionConsent
+        appId="todo"
+        appName="Todo"
+        requested={["app.net", "app.kv"]}
+        onAllow={() => {}}
+        onDeny={() => {}}
+      />,
+    );
+    const netRow = screen.getByText(/connect to the internet/i).closest("li")!;
+    const kvRow = screen.getByText(/store and read its own app data/i).closest("li")!;
+    expect(netRow.textContent).toContain("⚠");
+    expect(kvRow.textContent).not.toContain("⚠");
+  });
+
+  it("Allow POSTs the granted permissions (merged with any already granted) and calls onAllow", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", mockFetch);
+    const onAllow = vi.fn();
+
+    render(
+      <PermissionConsent
+        appId="todo"
+        appName="Todo"
+        requested={["app.net"]}
+        alreadyGranted={["app.memory"]}
+        onAllow={onAllow}
+        onDeny={() => {}}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: /allow/i }));
+
+    await waitFor(() => expect(onAllow).toHaveBeenCalled());
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/api/userspace-apps/todo/permissions",
+      expect.objectContaining({ method: "POST" }),
+    );
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(new Set(body.granted)).toEqual(new Set(["app.net", "app.memory"]));
+    expect(onAllow).toHaveBeenCalledWith(expect.arrayContaining(["app.net", "app.memory"]));
+  });
+
+  it("Deny cancels without granting anything", () => {
+    const mockFetch = vi.fn();
+    vi.stubGlobal("fetch", mockFetch);
+    const onDeny = vi.fn();
+
+    render(
+      <PermissionConsent
+        appId="todo"
+        appName="Todo"
+        requested={["app.net"]}
+        onAllow={() => {}}
+        onDeny={onDeny}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: /deny/i }));
+
+    expect(onDeny).toHaveBeenCalledTimes(1);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("Escape key cancels", () => {
+    const onDeny = vi.fn();
+    render(
+      <PermissionConsent
+        appId="todo"
+        appName="Todo"
+        requested={["app.net"]}
+        onAllow={() => {}}
+        onDeny={onDeny}
+      />,
+    );
+    fireEvent.keyDown(screen.getByRole("dialog"), { key: "Escape" });
+    expect(onDeny).toHaveBeenCalledTimes(1);
+  });
+});