@hosty-sdk/app 0.21.2 → 0.22.1

package/README.md

@@ -11,37 +11,75 @@ 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, Core popup/navigation recovery, content gate |
+| `@hosty-sdk/app/react` | client | `<HostyOverlay />` — shared loading, identity, required setup and recovery UI; legacy bridges remain available |
+| `@hosty-sdk/app/session/server` | server | Framework-neutral session response adapter for authenticated Node servers |
 | `@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` |
 
-Minimal Next.js wiring:
+Minimal Next.js wiring (the configuration object stays server-side):
 
 ```tsx
-// app/layout.tsx
-import { AppIdentityBridge } from "@hosty-sdk/app/react";
-// wrap protected client content: <AppIdentityBridge>{children}</AppIdentityBridge>
+// app/layout.tsx — inside the body and the existing theme/launch providers
+import { HostyOverlay } from "@hosty-sdk/app/react";
+// <HostyOverlay>{children}</HostyOverlay>
 
-// Reuse an active probe that already returns the app's session fields:
-// <AppIdentityBridge probePath="/api/auth/session" onSession={seedSessionCache}>
-//   {children}
-// </AppIdentityBridge>
-// seedSessionCache receives unknown JSON; validate app-specific fields before caching.
-// The callback runs before children mount, only for a successful active probe.
+// lib/hosty.ts
+export const hostyConfig = {
+  appIdFallback: "com.example.my-app",
+  identityCookieName: "my_app_hosty_identity",
+};
 
-// app/api/auth/app-code/route.ts
-import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
+// app/api/hosty/session/route.ts
+import { createHostySessionRouteHandler } from "@hosty-sdk/app/server";
+import { hostyConfig } from "@/lib/hosty";
 export const dynamic = "force-dynamic";
 export const runtime = "nodejs";
-export const POST = createAppCodeRouteHandler({
-  appIdFallback: "com.example.my-app",
-  identityCookieName: "my_app_hosty_identity",
-});
+export const GET = createHostySessionRouteHandler(hostyConfig);
+// Administrator-only app: pass { administratorOnly: true } as the second argument.
+
+// app/api/auth/app-code/route.ts
+import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
+import { hostyConfig } from "@/lib/hosty";
+export const POST = createAppCodeRouteHandler(hostyConfig);
 ```
 
+Replace the protected scope's `AppIdentityBridge`, `AppActivityBridge`, custom sign-in rendering
+and `MissingPermissionsNotice` with one `HostyOverlay`. Keep public routes outside that scope.
+Existing launch/theme bridges and bootstrap scripts stay in place. The only optional overlay props
+are `probePath` and `appCodePath` for existing route names; it has no visual customization API.
+API routes and server-rendered data still enforce their own authorization. The overlay delays
+protected client mounting; it is not a server data-access boundary.
+
+The session adapter resolves identity and checks the app's declared required permissions together.
+Only an administrator receives permission details and a Core review action; a regular user sees an
+administrator-setup explanation without buttons. Optional permissions do not block the app.
+A missing setup capability on Core displays a compatibility state instead of exposing content.
+Keep service credentials on the server and use `appFetch` for app-local browser requests.
+
+For a plain Node server, call `createHostySessionResponse(validatedSession, recovery, options)` from
+`@hosty-sdk/app/session/server` and forward its response. Pass a server-validated session, never an
+identity supplied by the request body. Harness is the in-repository example. Shell retains its
+HttpOnly-only code exchange; the shared coordinator also accepts a successful exchange without a
+browser-readable token.
+
+After first mount, blocked content and app portals become hidden and inert while the component tree
+remains mounted. Same-user renewal restores it. A different stable user ID reloads the app document
+and refuses to replay old pending requests. `APP_SESSION_RESTORED` from `/browser-auth` is an optional
+DOM notification with `detail.userId`; it contains no credential. There is no generic draft persistence
+across reloads or cache-clearing framework. Existing identity idle/absolute lifetimes and fixed
+privileged activity windows still apply.
+
+Compatible SDK updates change standard presentation and recovery after a dependency update and
+rebuild, without editing this wiring. New mandatory Core capabilities can require upgrading Core.
+`node packages/app-sdk/scripts/check-overlay-upgrade.mjs` checks the published export layout using
+identical consumer source before and after a dependency-only presentation revision (run SDK build first).
+
+Legacy `AppIdentityBridge` exports, `renderState` and `onSession` remain compatible for consumers
+that have not migrated. See [Hosty Overlay](../../docs/features/hosty-overlay/feature.md) for behavior.
+
 Following the shell's theme — the launch parameters decide the theme a document loads with, the
 `hosty:shell-theme` post covers changes while the frame is up, and the bootstrap keeps the first
 paint right:

package/dist/activity-react.d.ts

@@ -1,6 +1,6 @@
 import type { AppAuthProtocol } from "./app-code.js";
 /** Keep mounted beside app content so expiry never discards drafts or component state. */
-export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired, appAuthProtocol, probePath, native }: {
+export type AppActivityOptions = {
     openUrl: string;
     appCodePath: string;
     activeUntil?: string | null;
@@ -8,4 +8,13 @@ export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, a
     appAuthProtocol?: AppAuthProtocol | null;
     probePath?: string;
     native?: boolean;
-}): import("react").JSX.Element | null;
+    validateSession?: () => Promise<boolean>;
+};
+export declare function useAppActivity(options: AppActivityOptions | null): {
+    needed: boolean;
+    pending: boolean;
+    error: string;
+    renew: () => void;
+    cancel: () => void;
+};
+export declare function AppActivityBridge(options: AppActivityOptions): import("react").JSX.Element | null;

package/dist/activity-react.js

@@ -5,8 +5,8 @@ import { AuthNotice, AuthNoticeButton } from "./auth-notice.js";
 import { APP_SESSION_ENDED, APP_ACTIVITY_RENEWED, appActivityNeedsRenewal, configureAppActivity, updateAppActivity, renewAppActivity, cancelActivityRenewal } from "./browser-auth.js";
 import { resolveLaunchMode, detectLaunchMode, normalizeLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY } from "./index.js";
 import { acceptAppAuthProtocol, refreshAppAuthProtocol } 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, appAuthProtocol, probePath = "/api/auth/identity", native }) {
+export function useAppActivity(options) {
+    const { openUrl, appCodePath = "/api/auth/app-code", activeUntil, activityRequired = false, appAuthProtocol, probePath = "/api/auth/identity", native, validateSession } = options ?? {};
     const [needed, setNeeded] = useState(false);
     const [pending, setPending] = useState(false);
     const [error, setError] = useState("");
@@ -17,6 +17,8 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         void operation.catch(e => { setNeeded(true); setError(String(e.message ?? e)); }).finally(() => setPending(false));
     };
     useEffect(() => {
+        if (!openUrl)
+            return;
         let cancelled = false;
         let cleanup;
         const controller = new AbortController();
@@ -31,7 +33,7 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
             const mode = normalizeLaunchMode(document.documentElement.getAttribute(LAUNCH_MODE_ATTRIBUTE)) ?? resolveLaunchMode({
                 param: new URL(window.location.href).searchParams.get(LAUNCH_MODE_PARAM), stored, heuristic: detectLaunchMode(window),
             }).mode;
-            cleanup = configureAppActivity({ openUrl, appAuthProtocol: protocol, probePath, native: native ?? mode === "native", activeUntil, activityRequired, exchangeCode: async (proof) => {
+            cleanup = configureAppActivity({ openUrl, appAuthProtocol: protocol, probePath, native: native ?? mode === "native", activeUntil, activityRequired, validateSession, exchangeCode: async (proof) => {
                     const response = await fetch(appCodePath, { method: "POST", credentials: "same-origin", redirect: "error",
                         headers: { "Content-Type": "application/json" }, body: JSON.stringify(proof) });
                     const body = await response.json();
@@ -59,9 +61,13 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         window.addEventListener(APP_ACTIVITY_RENEWED, renewed);
         document.addEventListener("click", click, true);
         return () => { cancelled = true; controller.abort(); cleanup?.(); window.removeEventListener(APP_SESSION_ENDED, expired); window.removeEventListener(APP_ACTIVITY_RENEWED, renewed); document.removeEventListener("click", click, true); };
-    }, [openUrl, appCodePath, appAuthProtocol, probePath, native]);
+    }, [openUrl, appCodePath, appAuthProtocol, probePath, native, validateSession]);
     useEffect(() => { updateAppActivity(activeUntil, activityRequired); }, [activeUntil, activityRequired, openUrl, appCodePath]);
+    return { needed, pending, error, renew, cancel: () => { cancelActivityRenewal(); setNeeded(false); } };
+}
+export function AppActivityBridge(options) {
+    const { needed, pending, error, renew, cancel } = useAppActivity(options);
     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" })] });
+    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: cancel, children: "Later" })] });
 }

package/dist/browser-auth.d.ts

@@ -45,6 +45,8 @@ export declare function refreshAppAuthProtocol(openUrl: string, probePath?: stri
 /** Must be called directly from a user gesture. Native hosts intercept before any request. */
 export declare function openAppSignIn(openUrl: string, signal?: AbortSignal, appAuthProtocol?: AppAuthProtocol, native?: boolean, probePath?: string): Promise<AppSignInResult>;
 export declare const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+/** Validated restoration of the same actor, before the app resumes protected work. */
+export declare const APP_SESSION_RESTORED = "hosty:app-session-restored";
 export type AppActivityConfig = {
     openUrl: string;
     appAuthProtocol: AppAuthProtocol;
@@ -56,6 +58,8 @@ export type AppActivityConfig = {
         accessToken?: string;
         activeUntil?: string | null;
     }>;
+    /** The root coordinator verifies actor and setup before any waiting request can retry. */
+    validateSession?: () => Promise<boolean>;
 };
 export declare function configureAppActivity(config: AppActivityConfig): () => void;
 export declare function updateAppActivity(activeUntil?: string | null, activityRequired?: boolean): void;

package/dist/browser-auth.js

@@ -265,6 +265,11 @@ export async function appFetch(input, init = {}, recover = true) {
     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.");
+    // Mounted app effects can still run behind the overlay. Do not send their requests with
+    // the newly exchanged credential until the coordinator has checked the actor and setup.
+    // SDK identity/protocol probes use recover=false so that validation itself can proceed.
+    if (recover && renewal && activityConfig?.validateSession && !await waitForActivity(init.signal))
+        return Response.json({ code: "reauth_required", message: "Hosty access has not been restored." }, { status: 401 });
     const current = grant?.origin === url.origin ? grant : null;
     const headers = new Headers(init.headers);
     if (current)
@@ -521,6 +526,8 @@ function openNativeAppSignIn(attempt, signal) {
     });
 }
 export const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
+/** Validated restoration of the same actor, before the app resumes protected work. */
+export const APP_SESSION_RESTORED = "hosty:app-session-restored";
 let activityConfig = null;
 let renewal = null;
 let renewalController = null;
@@ -571,6 +578,10 @@ export function renewAppActivity() {
         if (result.accessToken)
             rememberAppGrant(result.accessToken);
         config.activeUntil = result.activeUntil;
+        if (config.validateSession && !await config.validateSession())
+            throw new Error("Access has not been restored. Complete the Hosty setup before continuing.");
+        if (controller.signal.aborted || activityConfig !== config)
+            throw new Error("Sign-in was cancelled.");
         recoveryPending = false;
         for (const done of [...waiting])
             done(true);

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { AppSessionStatus, AppSessionFailureStatus, SessionRecoveryParams } from "./session-types.js";
+export type { AppSessionStatus, AppSessionFailureStatus, SessionRecoveryParams } from "./session-types.js";
 /**
  * The postMessage type for an embedded app's authentication-required intent.
  * A frozen protocol constant: it deliberately does not track product branding (precedent:
@@ -71,22 +73,6 @@ export interface DelegatedTokenGrant {
 export declare function createDelegatedTokenRequest(options?: {
     refresh?: boolean;
 }): DelegatedTokenRequest;
-/**
- * Recovery classification of an app session, per the platform identity error contract:
- * - `not-present`: no token at all (recoverable — same handling as `expired`).
- * - `active`: token revalidated OK.
- * - `expired`: Core 401 — recoverable; re-authorize via the Shell (embedded) or Core `/open`
- *   (standalone).
- * - `forbidden`: Core 403 or a token minted for a different app — terminal; never
- *   auto-redirect (it would loop).
- * - `unavailable`: Core unreachable, slow, or answering garbage — transient; keep the
- *   cookie and offer a retry.
- * - `misconfigured`: the app itself is broken (no service token / no Core origin) — an
- *   operator problem; signing in cannot fix it, so never offer a login.
- */
-export type AppSessionStatus = "not-present" | "active" | "expired" | "forbidden" | "unavailable" | "misconfigured";
-/** Failure statuses (everything but `active`). */
-export type AppSessionFailureStatus = Exclude<AppSessionStatus, "active">;
 /**
  * Maps a Core revalidation HTTP status onto the session classification. Classification is
  * by status code only — never by error-code strings — so new Core codes cannot break an
@@ -99,11 +85,6 @@ export declare function classifyRevalidationHttpStatus(status: number): AppSessi
  * prerendered at image build time, where the HOSTY_* environment does not exist yet
  * (docker-host PR #233 / media-server PR #63). Neither value is secret.
  */
-export interface SessionRecoveryParams {
-    appId: string | null;
-    corePublicOrigin: string | null;
-    appAuthProtocol: 1 | 2 | null;
-}
 export declare function readRecoveryParams(body: unknown): SessionRecoveryParams;
 /** True for hosts that only resolve on the machine itself. */
 export declare function isLoopbackHost(hostname: string): boolean;

package/dist/index.js

@@ -86,6 +86,12 @@ export function classifyRevalidationHttpStatus(status) {
     }
     return "unavailable";
 }
+/**
+ * Recovery parameters an app's force-dynamic identity/session endpoint hands the browser.
+ * They ride in a response — never in a server-component prop — because app pages are
+ * prerendered at image build time, where the HOSTY_* environment does not exist yet
+ * (docker-host PR #233 / media-server PR #63). Neither value is secret.
+ */
 export function readRecoveryParams(body) {
     const recovery = body && typeof body === "object" ? body.recovery : null;
     if (!recovery || typeof recovery !== "object") {

package/dist/overlay-react.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+/** Mount once around protected content. Presentation and recovery belong to Hosty. */
+export declare function HostyOverlay({ children, probePath, appCodePath }: {
+    children: ReactNode;
+    probePath?: string;
+    appCodePath?: string;
+}): import("react").JSX.Element;

package/dist/overlay-react.js

@@ -0,0 +1,252 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useAppIdentity } from "./react.js";
+import { useAppActivity } from "./activity-react.js";
+import { APP_SESSION_ENDED, APP_SESSION_RESTORED, APP_ACTIVITY_RENEWED, acceptAppAuthProtocol } from "./browser-auth.js";
+import { buildCoreOpenUrl, readRecoveryParams } from "./index.js";
+import { permissionReviewUrl, requestPermissionReview } from "./permissions.js";
+function snapshot(body) {
+    const value = body;
+    if (value?.status !== "active" || typeof value.userId !== "string" || !value.userId)
+        return null;
+    const setup = value.hosty?.version === 1 && ["ready", "missing", "unsupported", "unavailable", "incompatible"].includes(String(value.hosty.setup))
+        ? value.hosty.setup : "incompatible";
+    const recovery = readRecoveryParams(body);
+    const openUrl = recovery.appId ? buildCoreOpenUrl(recovery.corePublicOrigin, recovery.appId, window.location) : null;
+    // The activity policy remains authoritative even when renewal discovery fails.
+    return { userId: value.userId, setup, notice: value.hosty?.notice,
+        activityRequired: value.activityRequired === true,
+        activeUntil: typeof value.activeUntil === "string" ? value.activeUntil : null,
+        recoveryReady: !!openUrl && !!acceptAppAuthProtocol(new URL(openUrl).origin, recovery.appAuthProtocol) };
+}
+function activityExpired(session) {
+    const deadline = Date.parse(session?.activeUntil ?? "");
+    return !!session?.activityRequired && (!Number.isFinite(deadline) || deadline <= Date.now());
+}
+function sessionReady(session) {
+    return session?.setup === "ready" && (!session.activityRequired || session.recoveryReady) && !activityExpired(session);
+}
+/** Mount once around protected content. Presentation and recovery belong to Hosty. */
+export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code" }) {
+    const actor = useRef(null);
+    const changingActor = useRef(false);
+    const [session, setSession] = useState(null);
+    const [reviewing, setReviewing] = useState(false);
+    const renewedAwaitingReadiness = useRef(false);
+    const accept = (body) => {
+        const next = snapshot(body);
+        if (next && actor.current && actor.current !== next.userId) {
+            changingActor.current = true;
+            window.location.reload();
+        }
+        if (next && !actor.current)
+            actor.current = next.userId;
+        setSession(next);
+    };
+    const identity = useAppIdentity({ probePath, appCodePath, onSession: accept });
+    const refreshRef = useRef(identity.refresh);
+    refreshRef.current = async () => {
+        const body = await identity.refresh();
+        const next = snapshot(body);
+        if (renewedAwaitingReadiness.current && next && sessionReady(next) && next.userId === actor.current && !changingActor.current) {
+            renewedAwaitingReadiness.current = false;
+            window.dispatchEvent(new CustomEvent(APP_SESSION_RESTORED, { detail: { userId: next.userId } }));
+            window.dispatchEvent(new Event(APP_ACTIVITY_RENEWED));
+        }
+        return body;
+    };
+    const validate = useRef(async () => {
+        const next = snapshot(await refreshRef.current());
+        if (!next || changingActor.current || next.userId !== actor.current)
+            return false;
+        renewedAwaitingReadiness.current = !sessionReady(next);
+        if (renewedAwaitingReadiness.current)
+            return false;
+        window.dispatchEvent(new CustomEvent(APP_SESSION_RESTORED, { detail: { userId: next.userId } }));
+        return true;
+    }).current;
+    const activity = useAppActivity(identity.activity ? { ...identity.activity, probePath, appCodePath, validateSession: validate } : null);
+    const expired = activityExpired(session);
+    const recoveryUnavailable = session?.activityRequired && !session.recoveryReady;
+    const ready = identity.ui.kind === "active" && sessionReady(session) && !activity.needed && !activity.pending && !changingActor.current;
+    const mounted = useRef(false);
+    if (ready)
+        mounted.current = true;
+    useEffect(() => {
+        if (session?.setup === "ready")
+            setReviewing(false);
+    }, [session?.setup]);
+    useEffect(() => {
+        // No keepalive polling. Focus and a pending Core review are the only readiness refreshes.
+        let loading = false;
+        const refresh = () => {
+            if (loading || !actor.current || activity.pending || (activity.needed && !renewedAwaitingReadiness.current))
+                return;
+            loading = true;
+            void refreshRef.current().finally(() => { loading = false; });
+        };
+        window.addEventListener("focus", refresh);
+        const timer = reviewing ? window.setInterval(refresh, 2000) : undefined;
+        return () => { window.removeEventListener("focus", refresh); window.clearInterval(timer); };
+    }, [reviewing, activity.pending, activity.needed]);
+    useEffect(() => {
+        const metadata = session;
+        if (!metadata?.activityRequired || !metadata.activeUntil)
+            return;
+        const remaining = Date.parse(metadata.activeUntil) - Date.now();
+        if (!Number.isFinite(remaining))
+            return;
+        // Real activity windows are short. Do not expire a malformed far-future value early.
+        if (remaining > 2147483647)
+            return;
+        const timer = window.setTimeout(() => window.dispatchEvent(new Event(APP_SESSION_ENDED)), Math.max(0, remaining));
+        return () => window.clearTimeout(timer);
+    }, [session?.activeUntil, session?.activityRequired]);
+    let title = "Connecting to Hosty";
+    let message = "Checking your access…";
+    let action;
+    let actionLabel = "Retry";
+    let reviewUrl;
+    const pending = identity.ui.kind === "recovering" || activity.pending || changingActor.current;
+    if (identity.ui.kind === "signin") {
+        title = "Sign in to continue";
+        message = identity.ui.error ?? "Use your Hosty account to open this app.";
+        action = identity.hasBeenActive && identity.activity ? activity.renew : identity.ui.signIn;
+        actionLabel = "Sign in via Hosty";
+        if (!action)
+            message = "Open this app from Hosty, or ask the administrator to check its public address.";
+    }
+    else if (identity.ui.kind === "denied") {
+        title = "Access unavailable";
+        message = "Your account does not have access to this app.";
+    }
+    else if (identity.ui.kind === "misconfigured") {
+        title = "App setup required";
+        message = "This app needs configuration. Contact your administrator.";
+    }
+    else if (identity.ui.kind === "unavailable") {
+        title = "Cannot reach Hosty";
+        message = "Check the connection and try again.";
+        action = () => { void refreshRef.current(); };
+    }
+    else if (identity.ui.kind === "active" && session?.setup !== "ready") {
+        if (!session || session.setup === "incompatible" || session.setup === "unsupported") {
+            title = "Hosty update required";
+            message = "This app and Core need compatible versions. Contact your administrator.";
+        }
+        else if (session.setup === "unavailable") {
+            title = "Cannot check app setup";
+            message = "Hosty could not check required permissions. Try again.";
+            action = () => { void refreshRef.current(); };
+        }
+        else {
+            title = "App setup required";
+            message = "This app needs configuration by an administrator.";
+            const notice = session.notice;
+            if (notice?.hostRole === "host.admin" && notice.corePublicOrigin && notice.permissions?.reviewAvailable !== false) {
+                message = reviewing ? "Review the required permissions in Core, then return here." : "Review this app’s required permissions in Hosty Core.";
+                actionLabel = "Review permissions";
+                action = () => { requestPermissionReview(notice); setReviewing(true); };
+                if (reviewing)
+                    reviewUrl = permissionReviewUrl(notice.corePublicOrigin, notice.appId);
+            }
+        }
+    }
+    else if (identity.ui.kind === "active" && recoveryUnavailable) {
+        title = "Cannot verify access renewal";
+        message = "Hosty could not verify how to renew this app’s access. Try again.";
+        action = () => { void refreshRef.current(); };
+    }
+    else if (expired || activity.needed || activity.pending) {
+        title = activity.pending ? "Connecting to Hosty" : "Renew access to continue";
+        message = activity.error || (activity.pending ? "Complete the confirmation in Core." : "Confirm your access through Hosty Core.");
+        action = activity.renew;
+        actionLabel = "Renew access";
+    }
+    return _jsxs(_Fragment, { children: [_jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: mounted.current ? children : null }), !ready && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
+}
+function OverlaySurface({ pending, title, message, action, actionLabel, reviewUrl }) {
+    const [portal, setPortal] = useState(null);
+    const [showProgress, setShowProgress] = useState(false);
+    const dialog = useRef(null);
+    useEffect(() => {
+        if (!pending) {
+            setShowProgress(false);
+            return;
+        }
+        const timer = window.setTimeout(() => setShowProgress(true), 180);
+        return () => window.clearTimeout(timer);
+    }, [pending]);
+    useLayoutEffect(() => {
+        const container = document.createElement("div");
+        container.dataset.hostyOverlayPortal = "";
+        const previousFocus = document.activeElement;
+        const original = new Map();
+        document.body.append(container);
+        document.documentElement.setAttribute("data-hosty-overlay-blocked", "");
+        const block = () => {
+            for (const element of Array.from(document.body.children)) {
+                if (!(element instanceof HTMLElement) || element === container || original.has(element))
+                    continue;
+                original.set(element, element.inert);
+                element.inert = true;
+            }
+        };
+        block();
+        const observer = new MutationObserver(block);
+        observer.observe(document.body, { childList: true });
+        setPortal(container);
+        return () => {
+            observer.disconnect();
+            original.forEach((inert, element) => { element.inert = inert; });
+            document.documentElement.removeAttribute("data-hosty-overlay-blocked");
+            container.remove();
+            if (previousFocus instanceof HTMLElement && previousFocus.isConnected)
+                previousFocus.focus();
+        };
+    }, []);
+    useLayoutEffect(() => {
+        const element = dialog.current;
+        // Replayed effects can still reference the dialog in the removed portal until state catches up.
+        if (!element?.isConnected)
+            return;
+        if (typeof element.showModal === "function")
+            element.showModal();
+        else
+            element.setAttribute("open", "");
+        element.focus();
+        return () => { if (element.open && typeof element.close === "function")
+            element.close(); };
+    }, [portal]);
+    const content = _jsxs(_Fragment, { children: [_jsx("style", { children: styles }), _jsx("dialog", { ref: dialog, className: "hosty-overlay-dialog", "aria-label": "Hosty access", tabIndex: -1, onCancel: event => event.preventDefault(), "data-hosty-activity-control": true, children: _jsx("section", { className: "hosty-overlay-card", "aria-live": "polite", "aria-busy": pending, children: pending ? _jsx("div", { className: "hosty-overlay-loading", role: "status", "aria-label": title, children: showProgress && _jsxs(_Fragment, { children: [_jsx("span", { className: "hosty-overlay-spinner" }), _jsx("p", { children: message })] }) }) : _jsxs(_Fragment, { children: [_jsxs("span", { className: "hosty-overlay-brand", children: [_jsx("span", { className: "hosty-overlay-brand-mark", children: _jsxs("svg", { viewBox: "0 0 100 100", "aria-hidden": "true", focusable: "false", fill: "none", stroke: "currentColor", strokeWidth: 6, strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: "M25 36 V64 M75 36 V64 M25 50 H39 M61 50 H75" }), _jsx("rect", { x: "17", y: "17", width: "16", height: "16", rx: "4.5" }), _jsx("rect", { x: "67", y: "17", width: "16", height: "16", rx: "4.5" }), _jsx("rect", { x: "17", y: "67", width: "16", height: "16", rx: "4.5" }), _jsx("rect", { x: "67", y: "67", width: "16", height: "16", rx: "4.5" }), _jsx("rect", { x: "42", y: "42", width: "16", height: "16", rx: "4.5" })] }) }), _jsx("span", { children: "Hosty" })] }), _jsx("h1", { children: title }), _jsx("p", { children: message }), action && _jsx("button", { type: "button", onClick: action, children: actionLabel }), reviewUrl && _jsx("a", { href: reviewUrl, target: "_blank", rel: "noopener noreferrer", children: "Open Core permissions" })] }) }) })] });
+    return portal ? createPortal(content, portal) : _jsx("div", { className: "hosty-overlay-boot", role: "status", "aria-label": "Connecting to Hosty", children: _jsx("style", { children: styles }) });
+}
+const styles = `
+.hosty-overlay-boot,.hosty-overlay-dialog{--hosty-bg:#f8f9fb;--hosty-fg:#20242c;--hosty-muted:#606875;--hosty-border:#e0e4eb;color-scheme:light}
+html.dark .hosty-overlay-dialog,html[data-hosty-theme=dark] .hosty-overlay-dialog,html.dark .hosty-overlay-boot{--hosty-bg:#14171c;--hosty-fg:#f0f2f5;--hosty-muted:#a2aab7;--hosty-border:#323843;color-scheme:dark}
+.hosty-overlay-boot{position:fixed;inset:0;background:var(--hosty-bg);z-index:2147483647}
+html[data-hosty-overlay-blocked] body>:not([data-hosty-overlay-portal]){visibility:hidden!important}
+html[data-hosty-overlay-blocked],html[data-hosty-overlay-blocked] body{background:#f8f9fb!important}
+html.dark[data-hosty-overlay-blocked],html.dark[data-hosty-overlay-blocked] body{background:#14171c!important}
+html[data-hosty-launch=embedded][data-hosty-overlay-blocked],html[data-hosty-launch=embedded][data-hosty-overlay-blocked] body{background:transparent!important}
+.hosty-overlay-dialog{position:fixed;inset:0;width:100%;height:100%;max-width:none;max-height:none;box-sizing:border-box;margin:0;padding:24px;border:0;background:var(--hosty-bg);color:var(--hosty-fg);font:400 14px/1.55 system-ui,sans-serif;outline:0}
+.hosty-overlay-dialog[open]{display:grid;place-items:center}
+.hosty-overlay-dialog::backdrop{background:transparent}
+html[data-hosty-launch=embedded] .hosty-overlay-dialog,html[data-hosty-launch=embedded] .hosty-overlay-boot{background:transparent}
+.hosty-overlay-card{width:min(100%,360px);text-align:center;animation:hosty-overlay-enter 160ms ease-out}
+.hosty-overlay-brand{display:flex;align-items:center;justify-content:center;gap:8px;color:var(--hosty-fg);font-size:14px;font-weight:600;text-transform:uppercase;margin-bottom:22px}
+.hosty-overlay-brand-mark{display:flex;align-items:center;justify-content:center;width:20px;height:20px;flex-shrink:0}
+.hosty-overlay-brand-mark svg{width:24px;height:24px;flex-shrink:0}
+.hosty-overlay-card h1{font:600 22px/1.3 system-ui,sans-serif;letter-spacing:-.025em;margin:0 0 12px;color:var(--hosty-fg)}
+.hosty-overlay-card p{margin:0 0 24px;color:var(--hosty-muted)}
+.hosty-overlay-card button{appearance:none;border:1px solid var(--hosty-border);border-radius:9px;background:var(--hosty-fg);color:var(--hosty-bg);padding:10px 18px;font:600 14px/1.4 system-ui,sans-serif;cursor:pointer}
+.hosty-overlay-card button:focus-visible,.hosty-overlay-card a:focus-visible{outline:2px solid var(--hosty-muted);outline-offset:4px}
+.hosty-overlay-card a{display:block;color:var(--hosty-muted);font-size:13px;margin-top:18px;text-decoration:underline}
+.hosty-overlay-loading{min-height:100px;color:var(--hosty-muted)}
+.hosty-overlay-spinner{display:inline-block;width:20px;height:20px;margin:0 0 16px;border:2px solid var(--hosty-border);border-top-color:var(--hosty-muted);border-radius:50%;animation:hosty-overlay-spin .8s linear infinite}
+@keyframes hosty-overlay-spin{to{transform:rotate(360deg)}}
+@keyframes hosty-overlay-enter{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:translateY(0)}}
+@media(prefers-reduced-motion:reduce){.hosty-overlay-card,.hosty-overlay-spinner{animation:none}}
+`;

package/dist/react.d.ts

@@ -1,3 +1,4 @@
+import type { AppAuthProtocol } from "./app-code.js";
 import type { ReactNode } from "react";
 import { type AppLaunchMode, type AppSessionStatus } from "./index.js";
 import { type HostyResolvedTheme, type HostyThemePreference } from "./theme.js";
@@ -62,7 +63,19 @@ export interface AppIdentityBridgeProps {
  * 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, onSession, 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 declare function useAppIdentity({ probePath, appCodePath, onSession, }?: Pick<AppIdentityBridgeProps, "probePath" | "appCodePath" | "onSession">): {
+    ui: AppIdentityBridgeState;
+    session: unknown;
+    activity: {
+        openUrl: string;
+        appAuthProtocol: AppAuthProtocol;
+        activeUntil?: string | null;
+        activityRequired?: boolean;
+    } | null;
+    hasBeenActive: boolean;
+    refresh: () => Promise<unknown>;
+};
+export declare function AppIdentityBridge({ renderState, children, ...options }?: 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
@@ -93,3 +106,4 @@ export interface HostThemeBridgeProps {
 export declare function HostThemeBridge({ followSystem, onTheme }?: HostThemeBridgeProps): null;
 export { MissingPermissionsNotice } from "./permissions-react.js";
 export { AppActivityBridge } from "./activity-react.js";
+export { HostyOverlay } from "./overlay-react.js";

package/dist/react.js

@@ -187,8 +187,10 @@ export function useLaunchMode() {
  * 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, onSession, children, } = {}) {
+export function useAppIdentity({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", onSession, } = {}) {
     const [ui, setUi] = useState({ kind: "recovering" });
+    const [session, setSession] = useState(null);
+    const refreshRef = useRef(async () => null);
     // 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);
@@ -203,10 +205,12 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
     useEffect(() => { onSessionRef.current = onSession; }, [onSession]);
     useEffect(() => {
         let cancelled = false;
+        let probeSequence = 0;
         const controller = new AbortController();
         if (initialGrantPresent.current === null)
             initialGrantPresent.current = restoreAppGrant();
         async function probeAndRecover() {
+            const sequence = ++probeSequence;
             // Dedicated controller + setTimeout instead of AbortSignal.any/timeout, which are not
             // available in every browser (a synchronous throw here would stop the bridge from
             // ever rendering). Aborts on effect teardown or when the probe times out.
@@ -249,13 +253,12 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 window.clearTimeout(probeTimeout);
                 controller.signal.removeEventListener("abort", abortProbe);
             }
-            if (cancelled) {
-                return;
+            if (cancelled || sequence !== probeSequence) {
+                return null;
             }
             if (revision !== appGrantRevision()) {
                 initialGrantPresent.current ||= restoreAppGrant();
-                void probeAndRecover();
-                return;
+                return probeAndRecover();
             }
             forgetRejectedAppGrant(rejectionCode, revision);
             if (openUrl && protocol)
@@ -295,16 +298,21 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 });
             switch (action.kind) {
                 case "none":
+                    setSession(sessionBody);
                     onSessionRef.current?.(sessionBody);
                     appSessionActive();
                     wasActive.current = true;
                     setUi({ kind: "active" });
-                    return;
+                    return sessionBody;
                 case "post-auth-required": {
                     showSignIn();
                     return;
                 }
                 case "redirect":
+                    if (wasActive.current) {
+                        showSignIn();
+                        return null;
+                    }
                     if (appId && protocol && beginNavigationSignIn(action.openUrl, appId, protocol, mode === "native" ? "native" : "standalone", shouldUpgrade))
                         return;
                     showSignIn("Allow app storage, or sign in with a popup.");
@@ -329,7 +337,7 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                                 body: JSON.stringify(proof),
                             }, false);
                             const body = await response.json();
-                            if (!response.ok || typeof body.accessToken !== "string" || !body.accessToken)
+                            if (!response.ok)
                                 throw new Error("Hosty could not establish this app session.");
                             if (cancelled)
                                 return;
@@ -337,7 +345,8 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                                 await probeAndRecover();
                                 return;
                             }
-                            rememberAppGrant(body.accessToken);
+                            if (typeof body.accessToken === "string" && body.accessToken)
+                                rememberAppGrant(body.accessToken);
                             silentError.current = null;
                             writeGuard(false);
                             await probeAndRecover();
@@ -346,6 +355,7 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                     } : undefined });
             }
         }
+        refreshRef.current = probeAndRecover;
         const recover = () => { if (!cancelled && !wasActive.current) {
             setUi({ kind: "recovering" });
             void probeAndRecover();
@@ -420,11 +430,17 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         }
         return () => {
             cancelled = true;
+            refreshRef.current = async () => null;
             controller.abort();
             window.removeEventListener(APP_SESSION_ENDED, recover);
         };
     }, [probePath, appCodePath]);
-    if (wasActive.current)
+    return { ui, session, activity, hasBeenActive: wasActive.current, refresh: () => refreshRef.current() };
+}
+export function AppIdentityBridge({ renderState, children, ...options } = {}) {
+    const { ui, activity, hasBeenActive } = useAppIdentity(options);
+    const { appCodePath = "/api/auth/app-code", probePath = "/api/auth/identity" } = options;
+    if (hasBeenActive)
         return _jsxs(_Fragment, { children: [activity && _jsx(AppActivityBridge, { ...activity, appCodePath: appCodePath, probePath: probePath }), renderState ? renderState({ kind: "active" }) : children] });
     if (renderState)
         return renderState(ui);
@@ -534,3 +550,4 @@ export function HostThemeBridge({ followSystem = true, onTheme } = {}) {
 }
 export { MissingPermissionsNotice } from "./permissions-react.js";
 export { AppActivityBridge } from "./activity-react.js";
+export { HostyOverlay } from "./overlay-react.js";

package/dist/server.d.ts

@@ -43,6 +43,10 @@ export type AppSessionResolution = {
     error?: ResolutionError;
 };
 export declare function getAppId(config: HostyAppConfig): string;
+/** Standard root-overlay identity and required-setup endpoint, with app-owned access policy. */
+export declare function createHostySessionRouteHandler(config: HostyAppConfig, options?: {
+    administratorOnly?: boolean;
+}): (request: Request) => Promise<Response>;
 export declare function getCoreOrigin(): string | null;
 /** Browser-reachable Core origin. Core always injects it (falls back to its loopback
  * listen URL on localhost-only installs), so a missing value is a broken environment. */

package/dist/server.js

@@ -1,6 +1,7 @@
 // Server slice: Next route-handler factories and Core revalidation. Never reaches a client
 // bundle — the service token lives here.
 import "server-only";
+import { createHostySessionResponse } from "./session-server.js";
 import { resolveAppAuthProtocol, appAuthProtocolMinimum, isValidCodeVerifier } from "./app-code.js";
 export { isValidCodeVerifier } from "./app-code.js";
 import { classifyRevalidationHttpStatus, } from "./index.js";
@@ -18,6 +19,15 @@ export const HOSTY_APP_IDENTITY_HEADER = "x-docker-host-identity";
 export function getAppId(config) {
     return process.env.HOSTY_APP_ID?.trim() || config.appIdFallback;
 }
+/** Standard root-overlay identity and required-setup endpoint, with app-owned access policy. */
+export function createHostySessionRouteHandler(config, options = {}) {
+    return async (request) => {
+        const [session, recovery] = await Promise.all([
+            resolveAppSession(readAppIdentityToken(request.headers, config), config), getRecoveryParams(config),
+        ]);
+        return createHostySessionResponse(session, recovery, { ...options, signal: request.signal });
+    };
+}
 export function getCoreOrigin() {
     return process.env.HOSTY_CORE_ORIGIN?.trim() || null;
 }

package/dist/session-server.d.ts

@@ -0,0 +1,21 @@
+import { type ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+import type { AppSessionStatus, SessionRecoveryParams } from "./session-types.js";
+/** Framework-neutral server adapter. Call with an already authenticated app session, never request data. */
+export type HostySessionInput = {
+    status: AppSessionStatus;
+    identity?: {
+        userId: string;
+        hostRole: string | null;
+        activeUntil?: string | null;
+        activityRequired?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+        status: number | null;
+    };
+};
+export declare function createHostySessionResponse(session: HostySessionInput, recovery: SessionRecoveryParams, options?: ProviderServerOptions & {
+    administratorOnly?: boolean;
+    signal?: AbortSignal;
+}): Promise<Response>;

package/dist/session-server.js

@@ -0,0 +1,27 @@
+import { ProviderClient } from "@hosty-sdk/app/providers/server";
+import { ProviderError } from "@hosty-sdk/app/providers";
+export async function createHostySessionResponse(session, recovery, options = {}) {
+    const headers = { "Cache-Control": "no-store" };
+    if (session.status !== "active" || !session.identity)
+        return Response.json({ status: session.status, error: session.error, recovery }, { headers });
+    const identity = session.identity;
+    if (options.administratorOnly && identity.hostRole !== "host.admin")
+        return Response.json({ status: "forbidden", recovery }, { headers });
+    let setup = "unavailable";
+    let notice;
+    try {
+        const permissions = await new ProviderClient({ ...options, appId: recovery.appId ?? undefined }).permissions(options.signal);
+        if (![permissions.required, permissions.optional, permissions.granted, permissions.unsupportedRequired ?? []].every(list => Array.isArray(list) && list.every(name => typeof name === "string")))
+            throw new Error("Invalid permission state.");
+        setup = permissions.unsupportedRequired?.length ? "unsupported"
+            : permissions.required.some(name => !permissions.granted.includes(name)) ? "missing" : "ready";
+        if (identity.hostRole === "host.admin")
+            notice = { hostRole: identity.hostRole, appId: recovery.appId ?? "",
+                corePublicOrigin: recovery.corePublicOrigin, permissions };
+    }
+    catch (error) {
+        if (error instanceof ProviderError && error.status === 404)
+            setup = "incompatible";
+    }
+    return Response.json({ status: "active", ...identity, recovery, hosty: { version: 1, setup, notice } }, { headers });
+}

package/dist/session-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Recovery classification of an app session, per the platform identity error contract:
+ * - `not-present`: no token at all (recoverable — same handling as `expired`).
+ * - `active`: token revalidated OK.
+ * - `expired`: Core 401 — recoverable; re-authorize via the Shell (embedded) or Core `/open`
+ *   (standalone).
+ * - `forbidden`: Core 403 or a token minted for a different app — terminal; never
+ *   auto-redirect (it would loop).
+ * - `unavailable`: Core unreachable, slow, or answering garbage — transient; keep the
+ *   cookie and offer a retry.
+ * - `misconfigured`: the app itself is broken (no service token / no Core origin) — an
+ *   operator problem; signing in cannot fix it, so never offer a login.
+ */
+export type AppSessionStatus = "not-present" | "active" | "expired" | "forbidden" | "unavailable" | "misconfigured";
+/** Failure statuses (everything but `active`). */
+export type AppSessionFailureStatus = Exclude<AppSessionStatus, "active">;
+export interface SessionRecoveryParams {
+    appId: string | null;
+    corePublicOrigin: string | null;
+    appAuthProtocol: 1 | 2 | null;
+}

package/dist/session-types.js

@@ -0,0 +1,15 @@
+// Shared session types with no DOM or framework dependency.
+/**
+ * Recovery classification of an app session, per the platform identity error contract:
+ * - `not-present`: no token at all (recoverable — same handling as `expired`).
+ * - `active`: token revalidated OK.
+ * - `expired`: Core 401 — recoverable; re-authorize via the Shell (embedded) or Core `/open`
+ *   (standalone).
+ * - `forbidden`: Core 403 or a token minted for a different app — terminal; never
+ *   auto-redirect (it would loop).
+ * - `unavailable`: Core unreachable, slow, or answering garbage — transient; keep the
+ *   cookie and offer a retry.
+ * - `misconfigured`: the app itself is broken (no service token / no Core origin) — an
+ *   operator problem; signing in cannot fix it, so never offer a login.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.21.2",
+  "version": "0.22.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"
     },
+    "./session/server": {
+      "types": "./dist/session-server.d.ts",
+      "default": "./dist/session-server.js"
+    },
     "./browser-auth": {
       "types": "./dist/browser-auth.d.ts",
       "default": "./dist/browser-auth.js"
@@ -92,7 +96,8 @@
   },
   "peerDependencies": {
     "next": "^16.3.8",
-    "react": "^19.2.8"
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -100,6 +105,9 @@
     },
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {