@hosty-sdk/app 0.18.0 → 0.19.1

package/dist/permissions-react.d.ts

@@ -0,0 +1,4 @@
+/** App-owned GET endpoint authenticates the viewer and calls readOwnPermissionNotice. */
+export declare function MissingPermissionsNotice({ endpoint }: {
+    endpoint?: string;
+}): import("react").JSX.Element | null;

package/dist/permissions-react.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { appFetch } from "./browser-auth.js";
+import { permissionNotice, requestPermissionReview } from "./permissions.js";
+/** App-owned GET endpoint authenticates the viewer and calls readOwnPermissionNotice. */
+export function MissingPermissionsNotice({ endpoint = "/api/hosty/permissions" }) {
+    const [state, setState] = useState(null);
+    const [dismissed, setDismissed] = useState(false);
+    const [pending, setPending] = useState(false);
+    useEffect(() => {
+        const controller = new AbortController();
+        let loading = false;
+        const refresh = async () => {
+            if (loading)
+                return;
+            loading = true;
+            try {
+                const response = await appFetch(endpoint, { cache: "no-store", signal: controller.signal });
+                if (!response.ok) {
+                    setState(null);
+                    return;
+                }
+                const next = await response.json();
+                if (!controller.signal.aborted) {
+                    setState(next);
+                    if (!permissionNotice(next))
+                        setPending(false);
+                }
+            }
+            catch { /* A transient failure must not erase a known setup warning. */ }
+            finally {
+                loading = false;
+            }
+        };
+        void refresh();
+        window.addEventListener("focus", refresh);
+        const timer = pending ? window.setInterval(refresh, 2000) : undefined;
+        return () => { controller.abort(); window.removeEventListener("focus", refresh); window.clearInterval(timer); };
+    }, [endpoint, pending]);
+    const kind = state && permissionNotice(state);
+    if (dismissed || !kind || !state)
+        return null;
+    return _jsxs("section", { "data-hosty-activity-control": true, role: "alert", "aria-label": "Required permissions", style: { border: "1px solid currentColor", padding: 12, margin: 8, borderRadius: 8, color: "#c2410c" }, children: [kind === "unsupported"
+                ? _jsxs("p", { children: ["Core does not support required permissions: ", state.permissions.unsupportedRequired.join(", "), ". Update the app or Core."] })
+                : _jsx("p", { children: "This app needs required permissions. Operations using them are unavailable until approval." }), kind === "missing" && state.permissions?.reviewAvailable !== false && state.corePublicOrigin &&
+                _jsx("button", { type: "button", onClick: () => { requestPermissionReview(state); setPending(true); }, children: "Request permissions" }), pending && _jsx("p", { children: "Review permissions in Core, then return here. You can leave this app installed without approving." }), _jsx("button", { type: "button", onClick: () => { setDismissed(true); setPending(false); }, style: { marginLeft: 12 }, children: "Dismiss" })] });
+}

package/dist/permissions-server.d.ts

@@ -0,0 +1,6 @@
+import { type ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+import type { PermissionNoticeState } from "./permission-types.js";
+/** Server-only: pass the role from an authenticated session, never from request input. */
+export declare function readOwnPermissionNotice(hostRole: string | null, options?: ProviderServerOptions & {
+    corePublicOrigin?: string | null;
+}, signal?: AbortSignal): Promise<PermissionNoticeState>;

package/dist/permissions-server.js

@@ -0,0 +1,13 @@
+import { ProviderClient } from "@hosty-sdk/app/providers/server";
+/** Server-only: pass the role from an authenticated session, never from request input. */
+export async function readOwnPermissionNotice(hostRole, options = {}, signal) {
+    const state = {
+        hostRole,
+        appId: options.appId ?? process.env.HOSTY_APP_ID ?? "",
+        corePublicOrigin: options.corePublicOrigin ?? process.env.HOSTY_CORE_PUBLIC_ORIGIN ?? null,
+        permissions: null,
+    };
+    if (hostRole === "host.admin")
+        state.permissions = await new ProviderClient(options).permissions(signal);
+    return state;
+}

package/dist/permissions.d.ts

@@ -0,0 +1,8 @@
+import type { PermissionNoticeState } from "./permission-types.js";
+export type { PermissionNoticeState } from "./permission-types.js";
+export declare const PERMISSION_REVIEW_REQUEST = "hosty:request-permission-review";
+/** No optional declaration, or declaration alone, confers authority. */
+export declare function permissionNotice(state: PermissionNoticeState): "missing" | "unsupported" | null;
+export declare function permissionReviewUrl(corePublicOrigin: string, appId: string): string;
+/** Invoke synchronously from a user click. The embedder determines the app from its frame. */
+export declare function requestPermissionReview(state: PermissionNoticeState, browser?: Pick<Window, "parent" | "open">): void;

package/dist/permissions.js

@@ -0,0 +1,25 @@
+export const PERMISSION_REVIEW_REQUEST = "hosty:request-permission-review";
+/** No optional declaration, or declaration alone, confers authority. */
+export function permissionNotice(state) {
+    if (state.hostRole !== "host.admin" || !state.permissions)
+        return null;
+    const p = state.permissions;
+    if (p.unsupportedRequired?.length)
+        return "unsupported";
+    return p.required.some(name => !p.granted.includes(name)) ? "missing" : null;
+}
+export function permissionReviewUrl(corePublicOrigin, appId) {
+    const core = new URL(corePublicOrigin);
+    if (!["http:", "https:"].includes(core.protocol) || core.username || core.password)
+        throw new Error("Invalid Core origin");
+    return new URL(`/install/permissions/${encodeURIComponent(appId)}`, core.origin).href;
+}
+/** Invoke synchronously from a user click. The embedder determines the app from its frame. */
+export function requestPermissionReview(state, browser = window) {
+    if (permissionNotice(state) !== "missing" || state.permissions?.reviewAvailable === false || !state.corePublicOrigin)
+        return;
+    if (browser.parent !== browser)
+        browser.parent.postMessage({ type: PERMISSION_REVIEW_REQUEST }, "*");
+    else
+        browser.open(permissionReviewUrl(state.corePublicOrigin, state.appId), "_blank", "noopener,noreferrer");
+}

package/dist/providers-server.d.ts

@@ -1,5 +1,5 @@
-import { AssistantClient } from "./assistant.js";
-import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "./providers.js";
+import { AssistantClient } from "@hosty-sdk/app/assistant";
+import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "@hosty-sdk/app/providers";
 export type ProviderServerOptions = {
     appId?: string;
     coreOrigin?: string;

package/dist/providers-server.js

@@ -1,5 +1,5 @@
-import { AssistantClient } from "./assistant.js";
-import { ProviderError } from "./providers.js";
+import { AssistantClient } from "@hosty-sdk/app/assistant";
+import { ProviderError } from "@hosty-sdk/app/providers";
 /** Server-only provider client. Its app service token must never be sent to a browser or provider. */
 export class ProviderClient {
     appId;

package/dist/providers.d.ts

@@ -15,6 +15,8 @@ export type AppPermissionState = {
     optional: string[];
     granted: string[];
     reviewAvailable?: boolean;
+    unsupportedRequired?: string[];
+    status?: string;
 };
 export type ProviderInvocation = {
     callerAppId: string;

package/dist/react.d.ts

@@ -34,6 +34,8 @@ export type AppIdentityBridgeState = {
     kind: "signin";
     openUrl: string | null;
     embedded: boolean;
+    signIn?: () => void;
+    error?: string;
 } | {
     kind: "denied";
 } | {
@@ -48,15 +50,16 @@ export interface AppIdentityBridgeProps {
     appCodePath?: string;
     /** Optional app-owned rendering, including loading and active content. Recovery remains SDK-owned. */
     renderState?: (state: AppIdentityBridgeState) => ReactNode;
+    children?: ReactNode;
 }
 /**
  * Mount once at the top of the root layout body. On first load it consumes a `?code` from
  * the URL (exchanging it for the identity cookie), then probes the session and runs the
- * recovery decision: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * recovery decision: an app-owned Core 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.
  */
-export declare function AppIdentityBridge({ probePath, appCodePath, renderState, }?: AppIdentityBridgeProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export 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 interface HostThemeBridgeProps {
     /**
      * Whether the operating system decides the theme while no shell has spoken — `true` unless the
@@ -85,3 +88,5 @@ export interface HostThemeBridgeProps {
  * choice is not overruled by the OS.
  */
 export declare function HostThemeBridge({ followSystem, onTheme }?: HostThemeBridgeProps): null;
+export { MissingPermissionsNotice } from "./permissions-react.js";
+export { AppActivityBridge } from "./activity-react.js";

package/dist/react.js

@@ -3,15 +3,15 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 // React slice: the client identity bridge — probe, silent recovery, and the fallback
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
+import { 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 { 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";
-// How long an embedded frame waits for the Shell to reissue a launch code before showing
-// the manual sign-in fallback (i.e. it is embedded by something other than Hosty Shell).
-const EMBEDDED_RECOVERY_TIMEOUT_MS = 4_000;
 // Cap the status probe so a stalled request cannot leave the bridge stuck hidden — on
 // timeout it classifies as unavailable and the user gets a Retry affordance.
 const IDENTITY_PROBE_TIMEOUT_MS = 4_000;
@@ -144,14 +144,16 @@ 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: silent `hosty:auth-required` to the Shell when embedded, a once-per-tab
+ * recovery decision: an app-owned Core 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.
  */
-export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, } = {}) {
+export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePath = "/api/auth/app-code", renderState, 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.
+    const wasActive = useRef(false);
+    const [activity, setActivity] = useState(null);
     const exchangeRef = useRef(null);
     useEffect(() => {
         let cancelled = false;
@@ -168,16 +170,19 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
             let openUrl = null;
             let appId = null;
             try {
-                const response = await fetch(probePath, {
+                const response = await appFetch(probePath, {
                     headers: { Accept: "application/json" },
                     cache: "no-store",
                     signal: probeController.signal,
-                });
+                }, false);
                 const body = await response.json().catch(() => null);
                 status = readProbedSessionStatus(body);
                 const recovery = readRecoveryParams(body);
                 appId = recovery.appId;
                 openUrl = appId ? buildCoreOpenUrl(recovery.corePublicOrigin, appId, window.location) : null;
+                const metadata = body;
+                if (!cancelled && openUrl)
+                    setActivity({ openUrl, activeUntil: metadata?.activeUntil, activityRequired: metadata?.activityRequired });
             }
             catch {
                 // A failed or timed-out probe (Core unreachable) classifies as unavailable below.
@@ -201,25 +206,33 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                 });
             switch (action.kind) {
                 case "none":
+                    appSessionActive();
+                    wasActive.current = true;
                     setUi({ kind: "active" });
                     return;
                 case "post-auth-required": {
-                    // The payload carries no secret, so targetOrigin "*" is safe — the Shell verifies
-                    // the sender before acting, and answers by swapping the iframe src.
-                    try {
-                        window.parent.postMessage(action.intent, "*");
-                    }
-                    catch {
-                        // Ignore; the timeout below still falls back to the manual sign-in card.
-                    }
-                    const timeoutId = window.setTimeout(() => {
-                        if (!cancelled) {
-                            setUi({ kind: "signin", openUrl, embedded: true });
-                        }
-                    }, EMBEDDED_RECOVERY_TIMEOUT_MS);
-                    controller.signal.addEventListener("abort", () => window.clearTimeout(timeoutId), {
-                        once: true,
-                    });
+                    const showSignIn = (error) => setUi({ kind: "signin", openUrl, embedded: true, error,
+                        signIn: openUrl ? () => {
+                            // Open synchronously in the click handler; an awaited request loses the user gesture.
+                            const result = openAppSignIn(openUrl, controller.signal);
+                            setUi({ kind: "recovering" });
+                            void result.then(async (code) => {
+                                const response = await appFetch(appCodePath, {
+                                    method: "POST", headers: { "Content-Type": "application/json" },
+                                    body: JSON.stringify({ code }),
+                                });
+                                const body = await response.json();
+                                if (!response.ok || typeof body.accessToken !== "string" || !body.accessToken)
+                                    throw new Error("Hosty could not establish this app session.");
+                                if (cancelled)
+                                    return;
+                                rememberAppGrant(body.accessToken);
+                                writeGuard(false);
+                                await probeAndRecover();
+                            }).catch(error => { if (!cancelled)
+                                showSignIn(error instanceof Error ? error.message : "Sign-in failed."); });
+                        } : undefined });
+                    showSignIn();
                     return;
                 }
                 case "redirect":
@@ -233,6 +246,11 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
                     return;
             }
         }
+        const recover = () => { if (!cancelled && !wasActive.current) {
+            setUi({ kind: "recovering" });
+            void probeAndRecover();
+        } };
+        window.addEventListener(APP_SESSION_ENDED, recover);
         const url = new URL(window.location.href);
         const code = url.searchParams.get("code")?.trim();
         if (code) {
@@ -250,13 +268,17 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         const exchange = exchangeRef.current;
         if (exchange && exchange.path === appCodePath) {
             void exchange.response
-                .then((response) => {
+                .then(async (response) => {
                 if (cancelled) {
                     return;
                 }
                 if (response.ok) {
                     writeGuard(false);
-                    window.location.reload();
+                    const body = await response.json().catch(() => null);
+                    if (typeof body?.accessToken === "string")
+                        rememberAppGrant(body.accessToken);
+                    exchangeRef.current = null;
+                    await probeAndRecover();
                 }
                 else {
                     exchangeRef.current = null;
@@ -276,43 +298,19 @@ export function AppIdentityBridge({ probePath = "/api/auth/identity", appCodePat
         return () => {
             cancelled = true;
             controller.abort();
+            window.removeEventListener(APP_SESSION_ENDED, recover);
         };
     }, [probePath, appCodePath]);
+    if (wasActive.current)
+        return _jsxs(_Fragment, { children: [activity && _jsx(AppActivityBridge, { ...activity, appCodePath: appCodePath }), renderState ? renderState({ kind: "active" }) : children] });
     if (renderState)
         return renderState(ui);
-    if (ui.kind === "recovering" || ui.kind === "active") {
-        return null;
-    }
-    return (_jsx("div", { role: "status", style: barStyle, children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: "Your Hosty session ended." }), ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: actionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), style: actionStyle, children: "Retry" })] })) }));
+    if (ui.kind === "active")
+        return children ?? null;
+    if (ui.kind === "recovering")
+        return _jsx(AuthNotice, { children: "Connecting to Hosty\u2026" });
+    return (_jsx(AuthNotice, { children: ui.kind === "signin" ? (_jsxs(_Fragment, { children: [_jsx("span", { children: ui.error ?? "Sign in through Hosty to use this app." }), ui.signIn ? _jsx(AuthNoticeButton, { onClick: ui.signIn, children: "Sign in via Hosty" }) : ui.openUrl ? (_jsx("a", { href: ui.openUrl, ...(ui.embedded ? { target: "_blank", rel: "noopener noreferrer" } : {}), style: authNoticeActionStyle, children: "Sign in via Hosty" })) : (_jsx("span", { children: "Open this app from the machine running Hosty, or configure a public origin." }))] })) : ui.kind === "denied" ? (_jsx("span", { children: "You are signed in to Hosty but are not allowed to use this app." })) : ui.kind === "misconfigured" ? (_jsx("span", { children: "This app is not configured correctly on the host. Contact the administrator." })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: "Can\u2019t reach Hosty right now." }), _jsx(AuthNoticeButton, { onClick: () => window.location.reload(), children: "Retry" })] })) }));
 }
-const barStyle = {
-    position: "fixed",
-    insetInline: 0,
-    bottom: 0,
-    zIndex: 2147483647,
-    display: "flex",
-    flexWrap: "wrap",
-    alignItems: "center",
-    justifyContent: "center",
-    gap: "0.75rem",
-    padding: "0.75rem 1rem",
-    background: "#111827",
-    color: "#f9fafb",
-    font: "500 0.875rem/1.4 system-ui, sans-serif",
-    boxShadow: "0 -1px 0 rgba(255,255,255,0.08)",
-};
-const actionStyle = {
-    display: "inline-block",
-    padding: "0.4rem 0.85rem",
-    borderRadius: "0.5rem",
-    background: "#f9fafb",
-    color: "#111827",
-    border: "none",
-    cursor: "pointer",
-    font: "inherit",
-    fontWeight: 650,
-    textDecoration: "none",
-};
 function readStoredTheme(key) {
     try {
         return window.sessionStorage.getItem(key);
@@ -411,3 +409,5 @@ export function HostThemeBridge({ followSystem = true, onTheme } = {}) {
     }, []);
     return null;
 }
+export { MissingPermissionsNotice } from "./permissions-react.js";
+export { AppActivityBridge } from "./activity-react.js";

package/dist/scoped-token.d.ts

@@ -5,6 +5,7 @@ export type ScopedTokenIntrospection = {
     sub: string;
     role: string | null;
     scopes: string[];
+    callerAppId?: string;
 } | {
     active: false;
     error?: ScopedTokenError;
@@ -40,9 +41,13 @@ export interface IntrospectScopedTokenOptions {
  * window that would take back.
  */
 export declare function introspectScopedToken(token: string, options?: IntrospectScopedTokenOptions): Promise<ScopedTokenIntrospection>;
+/** MCP handlers only. Ordinary APIs must use introspectScopedToken, which rejects MCP-only tokens. */
+export declare function introspectMcpToken(token: string, options?: IntrospectScopedTokenOptions): Promise<ScopedTokenIntrospection>;
 /** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
  * constant rather than text a caller should normalize. */
 export declare function hasScope(result: ScopedTokenIntrospection, scope: string): boolean;
 /** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
  * that introduces mutations. */
 export declare const SCOPE_MCP_READ = "mcp:read";
+/** A Core-authorized assistant may invoke MCP operations subject to the target user policy. */
+export declare const SCOPE_MCP_INVOKE = "mcp:invoke";

package/dist/scoped-token.js

@@ -20,6 +20,13 @@ const DEFAULT_TIMEOUT_MS = 2_000;
  * window that would take back.
  */
 export async function introspectScopedToken(token, options = {}) {
+    return introspect(token, options);
+}
+/** MCP handlers only. Ordinary APIs must use introspectScopedToken, which rejects MCP-only tokens. */
+export async function introspectMcpToken(token, options = {}) {
+    return introspect(token, options, "mcp");
+}
+async function introspect(token, options, purpose) {
     const appId = options.appId?.trim() || process.env.HOSTY_APP_ID?.trim();
     const serviceToken = options.serviceToken?.trim() || process.env.HOSTY_APP_SERVICE_TOKEN?.trim();
     // No fallback origin is invented when the variable is missing. Core injects HOSTY_CORE_ORIGIN
@@ -59,7 +66,7 @@ export async function introspectScopedToken(token, options = {}) {
         response = await fetch(endpoint, {
             method: "POST",
             headers: { authorization: `Bearer ${serviceToken}`, "content-type": "application/json" },
-            body: JSON.stringify({ token, ...(options.tool ? { tool: options.tool } : {}) }),
+            body: JSON.stringify({ token, ...(purpose ? { purpose } : {}), ...(options.tool ? { tool: options.tool } : {}) }),
             cache: "no-store",
             signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
         });
@@ -130,6 +137,7 @@ export async function introspectScopedToken(token, options = {}) {
         sub: body.sub,
         role: typeof body.role === "string" ? body.role : null,
         scopes: body.scopes,
+        ...(typeof body.callerAppId === "string" ? { callerAppId: body.callerAppId } : {}),
     };
 }
 /** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
@@ -140,3 +148,5 @@ export function hasScope(result, scope) {
 /** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
  * that introduces mutations. */
 export const SCOPE_MCP_READ = "mcp:read";
+/** A Core-authorized assistant may invoke MCP operations subject to the target user policy. */
+export const SCOPE_MCP_INVOKE = "mcp:invoke";

package/dist/server.d.ts

@@ -21,6 +21,8 @@ export interface HostIdentity {
     /** `mapHostRole(hostRole)` when the config provides the hook, else the raw host role. */
     appRole: string | null;
     expiresAt: string | null;
+    activeUntil?: string | null;
+    activityRequired?: boolean;
 }
 /** Structured detail for a failed resolution: the Core HTTP status (null when Core was
  * never reached) plus a machine-readable code and human-readable message. Codes pass
@@ -49,9 +51,8 @@ export type HeaderReader = {
     get(name: string): string | null;
 };
 /**
- * Reads the app identity token from a request: the app-origin cookie first (authoritative
- * when present), then the Authorization bearer fallback the browser sends when the
- * cross-site cookie is blocked, then the legacy inbound identity header.
+ * Reads an explicitly presented app grant first, then the app cookie and legacy identity header.
+ * A recovered iframe grant must not be shadowed by an older cookie.
  */
 export declare function readAppIdentityToken(headers: HeaderReader, config: HostyAppConfig): string | null;
 /** True when the effective request protocol is https (honouring the forwarded proto). */
@@ -90,6 +91,7 @@ export type AppCodeExchange = {
     ok: true;
     accessToken: string;
     expiresInSeconds: number | null;
+    activeUntil?: string | null;
 } | {
     ok: false;
     status: number;

package/dist/server.js

@@ -31,15 +31,10 @@ export function getRecoveryParams(config) {
     return { appId: getAppId(config), corePublicOrigin: getCorePublicOrigin() };
 }
 /**
- * Reads the app identity token from a request: the app-origin cookie first (authoritative
- * when present), then the Authorization bearer fallback the browser sends when the
- * cross-site cookie is blocked, then the legacy inbound identity header.
+ * Reads an explicitly presented app grant first, then the app cookie and legacy identity header.
+ * A recovered iframe grant must not be shadowed by an older cookie.
  */
 export function readAppIdentityToken(headers, config) {
-    const cookieToken = readCookie(headers.get("cookie"), config.identityCookieName);
-    if (cookieToken) {
-        return cookieToken;
-    }
     const authorization = headers.get("authorization")?.trim();
     if (authorization?.toLowerCase().startsWith("bearer ")) {
         const token = authorization.slice("bearer ".length).trim();
@@ -47,7 +42,7 @@ export function readAppIdentityToken(headers, config) {
             return token;
         }
     }
-    return headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
+    return readCookie(headers.get("cookie"), config.identityCookieName) || headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
 }
 /** True when the effective request protocol is https (honouring the forwarded proto). */
 export function isSecureRequest(headers, requestProtocol) {
@@ -200,6 +195,8 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
         hostRole,
         appRole: config.mapHostRole ? config.mapHostRole(hostRole) : hostRole,
         expiresAt,
+        activeUntil: readString(payload.activeUntil),
+        activityRequired: payload.activityRequired === true,
     };
     const expiresAtMs = expiresAt ? Date.parse(expiresAt) : Number.NaN;
     if (Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {
@@ -291,7 +288,7 @@ export async function exchangeAppCode(code) {
     const expiresInSeconds = typeof payload?.expiresInSeconds === "number" && payload.expiresInSeconds > 0
         ? payload.expiresInSeconds
         : null;
-    return { ok: true, accessToken, expiresInSeconds };
+    return { ok: true, accessToken, expiresInSeconds, activeUntil: readString(payload?.activeUntil) };
 }
 /**
  * Route-handler factory for `POST /api/auth/app-code`: exchanges the one-time `code` for
@@ -301,6 +298,14 @@ export async function exchangeAppCode(code) {
  */
 export function createAppCodeRouteHandler(config) {
     return async function POST(request) {
+        const origin = request.headers.get("origin");
+        let sameOrigin = request.headers.get("sec-fetch-site") === "same-origin";
+        try {
+            sameOrigin ||= !!origin && new URL(origin).host === (request.headers.get("host") ?? new URL(request.url).host);
+        }
+        catch { /* invalid origin */ }
+        if (!sameOrigin)
+            return jsonResponse({ code: "cross_site_request_blocked", message: "Sign-in must originate from this app." }, 403);
         let body = null;
         try {
             body = await request.json();
@@ -316,6 +321,9 @@ export function createAppCodeRouteHandler(config) {
         if (!exchange.ok) {
             return jsonResponse({ code: exchange.code, message: exchange.message }, exchange.status);
         }
+        const identity = await resolveAppSession(exchange.accessToken, config);
+        if (identity.status !== "active")
+            return jsonResponse({ code: "app_identity_rejected", message: "Core could not validate this app session." }, identity.status === "unavailable" || identity.status === "misconfigured" ? 503 : 403);
         const secure = isSecureRequest(request.headers, safeProtocol(request.url));
         const attributes = identityCookieAttributes(secure, Math.min(exchange.expiresInSeconds ?? MAX_COOKIE_AGE_SECONDS, MAX_COOKIE_AGE_SECONDS));
         const cookie = [
@@ -326,7 +334,7 @@ export function createAppCodeRouteHandler(config) {
             "HttpOnly",
             ...(attributes.secure ? ["Secure"] : []),
         ].join("; ");
-        return jsonResponse({ accessToken: exchange.accessToken, expiresInSeconds: exchange.expiresInSeconds }, 200, { "set-cookie": cookie });
+        return jsonResponse({ accessToken: exchange.accessToken, expiresInSeconds: exchange.expiresInSeconds, activeUntil: exchange.activeUntil }, 200, { "set-cookie": cookie });
     };
 }
 function safeProtocol(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -13,6 +13,10 @@
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
     },
+    "./browser-auth": {
+      "types": "./dist/browser-auth.d.ts",
+      "default": "./dist/browser-auth.js"
+    },
     "./delegated": {
       "types": "./dist/delegated.d.ts",
       "default": "./dist/delegated.js"
@@ -60,6 +64,18 @@
     "./providers/server": {
       "types": "./dist/providers-server.d.ts",
       "default": "./dist/providers-server.js"
+    },
+    "./permissions": {
+      "types": "./dist/permissions.d.ts",
+      "default": "./dist/permissions.js"
+    },
+    "./permissions/server": {
+      "types": "./dist/permissions-server.d.ts",
+      "default": "./dist/permissions-server.js"
+    },
+    "./permissions/react": {
+      "types": "./dist/permissions-react.d.ts",
+      "default": "./dist/permissions-react.js"
     }
   },
   "scripts": {
@@ -85,7 +101,11 @@
     "@types/node": "^24.19.0",
     "@types/react": "^19.3.0",
     "typescript": "^6",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1"
   },
   "repository": {
     "type": "git",