@hosty-sdk/app 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @hosty-sdk/app
+
+Auth and host integration for [Hosty](https://github.com/alex-de-haas/docker-host) runtime
+apps: the app-session state machine, silent session recovery, Core revalidation, and the
+embedder responder for shells.
+
+```
+npm install @hosty-sdk/app
+```
+
+| Entry | Runtime | Contents |
+| --- | --- | --- |
+| `@hosty-sdk/app` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` schema, URL/env helpers |
+| `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory |
+| `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, silent recovery, fallback cards |
+| `@hosty-sdk/app/embedder` | client | verified `hosty:auth-required` responder for anything that embeds Hosty apps |
+
+Minimal Next.js wiring:
+
+```tsx
+// app/layout.tsx
+import { AppIdentityBridge } from "@hosty-sdk/app/react";
+// mount <AppIdentityBridge /> at the top of <body>
+
+// app/api/auth/app-code/route.ts
+import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+export const POST = createAppCodeRouteHandler({
+  appIdFallback: "com.example.my-app",
+  identityCookieName: "my_app_hosty_identity",
+});
+```
+
+The design contract lives in the Hosty repository:
+[`docs/ideas/hosty-app-sdk.md`](https://github.com/alex-de-haas/docker-host/blob/main/docs/ideas/hosty-app-sdk.md).
+
+License: AGPL-3.0-only.

package/dist/embedder.d.ts

@@ -0,0 +1,24 @@
+export interface AuthRequiredMessage {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}
+/**
+ * Verifies that a `message` event is a genuine auth-required intent from the active app
+ * frame. Every check is about facts only the embedder can know:
+ * - `event.source` must be the active iframe's `contentWindow` (not some other frame);
+ * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
+ * - the payload's `appId` must match the app the embedder actually mounted there.
+ * No credential crosses the boundary in either direction: the payload is only the app id,
+ * and the embedder answers by reissuing a code through its own authenticated Core call.
+ */
+export declare function parseActiveFrameAuthRequired(event: AuthRequiredMessage, activeFrameWindow: unknown, activeFrameUrl: string, expectedAppId: string): boolean;
+/**
+ * Per-app reissue throttle: a frame that keeps re-posting (e.g. it never accepts the new
+ * code) must not drive an unbounded reissue storm. One reissue per app per interval is
+ * plenty for recovery — Hosty Shell ships 3000ms.
+ */
+export declare function createReissueRateLimiter(minIntervalMs: number, now?: () => number): {
+    /** True when a reissue for this app is allowed now; records the attempt when allowed. */
+    tryAcquire(appId: string): boolean;
+};

package/dist/embedder.js

@@ -0,0 +1,58 @@
+// Embedder slice: the shell half of the recovery contract, for anything that embeds Hosty
+// apps in iframes (Hosty Shell or a third-party UI client). Pure functions plus a small
+// rate limiter — the embedder wires them to its own DOM and its own "open this app" flow.
+//
+// The contract in one sentence: on a VERIFIED `hosty:auth-required` from an app you embed,
+// re-run your normal open flow for that app (which mints a fresh launch code), rate-limited.
+// The re-open must take the full launch-code path — an "already open → reuse the URL
+// without a code" optimization must not short-circuit recovery.
+import { AUTH_REQUIRED_INTENT_TYPE } from "./index";
+/**
+ * Verifies that a `message` event is a genuine auth-required intent from the active app
+ * frame. Every check is about facts only the embedder can know:
+ * - `event.source` must be the active iframe's `contentWindow` (not some other frame);
+ * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
+ * - the payload's `appId` must match the app the embedder actually mounted there.
+ * No credential crosses the boundary in either direction: the payload is only the app id,
+ * and the embedder answers by reissuing a code through its own authenticated Core call.
+ */
+export function parseActiveFrameAuthRequired(event, activeFrameWindow, activeFrameUrl, expectedAppId) {
+    if (!activeFrameWindow || event.source !== activeFrameWindow) {
+        return false;
+    }
+    try {
+        if (event.origin !== new URL(activeFrameUrl).origin) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    if (!event.data || typeof event.data !== "object" || Array.isArray(event.data)) {
+        return false;
+    }
+    const candidate = event.data;
+    return (candidate.type === AUTH_REQUIRED_INTENT_TYPE &&
+        typeof candidate.appId === "string" &&
+        candidate.appId === expectedAppId);
+}
+/**
+ * Per-app reissue throttle: a frame that keeps re-posting (e.g. it never accepts the new
+ * code) must not drive an unbounded reissue storm. One reissue per app per interval is
+ * plenty for recovery — Hosty Shell ships 3000ms.
+ */
+export function createReissueRateLimiter(minIntervalMs, now = Date.now) {
+    const lastReissueAt = new Map();
+    return {
+        /** True when a reissue for this app is allowed now; records the attempt when allowed. */
+        tryAcquire(appId) {
+            const at = now();
+            const last = lastReissueAt.get(appId);
+            if (last !== undefined && at - last < minIntervalMs) {
+                return false;
+            }
+            lastReissueAt.set(appId, at);
+            return true;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The postMessage type an embedded app sends its parent to request a fresh launch code.
+ * A frozen protocol constant: it deliberately does not track product branding (precedent:
+ * the `x-docker-host-identity` header survived the docker-host→hosty rename untouched).
+ * The payload carries no secret — the embedder verifies the sender before acting.
+ */
+export declare const AUTH_REQUIRED_INTENT_TYPE = "hosty:auth-required";
+export interface AuthRequiredIntent {
+    type: typeof AUTH_REQUIRED_INTENT_TYPE;
+    appId: string;
+}
+export declare function createAuthRequiredIntent(appId: string): AuthRequiredIntent;
+/**
+ * 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
+ * app; `MapIdentityErrorStatus` in Core is the normative table behind these numbers.
+ */
+export declare function classifyRevalidationHttpStatus(status: number): AppSessionFailureStatus;
+/**
+ * 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 interface SessionRecoveryParams {
+    appId: string | null;
+    corePublicOrigin: string | 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;
+export interface PageLocation {
+    origin: string;
+    pathname: string;
+    search: string;
+    hostname: string;
+}
+/**
+ * Builds the Core standalone re-auth URL (`/api/apps/{id}/open?redirectUri=…`) for the
+ * current page, or null when the redirect is known to be impossible:
+ * - no Core public origin at all, or an unparsable one;
+ * - Core's origin is loopback while this page is not — an unset public origin falls back
+ *   to Core's loopback listen URL, which only a same-machine browser can follow, and Core
+ *   would reject the foreign redirect URI anyway (`redirect_uri_denied`).
+ * The fragment is deliberately dropped: Core rejects redirect URIs carrying one
+ * (`redirect_uri_invalid`), and it would not survive the server redirect anyway.
+ */
+export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId: string, location: PageLocation): string | null;
+/** Launch mode drives the logout affordance: embedded apps hide logout entirely (the
+ * session belongs to the Shell), standalone apps may show one. `window.self !== window.top`
+ * is the baseline signal; a Core-reported launch channel can replace it later without
+ * changing callers. */
+export type AppLaunchMode = "embedded" | "standalone";
+export declare function detectLaunchMode(win: Pick<Window, "self" | "top">): AppLaunchMode;
+/**
+ * The recovery decision: state × launch mode → what the app should do, per the UX
+ * contract (Core `/login` is the only auth UI in the system; apps render no login UI and
+ * no errors while recovery runs).
+ */
+export type RecoveryAction = {
+    kind: "none";
+} | {
+    kind: "post-auth-required";
+    intent: AuthRequiredIntent;
+} | {
+    kind: "redirect";
+    openUrl: string;
+} | {
+    kind: "card";
+    card: "signin" | "denied" | "unavailable" | "misconfigured";
+};
+export declare function decideRecoveryAction(input: {
+    status: AppSessionStatus;
+    mode: AppLaunchMode;
+    appId: string;
+    openUrl: string | null;
+    redirectAlreadyAttempted: boolean;
+}): RecoveryAction;

package/dist/index.js

@@ -0,0 +1,107 @@
+// Core slice: pure TypeScript, safe in any runtime (browser, Node, edge, solitaire's
+// server.mjs). No React, no Next, no environment reads — everything is passed in.
+//
+// This is the single source of truth for the Hosty app-session contract described in
+// docker-host docs/ideas/hosty-app-sdk.md and docs/ideas/auth-session-lifecycle.md.
+/**
+ * The postMessage type an embedded app sends its parent to request a fresh launch code.
+ * A frozen protocol constant: it deliberately does not track product branding (precedent:
+ * the `x-docker-host-identity` header survived the docker-host→hosty rename untouched).
+ * The payload carries no secret — the embedder verifies the sender before acting.
+ */
+export const AUTH_REQUIRED_INTENT_TYPE = "hosty:auth-required";
+export function createAuthRequiredIntent(appId) {
+    return { type: AUTH_REQUIRED_INTENT_TYPE, appId };
+}
+/**
+ * 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
+ * app; `MapIdentityErrorStatus` in Core is the normative table behind these numbers.
+ */
+export function classifyRevalidationHttpStatus(status) {
+    if (status === 401) {
+        return "expired";
+    }
+    if (status === 403) {
+        return "forbidden";
+    }
+    return "unavailable";
+}
+export function readRecoveryParams(body) {
+    const recovery = body && typeof body === "object" ? body.recovery : null;
+    if (!recovery || typeof recovery !== "object") {
+        return { appId: null, corePublicOrigin: null };
+    }
+    const { appId, corePublicOrigin } = recovery;
+    return {
+        appId: typeof appId === "string" && appId.length > 0 ? appId : null,
+        corePublicOrigin: typeof corePublicOrigin === "string" && corePublicOrigin.length > 0
+            ? corePublicOrigin
+            : null,
+    };
+}
+/** True for hosts that only resolve on the machine itself. */
+export function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+/**
+ * Builds the Core standalone re-auth URL (`/api/apps/{id}/open?redirectUri=…`) for the
+ * current page, or null when the redirect is known to be impossible:
+ * - no Core public origin at all, or an unparsable one;
+ * - Core's origin is loopback while this page is not — an unset public origin falls back
+ *   to Core's loopback listen URL, which only a same-machine browser can follow, and Core
+ *   would reject the foreign redirect URI anyway (`redirect_uri_denied`).
+ * The fragment is deliberately dropped: Core rejects redirect URIs carrying one
+ * (`redirect_uri_invalid`), and it would not survive the server redirect anyway.
+ */
+export function buildCoreOpenUrl(corePublicOrigin, appId, location) {
+    if (!corePublicOrigin) {
+        return null;
+    }
+    let target;
+    try {
+        target = new URL(`/api/apps/${encodeURIComponent(appId)}/open`, corePublicOrigin);
+    }
+    catch {
+        return null;
+    }
+    if (isLoopbackHost(target.hostname) && !isLoopbackHost(location.hostname)) {
+        return null;
+    }
+    target.searchParams.set("redirectUri", `${location.origin}${location.pathname}${location.search}`);
+    return target.toString();
+}
+export function detectLaunchMode(win) {
+    try {
+        return win.self !== win.top ? "embedded" : "standalone";
+    }
+    catch {
+        // A cross-origin `top` access can throw in exotic embeddings; being framed is the only
+        // way that happens, so classify it as embedded.
+        return "embedded";
+    }
+}
+export function decideRecoveryAction(input) {
+    const { status, mode, appId, openUrl, redirectAlreadyAttempted } = input;
+    if (status === "active") {
+        return { kind: "none" };
+    }
+    if (status === "forbidden") {
+        return { kind: "card", card: "denied" };
+    }
+    if (status === "unavailable") {
+        return { kind: "card", card: "unavailable" };
+    }
+    if (status === "misconfigured") {
+        return { kind: "card", card: "misconfigured" };
+    }
+    // expired / not-present — the recoverable pair.
+    if (mode === "embedded") {
+        return { kind: "post-auth-required", intent: createAuthRequiredIntent(appId) };
+    }
+    if (openUrl && !redirectAlreadyAttempted) {
+        return { kind: "redirect", openUrl };
+    }
+    return { kind: "card", card: "signin" };
+}

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+import { type AppSessionStatus } from "./index";
+/**
+ * Tolerant probe reader: accepts both identity-route shapes in the fleet — a top-level
+ * `status` (marketplace/telemetry) and a nested `appSession.status` (demo-app,
+ * project-manager). The legacy `error` status maps to `unavailable` (transient).
+ */
+export declare function readProbedSessionStatus(body: unknown): AppSessionStatus | null;
+export interface AppIdentityBridgeProps {
+    /** Probe endpoint returning a session status + recovery params. */
+    probePath?: string;
+    /** Code-exchange endpoint. */
+    appCodePath?: string;
+}
+/**
+ * Mount once at the top of the root layout body. On first load it consumes a `?code` from
+ * the URL (exchanging it for the identity cookie), then probes the session and runs the
+ * recovery decision: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * 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, }?: AppIdentityBridgeProps): import("react").JSX.Element | null;

package/dist/react.js

@@ -0,0 +1,226 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// React slice: the client identity bridge — probe, silent recovery, and the fallback
+// cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
+// probe response's `recovery` field (request-time values, never build-time props).
+import { useEffect, useState } from "react";
+import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, readRecoveryParams, } from "./index";
+// Once-per-tab guard so a standalone app that returns from Core still unauthorized does
+// not bounce through /open forever. Cleared on a successful code exchange.
+const RECOVERY_GUARD_KEY = "hosty.auth.recovery-attempted";
+// How long an embedded frame waits for the Shell to reissue a launch code before showing
+// the manual sign-in fallback (i.e. it is embedded by something other than Hosty Shell).
+const EMBEDDED_RECOVERY_TIMEOUT_MS = 4_000;
+// Cap the status probe so a stalled request cannot leave the bridge stuck hidden — on
+// timeout it classifies as unavailable and the user gets a Retry affordance.
+const IDENTITY_PROBE_TIMEOUT_MS = 4_000;
+const KNOWN_STATUSES = [
+    "not-present",
+    "active",
+    "expired",
+    "forbidden",
+    "unavailable",
+    "misconfigured",
+];
+/**
+ * Tolerant probe reader: accepts both identity-route shapes in the fleet — a top-level
+ * `status` (marketplace/telemetry) and a nested `appSession.status` (demo-app,
+ * project-manager). The legacy `error` status maps to `unavailable` (transient).
+ */
+export function readProbedSessionStatus(body) {
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    const record = body;
+    const nested = record.appSession && typeof record.appSession === "object"
+        ? record.appSession.status
+        : undefined;
+    const raw = typeof record.status === "string" ? record.status : nested;
+    if (typeof raw !== "string") {
+        return null;
+    }
+    if (raw === "error") {
+        return "unavailable";
+    }
+    return KNOWN_STATUSES.includes(raw) ? raw : null;
+}
+function readGuard() {
+    try {
+        return window.sessionStorage.getItem(RECOVERY_GUARD_KEY) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+function writeGuard(value) {
+    try {
+        if (value) {
+            window.sessionStorage.setItem(RECOVERY_GUARD_KEY, "1");
+        }
+        else {
+            window.sessionStorage.removeItem(RECOVERY_GUARD_KEY);
+        }
+    }
+    catch {
+        // sessionStorage may be blocked; recovery still works, only the guard is lost.
+    }
+}
+/**
+ * Mount once at the top of the root layout body. On first load it consumes a `?code` from
+ * the URL (exchanging it for the identity cookie), then probes the session and runs the
+ * recovery decision: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * 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", } = {}) {
+    const [ui, setUi] = useState({ kind: "hidden" });
+    useEffect(() => {
+        let cancelled = false;
+        const controller = new AbortController();
+        async function probeAndRecover() {
+            // 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.
+            const probeController = new AbortController();
+            const abortProbe = () => probeController.abort();
+            controller.signal.addEventListener("abort", abortProbe, { once: true });
+            const probeTimeout = window.setTimeout(abortProbe, IDENTITY_PROBE_TIMEOUT_MS);
+            let status = null;
+            let openUrl = null;
+            let appId = null;
+            try {
+                const response = await fetch(probePath, {
+                    headers: { Accept: "application/json" },
+                    cache: "no-store",
+                    signal: probeController.signal,
+                });
+                const body = await response.json().catch(() => null);
+                status = readProbedSessionStatus(body);
+                const recovery = readRecoveryParams(body);
+                appId = recovery.appId;
+                openUrl = appId ? buildCoreOpenUrl(recovery.corePublicOrigin, appId, window.location) : null;
+            }
+            catch {
+                // A failed or timed-out probe (Core unreachable) classifies as unavailable below.
+                status = null;
+            }
+            finally {
+                window.clearTimeout(probeTimeout);
+                controller.signal.removeEventListener("abort", abortProbe);
+            }
+            if (cancelled) {
+                return;
+            }
+            const action = !status || !appId
+                ? { kind: "card", card: "unavailable" }
+                : decideRecoveryAction({
+                    status,
+                    mode: detectLaunchMode(window),
+                    appId,
+                    openUrl,
+                    redirectAlreadyAttempted: readGuard(),
+                });
+            switch (action.kind) {
+                case "none":
+                    setUi({ kind: "hidden" });
+                    return;
+                case "post-auth-required": {
+                    // The payload carries no secret, so targetOrigin "*" is safe — the Shell verifies
+                    // the sender before acting, and answers by swapping the iframe src.
+                    try {
+                        window.parent.postMessage(action.intent, "*");
+                    }
+                    catch {
+                        // Ignore; the timeout below still falls back to the manual sign-in card.
+                    }
+                    const timeoutId = window.setTimeout(() => {
+                        if (!cancelled) {
+                            setUi({ kind: "signin", openUrl, embedded: true });
+                        }
+                    }, EMBEDDED_RECOVERY_TIMEOUT_MS);
+                    controller.signal.addEventListener("abort", () => window.clearTimeout(timeoutId), {
+                        once: true,
+                    });
+                    return;
+                }
+                case "redirect":
+                    writeGuard(true);
+                    window.location.assign(action.openUrl);
+                    return;
+                case "card":
+                    setUi(action.card === "signin"
+                        ? { kind: "signin", openUrl, embedded: false }
+                        : { kind: action.card });
+                    return;
+            }
+        }
+        const url = new URL(window.location.href);
+        const code = url.searchParams.get("code")?.trim();
+        if (code) {
+            url.searchParams.delete("code");
+            window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+            void fetch(appCodePath, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ code }),
+                signal: controller.signal,
+            })
+                .then((response) => {
+                if (cancelled) {
+                    return;
+                }
+                if (response.ok) {
+                    writeGuard(false);
+                    window.location.reload();
+                }
+                else {
+                    void probeAndRecover();
+                }
+            })
+                .catch(() => {
+                if (!cancelled) {
+                    void probeAndRecover();
+                }
+            });
+        }
+        else {
+            void probeAndRecover();
+        }
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [probePath, appCodePath]);
+    if (ui.kind === "hidden") {
+        return null;
+    }
+    return (_jsx("div", { role: "status", style: barStyle, children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: "Your Hosty session ended." }), ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: actionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), style: actionStyle, children: "Retry" })] })) }));
+}
+const barStyle = {
+    position: "fixed",
+    insetInline: 0,
+    bottom: 0,
+    zIndex: 2147483647,
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "0.75rem",
+    padding: "0.75rem 1rem",
+    background: "#111827",
+    color: "#f9fafb",
+    font: "500 0.875rem/1.4 system-ui, sans-serif",
+    boxShadow: "0 -1px 0 rgba(255,255,255,0.08)",
+};
+const actionStyle = {
+    display: "inline-block",
+    padding: "0.4rem 0.85rem",
+    borderRadius: "0.5rem",
+    background: "#f9fafb",
+    color: "#111827",
+    border: "none",
+    cursor: "pointer",
+    font: "inherit",
+    fontWeight: 650,
+    textDecoration: "none",
+};

package/dist/server.d.ts

@@ -0,0 +1,98 @@
+import "server-only";
+import { type AppSessionFailureStatus, type AppSessionStatus, type SessionRecoveryParams } from "./index";
+/** Per-app parameters: everything that legitimately diverges between apps stays a
+ * parameter — cookie namespaces and role models are per-app by decision, never unified. */
+export interface HostyAppConfig {
+    /** Stable app id fallback for when HOSTY_APP_ID is not injected (mirrors the manifest). */
+    appIdFallback: string;
+    /** This app's identity cookie name (e.g. "hosty_marketplace_identity"). */
+    identityCookieName: string;
+    /** Optional host-role → app-role mapping hook; the raw role passes through when absent. */
+    mapHostRole?: (hostRole: string | null) => string | null;
+}
+/** The inbound trusted-identity header the platform has always used (a frozen protocol
+ * constant that survived the docker-host→hosty rename). */
+export declare const HOSTY_APP_IDENTITY_HEADER = "x-docker-host-identity";
+export interface HostIdentity {
+    userId: string;
+    email: string | null;
+    displayName: string | null;
+    hostRole: string | null;
+    /** `mapHostRole(hostRole)` when the config provides the hook, else the raw host role. */
+    appRole: string | null;
+    expiresAt: string | null;
+}
+export type AppSessionResolution = {
+    status: "active";
+    identity: HostIdentity;
+} | {
+    status: AppSessionFailureStatus;
+};
+export declare function getAppId(config: HostyAppConfig): string;
+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. */
+export declare function getCorePublicOrigin(): string | null;
+export declare function getServiceToken(): string | null;
+export declare function getRecoveryParams(config: HostyAppConfig): SessionRecoveryParams;
+export type HeaderReader = {
+    get(name: string): string | null;
+};
+/**
+ * Reads the app identity token from a request: the app-origin cookie first (authoritative
+ * when present), then the Authorization bearer fallback the browser sends when the
+ * cross-site cookie is blocked, then the legacy inbound identity header.
+ */
+export declare function readAppIdentityToken(headers: HeaderReader, config: HostyAppConfig): string | null;
+/** True when the effective request protocol is https (honouring the forwarded proto). */
+export declare function isSecureRequest(headers: HeaderReader, requestProtocol?: string): boolean;
+export interface IdentityCookieAttributes {
+    httpOnly: true;
+    secure: boolean;
+    sameSite: "none" | "lax";
+    path: "/";
+    maxAge: number;
+}
+/**
+ * Cookie attributes for the app-origin identity cookie. Cross-site Shell iframes need
+ * `SameSite=None; Secure` over https; plain http (local dev) cannot use `Secure` and
+ * falls back to `SameSite=Lax`. `maxAge` follows the grant's absolute lifetime.
+ */
+export declare function identityCookieAttributes(secure: boolean, maxAgeSeconds: number): IdentityCookieAttributes;
+/** Test hook: the cache is process-global by design (route handlers are stateless). */
+export declare function clearRevalidationCache(): void;
+/**
+ * Revalidates an app identity token against Core with the app service token and
+ * classifies the outcome. Core identity tokens are opaque (`hostyg_` grants), so this
+ * round-trip is the only trustworthy validation; policy (disabled / unassigned / role
+ * downgrade) is re-checked online by Core on every call, which is why caching stays short.
+ */
+export declare function resolveAppSession(token: string | null, config: HostyAppConfig): Promise<AppSessionResolution>;
+/**
+ * Cookie-only probe classification for the client recovery bridge. Deliberately ignores
+ * bearer/header tokens: probe routes are public, and honoring caller-supplied tokens would
+ * turn them into an unauthenticated oracle that revalidates attacker-chosen tokens against
+ * Core. The recovery contract only ever concerns *this browser's* session, which lives in
+ * the HttpOnly app cookie.
+ */
+export declare function classifyAppSessionFromCookie(headers: HeaderReader, config: HostyAppConfig): Promise<AppSessionStatus>;
+export type AppCodeExchange = {
+    ok: true;
+    accessToken: string;
+    expiresInSeconds: number | null;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/** Exchanges a one-time Shell/Core launch code for an identity token at Core. The code is
+ * the only credential — the endpoint is deliberately unauthenticated on Core's side. */
+export declare function exchangeAppCode(code: string): Promise<AppCodeExchange>;
+/**
+ * Route-handler factory for `POST /api/auth/app-code`: exchanges the one-time `code` for
+ * an identity token, stores it in the app-origin HttpOnly cookie, and returns the token so
+ * the browser can keep a bearer fallback for when the cross-site cookie is blocked.
+ * Framework-agnostic (Web `Request`/`Response`), usable directly as a Next route handler.
+ */
+export declare function createAppCodeRouteHandler(config: HostyAppConfig): (request: Request) => Promise<Response>;

package/dist/server.js

@@ -0,0 +1,334 @@
+// Server slice: Next route-handler factories and Core revalidation. Never reaches a client
+// bundle — the service token lives here.
+import "server-only";
+import { classifyRevalidationHttpStatus, } from "./index";
+// Core runs on the same host as the app services, so a short budget is plenty; a stalled
+// call must not hold a route open indefinitely.
+const CORE_AUTH_TIMEOUT_MS = 1_500;
+// Decision 9 (hosty-app-sdk.md): positive revalidations may be cached for 30s, clamped to
+// the grant's expiry; negative results are never cached, so a stuck-unauthenticated state
+// is impossible. Bounded so an attacker spraying tokens cannot grow the map unboundedly.
+const REVALIDATION_CACHE_TTL_MS = 30_000;
+const MAX_REVALIDATION_CACHE_ENTRIES = 256;
+/** The inbound trusted-identity header the platform has always used (a frozen protocol
+ * constant that survived the docker-host→hosty rename). */
+export const HOSTY_APP_IDENTITY_HEADER = "x-docker-host-identity";
+export function getAppId(config) {
+    return process.env.HOSTY_APP_ID?.trim() || config.appIdFallback;
+}
+export function getCoreOrigin() {
+    return process.env.HOSTY_CORE_ORIGIN?.trim() || 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. */
+export function getCorePublicOrigin() {
+    return process.env.HOSTY_CORE_PUBLIC_ORIGIN?.trim() || null;
+}
+export function getServiceToken() {
+    return process.env.HOSTY_APP_SERVICE_TOKEN?.trim() || null;
+}
+export function getRecoveryParams(config) {
+    return { appId: getAppId(config), corePublicOrigin: getCorePublicOrigin() };
+}
+/**
+ * Reads the app identity token from a request: the app-origin cookie first (authoritative
+ * when present), then the Authorization bearer fallback the browser sends when the
+ * cross-site cookie is blocked, then the legacy inbound identity header.
+ */
+export function readAppIdentityToken(headers, config) {
+    const cookieToken = readCookie(headers.get("cookie"), config.identityCookieName);
+    if (cookieToken) {
+        return cookieToken;
+    }
+    const authorization = headers.get("authorization")?.trim();
+    if (authorization?.toLowerCase().startsWith("bearer ")) {
+        const token = authorization.slice("bearer ".length).trim();
+        if (token) {
+            return token;
+        }
+    }
+    return headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
+}
+/** True when the effective request protocol is https (honouring the forwarded proto). */
+export function isSecureRequest(headers, requestProtocol) {
+    const forwarded = headers.get("x-forwarded-proto");
+    if (forwarded) {
+        return forwarded.split(",")[0].trim().toLowerCase() === "https";
+    }
+    return requestProtocol === "https:";
+}
+/**
+ * Cookie attributes for the app-origin identity cookie. Cross-site Shell iframes need
+ * `SameSite=None; Secure` over https; plain http (local dev) cannot use `Secure` and
+ * falls back to `SameSite=Lax`. `maxAge` follows the grant's absolute lifetime.
+ */
+export function identityCookieAttributes(secure, maxAgeSeconds) {
+    return {
+        httpOnly: true,
+        secure,
+        sameSite: secure ? "none" : "lax",
+        path: "/",
+        maxAge: Math.max(0, Math.floor(maxAgeSeconds)),
+    };
+}
+const revalidationCache = new Map();
+const pendingRevalidations = new Map();
+/** Test hook: the cache is process-global by design (route handlers are stateless). */
+export function clearRevalidationCache() {
+    revalidationCache.clear();
+    pendingRevalidations.clear();
+}
+/**
+ * Revalidates an app identity token against Core with the app service token and
+ * classifies the outcome. Core identity tokens are opaque (`hostyg_` grants), so this
+ * round-trip is the only trustworthy validation; policy (disabled / unassigned / role
+ * downgrade) is re-checked online by Core on every call, which is why caching stays short.
+ */
+export async function resolveAppSession(token, config) {
+    if (!token) {
+        return { status: "not-present" };
+    }
+    const serviceToken = getServiceToken();
+    const coreOrigin = getCoreOrigin();
+    if (!serviceToken || !coreOrigin) {
+        return { status: "misconfigured" };
+    }
+    const now = Date.now();
+    const cached = revalidationCache.get(token);
+    if (cached) {
+        if (now - cached.cachedAt < REVALIDATION_CACHE_TTL_MS && now < cached.expiresAtMs) {
+            return { status: "active", identity: cached.identity };
+        }
+        revalidationCache.delete(token);
+    }
+    const pending = pendingRevalidations.get(token);
+    if (pending) {
+        return pending;
+    }
+    const revalidation = revalidateWithCore(token, coreOrigin, serviceToken, config);
+    pendingRevalidations.set(token, revalidation);
+    try {
+        return await revalidation;
+    }
+    finally {
+        pendingRevalidations.delete(token);
+    }
+}
+async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
+    let endpoint;
+    try {
+        endpoint = new URL("/api/auth/apps/revalidate", coreOrigin).toString();
+    }
+    catch {
+        return { status: "misconfigured" };
+    }
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${serviceToken}`,
+            },
+            body: JSON.stringify({ accessToken: token }),
+            cache: "no-store",
+            signal: AbortSignal.timeout(CORE_AUTH_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Network failure or timeout — transient either way; never cached.
+        return { status: "unavailable" };
+    }
+    if (!response.ok) {
+        return { status: classifyRevalidationHttpStatus(response.status) };
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        // A non-JSON / truncated body means the session is unverifiable, not proof it is invalid.
+        return { status: "unavailable" };
+    }
+    const appId = readString(payload?.appId);
+    if (appId && appId !== getAppId(config)) {
+        // A token minted for a different app is Core's token_app_mismatch — terminal, like 403.
+        return { status: "forbidden" };
+    }
+    const userId = readString(payload?.userId);
+    // An "active" grant without a subject is unusable; classify it as recoverable so a probe
+    // and the real auth path can never disagree about the same token.
+    if (!payload || payload.active !== true || !userId) {
+        return { status: "expired" };
+    }
+    const hostRole = readString(payload.hostRole);
+    const expiresAt = readString(payload.expiresAt);
+    const identity = {
+        userId,
+        email: readString(payload.email),
+        displayName: readString(payload.displayName),
+        hostRole,
+        appRole: config.mapHostRole ? config.mapHostRole(hostRole) : hostRole,
+        expiresAt,
+    };
+    const expiresAtMs = expiresAt ? Date.parse(expiresAt) : Number.NaN;
+    if (Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {
+        pruneRevalidationCache();
+        revalidationCache.set(token, { identity, expiresAtMs, cachedAt: Date.now() });
+    }
+    return { status: "active", identity };
+}
+function pruneRevalidationCache() {
+    if (revalidationCache.size < MAX_REVALIDATION_CACHE_ENTRIES) {
+        return;
+    }
+    const now = Date.now();
+    for (const [token, entry] of revalidationCache) {
+        if (now - entry.cachedAt >= REVALIDATION_CACHE_TTL_MS || now >= entry.expiresAtMs) {
+            revalidationCache.delete(token);
+        }
+    }
+    while (revalidationCache.size >= MAX_REVALIDATION_CACHE_ENTRIES) {
+        const oldest = revalidationCache.keys().next().value;
+        if (oldest === undefined) {
+            return;
+        }
+        revalidationCache.delete(oldest);
+    }
+}
+/**
+ * Cookie-only probe classification for the client recovery bridge. Deliberately ignores
+ * bearer/header tokens: probe routes are public, and honoring caller-supplied tokens would
+ * turn them into an unauthenticated oracle that revalidates attacker-chosen tokens against
+ * Core. The recovery contract only ever concerns *this browser's* session, which lives in
+ * the HttpOnly app cookie.
+ */
+export async function classifyAppSessionFromCookie(headers, config) {
+    const token = readCookie(headers.get("cookie"), config.identityCookieName);
+    const resolution = await resolveAppSession(token, config);
+    return resolution.status;
+}
+// Follow the grant's absolute lifetime (expiresInSeconds). The bound is only a sanity
+// ceiling against a malformed response: 400 days is the maximum cookie Max-Age browsers
+// honor (RFC 6265bis), so it never truncates a configured absolute lifetime.
+const MAX_COOKIE_AGE_SECONDS = 400 * 24 * 60 * 60;
+/** Exchanges a one-time Shell/Core launch code for an identity token at Core. The code is
+ * the only credential — the endpoint is deliberately unauthenticated on Core's side. */
+export async function exchangeAppCode(code) {
+    const coreOrigin = getCoreOrigin();
+    let endpoint;
+    try {
+        endpoint = new URL("/api/auth/apps/token", coreOrigin ?? "").toString();
+    }
+    catch {
+        return { ok: false, status: 503, code: "core_origin_invalid", message: "HOSTY_CORE_ORIGIN is not a valid URL." };
+    }
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ code }),
+            cache: "no-store",
+            signal: AbortSignal.timeout(CORE_AUTH_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const timeout = error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError");
+        return {
+            ok: false,
+            status: 503,
+            code: timeout ? "core_token_exchange_timeout" : "core_token_exchange_unavailable",
+            message: "Hosty Core could not be reached to exchange the authorization code.",
+        };
+    }
+    if (!response.ok) {
+        return {
+            ok: false,
+            status: 401,
+            code: "app_auth_code_rejected",
+            message: `Core rejected the authorization code (HTTP ${response.status}).`,
+        };
+    }
+    const payload = (await response.json().catch(() => null));
+    const accessToken = readString(payload?.accessToken);
+    if (!accessToken) {
+        return { ok: false, status: 502, code: "app_identity_token_missing", message: "Core returned no usable identity token." };
+    }
+    // A missing/malformed lifetime is tolerated (the cookie falls back to the browser
+    // Max-Age ceiling) — the server-side grant still expires on schedule regardless, and
+    // recovery handles the eventual 401.
+    const expiresInSeconds = typeof payload?.expiresInSeconds === "number" && payload.expiresInSeconds > 0
+        ? payload.expiresInSeconds
+        : null;
+    return { ok: true, accessToken, expiresInSeconds };
+}
+/**
+ * Route-handler factory for `POST /api/auth/app-code`: exchanges the one-time `code` for
+ * an identity token, stores it in the app-origin HttpOnly cookie, and returns the token so
+ * the browser can keep a bearer fallback for when the cross-site cookie is blocked.
+ * Framework-agnostic (Web `Request`/`Response`), usable directly as a Next route handler.
+ */
+export function createAppCodeRouteHandler(config) {
+    return async function POST(request) {
+        let body = null;
+        try {
+            body = await request.json();
+        }
+        catch {
+            // Fall through to the missing-code response.
+        }
+        const code = body && typeof body === "object" ? readString(body.code) : null;
+        if (!code) {
+            return jsonResponse({ code: "app_auth_code_required", message: "A Hosty app authorization code is required." }, 422);
+        }
+        const exchange = await exchangeAppCode(code);
+        if (!exchange.ok) {
+            return jsonResponse({ code: exchange.code, message: exchange.message }, exchange.status);
+        }
+        const secure = isSecureRequest(request.headers, safeProtocol(request.url));
+        const attributes = identityCookieAttributes(secure, Math.min(exchange.expiresInSeconds ?? MAX_COOKIE_AGE_SECONDS, MAX_COOKIE_AGE_SECONDS));
+        const cookie = [
+            `${config.identityCookieName}=${encodeURIComponent(exchange.accessToken)}`,
+            `Path=${attributes.path}`,
+            `Max-Age=${attributes.maxAge}`,
+            `SameSite=${attributes.sameSite === "none" ? "None" : "Lax"}`,
+            "HttpOnly",
+            ...(attributes.secure ? ["Secure"] : []),
+        ].join("; ");
+        return jsonResponse({ accessToken: exchange.accessToken, expiresInSeconds: exchange.expiresInSeconds }, 200, { "set-cookie": cookie });
+    };
+}
+function safeProtocol(url) {
+    try {
+        return new URL(url).protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
+function jsonResponse(body, status, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", "cache-control": "no-store", ...headers },
+    });
+}
+function readCookie(cookieHeader, name) {
+    for (const entry of cookieHeader?.split(";") ?? []) {
+        const separator = entry.indexOf("=");
+        if (separator < 0 || entry.slice(0, separator).trim() !== name) {
+            continue;
+        }
+        try {
+            const value = decodeURIComponent(entry.slice(separator + 1).trim());
+            return value || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@hosty-sdk/app",
+  "version": "0.1.0",
+  "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./embedder": {
+      "types": "./dist/embedder.d.ts",
+      "default": "./dist/embedder.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^4",
+    "@types/node": "^24",
+    "@types/react": "^19"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-de-haas/docker-host.git",
+    "directory": "packages/app-sdk"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}