From fc2671d7695408e27ab0ed10651844673a273ebd Mon Sep 17 00:00:00 2001
From: jaylfc <jaylfc25@gmail.com>
Date: Wed, 17 Jun 2026 00:24:25 +0100
Subject: [PATCH 1/3] feat(userspace): re-integrate web app-runtime foundation
 onto dev (#89 P3a)

---
 desktop/src/apps/SandboxedAppWindow.tsx       |  56 ++++++
 .../__tests__/SandboxedAppWindow.test.tsx     |  47 +++++
 .../src/lib/__tests__/userspace-apps.test.ts  |  72 +++++++
 desktop/src/lib/userspace-apps.ts             |  81 ++++++++
 desktop/src/registry/app-registry.ts          |   2 +-
 tests/userspace/__init__.py                   |   0
 tests/userspace/conftest.py                   |  75 +++++++
 tests/userspace/test_broker.py                | 133 +++++++++++++
 tests/userspace/test_broker_route.py          |  64 ++++++
 tests/userspace/test_data_store.py            |  34 ++++
 tests/userspace/test_e2e.py                   |  32 +++
 tests/userspace/test_immutability.py          |  39 ++++
 tests/userspace/test_install_security.py      |  43 ++++
 tests/userspace/test_package.py               |  54 +++++
 tests/userspace/test_routes.py                |  44 +++++
 tests/userspace/test_sdk_route.py             |   9 +
 tests/userspace/test_store.py                 |  83 ++++++++
 tests/userspace/test_update_consent.py        |  25 +++
 tests/userspace/test_url_guard.py             |  26 +++
 tinyagentos/app.py                            |  14 ++
 tinyagentos/routes/__init__.py                |   5 +-
 tinyagentos/routes/userspace_apps.py          | 186 ++++++++++++++++++
 tinyagentos/userspace/__init__.py             |   1 +
 tinyagentos/userspace/broker.py               | 116 +++++++++++
 tinyagentos/userspace/data_store.py           |  80 ++++++++
 tinyagentos/userspace/package.py              |  74 +++++++
 tinyagentos/userspace/sdk/taos-app-sdk.js     |  53 +++++
 tinyagentos/userspace/store.py                |  97 +++++++++
 tinyagentos/userspace/url_guard.py            |  47 +++++
 29 files changed, 1590 insertions(+), 2 deletions(-)
 create mode 100644 desktop/src/apps/SandboxedAppWindow.tsx
 create mode 100644 desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
 create mode 100644 desktop/src/lib/__tests__/userspace-apps.test.ts
 create mode 100644 desktop/src/lib/userspace-apps.ts
 create mode 100644 tests/userspace/__init__.py
 create mode 100644 tests/userspace/conftest.py
 create mode 100644 tests/userspace/test_broker.py
 create mode 100644 tests/userspace/test_broker_route.py
 create mode 100644 tests/userspace/test_data_store.py
 create mode 100644 tests/userspace/test_e2e.py
 create mode 100644 tests/userspace/test_immutability.py
 create mode 100644 tests/userspace/test_install_security.py
 create mode 100644 tests/userspace/test_package.py
 create mode 100644 tests/userspace/test_routes.py
 create mode 100644 tests/userspace/test_sdk_route.py
 create mode 100644 tests/userspace/test_store.py
 create mode 100644 tests/userspace/test_update_consent.py
 create mode 100644 tests/userspace/test_url_guard.py
 create mode 100644 tinyagentos/routes/userspace_apps.py
 create mode 100644 tinyagentos/userspace/__init__.py
 create mode 100644 tinyagentos/userspace/broker.py
 create mode 100644 tinyagentos/userspace/data_store.py
 create mode 100644 tinyagentos/userspace/package.py
 create mode 100644 tinyagentos/userspace/sdk/taos-app-sdk.js
 create mode 100644 tinyagentos/userspace/store.py
 create mode 100644 tinyagentos/userspace/url_guard.py

diff --git a/desktop/src/apps/SandboxedAppWindow.tsx b/desktop/src/apps/SandboxedAppWindow.tsx
new file mode 100644
index 000000000..c0f827827
--- /dev/null
+++ b/desktop/src/apps/SandboxedAppWindow.tsx
@@ -0,0 +1,56 @@
+// desktop/src/apps/SandboxedAppWindow.tsx
+import { useEffect, useRef } from "react";
+
+interface Props {
+  windowId: string;
+  appId: string;
+}
+
+interface BrokerRequest {
+  taosApp: string;
+  id: number;
+  capability: string;
+  args?: Record<string, unknown>;
+}
+
+export function SandboxedAppWindow({ appId }: Props) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  useEffect(() => {
+    async function onMessage(e: MessageEvent) {
+      const iframe = iframeRef.current;
+      // Only handle messages from THIS app's sandboxed iframe.
+      if (!iframe || e.source !== iframe.contentWindow) return;
+      const msg = e.data as BrokerRequest;
+      if (!msg || msg.taosApp !== appId || typeof msg.id !== "number" || !msg.capability) return;
+      let result: Record<string, unknown>;
+      try {
+        const res = await fetch(`/api/userspace-apps/${encodeURIComponent(appId)}/broker`, {
+          method: "POST",
+          // Carry the taos_session cookie so the broker authenticates the
+          // caller -- matches every other SPA API call, and stays correct
+          // under the Vite dev proxy (SPA :5173 -> API :6969).
+          credentials: "include",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ capability: msg.capability, args: msg.args || {} }),
+        });
+        result = res.ok ? await res.json() : { error: `broker_${res.status}` };
+      } catch {
+        result = { error: "broker_unreachable" };
+      }
+      iframe.contentWindow?.postMessage({ taosAppReply: msg.id, ...result }, "*");
+    }
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [appId]);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      title={appId}
+      src={`/api/userspace-apps/${encodeURIComponent(appId)}/bundle/index.html?app=${encodeURIComponent(appId)}`}
+      sandbox="allow-scripts"
+      className="w-full h-full border-0 bg-white"
+    />
+  );
+}
diff --git a/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx b/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
new file mode 100644
index 000000000..57f72be46
--- /dev/null
+++ b/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
@@ -0,0 +1,47 @@
+// desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { SandboxedAppWindow } from "../SandboxedAppWindow";
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("SandboxedAppWindow", () => {
+  it("renders a locked-down sandbox iframe pointed at the bundle", () => {
+    render(<SandboxedAppWindow windowId="w1" appId="todo" />);
+    const iframe = screen.getByTitle("todo") as HTMLIFrameElement;
+    expect(iframe.getAttribute("sandbox")).toBe("allow-scripts");
+    expect(iframe.getAttribute("src")).toBe("/api/userspace-apps/todo/bundle/index.html?app=todo");
+  });
+
+  it("bridges a capability message to the broker and posts the reply back", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ result: 42 }) });
+    vi.stubGlobal("fetch", fetchMock);
+    render(<SandboxedAppWindow windowId="w1" appId="todo" />);
+    const iframe = screen.getByTitle("todo") as HTMLIFrameElement;
+    const post = vi.fn();
+    Object.defineProperty(iframe, "contentWindow", { value: { postMessage: post }, configurable: true });
+
+    window.dispatchEvent(new MessageEvent("message", {
+      source: iframe.contentWindow as Window,
+      data: { taosApp: "todo", id: 1, capability: "app.kv.get", args: { key: "k" } },
+    }));
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(
+      "/api/userspace-apps/todo/broker",
+      expect.objectContaining({ method: "POST" }),
+    ));
+    await waitFor(() => expect(post).toHaveBeenCalledWith(
+      expect.objectContaining({ taosAppReply: 1, result: 42 }), "*"));
+  });
+
+  it("ignores messages from other sources", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    render(<SandboxedAppWindow windowId="w1" appId="todo" />);
+    window.dispatchEvent(new MessageEvent("message", {
+      source: window,  // not the iframe
+      data: { taosApp: "todo", id: 9, capability: "app.kv.get", args: {} },
+    }));
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/desktop/src/lib/__tests__/userspace-apps.test.ts b/desktop/src/lib/__tests__/userspace-apps.test.ts
new file mode 100644
index 000000000..708165b35
--- /dev/null
+++ b/desktop/src/lib/__tests__/userspace-apps.test.ts
@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { fetchUserspaceApps, toAppManifest, installUserspaceApp, grantUserspacePermissions } from "../userspace-apps";
+
+describe("userspace apps", () => {
+  it("maps a userspace app row to an AppManifest in the 'userspace' category", () => {
+    const m = toAppManifest({ app_id: "todo", name: "Todo", icon: "", app_type: "web", version: "1", enabled: 1, permissions_requested: [], permissions_granted: [] });
+    expect(m.id).toBe("todo");
+    expect(m.name).toBe("Todo");
+    expect(m.category).toBe("userspace");
+    expect(typeof m.component).toBe("function");
+  });
+
+  it("fetchUserspaceApps returns only enabled apps as manifests", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true, json: async () => [
+      { app_id: "a", name: "A", icon: "", app_type: "web", version: "1", enabled: 1, permissions_requested: [], permissions_granted: [] },
+      { app_id: "b", name: "B", icon: "", app_type: "web", version: "1", enabled: 0, permissions_requested: [], permissions_granted: [] },
+    ]}));
+    const apps = await fetchUserspaceApps();
+    expect(apps.map(a => a.id)).toEqual(["a"]);
+    vi.unstubAllGlobals();
+  });
+
+  it("fetchUserspaceApps returns [] on fetch failure", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false }));
+    expect(await fetchUserspaceApps()).toEqual([]);
+    vi.unstubAllGlobals();
+  });
+});
+
+describe("installUserspaceApp", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("posts multipart to install endpoint and returns parsed InstallResult", async () => {
+    const mockResult = { app_id: "todo", permissions_requested: ["app.net"], needs_consent: false, new_permissions: [] };
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true, json: async () => mockResult });
+    vi.stubGlobal("fetch", mockFetch);
+
+    const file = new File(["data"], "todo.taosapp");
+    const result = await installUserspaceApp(file);
+
+    expect(result).toEqual(mockResult);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/api/userspace-apps/install",
+      expect.objectContaining({ method: "POST", credentials: "include" })
+    );
+  });
+
+  it("throws with server error string when res.ok is false", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 400, json: async () => ({ error: "bundle too large" }) }));
+
+    const file = new File(["data"], "todo.taosapp");
+    await expect(installUserspaceApp(file)).rejects.toThrow("bundle too large");
+  });
+});
+
+describe("grantUserspacePermissions", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("posts JSON granted list to the permissions URL with credentials include", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", mockFetch);
+
+    await grantUserspacePermissions("todo", ["app.net"]);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/api/userspace-apps/todo/permissions",
+      expect.objectContaining({ method: "POST", credentials: "include" })
+    );
+    const callArgs = mockFetch.mock.calls[0][1];
+    expect(JSON.parse(callArgs.body)).toEqual({ granted: ["app.net"] });
+  });
+});
diff --git a/desktop/src/lib/userspace-apps.ts b/desktop/src/lib/userspace-apps.ts
new file mode 100644
index 000000000..e3ef38e6d
--- /dev/null
+++ b/desktop/src/lib/userspace-apps.ts
@@ -0,0 +1,81 @@
+import type { AppManifest } from "@/registry/app-registry";
+
+export interface UserspaceAppRow {
+  app_id: string;
+  name: string;
+  icon: string;
+  app_type: "web" | "container";
+  version: string;
+  enabled: number;
+  permissions_requested: string[];
+  permissions_granted: string[];
+}
+
+export function toAppManifest(row: UserspaceAppRow): AppManifest {
+  return {
+    id: row.app_id,
+    name: row.name,
+    icon: "layout-grid",
+    category: "userspace",
+    component: () =>
+      import("@/apps/SandboxedAppWindow").then((m) => ({
+        default: (props: { windowId: string }) =>
+          m.SandboxedAppWindow({ ...props, appId: row.app_id }),
+      })),
+    defaultSize: { w: 900, h: 600 },
+    minSize: { w: 360, h: 280 },
+    singleton: true,
+    pinned: false,
+    launchpadOrder: 100,
+  };
+}
+
+export interface InstallResult {
+  app_id: string;
+  permissions_requested: string[];
+  needs_consent: boolean;
+  new_permissions: string[];
+}
+
+export async function installUserspaceApp(file: File): Promise<InstallResult> {
+  const form = new FormData();
+  form.append("package", file);
+  const res = await fetch("/api/userspace-apps/install", {
+    method: "POST",
+    credentials: "include",
+    body: form,
+  });
+  if (!res.ok) {
+    let detail = `install failed (${res.status})`;
+    try {
+      const body = await res.json();
+      if (body?.error) detail = body.error;
+    } catch {
+      // non-JSON error body; keep the status-based message
+    }
+    throw new Error(detail);
+  }
+  return (await res.json()) as InstallResult;
+}
+
+export async function grantUserspacePermissions(appId: string, granted: string[]): Promise<void> {
+  const res = await fetch(`/api/userspace-apps/${encodeURIComponent(appId)}/permissions`, {
+    method: "POST",
+    credentials: "include",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ granted }),
+  });
+  if (!res.ok) throw new Error(`granting permissions failed (${res.status})`);
+}
+
+export async function fetchUserspaceApps(): Promise<AppManifest[]> {
+  let rows: UserspaceAppRow[];
+  try {
+    const res = await fetch("/api/userspace-apps");
+    if (!res.ok) return [];
+    rows = (await res.json()) as UserspaceAppRow[];
+  } catch {
+    return [];
+  }
+  return rows.filter((r) => r.enabled).map(toAppManifest);
+}
diff --git a/desktop/src/registry/app-registry.ts b/desktop/src/registry/app-registry.ts
index 592d9a466..a088f2959 100644
--- a/desktop/src/registry/app-registry.ts
+++ b/desktop/src/registry/app-registry.ts
@@ -4,7 +4,7 @@ export interface AppManifest {
   id: string;
   name: string;
   icon: string;
-  category: "platform" | "os" | "streaming" | "game";
+  category: "platform" | "os" | "streaming" | "game" | "userspace";
   component: () => Promise<{ default: ComponentType<{ windowId: string }> }>;
   defaultSize: { w: number; h: number };
   minSize: { w: number; h: number };
diff --git a/tests/userspace/__init__.py b/tests/userspace/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/userspace/conftest.py b/tests/userspace/conftest.py
new file mode 100644
index 000000000..e24a5ca75
--- /dev/null
+++ b/tests/userspace/conftest.py
@@ -0,0 +1,75 @@
+"""Shared fixtures for tests/userspace/ route-level tests."""
+from __future__ import annotations
+
+import pytest
+import pytest_asyncio
+import yaml
+from httpx import ASGITransport, AsyncClient
+
+from tinyagentos.app import create_app
+from tinyagentos.userspace.store import UserspaceAppStore
+from tinyagentos.userspace.data_store import UserspaceDataStore
+
+
+def _make_app(tmp_path):
+    config = {
+        "server": {"host": "0.0.0.0", "port": 6969},
+        "backends": [],
+        "qmd": {"url": "http://localhost:7832"},
+        "agents": [],
+        "metrics": {"poll_interval": 30, "retention_days": 30},
+    }
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(yaml.dump(config))
+    (tmp_path / ".setup_complete").touch()
+    app = create_app(data_dir=tmp_path)
+    from tinyagentos.routes.desktop_browser.vapid import load_or_create_vapid_keypair
+    app.state.vapid_keypair = load_or_create_vapid_keypair(tmp_path)
+    return app
+
+
+@pytest.fixture
+def app(tmp_path):
+    return _make_app(tmp_path)
+
+
+@pytest_asyncio.fixture
+async def client(app, tmp_path):
+    """Async client with userspace stores initialised and auth set up."""
+    # Initialise the minimal set of stores that routes require.
+    await app.state.metrics.init()
+    await app.state.notifications.init()
+    await app.state.qmd_client.init()
+    await app.state.secrets.init()
+
+    # Userspace stores -- created fresh per test in tmp_path.
+    userspace_apps = UserspaceAppStore(tmp_path / "userspace_apps.db")
+    await userspace_apps.init()
+    app.state.userspace_apps = userspace_apps
+
+    userspace_data = UserspaceDataStore(tmp_path / "userspace_data.db")
+    await userspace_data.init()
+    app.state.userspace_data = userspace_data
+
+    # Auth setup.
+    app.state.auth.setup_user("admin", "Test Admin", "", "testpass")
+    record = app.state.auth.find_user("admin")
+    uid = record["id"] if record else ""
+    token = app.state.auth.create_session(user_id=uid, long_lived=True)
+    app.state._startup_complete = True
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(
+        transport=transport,
+        base_url="http://test",
+        cookies={"taos_session": token},
+    ) as c:
+        yield c
+
+    await userspace_data.close()
+    await userspace_apps.close()
+    await app.state.secrets.close()
+    await app.state.qmd_client.close()
+    await app.state.notifications.close()
+    await app.state.metrics.close()
+    await app.state.http_client.aclose()
diff --git a/tests/userspace/test_broker.py b/tests/userspace/test_broker.py
new file mode 100644
index 000000000..a61980dba
--- /dev/null
+++ b/tests/userspace/test_broker.py
@@ -0,0 +1,133 @@
+import pytest
+from tinyagentos.userspace.broker import handle_capability, FREE_CAPS, GATED_CAPS
+from tinyagentos.userspace.data_store import UserspaceDataStore
+
+
+async def _store(tmp_path):
+    s = UserspaceDataStore(tmp_path / "d.db"); await s.init(); return s
+
+
+@pytest.mark.asyncio
+async def test_ungranted_gated_capability_denied(tmp_path):
+    s = await _store(tmp_path)
+    out = await handle_capability("todo", "app.memory.search", {"q": "x"},
+                                  granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert out == {"error": "permission_denied", "capability": "app.memory.search"}
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_free_kv_capability_allowed_and_scoped(tmp_path):
+    s = await _store(tmp_path)
+    await handle_capability("todo", "app.kv.set", {"key": "k", "value": 1},
+                            granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    out = await handle_capability("todo", "app.kv.get", {"key": "k"},
+                                  granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert out["result"] == 1
+    other = await handle_capability("evil", "app.kv.get", {"key": "k"},
+                                    granted=[], data_store=s, app_dir=tmp_path / "evil", services={})
+    assert other["result"] is None   # evil app cannot see todo's data
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_table_capabilities(tmp_path):
+    s = await _store(tmp_path)
+    ins = await handle_capability("todo", "app.table.insert", {"table": "t", "row": {"x": 1}},
+                                  granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert isinstance(ins["result"], int)
+    q = await handle_capability("todo", "app.table.query", {"table": "t"},
+                                granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert q["result"][0]["x"] == 1
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_gated_capability_allowed_when_granted(tmp_path):
+    s = await _store(tmp_path)
+
+    class FakeMemory:
+        async def search(self, q):
+            return [{"text": "hit"}]
+
+    out = await handle_capability("todo", "app.memory.search", {"q": "x"},
+                                  granted=["app.memory"], data_store=s,
+                                  app_dir=tmp_path / "todo", services={"memory": FakeMemory()})
+    assert out["result"] == [{"text": "hit"}]
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_files_jailed_to_app_dir(tmp_path):
+    s = await _store(tmp_path)
+    (tmp_path / "todo" / "files").mkdir(parents=True)
+    out = await handle_capability("todo", "app.files.read", {"path": "../../etc/passwd"},
+                                  granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert out["error"] == "invalid_path"
+    # legit write+read within the jail works
+    await handle_capability("todo", "app.files.write", {"path": "note.txt", "content": "hi"},
+                            granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    rd = await handle_capability("todo", "app.files.read", {"path": "note.txt"},
+                                 granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert rd["result"] == "hi"
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_unknown_capability_rejected(tmp_path):
+    s = await _store(tmp_path)
+    out = await handle_capability("todo", "app.evil.hack", {}, granted=["app.evil"],
+                                  data_store=s, app_dir=tmp_path / "todo", services={})
+    assert out["error"] == "unknown_capability"
+    await s.close()
+
+
+def test_capability_sets():
+    assert "app.net" in GATED_CAPS and "app.memory" in GATED_CAPS
+    assert "app.kv" in FREE_CAPS and "app.net" not in FREE_CAPS
+
+
+# --- Finding 1: app.net path traversal + header filtering ---
+
+import types
+from unittest.mock import AsyncMock, patch
+
+
+@pytest.mark.asyncio
+async def test_app_net_rejects_dotdot_traversal(tmp_path):
+    """.. segments in the path must be blocked before any HTTP call is made."""
+    s = await _store(tmp_path)
+    out = await handle_capability(
+        "echo", "app.net", {"path": "../../secret"},
+        granted=["app.net"], data_store=s, app_dir=tmp_path / "echo",
+        services={"app_backend_url": "http://127.0.0.1:13042"},
+    )
+    assert out == {"error": "invalid_path"}
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_app_net_blocks_dangerous_headers_and_passes_safe_ones(tmp_path):
+    """Host (and other blocked headers) must be stripped; X-Ok must reach the backend."""
+    s = await _store(tmp_path)
+    fake_resp = types.SimpleNamespace(status_code=200, text="ok")
+    with patch("tinyagentos.userspace.broker.httpx.AsyncClient") as mock_client:
+        mock_request = AsyncMock(return_value=fake_resp)
+        mock_client.return_value.__aenter__ = AsyncMock(
+            return_value=types.SimpleNamespace(request=mock_request)
+        )
+        mock_client.return_value.__aexit__ = AsyncMock(return_value=False)
+
+        out = await handle_capability(
+            "echo", "app.net", {"path": "/ping", "headers": {"Host": "evil", "X-Ok": "1"}},
+            granted=["app.net"], data_store=s, app_dir=tmp_path / "echo",
+            services={"app_backend_url": "http://127.0.0.1:13042"},
+        )
+
+    assert out == {"result": {"status": 200, "body": "ok"}}
+    _, call_kwargs = mock_request.call_args
+    sent_headers = call_kwargs.get("headers") or {}
+    lower_keys = {k.lower() for k in sent_headers}
+    assert "host" not in lower_keys, "Host header must be stripped"
+    assert "x-ok" in lower_keys, "X-Ok header must be forwarded"
+    await s.close()
diff --git a/tests/userspace/test_broker_route.py b/tests/userspace/test_broker_route.py
new file mode 100644
index 000000000..e31c2a9eb
--- /dev/null
+++ b/tests/userspace/test_broker_route.py
@@ -0,0 +1,64 @@
+import io, types, zipfile
+import pytest
+from unittest.mock import AsyncMock, patch
+
+MANIFEST = "id: todo\nname: Todo\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: [app.memory]\n"
+
+
+def _zip():
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", MANIFEST)
+        z.writestr("index.html", "<h1>todo</h1>")
+        z.writestr("icon.png", "x")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_broker_enforces_granted(client):
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("todo.taosapp", _zip(), "application/zip")})
+    # free cap works without any grant
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.kv.set", "args": {"key": "k", "value": 5}})
+    assert r.status_code == 200 and r.json()["result"] is True
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.kv.get", "args": {"key": "k"}})
+    assert r.json()["result"] == 5
+    # gated cap denied until granted
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.memory.search", "args": {"q": "x"}})
+    assert r.json()["error"] == "permission_denied"
+    await client.post("/api/userspace-apps/todo/permissions", json={"granted": ["app.memory"]})
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.memory.search", "args": {"q": "x"}})
+    assert "error" not in r.json()
+
+
+@pytest.mark.asyncio
+async def test_broker_404_for_unknown_app(client):
+    r = await client.post("/api/userspace-apps/ghost/broker",
+                          json={"capability": "app.kv.get", "args": {"key": "k"}})
+    assert r.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_app_net_denied_without_grant(client):
+    """app.net is a gated capability and must be denied if not explicitly granted."""
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("todo.taosapp", _zip(), "application/zip")})
+    # do NOT grant app.net
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.net", "args": {"path": "/ping"}})
+    assert r.json()["error"] == "permission_denied"
+
+
+@pytest.mark.asyncio
+async def test_app_net_no_backend_returns_error(client):
+    """app.net granted on a web app (no container backend) returns no_backend."""
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("todo.taosapp", _zip(), "application/zip")})
+    await client.post("/api/userspace-apps/todo/permissions", json={"granted": ["app.net"]})
+    r = await client.post("/api/userspace-apps/todo/broker",
+                          json={"capability": "app.net", "args": {"path": "/ping"}})
+    assert r.json() == {"error": "no_backend"}
diff --git a/tests/userspace/test_data_store.py b/tests/userspace/test_data_store.py
new file mode 100644
index 000000000..6e74d198c
--- /dev/null
+++ b/tests/userspace/test_data_store.py
@@ -0,0 +1,34 @@
+import pytest
+from tinyagentos.userspace.data_store import UserspaceDataStore
+
+
+@pytest.mark.asyncio
+async def test_kv_namespaced_per_app(tmp_path):
+    s = UserspaceDataStore(tmp_path / "d.db"); await s.init()
+    await s.kv_set("appA", "k", {"v": 1})
+    await s.kv_set("appB", "k", {"v": 2})
+    assert await s.kv_get("appA", "k") == {"v": 1}
+    assert await s.kv_get("appB", "k") == {"v": 2}
+    assert await s.kv_get("appA", "missing") is None
+    assert await s.kv_keys("appA") == ["k"]
+    await s.kv_delete("appA", "k")
+    assert await s.kv_get("appA", "k") is None
+    assert await s.kv_get("appB", "k") == {"v": 2}  # appB untouched
+    await s.close()
+
+
+@pytest.mark.asyncio
+async def test_table_insert_query_delete_scoped(tmp_path):
+    s = UserspaceDataStore(tmp_path / "d.db"); await s.init()
+    rid = await s.table_insert("appA", "todos", {"text": "buy milk", "done": False})
+    assert isinstance(rid, int)
+    await s.table_insert("appB", "todos", {"text": "other"})
+    rows = await s.table_query("appA", "todos", None)
+    assert len(rows) == 1 and rows[0]["text"] == "buy milk" and rows[0]["id"] == rid
+    filtered = await s.table_query("appA", "todos", {"done": False})
+    assert len(filtered) == 1 and filtered[0]["text"] == "buy milk"
+    assert await s.table_query("appA", "todos", {"done": True}) == []
+    await s.table_delete("appA", "todos", rid)
+    assert await s.table_query("appA", "todos", None) == []
+    assert len(await s.table_query("appB", "todos", None)) == 1  # appB untouched
+    await s.close()
diff --git a/tests/userspace/test_e2e.py b/tests/userspace/test_e2e.py
new file mode 100644
index 000000000..c22be9386
--- /dev/null
+++ b/tests/userspace/test_e2e.py
@@ -0,0 +1,32 @@
+# tests/userspace/test_e2e.py
+import io, zipfile
+import pytest
+
+
+def _todo_zip():
+    manifest = "id: todo\nname: Todo\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: []\n"
+    html = '<script src="/api/userspace-apps/sdk.js?app=todo"></script>'
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", manifest)
+        z.writestr("index.html", html)
+        z.writestr("icon.png", "x")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_install_use_isolate_uninstall(client, tmp_path):
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("todo.taosapp", _todo_zip(), "application/zip")})
+    # use via broker
+    await client.post("/api/userspace-apps/todo/broker",
+                      json={"capability": "app.table.insert", "args": {"table": "t", "row": {"text": "milk"}}})
+    rows = (await client.post("/api/userspace-apps/todo/broker",
+            json={"capability": "app.table.query", "args": {"table": "t"}})).json()["result"]
+    assert len(rows) == 1 and rows[0]["text"] == "milk"
+    # uninstall removes registry
+    await client.delete("/api/userspace-apps/todo")
+    assert all(a["app_id"] != "todo" for a in (await client.get("/api/userspace-apps")).json())
+    after = (await client.post("/api/userspace-apps/todo/broker",
+             json={"capability": "app.table.query", "args": {"table": "t"}}))
+    assert after.status_code == 404  # app gone
diff --git a/tests/userspace/test_immutability.py b/tests/userspace/test_immutability.py
new file mode 100644
index 000000000..1c8d940a3
--- /dev/null
+++ b/tests/userspace/test_immutability.py
@@ -0,0 +1,39 @@
+# tests/userspace/test_immutability.py
+import io, zipfile
+import pytest
+from tinyagentos.userspace.package import parse_manifest, PackageError
+
+
+def test_native_app_type_rejected():
+    with pytest.raises(PackageError, match="native"):
+        parse_manifest("id: x\nname: X\nversion: 1\napp_type: native\n")
+
+
+@pytest.mark.asyncio
+async def test_bundle_path_traversal_blocked(client):
+    m = "id: t\nname: T\nversion: 1\napp_type: web\nentry: index.html\nicon: i\npermissions: []\n"
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", m)
+        z.writestr("index.html", "x")
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("t.taosapp", buf.getvalue(), "application/zip")})
+    r = await client.get("/api/userspace-apps/t/bundle/../../../etc/passwd")
+    assert r.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_cross_app_data_isolation(client):
+    for app in ("a", "b"):
+        m = f"id: {app}\nname: {app}\nversion: 1\napp_type: web\nentry: index.html\nicon: i\npermissions: []\n"
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w") as z:
+            z.writestr("manifest.yaml", m)
+            z.writestr("index.html", "x")
+        await client.post("/api/userspace-apps/install",
+                          files={"package": (f"{app}.taosapp", buf.getvalue(), "application/zip")})
+    await client.post("/api/userspace-apps/a/broker",
+                      json={"capability": "app.kv.set", "args": {"key": "secret", "value": 1}})
+    out = (await client.post("/api/userspace-apps/b/broker",
+           json={"capability": "app.kv.get", "args": {"key": "secret"}})).json()
+    assert out["result"] is None  # b cannot read a's data
diff --git a/tests/userspace/test_install_security.py b/tests/userspace/test_install_security.py
new file mode 100644
index 000000000..5c30b9af9
--- /dev/null
+++ b/tests/userspace/test_install_security.py
@@ -0,0 +1,43 @@
+"""Security regressions for the userspace install/bundle routes:
+- source_url install must not be SSRF-able to internal addresses
+- served bundles must carry the CSP `sandbox` directive (cannot execute on the
+  core origin even on a direct navigation).
+"""
+import io
+import zipfile
+
+import pytest
+
+WEB_MANIFEST = "id: sec\nname: Sec\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: []\n"
+
+
+def _zip():
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", WEB_MANIFEST)
+        z.writestr("index.html", "<h1>sec</h1>")
+        z.writestr("icon.png", "x")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_install_source_url_ssrf_blocked(client):
+    for bad in (
+        "http://169.254.169.254/latest/meta-data",
+        "http://127.0.0.1:6969/api/agents",
+        "http://10.0.0.5/x",
+    ):
+        r = await client.post("/api/userspace-apps/install", json={"source_url": bad})
+        assert r.status_code == 400, bad
+        assert "not allowed" in r.json()["error"]
+
+
+@pytest.mark.asyncio
+async def test_bundle_csp_has_sandbox_directive(client):
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("sec.taosapp", _zip(), "application/zip")})
+    r = await client.get("/api/userspace-apps/sec/bundle/index.html")
+    assert r.status_code == 200
+    csp = r.headers.get("content-security-policy", "").lower()
+    assert "sandbox" in csp           # forces opaque origin on direct nav
+    assert "allow-same-origin" not in csp  # never grant same-origin to a bundle
diff --git a/tests/userspace/test_package.py b/tests/userspace/test_package.py
new file mode 100644
index 000000000..e2cb4d7d8
--- /dev/null
+++ b/tests/userspace/test_package.py
@@ -0,0 +1,54 @@
+import io, zipfile
+import pytest
+from tinyagentos.userspace.package import parse_manifest, extract_package, PackageError
+
+
+def _zip(manifest: str, files: dict[str, str]) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", manifest)
+        for name, content in files.items():
+            z.writestr(name, content)
+    return buf.getvalue()
+
+
+WEB_MANIFEST = """
+id: todo
+name: Todo
+version: 1.0.0
+app_type: web
+entry: index.html
+icon: icon.png
+permissions: [app.net]
+"""
+
+
+def test_parse_valid_web_manifest():
+    m = parse_manifest(WEB_MANIFEST)
+    assert m["id"] == "todo"
+    assert m["app_type"] == "web"
+    assert m["permissions"] == ["app.net"]
+
+
+def test_native_app_type_rejected():
+    with pytest.raises(PackageError, match="native"):
+        parse_manifest(WEB_MANIFEST.replace("app_type: web", "app_type: native"))
+
+
+def test_missing_required_field_rejected():
+    with pytest.raises(PackageError, match="required"):
+        parse_manifest("name: NoId\nversion: 1\napp_type: web\n")
+
+
+def test_extract_writes_files(tmp_path):
+    data = _zip(WEB_MANIFEST, {"index.html": "<h1>hi</h1>", "icon.png": "x"})
+    manifest = extract_package(data, apps_root=tmp_path)
+    app_dir = tmp_path / "todo"
+    assert (app_dir / "index.html").read_text() == "<h1>hi</h1>"
+    assert manifest["id"] == "todo"
+
+
+def test_extract_rejects_path_traversal(tmp_path):
+    data = _zip(WEB_MANIFEST, {"../evil.txt": "pwned"})
+    with pytest.raises(PackageError, match="unsafe path"):
+        extract_package(data, apps_root=tmp_path)
diff --git a/tests/userspace/test_routes.py b/tests/userspace/test_routes.py
new file mode 100644
index 000000000..b77b03c07
--- /dev/null
+++ b/tests/userspace/test_routes.py
@@ -0,0 +1,44 @@
+import io, zipfile
+import pytest
+
+WEB_MANIFEST = "id: todo\nname: Todo\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: [app.net]\n"
+
+
+def _zip():
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", WEB_MANIFEST)
+        z.writestr("index.html", "<h1>todo</h1>")
+        z.writestr("icon.png", "x")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_install_list_bundle_uninstall(client):
+    r = await client.post("/api/userspace-apps/install",
+                          files={"package": ("todo.taosapp", _zip(), "application/zip")})
+    assert r.status_code == 200, r.text
+    assert r.json()["app_id"] == "todo"
+    assert r.json()["permissions_requested"] == ["app.net"]
+
+    r = await client.get("/api/userspace-apps")
+    assert any(a["app_id"] == "todo" for a in r.json())
+
+    r = await client.get("/api/userspace-apps/todo/bundle/index.html")
+    assert r.status_code == 200
+    assert "todo" in r.text
+    csp = r.headers.get("content-security-policy", "").lower()
+    assert "frame-ancestors" in csp or "default-src" in csp
+
+    r = await client.delete("/api/userspace-apps/todo")
+    assert r.status_code == 200
+    rows = (await client.get("/api/userspace-apps")).json()
+    assert all(a["app_id"] != "todo" for a in rows)
+
+
+@pytest.mark.asyncio
+async def test_bundle_path_traversal_404(client):
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("todo.taosapp", _zip(), "application/zip")})
+    r = await client.get("/api/userspace-apps/todo/bundle/../../../etc/passwd")
+    assert r.status_code == 404
diff --git a/tests/userspace/test_sdk_route.py b/tests/userspace/test_sdk_route.py
new file mode 100644
index 000000000..b6d1e26d1
--- /dev/null
+++ b/tests/userspace/test_sdk_route.py
@@ -0,0 +1,9 @@
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_sdk_served(client):
+    r = await client.get("/api/userspace-apps/sdk.js")
+    assert r.status_code == 200
+    assert "application/javascript" in r.headers["content-type"]
+    assert "window.taos" in r.text
diff --git a/tests/userspace/test_store.py b/tests/userspace/test_store.py
new file mode 100644
index 000000000..2d1fffd0a
--- /dev/null
+++ b/tests/userspace/test_store.py
@@ -0,0 +1,83 @@
+import pytest
+from tinyagentos.userspace.store import UserspaceAppStore
+
+
+@pytest.mark.asyncio
+async def test_install_list_and_uninstall(tmp_path):
+    store = UserspaceAppStore(tmp_path / "userspace_apps.db")
+    await store.init()
+    await store.install(
+        app_id="todo", name="Todo", version="1.0.0", app_type="web",
+        entry="index.html", icon="icon.png", permissions_requested=["app.net"],
+    )
+    rows = await store.list_installed()
+    assert len(rows) == 1
+    assert rows[0]["app_id"] == "todo"
+    assert rows[0]["app_type"] == "web"
+    assert rows[0]["enabled"] == 1
+    assert rows[0]["permissions_granted"] == []
+    assert rows[0]["permissions_requested"] == ["app.net"]
+    assert await store.uninstall("todo") is True
+    assert await store.list_installed() == []
+    await store.close()
+
+
+@pytest.mark.asyncio
+async def test_set_permissions_and_enabled(tmp_path):
+    store = UserspaceAppStore(tmp_path / "u.db")
+    await store.init()
+    await store.install(app_id="a", name="A", version="1", app_type="web",
+                        entry="index.html", icon="i.png",
+                        permissions_requested=["app.net", "app.memory"])
+    await store.set_permissions_granted("a", ["app.net"])
+    await store.set_enabled("a", False)
+    row = await store.get("a")
+    assert row["permissions_granted"] == ["app.net"]
+    assert row["enabled"] == 0
+    await store.close()
+
+
+@pytest.mark.asyncio
+async def test_fresh_install_has_no_runtime_location(tmp_path):
+    store = UserspaceAppStore(tmp_path / "rt.db")
+    await store.init()
+    await store.install(app_id="ctr", name="Ctr", version="1.0.0",
+                        app_type="container", entry="index.html", icon="",
+                        permissions_requested=[])
+    row = await store.get("ctr")
+    assert row["container_host"] is None
+    assert row["container_port"] is None
+    await store.close()
+
+
+@pytest.mark.asyncio
+async def test_set_runtime_location(tmp_path):
+    store = UserspaceAppStore(tmp_path / "rt2.db")
+    await store.init()
+    await store.install(app_id="ctr", name="Ctr", version="1.0.0",
+                        app_type="container", entry="index.html", icon="",
+                        permissions_requested=[])
+    await store.set_runtime_location("ctr", "127.0.0.1", 13042)
+    row = await store.get("ctr")
+    assert row["container_host"] == "127.0.0.1"
+    assert row["container_port"] == 13042
+    await store.close()
+
+
+@pytest.mark.asyncio
+async def test_reinstall_preserves_runtime_location(tmp_path):
+    store = UserspaceAppStore(tmp_path / "rt3.db")
+    await store.init()
+    await store.install(app_id="ctr", name="Ctr", version="1.0.0",
+                        app_type="container", entry="index.html", icon="",
+                        permissions_requested=[])
+    await store.set_runtime_location("ctr", "127.0.0.1", 13042)
+    # Re-install (upsert) should not wipe the runtime location
+    await store.install(app_id="ctr", name="Ctr v2", version="1.0.1",
+                        app_type="container", entry="index.html", icon="",
+                        permissions_requested=[])
+    row = await store.get("ctr")
+    assert row["container_host"] == "127.0.0.1"
+    assert row["container_port"] == 13042
+    assert row["version"] == "1.0.1"
+    await store.close()
diff --git a/tests/userspace/test_update_consent.py b/tests/userspace/test_update_consent.py
new file mode 100644
index 000000000..a3e26a142
--- /dev/null
+++ b/tests/userspace/test_update_consent.py
@@ -0,0 +1,25 @@
+# tests/userspace/test_update_consent.py -- install v1 (app.net), then "update" requesting app.memory too
+import io, zipfile
+import pytest
+
+
+def _zip(perms):
+    m = f"id: todo\nname: Todo\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: {perms}\n"
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", m)
+        z.writestr("index.html", "x")
+        z.writestr("icon.png", "x")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_update_with_new_permission_flags_consent(client):
+    await client.post("/api/userspace-apps/install",
+                      files={"package": ("t.taosapp", _zip("[app.net]"), "application/zip")})
+    await client.post("/api/userspace-apps/todo/permissions", json={"granted": ["app.net"]})
+    r = await client.post("/api/userspace-apps/install",
+                          files={"package": ("t.taosapp", _zip("[app.net, app.memory]"), "application/zip")})
+    body = r.json()
+    assert body["needs_consent"] is True
+    assert "app.memory" in body["new_permissions"]
diff --git a/tests/userspace/test_url_guard.py b/tests/userspace/test_url_guard.py
new file mode 100644
index 000000000..1b4e8b6e9
--- /dev/null
+++ b/tests/userspace/test_url_guard.py
@@ -0,0 +1,26 @@
+from tinyagentos.userspace.url_guard import is_safe_public_url
+
+
+def test_blocks_link_local_metadata_endpoint():
+    assert is_safe_public_url("http://169.254.169.254/latest/meta-data") is False
+
+
+def test_blocks_loopback_and_private():
+    assert is_safe_public_url("http://127.0.0.1/x") is False
+    assert is_safe_public_url("http://10.0.0.1/x") is False
+    assert is_safe_public_url("https://192.168.1.1/x") is False
+
+
+def test_blocks_non_http_scheme():
+    assert is_safe_public_url("ftp://example.com/x") is False
+    assert is_safe_public_url("file:///etc/passwd") is False
+
+
+def test_allows_public_ip():
+    # literal public IP -- getaddrinfo returns it without DNS
+    assert is_safe_public_url("https://8.8.8.8/app.taosapp") is True
+
+
+def test_rejects_garbage():
+    assert is_safe_public_url("not a url") is False
+    assert is_safe_public_url("http://") is False
diff --git a/tinyagentos/app.py b/tinyagentos/app.py
index fc400b5ce..6f6e3f213 100644
--- a/tinyagentos/app.py
+++ b/tinyagentos/app.py
@@ -340,6 +340,10 @@ async def _probe_backend(backend: dict) -> dict:
     user_memory = UserMemoryStore(data_dir / "user_memory.db")
     user_personas = UserPersonaStore(data_dir / "user_personas.db")
     installed_apps = InstalledAppsStore(data_dir / "installed_apps.db")
+    from tinyagentos.userspace.store import UserspaceAppStore
+    from tinyagentos.userspace.data_store import UserspaceDataStore
+    userspace_apps = UserspaceAppStore(data_dir / "userspace_apps.db")
+    userspace_data = UserspaceDataStore(data_dir / "userspace_data.db")
     skills = SkillStore(data_dir / "skills.db")
     from tinyagentos.themes.store import ThemeStore
     themes = ThemeStore(data_dir / "themes.sqlite3")
@@ -416,6 +420,10 @@ async def lifespan(app: FastAPI):
         await desktop_settings.init()
         await user_memory.init()
         await installed_apps.init()
+        await userspace_apps.init()
+        app.state.userspace_apps = userspace_apps
+        await userspace_data.init()
+        app.state.userspace_data = userspace_data
         await skills.init()
         await themes.init()
         app.state.themes = themes
@@ -657,6 +665,8 @@ async def _browser_reap_loop(app: FastAPI) -> None:
         app.state.user_memory = user_memory
         app.state.user_personas = user_personas
         app.state.installed_apps = installed_apps
+        app.state.userspace_apps = userspace_apps
+        app.state.userspace_data = userspace_data
         app.state.skills = skills
         app.state.benchmark_store = benchmark_store
         app.state.score_cache = score_cache
@@ -1109,6 +1119,8 @@ async def _reload_llm_proxy_on_catalog_change() -> None:
         await knowledge_graph.close()
         await archive.close()
         await installed_apps.close()
+        await userspace_apps.close()
+        await userspace_data.close()
         await user_memory.close()
         await desktop_settings.close()
         await canvas_store.close()
@@ -1281,6 +1293,8 @@ async def dispatch(self, request, call_next):
     app.state.user_memory = user_memory
     app.state.user_personas = user_personas
     app.state.installed_apps = installed_apps
+    app.state.userspace_apps = userspace_apps
+    app.state.userspace_data = userspace_data
     app.state.skills = skills
     app.state.themes = themes
     app.state.knowledge_store = knowledge_store
diff --git a/tinyagentos/routes/__init__.py b/tinyagentos/routes/__init__.py
index 339681d2a..489c045f2 100644
--- a/tinyagentos/routes/__init__.py
+++ b/tinyagentos/routes/__init__.py
@@ -284,8 +284,11 @@ def register_all_routers(app):
     from tinyagentos.routes.events import router as events_router
     app.include_router(events_router)
 
-    # OTLP/HTTP+JSON receiver — Phase 2 observability.
+    # OTLP/HTTP+JSON receiver -- Phase 2 observability.
     # POST /v1/traces accepts ExportTraceServiceRequest JSON and writes spans
     # to the per-agent SpanStore (app.state.span_store_registry).
     from tinyagentos.otel.receiver import router as otel_receiver_router
     app.include_router(otel_receiver_router)
+
+    from tinyagentos.routes.userspace_apps import router as userspace_apps_router
+    app.include_router(userspace_apps_router)
diff --git a/tinyagentos/routes/userspace_apps.py b/tinyagentos/routes/userspace_apps.py
new file mode 100644
index 000000000..af24e5c70
--- /dev/null
+++ b/tinyagentos/routes/userspace_apps.py
@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import httpx
+from fastapi import APIRouter, Request, UploadFile, File
+from fastapi.responses import JSONResponse, FileResponse, Response
+
+from tinyagentos.userspace.broker import handle_capability
+from tinyagentos.userspace.package import extract_package, PackageError
+from tinyagentos.userspace.url_guard import is_safe_public_url
+
+router = APIRouter()
+
+_SDK_PATH = Path(__file__).resolve().parent.parent / "userspace" / "sdk" / "taos-app-sdk.js"
+
+# Bundle CSP. The `sandbox allow-scripts` directive (no allow-same-origin)
+# forces the document into an OPAQUE origin even on a direct top-level
+# navigation -- so a userspace bundle can never execute on the core origin with
+# the session cookie (defends against stored XSS), while still letting the app
+# run its own scripts inside our sandboxed iframe. `default-src 'none'` plus
+# the explicit self/inline allowances keep it locked down.
+_BUNDLE_CSP = (
+    "sandbox allow-scripts allow-forms allow-popups; "
+    "default-src 'none'; "
+    "script-src 'self' 'unsafe-inline' blob:; "
+    "style-src 'self' 'unsafe-inline'; "
+    "img-src 'self' data: blob:; "
+    "font-src 'self' data:; "
+    "connect-src 'self'; "
+    "frame-ancestors 'self'; base-uri 'none'"
+)
+
+
+def _apps_root(request: Request) -> Path:
+    return Path(request.app.state.data_dir) / "apps"
+
+
+@router.get("/api/userspace-apps/sdk.js")
+async def serve_sdk(request: Request):
+    resp = FileResponse(_SDK_PATH, media_type="application/javascript")
+    resp.headers["Cache-Control"] = "no-cache"
+    return resp
+
+
+@router.get("/api/userspace-apps")
+async def list_apps(request: Request):
+    return await request.app.state.userspace_apps.list_installed()
+
+
+@router.post("/api/userspace-apps/install")
+async def install_app(request: Request, package: UploadFile | None = File(default=None)):
+    store = request.app.state.userspace_apps
+    if package is not None:
+        data = await package.read()
+    else:
+        body = await request.json()
+        url = body.get("source_url")
+        if not url:
+            return JSONResponse({"error": "source_url or package required"}, status_code=400)
+        # SSRF guard: only fetch public http(s) hosts, and do not follow
+        # redirects (a 3xx could bounce to a blocked internal address).
+        if not is_safe_public_url(url):
+            return JSONResponse(
+                {"error": "source_url is not allowed -- only public http(s) hosts "
+                          "(no private, loopback, link-local or reserved addresses)"},
+                status_code=400,
+            )
+        async with httpx.AsyncClient(timeout=120, follow_redirects=False) as c:
+            resp = await c.get(url)
+            resp.raise_for_status()
+            data = resp.content
+    try:
+        manifest = extract_package(data, apps_root=_apps_root(request))
+    except PackageError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=400)
+    existing = await store.get(manifest["id"])
+    new_perms = [
+        p for p in manifest["permissions"]
+        if existing and p not in existing["permissions_granted"]
+    ]
+    await store.install(
+        app_id=manifest["id"], name=manifest["name"], version=manifest["version"],
+        app_type=manifest["app_type"], entry=manifest["entry"], icon=manifest["icon"],
+        permissions_requested=manifest["permissions"],
+    )
+    deploy_info: dict = {}
+    if manifest["app_type"] == "container":
+        # Container deploy is not yet wired in this phase (web-only).
+        # Re-installs of container apps are accepted and stored, but not deployed.
+        raise NotImplementedError("container packages: web-only for now")
+    return {
+        "app_id": manifest["id"],
+        "permissions_requested": manifest["permissions"],
+        "needs_consent": bool(existing and new_perms),
+        "new_permissions": new_perms,
+        **deploy_info,
+    }
+
+
+@router.post("/api/userspace-apps/{app_id}/permissions")
+async def set_permissions(request: Request, app_id: str):
+    body = await request.json()
+    await request.app.state.userspace_apps.set_permissions_granted(app_id, body.get("granted", []))
+    return {"status": "ok"}
+
+
+@router.post("/api/userspace-apps/{app_id}/enable")
+async def enable_app(request: Request, app_id: str):
+    await request.app.state.userspace_apps.set_enabled(app_id, True)
+    return {"status": "ok"}
+
+
+@router.post("/api/userspace-apps/{app_id}/disable")
+async def disable_app(request: Request, app_id: str):
+    await request.app.state.userspace_apps.set_enabled(app_id, False)
+    return {"status": "ok"}
+
+
+@router.delete("/api/userspace-apps/{app_id}")
+async def uninstall_app(request: Request, app_id: str):
+    store = request.app.state.userspace_apps
+    removed = await store.uninstall(app_id)
+    root = _apps_root(request).resolve()
+    app_dir = (root / app_id).resolve()
+    if str(app_dir).startswith(str(root) + "/") and app_dir.exists():
+        shutil.rmtree(app_dir, ignore_errors=True)
+    return {"status": "ok", "removed": removed}
+
+
+@router.get("/api/userspace-apps/{app_id}/bundle/{path:path}")
+async def serve_bundle(request: Request, app_id: str, path: str):
+    root = (_apps_root(request) / app_id).resolve()
+    target = (root / path).resolve()
+    if not str(target).startswith(str(root) + "/") or not target.is_file():
+        return JSONResponse({"error": "not found"}, status_code=404)
+    resp = FileResponse(target)
+    resp.headers["Content-Security-Policy"] = _BUNDLE_CSP
+    resp.headers["X-Content-Type-Options"] = "nosniff"
+    return resp
+
+
+@router.get("/api/userspace-apps/{app_id}/icon")
+async def serve_icon(request: Request, app_id: str):
+    app = await request.app.state.userspace_apps.get(app_id)
+    if not app or not app["icon"]:
+        return Response(status_code=404)
+    root = (_apps_root(request) / app_id).resolve()
+    icon = (root / app["icon"]).resolve()
+    if not str(icon).startswith(str(root) + "/") or not icon.is_file():
+        return Response(status_code=404)
+    return FileResponse(icon)
+
+
+def _broker_services(request: Request, app: dict) -> dict:
+    """Core services the broker may expose for gated capabilities. Each optional;
+    absence => the gated capability returns a null/empty result."""
+    st = request.app.state
+    backend_url = None
+    if app.get("container_host") and app.get("container_port"):
+        backend_url = f"http://{app['container_host']}:{app['container_port']}"
+    return {
+        "notifications": getattr(st, "notifications", None),
+        "memory": getattr(st, "user_memory", None),
+        "llm": getattr(st, "llm_proxy", None),
+        "agent": None,  # agent-invocation adapter wired in a later increment
+        "app_backend_url": backend_url,
+    }
+
+
+@router.post("/api/userspace-apps/{app_id}/broker")
+async def broker(request: Request, app_id: str):
+    store = request.app.state.userspace_apps
+    app = await store.get(app_id)
+    if app is None or not app["enabled"]:
+        return JSONResponse({"error": "app not found or disabled"}, status_code=404)
+    body = await request.json()
+    out = await handle_capability(
+        app_id, body.get("capability", ""), body.get("args") or {},
+        granted=app["permissions_granted"],
+        data_store=request.app.state.userspace_data,
+        app_dir=_apps_root(request) / app_id,
+        services=_broker_services(request, app),
+    )
+    return out
diff --git a/tinyagentos/userspace/__init__.py b/tinyagentos/userspace/__init__.py
new file mode 100644
index 000000000..889a587cd
--- /dev/null
+++ b/tinyagentos/userspace/__init__.py
@@ -0,0 +1 @@
+# tinyagentos/userspace -- sandboxed .taosapp runtime (web-only)
diff --git a/tinyagentos/userspace/broker.py b/tinyagentos/userspace/broker.py
new file mode 100644
index 000000000..e16b706e7
--- /dev/null
+++ b/tinyagentos/userspace/broker.py
@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import httpx
+from pathlib import Path
+
+# Headers an app may NOT set on a backend-proxy call -- these would let it
+# spoof identity/routing or exfiltrate the session.
+_BLOCKED_PROXY_HEADERS = {"host", "authorization", "cookie",
+                          "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto"}
+
+# Capability namespaces granted to every app without consent.
+FREE_CAPS = {"app.kv", "app.table", "app.files", "app.notify", "app.window"}
+# Capability namespaces that require an explicit granted permission.
+GATED_CAPS = {"app.net", "app.agent", "app.llm", "app.memory"}
+
+
+def _namespace(capability: str) -> str:
+    parts = capability.split(".")
+    return ".".join(parts[:2]) if len(parts) >= 2 else capability
+
+
+async def handle_capability(app_id, capability, args, *, granted, data_store, app_dir, services):
+    """Dispatch one capability call. Returns {"result": ...} or {"error": ...}.
+
+    Enforces: gated caps require membership in `granted`; data calls are
+    namespaced by app_id; file calls are jailed to app_dir/files.
+    """
+    ns = _namespace(capability)
+    if ns not in FREE_CAPS and ns not in GATED_CAPS:
+        return {"error": "unknown_capability", "capability": capability}
+    if ns in GATED_CAPS and ns not in granted:
+        return {"error": "permission_denied", "capability": capability}
+
+    args = args or {}
+
+    if capability == "app.kv.get":
+        return {"result": await data_store.kv_get(app_id, args["key"])}
+    if capability == "app.kv.set":
+        await data_store.kv_set(app_id, args["key"], args.get("value"))
+        return {"result": True}
+    if capability == "app.kv.delete":
+        await data_store.kv_delete(app_id, args["key"])
+        return {"result": True}
+    if capability == "app.kv.keys":
+        return {"result": await data_store.kv_keys(app_id)}
+    if capability == "app.table.insert":
+        return {"result": await data_store.table_insert(app_id, args["table"], args.get("row", {}))}
+    if capability == "app.table.query":
+        return {"result": await data_store.table_query(app_id, args["table"], args.get("where"))}
+    if capability == "app.table.delete":
+        await data_store.table_delete(app_id, args["table"], args["id"])
+        return {"result": True}
+
+    if capability in ("app.files.read", "app.files.write"):
+        files_root = (Path(app_dir) / "files").resolve()
+        target = (files_root / args.get("path", "")).resolve()
+        if not str(target).startswith(str(files_root) + "/") and target != files_root:
+            return {"error": "invalid_path"}
+        if capability == "app.files.read":
+            if not target.is_file():
+                return {"error": "not_found"}
+            return {"result": target.read_text()}
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(args.get("content", ""))
+        return {"result": True}
+
+    if capability == "app.notify":
+        notif = services.get("notifications")
+        if notif is not None:
+            await notif.add_notification({
+                "source": app_id, "title": args.get("title", app_id),
+                "body": args.get("body", ""), "level": "info", "icon": "layout-grid"})
+        return {"result": True}
+    if capability == "app.window":
+        return {"result": True}  # window ops handled client-side; no-op server result
+
+    # Gated caps (only reached when granted)
+    if capability == "app.memory.search":
+        mem = services.get("memory")
+        _search = getattr(mem, "search", None) if mem is not None else None
+        if _search is None:
+            return {"result": []}
+        try:
+            return {"result": await _search(args.get("q", ""))}
+        except TypeError:
+            return {"result": []}
+    if capability == "app.agent":
+        agent = services.get("agent")
+        return {"result": await agent.ask(args.get("name"), args.get("message")) if agent else None}
+    if capability == "app.llm":
+        llm = services.get("llm")
+        return {"result": await llm.complete(args.get("prompt", "")) if llm else None}
+    if capability == "app.net":
+        base = services.get("app_backend_url")
+        if not base:
+            return {"error": "no_backend"}
+        path = str(args.get("path", "/"))
+        if "://" in path or path.startswith("//") or ".." in path.split("/"):
+            return {"error": "invalid_path"}
+        url = base.rstrip("/") + "/" + path.lstrip("/")
+        method = str(args.get("method", "GET")).upper()
+        _raw = args.get("headers") or {}
+        _headers = {k: v for k, v in _raw.items()
+                    if k.lower() not in _BLOCKED_PROXY_HEADERS} or None
+        try:
+            async with httpx.AsyncClient(timeout=30, follow_redirects=False) as c:
+                resp = await c.request(
+                    method, url,
+                    json=args.get("body") if args.get("body") is not None else None,
+                    headers=_headers,
+                )
+            return {"result": {"status": resp.status_code, "body": resp.text}}
+        except httpx.HTTPError as exc:
+            return {"error": "backend_unreachable", "detail": str(exc)}
+
+    return {"error": "unknown_capability", "capability": capability}
diff --git a/tinyagentos/userspace/data_store.py b/tinyagentos/userspace/data_store.py
new file mode 100644
index 000000000..2035d9826
--- /dev/null
+++ b/tinyagentos/userspace/data_store.py
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+
+from tinyagentos.base_store import BaseStore
+
+
+class UserspaceDataStore(BaseStore):
+    """Per-app KV + table storage, namespaced by app_id. Every read/write is
+    filtered by app_id so one app can never see another app's data."""
+
+    SCHEMA = """
+    CREATE TABLE IF NOT EXISTS app_kv (
+        app_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value_json TEXT NOT NULL,
+        PRIMARY KEY (app_id, key)
+    );
+    CREATE TABLE IF NOT EXISTS app_rows (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        app_id TEXT NOT NULL,
+        table_name TEXT NOT NULL,
+        row_json TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_app_rows ON app_rows (app_id, table_name);
+    """
+
+    async def kv_get(self, app_id: str, key: str):
+        assert self._db is not None
+        cur = await self._db.execute(
+            "SELECT value_json FROM app_kv WHERE app_id=? AND key=?", (app_id, key))
+        row = await cur.fetchone()
+        return json.loads(row[0]) if row else None
+
+    async def kv_set(self, app_id: str, key: str, value) -> None:
+        assert self._db is not None
+        await self._db.execute(
+            "INSERT INTO app_kv (app_id, key, value_json) VALUES (?,?,?) "
+            "ON CONFLICT(app_id, key) DO UPDATE SET value_json=excluded.value_json",
+            (app_id, key, json.dumps(value)))
+        await self._db.commit()
+
+    async def kv_delete(self, app_id: str, key: str) -> None:
+        assert self._db is not None
+        await self._db.execute("DELETE FROM app_kv WHERE app_id=? AND key=?", (app_id, key))
+        await self._db.commit()
+
+    async def kv_keys(self, app_id: str) -> list[str]:
+        assert self._db is not None
+        cur = await self._db.execute(
+            "SELECT key FROM app_kv WHERE app_id=? ORDER BY key", (app_id,))
+        return [r[0] for r in await cur.fetchall()]
+
+    async def table_insert(self, app_id: str, table: str, row: dict) -> int:
+        assert self._db is not None
+        cur = await self._db.execute(
+            "INSERT INTO app_rows (app_id, table_name, row_json) VALUES (?,?,?)",
+            (app_id, table, json.dumps(row)))
+        await self._db.commit()
+        return cur.lastrowid
+
+    async def table_query(self, app_id: str, table: str, where: dict | None) -> list[dict]:
+        assert self._db is not None
+        cur = await self._db.execute(
+            "SELECT id, row_json FROM app_rows WHERE app_id=? AND table_name=? ORDER BY id",
+            (app_id, table))
+        out = []
+        for rid, row_json in await cur.fetchall():
+            data = json.loads(row_json)
+            if where and any(data.get(k) != v for k, v in where.items()):
+                continue
+            out.append({"id": rid, **data})
+        return out
+
+    async def table_delete(self, app_id: str, table: str, row_id: int) -> None:
+        assert self._db is not None
+        await self._db.execute(
+            "DELETE FROM app_rows WHERE app_id=? AND table_name=? AND id=?",
+            (app_id, table, row_id))
+        await self._db.commit()
diff --git a/tinyagentos/userspace/package.py b/tinyagentos/userspace/package.py
new file mode 100644
index 000000000..782916d50
--- /dev/null
+++ b/tinyagentos/userspace/package.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+import yaml
+
+_ALLOWED_TYPES = {"web", "container"}
+_REQUIRED = ("id", "name", "version", "app_type")
+
+
+class PackageError(Exception):
+    """Raised when a .taosapp package is invalid or unsafe."""
+
+
+def parse_manifest(text: str) -> dict:
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise PackageError(f"invalid manifest YAML: {exc}") from exc
+    for key in _REQUIRED:
+        if not data.get(key):
+            raise PackageError(f"manifest missing required field: {key}")
+    if data["app_type"] not in _ALLOWED_TYPES:
+        raise PackageError(
+            f"app_type {data['app_type']!r} not allowed for userspace apps "
+            f"(native is reserved for first-party core); use one of {_ALLOWED_TYPES}"
+        )
+    if data["app_type"] == "container":
+        container = data.get("container")
+        if not isinstance(container, dict):
+            raise PackageError("container app requires a 'container' block")
+        if not container.get("image") or not isinstance(container.get("image"), str):
+            raise PackageError("container app requires container.image")
+        ports = container.get("ports")
+        if (
+            not isinstance(ports, list)
+            or len(ports) == 0
+            or not all(isinstance(p, int) and not isinstance(p, bool) for p in ports)
+        ):
+            raise PackageError("container app requires container.ports as a non-empty list of ints")
+    data.setdefault("entry", "index.html")
+    data.setdefault("icon", "")
+    data.setdefault("permissions", [])
+    return data
+
+
+def extract_package(data: bytes, apps_root: Path) -> dict:
+    """Validate + extract a .taosapp zip into apps_root/{id}/. Returns the manifest."""
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(data))
+    except zipfile.BadZipFile as exc:
+        raise PackageError("not a valid .taosapp (zip) archive") from exc
+    try:
+        manifest = parse_manifest(zf.read("manifest.yaml").decode("utf-8"))
+    except KeyError as exc:
+        raise PackageError("manifest.yaml missing from package") from exc
+
+    apps_root = Path(apps_root).resolve()
+    app_dir = (apps_root / manifest["id"]).resolve()
+    # app_dir itself must stay within apps_root (defends against a crafted id)
+    if not str(app_dir).startswith(str(apps_root) + "/"):
+        raise PackageError(f"unsafe path in package: id {manifest['id']!r}")
+    app_dir.mkdir(parents=True, exist_ok=True)
+    for member in zf.namelist():
+        if member.endswith("/"):
+            continue
+        dest = (app_dir / member).resolve()
+        if not str(dest).startswith(str(app_dir) + "/") and dest != app_dir:
+            raise PackageError(f"unsafe path in package: {member}")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(zf.read(member))
+    return manifest
diff --git a/tinyagentos/userspace/sdk/taos-app-sdk.js b/tinyagentos/userspace/sdk/taos-app-sdk.js
new file mode 100644
index 000000000..9ef076f8d
--- /dev/null
+++ b/tinyagentos/userspace/sdk/taos-app-sdk.js
@@ -0,0 +1,53 @@
+// tinyagentos/userspace/sdk/taos-app-sdk.js
+(() => {
+  const APP_ID = new URLSearchParams(location.search).get("app")
+    || (document.currentScript && document.currentScript.dataset.appId) || "";
+  let seq = 0;
+  const pending = new Map();
+  window.addEventListener("message", (e) => {
+    const m = e.data;
+    if (m && m.taosAppReply != null && pending.has(m.taosAppReply)) {
+      const { resolve } = pending.get(m.taosAppReply);
+      pending.delete(m.taosAppReply);
+      resolve(m);
+    }
+  });
+  function call(capability, args) {
+    const id = ++seq;
+    return new Promise((resolve) => {
+      pending.set(id, { resolve });
+      parent.postMessage({ taosApp: APP_ID, id, capability, args: args || {} }, "*");
+    });
+  }
+  window.taos = {
+    appId: APP_ID,
+    kv: {
+      get: (k) => call("app.kv.get", { key: k }).then((r) => r.result),
+      set: (k, v) => call("app.kv.set", { key: k, value: v }),
+      delete: (k) => call("app.kv.delete", { key: k }),
+      keys: () => call("app.kv.keys", {}).then((r) => r.result),
+    },
+    table: {
+      insert: (t, row) => call("app.table.insert", { table: t, row }).then((r) => r.result),
+      query: (t, where) => call("app.table.query", { table: t, where }).then((r) => r.result),
+      delete: (t, id) => call("app.table.delete", { table: t, id }),
+    },
+    files: {
+      read: (p) => call("app.files.read", { path: p }).then((r) => r.result),
+      write: (p, content) => call("app.files.write", { path: p, content }),
+    },
+    notify: (title, body) => call("app.notify", { title, body }),
+    // gated -- resolve to {error:"permission_denied"} if not granted
+    net: { fetch: (url, opts) => call("app.net", { url, opts }) },
+    backend: {
+      fetch: (path, opts) => call("app.net", {
+        path,
+        method: (opts && opts.method) || "GET",
+        body: opts && opts.body,
+        headers: opts && opts.headers,
+      }).then((r) => r.result),
+    },
+    agent: { ask: (name, message) => call("app.agent", { name, message }).then((r) => r.result) },
+    memory: { search: (q) => call("app.memory.search", { q }).then((r) => r.result) },
+  };
+})();
diff --git a/tinyagentos/userspace/store.py b/tinyagentos/userspace/store.py
new file mode 100644
index 000000000..f0f69d942
--- /dev/null
+++ b/tinyagentos/userspace/store.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+import time
+
+from tinyagentos.base_store import BaseStore
+
+
+class UserspaceAppStore(BaseStore):
+    """Registry of installed userspace apps (sandboxed .taosapp packages).
+    Distinct from InstalledAppsStore (catalog services). Userspace apps are
+    web (iframe) or container; never in-process 'native'.
+
+    BaseStore.init() runs SCHEMA and sets self._db -- do NOT override init().
+    """
+
+    SCHEMA = """
+    CREATE TABLE IF NOT EXISTS userspace_apps (
+        app_id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        version TEXT NOT NULL DEFAULT '',
+        app_type TEXT NOT NULL,
+        entry TEXT NOT NULL DEFAULT 'index.html',
+        icon TEXT NOT NULL DEFAULT '',
+        permissions_requested TEXT NOT NULL DEFAULT '[]',
+        permissions_granted TEXT NOT NULL DEFAULT '[]',
+        enabled INTEGER NOT NULL DEFAULT 1,
+        installed_at INTEGER NOT NULL,
+        container_host TEXT,
+        container_port INTEGER
+    );
+    """
+
+    async def install(self, app_id, name, version, app_type, entry, icon,
+                      permissions_requested):
+        assert self._db is not None
+        await self._db.execute(
+            """INSERT INTO userspace_apps
+               (app_id, name, version, app_type, entry, icon,
+                permissions_requested, permissions_granted, enabled, installed_at)
+               VALUES (?,?,?,?,?,?,?,'[]',1,?)
+               ON CONFLICT(app_id) DO UPDATE SET
+                 name=excluded.name, version=excluded.version,
+                 app_type=excluded.app_type, entry=excluded.entry,
+                 icon=excluded.icon,
+                 permissions_requested=excluded.permissions_requested""",
+            (app_id, name, version, app_type, entry, icon,
+             json.dumps(permissions_requested), int(time.time())),
+        )
+        await self._db.commit()
+
+    def _row_to_dict(self, row) -> dict:
+        return {
+            "app_id": row[0], "name": row[1], "version": row[2],
+            "app_type": row[3], "entry": row[4], "icon": row[5],
+            "permissions_requested": json.loads(row[6]),
+            "permissions_granted": json.loads(row[7]),
+            "enabled": row[8], "installed_at": row[9],
+            "container_host": row[10], "container_port": row[11],
+        }
+
+    async def get(self, app_id) -> dict | None:
+        assert self._db is not None
+        cur = await self._db.execute("SELECT * FROM userspace_apps WHERE app_id=?", (app_id,))
+        row = await cur.fetchone()
+        return self._row_to_dict(row) if row else None
+
+    async def list_installed(self) -> list[dict]:
+        assert self._db is not None
+        cur = await self._db.execute("SELECT * FROM userspace_apps ORDER BY installed_at")
+        return [self._row_to_dict(r) for r in await cur.fetchall()]
+
+    async def set_permissions_granted(self, app_id, perms):
+        assert self._db is not None
+        await self._db.execute("UPDATE userspace_apps SET permissions_granted=? WHERE app_id=?",
+                               (json.dumps(perms), app_id))
+        await self._db.commit()
+
+    async def set_enabled(self, app_id, enabled: bool):
+        assert self._db is not None
+        await self._db.execute("UPDATE userspace_apps SET enabled=? WHERE app_id=?",
+                               (1 if enabled else 0, app_id))
+        await self._db.commit()
+
+    async def set_runtime_location(self, app_id, host: str, port: int):
+        assert self._db is not None
+        await self._db.execute(
+            "UPDATE userspace_apps SET container_host=?, container_port=? WHERE app_id=?",
+            (host, port, app_id),
+        )
+        await self._db.commit()
+
+    async def uninstall(self, app_id) -> bool:
+        assert self._db is not None
+        cur = await self._db.execute("DELETE FROM userspace_apps WHERE app_id=?", (app_id,))
+        await self._db.commit()
+        return cur.rowcount > 0
diff --git a/tinyagentos/userspace/url_guard.py b/tinyagentos/userspace/url_guard.py
new file mode 100644
index 000000000..9afbc3575
--- /dev/null
+++ b/tinyagentos/userspace/url_guard.py
@@ -0,0 +1,47 @@
+"""SSRF guard for userspace app installs.
+
+POST /api/userspace-apps/install can fetch a .taosapp from a caller-supplied
+source_url. Without validation that lets an authenticated user make the
+controller fetch internal addresses (cloud metadata at 169.254.169.254,
+localhost services, private LAN ranges) -- a classic SSRF. This module rejects
+non-public hosts before any request is made; the caller should also use
+follow_redirects=False so a 3xx cannot bounce to a blocked host.
+"""
+from __future__ import annotations
+
+import socket
+from ipaddress import ip_address
+from urllib.parse import urlparse
+
+_ALLOWED_SCHEMES = {"http", "https"}
+
+
+def is_safe_public_url(url: str) -> bool:
+    """True only if url is http(s) and every resolved IP is a public address.
+
+    Rejects private, loopback, link-local, reserved, unspecified and multicast
+    addresses (covers 127/8, ::1, 10/8, 172.16/12, 192.168/16, 169.254/16,
+    0.0.0.0, etc.).
+    """
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return False
+    if parsed.scheme not in _ALLOWED_SCHEMES or not parsed.hostname:
+        return False
+    try:
+        infos = socket.getaddrinfo(parsed.hostname, parsed.port or None)
+    except (socket.gaierror, UnicodeError, OSError):
+        return False
+    if not infos:
+        return False
+    for info in infos:
+        sockaddr = info[4]
+        try:
+            ip = ip_address(sockaddr[0])
+        except ValueError:
+            return False
+        if (ip.is_private or ip.is_loopback or ip.is_link_local
+                or ip.is_reserved or ip.is_unspecified or ip.is_multicast):
+            return False
+    return True

From 2d4d1c60990703f478f64452edd8dd75461411aa Mon Sep 17 00:00:00 2001
From: jaylfc <jaylfc25@gmail.com>
Date: Wed, 17 Jun 2026 00:45:45 +0100
Subject: [PATCH 2/3] fix(userspace): fold CodeRabbit findings on the
 app-runtime foundation (#89 P3a)

---
 desktop/src/apps/SandboxedAppWindow.tsx       | 10 ++-
 .../__tests__/SandboxedAppWindow.test.tsx     | 22 +++++++
 tests/userspace/test_package.py               | 25 ++++++++
 tests/userspace/test_routes.py                | 61 ++++++++++++++++++-
 tinyagentos/routes/userspace_apps.py          | 39 +++++++-----
 tinyagentos/userspace/package.py              | 10 ++-
 tinyagentos/userspace/sdk/taos-app-sdk.js     |  2 +-
 7 files changed, 150 insertions(+), 19 deletions(-)

diff --git a/desktop/src/apps/SandboxedAppWindow.tsx b/desktop/src/apps/SandboxedAppWindow.tsx
index c0f827827..cf03a9124 100644
--- a/desktop/src/apps/SandboxedAppWindow.tsx
+++ b/desktop/src/apps/SandboxedAppWindow.tsx
@@ -23,6 +23,14 @@ export function SandboxedAppWindow({ appId }: Props) {
       if (!iframe || e.source !== iframe.contentWindow) return;
       const msg = e.data as BrokerRequest;
       if (!msg || msg.taosApp !== appId || typeof msg.id !== "number" || !msg.capability) return;
+      // Validate args: must be a plain object (not an array, null, or primitive).
+      // Non-conforming values are coerced to {} rather than forwarded as-is into
+      // backend capability handling.
+      const rawArgs = msg.args;
+      const safeArgs: Record<string, unknown> =
+        rawArgs !== null && typeof rawArgs === "object" && !Array.isArray(rawArgs)
+          ? rawArgs
+          : {};
       let result: Record<string, unknown>;
       try {
         const res = await fetch(`/api/userspace-apps/${encodeURIComponent(appId)}/broker`, {
@@ -32,7 +40,7 @@ export function SandboxedAppWindow({ appId }: Props) {
           // under the Vite dev proxy (SPA :5173 -> API :6969).
           credentials: "include",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ capability: msg.capability, args: msg.args || {} }),
+          body: JSON.stringify({ capability: msg.capability, args: safeArgs }),
         });
         result = res.ok ? await res.json() : { error: `broker_${res.status}` };
       } catch {
diff --git a/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx b/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
index 57f72be46..ad077ddbe 100644
--- a/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
+++ b/desktop/src/apps/__tests__/SandboxedAppWindow.test.tsx
@@ -44,4 +44,26 @@ describe("SandboxedAppWindow", () => {
     }));
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("coerces non-object args to {} before forwarding to broker", async () => {
+    // Finding 1: array, null, or scalar args must not be forwarded as-is.
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ result: "ok" }) });
+    vi.stubGlobal("fetch", fetchMock);
+    render(<SandboxedAppWindow windowId="w1" appId="todo" />);
+    const iframe = screen.getByTitle("todo") as HTMLIFrameElement;
+    Object.defineProperty(iframe, "contentWindow", {
+      value: { postMessage: vi.fn() }, configurable: true
+    });
+
+    for (const badArgs of [["array"], null, "string", 42]) {
+      fetchMock.mockClear();
+      window.dispatchEvent(new MessageEvent("message", {
+        source: iframe.contentWindow as Window,
+        data: { taosApp: "todo", id: 2, capability: "app.kv.get", args: badArgs },
+      }));
+      await waitFor(() => expect(fetchMock).toHaveBeenCalled());
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.args).toEqual({});
+    }
+  });
 });
diff --git a/tests/userspace/test_package.py b/tests/userspace/test_package.py
index e2cb4d7d8..dd6d51c85 100644
--- a/tests/userspace/test_package.py
+++ b/tests/userspace/test_package.py
@@ -52,3 +52,28 @@ def test_extract_rejects_path_traversal(tmp_path):
     data = _zip(WEB_MANIFEST, {"../evil.txt": "pwned"})
     with pytest.raises(PackageError, match="unsafe path"):
         extract_package(data, apps_root=tmp_path)
+
+
+def test_parse_manifest_rejects_yaml_list():
+    # Finding 5: safe_load returns a list -- must raise PackageError, not AttributeError.
+    with pytest.raises(PackageError, match="mapping"):
+        parse_manifest("- item1\n- item2\n")
+
+
+def test_parse_manifest_rejects_yaml_scalar():
+    # Finding 5: safe_load returns a scalar -- must raise PackageError.
+    with pytest.raises(PackageError, match="mapping"):
+        parse_manifest("just a string")
+
+
+def test_extract_rejects_dot_member(tmp_path):
+    # Finding 7: a zip member "." resolves to app_dir itself -- must raise PackageError,
+    # not an IsADirectoryError when write_bytes is called on a directory.
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", WEB_MANIFEST.strip())
+        z.writestr("index.html", "<h1>ok</h1>")
+        # Add a member whose name is just "." -- resolves to app_dir on extraction.
+        z.writestr(".", "bad")
+    with pytest.raises(PackageError, match="unsafe path"):
+        extract_package(buf.getvalue(), apps_root=tmp_path)
diff --git a/tests/userspace/test_routes.py b/tests/userspace/test_routes.py
index b77b03c07..a0941c5de 100644
--- a/tests/userspace/test_routes.py
+++ b/tests/userspace/test_routes.py
@@ -1,5 +1,7 @@
 import io, zipfile
 import pytest
+from unittest.mock import AsyncMock, patch
+import httpx
 
 WEB_MANIFEST = "id: todo\nname: Todo\nversion: 1.0.0\napp_type: web\nentry: index.html\nicon: icon.png\npermissions: [app.net]\n"
 
@@ -40,5 +42,62 @@ async def test_install_list_bundle_uninstall(client):
 async def test_bundle_path_traversal_404(client):
     await client.post("/api/userspace-apps/install",
                       files={"package": ("todo.taosapp", _zip(), "application/zip")})
-    r = await client.get("/api/userspace-apps/todo/bundle/../../../etc/passwd")
+    # Use percent-encoded traversal so URL normalization cannot collapse it
+    # before the route handler, ensuring the bundle path guard is exercised.
+    r = await client.get("/api/userspace-apps/todo/bundle/%2e%2e%2f%2e%2e%2fetc%2fpasswd")
     assert r.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_install_malformed_json_returns_400(client):
+    # Finding 2: a request body that is not valid JSON must return 400, not 500.
+    r = await client.post(
+        "/api/userspace-apps/install",
+        content=b"{not valid json",
+        headers={"Content-Type": "application/json"},
+    )
+    assert r.status_code == 400
+    assert "invalid" in r.json()["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_install_upstream_fetch_failure_returns_502(client):
+    # Finding 2: httpx connectivity failure on source_url must return 502.
+    with patch("tinyagentos.routes.userspace_apps.is_safe_public_url", return_value=True):
+        with patch("httpx.AsyncClient.get", new_callable=AsyncMock,
+                   side_effect=httpx.ConnectError("refused")):
+            r = await client.post(
+                "/api/userspace-apps/install",
+                json={"source_url": "http://example.com/app.taosapp"},
+            )
+    assert r.status_code == 502
+    assert "upstream" in r.json()["error"].lower() or "fetch" in r.json()["error"].lower()
+
+
+def _container_zip():
+    manifest = (
+        "id: ctapp\nname: ContainerApp\nversion: 1.0.0\napp_type: container\n"
+        "entry: index.html\nicon: \npermissions: []\n"
+        "container:\n  image: myimage:latest\n  ports: [8080]\n"
+    )
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as z:
+        z.writestr("manifest.yaml", manifest)
+        z.writestr("index.html", "<h1>ct</h1>")
+    return buf.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_container_install_rejected_with_no_stored_state(client):
+    # Finding 3: installing a container package must return 501 before
+    # persisting anything -- no app row and no extracted directory must remain.
+    r = await client.post(
+        "/api/userspace-apps/install",
+        files={"package": ("ctapp.taosapp", _container_zip(), "application/zip")},
+    )
+    assert r.status_code == 501
+    assert "container" in r.json()["error"].lower()
+
+    # No app row stored.
+    rows = (await client.get("/api/userspace-apps")).json()
+    assert all(a["app_id"] != "ctapp" for a in rows)
diff --git a/tinyagentos/routes/userspace_apps.py b/tinyagentos/routes/userspace_apps.py
index af24e5c70..e0edffffe 100644
--- a/tinyagentos/routes/userspace_apps.py
+++ b/tinyagentos/routes/userspace_apps.py
@@ -55,7 +55,10 @@ async def install_app(request: Request, package: UploadFile | None = File(defaul
     if package is not None:
         data = await package.read()
     else:
-        body = await request.json()
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse({"error": "invalid JSON body"}, status_code=400)
         url = body.get("source_url")
         if not url:
             return JSONResponse({"error": "source_url or package required"}, status_code=400)
@@ -67,14 +70,28 @@ async def install_app(request: Request, package: UploadFile | None = File(defaul
                           "(no private, loopback, link-local or reserved addresses)"},
                 status_code=400,
             )
-        async with httpx.AsyncClient(timeout=120, follow_redirects=False) as c:
-            resp = await c.get(url)
-            resp.raise_for_status()
-            data = resp.content
+        try:
+            async with httpx.AsyncClient(timeout=120, follow_redirects=False) as c:
+                resp = await c.get(url)
+                resp.raise_for_status()
+                data = resp.content
+        except httpx.HTTPStatusError as exc:
+            return JSONResponse(
+                {"error": f"upstream returned {exc.response.status_code}"},
+                status_code=502,
+            )
+        except httpx.HTTPError as exc:
+            return JSONResponse({"error": f"upstream fetch failed: {exc}"}, status_code=502)
     try:
         manifest = extract_package(data, apps_root=_apps_root(request))
     except PackageError as exc:
         return JSONResponse({"error": str(exc)}, status_code=400)
+    # Reject container packages before persisting anything -- no partial state.
+    if manifest["app_type"] == "container":
+        return JSONResponse(
+            {"error": "container packages are not supported in this release (web-only)"},
+            status_code=501,
+        )
     existing = await store.get(manifest["id"])
     new_perms = [
         p for p in manifest["permissions"]
@@ -85,17 +102,11 @@ async def install_app(request: Request, package: UploadFile | None = File(defaul
         app_type=manifest["app_type"], entry=manifest["entry"], icon=manifest["icon"],
         permissions_requested=manifest["permissions"],
     )
-    deploy_info: dict = {}
-    if manifest["app_type"] == "container":
-        # Container deploy is not yet wired in this phase (web-only).
-        # Re-installs of container apps are accepted and stored, but not deployed.
-        raise NotImplementedError("container packages: web-only for now")
     return {
         "app_id": manifest["id"],
         "permissions_requested": manifest["permissions"],
         "needs_consent": bool(existing and new_perms),
         "new_permissions": new_perms,
-        **deploy_info,
     }
 
 
@@ -124,7 +135,7 @@ async def uninstall_app(request: Request, app_id: str):
     removed = await store.uninstall(app_id)
     root = _apps_root(request).resolve()
     app_dir = (root / app_id).resolve()
-    if str(app_dir).startswith(str(root) + "/") and app_dir.exists():
+    if app_dir.is_relative_to(root) and app_dir != root and app_dir.exists():
         shutil.rmtree(app_dir, ignore_errors=True)
     return {"status": "ok", "removed": removed}
 
@@ -133,7 +144,7 @@ async def uninstall_app(request: Request, app_id: str):
 async def serve_bundle(request: Request, app_id: str, path: str):
     root = (_apps_root(request) / app_id).resolve()
     target = (root / path).resolve()
-    if not str(target).startswith(str(root) + "/") or not target.is_file():
+    if not target.is_relative_to(root) or target == root or not target.is_file():
         return JSONResponse({"error": "not found"}, status_code=404)
     resp = FileResponse(target)
     resp.headers["Content-Security-Policy"] = _BUNDLE_CSP
@@ -148,7 +159,7 @@ async def serve_icon(request: Request, app_id: str):
         return Response(status_code=404)
     root = (_apps_root(request) / app_id).resolve()
     icon = (root / app["icon"]).resolve()
-    if not str(icon).startswith(str(root) + "/") or not icon.is_file():
+    if not icon.is_relative_to(root) or icon == root or not icon.is_file():
         return Response(status_code=404)
     return FileResponse(icon)
 
diff --git a/tinyagentos/userspace/package.py b/tinyagentos/userspace/package.py
index 782916d50..0cb99441d 100644
--- a/tinyagentos/userspace/package.py
+++ b/tinyagentos/userspace/package.py
@@ -19,6 +19,10 @@ def parse_manifest(text: str) -> dict:
         data = yaml.safe_load(text) or {}
     except yaml.YAMLError as exc:
         raise PackageError(f"invalid manifest YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise PackageError(
+            f"manifest.yaml must be a YAML mapping, got {type(data).__name__}"
+        )
     for key in _REQUIRED:
         if not data.get(key):
             raise PackageError(f"manifest missing required field: {key}")
@@ -60,14 +64,16 @@ def extract_package(data: bytes, apps_root: Path) -> dict:
     apps_root = Path(apps_root).resolve()
     app_dir = (apps_root / manifest["id"]).resolve()
     # app_dir itself must stay within apps_root (defends against a crafted id)
-    if not str(app_dir).startswith(str(apps_root) + "/"):
+    if not app_dir.is_relative_to(apps_root) or app_dir == apps_root:
         raise PackageError(f"unsafe path in package: id {manifest['id']!r}")
     app_dir.mkdir(parents=True, exist_ok=True)
     for member in zf.namelist():
         if member.endswith("/"):
             continue
         dest = (app_dir / member).resolve()
-        if not str(dest).startswith(str(app_dir) + "/") and dest != app_dir:
+        # dest must be a file strictly inside app_dir -- reject traversals and
+        # members that resolve to app_dir itself (e.g. "." -> IsADirectoryError)
+        if dest == app_dir or not dest.is_relative_to(app_dir):
             raise PackageError(f"unsafe path in package: {member}")
         dest.parent.mkdir(parents=True, exist_ok=True)
         dest.write_bytes(zf.read(member))
diff --git a/tinyagentos/userspace/sdk/taos-app-sdk.js b/tinyagentos/userspace/sdk/taos-app-sdk.js
index 9ef076f8d..7d3de1f73 100644
--- a/tinyagentos/userspace/sdk/taos-app-sdk.js
+++ b/tinyagentos/userspace/sdk/taos-app-sdk.js
@@ -38,7 +38,7 @@
     },
     notify: (title, body) => call("app.notify", { title, body }),
     // gated -- resolve to {error:"permission_denied"} if not granted
-    net: { fetch: (url, opts) => call("app.net", { url, opts }) },
+    net: { fetch: (url, opts) => call("app.net", { path: url, method: (opts && opts.method) || "GET", body: opts && opts.body, headers: opts && opts.headers }) },
     backend: {
       fetch: (path, opts) => call("app.net", {
         path,

From 0b990a029653616a7e4f81f55d2ceece03c76506 Mon Sep 17 00:00:00 2001
From: jaylfc <jaylfc25@gmail.com>
Date: Wed, 17 Jun 2026 00:51:10 +0100
Subject: [PATCH 3/3] fix(userspace): zip-bomb size caps + reject
 app.files.write to the jail root (#89 P3a)

- package.py: cap declared uncompressed total, per-member size, and member count
  before extraction (zip-bomb defense, gitar Security finding)
- install_app: bound the upload/fetch read to a max size, return 413 if exceeded
- broker.py: app.files.write to the jail root or any existing dir now returns
  invalid_path instead of an uncaught IsADirectoryError (500); path containment
  uses is_relative_to
- tests for the zip-bomb cap and the jail-root write guard
---
 desktop/node_modules                 |  1 +
 tests/userspace/test_broker.py       | 12 ++++++++++++
 tests/userspace/test_package.py      | 10 ++++++++++
 tinyagentos/routes/userspace_apps.py |  8 +++++++-
 tinyagentos/userspace/broker.py      |  6 +++++-
 tinyagentos/userspace/package.py     | 17 +++++++++++++++++
 6 files changed, 52 insertions(+), 2 deletions(-)
 create mode 120000 desktop/node_modules

diff --git a/desktop/node_modules b/desktop/node_modules
new file mode 120000
index 000000000..f0c65aeaa
--- /dev/null
+++ b/desktop/node_modules
@@ -0,0 +1 @@
+/Volumes/NVMe/Users/jay/Development/tinyagentos/desktop/node_modules
\ No newline at end of file
diff --git a/tests/userspace/test_broker.py b/tests/userspace/test_broker.py
index a61980dba..2d375df25 100644
--- a/tests/userspace/test_broker.py
+++ b/tests/userspace/test_broker.py
@@ -131,3 +131,15 @@ async def test_app_net_blocks_dangerous_headers_and_passes_safe_ones(tmp_path):
     assert "host" not in lower_keys, "Host header must be stripped"
     assert "x-ok" in lower_keys, "X-Ok header must be forwarded"
     await s.close()
+
+
+@pytest.mark.asyncio
+async def test_files_write_to_jail_root_rejected(tmp_path):
+    # app.files.write with an empty path targets the jail root (a directory) and
+    # must return invalid_path, not raise an uncaught IsADirectoryError (a 500).
+    s = await _store(tmp_path)
+    (tmp_path / "todo" / "files").mkdir(parents=True)
+    out = await handle_capability("todo", "app.files.write", {"path": "", "content": "x"},
+                                  granted=[], data_store=s, app_dir=tmp_path / "todo", services={})
+    assert out["error"] == "invalid_path"
+    await s.close()
diff --git a/tests/userspace/test_package.py b/tests/userspace/test_package.py
index dd6d51c85..7bbab9a93 100644
--- a/tests/userspace/test_package.py
+++ b/tests/userspace/test_package.py
@@ -77,3 +77,13 @@ def test_extract_rejects_dot_member(tmp_path):
         z.writestr(".", "bad")
     with pytest.raises(PackageError, match="unsafe path"):
         extract_package(buf.getvalue(), apps_root=tmp_path)
+
+
+def test_extract_rejects_zip_bomb(tmp_path, monkeypatch):
+    # Zip-bomb defense: cap the declared uncompressed total low and confirm an
+    # over-cap package is rejected before extraction.
+    import tinyagentos.userspace.package as pkg
+    monkeypatch.setattr(pkg, "_MAX_UNCOMPRESSED_BYTES", 8)
+    data = _zip(WEB_MANIFEST, {"index.html": "<h1>more than eight bytes</h1>"})
+    with pytest.raises(PackageError, match="uncompressed size too large"):
+        extract_package(data, apps_root=tmp_path)
diff --git a/tinyagentos/routes/userspace_apps.py b/tinyagentos/routes/userspace_apps.py
index e0edffffe..4e0656d23 100644
--- a/tinyagentos/routes/userspace_apps.py
+++ b/tinyagentos/routes/userspace_apps.py
@@ -49,11 +49,15 @@ async def list_apps(request: Request):
     return await request.app.state.userspace_apps.list_installed()
 
 
+# Cap the package upload / fetch size to bound memory and pre-filter zip bombs.
+_MAX_PACKAGE_BYTES = 64 * 1024 * 1024
+
+
 @router.post("/api/userspace-apps/install")
 async def install_app(request: Request, package: UploadFile | None = File(default=None)):
     store = request.app.state.userspace_apps
     if package is not None:
-        data = await package.read()
+        data = await package.read(_MAX_PACKAGE_BYTES + 1)
     else:
         try:
             body = await request.json()
@@ -82,6 +86,8 @@ async def install_app(request: Request, package: UploadFile | None = File(defaul
             )
         except httpx.HTTPError as exc:
             return JSONResponse({"error": f"upstream fetch failed: {exc}"}, status_code=502)
+    if len(data) > _MAX_PACKAGE_BYTES:
+        return JSONResponse({"error": "package too large"}, status_code=413)
     try:
         manifest = extract_package(data, apps_root=_apps_root(request))
     except PackageError as exc:
diff --git a/tinyagentos/userspace/broker.py b/tinyagentos/userspace/broker.py
index e16b706e7..18c384bc8 100644
--- a/tinyagentos/userspace/broker.py
+++ b/tinyagentos/userspace/broker.py
@@ -54,12 +54,16 @@ async def handle_capability(app_id, capability, args, *, granted, data_store, ap
     if capability in ("app.files.read", "app.files.write"):
         files_root = (Path(app_dir) / "files").resolve()
         target = (files_root / args.get("path", "")).resolve()
-        if not str(target).startswith(str(files_root) + "/") and target != files_root:
+        if target != files_root and not target.is_relative_to(files_root):
             return {"error": "invalid_path"}
         if capability == "app.files.read":
             if not target.is_file():
                 return {"error": "not_found"}
             return {"result": target.read_text()}
+        # write: reject the jail root itself or any existing directory, which
+        # would otherwise raise an uncaught IsADirectoryError (a 500).
+        if target == files_root or target.is_dir():
+            return {"error": "invalid_path"}
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(args.get("content", ""))
         return {"result": True}
diff --git a/tinyagentos/userspace/package.py b/tinyagentos/userspace/package.py
index 0cb99441d..8075ce8aa 100644
--- a/tinyagentos/userspace/package.py
+++ b/tinyagentos/userspace/package.py
@@ -9,6 +9,11 @@
 _ALLOWED_TYPES = {"web", "container"}
 _REQUIRED = ("id", "name", "version", "app_type")
 
+# Zip-bomb defenses: cap the declared uncompressed total, per-member size, and count.
+_MAX_UNCOMPRESSED_BYTES = 256 * 1024 * 1024
+_MAX_MEMBER_BYTES = 64 * 1024 * 1024
+_MAX_MEMBERS = 10000
+
 
 class PackageError(Exception):
     """Raised when a .taosapp package is invalid or unsafe."""
@@ -56,6 +61,18 @@ def extract_package(data: bytes, apps_root: Path) -> dict:
         zf = zipfile.ZipFile(io.BytesIO(data))
     except zipfile.BadZipFile as exc:
         raise PackageError("not a valid .taosapp (zip) archive") from exc
+    infos = zf.infolist()
+    if len(infos) > _MAX_MEMBERS:
+        raise PackageError(f"package has too many files ({len(infos)} > {_MAX_MEMBERS})")
+    total_uncompressed = 0
+    for zi in infos:
+        if zi.file_size > _MAX_MEMBER_BYTES:
+            raise PackageError(f"package member too large: {zi.filename}")
+        total_uncompressed += zi.file_size
+    if total_uncompressed > _MAX_UNCOMPRESSED_BYTES:
+        raise PackageError(
+            f"package uncompressed size too large ({total_uncompressed} bytes)"
+        )
     try:
         manifest = parse_manifest(zf.read("manifest.yaml").decode("utf-8"))
     except KeyError as exc: