@hosty-sdk/app 0.18.0 → 0.20.0

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,31 @@
+export declare const APP_SESSION_ENDED = "hosty:app-session-ended";
+export declare const APP_GRANT_STORAGE_KEY = "hosty.auth.app-grant";
+/** Restore before the first identity probe; standalone documents use their first-party cookie. */
+export declare function restoreAppGrant(): boolean;
+export declare function rememberAppGrant(token: string): void;
+export declare function forgetAppGrant(): void;
+/** Snapshot the grant generation so older probes cannot invalidate a renewed identity. */
+export declare function appGrantRevision(): number;
+/** Activity expiry keeps identity; only explicit identity rejection discards the credential. */
+export declare function forgetRejectedAppGrant(code: unknown, expectedRevision?: number): boolean;
+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,217 @@
+/** App-only credentials. Embedded documents keep them for this tab on the app's own origin. */
+let grant = null;
+let grantRevision = 0;
+let recoveryPending = false;
+export const APP_SESSION_ENDED = "hosty:app-session-ended";
+export const APP_GRANT_STORAGE_KEY = "hosty.auth.app-grant";
+function isEmbedded() {
+    try {
+        return window.self !== window.top;
+    }
+    catch {
+        return true;
+    }
+}
+/** Restore before the first identity probe; standalone documents use their first-party cookie. */
+export function restoreAppGrant() {
+    if (typeof window === "undefined")
+        return false;
+    if (grant?.origin === window.location.origin)
+        return true;
+    if (!isEmbedded())
+        return false;
+    try {
+        const token = window.sessionStorage.getItem(APP_GRANT_STORAGE_KEY);
+        if (token) {
+            grant = { token, origin: window.location.origin };
+            grantRevision++;
+        }
+    }
+    catch {
+        // Blocked storage leaves the in-memory transport available.
+    }
+    return grant?.origin === window.location.origin;
+}
+export function rememberAppGrant(token) {
+    grant = { token, origin: window.location.origin };
+    grantRevision++;
+    recoveryPending = false;
+    if (isEmbedded()) {
+        try {
+            window.sessionStorage.setItem(APP_GRANT_STORAGE_KEY, token);
+        }
+        catch { /* In-memory fallback. */ }
+    }
+}
+export function forgetAppGrant() {
+    if (grant)
+        grantRevision++;
+    grant = null;
+    recoveryPending = false;
+    if (typeof window !== "undefined") {
+        try {
+            window.sessionStorage.removeItem(APP_GRANT_STORAGE_KEY);
+        }
+        catch { /* In-memory fallback. */ }
+    }
+}
+/** Snapshot the grant generation so older probes cannot invalidate a renewed identity. */
+export function appGrantRevision() { return grantRevision; }
+/** Activity expiry keeps identity; only explicit identity rejection discards the credential. */
+export function forgetRejectedAppGrant(code, expectedRevision = grantRevision) {
+    if (expectedRevision !== grantRevision)
+        return false;
+    if (typeof code !== "string" || !["token_invalid", "token_revoked", "token_expired", "token_app_mismatch"].includes(code))
+        return false;
+    forgetAppGrant();
+    return true;
+}
+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 || response.status === 403) && grant === current && !init.signal?.aborted) {
+        const revision = grantRevision;
+        const body = await response.clone().json().catch(() => null);
+        if (grant !== current || grantRevision !== revision || init.signal?.aborted)
+            return response;
+        // Identity probes disable recovery, but a rejected grant must still be forgotten. Activity
+        // expiry is different: the identity remains valid and the popup renews the same session.
+        const rejected = forgetRejectedAppGrant(body?.code);
+        if (response.status !== 401)
+            return response;
+        if (!rejected && recover && body?.code !== "reauth_required" && current)
+            forgetAppGrant();
+        if (!recover)
+            return response;
+        if (activityConfig) {
+            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) {
+            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

@@ -13,7 +13,8 @@ export type AuthRequiredMessage = EmbedderMessage;
  * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
  * - the payload's `appId` must match the app the embedder actually mounted there.
  * No credential crosses the boundary in either direction: the payload is only the app id,
- * and the embedder answers by reissuing a code through its own authenticated Core call.
+ * and the app owns its direct sign-in with Core. This parser gives the embedder no authority
+ * to issue or redeem credentials for the app.
  */
 export declare function parseActiveFrameAuthRequired(event: AuthRequiredMessage, activeFrameWindow: unknown, activeFrameUrl: string, expectedAppId: string): boolean;
 /** A verified request, and the one thing its payload carries. */
@@ -82,3 +83,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

@@ -3,10 +3,10 @@
 // functions plus a small rate limiter — the embedder wires them to its own DOM, its own "open
 // this app" flow, and its own Core session.
 //
-// Recovery, in one sentence: on a VERIFIED `hosty:auth-required` from an app you embed,
-// re-run your normal open flow for that app (which mints a fresh launch code), rate-limited.
-// The re-open must take the full launch-code path — an "already open → reuse the URL
-// without a code" optimization must not short-circuit recovery.
+// Authentication belongs to the app frame: it restores its own per-tab grant, tries a silent
+// Core navigation on first load, and opens its own Core popup when interaction is required.
+// An embedder may observe a verified `hosty:auth-required` intent, but never carries or
+// redeems another app's code or grant.
 //
 // Delegated tokens, in one sentence: on a VERIFIED `hosty:request-delegated-token` from an app
 // you have decided to grant one, mint a token from Core with your own session and post it back
@@ -21,7 +21,8 @@ import { THEME_PARAM, THEME_PREFERENCE_PARAM } from "./theme.js";
  * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
  * - the payload's `appId` must match the app the embedder actually mounted there.
  * No credential crosses the boundary in either direction: the payload is only the app id,
- * and the embedder answers by reissuing a code through its own authenticated Core call.
+ * and the app owns its direct sign-in with Core. This parser gives the embedder no authority
+ * to issue or redeem credentials for the app.
  */
 export function parseActiveFrameAuthRequired(event, activeFrameWindow, activeFrameUrl, expectedAppId) {
     if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
@@ -151,3 +152,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;
+}