@hosty-sdk/app 0.19.1 → 0.21.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * The postMessage type an embedded app sends its parent to request a fresh launch code.
+ * The postMessage type for an embedded app's authentication-required intent.
  * 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.
@@ -13,8 +13,8 @@ export declare function createAuthRequiredIntent(appId: string): AuthRequiredInt
 /**
  * The postMessage types of the delegated-token handshake: an embedded app page asks its embedder
  * for a short-TTL token scoped to itself, and the embedder answers with one it minted from Core.
- * Same shape of contract as the launch-code recovery above — the app cannot self-serve, because
- * minting needs the user's Core session in a first-party context, which only the embedder has.
+ * Minting a delegated token uses the embedder's first-party Core session. The app's own identity
+ * sign-in is separate: it navigates directly to Core or opens its own popup.
  *
  * The request carries no secret, so it is safe to broadcast; the answer does, so an embedder must
  * post it to the frame's own origin and never to `*`. Answering is a decision, not a reflex: the
@@ -102,6 +102,7 @@ export declare function classifyRevalidationHttpStatus(status: number): AppSessi
 export interface SessionRecoveryParams {
     appId: string | null;
     corePublicOrigin: string | null;
+    appAuthProtocol: 1 | 2 | null;
 }
 export declare function readRecoveryParams(body: unknown): SessionRecoveryParams;
 /** True for hosts that only resolve on the machine itself. */
@@ -126,8 +127,9 @@ export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId:
 /**
  * How a shell is presenting this app.
  *
- * - `embedded` — framed by the browser Shell. The shell renders navigation for this app, and a
- *   parent frame exists, so identity recovery is a `hosty:auth-required` post to it.
+ * - `embedded` — framed by the browser Shell. The shell renders navigation for this app. The
+ *   app restores its per-tab grant, tries a silent Core redirect on first load, then uses its
+ *   own Core popup when interaction is required. No credential passes through the parent.
  * - `native` — the top frame inside a native shell's web view (`apps/shell-swift`). The shell
  *   renders navigation, but there is no parent to post to, so recovery takes the standalone
  *   redirect — which is exactly the navigation that client intercepts to re-mint a launch code.
@@ -135,10 +137,9 @@ export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId:
  *   for this app, so it keeps its own.
  *
  * Two independent decisions read this one value and they do not split it the same way: chrome
- * is hidden whenever the mode is not `standalone` (`hidesAppChrome`), while the parent post
- * belongs to `embedded` alone (`decideRecoveryAction`). That asymmetry is the whole reason
- * `native` exists as its own value — calling a native web view `embedded` to get its chrome
- * hidden would send recovery to a parent that is not there.
+ * is hidden whenever the mode is not `standalone` (`hidesAppChrome`), while frame-local silent
+ * sign-in and popup recovery belong to `embedded` alone (`AppIdentityBridge`). A native web
+ * view keeps standalone recovery even though its app chrome is hidden.
  */
 export type AppLaunchMode = "embedded" | "native" | "standalone";
 /** The query parameter a shell appends to the launch URL to declare the mode. */
@@ -160,9 +161,8 @@ export declare function normalizeLaunchMode(value: unknown): AppLaunchMode | nul
  * `standalone` — a native shell's web view makes the app the top frame, so it reads as
  * `standalone`, which is why the declared `hosty_launch` parameter exists at all.
  *
- * This stays the input to the *recovery* decision, because whether a parent exists is a
- * structural fact that a declared value cannot override: a stale `embedded` would otherwise
- * post into a window with no shell listening.
+ * This stays the input to the *recovery* decision, because framing is a structural fact a
+ * declared value cannot override: a stale `embedded` must not select frame-only silent sign-in.
  */
 export declare function detectLaunchMode(win: Pick<Window, "self" | "top">): Exclude<AppLaunchMode, "native">;
 export interface LaunchModeResolution {

package/dist/index.js

@@ -4,7 +4,7 @@
 // This is the single source of truth for the Hosty app-session contract described in
 // docker-host docs/features/hosty-app-sdk/feature.md and docs/features/auth-session-lifecycle/feature.md.
 /**
- * The postMessage type an embedded app sends its parent to request a fresh launch code.
+ * The postMessage type for an embedded app's authentication-required intent.
  * 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.
@@ -16,8 +16,8 @@ export function createAuthRequiredIntent(appId) {
 /**
  * The postMessage types of the delegated-token handshake: an embedded app page asks its embedder
  * for a short-TTL token scoped to itself, and the embedder answers with one it minted from Core.
- * Same shape of contract as the launch-code recovery above — the app cannot self-serve, because
- * minting needs the user's Core session in a first-party context, which only the embedder has.
+ * Minting a delegated token uses the embedder's first-party Core session. The app's own identity
+ * sign-in is separate: it navigates directly to Core or opens its own popup.
  *
  * The request carries no secret, so it is safe to broadcast; the answer does, so an embedder must
  * post it to the frame's own origin and never to `*`. Answering is a decision, not a reflex: the
@@ -89,10 +89,11 @@ export function classifyRevalidationHttpStatus(status) {
 export function readRecoveryParams(body) {
     const recovery = body && typeof body === "object" ? body.recovery : null;
     if (!recovery || typeof recovery !== "object") {
-        return { appId: null, corePublicOrigin: null };
+        return { appId: null, corePublicOrigin: null, appAuthProtocol: null };
     }
-    const { appId, corePublicOrigin } = recovery;
+    const { appId, corePublicOrigin, appAuthProtocol } = recovery;
     return {
+        appAuthProtocol: appAuthProtocol === 1 || appAuthProtocol === 2 ? appAuthProtocol : null,
         appId: typeof appId === "string" && appId.length > 0 ? appId : null,
         corePublicOrigin: typeof corePublicOrigin === "string" && corePublicOrigin.length > 0
             ? corePublicOrigin
@@ -102,7 +103,7 @@ export function readRecoveryParams(body) {
 /** 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]";
+    return host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1" || host === "::1" || host === "[::1]";
 }
 /**
  * Builds the Core standalone re-auth URL (`/api/apps/{id}/open?redirectUri=…`) for the
@@ -152,9 +153,8 @@ export function normalizeLaunchMode(value) {
  * `standalone` — a native shell's web view makes the app the top frame, so it reads as
  * `standalone`, which is why the declared `hosty_launch` parameter exists at all.
  *
- * This stays the input to the *recovery* decision, because whether a parent exists is a
- * structural fact that a declared value cannot override: a stale `embedded` would otherwise
- * post into a window with no shell listening.
+ * This stays the input to the *recovery* decision, because framing is a structural fact a
+ * declared value cannot override: a stale `embedded` must not select frame-only silent sign-in.
  */
 export function detectLaunchMode(win) {
     try {
@@ -241,7 +241,8 @@ export function decideRecoveryAction(input) {
     }
     // expired / not-present — the recoverable pair.
     //
-    // `embedded` is the only mode with a parent to ask. `native` deliberately falls through to the
+    // `embedded` selects app-owned interactive recovery after the bridge's silent first-load path.
+    // `native` deliberately falls through to the
     // redirect beside `standalone`: a native shell's web view has no parent, and the redirect to
     // Core's `/open` is the navigation that client watches for to re-mint a launch code. Adding a
     // mode must never quietly add a case here — a mode that cannot reach a shell has to redirect.

package/dist/react.d.ts

@@ -55,7 +55,8 @@ export interface AppIdentityBridgeProps {
 /**
  * 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: an app-owned Core popup when embedded, a once-per-tab
+ * recovery decision: a silent first-load Core navigation followed by an app-owned popup
+ * 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.
  */

package/dist/react.js

@@ -6,12 +6,14 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { AppActivityBridge } from "./activity-react.js";
 import { AuthNotice, AuthNoticeButton, authNoticeActionStyle } from "./auth-notice.js";
 import { useEffect, useRef, useState } from "react";
-import { appFetch, appSessionActive, rememberAppGrant, openAppSignIn, APP_SESSION_ENDED } from "./browser-auth.js";
+import { appFetch, appSessionActive, appGrantRevision, rememberAppGrant, restoreAppGrant, forgetRejectedAppGrant, openAppSignIn, APP_SESSION_ENDED } from "./browser-auth.js";
+import { acceptAppAuthProtocol, createAppAuthAttempt, persistAppAuthAttempt, takeAppAuthAttempt, submitAppAuthIntent, appAuthNavigationUrl, APP_AUTH_ATTEMPT_PREFIX } from "./browser-auth.js";
 import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, normalizeLaunchMode, readRecoveryParams, resolveLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY, } from "./index.js";
 import { applyTheme, parseShellThemeMessage, resolveTheme, THEME_PARAM, THEME_PREFERENCE_PARAM, THEME_PREFERENCE_STORAGE_KEY, THEME_STORAGE_KEY, } from "./theme.js";
 // 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";
+const SILENT_GUARD_PREFIX = "hosty.auth.silent-attempted:";
 // 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;
@@ -66,6 +68,42 @@ function writeGuard(value) {
         // sessionStorage may be blocked; recovery still works, only the guard is lost.
     }
 }
+/** Both state and the per-app guard must survive navigation, or the popup is the fallback. */
+function beginNavigationSignIn(openUrl, appId, protocol, mode, force = false) {
+    let state = null;
+    try {
+        const guardKey = mode === "silent" ? `${SILENT_GUARD_PREFIX}${appId}` : RECOVERY_GUARD_KEY;
+        if (!force && window.sessionStorage.getItem(guardKey) === "1")
+            return false;
+        const attempt = createAppAuthAttempt(openUrl, mode, protocol);
+        state = attempt.state;
+        if (!persistAppAuthAttempt(attempt))
+            return false;
+        window.sessionStorage.setItem(guardKey, "1");
+        if (window.sessionStorage.getItem(guardKey) !== "1")
+            throw new Error("Sign-in storage is unavailable.");
+        if (mode === "native")
+            window.location.assign(appAuthNavigationUrl(attempt));
+        else if (protocol === 1) {
+            if (mode === "silent")
+                window.location.replace(appAuthNavigationUrl(attempt));
+            else
+                window.location.assign(appAuthNavigationUrl(attempt));
+        }
+        else
+            submitAppAuthIntent(attempt);
+        return true;
+    }
+    catch {
+        if (state) {
+            try {
+                window.sessionStorage.removeItem(`${APP_AUTH_ATTEMPT_PREFIX}${state}`);
+            }
+            catch { /* Popup fallback. */ }
+        }
+        return false;
+    }
+}
 function readStoredLaunchMode() {
     try {
         return window.sessionStorage.getItem(LAUNCH_MODE_STORAGE_KEY);
@@ -76,7 +114,7 @@ function readStoredLaunchMode() {
 }
 /** The mode already applied to the document, or a fresh resolution when nothing applied one. */
 function currentLaunchMode() {
-    const applied = normalizeLaunchMode(document.documentElement.getAttribute(LAUNCH_MODE_ATTRIBUTE));
+    const applied = typeof document === "undefined" ? null : normalizeLaunchMode(document.documentElement.getAttribute(LAUNCH_MODE_ATTRIBUTE));
     if (applied) {
         return applied;
     }
@@ -144,7 +182,8 @@ export function useLaunchMode() {
 /**
  * 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: an app-owned Core popup when embedded, a once-per-tab
+ * recovery decision: a silent first-load Core navigation followed by an app-owned popup
+ * 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.
  */
@@ -153,11 +192,18 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
     // 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);
+    const firstProbe = useRef(true);
+    const initialGrantPresent = useRef(null);
+    const silentError = useRef(null);
+    const returnedLegacyAttempt = useRef(null);
+    const upgradedAttempt = useRef(false);
     const [activity, setActivity] = useState(null);
     const exchangeRef = useRef(null);
     useEffect(() => {
         let cancelled = false;
         const controller = new AbortController();
+        if (initialGrantPresent.current === null)
+            initialGrantPresent.current = restoreAppGrant();
         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
@@ -169,6 +215,10 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             let status = null;
             let openUrl = null;
             let appId = null;
+            let protocol = null;
+            let activityMetadata = null;
+            let rejectionCode;
+            const revision = appGrantRevision();
             try {
                 const response = await appFetch(probePath, {
                     headers: { Accept: "application/json" },
@@ -177,12 +227,13 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 }, false);
                 const body = await response.json().catch(() => null);
                 status = readProbedSessionStatus(body);
+                const identityError = body;
+                rejectionCode = identityError?.error?.code ?? identityError?.appSession?.error?.code;
                 const recovery = readRecoveryParams(body);
                 appId = recovery.appId;
                 openUrl = appId ? buildCoreOpenUrl(recovery.corePublicOrigin, appId, window.location) : null;
-                const metadata = body;
-                if (!cancelled && openUrl)
-                    setActivity({ openUrl, activeUntil: metadata?.activeUntil, activityRequired: metadata?.activityRequired });
+                protocol = openUrl ? acceptAppAuthProtocol(new URL(openUrl).origin, recovery.appAuthProtocol) : recovery.appAuthProtocol;
+                activityMetadata = body;
             }
             catch {
                 // A failed or timed-out probe (Core unreachable) classifies as unavailable below.
@@ -195,14 +246,46 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             if (cancelled) {
                 return;
             }
-            const action = !status || !appId
+            if (revision !== appGrantRevision()) {
+                initialGrantPresent.current ||= restoreAppGrant();
+                void probeAndRecover();
+                return;
+            }
+            forgetRejectedAppGrant(rejectionCode, revision);
+            if (openUrl && protocol)
+                setActivity({ openUrl, appAuthProtocol: protocol,
+                    activeUntil: activityMetadata?.activeUntil, activityRequired: activityMetadata?.activityRequired });
+            const initialLoad = firstProbe.current;
+            firstProbe.current = false;
+            if (silentError.current === "access_denied") {
+                setUi({ kind: "denied" });
+                return;
+            }
+            const mode = currentLaunchMode();
+            const legacy = returnedLegacyAttempt.current;
+            const sameLegacyCore = !!legacy && appId === legacy.appId && !!openUrl && new URL(openUrl).origin === legacy.coreOrigin;
+            if (legacy?.protocolRequired && (status === "not-present" || status === "expired") && (!sameLegacyCore || protocol !== 2)) {
+                setUi({ kind: "unavailable" });
+                return;
+            }
+            const shouldUpgrade = sameLegacyCore && protocol === 2 && !upgradedAttempt.current;
+            if (shouldUpgrade) {
+                upgradedAttempt.current = true;
+                returnedLegacyAttempt.current = null;
+            }
+            if (!wasActive.current && protocol && ((initialLoad && !initialGrantPresent.current && !silentError.current) || shouldUpgrade) &&
+                detectLaunchMode(window) === "embedded" && (status === "not-present" || status === "expired") && appId && openUrl) {
+                if (beginNavigationSignIn(openUrl, appId, protocol, "silent", shouldUpgrade))
+                    return;
+            }
+            const action = !status || !appId || ((status === "not-present" || status === "expired") && !protocol)
                 ? { kind: "card", card: "unavailable" }
                 : decideRecoveryAction({
-                    status,
-                    mode: detectLaunchMode(window),
+                    status: silentError.current === "login_required" ? "not-present" : status,
+                    mode,
                     appId,
                     openUrl,
-                    redirectAlreadyAttempted: readGuard(),
+                    redirectAlreadyAttempted: !shouldUpgrade && readGuard(),
                 });
             switch (action.kind) {
                 case "none":
@@ -211,40 +294,50 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                     setUi({ kind: "active" });
                     return;
                 case "post-auth-required": {
-                    const showSignIn = (error) => setUi({ kind: "signin", openUrl, embedded: true, error,
-                        signIn: openUrl ? () => {
-                            // Open synchronously in the click handler; an awaited request loses the user gesture.
-                            const result = openAppSignIn(openUrl, controller.signal);
-                            setUi({ kind: "recovering" });
-                            void result.then(async (code) => {
-                                const response = await appFetch(appCodePath, {
-                                    method: "POST", headers: { "Content-Type": "application/json" },
-                                    body: JSON.stringify({ code }),
-                                });
-                                const body = await response.json();
-                                if (!response.ok || typeof body.accessToken !== "string" || !body.accessToken)
-                                    throw new Error("Hosty could not establish this app session.");
-                                if (cancelled)
-                                    return;
-                                rememberAppGrant(body.accessToken);
-                                writeGuard(false);
-                                await probeAndRecover();
-                            }).catch(error => { if (!cancelled)
-                                showSignIn(error instanceof Error ? error.message : "Sign-in failed."); });
-                        } : undefined });
                     showSignIn();
                     return;
                 }
                 case "redirect":
-                    writeGuard(true);
-                    window.location.assign(action.openUrl);
+                    if (appId && protocol && beginNavigationSignIn(action.openUrl, appId, protocol, mode === "native" ? "native" : "standalone", shouldUpgrade))
+                        return;
+                    showSignIn("Allow app storage, or sign in with a popup.");
                     return;
                 case "card":
-                    setUi(action.card === "signin"
-                        ? { kind: "signin", openUrl, embedded: false }
-                        : { kind: action.card });
+                    if (action.card === "signin")
+                        showSignIn();
+                    else
+                        setUi({ kind: action.card });
                     return;
             }
+            function showSignIn(error) {
+                setUi({ kind: "signin", openUrl, embedded: mode === "embedded", error,
+                    signIn: openUrl && protocol ? () => {
+                        // Open synchronously in the click handler; an awaited request loses the user gesture.
+                        const revision = appGrantRevision();
+                        const result = openAppSignIn(openUrl, controller.signal, protocol, mode === "native", probePath);
+                        setUi({ kind: "recovering" });
+                        void result.then(async (proof) => {
+                            const response = await appFetch(appCodePath, {
+                                method: "POST", headers: { "Content-Type": "application/json" },
+                                body: JSON.stringify(proof),
+                            }, false);
+                            const body = await response.json();
+                            if (!response.ok || typeof body.accessToken !== "string" || !body.accessToken)
+                                throw new Error("Hosty could not establish this app session.");
+                            if (cancelled)
+                                return;
+                            if (revision !== appGrantRevision()) {
+                                await probeAndRecover();
+                                return;
+                            }
+                            rememberAppGrant(body.accessToken);
+                            silentError.current = null;
+                            writeGuard(false);
+                            await probeAndRecover();
+                        }).catch(error => { if (!cancelled)
+                            showSignIn(error instanceof Error ? error.message : "Sign-in failed."); });
+                    } : undefined });
+            }
         }
         const recover = () => { if (!cancelled && !wasActive.current) {
             setUi({ kind: "recovering" });
@@ -253,15 +346,31 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         window.addEventListener(APP_SESSION_ENDED, recover);
         const url = new URL(window.location.href);
         const code = url.searchParams.get("code")?.trim();
-        if (code) {
+        const error = url.searchParams.get("error");
+        const isSilentError = error === "login_required" || error === "access_denied";
+        const attempt = takeAppAuthAttempt(url, true);
+        const upgradedLegacy = attempt?.protocol === 1 && acceptAppAuthProtocol(attempt.coreOrigin, 1) === null;
+        if (attempt?.mode === "silent" && isSilentError)
+            silentError.current = error;
+        const protocolRequired = attempt?.protocol === 1 && !code && error === "protocol_required" && url.searchParams.getAll("error").length === 1;
+        if (attempt?.protocol === 1 && (!error || protocolRequired || upgradedLegacy))
+            returnedLegacyAttempt.current = { appId: attempt.appId, coreOrigin: attempt.coreOrigin, protocolRequired: protocolRequired || upgradedLegacy };
+        if (code || isSilentError || attempt) {
             url.searchParams.delete("code");
+            url.searchParams.delete("state");
+            if (isSilentError || protocolRequired)
+                url.searchParams.delete("error");
             window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+        }
+        if (code && !error && !upgradedLegacy && attempt && !exchangeRef.current) {
             exchangeRef.current = {
                 path: appCodePath,
+                revision: appGrantRevision(),
                 response: fetch(appCodePath, {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify({ code }),
+                    body: JSON.stringify({ code, codeVerifier: attempt.codeVerifier }),
+                    credentials: "same-origin", redirect: "error",
                 }),
             };
         }
@@ -275,6 +384,13 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 if (response.ok) {
                     writeGuard(false);
                     const body = await response.json().catch(() => null);
+                    if (cancelled)
+                        return;
+                    if (exchange.revision !== appGrantRevision()) {
+                        exchangeRef.current = null;
+                        await probeAndRecover();
+                        return;
+                    }
                     if (typeof body?.accessToken === "string")
                         rememberAppGrant(body.accessToken);
                     exchangeRef.current = null;
@@ -302,7 +418,7 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         };
     }, [probePath, appCodePath]);
     if (wasActive.current)
-        return _jsxs(_Fragment, { children: [activity && _jsx(AppActivityBridge, { ...activity, appCodePath: appCodePath }), renderState ? renderState({ kind: "active" }) : children] });
+        return _jsxs(_Fragment, { children: [activity && _jsx(AppActivityBridge, { ...activity, appCodePath: appCodePath, probePath: probePath }), renderState ? renderState({ kind: "active" }) : children] });
     if (renderState)
         return renderState(ui);
     if (ui.kind === "active")

package/dist/server.d.ts

@@ -1,4 +1,6 @@
 import "server-only";
+import { type AppAuthProtocol } from "./app-code.js";
+export { isValidCodeVerifier } from "./app-code.js";
 import { type AppSessionFailureStatus, type AppSessionStatus, type SessionRecoveryParams } from "./index.js";
 /** Per-app parameters: everything that legitimately diverges between apps stays a
  * parameter — cookie namespaces and role models are per-app by decision, never unified. */
@@ -46,7 +48,8 @@ export declare function getCoreOrigin(): string | null;
  * 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 declare function getAppAuthProtocol(): Promise<AppAuthProtocol | null>;
+export declare function getRecoveryParams(config: HostyAppConfig): Promise<SessionRecoveryParams>;
 export type HeaderReader = {
     get(name: string): string | null;
 };
@@ -98,9 +101,8 @@ export type AppCodeExchange = {
     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>;
+/** Exchanges a one-time Core code using this app's service credential. */
+export declare function exchangeAppCode(code: string, codeVerifier: 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

package/dist/server.js

@@ -1,6 +1,8 @@
 // Server slice: Next route-handler factories and Core revalidation. Never reaches a client
 // bundle — the service token lives here.
 import "server-only";
+import { resolveAppAuthProtocol, appAuthProtocolMinimum, isValidCodeVerifier } from "./app-code.js";
+export { isValidCodeVerifier } from "./app-code.js";
 import { classifyRevalidationHttpStatus, } from "./index.js";
 // 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.
@@ -27,8 +29,11 @@ export function getCorePublicOrigin() {
 export function getServiceToken() {
     return process.env.HOSTY_APP_SERVICE_TOKEN?.trim() || null;
 }
-export function getRecoveryParams(config) {
-    return { appId: getAppId(config), corePublicOrigin: getCorePublicOrigin() };
+export function getAppAuthProtocol() {
+    return resolveAppAuthProtocol(getCoreOrigin());
+}
+export async function getRecoveryParams(config) {
+    return { appId: getAppId(config), corePublicOrigin: getCorePublicOrigin(), appAuthProtocol: await getAppAuthProtocol() };
 }
 /**
  * Reads an explicitly presented app grant first, then the app cookie and legacy identity header.
@@ -239,10 +244,17 @@ export async function classifyAppSessionFromCookie(headers, config) {
 // 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) {
+/** Exchanges a one-time Core code using this app's service credential. */
+export async function exchangeAppCode(code, codeVerifier) {
+    if (!isValidCodeVerifier(codeVerifier))
+        return { ok: false, status: 400, code: "app_auth_proof_required", message: "A valid Hosty sign-in proof is required." };
+    const serviceToken = getServiceToken();
+    if (!serviceToken) {
+        return { ok: false, status: 503, code: "app_service_token_missing", message: "HOSTY_APP_SERVICE_TOKEN is not configured." };
+    }
     const coreOrigin = getCoreOrigin();
+    if (appAuthProtocolMinimum(coreOrigin) === 2 && await getAppAuthProtocol() !== 2)
+        return { ok: false, status: 503, code: "app_auth_protocol_unavailable", message: "Hosty sign-in protocol could not be verified." };
     let endpoint;
     try {
         endpoint = new URL("/api/auth/apps/token", coreOrigin ?? "").toString();
@@ -254,9 +266,10 @@ export async function exchangeAppCode(code) {
     try {
         response = await fetch(endpoint, {
             method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ code }),
+            headers: { "content-type": "application/json", authorization: `Bearer ${serviceToken}` },
+            body: JSON.stringify({ code, codeVerifier }),
             cache: "no-store",
+            redirect: "error",
             signal: AbortSignal.timeout(CORE_AUTH_TIMEOUT_MS),
         });
     }
@@ -317,7 +330,10 @@ export function createAppCodeRouteHandler(config) {
         if (!code) {
             return jsonResponse({ code: "app_auth_code_required", message: "A Hosty app authorization code is required." }, 422);
         }
-        const exchange = await exchangeAppCode(code);
+        const codeVerifier = body && typeof body === "object" ? body.codeVerifier : null;
+        if (!isValidCodeVerifier(codeVerifier))
+            return jsonResponse({ code: "app_auth_proof_required", message: "A valid Hosty sign-in proof is required." }, 400);
+        const exchange = await exchangeAppCode(code, codeVerifier);
         if (!exchange.ok) {
             return jsonResponse({ code: exchange.code, message: exchange.message }, exchange.status);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/browser-auth.d.ts",
       "default": "./dist/browser-auth.js"
     },
+    "./app-code": {
+      "types": "./dist/app-code.d.ts",
+      "default": "./dist/app-code.js"
+    },
     "./delegated": {
       "types": "./dist/delegated.d.ts",
       "default": "./dist/delegated.js"
@@ -83,6 +87,7 @@
     "build": "tsc -p tsconfig.build.json && node scripts/fix-dist-extensions.mjs"
   },
   "dependencies": {
+    "@noble/hashes": "^2.4.0",
     "server-only": "^0.0.1"
   },
   "peerDependencies": {