@hosty-sdk/app 0.18.0 → 0.19.1

package/README.md

@@ -1,8 +1,7 @@
 # @hosty-sdk/app
 
 Auth and host integration for [Hosty](https://github.com/alex-de-haas/docker-host) runtime
-apps: the app-session state machine, silent session recovery, Core revalidation, and the
-embedder responder for shells.
+apps: app-session classification, Core-owned sign-in, app-local request transport and revalidation.
 
 ```
 npm install @hosty-sdk/app
@@ -12,8 +11,9 @@ npm install @hosty-sdk/app
 | --- | --- | --- |
 | `@hosty-sdk/app` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` and `hosty:request-delegated-token` schemas, URL/env helpers |
 | `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory, the app secrets client |
-| `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, silent recovery, fallback cards |
-| `@hosty-sdk/app/embedder` | client | verified responders — launch-code recovery and delegated tokens — plus the theme sender half, for anything that embeds Hosty apps |
+| `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, Core popup/navigation recovery, content gate |
+| `@hosty-sdk/app/embedder` | client | theme sender and legacy embedder message parsers; Shell no longer mints app credentials |
+| `@hosty-sdk/app/browser-auth` | client | `appFetch` for app-local API requests and bound Core popup sign-in |
 | `@hosty-sdk/app/providers` | anywhere | permission state, provider descriptors, speech contract types |
 | `@hosty-sdk/app/providers/server` | server only | `ProviderClient`: discovery, speech recognition, assistant handoffs and live credential validation |
 | `@hosty-sdk/app/theme` | anywhere | the shell→app theme protocol: constants, `resolveTheme`, `applyTheme`, `parseShellThemeMessage`, `themeBootstrapScript` / `createThemeBootstrapScript` |
@@ -23,7 +23,7 @@ Minimal Next.js wiring:
 ```tsx
 // app/layout.tsx
 import { AppIdentityBridge } from "@hosty-sdk/app/react";
-// mount <AppIdentityBridge /> at the top of <body>
+// wrap protected client content: <AppIdentityBridge>{children}</AppIdentityBridge>
 
 // app/api/auth/app-code/route.ts
 import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
@@ -81,36 +81,26 @@ await setAppSecret("trakt.connection.1.tokens", refreshed, config);
 Reads are served from a write-through cache, namespaced by Core origin and app id; pass
 `{ refresh: true }` to force a live read.
 
-Delegated tokens — the credential a browser client (Shell) presents when calling a system
-app's API directly. Core signs them (ECDSA P-256, 5-minute TTL) and injects the verification
-key as `HOSTY_DELEGATED_TOKEN_PUBLIC_KEY`, so validation is fully local — no Core round-trip:
+Protected browser requests use the app-only credential held by the bridge:
 
 ```ts
-import { validateDelegatedToken } from "@hosty-sdk/app/server";
-
-// null for anything invalid (bad signature, wrong audience, expired) — treat like a missing token.
-const claims = validateDelegatedToken(bearerToken);
-if (claims?.role !== "host.admin") { /* 401/403 */ }
+import { appFetch } from "@hosty-sdk/app/browser-auth";
+const response = await appFetch("/api/items");
 ```
 
-An embedded page cannot mint a delegated token itself — that needs the user's Core session in a
-first-party context — so it asks whoever embeds it:
+The server must accept the explicit app bearer as well as its cookie (`readAppIdentityToken`), then
+revalidate it with the app service token. This supports embedded browsers that block cookie access.
+The bridge retains the grant only in memory and never sends it to Shell. `appFetch` rejects foreign
+origins and redirects; 401 starts recovery, while 503 preserves the credential. Custom bridge views
+must call `state.signIn` from a click and display `state.error` if present.
 
-```ts
-import { DELEGATED_TOKEN_REQUEST_TYPE, DELEGATED_TOKEN_TYPE } from "@hosty-sdk/app";
-import { parseActiveFrameDelegatedTokenRequest } from "@hosty-sdk/app/embedder";
-
-// In the embedder, per app frame. A verified request says who asked, never whether to answer: the
-// token is user-scoped, so grant it only to apps you decided to grant it to, and post it to that
-// frame's own origin — never "*". Attach the listener before the frame can run (apps ask as soon as
-// their document does, and they re-ask until answered), and honour `refresh`: it means the token the
-// app holds was refused, so a cached mint must not be handed back.
-const intent = parseActiveFrameDelegatedTokenRequest(event, frame.contentWindow, frame.src);
-if (intent) {
-  const { token, expiresAt } = await mintDelegatedTokenFromCore(appId, { force: intent.refresh });
-  frame.contentWindow.postMessage({ type: DELEGATED_TOKEN_TYPE, token, expiresAt }, frameOrigin);
-}
-```
+Embedded recovery opens Core in a popup and accepts a one-time code only from that window, the exact
+Core origin and matching random state. The app exchanges and validates the code on its own server.
+Standalone recovery uses Core navigation. No Core session credential is copied into either app.
+
+Legacy signed clients can still use `validateDelegatedToken` from `@hosty-sdk/app/delegated` for
+local signature/audience/expiry checking. An app login is not permission to mint cross-app MCP
+tokens. Do not ask Shell for a delegated token; its old responder is disabled.
 
 The design contract lives in the Hosty repository:
 [`docs/features/hosty-app-sdk/feature.md`](https://github.com/alex-de-haas/docker-host/blob/main/docs/features/hosty-app-sdk/feature.md).
@@ -121,7 +111,7 @@ License: AGPL-3.0-only.
 
 Declare `"corePermissions": ["apps.install"]` in the manifest and have an administrator approve
 that permission when installing/updating your app. This grants the ability to **request** an
-installation; it never grants the ability to approve it on the user's behalf.
+installation, update or removal; it never grants the ability to approve it on the user's behalf.
 
 Mount an app-local handler using the existing Hosty identity-cookie configuration:
 
@@ -174,15 +164,27 @@ Open an empty confirmation window synchronously in the click handler with
 `showInstallationConfirmation(popup, pending)`. Always retain a visible new-tab link for popup
 blocking. No installation-specific Shell messages or shared administrative credentials are needed.
 `prepare({ updateAppId, planDigest })` similarly requests approval of a reviewed update for clients
-with `apps.update`. A transport override supports existing Core operator clients:
+with `apps.install`. A transport override supports existing Core operator clients:
 `createInstallationClient({ baseUrl: coreOrigin + "/api/installations", request: sendCsrfJson })`.
 
+Removal uses the same flow: `prepare({ removeAppId, removalOptions: { deleteData: true,
+deleteBackups: false } })`, then `submit(draft.id, {}, false)`, Core confirmation and status polling.
+Core freezes the target installation and cleanup options during preparation; later payloads cannot
+change them. `deleteRuntimeState` defaults to true; `deleteData`, `deleteBackups`, `deleteSource`
+and `ignoreRuntimeErrors` default to false. Only report removal after status is `succeeded`.
+App credentials cannot call the direct removal endpoint, even with `apps.install`.
+
 Core's final page cannot be embedded or replaced by a custom permission-grant dialog. It requires
 an administrator browser login issued on a dedicated Core hostname, separate from app cookie
 hosts. Existing sessions need a fresh login. Requests expire after 15 minutes and Core restart
 invalidates them. Closing your UI does not cancel a confirmed operation; status is the authority.
 Never automatically retry an execution after a lost response.
 
+Optional permission choices belong exclusively to the Core confirmation page. The client cannot
+preselect them: `submit` accepts only the request ID, settings and autostart. Core starts new optional
+rights unchecked and checks rights already granted to that app. The user can grant or revoke them
+there. App settings should display grants read-only and link to Core to change permissions.
+
 ## Assistant handoffs
 
 `@hosty-sdk/app/assistant` exposes the version-1 client. Discover the confirmed assistant's
@@ -221,3 +223,23 @@ PCM16 WAV. Browser microphone consent is separate from Core permission.
 `assistant(selected, getUserToken)` returns the existing `AssistantClient` with bounded provider
 credentials and the acting user's access. It does not expose general agent execution.
 See [Provider consumption](../../docs/features/provider-consumption/feature.md) for the full contract.
+
+### Assistant MCP credentials
+
+MCP handlers use `introspectMcpToken` from `@hosty-sdk/app/scoped-token` for online validation of
+external scoped tokens and Core's assistant-only `hosty_mcp.1` tokens. The latter require explicit
+Core assistant-to-target grants and include `callerAppId` in the result. Require `mcp:read` for
+reads or `mcp:invoke` for assistant mutations, then apply your application's user permissions.
+Do not cache validation. Keep `introspectScopedToken` on ordinary APIs: it does not opt into accepting
+MCP-only credentials. Neither token permits skipping the application's own authorization.
+
+## Privileged activity renewal
+
+Identity probes used by `AppIdentityBridge` pass `activeUntil` and `activityRequired` through from
+`resolveAppSession().identity`. Keep app APIs on `appFetch`; a 401 can then request a user-click
+Core popup, exchange a code on the same origin and retry once without replacing mounted content.
+For another UI framework, use `configureAppActivity` with an app-owned `exchangeCode` function,
+listen for `APP_SESSION_ENDED`, and call `renewAppActivity` directly from a click. Do not navigate
+or reload to renew access. `appActivityNeedsRenewal()` supports proactive click renewal near expiry.
+See [the activity contract](../../docs/features/app-activity-window/feature.md), including the
+separate Core-approved assistant session leases.

package/dist/activity-react.d.ts

@@ -0,0 +1,7 @@
+/** Keep mounted beside app content so expiry never discards drafts or component state. */
+export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired }: {
+    openUrl: string;
+    appCodePath: string;
+    activeUntil?: string | null;
+    activityRequired?: boolean;
+}): import("react").JSX.Element | null;

package/dist/activity-react.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { AuthNotice, AuthNoticeButton } from "./auth-notice.js";
+import { APP_SESSION_ENDED, APP_ACTIVITY_RENEWED, appActivityNeedsRenewal, configureAppActivity, updateAppActivity, renewAppActivity, cancelActivityRenewal } from "./browser-auth.js";
+/** Keep mounted beside app content so expiry never discards drafts or component state. */
+export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired = false }) {
+    const [needed, setNeeded] = useState(false);
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState("");
+    const renew = () => {
+        const operation = renewAppActivity();
+        setPending(true);
+        setError("");
+        void operation.catch(e => { setNeeded(true); setError(String(e.message ?? e)); }).finally(() => setPending(false));
+    };
+    useEffect(() => {
+        const cleanup = configureAppActivity({ openUrl, exchangeCode: async (code) => {
+                const response = await fetch(appCodePath, { method: "POST", credentials: "same-origin", redirect: "error",
+                    headers: { "Content-Type": "application/json" }, body: JSON.stringify({ code }) });
+                const body = await response.json();
+                if (!response.ok)
+                    throw new Error(body.message ?? "Could not renew app activity.");
+                return body;
+            } });
+        const expired = () => setNeeded(true);
+        const renewed = () => { setNeeded(false); setError(""); };
+        const click = (event) => {
+            if (event.target instanceof Element && event.target.closest("[data-hosty-activity-control]"))
+                return;
+            if (event.isTrusted && appActivityNeedsRenewal()) {
+                void renewAppActivity().catch(e => { setNeeded(true); setError(String(e.message ?? e)); });
+            }
+        };
+        window.addEventListener(APP_SESSION_ENDED, expired);
+        window.addEventListener(APP_ACTIVITY_RENEWED, renewed);
+        document.addEventListener("click", click, true);
+        return () => { cleanup(); window.removeEventListener(APP_SESSION_ENDED, expired); window.removeEventListener(APP_ACTIVITY_RENEWED, renewed); document.removeEventListener("click", click, true); };
+    }, [openUrl, appCodePath]);
+    useEffect(() => { updateAppActivity(activeUntil, activityRequired); }, [activeUntil, activityRequired, openUrl, appCodePath]);
+    if (!needed)
+        return null;
+    return _jsxs(AuthNotice, { children: [_jsx("span", { children: error || "Renew access through Core to continue. Your work stays on this page." }), _jsx(AuthNoticeButton, { disabled: pending, onClick: renew, children: pending ? "Waiting for Core…" : "Renew access" }), _jsx(AuthNoticeButton, { secondary: true, onClick: () => { cancelActivityRenewal(); setNeeded(false); }, children: "Later" })] });
+}

package/dist/assistant.d.ts

@@ -1,3 +1,9 @@
+/** Preserve provider refusal details through app-owned server transports. */
+export declare class AssistantError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
 /** Version 1 of the manifest-discovered assistant handoff. */
 export type AssistantContract = {
     version?: number | null;

package/dist/assistant.js

@@ -1,3 +1,13 @@
+/** Preserve provider refusal details through app-owned server transports. */
+export class AssistantError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
 export function assistantContractError(contract) {
     return contract.version !== 1 || !Array.isArray(contract.capabilities)
         ? "This assistant does not support the required assistant interface version 1." : null;
@@ -56,7 +66,7 @@ export class AssistantClient {
                 continue;
             const body = await response.json().catch(() => null);
             if (!response.ok)
-                throw new Error(body?.message || `Assistant request failed (${response.status}).`);
+                throw new AssistantError(body?.code ?? "assistant_failed", body?.message || `Assistant request failed (${response.status}).`, response.status);
             return body;
         }
         throw new Error("Assistant authorization expired.");

package/dist/auth-notice.d.ts

@@ -0,0 +1,9 @@
+import type { ButtonHTMLAttributes, CSSProperties, ReactNode } from "react";
+/** Shared SDK chrome for sign-in and renewal, independent of the app's CSS framework. */
+export declare function AuthNotice({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function AuthNoticeButton({ secondary, disabled, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    secondary?: boolean;
+}): import("react").JSX.Element;
+export declare const authNoticeActionStyle: CSSProperties;

package/dist/auth-notice.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Shared SDK chrome for sign-in and renewal, independent of the app's CSS framework. */
+export function AuthNotice({ children }) {
+    return _jsx("div", { "data-hosty-activity-control": true, role: "status", style: barStyle, children: children });
+}
+export function AuthNoticeButton({ secondary = false, disabled, ...props }) {
+    return _jsx("button", { ...props, type: "button", disabled: disabled, style: {
+            ...authNoticeActionStyle,
+            ...(secondary ? { background: "transparent", color: "#422006", boxShadow: "inset 0 0 0 1px #a16207" } : {}),
+            ...(disabled ? { opacity: 0.65, cursor: "wait" } : {}),
+        } });
+}
+const barStyle = {
+    position: "fixed",
+    insetInline: 0,
+    bottom: 0,
+    zIndex: 2147483647,
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "12px",
+    padding: "12px 16px",
+    margin: 0,
+    border: 0,
+    borderTop: "1px solid #d97706",
+    boxSizing: "border-box",
+    background: "#fef3c7",
+    color: "#422006",
+    font: "500 14px/1.4 system-ui, sans-serif",
+    textAlign: "center",
+    boxShadow: "0 -2px 8px rgba(66,32,6,0.12)",
+};
+export const authNoticeActionStyle = {
+    display: "inline-block",
+    padding: "6px 14px",
+    margin: 0,
+    borderRadius: "8px",
+    background: "#422006",
+    color: "#fffbeb",
+    border: "none",
+    cursor: "pointer",
+    font: "650 14px/1.4 system-ui, sans-serif",
+    textDecoration: "none",
+    textTransform: "none",
+    letterSpacing: "normal",
+};

package/dist/browser-auth.d.ts

@@ -0,0 +1,24 @@
+export declare const APP_SESSION_ENDED = "hosty:app-session-ended";
+export declare function rememberAppGrant(token: string): void;
+export declare function forgetAppGrant(): void;
+export declare function appSessionActive(): void;
+/** Use for app-local API calls, including streams. Redirects cannot carry the credential away. */
+export declare function appFetch(input: string | URL, init?: RequestInit, recover?: boolean): Promise<Response>;
+/** Must be called directly from a user gesture. The popup belongs to this app frame, not Shell. */
+export declare function openAppSignIn(openUrl: string, signal?: AbortSignal): Promise<string>;
+export declare const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+export type AppActivityConfig = {
+    openUrl: string;
+    activeUntil?: string | null;
+    activityRequired?: boolean;
+    exchangeCode: (code: string) => Promise<{
+        accessToken?: string;
+        activeUntil?: string | null;
+    }>;
+};
+export declare function configureAppActivity(config: AppActivityConfig): () => void;
+export declare function updateAppActivity(activeUntil?: string | null, activityRequired?: boolean): void;
+export declare function cancelActivityRenewal(): void;
+/** Call only in response to a user gesture. The original page is never navigated or reloaded. */
+export declare function renewAppActivity(): Promise<void>;
+export declare function appActivityNeedsRenewal(now?: number): boolean;

package/dist/browser-auth.js

@@ -0,0 +1,150 @@
+/** App-only browser credentials. Never persisted or sent to an embedder. */
+let grant = null;
+let recoveryPending = false;
+export const APP_SESSION_ENDED = "hosty:app-session-ended";
+export function rememberAppGrant(token) {
+    grant = { token, origin: window.location.origin };
+    recoveryPending = false;
+}
+export function forgetAppGrant() { grant = null; recoveryPending = false; }
+export function appSessionActive() { recoveryPending = false; }
+/** Use for app-local API calls, including streams. Redirects cannot carry the credential away. */
+export async function appFetch(input, init = {}, recover = true) {
+    if (typeof window === "undefined")
+        return fetch(input, init);
+    const url = new URL(input, window.location.href);
+    if (url.origin !== window.location.origin || url.username || url.password)
+        throw new Error("App API requests must stay on this app's origin.");
+    const current = grant?.origin === url.origin ? grant : null;
+    const headers = new Headers(init.headers);
+    if (current)
+        headers.set("authorization", `Bearer ${current.token}`);
+    const response = await fetch(input, { ...init, headers, credentials: "same-origin", redirect: "error" });
+    if (response.status === 401 && recover && (!current || grant === current)) {
+        const body = await response.clone().json().catch(() => null);
+        if (activityConfig) {
+            if (body?.code !== "reauth_required" && current)
+                grant = null;
+            const renewed = waitForActivity(init.signal);
+            window.dispatchEvent(new Event(APP_SESSION_ENDED));
+            // A response may arrive while the originating click still has browser activation.
+            // Otherwise the inline button owns the next attempt; background work never opens a popup.
+            if (navigator.userActivation?.isActive)
+                void renewAppActivity().catch(() => undefined);
+            if (await renewed)
+                return appFetch(input, init, false);
+        }
+        else if (!recoveryPending) {
+            if (current)
+                grant = null;
+            recoveryPending = true;
+            window.dispatchEvent(new Event(APP_SESSION_ENDED));
+        }
+    }
+    return response;
+}
+/** Must be called directly from a user gesture. The popup belongs to this app frame, not Shell. */
+export function openAppSignIn(openUrl, signal) {
+    const url = new URL(openUrl);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+        return Promise.reject(new Error("Hosty sign-in URL is invalid."));
+    const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
+    url.searchParams.set("responseMode", "web_message");
+    url.searchParams.set("state", state);
+    return new Promise((resolve, reject) => {
+        let popup = null;
+        let settled = false;
+        const finish = (code, error) => {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener("message", receive);
+            signal?.removeEventListener("abort", abort);
+            window.clearTimeout(timer);
+            clearInterval(closedCheck);
+            popup?.close();
+            if (code)
+                resolve(code);
+            else
+                reject(new Error(error ?? "Sign-in was cancelled."));
+        };
+        const receive = (event) => {
+            if (!popup || event.source !== popup || event.origin !== url.origin)
+                return;
+            const data = event.data;
+            if (data?.type !== "hosty:app-auth-code" || data.state !== state ||
+                typeof data.code !== "string" || !data.code || data.code.length > 4096)
+                return;
+            finish(data.code);
+        };
+        const abort = () => finish();
+        const timer = window.setTimeout(() => finish(undefined, "Sign-in timed out. Please try again."), 180_000);
+        const closedCheck = setInterval(() => { if (popup?.closed)
+            finish(); }, 500);
+        window.addEventListener("message", receive);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) {
+            finish();
+            return;
+        }
+        popup = window.open(url.href, "_blank", "popup,width=520,height=700");
+        if (!popup)
+            finish(undefined, "Allow the sign-in popup and try again.");
+    });
+}
+export const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+let activityConfig = null;
+let renewal = null;
+const waiting = new Set();
+export function configureAppActivity(config) {
+    activityConfig = config;
+    return () => { if (activityConfig === config) {
+        activityConfig = null;
+        cancelActivityRenewal();
+    } };
+}
+export function updateAppActivity(activeUntil, activityRequired) {
+    if (activityConfig) {
+        activityConfig.activeUntil = activeUntil;
+        activityConfig.activityRequired = activityRequired;
+    }
+}
+export function cancelActivityRenewal() { for (const done of [...waiting])
+    done(false); }
+function waitForActivity(signal) {
+    return new Promise(resolve => {
+        const done = (ok) => { waiting.delete(done); signal?.removeEventListener("abort", abort); resolve(ok); };
+        const abort = () => done(false);
+        waiting.add(done);
+        if (signal?.aborted)
+            done(false);
+        else
+            signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Call only in response to a user gesture. The original page is never navigated or reloaded. */
+export function renewAppActivity() {
+    if (renewal)
+        return renewal;
+    const config = activityConfig;
+    if (!config)
+        return Promise.reject(new Error("App recovery is not configured."));
+    const popup = openAppSignIn(config.openUrl);
+    renewal = popup.then(async (code) => {
+        const result = await config.exchangeCode(code);
+        if (result.accessToken)
+            rememberAppGrant(result.accessToken);
+        config.activeUntil = result.activeUntil;
+        recoveryPending = false;
+        for (const done of [...waiting])
+            done(true);
+        window.dispatchEvent(new Event(APP_ACTIVITY_RENEWED));
+    }).catch(error => { cancelActivityRenewal(); throw error; }).finally(() => { renewal = null; });
+    return renewal;
+}
+export function appActivityNeedsRenewal(now = Date.now()) {
+    if (!activityConfig?.activityRequired)
+        return false;
+    const until = Date.parse(activityConfig.activeUntil ?? "");
+    return !Number.isFinite(until) || until - now < 10 * 60_000;
+}

package/dist/embedder.d.ts

@@ -82,3 +82,10 @@ export declare function createReissueRateLimiter(minIntervalMs: number, now?: ()
  * a listener. Re-derived on every launch and every page switch, so it is never stale.
  */
 export declare function appendThemeLaunchParams(redirectUri: string, theme: HostyResolvedTheme, preference: HostyThemePreference): string;
+/** Return the trusted mounted app id, ignoring any id or URL claimed by the payload. */
+export declare function parseActiveFramePermissionReview(event: EmbedderMessage, frame: unknown, url: string, appId: string): string | null;
+/** An assistant frame may request its own session review, never another app's. */
+export declare function parseActiveFrameAssistantReview(event: EmbedderMessage, frame: unknown, url: string, appId: string): {
+    appId: string;
+    sessionId: string;
+} | null;

package/dist/embedder.js

@@ -151,3 +151,17 @@ export function appendThemeLaunchParams(redirectUri, theme, preference) {
     url.searchParams.set(THEME_PREFERENCE_PARAM, preference);
     return url.toString();
 }
+/** Return the trusted mounted app id, ignoring any id or URL claimed by the payload. */
+export function parseActiveFramePermissionReview(event, frame, url, appId) {
+    if (!isActiveFrameMessage(event, frame, url))
+        return null;
+    return event.data.type === "hosty:request-permission-review" ? appId : null;
+}
+/** An assistant frame may request its own session review, never another app's. */
+export function parseActiveFrameAssistantReview(event, frame, url, appId) {
+    if (!isActiveFrameMessage(event, frame, url))
+        return null;
+    const data = event.data;
+    return data.type === "hosty:request-assistant-authority" && typeof data.sessionId === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(data.sessionId)
+        ? { appId, sessionId: data.sessionId } : null;
+}

package/dist/install-react.js

@@ -64,7 +64,7 @@ export function InstallDialog({ client, source, onClose, onInstalled }) {
         else
             popup?.close();
     };
-    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. Only host administrators can open it." }), !!plan.requestedRoles?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested provider roles" }), _jsx("ul", { children: plan.requestedRoles.map(role => _jsx("li", { children: plan.roleDescriptions?.[role] ?? role }, role)) })] }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: plan.permissionDescriptions?.[permission] ?? permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
+    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. User access is controlled by Hosty assignments." }), !!plan.requestedRoles?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested provider roles" }), _jsx("ul", { children: plan.requestedRoles.map(role => _jsx("li", { children: plan.roleDescriptions?.[role] ?? role }, role)) })] }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: plan.permissionDescriptions?.[permission] ?? permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
                                 ? _jsx("input", { type: "checkbox", checked: ["true", "1", "yes", "on", "enabled"].includes((settings[setting.key] ?? "").toLowerCase()), disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: String(event.target.checked) })) })
                                 : setting.type === "select" && setting.options?.length && !setting.secret
                                     ? _jsxs("select", { value: settings[setting.key] ?? "", disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })), children: [_jsx("option", { value: "", children: "Select a value" }), setting.options.map(option => _jsx("option", { value: option.value, children: option.label }, option.value))] })

package/dist/install.d.ts

@@ -47,11 +47,61 @@ export interface InstallationSource {
     planDigest?: string;
     /** Review permission declarations and optional grants for this installed app, without reinstalling it. */
     permissionsAppId?: string;
+    /** Request removal of this installed app. Core freezes these options for its confirmation page. */
+    removeAppId?: string;
+    removalOptions?: {
+        deleteRuntimeState?: boolean;
+        deleteData?: boolean;
+        deleteBackups?: boolean;
+        deleteSource?: boolean;
+        ignoreRuntimeErrors?: boolean;
+    };
+    hostPathChange?: {
+        kind: "source-override";
+        appId: string;
+        source: {
+            path: string;
+            commit?: string;
+        };
+    } | {
+        kind: "app-mounts";
+        appId: string;
+        mounts: {
+            mounts: {
+                key: string;
+                label?: string | null;
+                hostPath?: string | null;
+                globalMountName?: string | null;
+            }[];
+        };
+    } | {
+        kind: "global-mount";
+        globalMount: {
+            name: string;
+            hostPath: string;
+            mode?: string;
+            description?: string | null;
+        };
+    };
+    /** Personal source selection requires apps.sources as well as apps.install and Core review. */
+    sourceConnections?: {
+        manifestConnectionId?: string;
+        gitConnectionId?: string;
+        clearManifestConnection?: boolean;
+        clearGitConnection?: boolean;
+    };
 }
 export interface InstallationRequest {
     id: string;
     status: "draft" | "pending" | "executing" | "succeeded" | "denied" | "failed";
     plan: InstallPlan | null;
+    updatePlan?: {
+        appId: string;
+        displayName: string;
+        targetVersion: string;
+        targetRuntime: string;
+        changes: string[];
+    } | null;
     permissionPlan?: {
         appId: string;
         displayName: string;
@@ -61,13 +111,24 @@ export interface InstallationRequest {
         acceptedRequired?: string[];
         acceptedOptional?: string[];
     } | null;
+    removalPlan?: {
+        appId: string;
+        displayName: string;
+        version: string;
+        options: NonNullable<InstallationSource["removalOptions"]>;
+    } | null;
+    hostPathPlan?: {
+        change: InstallationSource["hostPathChange"];
+        displayName: string;
+        details: string[];
+    } | null;
     approvalUrl: string;
     expiresAt: string;
     error?: string | null;
 }
 export interface InstallationClient {
     prepare(source: InstallationSource): Promise<InstallationRequest>;
-    submit(id: string, settings: Record<string, string | null>, autostart: boolean, optionalPermissions?: string[]): Promise<InstallationRequest>;
+    submit(id: string, settings: Record<string, string | null>, autostart: boolean): Promise<InstallationRequest>;
     status(id: string): Promise<InstallationRequest>;
 }
 export declare class InstallationError extends Error {

package/dist/install.js

@@ -1,3 +1,4 @@
+import { appFetch } from "./browser-auth.js";
 export class InstallationError extends Error {
     status;
     code;
@@ -9,7 +10,7 @@ export class InstallationError extends Error {
 }
 export function createInstallationClient(options = {}) {
     const base = (options.baseUrl ?? "/api/hosty/installations").replace(/\/$/, "");
-    const request = options.request ?? ((url, body, method = "POST") => fetch(url, {
+    const request = options.request ?? ((url, body, method = "POST") => appFetch(url, {
         method, credentials: "same-origin", cache: "no-store",
         headers: { "Content-Type": "application/json" },
         body: body === undefined ? undefined : JSON.stringify(body),
@@ -25,7 +26,7 @@ export function createInstallationClient(options = {}) {
     }
     return {
         prepare: source => call("", source),
-        submit: (id, settings, autostart, optionalPermissions) => call(`/${encodeURIComponent(id)}/submit`, { settings, autostart, ...(optionalPermissions === undefined ? {} : { optionalPermissions }) }),
+        submit: (id, settings, autostart) => call(`/${encodeURIComponent(id)}/submit`, { settings, autostart }),
         status: id => call(`/${encodeURIComponent(id)}`, undefined, "GET"),
     };
 }

package/dist/permission-types.d.ts

@@ -0,0 +1,7 @@
+import type { AppPermissionState } from "./providers.js";
+export type PermissionNoticeState = {
+    hostRole: string | null;
+    appId: string;
+    corePublicOrigin: string | null;
+    permissions: AppPermissionState | null;
+};

package/dist/permission-types.js

@@ -0,0 +1 @@
+export {};