@hosty-sdk/app 0.13.0 → 0.14.0

package/README.md

@@ -114,3 +114,69 @@ 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).
 
 License: AGPL-3.0-only.
+
+## Installing apps
+
+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.
+
+Mount an app-local handler using the existing Hosty identity-cookie configuration:
+
+```ts
+// app/api/hosty/installations/[[...path]]/route.ts
+import { createInstallationRouteHandler } from "@hosty-sdk/app/install/server";
+export const GET = createInstallationRouteHandler({
+  appIdFallback: "com.example.marketplace",
+  identityCookieName: "my_app_hosty_identity",
+}, {
+  publicOrigin: process.env.HOSTY_PUBLIC_ORIGIN_HTTP,
+});
+export const POST = GET;
+```
+
+Set `publicOrigin` to the Core-injected public origin for your UI endpoint when the framework
+exposes an internal request URL. The adapter checks browser `Origin` against this configured
+value, or against the request URL when it is omitted; forwarded-host headers are never trusted.
+
+The default dialog includes runtime selection, settings and a link to Core confirmation:
+
+```tsx
+"use client";
+import { createInstallationClient } from "@hosty-sdk/app/install";
+import { InstallDialog } from "@hosty-sdk/app/install/react";
+const client = createInstallationClient();
+
+// Render conditionally while open; unmount it when closed.
+<InstallDialog
+  client={client}
+  source={{ feedsUrl: "https://example.com/feeds.json", feedId: "stable" }}
+  onClose={() => setOpen(false)}
+  onInstalled={() => { setOpen(false); refreshInstalledApps(); }}
+/>;
+```
+
+For a custom UI, use `useInstallation(client)` or the framework-independent `InstallationFlow`.
+For direct API use, the same client provides the full request sequence:
+
+```ts
+const draft = await client.prepare({ manifestPath: "https://example.com/manifest.json" });
+// Render draft.plan and collect settings in your UI.
+const pending = await client.submit(draft.id, { APP_MODE: "standard" }, true);
+// Open pending.approvalUrl from a user gesture, or render it as a new-tab link.
+// Poll client.status(pending.id) until succeeded, denied or failed.
+```
+
+Open an empty confirmation window synchronously in the click handler with
+`openInstallationConfirmation()`, before awaiting `submit`, then navigate it using
+`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:
+`createInstallationClient({ baseUrl: coreOrigin + "/api/installations", request: sendCsrfJson })`.
+
+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.

package/dist/install-react.d.ts

@@ -0,0 +1,16 @@
+import { InstallationFlow, type InstallationClient, type InstallationRequest, type InstallationSource } from "./install.js";
+/** Custom dialogs can use this hook without adopting the default presentation. */
+export declare function useInstallation(client: InstallationClient): {
+    flow: InstallationFlow;
+    request: InstallationRequest | null;
+    busy: boolean;
+    error: string | null;
+};
+export interface InstallDialogProps {
+    client: InstallationClient;
+    source?: InstallationSource;
+    onClose: () => void;
+    onInstalled?: (request: InstallationRequest) => void;
+}
+/** Mount when opened; unmount on close. Styling is self-contained and has no Next/Tailwind dependency. */
+export declare function InstallDialog({ client, source, onClose, onInstalled }: InstallDialogProps): import("react").JSX.Element;

package/dist/install-react.js

@@ -0,0 +1,76 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { InstallationFlow, openInstallationConfirmation, showInstallationConfirmation, } from "./install.js";
+/** Custom dialogs can use this hook without adopting the default presentation. */
+export function useInstallation(client) {
+    const flow = useMemo(() => new InstallationFlow(client), [client]);
+    const state = useSyncExternalStore(flow.subscribe, flow.snapshot, flow.snapshot);
+    useEffect(() => () => flow.cancelPending(), [flow]);
+    useEffect(() => {
+        if (!state.request || !["pending", "executing"].includes(state.request.status))
+            return;
+        const timer = setInterval(() => void flow.refresh(), 1500);
+        return () => clearInterval(timer);
+    }, [flow, state.request?.id, state.request?.status]);
+    return { ...state, flow };
+}
+/** Mount when opened; unmount on close. Styling is self-contained and has no Next/Tailwind dependency. */
+export function InstallDialog({ client, source, onClose, onInstalled }) {
+    const { request, busy, error, flow } = useInstallation(client);
+    const dialog = useRef(null);
+    const titleId = useId();
+    const [manifestPath, setManifestPath] = useState(source?.manifestPath ?? "");
+    const [settings, setSettings] = useState({});
+    const [autostart, setAutostart] = useState(true);
+    const [draftPlanId, setDraftPlanId] = useState(null);
+    const notified = useRef(null);
+    const plan = request?.plan ?? null;
+    if (plan && request?.id !== draftPlanId) {
+        setDraftPlanId(request.id);
+        setSettings(Object.fromEntries(plan.settings.map(setting => [setting.key, setting.secret ? "" : setting.defaultValue ?? ""])));
+        setAutostart(plan.defaultAutostart ?? true);
+    }
+    const initialManifest = source?.manifestPath;
+    const initialFeed = source?.feedsUrl;
+    const initialFeedId = source?.feedId;
+    useEffect(() => {
+        if (initialManifest || initialFeed)
+            void flow.review({ manifestPath: initialManifest, feedsUrl: initialFeed, feedId: initialFeedId });
+    }, [flow, initialManifest, initialFeed, initialFeedId]);
+    useEffect(() => {
+        const element = dialog.current;
+        element?.showModal();
+        return () => element?.close();
+    }, []);
+    useEffect(() => {
+        if (request?.status === "succeeded" && notified.current !== request.id) {
+            notified.current = request.id;
+            onInstalled?.(request);
+        }
+    }, [request, onInstalled]);
+    const frozen = request !== null && request.status !== "draft";
+    const review = (runtime) => flow.review({
+        ...(source?.feedsUrl ? { feedsUrl: source.feedsUrl, feedId: source.feedId } : { manifestPath: manifestPath.trim() }),
+        selectedRuntime: runtime,
+    });
+    const submit = async () => {
+        const popup = openInstallationConfirmation();
+        const values = Object.fromEntries((plan?.settings ?? []).filter(setting => !setting.secret || settings[setting.key])
+            .map(setting => [setting.key, settings[setting.key] ?? ""]));
+        const submitted = await flow.submit(values, autostart);
+        if (submitted)
+            showInstallationConfirmation(popup, submitted);
+        else
+            popup?.close();
+    };
+    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. Only host administrators can open it." }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
+                                ? _jsx("input", { type: "checkbox", checked: ["true", "1", "yes", "on", "enabled"].includes((settings[setting.key] ?? "").toLowerCase()), disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: String(event.target.checked) })) })
+                                : setting.type === "select" && setting.options?.length && !setting.secret
+                                    ? _jsxs("select", { value: settings[setting.key] ?? "", disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })), children: [_jsx("option", { value: "", children: "Select a value" }), setting.options.map(option => _jsx("option", { value: option.value, children: option.label }, option.value))] })
+                                    : _jsx("input", { type: setting.secret ? "password" : setting.type === "number" ? "number" : setting.type === "url" ? "url" : "text", step: setting.type === "number" ? "any" : undefined, autoComplete: setting.secret ? "new-password" : "off", required: setting.required && !setting.secret, disabled: busy || frozen, value: settings[setting.key] ?? "", onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })) }), setting.description && _jsx("small", { children: setting.description })] }, setting.key)), _jsxs("label", { className: "check", children: [_jsx("input", { type: "checkbox", checked: autostart, disabled: busy || frozen, onChange: event => setAutostart(event.target.checked) }), " Start automatically (now and on Core startup)"] }), !frozen && _jsx("footer", { children: _jsx("button", { className: "primary", disabled: busy, children: "Continue to Core confirmation" }) })] }), frozen && _jsxs("section", { role: "status", children: [_jsx("p", { children: request.status === "pending" ? "Waiting for your confirmation in Hosty Core." : request.status === "executing" ? "Core is applying your confirmed request…" : request.status === "succeeded" ? "App installed." : request.status === "denied" ? "Installation cancelled." : "Installation failed. Close this dialog and review a new plan to retry." }), request.status === "pending" && _jsx("a", { href: request.approvalUrl, target: "_blank", rel: "noopener noreferrer", children: "Open Core confirmation" }), _jsx("p", { children: _jsx("small", { children: "Closing this dialog does not cancel an operation already confirmed in Core." }) })] })] });
+}
+const styles = `
+.hosty-install{box-sizing:border-box;width:min(640px,calc(100vw - 32px));max-height:calc(100dvh - 32px);padding:24px;border:1px solid var(--border,#aaa);border-radius:12px;background:var(--background,Canvas);color:var(--foreground,CanvasText);font:inherit;overflow:auto;margin:auto}
+.hosty-install::backdrop{background:#0008}.hosty-install header{display:flex;align-items:center;justify-content:space-between;gap:16px}.hosty-install h2{font-size:1.25rem;margin:0}.hosty-install h3{font-size:1rem;margin:20px 0 8px}.hosty-install p{margin:12px 0;font-size:.9rem}.hosty-install small{font-size:.8rem;opacity:.75}.hosty-install label{display:flex;flex-direction:column;gap:6px;margin:16px 0;font-size:.9rem}.hosty-install input:not([type=checkbox]),.hosty-install select{box-sizing:border-box;width:100%;border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 10px;background:transparent;color:inherit;font:inherit}.hosty-install .check{flex-direction:row;align-items:center;gap:10px}.hosty-install input[type=checkbox]{width:16px;height:16px;accent-color:#2563eb}.hosty-install button{border:1px solid var(--border,#aaa);border-radius:6px;padding:8px 12px;font:inherit;background:transparent;color:inherit;cursor:pointer}.hosty-install button:disabled{opacity:.5;cursor:default}.hosty-install .primary{background:#2563eb;color:white;border-color:#2563eb}.hosty-install footer{display:flex;justify-content:flex-end;margin-top:24px}.hosty-install .warning{padding:12px;border:1px solid #b7791f;border-radius:6px}.hosty-install [role=alert]{color:#d33}.hosty-install a{color:#2563eb;text-decoration:underline}.hosty-install :focus-visible{outline:2px solid #60a5fa;outline-offset:3px}
+`;

package/dist/install-server.d.ts

@@ -0,0 +1,6 @@
+import "server-only";
+import { type HostyAppConfig } from "./server.js";
+/** App-local adapter. Core revalidates the app/user on every call; service credentials stay server-side. */
+export declare function createInstallationRouteHandler(config: HostyAppConfig, options?: {
+    publicOrigin?: string | null;
+}): (request: Request) => Promise<Response>;

package/dist/install-server.js

@@ -0,0 +1,52 @@
+import "server-only";
+import { getAppId, getCoreOrigin, getServiceToken, readAppIdentityToken } from "./server.js";
+/** App-local adapter. Core revalidates the app/user on every call; service credentials stay server-side. */
+export function createInstallationRouteHandler(config, options = {}) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const match = /\/installations(?:\/([a-f0-9]{48})(\/submit)?)?$/.exec(url.pathname);
+        const valid = match && ((request.method === "POST" && (!match[1] || match[2])) || (request.method === "GET" && match[1] && !match[2]));
+        if (!valid)
+            return Response.json({ message: "Unsupported installation route." }, { status: 404 });
+        // Origin is browser-controlled; an installed hostile page cannot submit through the user's
+        // app cookie. Do not trust a caller-supplied forwarded host to decide which origins are allowed.
+        // Frameworks may expose an internal request URL behind a proxy or custom local hostname.
+        // An explicit operator-configured origin is authoritative in that case.
+        let expectedOrigin = url.origin;
+        if (options.publicOrigin?.trim()) {
+            try {
+                const configured = new URL(options.publicOrigin);
+                if (!["http:", "https:"].includes(configured.protocol))
+                    throw new Error("Invalid origin");
+                expectedOrigin = configured.origin;
+            }
+            catch {
+                return Response.json({ code: "hosty_misconfigured", message: "Installation public origin is invalid." }, { status: 503 });
+            }
+        }
+        if (request.method !== "GET" && (request.headers.get("origin") !== expectedOrigin ||
+            !request.headers.get("content-type")?.startsWith("application/json")))
+            return Response.json({ code: "origin_denied", message: "A same-origin JSON request is required." }, { status: 403 });
+        const token = readAppIdentityToken(request.headers, config);
+        if (!token)
+            return Response.json({ code: "app_identity_required", message: "Sign in through Hosty." }, { status: 401 });
+        const core = getCoreOrigin();
+        const service = getServiceToken();
+        if (!core || !service)
+            return Response.json({ code: "hosty_misconfigured", message: "Core integration is not configured." }, { status: 503 });
+        const suffix = match[1] ? `/${match[1]}${match[2] ?? ""}` : "";
+        try {
+            const body = request.method === "GET" ? undefined : await request.text();
+            if (body && body.length > 65536)
+                return Response.json({ message: "Request is too large." }, { status: 413 });
+            const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(getAppId(config))}/installations${suffix}`, core), {
+                method: request.method, redirect: "error", cache: "no-store", signal: request.signal,
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${service}`, "X-Hosty-App-Identity": token }, body,
+            });
+            return new Response(response.body, { status: response.status, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+        }
+        catch {
+            return Response.json({ code: "core_unavailable", message: "Core could not be reached. Check the request status before trying again." }, { status: 503 });
+        }
+    };
+}

package/dist/install.d.ts

@@ -0,0 +1,93 @@
+/** Framework-independent client for Core's reviewed, user-confirmed installation requests. */
+export interface InstallSetting {
+    key: string;
+    type: string;
+    defaultValue?: string | null;
+    secret: boolean;
+    required?: boolean;
+    label?: string | null;
+    description?: string | null;
+    options?: {
+        value: string;
+        label: string;
+    }[] | null;
+}
+export interface InstallPlan {
+    appId: string;
+    displayName: string;
+    description?: string | null;
+    action: string;
+    planId?: string | null;
+    targetVersion: string;
+    targetRuntime: string;
+    targetRuntimeType: string;
+    targetManifestDigest: string;
+    manifestPath: string;
+    defaultAutostart?: boolean;
+    system?: boolean;
+    corePermissions?: string[];
+    runtimeProfiles?: {
+        key: string;
+        type: string;
+        default: boolean;
+        development?: boolean;
+    }[];
+    settings: InstallSetting[];
+}
+export interface InstallationSource {
+    manifestPath?: string;
+    feedsUrl?: string;
+    feedId?: string;
+    selectedRuntime?: string;
+    updateAppId?: string;
+    planDigest?: string;
+}
+export interface InstallationRequest {
+    id: string;
+    status: "draft" | "pending" | "executing" | "succeeded" | "denied" | "failed";
+    plan: InstallPlan | null;
+    approvalUrl: string;
+    expiresAt: string;
+    error?: string | null;
+}
+export interface InstallationClient {
+    prepare(source: InstallationSource): Promise<InstallationRequest>;
+    submit(id: string, settings: Record<string, string | null>, autostart: boolean): Promise<InstallationRequest>;
+    status(id: string): Promise<InstallationRequest>;
+}
+export declare class InstallationError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare function createInstallationClient(options?: {
+    /** App-local server adapter by default; Shell may use Core's browser-session transport. */
+    baseUrl?: string;
+    request?: (url: string, body?: unknown, method?: string) => Promise<Response>;
+}): InstallationClient;
+export interface InstallationState {
+    request: InstallationRequest | null;
+    busy: boolean;
+    error: string | null;
+}
+/** Reusable state flow for custom UIs, independent of React. Never automatically retries a mutation. */
+export declare class InstallationFlow {
+    private readonly client;
+    private state;
+    private listeners;
+    private generation;
+    private disposed;
+    constructor(client: InstallationClient);
+    snapshot: () => InstallationState;
+    subscribe: (listener: () => void) => (() => void);
+    private set;
+    clearReview(): void;
+    cancelPending(): void;
+    dispose(): void;
+    review(source: InstallationSource): Promise<void>;
+    submit(settings: Record<string, string | null>, autostart: boolean): Promise<InstallationRequest | null>;
+    refresh(): Promise<void>;
+}
+/** Open synchronously in a click handler, before awaiting plan/submit requests. */
+export declare function openInstallationConfirmation(): Window | null;
+export declare function showInstallationConfirmation(popup: Window | null, request: InstallationRequest): void;

package/dist/install.js

@@ -0,0 +1,133 @@
+export class InstallationError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function createInstallationClient(options = {}) {
+    const base = (options.baseUrl ?? "/api/hosty/installations").replace(/\/$/, "");
+    const request = options.request ?? ((url, body, method = "POST") => fetch(url, {
+        method, credentials: "same-origin", cache: "no-store",
+        headers: { "Content-Type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    }));
+    async function call(path, body, method = "POST") {
+        const response = await request(`${base}${path}`, body, method);
+        const data = await response.json().catch(() => null);
+        if (!response.ok)
+            throw new InstallationError(data?.message ?? `Core returned ${response.status}.`, response.status, data?.code);
+        if (!data || typeof data.id !== "string" || typeof data.approvalUrl !== "string" || typeof data.status !== "string")
+            throw new InstallationError("Core returned an invalid installation request.", 502, "response_invalid");
+        return data;
+    }
+    return {
+        prepare: source => call("", source),
+        submit: (id, settings, autostart) => call(`/${encodeURIComponent(id)}/submit`, { settings, autostart }),
+        status: id => call(`/${encodeURIComponent(id)}`, undefined, "GET"),
+    };
+}
+/** 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 };
+    listeners = new Set();
+    generation = 0;
+    disposed = false;
+    constructor(client) {
+        this.client = client;
+    }
+    snapshot = () => this.state;
+    subscribe = (listener) => { this.listeners.add(listener); return () => this.listeners.delete(listener); };
+    set(state) {
+        if (this.disposed)
+            return;
+        this.state = state;
+        for (const listener of this.listeners)
+            listener();
+    }
+    clearReview() {
+        if (this.state.request && this.state.request.status !== "draft")
+            return;
+        this.generation++;
+        this.set({ request: null, busy: false, error: null });
+    }
+    cancelPending() { this.generation++; }
+    dispose() { this.disposed = true; this.generation++; this.listeners.clear(); }
+    async review(source) {
+        if (this.state.request && this.state.request.status !== "draft")
+            return;
+        const generation = ++this.generation;
+        this.set({ request: null, busy: true, error: null });
+        try {
+            const request = await this.client.prepare(source);
+            if (generation === this.generation)
+                this.set({ request, busy: false, error: null });
+        }
+        catch (error) {
+            if (generation === this.generation)
+                this.set({ request: null, busy: false, error: message(error) });
+        }
+    }
+    async submit(settings, autostart) {
+        if (this.state.busy || this.state.request?.status !== "draft")
+            return null;
+        const id = this.state.request.id;
+        const generation = this.generation;
+        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 });
+            return request;
+        }
+        catch (error) {
+            // 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 });
+                return request.status === "draft" ? null : request;
+            }
+            catch {
+                if (generation === this.generation)
+                    this.set({ ...this.state, busy: false, error: message(error) });
+                return null;
+            }
+        }
+    }
+    async refresh() {
+        if (!this.state.request || this.state.busy)
+            return;
+        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 });
+        }
+        catch (error) {
+            if (generation === this.generation)
+                this.set({ ...this.state, error: message(error) });
+        }
+    }
+}
+function message(error) { return error instanceof Error ? error.message : "Installation request failed."; }
+/** Open synchronously in a click handler, before awaiting plan/submit requests. */
+export function openInstallationConfirmation() {
+    return window.open("about:blank", "_blank", "popup,width=640,height=720");
+}
+export function showInstallationConfirmation(popup, request) {
+    const url = new URL(request.approvalUrl);
+    if (!["http:", "https:"].includes(url.protocol))
+        throw new Error("Invalid Core confirmation URL.");
+    if (popup && !popup.closed) {
+        popup.opener = null;
+        popup.location.replace(url.href);
+    }
+}

package/dist/react.d.ts

@@ -56,7 +56,7 @@ 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, }?: 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 AppIdentityBridge({ probePath, appCodePath, renderState, }?: AppIdentityBridgeProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 export interface HostThemeBridgeProps {
     /**
      * Whether the operating system decides the theme while no shell has spoken — `true` unless the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -36,6 +36,18 @@
     "./theme": {
       "types": "./dist/theme.d.ts",
       "default": "./dist/theme.js"
+    },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "default": "./dist/install.js"
+    },
+    "./install/react": {
+      "types": "./dist/install-react.d.ts",
+      "default": "./dist/install-react.js"
+    },
+    "./install/server": {
+      "types": "./dist/install-server.d.ts",
+      "default": "./dist/install-server.js"
     }
   },
   "scripts": {
@@ -58,8 +70,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24",
-    "@types/react": "^19.2.18",
+    "@types/node": "^24.13.4",
+    "@types/react": "^19.3.0",
     "typescript": "^6",
     "vitest": "^5.0.0"
   },