@hosty-sdk/app 0.21.2 → 0.23.0

package/dist/install.js

@@ -33,10 +33,12 @@ export function createInstallationClient(options = {}) {
 /** Reusable state flow for custom UIs, independent of React. Never automatically retries a mutation. */
 export class InstallationFlow {
     client;
-    state = { request: null, busy: false, error: null };
+    state = { request: null, busy: false, error: null, uncertainSubmit: false };
     listeners = new Set();
     generation = 0;
     disposed = false;
+    submitting = false;
+    refreshing = false;
     constructor(client) {
         this.client = client;
     }
@@ -50,72 +52,88 @@ export class InstallationFlow {
             listener();
     }
     clearReview() {
-        if (this.state.request && this.state.request.status !== "draft")
+        const status = this.state.request?.status;
+        if (this.submitting || this.state.uncertainSubmit || (status && !["draft", "succeeded", "denied", "failed"].includes(status)))
             return;
         this.generation++;
-        this.set({ request: null, busy: false, error: null });
+        this.set({ request: null, busy: false, error: null, uncertainSubmit: false });
     }
     cancelPending() { this.generation++; }
     dispose() { this.disposed = true; this.generation++; this.listeners.clear(); }
     async review(source) {
-        if (this.state.request && this.state.request.status !== "draft")
+        if (this.submitting || this.state.uncertainSubmit || (this.state.request && this.state.request.status !== "draft"))
             return;
         const generation = ++this.generation;
-        this.set({ request: null, busy: true, error: null });
+        this.set({ request: null, busy: true, error: null, uncertainSubmit: false });
         try {
             const request = await this.client.prepare(source);
             if (generation === this.generation)
-                this.set({ request, busy: false, error: null });
+                this.set({ request, busy: false, error: null, uncertainSubmit: false });
         }
         catch (error) {
             if (generation === this.generation)
-                this.set({ request: null, busy: false, error: message(error) });
+                this.set({ request: null, busy: false, error: message(error), uncertainSubmit: false });
         }
     }
     async submit(settings, autostart) {
-        if (this.state.busy || this.state.request?.status !== "draft")
+        if (this.state.busy || this.state.uncertainSubmit || this.state.request?.status !== "draft")
             return null;
         const id = this.state.request.id;
         const generation = this.generation;
+        this.submitting = true;
         this.set({ ...this.state, busy: true, error: null });
         try {
             const request = await this.client.submit(id, settings, autostart);
             if (generation !== this.generation)
                 return null;
-            this.set({ request, busy: false, error: null });
+            this.set({ request, busy: false, error: null, uncertainSubmit: false });
             return request;
         }
         catch (error) {
+            if (error instanceof InstallationError && error.status >= 400 && error.status < 500) {
+                if (generation === this.generation)
+                    this.set({ ...this.state, busy: false, error: message(error), uncertainSubmit: false });
+                return null;
+            }
             // A lost response may mean the request was already frozen. Recover by reading its status,
             // not by sending another submit or creating a second installation.
             try {
                 const request = await this.client.status(id);
                 if (generation !== this.generation)
                     return null;
-                this.set({ request, busy: false, error: request.status === "draft" ? message(error) : null });
+                this.set({ request, busy: false, error: request.status === "draft" ? message(error) : null, uncertainSubmit: false });
                 return request.status === "draft" ? null : request;
             }
             catch {
                 if (generation === this.generation)
-                    this.set({ ...this.state, busy: false, error: message(error) });
+                    this.set({ ...this.state, busy: false, error: message(error), uncertainSubmit: true });
                 return null;
             }
         }
+        finally {
+            this.submitting = false;
+        }
     }
     async refresh() {
-        if (!this.state.request || this.state.busy)
+        if (!this.state.request || this.state.busy || this.refreshing)
             return;
+        this.refreshing = true;
         const id = this.state.request.id;
         const generation = this.generation;
         try {
             const request = await this.client.status(id);
             if (generation === this.generation)
-                this.set({ request, busy: false, error: request.error ?? null });
+                this.set({ request, busy: false,
+                    error: request.error ?? (this.state.uncertainSubmit && request.status === "draft" ? "Core has not received the submission. Retry this request." : null),
+                    uncertainSubmit: false });
         }
         catch (error) {
             if (generation === this.generation)
                 this.set({ ...this.state, error: message(error) });
         }
+        finally {
+            this.refreshing = false;
+        }
     }
 }
 function message(error) { return error instanceof Error ? error.message : "Installation request failed."; }

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