@hosty-sdk/app 0.19.1 → 0.20.0

package/dist/browser-auth.d.ts

@@ -1,6 +1,13 @@
 export declare const APP_SESSION_ENDED = "hosty:app-session-ended";
+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;
 export declare function rememberAppGrant(token: string): void;
 export declare function forgetAppGrant(): void;
+/** Snapshot the grant generation so older probes cannot invalidate a renewed identity. */
+export declare function appGrantRevision(): number;
+/** Activity expiry keeps identity; only explicit identity rejection discards the credential. */
+export declare function forgetRejectedAppGrant(code: unknown, expectedRevision?: number): boolean;
 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>;

package/dist/browser-auth.js

@@ -1,12 +1,71 @@
-/** App-only browser credentials. Never persisted or sent to an embedder. */
+/** 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;
 export const APP_SESSION_ENDED = "hosty:app-session-ended";
+export const APP_GRANT_STORAGE_KEY = "hosty.auth.app-grant";
+function isEmbedded() {
+    try {
+        return window.self !== window.top;
+    }
+    catch {
+        return true;
+    }
+}
+/** Restore before the first identity probe; standalone documents use their first-party cookie. */
+export function restoreAppGrant() {
+    if (typeof window === "undefined")
+        return false;
+    if (grant?.origin === window.location.origin)
+        return true;
+    if (!isEmbedded())
+        return false;
+    try {
+        const token = window.sessionStorage.getItem(APP_GRANT_STORAGE_KEY);
+        if (token) {
+            grant = { token, origin: window.location.origin };
+            grantRevision++;
+        }
+    }
+    catch {
+        // Blocked storage leaves the in-memory transport available.
+    }
+    return grant?.origin === window.location.origin;
+}
 export function rememberAppGrant(token) {
     grant = { token, origin: window.location.origin };
+    grantRevision++;
     recoveryPending = false;
+    if (isEmbedded()) {
+        try {
+            window.sessionStorage.setItem(APP_GRANT_STORAGE_KEY, token);
+        }
+        catch { /* In-memory fallback. */ }
+    }
+}
+export function forgetAppGrant() {
+    if (grant)
+        grantRevision++;
+    grant = null;
+    recoveryPending = false;
+    if (typeof window !== "undefined") {
+        try {
+            window.sessionStorage.removeItem(APP_GRANT_STORAGE_KEY);
+        }
+        catch { /* In-memory fallback. */ }
+    }
+}
+/** Snapshot the grant generation so older probes cannot invalidate a renewed identity. */
+export function appGrantRevision() { return grantRevision; }
+/** Activity expiry keeps identity; only explicit identity rejection discards the credential. */
+export function forgetRejectedAppGrant(code, expectedRevision = grantRevision) {
+    if (expectedRevision !== grantRevision)
+        return false;
+    if (typeof code !== "string" || !["token_invalid", "token_revoked", "token_expired", "token_app_mismatch"].includes(code))
+        return false;
+    forgetAppGrant();
+    return true;
 }
-export function forgetAppGrant() { grant = null; recoveryPending = false; }
 export function appSessionActive() { recoveryPending = false; }
 /** Use for app-local API calls, including streams. Redirects cannot carry the credential away. */
 export async function appFetch(input, init = {}, recover = true) {
@@ -20,11 +79,21 @@ export async function appFetch(input, init = {}, recover = true) {
     if (current)
         headers.set("authorization", `Bearer ${current.token}`);
     const response = await fetch(input, { ...init, headers, credentials: "same-origin", redirect: "error" });
-    if (response.status === 401 && recover && (!current || grant === current)) {
+    if ((response.status === 401 || response.status === 403) && grant === current && !init.signal?.aborted) {
+        const revision = grantRevision;
         const body = await response.clone().json().catch(() => null);
+        if (grant !== current || grantRevision !== revision || init.signal?.aborted)
+            return response;
+        // Identity probes disable recovery, but a rejected grant must still be forgotten. Activity
+        // expiry is different: the identity remains valid and the popup renews the same session.
+        const rejected = forgetRejectedAppGrant(body?.code);
+        if (response.status !== 401)
+            return response;
+        if (!rejected && recover && body?.code !== "reauth_required" && current)
+            forgetAppGrant();
+        if (!recover)
+            return response;
         if (activityConfig) {
-            if (body?.code !== "reauth_required" && current)
-                grant = null;
             const renewed = waitForActivity(init.signal);
             window.dispatchEvent(new Event(APP_SESSION_ENDED));
             // A response may arrive while the originating click still has browser activation.
@@ -35,8 +104,6 @@ export async function appFetch(input, init = {}, recover = true) {
                 return appFetch(input, init, false);
         }
         else if (!recoveryPending) {
-            if (current)
-                grant = null;
             recoveryPending = true;
             window.dispatchEvent(new Event(APP_SESSION_ENDED));
         }

package/dist/embedder.d.ts

@@ -13,7 +13,8 @@ export type AuthRequiredMessage = EmbedderMessage;
  * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
  * - the payload's `appId` must match the app the embedder actually mounted there.
  * No credential crosses the boundary in either direction: the payload is only the app id,
- * and the embedder answers by reissuing a code through its own authenticated Core call.
+ * and the app owns its direct sign-in with Core. This parser gives the embedder no authority
+ * to issue or redeem credentials for the app.
  */
 export declare function parseActiveFrameAuthRequired(event: AuthRequiredMessage, activeFrameWindow: unknown, activeFrameUrl: string, expectedAppId: string): boolean;
 /** A verified request, and the one thing its payload carries. */

package/dist/embedder.js

@@ -3,10 +3,10 @@
 // functions plus a small rate limiter — the embedder wires them to its own DOM, its own "open
 // this app" flow, and its own Core session.
 //
-// Recovery, in one sentence: on a VERIFIED `hosty:auth-required` from an app you embed,
-// re-run your normal open flow for that app (which mints a fresh launch code), rate-limited.
-// The re-open must take the full launch-code path — an "already open → reuse the URL
-// without a code" optimization must not short-circuit recovery.
+// Authentication belongs to the app frame: it restores its own per-tab grant, tries a silent
+// Core navigation on first load, and opens its own Core popup when interaction is required.
+// An embedder may observe a verified `hosty:auth-required` intent, but never carries or
+// redeems another app's code or grant.
 //
 // Delegated tokens, in one sentence: on a VERIFIED `hosty:request-delegated-token` from an app
 // you have decided to grant one, mint a token from Core with your own session and post it back
@@ -21,7 +21,8 @@ import { THEME_PARAM, THEME_PREFERENCE_PARAM } from "./theme.js";
  * - `event.origin` must match the frame URL's origin (the app itself, not an inner frame);
  * - the payload's `appId` must match the app the embedder actually mounted there.
  * No credential crosses the boundary in either direction: the payload is only the app id,
- * and the embedder answers by reissuing a code through its own authenticated Core call.
+ * and the app owns its direct sign-in with Core. This parser gives the embedder no authority
+ * to issue or redeem credentials for the app.
  */
 export function parseActiveFrameAuthRequired(event, activeFrameWindow, activeFrameUrl, expectedAppId) {
     if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {

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
@@ -126,8 +126,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 +136,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 +160,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
@@ -152,9 +152,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 +240,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 { 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.
 const IDENTITY_PROBE_TIMEOUT_MS = 4_000;
@@ -66,6 +68,40 @@ 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 beginSilentSignIn(openUrl, appId) {
+    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))
+            return false;
+        window.sessionStorage.removeItem(SILENT_STATE_KEY);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function readStoredLaunchMode() {
     try {
         return window.sessionStorage.getItem(LAUNCH_MODE_STORAGE_KEY);
@@ -144,7 +180,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 +190,16 @@ 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 [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 +211,8 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             let status = null;
             let openUrl = null;
             let appId = null;
+            let rejectionCode;
+            const revision = appGrantRevision();
             try {
                 const response = await appFetch(probePath, {
                     headers: { Accept: "application/json" },
@@ -177,6 +221,8 @@ 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;
@@ -195,10 +241,30 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             if (cancelled) {
                 return;
             }
+            if (revision !== appGrantRevision()) {
+                initialGrantPresent.current ||= restoreAppGrant();
+                void probeAndRecover();
+                return;
+            }
+            forgetRejectedAppGrant(rejectionCode, revision);
+            const initialLoad = firstProbe.current;
+            firstProbe.current = false;
+            if (silentError.current === "access_denied") {
+                setUi({ kind: "denied" });
+                return;
+            }
+            if (initialLoad && !wasActive.current && !initialGrantPresent.current && !silentError.current &&
+                detectLaunchMode(window) === "embedded" && (status === "not-present" || status === "expired") && appId && openUrl) {
+                const silentUrl = beginSilentSignIn(openUrl, appId);
+                if (silentUrl) {
+                    window.location.replace(silentUrl);
+                    return;
+                }
+            }
             const action = !status || !appId
                 ? { kind: "card", card: "unavailable" }
                 : decideRecoveryAction({
-                    status,
+                    status: silentError.current === "login_required" ? "not-present" : status,
                     mode: detectLaunchMode(window),
                     appId,
                     openUrl,
@@ -227,6 +293,7 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                                 if (cancelled)
                                     return;
                                 rememberAppGrant(body.accessToken);
+                                silentError.current = null;
                                 writeGuard(false);
                                 await probeAndRecover();
                             }).catch(error => { if (!cancelled)
@@ -253,9 +320,22 @@ 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 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)
+            silentError.current = error;
+        if (code || (embedded && isSilentError)) {
             url.searchParams.delete("code");
+            if (embedded) {
+                url.searchParams.delete("state");
+                if (isSilentError)
+                    url.searchParams.delete("error");
+            }
             window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+        }
+        if (code && accepted) {
             exchangeRef.current = {
                 path: appCodePath,
                 response: fetch(appCodePath, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",