@hosty-sdk/app 0.20.0 → 0.21.1

package/README.md

@@ -25,6 +25,13 @@ Minimal Next.js wiring:
 import { AppIdentityBridge } from "@hosty-sdk/app/react";
 // wrap protected client content: <AppIdentityBridge>{children}</AppIdentityBridge>
 
+// Reuse an active probe that already returns the app's session fields:
+// <AppIdentityBridge probePath="/api/auth/session" onSession={seedSessionCache}>
+//   {children}
+// </AppIdentityBridge>
+// seedSessionCache receives unknown JSON; validate app-specific fields before caching.
+// The callback runs before children mount, only for a successful active probe.
+
 // app/api/auth/app-code/route.ts
 import { createAppCodeRouteHandler } from "@hosty-sdk/app/server";
 export const dynamic = "force-dynamic";

package/dist/activity-react.d.ts

@@ -1,7 +1,11 @@
+import type { AppAuthProtocol } from "./app-code.js";
 /** Keep mounted beside app content so expiry never discards drafts or component state. */
-export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired }: {
+export declare function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired, appAuthProtocol, probePath, native }: {
     openUrl: string;
     appCodePath: string;
     activeUntil?: string | null;
     activityRequired?: boolean;
+    appAuthProtocol?: AppAuthProtocol | null;
+    probePath?: string;
+    native?: boolean;
 }): import("react").JSX.Element | null;

package/dist/activity-react.js

@@ -3,8 +3,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { AuthNotice, AuthNoticeButton } from "./auth-notice.js";
 import { APP_SESSION_ENDED, APP_ACTIVITY_RENEWED, appActivityNeedsRenewal, configureAppActivity, updateAppActivity, renewAppActivity, cancelActivityRenewal } from "./browser-auth.js";
+import { resolveLaunchMode, detectLaunchMode, normalizeLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY } from "./index.js";
+import { acceptAppAuthProtocol, refreshAppAuthProtocol } from "./browser-auth.js";
 /** Keep mounted beside app content so expiry never discards drafts or component state. */
-export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired = false }) {
+export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityRequired = false, appAuthProtocol, probePath = "/api/auth/identity", native }) {
     const [needed, setNeeded] = useState(false);
     const [pending, setPending] = useState(false);
     const [error, setError] = useState("");
@@ -15,14 +17,35 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         void operation.catch(e => { setNeeded(true); setError(String(e.message ?? e)); }).finally(() => setPending(false));
     };
     useEffect(() => {
-        const cleanup = configureAppActivity({ openUrl, exchangeCode: async (code) => {
-                const response = await fetch(appCodePath, { method: "POST", credentials: "same-origin", redirect: "error",
-                    headers: { "Content-Type": "application/json" }, body: JSON.stringify({ code }) });
-                const body = await response.json();
-                if (!response.ok)
-                    throw new Error(body.message ?? "Could not renew app activity.");
-                return body;
-            } });
+        let cancelled = false;
+        let cleanup;
+        const controller = new AbortController();
+        const configure = (protocol) => {
+            if (cancelled || !protocol || acceptAppAuthProtocol(new URL(openUrl).origin, protocol) !== protocol)
+                return;
+            let stored = null;
+            try {
+                stored = window.sessionStorage.getItem(LAUNCH_MODE_STORAGE_KEY);
+            }
+            catch { /* The applied document mode remains available. */ }
+            const mode = normalizeLaunchMode(document.documentElement.getAttribute(LAUNCH_MODE_ATTRIBUTE)) ?? resolveLaunchMode({
+                param: new URL(window.location.href).searchParams.get(LAUNCH_MODE_PARAM), stored, heuristic: detectLaunchMode(window),
+            }).mode;
+            cleanup = configureAppActivity({ openUrl, appAuthProtocol: protocol, probePath, native: native ?? mode === "native", activeUntil, activityRequired, exchangeCode: async (proof) => {
+                    const response = await fetch(appCodePath, { method: "POST", credentials: "same-origin", redirect: "error",
+                        headers: { "Content-Type": "application/json" }, body: JSON.stringify(proof) });
+                    const body = await response.json();
+                    if (!response.ok)
+                        throw new Error(body.message ?? "Could not renew app activity.");
+                    return body;
+                } });
+        };
+        if (appAuthProtocol !== undefined && !(appAuthProtocol === 1 && acceptAppAuthProtocol(new URL(openUrl).origin, 1) === null))
+            configure(appAuthProtocol);
+        else
+            void refreshAppAuthProtocol(openUrl, probePath, controller.signal).then(configure);
+        // A stale protocol-1 prop cannot overwrite a protocol-2 minimum already verified
+        // by this app. Unknown discovery leaves renewal disabled instead of downgrading.
         const expired = () => setNeeded(true);
         const renewed = () => { setNeeded(false); setError(""); };
         const click = (event) => {
@@ -35,8 +58,8 @@ export function AppActivityBridge({ openUrl, appCodePath, activeUntil, activityR
         window.addEventListener(APP_SESSION_ENDED, expired);
         window.addEventListener(APP_ACTIVITY_RENEWED, renewed);
         document.addEventListener("click", click, true);
-        return () => { cleanup(); window.removeEventListener(APP_SESSION_ENDED, expired); window.removeEventListener(APP_ACTIVITY_RENEWED, renewed); document.removeEventListener("click", click, true); };
-    }, [openUrl, appCodePath]);
+        return () => { cancelled = true; controller.abort(); cleanup?.(); window.removeEventListener(APP_SESSION_ENDED, expired); window.removeEventListener(APP_ACTIVITY_RENEWED, renewed); document.removeEventListener("click", click, true); };
+    }, [openUrl, appCodePath, appAuthProtocol, probePath, native]);
     useEffect(() => { updateAppActivity(activeUntil, activityRequired); }, [activeUntil, activityRequired, openUrl, appCodePath]);
     if (!needed)
         return null;

package/dist/app-code.d.ts

@@ -0,0 +1,6 @@
+/** Shared by framework server adapters and plain Node apps. Never sends an app credential. */
+export type AppAuthProtocol = 1 | 2;
+export declare function isValidCodeVerifier(value: unknown): value is string;
+export declare function appAuthProtocolMinimum(coreOrigin: string | null): 2 | null;
+/** A 404 alone is insufficient: only an identified, older Core permits the old navigation. */
+export declare function resolveAppAuthProtocol(coreOrigin: string | null): Promise<AppAuthProtocol | null>;

package/dist/app-code.js

@@ -0,0 +1,80 @@
+export function isValidCodeVerifier(value) {
+    return typeof value === "string" && /^[A-Za-z0-9._~-]{43,128}$/.test(value);
+}
+const minimumProtocols = new Set();
+const discoveries = new Map();
+export function appAuthProtocolMinimum(coreOrigin) {
+    try {
+        return minimumProtocols.has(new URL(coreOrigin ?? "").origin) ? 2 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isOlderCoreVersion(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/.exec(value);
+    if (!match)
+        return false;
+    for (const [index, suffix] of [[4, match[4]], [5, match[5]]]) {
+        if (suffix && suffix.split(".").some(part => !/^[0-9A-Za-z-]+$/.test(part) || (index === 4 && /^0\d+$/.test(part))))
+            return false;
+    }
+    const major = Number(match[1]), minor = Number(match[2]), patch = Number(match[3]);
+    return [major, minor, patch].every(Number.isSafeInteger) && major === 0 && minor < 120;
+}
+/** A 404 alone is insufficient: only an identified, older Core permits the old navigation. */
+export async function resolveAppAuthProtocol(coreOrigin) {
+    let origin;
+    try {
+        const parsed = new URL(coreOrigin ?? "");
+        if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password ||
+            parsed.pathname !== "/" || parsed.search || parsed.hash)
+            return null;
+        origin = parsed.origin;
+    }
+    catch {
+        return null;
+    }
+    const pending = discoveries.get(origin);
+    if (pending)
+        return pending;
+    const operation = (async () => {
+        const request = (path) => fetch(new URL(path, origin), {
+            cache: "no-store", redirect: "error", headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(1_500),
+        });
+        try {
+            const response = await request("/api/auth/apps/protocol");
+            if (response.status === 200) {
+                if (!response.headers.get("content-type")?.toLowerCase().startsWith("application/json"))
+                    return null;
+                const body = await response.json().catch(() => null);
+                if (body?.version !== 2)
+                    return null;
+                minimumProtocols.add(origin);
+                return 2;
+            }
+            if (response.status !== 404 || minimumProtocols.has(origin))
+                return null;
+            const status = await request("/api/core/status");
+            if (status.status !== 200)
+                return null;
+            if (!status.headers.get("content-type")?.toLowerCase().startsWith("application/json"))
+                return null;
+            const body = await status.json().catch(() => null);
+            return body?.component === "hosty-core" && body.status === "running" && isOlderCoreVersion(body.version) ? 1 : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    discoveries.set(origin, operation);
+    try {
+        return await operation;
+    }
+    finally {
+        discoveries.delete(origin);
+    }
+}

package/dist/browser-auth.d.ts

@@ -1,4 +1,33 @@
+import type { AppAuthProtocol } from "./app-code.js";
+export type AppSignInResult = {
+    code: string;
+    codeVerifier: string;
+};
+export type AppAuthAttempt = {
+    state: string;
+    codeVerifier: string;
+    codeChallenge: string;
+    appId: string;
+    coreOrigin: string;
+    redirectUri: string;
+    createdAt: number;
+    mode: "standalone" | "silent" | "popup" | "native";
+    protocol: AppAuthProtocol;
+};
+export declare const APP_AUTH_ATTEMPT_PREFIX = "hosty.auth.attempt:";
+export declare function appCodeChallenge(verifier: string): string;
+export declare function acceptAppAuthProtocol(coreOrigin: string, protocol: AppAuthProtocol | null): AppAuthProtocol | null;
+export declare function createAppAuthAttempt(openUrl: string, mode: AppAuthAttempt["mode"], protocol: AppAuthProtocol): AppAuthAttempt;
+/** Do not leave the app document unless this exact proof survives a storage round trip. */
+export declare function persistAppAuthAttempt(attempt: AppAuthAttempt): boolean;
+/** Correlation is local; URL fields never supply a verifier or a pending attempt. */
+export declare function takeAppAuthAttempt(callback: URL, allowLegacyUpgrade?: boolean): AppAuthAttempt | null;
+export declare function clearAppAuthAttempts(): void;
+export declare function appAuthNavigationUrl(attempt: AppAuthAttempt): string;
+/** Constant document and DOM-built fields prevent a public URL from laundering a challenge. */
+export declare function submitAppAuthIntent(attempt: AppAuthAttempt, doc?: Document): void;
 export declare const APP_SESSION_ENDED = "hosty:app-session-ended";
+export declare const NATIVE_APP_AUTH_RESULT = "hosty:native-auth-result";
 export declare const APP_GRANT_STORAGE_KEY = "hosty.auth.app-grant";
 /** Restore before the first identity probe; standalone documents use their first-party cookie. */
 export declare function restoreAppGrant(): boolean;
@@ -11,14 +40,19 @@ export declare function forgetRejectedAppGrant(code: unknown, expectedRevision?:
 export declare function appSessionActive(): void;
 /** Use for app-local API calls, including streams. Redirects cannot carry the credential away. */
 export declare function appFetch(input: string | URL, init?: RequestInit, recover?: boolean): Promise<Response>;
-/** Must be called directly from a user gesture. The popup belongs to this app frame, not Shell. */
-export declare function openAppSignIn(openUrl: string, signal?: AbortSignal): Promise<string>;
+/** Refresh only the app-local, server-verified metadata for this frozen app/Core pair. */
+export declare function refreshAppAuthProtocol(openUrl: string, probePath?: string, signal?: AbortSignal): Promise<AppAuthProtocol | null>;
+/** Must be called directly from a user gesture. Native hosts intercept before any request. */
+export declare function openAppSignIn(openUrl: string, signal?: AbortSignal, appAuthProtocol?: AppAuthProtocol, native?: boolean, probePath?: string): Promise<AppSignInResult>;
 export declare const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
 export type AppActivityConfig = {
     openUrl: string;
+    appAuthProtocol: AppAuthProtocol;
+    native?: boolean;
+    probePath?: string;
     activeUntil?: string | null;
     activityRequired?: boolean;
-    exchangeCode: (code: string) => Promise<{
+    exchangeCode: (result: AppSignInResult) => Promise<{
         accessToken?: string;
         activeUntil?: string | null;
     }>;

package/dist/browser-auth.js

@@ -1,8 +1,190 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+function isValidCodeVerifier(value) {
+    return typeof value === "string" && /^[A-Za-z0-9._~-]{43,128}$/.test(value);
+}
+export const APP_AUTH_ATTEMPT_PREFIX = "hosty.auth.attempt:";
+const MINIMUM_PROTOCOL_PREFIX = "hosty.auth.protocol:";
+const ATTEMPT_LIFETIME = 300_000;
+const MAX_ATTEMPTS = 16;
+const protocolMinimums = new Set();
+function base64url(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function appCodeChallenge(verifier) {
+    if (!isValidCodeVerifier(verifier))
+        throw new Error("The sign-in proof is invalid.");
+    return base64url(sha256(Uint8Array.from(verifier, character => character.charCodeAt(0))));
+}
+export function acceptAppAuthProtocol(coreOrigin, protocol) {
+    const key = `${MINIMUM_PROTOCOL_PREFIX}${coreOrigin}`;
+    try {
+        if (window.sessionStorage.getItem(key) === "2")
+            protocolMinimums.add(coreOrigin);
+    }
+    catch { /* Memory minimum still applies. */ }
+    if (protocol === 2) {
+        protocolMinimums.add(coreOrigin);
+        try {
+            window.sessionStorage.setItem(key, "2");
+        }
+        catch { /* Keep the minimum in memory. */ }
+        return 2;
+    }
+    return protocol === 1 && !protocolMinimums.has(coreOrigin) ? 1 : null;
+}
+export function createAppAuthAttempt(openUrl, mode, protocol) {
+    const url = new URL(openUrl);
+    const match = /^\/api\/apps\/([^/]+)\/open$/.exec(url.pathname);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || !match)
+        throw new Error("Hosty sign-in URL is invalid.");
+    if (acceptAppAuthProtocol(url.origin, protocol) !== protocol)
+        throw new Error("Hosty sign-in protocol could not be verified.");
+    const redirect = new URL(url.searchParams.get("redirectUri") ?? "");
+    if (redirect.origin !== window.location.origin || redirect.username || redirect.password || redirect.hash)
+        throw new Error("Hosty sign-in must return to this app.");
+    const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+    const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), byte => byte.toString(16).padStart(2, "0")).join("");
+    redirect.searchParams.delete("code");
+    redirect.searchParams.delete("error");
+    redirect.searchParams.set("state", state);
+    return { state, codeVerifier, codeChallenge: appCodeChallenge(codeVerifier), appId: decodeURIComponent(match[1]),
+        coreOrigin: url.origin, redirectUri: redirect.href, createdAt: Date.now(), mode, protocol };
+}
+function storedAttempts() {
+    const keys = [];
+    const storage = window.sessionStorage;
+    for (let index = 0; index < storage.length; index++) {
+        const key = storage.key(index);
+        if (!key?.startsWith(APP_AUTH_ATTEMPT_PREFIX))
+            continue;
+        try {
+            const record = JSON.parse(storage.getItem(key) ?? "null");
+            if (typeof record?.createdAt !== "number" || record.createdAt > Date.now() || Date.now() - record.createdAt >= ATTEMPT_LIFETIME) {
+                storage.removeItem(key);
+                index--;
+                continue;
+            }
+        }
+        catch {
+            storage.removeItem(key);
+            index--;
+            continue;
+        }
+        keys.push(key);
+    }
+    return keys;
+}
+/** Do not leave the app document unless this exact proof survives a storage round trip. */
+export function persistAppAuthAttempt(attempt) {
+    const key = `${APP_AUTH_ATTEMPT_PREFIX}${attempt.state}`;
+    try {
+        if (storedAttempts().length >= MAX_ATTEMPTS)
+            return false;
+        const value = JSON.stringify(attempt);
+        window.sessionStorage.setItem(key, value);
+        if (window.sessionStorage.getItem(key) === value)
+            return true;
+    }
+    catch { /* The explicit popup can keep a proof in memory instead. */ }
+    try {
+        window.sessionStorage.removeItem(key);
+    }
+    catch { /* Storage remains blocked. */ }
+    return false;
+}
+function callbackLocation(url) {
+    const copy = new URL(url);
+    for (const name of ["code", "state", "error", "hosty_launch"])
+        copy.searchParams.delete(name);
+    copy.hash = "";
+    copy.searchParams.sort();
+    return copy.href;
+}
+/** Correlation is local; URL fields never supply a verifier or a pending attempt. */
+// Only the recovery bridge opts in to classify and discard an obsolete local v1
+// record. Such a record must never be exchanged after v2 has already been observed.
+export function takeAppAuthAttempt(callback, allowLegacyUpgrade = false) {
+    const states = callback.searchParams.getAll("state");
+    const state = states[0];
+    if (!state || !/^[a-f0-9]{64}$/.test(state) || states.some(value => value !== state))
+        return null;
+    const key = `${APP_AUTH_ATTEMPT_PREFIX}${state}`;
+    try {
+        const value = window.sessionStorage.getItem(key);
+        if (!value)
+            return null;
+        window.sessionStorage.removeItem(key);
+        const attempt = JSON.parse(value);
+        if (attempt.state !== state || !isValidCodeVerifier(attempt.codeVerifier) ||
+            attempt.codeChallenge !== appCodeChallenge(attempt.codeVerifier) ||
+            ![1, 2].includes(attempt.protocol) || !["standalone", "silent", "native"].includes(attempt.mode) ||
+            typeof attempt.appId !== "string" || !attempt.appId ||
+            typeof attempt.createdAt !== "number" || attempt.createdAt > Date.now() || Date.now() - attempt.createdAt >= ATTEMPT_LIFETIME ||
+            new URL(attempt.redirectUri).origin !== window.location.origin || callbackLocation(new URL(attempt.redirectUri)) !== callbackLocation(callback) ||
+            new URL(attempt.coreOrigin).origin !== attempt.coreOrigin ||
+            (acceptAppAuthProtocol(attempt.coreOrigin, attempt.protocol) !== attempt.protocol && !(allowLegacyUpgrade && attempt.protocol === 1)))
+            return null;
+        return attempt;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearAppAuthAttempts() {
+    if (typeof window === "undefined")
+        return;
+    try {
+        for (const key of storedAttempts())
+            window.sessionStorage.removeItem(key);
+    }
+    catch { /* Nothing can navigate with inaccessible proof. */ }
+}
+export function appAuthNavigationUrl(attempt) {
+    const url = new URL(`/api/apps/${encodeURIComponent(attempt.appId)}/open`, attempt.coreOrigin);
+    for (const [name, value] of Object.entries(appAuthFields(attempt)))
+        url.searchParams.set(name, value);
+    return url.href;
+}
+function appAuthFields(attempt) {
+    return { redirectUri: attempt.redirectUri, state: attempt.state, codeChallenge: attempt.codeChallenge, codeChallengeMethod: "S256",
+        ...(attempt.mode === "silent" ? { prompt: "none" } : {}),
+        ...(attempt.mode === "popup" ? { responseMode: "web_message" } : {}) };
+}
+/** Constant document and DOM-built fields prevent a public URL from laundering a challenge. */
+export function submitAppAuthIntent(attempt, doc = document) {
+    doc.open();
+    doc.write('<!doctype html><html><head><meta charset="utf-8"><meta name="referrer" content="origin"><title>Connecting to Hosty</title></head><body></body></html>');
+    doc.close();
+    const policy = doc.createElement("meta");
+    policy.httpEquiv = "Content-Security-Policy";
+    // CSP host sources cannot represent IPv6 literals; the form target remains fixed to Core.
+    // Other origins permit Core and this frozen app origin through the return redirect chain.
+    const core = new URL(attempt.coreOrigin);
+    const formAction = core.hostname.startsWith("[") ? "" : `form-action ${core.origin} 'self'; `;
+    policy.content = `default-src 'none'; ${formAction}base-uri 'none'`;
+    doc.head.append(policy);
+    const form = doc.createElement("form");
+    form.method = "POST";
+    form.action = new URL(`/api/apps/${encodeURIComponent(attempt.appId)}/sign-in-intent`, attempt.coreOrigin).href;
+    for (const [name, value] of Object.entries(appAuthFields(attempt))) {
+        const input = doc.createElement("input");
+        input.type = "hidden";
+        input.name = name;
+        input.value = value;
+        form.append(input);
+    }
+    const notice = doc.createElement("p");
+    notice.textContent = "Connecting to Hosty…";
+    doc.body.append(notice, form);
+    form.submit();
+}
 /** App-only credentials. Embedded documents keep them for this tab on the app's own origin. */
 let grant = null;
 let grantRevision = 0;
 let recoveryPending = false;
+const popupCancellations = new Set();
 export const APP_SESSION_ENDED = "hosty:app-session-ended";
+export const NATIVE_APP_AUTH_RESULT = "hosty:native-auth-result";
 export const APP_GRANT_STORAGE_KEY = "hosty.auth.app-grant";
 function isEmbedded() {
     try {
@@ -44,6 +226,15 @@ export function rememberAppGrant(token) {
     }
 }
 export function forgetAppGrant() {
+    if (!grant)
+        grantRevision++;
+    discardAppGrant();
+    clearAppAuthAttempts();
+    for (const cancel of [...popupCancellations])
+        cancel();
+    cancelActivityRenewal();
+}
+function discardAppGrant() {
     if (grant)
         grantRevision++;
     grant = null;
@@ -63,7 +254,7 @@ export function forgetRejectedAppGrant(code, expectedRevision = grantRevision) {
         return false;
     if (typeof code !== "string" || !["token_invalid", "token_revoked", "token_expired", "token_app_mismatch"].includes(code))
         return false;
-    forgetAppGrant();
+    discardAppGrant();
     return true;
 }
 export function appSessionActive() { recoveryPending = false; }
@@ -90,7 +281,7 @@ export async function appFetch(input, init = {}, recover = true) {
         if (response.status !== 401)
             return response;
         if (!rejected && recover && body?.code !== "reauth_required" && current)
-            forgetAppGrant();
+            discardAppGrant();
         if (!recover)
             return response;
         if (activityConfig) {
@@ -110,37 +301,147 @@ export async function appFetch(input, init = {}, recover = true) {
     }
     return response;
 }
-/** Must be called directly from a user gesture. The popup belongs to this app frame, not Shell. */
-export function openAppSignIn(openUrl, signal) {
-    const url = new URL(openUrl);
-    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
-        return Promise.reject(new Error("Hosty sign-in URL is invalid."));
-    const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
-    url.searchParams.set("responseMode", "web_message");
-    url.searchParams.set("state", state);
+/** Refresh only the app-local, server-verified metadata for this frozen app/Core pair. */
+export async function refreshAppAuthProtocol(openUrl, probePath = "/api/auth/identity", signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+        controller.abort();
+    const timer = window.setTimeout(abort, 4_000);
+    try {
+        const open = new URL(openUrl);
+        const match = /^\/api\/apps\/([^/]+)\/open$/.exec(open.pathname);
+        if (!match || !["http:", "https:"].includes(open.protocol) || open.username || open.password)
+            return null;
+        const response = await appFetch(probePath, { cache: "no-store", signal: controller.signal }, false);
+        if (![200, 401].includes(response.status) || !response.headers.get("content-type")?.toLowerCase().startsWith("application/json"))
+            return null;
+        const body = await response.json();
+        const recovery = body?.recovery;
+        if (recovery?.appId !== decodeURIComponent(match[1]) || typeof recovery.corePublicOrigin !== "string")
+            return null;
+        const core = new URL(recovery.corePublicOrigin);
+        if (core.origin !== open.origin || core.username || core.password || core.pathname !== "/" || core.search || core.hash)
+            return null;
+        if (controller.signal.aborted)
+            return null;
+        return acceptAppAuthProtocol(open.origin, recovery.appAuthProtocol === 2 ? 2 : recovery.appAuthProtocol === 1 ? 1 : null);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        window.clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+    }
+}
+/** Must be called directly from a user gesture. Native hosts intercept before any request. */
+export function openAppSignIn(openUrl, signal, appAuthProtocol = 2, native = false, probePath = "/api/auth/identity") {
+    let initialAttempt;
+    try {
+        initialAttempt = createAppAuthAttempt(openUrl, native ? "native" : "popup", appAuthProtocol);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (native)
+        return openNativeAppSignIn(initialAttempt, signal);
     return new Promise((resolve, reject) => {
+        let attempt = initialAttempt;
+        initialAttempt = null;
         let popup = null;
         let settled = false;
+        let upgraded = false;
+        let restartPoll;
+        const refreshController = new AbortController();
         const finish = (code, error) => {
             if (settled)
                 return;
             settled = true;
+            const proof = code && attempt ? { code, codeVerifier: attempt.codeVerifier } : null;
+            attempt = null;
+            refreshController.abort();
             window.removeEventListener("message", receive);
             signal?.removeEventListener("abort", abort);
+            popupCancellations.delete(abort);
             window.clearTimeout(timer);
             clearInterval(closedCheck);
+            clearInterval(restartPoll);
             popup?.close();
-            if (code)
-                resolve(code);
+            if (proof)
+                resolve(proof);
             else
                 reject(new Error(error ?? "Sign-in was cancelled."));
         };
+        const restart = async () => {
+            // The correlated Core refusal carries no authority. The app server must verify v2
+            // before the existing gesture-opened window receives an entirely fresh attempt.
+            attempt = null;
+            if (await refreshAppAuthProtocol(openUrl, probePath, refreshController.signal) !== 2) {
+                if (!settled)
+                    finish(undefined, "Hosty sign-in protocol could not be verified. Please try again.");
+                return;
+            }
+            if (settled || !popup || popup.closed)
+                return;
+            try {
+                popup.location.href = "about:blank";
+            }
+            catch {
+                finish(undefined, "The app could not restart Hosty sign-in. Please try again.");
+                return;
+            }
+            const deadline = Date.now() + 5_000;
+            const submit = () => {
+                if (settled)
+                    return;
+                if (!popup || popup.closed) {
+                    finish();
+                    return;
+                }
+                let doc;
+                try {
+                    // Access is possible only after the app-initiated blank navigation restores
+                    // this app's origin. Never write an intent into the old Core document.
+                    doc = popup.document;
+                    if (doc.URL !== "about:blank")
+                        throw new Error("Popup is still navigating.");
+                }
+                catch {
+                    if (Date.now() >= deadline)
+                        finish(undefined, "The app could not restart Hosty sign-in. Please try again.");
+                    return;
+                }
+                clearInterval(restartPoll);
+                try {
+                    attempt = createAppAuthAttempt(openUrl, "popup", 2);
+                    submitAppAuthIntent(attempt, doc);
+                }
+                catch {
+                    finish(undefined, "The app could not restart Hosty sign-in. Please try again.");
+                }
+            };
+            restartPoll = setInterval(submit, 20);
+            submit();
+        };
         const receive = (event) => {
-            if (!popup || event.source !== popup || event.origin !== url.origin)
+            if (!popup || !attempt || event.source !== popup || event.origin !== attempt.coreOrigin)
                 return;
             const data = event.data;
-            if (data?.type !== "hosty:app-auth-code" || data.state !== state ||
-                typeof data.code !== "string" || !data.code || data.code.length > 4096)
+            if (data?.type !== "hosty:app-auth-code" || data.state !== attempt.state)
+                return;
+            if (typeof data.error === "string") {
+                if (data.error === "protocol_required" && attempt.protocol === 1 && !upgraded &&
+                    Object.keys(data).length === 3 && data.code === undefined) {
+                    upgraded = true;
+                    void restart();
+                }
+                else
+                    finish(undefined, "Hosty could not authorize this sign-in. Please try again.");
+                return;
+            }
+            if (typeof data.code !== "string" || !data.code || data.code.length > 4096)
                 return;
             finish(data.code);
         };
@@ -149,19 +450,80 @@ export function openAppSignIn(openUrl, signal) {
         const closedCheck = setInterval(() => { if (popup?.closed)
             finish(); }, 500);
         window.addEventListener("message", receive);
+        popupCancellations.add(abort);
         signal?.addEventListener("abort", abort, { once: true });
         if (signal?.aborted) {
             finish();
             return;
         }
-        popup = window.open(url.href, "_blank", "popup,width=520,height=700");
-        if (!popup)
+        // No await precedes window.open: browser activation belongs to this exact app gesture.
+        popup = window.open(appAuthProtocol === 1 ? appAuthNavigationUrl(attempt) : "about:blank", "_blank", "popup,width=520,height=700");
+        if (!popup) {
             finish(undefined, "Allow the sign-in popup and try again.");
+            return;
+        }
+        if (appAuthProtocol === 2) {
+            try {
+                submitAppAuthIntent(attempt, popup.document);
+            }
+            catch {
+                finish(undefined, "The app could not open the Hosty sign-in form. Please try again.");
+            }
+        }
+    });
+}
+/** The native host preserves this document and returns only a correlated public result. */
+function openNativeAppSignIn(attempt, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (code, error) => {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener(NATIVE_APP_AUTH_RESULT, receive);
+            signal?.removeEventListener("abort", abort);
+            popupCancellations.delete(abort);
+            window.clearTimeout(timer);
+            if (code)
+                resolve({ code, codeVerifier: attempt.codeVerifier });
+            else
+                reject(new Error(error ?? "Sign-in was cancelled."));
+        };
+        const receive = (event) => {
+            const data = event.detail;
+            if (!data || data.state !== attempt.state)
+                return;
+            if (data.error && typeof data.error.code === "string") {
+                finish(undefined, "Hosty could not authorize this sign-in. Please try again.");
+                return;
+            }
+            if (typeof data.code !== "string" || !data.code || data.code.length > 4096)
+                return;
+            finish(data.code);
+        };
+        const abort = () => finish();
+        const timer = window.setTimeout(() => finish(undefined, "Sign-in timed out. Please try again."), 180_000);
+        window.addEventListener(NATIVE_APP_AUTH_RESULT, receive);
+        popupCancellations.add(abort);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) {
+            finish();
+            return;
+        }
+        const url = new URL(appAuthNavigationUrl(attempt));
+        url.searchParams.set("responseMode", "web_message");
+        try {
+            window.location.assign(url.href);
+        }
+        catch {
+            finish(undefined, "The native host could not open Hosty sign-in. Please try again.");
+        }
     });
 }
 export const APP_ACTIVITY_RENEWED = "hosty:app-activity-renewed";
 let activityConfig = null;
 let renewal = null;
+let renewalController = null;
 const waiting = new Set();
 export function configureAppActivity(config) {
     activityConfig = config;
@@ -176,7 +538,7 @@ export function updateAppActivity(activeUntil, activityRequired) {
         activityConfig.activityRequired = activityRequired;
     }
 }
-export function cancelActivityRenewal() { for (const done of [...waiting])
+export function cancelActivityRenewal() { renewalController?.abort(); for (const done of [...waiting])
     done(false); }
 function waitForActivity(signal) {
     return new Promise(resolve => {
@@ -196,9 +558,16 @@ export function renewAppActivity() {
     const config = activityConfig;
     if (!config)
         return Promise.reject(new Error("App recovery is not configured."));
-    const popup = openAppSignIn(config.openUrl);
-    renewal = popup.then(async (code) => {
-        const result = await config.exchangeCode(code);
+    const controller = new AbortController();
+    const revision = grantRevision;
+    renewalController = controller;
+    const popup = openAppSignIn(config.openUrl, controller.signal, config.appAuthProtocol, config.native, config.probePath);
+    renewal = popup.then(async (proof) => {
+        if (config.appAuthProtocol === 1 && acceptAppAuthProtocol(new URL(config.openUrl).origin, 1) === null)
+            config.appAuthProtocol = 2;
+        const result = await config.exchangeCode(proof);
+        if (controller.signal.aborted || activityConfig !== config || revision !== grantRevision)
+            throw new Error("Sign-in was cancelled.");
         if (result.accessToken)
             rememberAppGrant(result.accessToken);
         config.activeUntil = result.activeUntil;
@@ -206,7 +575,7 @@ export function renewAppActivity() {
         for (const done of [...waiting])
             done(true);
         window.dispatchEvent(new Event(APP_ACTIVITY_RENEWED));
-    }).catch(error => { cancelActivityRenewal(); throw error; }).finally(() => { renewal = null; });
+    }).catch(error => { cancelActivityRenewal(); throw error; }).finally(() => { renewal = null; renewalController = null; });
     return renewal;
 }
 export function appActivityNeedsRenewal(now = Date.now()) {

package/dist/index.d.ts

@@ -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. */

package/dist/index.js

@@ -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

package/dist/install.d.ts

@@ -83,7 +83,7 @@ export interface InstallationSource {
             description?: string | null;
         };
     };
-    /** Personal source selection requires apps.sources as well as apps.install and Core review. */
+    /** Personal source selection requires apps.install plus apps.sources or sources.connections and Core review. */
     sourceConnections?: {
         manifestConnectionId?: string;
         gitConnectionId?: string;

package/dist/react.d.ts

@@ -50,6 +50,8 @@ export interface AppIdentityBridgeProps {
     appCodePath?: string;
     /** Optional app-owned rendering, including loading and active content. Recovery remains SDK-owned. */
     renderState?: (state: AppIdentityBridgeState) => ReactNode;
+    /** Receives a successful active probe before children mount, so an app can seed its session cache. */
+    onSession?: (body: unknown) => void;
     children?: ReactNode;
 }
 /**
@@ -60,7 +62,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, children, }?: AppIdentityBridgeProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+export declare function AppIdentityBridge({ probePath, appCodePath, renderState, onSession, children, }?: AppIdentityBridgeProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 export interface HostThemeBridgeProps {
     /**
      * Whether the operating system decides the theme while no shell has spoken — `true` unless the

package/dist/react.js

@@ -7,12 +7,12 @@ import { AppActivityBridge } from "./activity-react.js";
 import { AuthNotice, AuthNoticeButton, authNoticeActionStyle } from "./auth-notice.js";
 import { useEffect, useRef, useState } from "react";
 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_STATE_KEY = "hosty.auth.silent-state";
 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.
@@ -69,36 +69,38 @@ function writeGuard(value) {
     }
 }
 /** Both state and the per-app guard must survive navigation, or the popup is the fallback. */
-function beginSilentSignIn(openUrl, appId) {
+function beginNavigationSignIn(openUrl, appId, protocol, mode, force = false) {
+    let state = null;
     try {
-        const guardKey = `${SILENT_GUARD_PREFIX}${appId}`;
-        if (window.sessionStorage.getItem(guardKey) === "1")
-            return null;
-        const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
-        window.sessionStorage.setItem(SILENT_STATE_KEY, state);
-        window.sessionStorage.setItem(guardKey, "1");
-        if (window.sessionStorage.getItem(SILENT_STATE_KEY) !== state || window.sessionStorage.getItem(guardKey) !== "1")
-            return null;
-        const url = new URL(openUrl);
-        url.searchParams.set("prompt", "none");
-        url.searchParams.set("state", state);
-        return url.href;
-    }
-    catch {
-        return null;
-    }
-}
-function consumeSilentState(state) {
-    if (!state)
-        return false;
-    try {
-        const expected = window.sessionStorage.getItem(SILENT_STATE_KEY);
-        if (!expected || expected !== state || !/^[a-f0-9]{64}$/.test(state))
+        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.removeItem(SILENT_STATE_KEY);
+        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;
     }
 }
@@ -112,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;
     }
@@ -185,7 +187,7 @@ export function useLaunchMode() {
  * redirect through Core `/open` when standalone, and cards only in fallback/terminal states
  * — never a login UI while recovery is still running.
  */
-export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, children, } = {}) {
+export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, onSession, children, } = {}) {
     const [ui, setUi] = useState({ kind: "recovering" });
     // 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.
@@ -193,8 +195,12 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
     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);
+    const onSessionRef = useRef(onSession);
+    useEffect(() => { onSessionRef.current = onSession; }, [onSession]);
     useEffect(() => {
         let cancelled = false;
         const controller = new AbortController();
@@ -211,7 +217,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;
+            let sessionBody = null;
             const revision = appGrantRevision();
             try {
                 const response = await appFetch(probePath, {
@@ -221,14 +230,16 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 }, false);
                 const body = await response.json().catch(() => null);
                 status = readProbedSessionStatus(body);
+                if (status === "active" && !response.ok)
+                    status = null;
+                sessionBody = 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.
@@ -247,71 +258,93 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 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;
             }
-            if (initialLoad && !wasActive.current && !initialGrantPresent.current && !silentError.current &&
+            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) {
-                const silentUrl = beginSilentSignIn(openUrl, appId);
-                if (silentUrl) {
-                    window.location.replace(silentUrl);
+                if (beginNavigationSignIn(openUrl, appId, protocol, "silent", shouldUpgrade))
                     return;
-                }
             }
-            const action = !status || !appId
+            const action = !status || !appId || ((status === "not-present" || status === "expired") && !protocol)
                 ? { kind: "card", card: "unavailable" }
                 : decideRecoveryAction({
                     status: silentError.current === "login_required" ? "not-present" : status,
-                    mode: detectLaunchMode(window),
+                    mode,
                     appId,
                     openUrl,
-                    redirectAlreadyAttempted: readGuard(),
+                    redirectAlreadyAttempted: !shouldUpgrade && readGuard(),
                 });
             switch (action.kind) {
                 case "none":
+                    onSessionRef.current?.(sessionBody);
                     appSessionActive();
                     wasActive.current = true;
                     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);
-                                silentError.current = null;
-                                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" });
@@ -321,27 +354,30 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         const url = new URL(window.location.href);
         const code = url.searchParams.get("code")?.trim();
         const error = url.searchParams.get("error");
-        const embedded = detectLaunchMode(window) === "embedded";
         const isSilentError = error === "login_required" || error === "access_denied";
-        const accepted = embedded && (code || isSilentError) ? consumeSilentState(url.searchParams.get("state")) : !embedded;
-        if (embedded && accepted && isSilentError)
+        const attempt = takeAppAuthAttempt(url, true);
+        const upgradedLegacy = attempt?.protocol === 1 && acceptAppAuthProtocol(attempt.coreOrigin, 1) === null;
+        if (attempt?.mode === "silent" && isSilentError)
             silentError.current = error;
-        if (code || (embedded && isSilentError)) {
+        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");
-            if (embedded) {
-                url.searchParams.delete("state");
-                if (isSilentError)
-                    url.searchParams.delete("error");
-            }
+            url.searchParams.delete("state");
+            if (isSilentError || protocolRequired)
+                url.searchParams.delete("error");
             window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
         }
-        if (code && accepted) {
+        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",
                 }),
             };
         }
@@ -355,6 +391,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;
@@ -382,7 +425,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.20.0",
+  "version": "0.21.1",
   "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,10 +87,11 @@
     "build": "tsc -p tsconfig.build.json && node scripts/fix-dist-extensions.mjs"
   },
   "dependencies": {
+    "@noble/hashes": "^2.4.0",
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": "^16.3.6",
+    "next": "^16.3.8",
     "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
@@ -98,14 +103,14 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.19.0",
+    "@types/node": "^24.19.1",
     "@types/react": "^19.3.0",
-    "typescript": "^6",
-    "vitest": "^5.0.2",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "jsdom": "^30.1.1"
+    "typescript": "^6",
+    "vitest": "^5.0.3"
   },
   "repository": {
     "type": "git",