@hosty-sdk/app 0.17.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

@@ -45,19 +45,82 @@ export interface InstallationSource {
     selectedRuntime?: string;
     updateAppId?: string;
     planDigest?: string;
-    /** Review optional grants for this installed app, without reinstalling it. */
+    /** 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;
         required: string[];
         optional: string[];
         granted: string[];
+        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;

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),

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 {};

package/dist/permissions-react.d.ts

@@ -0,0 +1,4 @@
+/** App-owned GET endpoint authenticates the viewer and calls readOwnPermissionNotice. */
+export declare function MissingPermissionsNotice({ endpoint }: {
+    endpoint?: string;
+}): import("react").JSX.Element | null;

package/dist/permissions-react.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { appFetch } from "./browser-auth.js";
+import { permissionNotice, requestPermissionReview } from "./permissions.js";
+/** App-owned GET endpoint authenticates the viewer and calls readOwnPermissionNotice. */
+export function MissingPermissionsNotice({ endpoint = "/api/hosty/permissions" }) {
+    const [state, setState] = useState(null);
+    const [dismissed, setDismissed] = useState(false);
+    const [pending, setPending] = useState(false);
+    useEffect(() => {
+        const controller = new AbortController();
+        let loading = false;
+        const refresh = async () => {
+            if (loading)
+                return;
+            loading = true;
+            try {
+                const response = await appFetch(endpoint, { cache: "no-store", signal: controller.signal });
+                if (!response.ok) {
+                    setState(null);
+                    return;
+                }
+                const next = await response.json();
+                if (!controller.signal.aborted) {
+                    setState(next);
+                    if (!permissionNotice(next))
+                        setPending(false);
+                }
+            }
+            catch { /* A transient failure must not erase a known setup warning. */ }
+            finally {
+                loading = false;
+            }
+        };
+        void refresh();
+        window.addEventListener("focus", refresh);
+        const timer = pending ? window.setInterval(refresh, 2000) : undefined;
+        return () => { controller.abort(); window.removeEventListener("focus", refresh); window.clearInterval(timer); };
+    }, [endpoint, pending]);
+    const kind = state && permissionNotice(state);
+    if (dismissed || !kind || !state)
+        return null;
+    return _jsxs("section", { "data-hosty-activity-control": true, role: "alert", "aria-label": "Required permissions", style: { border: "1px solid currentColor", padding: 12, margin: 8, borderRadius: 8, color: "#c2410c" }, children: [kind === "unsupported"
+                ? _jsxs("p", { children: ["Core does not support required permissions: ", state.permissions.unsupportedRequired.join(", "), ". Update the app or Core."] })
+                : _jsx("p", { children: "This app needs required permissions. Operations using them are unavailable until approval." }), kind === "missing" && state.permissions?.reviewAvailable !== false && state.corePublicOrigin &&
+                _jsx("button", { type: "button", onClick: () => { requestPermissionReview(state); setPending(true); }, children: "Request permissions" }), pending && _jsx("p", { children: "Review permissions in Core, then return here. You can leave this app installed without approving." }), _jsx("button", { type: "button", onClick: () => { setDismissed(true); setPending(false); }, style: { marginLeft: 12 }, children: "Dismiss" })] });
+}

package/dist/permissions-server.d.ts

@@ -0,0 +1,6 @@
+import { type ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+import type { PermissionNoticeState } from "./permission-types.js";
+/** Server-only: pass the role from an authenticated session, never from request input. */
+export declare function readOwnPermissionNotice(hostRole: string | null, options?: ProviderServerOptions & {
+    corePublicOrigin?: string | null;
+}, signal?: AbortSignal): Promise<PermissionNoticeState>;

package/dist/permissions-server.js

@@ -0,0 +1,13 @@
+import { ProviderClient } from "@hosty-sdk/app/providers/server";
+/** Server-only: pass the role from an authenticated session, never from request input. */
+export async function readOwnPermissionNotice(hostRole, options = {}, signal) {
+    const state = {
+        hostRole,
+        appId: options.appId ?? process.env.HOSTY_APP_ID ?? "",
+        corePublicOrigin: options.corePublicOrigin ?? process.env.HOSTY_CORE_PUBLIC_ORIGIN ?? null,
+        permissions: null,
+    };
+    if (hostRole === "host.admin")
+        state.permissions = await new ProviderClient(options).permissions(signal);
+    return state;
+}

package/dist/permissions.d.ts

@@ -0,0 +1,8 @@
+import type { PermissionNoticeState } from "./permission-types.js";
+export type { PermissionNoticeState } from "./permission-types.js";
+export declare const PERMISSION_REVIEW_REQUEST = "hosty:request-permission-review";
+/** No optional declaration, or declaration alone, confers authority. */
+export declare function permissionNotice(state: PermissionNoticeState): "missing" | "unsupported" | null;
+export declare function permissionReviewUrl(corePublicOrigin: string, appId: string): string;
+/** Invoke synchronously from a user click. The embedder determines the app from its frame. */
+export declare function requestPermissionReview(state: PermissionNoticeState, browser?: Pick<Window, "parent" | "open">): void;

package/dist/permissions.js

@@ -0,0 +1,25 @@
+export const PERMISSION_REVIEW_REQUEST = "hosty:request-permission-review";
+/** No optional declaration, or declaration alone, confers authority. */
+export function permissionNotice(state) {
+    if (state.hostRole !== "host.admin" || !state.permissions)
+        return null;
+    const p = state.permissions;
+    if (p.unsupportedRequired?.length)
+        return "unsupported";
+    return p.required.some(name => !p.granted.includes(name)) ? "missing" : null;
+}
+export function permissionReviewUrl(corePublicOrigin, appId) {
+    const core = new URL(corePublicOrigin);
+    if (!["http:", "https:"].includes(core.protocol) || core.username || core.password)
+        throw new Error("Invalid Core origin");
+    return new URL(`/install/permissions/${encodeURIComponent(appId)}`, core.origin).href;
+}
+/** Invoke synchronously from a user click. The embedder determines the app from its frame. */
+export function requestPermissionReview(state, browser = window) {
+    if (permissionNotice(state) !== "missing" || state.permissions?.reviewAvailable === false || !state.corePublicOrigin)
+        return;
+    if (browser.parent !== browser)
+        browser.parent.postMessage({ type: PERMISSION_REVIEW_REQUEST }, "*");
+    else
+        browser.open(permissionReviewUrl(state.corePublicOrigin, state.appId), "_blank", "noopener,noreferrer");
+}

package/dist/providers-server.d.ts

@@ -1,5 +1,5 @@
-import { AssistantClient } from "./assistant.js";
-import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "./providers.js";
+import { AssistantClient } from "@hosty-sdk/app/assistant";
+import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "@hosty-sdk/app/providers";
 export type ProviderServerOptions = {
     appId?: string;
     coreOrigin?: string;

package/dist/providers-server.js

@@ -1,5 +1,5 @@
-import { AssistantClient } from "./assistant.js";
-import { ProviderError } from "./providers.js";
+import { AssistantClient } from "@hosty-sdk/app/assistant";
+import { ProviderError } from "@hosty-sdk/app/providers";
 /** Server-only provider client. Its app service token must never be sent to a browser or provider. */
 export class ProviderClient {
     appId;

package/dist/providers.d.ts

@@ -14,6 +14,9 @@ export type AppPermissionState = {
     required: string[];
     optional: string[];
     granted: string[];
+    reviewAvailable?: boolean;
+    unsupportedRequired?: string[];
+    status?: string;
 };
 export type ProviderInvocation = {
     callerAppId: string;

package/dist/react.d.ts

@@ -34,6 +34,8 @@ export type AppIdentityBridgeState = {
     kind: "signin";
     openUrl: string | null;
     embedded: boolean;
+    signIn?: () => void;
+    error?: string;
 } | {
     kind: "denied";
 } | {
@@ -48,15 +50,16 @@ export interface AppIdentityBridgeProps {
     appCodePath?: string;
     /** Optional app-owned rendering, including loading and active content. Recovery remains SDK-owned. */
     renderState?: (state: AppIdentityBridgeState) => ReactNode;
+    children?: ReactNode;
 }
 /**
  * Mount once at the top of the root layout body. On first load it consumes a `?code` from
  * the URL (exchanging it for the identity cookie), then probes the session and runs the
- * recovery decision: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * recovery decision: an app-owned Core popup when embedded, a once-per-tab
  * redirect through Core `/open` when standalone, and cards only in fallback/terminal states
  * — never a login UI while recovery is still running.
  */
-export declare function AppIdentityBridge({ probePath, appCodePath, renderState, }?: AppIdentityBridgeProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export declare function AppIdentityBridge({ probePath, appCodePath, renderState, children, }?: AppIdentityBridgeProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 export interface HostThemeBridgeProps {
     /**
      * Whether the operating system decides the theme while no shell has spoken — `true` unless the
@@ -85,3 +88,5 @@ export interface HostThemeBridgeProps {
  * choice is not overruled by the OS.
  */
 export declare function HostThemeBridge({ followSystem, onTheme }?: HostThemeBridgeProps): null;
+export { MissingPermissionsNotice } from "./permissions-react.js";
+export { AppActivityBridge } from "./activity-react.js";

package/dist/react.js

@@ -3,15 +3,15 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 // React slice: the client identity bridge — probe, silent recovery, and the fallback
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
+import { AppActivityBridge } from "./activity-react.js";
+import { AuthNotice, AuthNoticeButton, authNoticeActionStyle } from "./auth-notice.js";
 import { useEffect, useRef, useState } from "react";
+import { appFetch, appSessionActive, rememberAppGrant, openAppSignIn, APP_SESSION_ENDED } from "./browser-auth.js";
 import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, normalizeLaunchMode, readRecoveryParams, resolveLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY, } from "./index.js";
 import { applyTheme, parseShellThemeMessage, resolveTheme, THEME_PARAM, THEME_PREFERENCE_PARAM, THEME_PREFERENCE_STORAGE_KEY, THEME_STORAGE_KEY, } from "./theme.js";
 // Once-per-tab guard so a standalone app that returns from Core still unauthorized does
 // not bounce through /open forever. Cleared on a successful code exchange.
 const RECOVERY_GUARD_KEY = "hosty.auth.recovery-attempted";
-// How long an embedded frame waits for the Shell to reissue a launch code before showing
-// the manual sign-in fallback (i.e. it is embedded by something other than Hosty Shell).
-const EMBEDDED_RECOVERY_TIMEOUT_MS = 4_000;
 // Cap the status probe so a stalled request cannot leave the bridge stuck hidden — on
 // timeout it classifies as unavailable and the user gets a Retry affordance.
 const IDENTITY_PROBE_TIMEOUT_MS = 4_000;
@@ -144,14 +144,16 @@ export function useLaunchMode() {
 /**
  * Mount once at the top of the root layout body. On first load it consumes a `?code` from
  * the URL (exchanging it for the identity cookie), then probes the session and runs the
- * recovery decision: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * recovery decision: an app-owned Core popup when embedded, a once-per-tab
  * redirect through Core `/open` when standalone, and cards only in fallback/terminal states
  * — never a login UI while recovery is still running.
  */
-export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, } = {}) {
+export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, children, } = {}) {
     const [ui, setUi] = useState({ kind: "recovering" });
     // A launch code is single-use. Strict Mode replays the effect after the URL is cleaned;
     // keep its exchange alive and let the replacement effect await the same response.
+    const wasActive = useRef(false);
+    const [activity, setActivity] = useState(null);
     const exchangeRef = useRef(null);
     useEffect(() => {
         let cancelled = false;
@@ -168,16 +170,19 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             let openUrl = null;
             let appId = null;
             try {
-                const response = await fetch(probePath, {
+                const response = await appFetch(probePath, {
                     headers: { Accept: "application/json" },
                     cache: "no-store",
                     signal: probeController.signal,
-                });
+                }, false);
                 const body = await response.json().catch(() => null);
                 status = readProbedSessionStatus(body);
                 const recovery = readRecoveryParams(body);
                 appId = recovery.appId;
                 openUrl = appId ? buildCoreOpenUrl(recovery.corePublicOrigin, appId, window.location) : null;
+                const metadata = body;
+                if (!cancelled && openUrl)
+                    setActivity({ openUrl, activeUntil: metadata?.activeUntil, activityRequired: metadata?.activityRequired });
             }
             catch {
                 // A failed or timed-out probe (Core unreachable) classifies as unavailable below.
@@ -201,25 +206,33 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 });
             switch (action.kind) {
                 case "none":
+                    appSessionActive();
+                    wasActive.current = true;
                     setUi({ kind: "active" });
                     return;
                 case "post-auth-required": {
-                    // The payload carries no secret, so targetOrigin "*" is safe — the Shell verifies
-                    // the sender before acting, and answers by swapping the iframe src.
-                    try {
-                        window.parent.postMessage(action.intent, "*");
-                    }
-                    catch {
-                        // Ignore; the timeout below still falls back to the manual sign-in card.
-                    }
-                    const timeoutId = window.setTimeout(() => {
-                        if (!cancelled) {
-                            setUi({ kind: "signin", openUrl, embedded: true });
-                        }
-                    }, EMBEDDED_RECOVERY_TIMEOUT_MS);
-                    controller.signal.addEventListener("abort", () => window.clearTimeout(timeoutId), {
-                        once: true,
-                    });
+                    const showSignIn = (error) => setUi({ kind: "signin", openUrl, embedded: true, error,
+                        signIn: openUrl ? () => {
+                            // Open synchronously in the click handler; an awaited request loses the user gesture.
+                            const result = openAppSignIn(openUrl, controller.signal);
+                            setUi({ kind: "recovering" });
+                            void result.then(async (code) => {
+                                const response = await appFetch(appCodePath, {
+                                    method: "POST", headers: { "Content-Type": "application/json" },
+                                    body: JSON.stringify({ code }),
+                                });
+                                const body = await response.json();
+                                if (!response.ok || typeof body.accessToken !== "string" || !body.accessToken)
+                                    throw new Error("Hosty could not establish this app session.");
+                                if (cancelled)
+                                    return;
+                                rememberAppGrant(body.accessToken);
+                                writeGuard(false);
+                                await probeAndRecover();
+                            }).catch(error => { if (!cancelled)
+                                showSignIn(error instanceof Error ? error.message : "Sign-in failed."); });
+                        } : undefined });
+                    showSignIn();
                     return;
                 }
                 case "redirect":
@@ -233,6 +246,11 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                     return;
             }
         }
+        const recover = () => { if (!cancelled && !wasActive.current) {
+            setUi({ kind: "recovering" });
+            void probeAndRecover();
+        } };
+        window.addEventListener(APP_SESSION_ENDED, recover);
         const url = new URL(window.location.href);
         const code = url.searchParams.get("code")?.trim();
         if (code) {
@@ -250,13 +268,17 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         const exchange = exchangeRef.current;
         if (exchange && exchange.path === appCodePath) {
             void exchange.response
-                .then((response) => {
+                .then(async (response) => {
                 if (cancelled) {
                     return;
                 }
                 if (response.ok) {
                     writeGuard(false);
-                    window.location.reload();
+                    const body = await response.json().catch(() => null);
+                    if (typeof body?.accessToken === "string")
+                        rememberAppGrant(body.accessToken);
+                    exchangeRef.current = null;
+                    await probeAndRecover();
                 }
                 else {
                     exchangeRef.current = null;
@@ -276,43 +298,19 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         return () => {
             cancelled = true;
             controller.abort();
+            window.removeEventListener(APP_SESSION_ENDED, recover);
         };
     }, [probePath, appCodePath]);
+    if (wasActive.current)
+        return _jsxs(_Fragment, { children: [activity && _jsx(AppActivityBridge, { ...activity, appCodePath: appCodePath }), renderState ? renderState({ kind: "active" }) : children] });
     if (renderState)
         return renderState(ui);
-    if (ui.kind === "recovering" || ui.kind === "active") {
-        return null;
-    }
-    return (_jsx("div", { role: "status", style: barStyle, children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: "Your Hosty session ended." }), ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: actionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), style: actionStyle, children: "Retry" })] })) }));
+    if (ui.kind === "active")
+        return children ?? null;
+    if (ui.kind === "recovering")
+        return _jsx(AuthNotice, { children: "Connecting to Hosty\u2026" });
+    return (_jsx(AuthNotice, { children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: ui.error ?? "Sign in through Hosty to use this app." }), ui.signIn ? _jsx(AuthNoticeButton, { onClick: ui.signIn, children: "Sign in via Hosty" }) : ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: authNoticeActionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx(AuthNoticeButton, { onClick: () => window.location.reload(), children: "Retry" })] })) }));
 }
-const barStyle = {
-    position: "fixed",
-    insetInline: 0,
-    bottom: 0,
-    zIndex: 2147483647,
-    display: "flex",
-    flexWrap: "wrap",
-    alignItems: "center",
-    justifyContent: "center",
-    gap: "0.75rem",
-    padding: "0.75rem 1rem",
-    background: "#111827",
-    color: "#f9fafb",
-    font: "500 0.875rem/1.4 system-ui, sans-serif",
-    boxShadow: "0 -1px 0 rgba(255,255,255,0.08)",
-};
-const actionStyle = {
-    display: "inline-block",
-    padding: "0.4rem 0.85rem",
-    borderRadius: "0.5rem",
-    background: "#f9fafb",
-    color: "#111827",
-    border: "none",
-    cursor: "pointer",
-    font: "inherit",
-    fontWeight: 650,
-    textDecoration: "none",
-};
 function readStoredTheme(key) {
     try {
         return window.sessionStorage.getItem(key);
@@ -411,3 +409,5 @@ export function HostThemeBridge({ followSystem = true, onTheme } = {}) {
     }, []);
     return null;
 }
+export { MissingPermissionsNotice } from "./permissions-react.js";
+export { AppActivityBridge } from "./activity-react.js";

package/dist/scoped-token.d.ts

@@ -5,6 +5,7 @@ export type ScopedTokenIntrospection = {
     sub: string;
     role: string | null;
     scopes: string[];
+    callerAppId?: string;
 } | {
     active: false;
     error?: ScopedTokenError;
@@ -40,9 +41,13 @@ export interface IntrospectScopedTokenOptions {
  * window that would take back.
  */
 export declare function introspectScopedToken(token: string, options?: IntrospectScopedTokenOptions): Promise<ScopedTokenIntrospection>;
+/** MCP handlers only. Ordinary APIs must use introspectScopedToken, which rejects MCP-only tokens. */
+export declare function introspectMcpToken(token: string, options?: IntrospectScopedTokenOptions): Promise<ScopedTokenIntrospection>;
 /** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
  * constant rather than text a caller should normalize. */
 export declare function hasScope(result: ScopedTokenIntrospection, scope: string): boolean;
 /** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
  * that introduces mutations. */
 export declare const SCOPE_MCP_READ = "mcp:read";
+/** A Core-authorized assistant may invoke MCP operations subject to the target user policy. */
+export declare const SCOPE_MCP_INVOKE = "mcp:invoke";

package/dist/scoped-token.js

@@ -20,6 +20,13 @@ const DEFAULT_TIMEOUT_MS = 2_000;
  * window that would take back.
  */
 export async function introspectScopedToken(token, options = {}) {
+    return introspect(token, options);
+}
+/** MCP handlers only. Ordinary APIs must use introspectScopedToken, which rejects MCP-only tokens. */
+export async function introspectMcpToken(token, options = {}) {
+    return introspect(token, options, "mcp");
+}
+async function introspect(token, options, purpose) {
     const appId = options.appId?.trim() || process.env.HOSTY_APP_ID?.trim();
     const serviceToken = options.serviceToken?.trim() || process.env.HOSTY_APP_SERVICE_TOKEN?.trim();
     // No fallback origin is invented when the variable is missing. Core injects HOSTY_CORE_ORIGIN
@@ -59,7 +66,7 @@ export async function introspectScopedToken(token, options = {}) {
         response = await fetch(endpoint, {
             method: "POST",
             headers: { authorization: `Bearer ${serviceToken}`, "content-type": "application/json" },
-            body: JSON.stringify({ token, ...(options.tool ? { tool: options.tool } : {}) }),
+            body: JSON.stringify({ token, ...(purpose ? { purpose } : {}), ...(options.tool ? { tool: options.tool } : {}) }),
             cache: "no-store",
             signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
         });
@@ -130,6 +137,7 @@ export async function introspectScopedToken(token, options = {}) {
         sub: body.sub,
         role: typeof body.role === "string" ? body.role : null,
         scopes: body.scopes,
+        ...(typeof body.callerAppId === "string" ? { callerAppId: body.callerAppId } : {}),
     };
 }
 /** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
@@ -140,3 +148,5 @@ export function hasScope(result, scope) {
 /** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
  * that introduces mutations. */
 export const SCOPE_MCP_READ = "mcp:read";
+/** A Core-authorized assistant may invoke MCP operations subject to the target user policy. */
+export const SCOPE_MCP_INVOKE = "mcp:invoke";

package/dist/server.d.ts

@@ -21,6 +21,8 @@ export interface HostIdentity {
     /** `mapHostRole(hostRole)` when the config provides the hook, else the raw host role. */
     appRole: string | null;
     expiresAt: string | null;
+    activeUntil?: string | null;
+    activityRequired?: boolean;
 }
 /** Structured detail for a failed resolution: the Core HTTP status (null when Core was
  * never reached) plus a machine-readable code and human-readable message. Codes pass
@@ -49,9 +51,8 @@ export type HeaderReader = {
     get(name: string): string | null;
 };
 /**
- * Reads the app identity token from a request: the app-origin cookie first (authoritative
- * when present), then the Authorization bearer fallback the browser sends when the
- * cross-site cookie is blocked, then the legacy inbound identity header.
+ * Reads an explicitly presented app grant first, then the app cookie and legacy identity header.
+ * A recovered iframe grant must not be shadowed by an older cookie.
  */
 export declare function readAppIdentityToken(headers: HeaderReader, config: HostyAppConfig): string | null;
 /** True when the effective request protocol is https (honouring the forwarded proto). */
@@ -90,6 +91,7 @@ export type AppCodeExchange = {
     ok: true;
     accessToken: string;
     expiresInSeconds: number | null;
+    activeUntil?: string | null;
 } | {
     ok: false;
     status: number;

package/dist/server.js

@@ -31,15 +31,10 @@ export function getRecoveryParams(config) {
     return { appId: getAppId(config), corePublicOrigin: getCorePublicOrigin() };
 }
 /**
- * Reads the app identity token from a request: the app-origin cookie first (authoritative
- * when present), then the Authorization bearer fallback the browser sends when the
- * cross-site cookie is blocked, then the legacy inbound identity header.
+ * Reads an explicitly presented app grant first, then the app cookie and legacy identity header.
+ * A recovered iframe grant must not be shadowed by an older cookie.
  */
 export function readAppIdentityToken(headers, config) {
-    const cookieToken = readCookie(headers.get("cookie"), config.identityCookieName);
-    if (cookieToken) {
-        return cookieToken;
-    }
     const authorization = headers.get("authorization")?.trim();
     if (authorization?.toLowerCase().startsWith("bearer ")) {
         const token = authorization.slice("bearer ".length).trim();
@@ -47,7 +42,7 @@ export function readAppIdentityToken(headers, config) {
             return token;
         }
     }
-    return headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
+    return readCookie(headers.get("cookie"), config.identityCookieName) || headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
 }
 /** True when the effective request protocol is https (honouring the forwarded proto). */
 export function isSecureRequest(headers, requestProtocol) {
@@ -200,6 +195,8 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
         hostRole,
         appRole: config.mapHostRole ? config.mapHostRole(hostRole) : hostRole,
         expiresAt,
+        activeUntil: readString(payload.activeUntil),
+        activityRequired: payload.activityRequired === true,
     };
     const expiresAtMs = expiresAt ? Date.parse(expiresAt) : Number.NaN;
     if (Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {
@@ -291,7 +288,7 @@ export async function exchangeAppCode(code) {
     const expiresInSeconds = typeof payload?.expiresInSeconds === "number" && payload.expiresInSeconds > 0
         ? payload.expiresInSeconds
         : null;
-    return { ok: true, accessToken, expiresInSeconds };
+    return { ok: true, accessToken, expiresInSeconds, activeUntil: readString(payload?.activeUntil) };
 }
 /**
  * Route-handler factory for `POST /api/auth/app-code`: exchanges the one-time `code` for
@@ -301,6 +298,14 @@ export async function exchangeAppCode(code) {
  */
 export function createAppCodeRouteHandler(config) {
     return async function POST(request) {
+        const origin = request.headers.get("origin");
+        let sameOrigin = request.headers.get("sec-fetch-site") === "same-origin";
+        try {
+            sameOrigin ||= !!origin && new URL(origin).host === (request.headers.get("host") ?? new URL(request.url).host);
+        }
+        catch { /* invalid origin */ }
+        if (!sameOrigin)
+            return jsonResponse({ code: "cross_site_request_blocked", message: "Sign-in must originate from this app." }, 403);
         let body = null;
         try {
             body = await request.json();
@@ -316,6 +321,9 @@ export function createAppCodeRouteHandler(config) {
         if (!exchange.ok) {
             return jsonResponse({ code: exchange.code, message: exchange.message }, exchange.status);
         }
+        const identity = await resolveAppSession(exchange.accessToken, config);
+        if (identity.status !== "active")
+            return jsonResponse({ code: "app_identity_rejected", message: "Core could not validate this app session." }, identity.status === "unavailable" || identity.status === "misconfigured" ? 503 : 403);
         const secure = isSecureRequest(request.headers, safeProtocol(request.url));
         const attributes = identityCookieAttributes(secure, Math.min(exchange.expiresInSeconds ?? MAX_COOKIE_AGE_SECONDS, MAX_COOKIE_AGE_SECONDS));
         const cookie = [
@@ -326,7 +334,7 @@ export function createAppCodeRouteHandler(config) {
             "HttpOnly",
             ...(attributes.secure ? ["Secure"] : []),
         ].join("; ");
-        return jsonResponse({ accessToken: exchange.accessToken, expiresInSeconds: exchange.expiresInSeconds }, 200, { "set-cookie": cookie });
+        return jsonResponse({ accessToken: exchange.accessToken, expiresInSeconds: exchange.expiresInSeconds, activeUntil: exchange.activeUntil }, 200, { "set-cookie": cookie });
     };
 }
 function safeProtocol(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.17.0",
+  "version": "0.19.1",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -13,6 +13,10 @@
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
     },
+    "./browser-auth": {
+      "types": "./dist/browser-auth.d.ts",
+      "default": "./dist/browser-auth.js"
+    },
     "./delegated": {
       "types": "./dist/delegated.d.ts",
       "default": "./dist/delegated.js"
@@ -60,6 +64,18 @@
     "./providers/server": {
       "types": "./dist/providers-server.d.ts",
       "default": "./dist/providers-server.js"
+    },
+    "./permissions": {
+      "types": "./dist/permissions.d.ts",
+      "default": "./dist/permissions.js"
+    },
+    "./permissions/server": {
+      "types": "./dist/permissions-server.d.ts",
+      "default": "./dist/permissions-server.js"
+    },
+    "./permissions/react": {
+      "types": "./dist/permissions-react.d.ts",
+      "default": "./dist/permissions-react.js"
     }
   },
   "scripts": {
@@ -85,7 +101,11 @@
     "@types/node": "^24.19.0",
     "@types/react": "^19.3.0",
     "typescript": "^6",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1"
   },
   "repository": {
     "type": "git",