@hosty-sdk/app 0.1.2 → 0.5.0

package/README.md

@@ -11,7 +11,7 @@ npm install @hosty-sdk/app
 | Entry | Runtime | Contents |
 | --- | --- | --- |
 | `@hosty-sdk/app` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` schema, URL/env helpers |
-| `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory |
+| `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory, the app secrets client |
 | `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, silent recovery, fallback cards |
 | `@hosty-sdk/app/embedder` | client | verified `hosty:auth-required` responder for anything that embeds Hosty apps |
 
@@ -32,6 +32,20 @@ export const POST = createAppCodeRouteHandler({
 });
 ```
 
+App secrets — the Core-managed keychain for runtime-acquired credentials (OAuth tokens and the
+like), kept by Core outside the app's backed-up data directory:
+
+```ts
+import { getAppSecret, setAppSecret } from "@hosty-sdk/app/server";
+
+// null means no secret is stored — an expected "reconnect required" state, not an error.
+const tokens = await getAppSecret("trakt.connection.1.tokens", config);
+await setAppSecret("trakt.connection.1.tokens", refreshed, config);
+```
+
+Reads are served from a write-through cache, namespaced by Core origin and app id; pass
+`{ refresh: true }` to force a live read.
+
 The design contract lives in the Hosty repository:
 [`docs/ideas/hosty-app-sdk.md`](https://github.com/alex-de-haas/docker-host/blob/main/docs/ideas/hosty-app-sdk.md).
 

package/dist/index.d.ts

@@ -62,12 +62,81 @@ export interface PageLocation {
  * (`redirect_uri_invalid`), and it would not survive the server redirect anyway.
  */
 export declare function buildCoreOpenUrl(corePublicOrigin: string | null, appId: string, location: PageLocation): string | null;
-/** Launch mode drives the logout affordance: embedded apps hide logout entirely (the
- * session belongs to the Shell), standalone apps may show one. `window.self !== window.top`
- * is the baseline signal; a Core-reported launch channel can replace it later without
- * changing callers. */
-export type AppLaunchMode = "embedded" | "standalone";
-export declare function detectLaunchMode(win: Pick<Window, "self" | "top">): AppLaunchMode;
+/**
+ * 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.
+ * - `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.
+ * - `standalone` — a plain browser tab on the app's own origin. Nothing else renders navigation
+ *   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.
+ */
+export type AppLaunchMode = "embedded" | "native" | "standalone";
+/** The query parameter a shell appends to the launch URL to declare the mode. */
+export declare const LAUNCH_MODE_PARAM = "hosty_launch";
+/** Where a resolved mode is kept for the life of the tab or web view. */
+export declare const LAUNCH_MODE_STORAGE_KEY = "hosty.launch.mode";
+/** The root attribute the launch bridge writes; CSS hides duplicated chrome off it. */
+export declare const LAUNCH_MODE_ATTRIBUTE = "data-hosty-launch";
+/**
+ * Marks an element that duplicates chrome a shell already renders — the app's own name and the
+ * navigation between its manifest pages. Contextual controls and information a shell does not
+ * render (a project picker, a refresh action, an identity badge) are not chrome in this sense
+ * and must not carry it.
+ */
+export declare const SHELL_DUPLICATED_CHROME_CLASS = "hosty-shell-chrome";
+export declare function normalizeLaunchMode(value: unknown): AppLaunchMode | null;
+/**
+ * The structural signal: is this document framed? It can only ever answer `embedded` or
+ * `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.
+ */
+export declare function detectLaunchMode(win: Pick<Window, "self" | "top">): Exclude<AppLaunchMode, "native">;
+export interface LaunchModeResolution {
+    mode: AppLaunchMode;
+    /** True when the mode came from the URL parameter, and so is worth persisting for this tab. */
+    fromParam: boolean;
+}
+/**
+ * Resolves the launch mode with explicit precedence: the URL parameter a shell just sent, then
+ * the value persisted for this tab, then the structural heuristic.
+ *
+ * An unrecognized parameter value is ignored rather than honoured or stored — a newer shell must
+ * degrade an older app to its previous behavior, never to a mode it cannot render.
+ */
+export declare function resolveLaunchMode(input: {
+    param?: string | null;
+    stored?: string | null;
+    heuristic: AppLaunchMode;
+}): LaunchModeResolution;
+/**
+ * True when a shell around this app already renders its name and page navigation, so the app's
+ * own copies are duplication. False for `standalone`, where nothing else renders them.
+ */
+export declare function hidesAppChrome(mode: AppLaunchMode): boolean;
+/**
+ * The pre-hydration bootstrap: sets the root attribute from the same precedence
+ * `resolveLaunchMode` implements, so chrome that a shell duplicates is never painted before
+ * React can hide it. Mount it as an inline `<script>` in the document head.
+ *
+ * It deliberately does not clean the parameter out of the URL — that is `HostLaunchBridge`'s
+ * job, on the same reasoning the theme bridges clean theirs from an effect rather than from
+ * their bootstrap: a `history.replaceState` before hydration is a router's business, not a
+ * paint-blocking script's.
+ */
+export declare const launchModeBootstrapScript: string;
 /**
  * The recovery decision: state × launch mode → what the app should do, per the UX
  * contract (Core `/login` is the only auth UI in the system; apps render no login UI and

package/dist/index.js

@@ -72,6 +72,31 @@ export function buildCoreOpenUrl(corePublicOrigin, appId, location) {
     target.searchParams.set("redirectUri", `${location.origin}${location.pathname}${location.search}`);
     return target.toString();
 }
+/** The query parameter a shell appends to the launch URL to declare the mode. */
+export const LAUNCH_MODE_PARAM = "hosty_launch";
+/** Where a resolved mode is kept for the life of the tab or web view. */
+export const LAUNCH_MODE_STORAGE_KEY = "hosty.launch.mode";
+/** The root attribute the launch bridge writes; CSS hides duplicated chrome off it. */
+export const LAUNCH_MODE_ATTRIBUTE = "data-hosty-launch";
+/**
+ * Marks an element that duplicates chrome a shell already renders — the app's own name and the
+ * navigation between its manifest pages. Contextual controls and information a shell does not
+ * render (a project picker, a refresh action, an identity badge) are not chrome in this sense
+ * and must not carry it.
+ */
+export const SHELL_DUPLICATED_CHROME_CLASS = "hosty-shell-chrome";
+export function normalizeLaunchMode(value) {
+    return value === "embedded" || value === "native" || value === "standalone" ? value : null;
+}
+/**
+ * The structural signal: is this document framed? It can only ever answer `embedded` or
+ * `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.
+ */
 export function detectLaunchMode(win) {
     try {
         return win.self !== win.top ? "embedded" : "standalone";
@@ -82,6 +107,65 @@ export function detectLaunchMode(win) {
         return "embedded";
     }
 }
+/**
+ * Resolves the launch mode with explicit precedence: the URL parameter a shell just sent, then
+ * the value persisted for this tab, then the structural heuristic.
+ *
+ * An unrecognized parameter value is ignored rather than honoured or stored — a newer shell must
+ * degrade an older app to its previous behavior, never to a mode it cannot render.
+ */
+export function resolveLaunchMode(input) {
+    const declared = normalizeLaunchMode(input.param);
+    if (declared) {
+        return { mode: declared, fromParam: true };
+    }
+    const stored = normalizeLaunchMode(input.stored);
+    return { mode: stored ?? input.heuristic, fromParam: false };
+}
+/**
+ * True when a shell around this app already renders its name and page navigation, so the app's
+ * own copies are duplication. False for `standalone`, where nothing else renders them.
+ */
+export function hidesAppChrome(mode) {
+    return mode !== "standalone";
+}
+/**
+ * The pre-hydration bootstrap: sets the root attribute from the same precedence
+ * `resolveLaunchMode` implements, so chrome that a shell duplicates is never painted before
+ * React can hide it. Mount it as an inline `<script>` in the document head.
+ *
+ * It deliberately does not clean the parameter out of the URL — that is `HostLaunchBridge`'s
+ * job, on the same reasoning the theme bridges clean theirs from an effect rather than from
+ * their bootstrap: a `history.replaceState` before hydration is a router's business, not a
+ * paint-blocking script's.
+ */
+export const launchModeBootstrapScript = `
+(() => {
+  const attribute = ${JSON.stringify(LAUNCH_MODE_ATTRIBUTE)};
+  const storageKey = ${JSON.stringify(LAUNCH_MODE_STORAGE_KEY)};
+  const known = ["embedded", "native", "standalone"];
+  const normalize = (value) => (known.indexOf(value) >= 0 ? value : null);
+  try {
+    const param = normalize(new URLSearchParams(window.location.search).get(${JSON.stringify(LAUNCH_MODE_PARAM)}));
+    let stored = null;
+    try {
+      stored = normalize(window.sessionStorage.getItem(storageKey));
+    } catch {}
+    let heuristic;
+    try {
+      heuristic = window.self !== window.top ? "embedded" : "standalone";
+    } catch {
+      heuristic = "embedded";
+    }
+    document.documentElement.setAttribute(attribute, param || stored || heuristic);
+    if (param) {
+      try {
+        window.sessionStorage.setItem(storageKey, param);
+      } catch {}
+    }
+  } catch {}
+})();
+`;
 export function decideRecoveryAction(input) {
     const { status, mode, appId, openUrl, redirectAlreadyAttempted } = input;
     if (status === "active") {
@@ -97,6 +181,11 @@ export function decideRecoveryAction(input) {
         return { kind: "card", card: "misconfigured" };
     }
     // expired / not-present — the recoverable pair.
+    //
+    // `embedded` is the only mode with a parent to ask. `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.
     if (mode === "embedded") {
         return { kind: "post-auth-required", intent: createAuthRequiredIntent(appId) };
     }

package/dist/react.d.ts

@@ -1,10 +1,29 @@
-import { type AppSessionStatus } from "./index.js";
+import { type AppLaunchMode, type AppSessionStatus } from "./index.js";
 /**
  * Tolerant probe reader: accepts both identity-route shapes in the fleet — a top-level
  * `status` (marketplace/telemetry) and a nested `appSession.status` (demo-app,
  * project-manager). The legacy `error` status maps to `unavailable` (transient).
  */
 export declare function readProbedSessionStatus(body: unknown): AppSessionStatus | null;
+/**
+ * Mount once in the root layout. Applies the resolved launch mode to `<html>` as
+ * `data-hosty-launch`, persists a mode the shell declared, and cleans the parameter out of the
+ * URL so a copied link cannot carry a shell's presentation into a plain browser tab.
+ *
+ * Pair it with `launchModeBootstrapScript` in the head: this effect runs after first paint, so
+ * without the script an app's own header is painted for a frame before it is hidden. Where that
+ * matters most is the native web view, which shows first paint directly — the browser Shell
+ * fades its iframe in on load and masks it.
+ */
+export declare function HostLaunchBridge(): null;
+/**
+ * The resolved launch mode, for logic that needs it — `null` until the first client effect.
+ *
+ * Rendering off this value costs a frame and risks a hydration mismatch, which is why chrome is
+ * hidden with CSS keyed on the root attribute instead. Reach for the hook only where CSS cannot
+ * express the decision.
+ */
+export declare function useLaunchMode(): AppLaunchMode | null;
 export interface AppIdentityBridgeProps {
     /** Probe endpoint returning a session status + recovery params. */
     probePath?: string;

package/dist/react.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
 import { useEffect, useState } from "react";
-import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, readRecoveryParams, } from "./index.js";
+import { buildCoreOpenUrl, decideRecoveryAction, detectLaunchMode, normalizeLaunchMode, readRecoveryParams, resolveLaunchMode, LAUNCH_MODE_ATTRIBUTE, LAUNCH_MODE_PARAM, LAUNCH_MODE_STORAGE_KEY, } from "./index.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";
@@ -65,6 +65,81 @@ function writeGuard(value) {
         // sessionStorage may be blocked; recovery still works, only the guard is lost.
     }
 }
+function readStoredLaunchMode() {
+    try {
+        return window.sessionStorage.getItem(LAUNCH_MODE_STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+}
+/** 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));
+    if (applied) {
+        return applied;
+    }
+    return resolveLaunchMode({
+        param: new URL(window.location.href).searchParams.get(LAUNCH_MODE_PARAM),
+        stored: readStoredLaunchMode(),
+        heuristic: detectLaunchMode(window),
+    }).mode;
+}
+/**
+ * Mount once in the root layout. Applies the resolved launch mode to `<html>` as
+ * `data-hosty-launch`, persists a mode the shell declared, and cleans the parameter out of the
+ * URL so a copied link cannot carry a shell's presentation into a plain browser tab.
+ *
+ * Pair it with `launchModeBootstrapScript` in the head: this effect runs after first paint, so
+ * without the script an app's own header is painted for a frame before it is hidden. Where that
+ * matters most is the native web view, which shows first paint directly — the browser Shell
+ * fades its iframe in on load and masks it.
+ */
+export function HostLaunchBridge() {
+    useEffect(() => {
+        const url = new URL(window.location.href);
+        const param = url.searchParams.get(LAUNCH_MODE_PARAM);
+        const { mode, fromParam } = resolveLaunchMode({
+            param,
+            stored: readStoredLaunchMode(),
+            heuristic: detectLaunchMode(window),
+        });
+        document.documentElement.setAttribute(LAUNCH_MODE_ATTRIBUTE, mode);
+        if (fromParam) {
+            try {
+                window.sessionStorage.setItem(LAUNCH_MODE_STORAGE_KEY, mode);
+            }
+            catch {
+                // sessionStorage may be blocked. The shell re-declares the mode on every launch and on
+                // every page switch it drives, so only app-internal navigation loses it.
+            }
+        }
+        // Cleaned whenever it is present, including an unrecognized value: a parameter this app
+        // ignored must not survive into a link someone copies.
+        if (url.searchParams.has(LAUNCH_MODE_PARAM)) {
+            url.searchParams.delete(LAUNCH_MODE_PARAM);
+            window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+        }
+    }, []);
+    return null;
+}
+/**
+ * The resolved launch mode, for logic that needs it — `null` until the first client effect.
+ *
+ * Rendering off this value costs a frame and risks a hydration mismatch, which is why chrome is
+ * hidden with CSS keyed on the root attribute instead. Reach for the hook only where CSS cannot
+ * express the decision.
+ */
+export function useLaunchMode() {
+    const [mode, setMode] = useState(null);
+    useEffect(() => {
+        // Effects run child-first, so a consumer deeper in the tree runs before `HostLaunchBridge`
+        // has applied the attribute. Resolving here rather than only reading the attribute makes the
+        // hook correct in either order.
+        setMode(currentLaunchMode());
+    }, []);
+    return mode;
+}
 /**
  * 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

package/dist/server.d.ts

@@ -22,11 +22,21 @@ export interface HostIdentity {
     appRole: string | null;
     expiresAt: string | null;
 }
+/** 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
+ * through from Core's error body where one exists; classification never branches on them
+ * (decision 10) — they exist for diagnostics and API responses. */
+export interface ResolutionError {
+    status: number | null;
+    code: string;
+    message: string;
+}
 export type AppSessionResolution = {
     status: "active";
     identity: HostIdentity;
 } | {
     status: AppSessionFailureStatus;
+    error?: ResolutionError;
 };
 export declare function getAppId(config: HostyAppConfig): string;
 export declare function getCoreOrigin(): string | null;
@@ -96,3 +106,32 @@ export declare function exchangeAppCode(code: string): Promise<AppCodeExchange>;
  * Framework-agnostic (Web `Request`/`Response`), usable directly as a Next route handler.
  */
 export declare function createAppCodeRouteHandler(config: HostyAppConfig): (request: Request) => Promise<Response>;
+/** Thrown when the secrets store could not be reached or rejected a request. A *missing* secret
+ * is not an error — {@link getAppSecret} returns null for that. */
+export declare class HostySecretsError extends Error {
+    /** Core's HTTP status, or null when Core was never reached. */
+    readonly status: number | null;
+    /** Machine-readable code from Core's error body, or a local code when Core was unreachable. */
+    readonly code: string;
+    constructor(message: string, status: number | null, code: string);
+}
+/** Test hook: the cache is process-global by design (route handlers are stateless). */
+export declare function clearAppSecretsCache(): void;
+/**
+ * Reads a secret from the app's Core-managed store. Returns `null` when no secret is stored under
+ * the key — an expected state (never connected, or the app was reinstalled on a new host), which
+ * callers should treat as "reconnect required" rather than an error.
+ *
+ * Served from a write-through cache unless `refresh` is set.
+ */
+export declare function getAppSecret(key: string, config: HostyAppConfig, options?: {
+    refresh?: boolean;
+}): Promise<string | null>;
+/** Stores (or replaces) a secret. Throws {@link HostySecretsError} when Core rejects the value
+ * (malformed key, empty/oversize value, per-app key limit) or is unreachable. */
+export declare function setAppSecret(key: string, value: string, config: HostyAppConfig): Promise<void>;
+/** Deletes a secret. Deleting an absent key succeeds. */
+export declare function deleteAppSecret(key: string, config: HostyAppConfig): Promise<void>;
+/** Lists the keys this app has stored. Always a live read — Core never returns values here, and
+ * the cache only knows the keys this process has touched. */
+export declare function listAppSecretKeys(config: HostyAppConfig): Promise<string[]>;

package/dist/server.js

@@ -91,7 +91,12 @@ export async function resolveAppSession(token, config) {
     const serviceToken = getServiceToken();
     const coreOrigin = getCoreOrigin();
     if (!serviceToken || !coreOrigin) {
-        return { status: "misconfigured" };
+        return {
+            status: "misconfigured",
+            error: serviceToken
+                ? { status: null, code: "core_origin_missing", message: "HOSTY_CORE_ORIGIN is not configured." }
+                : { status: null, code: "app_service_token_missing", message: "HOSTY_APP_SERVICE_TOKEN is not configured." },
+        };
     }
     const now = Date.now();
     const cached = revalidationCache.get(token);
@@ -120,7 +125,10 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
         endpoint = new URL("/api/auth/apps/revalidate", coreOrigin).toString();
     }
     catch {
-        return { status: "misconfigured" };
+        return {
+            status: "misconfigured",
+            error: { status: null, code: "core_origin_invalid", message: "HOSTY_CORE_ORIGIN is not a valid URL." },
+        };
     }
     let response;
     try {
@@ -135,12 +143,28 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
             signal: AbortSignal.timeout(CORE_AUTH_TIMEOUT_MS),
         });
     }
-    catch {
+    catch (error) {
         // Network failure or timeout — transient either way; never cached.
-        return { status: "unavailable" };
+        const timeout = error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError");
+        return {
+            status: "unavailable",
+            error: {
+                status: null,
+                code: timeout ? "core_revalidation_timeout" : "app_session_revalidation_error",
+                message: error instanceof Error ? error.message : "Core identity revalidation failed.",
+            },
+        };
     }
     if (!response.ok) {
-        return { status: classifyRevalidationHttpStatus(response.status) };
+        const body = (await response.json().catch(() => null));
+        return {
+            status: classifyRevalidationHttpStatus(response.status),
+            error: {
+                status: response.status,
+                code: readErrorField(body, "code") ?? "app_session_revalidation_failed",
+                message: readErrorField(body, "message") ?? `Core revalidation returned HTTP ${response.status}.`,
+            },
+        };
     }
     let payload;
     try {
@@ -148,12 +172,18 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
     }
     catch {
         // A non-JSON / truncated body means the session is unverifiable, not proof it is invalid.
-        return { status: "unavailable" };
+        return {
+            status: "unavailable",
+            error: { status: response.status, code: "core_response_invalid", message: "Core returned an unreadable revalidation body." },
+        };
     }
     const appId = readString(payload?.appId);
     if (appId && appId !== getAppId(config)) {
         // A token minted for a different app is Core's token_app_mismatch — terminal, like 403.
-        return { status: "forbidden" };
+        return {
+            status: "forbidden",
+            error: { status: response.status, code: "app_identity_app_mismatch", message: "Identity token was issued for a different app." },
+        };
     }
     const userId = readString(payload?.userId);
     // An "active" grant without a subject is unusable; classify it as recoverable so a probe
@@ -329,6 +359,195 @@ function readCookie(cookieHeader, name) {
     }
     return null;
 }
+function readErrorField(payload, field) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const nested = payload.error;
+    if (nested && typeof nested === "object") {
+        return readString(nested[field]);
+    }
+    return readString(payload[field]);
+}
 function readString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : null;
 }
+// ---------------------------------------------------------------------------
+// App secrets — the Core-managed keychain for runtime-acquired credentials.
+// ---------------------------------------------------------------------------
+// Secrets are small and Core is local, but a stalled call must not hold a route open. Slightly
+// more generous than the auth budget: a secret read blocks real work, not just a session check.
+const CORE_SECRETS_TIMEOUT_MS = 3_000;
+/** Thrown when the secrets store could not be reached or rejected a request. A *missing* secret
+ * is not an error — {@link getAppSecret} returns null for that. */
+export class HostySecretsError extends Error {
+    /** Core's HTTP status, or null when Core was never reached. */
+    status;
+    /** Machine-readable code from Core's error body, or a local code when Core was unreachable. */
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = "HostySecretsError";
+        this.status = status;
+        this.code = code;
+    }
+}
+// Write-through cache, process-global like the revalidation cache above: reads populate it,
+// mutations update it, so a briefly unavailable Core does not break an app that already read its
+// secret. Values are only ever what this process wrote or fetched, so no invalidation is needed.
+// Unbounded is fine here (unlike the token cache): keys are the app's own, and Core caps them at
+// 256 per app.
+//
+// Entries are namespaced by Core origin + effective app id, not by the bare secret name: the app
+// id comes from the environment with a per-config fallback, so one process can legitimately serve
+// more than one identity (multi-tenant hosting, or tests reusing the process). Sharing a cache
+// slot across identities would hand app B a value that only app A's service token could fetch,
+// silently bypassing the isolation Core enforces.
+const secretsCache = new Map();
+// Per-entry mutation counter. A read samples it before calling Core and only writes its result
+// back if it has not changed: without this a GET issued before a set/delete but completing after
+// it would overwrite the newer state, and later cached reads would serve the stale credential
+// (or a stale miss) until someone passed `refresh`.
+const secretsMutations = new Map();
+/** Test hook: the cache is process-global by design (route handlers are stateless). */
+export function clearAppSecretsCache() {
+    secretsCache.clear();
+    secretsMutations.clear();
+}
+function secretsCacheKey(key, config) {
+    // NUL cannot appear in an origin, an app id, or a Core-accepted secret key, so it is an
+    // unambiguous separator.
+    return `${getCoreOrigin() ?? ""}\u0000${getAppId(config)}\u0000${key}`;
+}
+function recordSecretMutation(cacheKey, value) {
+    secretsMutations.set(cacheKey, (secretsMutations.get(cacheKey) ?? 0) + 1);
+    secretsCache.set(cacheKey, value);
+}
+/**
+ * Reads a secret from the app's Core-managed store. Returns `null` when no secret is stored under
+ * the key — an expected state (never connected, or the app was reinstalled on a new host), which
+ * callers should treat as "reconnect required" rather than an error.
+ *
+ * Served from a write-through cache unless `refresh` is set.
+ */
+export async function getAppSecret(key, config, options) {
+    const cacheKey = secretsCacheKey(key, config);
+    if (!options?.refresh && secretsCache.has(cacheKey)) {
+        return secretsCache.get(cacheKey) ?? null;
+    }
+    const generation = secretsMutations.get(cacheKey) ?? 0;
+    const response = await secretsFetch("GET", key, config, undefined);
+    let value = null;
+    if (response !== null) {
+        // Deliberately not readString: a secret is opaque bytes, so trimming it would corrupt a value
+        // whose whitespace is significant. Core stores and returns it verbatim.
+        const raw = (await readJsonOrThrow(response))?.value;
+        if (typeof raw !== "string") {
+            // A 200 without a usable value is a broken Core/proxy, not an absent secret; reporting it
+            // as "no value" would send the app into a reconnect loop instead of surfacing the fault.
+            throw new HostySecretsError("Core returned a secret response without a value.", response.status, "core_response_invalid");
+        }
+        value = raw;
+    }
+    // Skip the cache write when a set/delete landed while this read was in flight: its state is
+    // newer than ours, and overwriting it would serve the stale value to every later reader.
+    if ((secretsMutations.get(cacheKey) ?? 0) === generation) {
+        secretsCache.set(cacheKey, value);
+    }
+    return value;
+}
+/** Stores (or replaces) a secret. Throws {@link HostySecretsError} when Core rejects the value
+ * (malformed key, empty/oversize value, per-app key limit) or is unreachable. */
+export async function setAppSecret(key, value, config) {
+    await secretsFetch("PUT", key, config, JSON.stringify({ value }));
+    recordSecretMutation(secretsCacheKey(key, config), value);
+}
+/** Deletes a secret. Deleting an absent key succeeds. */
+export async function deleteAppSecret(key, config) {
+    await secretsFetch("DELETE", key, config, undefined);
+    recordSecretMutation(secretsCacheKey(key, config), null);
+}
+/** Lists the keys this app has stored. Always a live read — Core never returns values here, and
+ * the cache only knows the keys this process has touched. */
+export async function listAppSecretKeys(config) {
+    // Only a per-key GET can resolve to null (an absent secret); the collection route throws instead.
+    const response = await secretsFetch("GET", null, config, undefined);
+    const payload = response === null ? null : (await readJsonOrThrow(response));
+    if (!Array.isArray(payload?.keys)) {
+        // Same reasoning as a valueless secret response: an unusable 200 is a fault to surface, not
+        // an app that happens to have stored nothing.
+        throw new HostySecretsError("Core returned a secret listing without a keys array.", response?.status ?? null, "core_response_invalid");
+    }
+    return payload.keys.filter((entry) => typeof entry === "string");
+}
+// Returns null only for a GET whose key is absent (404), which callers translate to "no value";
+// every other non-2xx throws. A null key targets the collection route.
+async function secretsFetch(method, key, config, body) {
+    const serviceToken = getServiceToken();
+    const coreOrigin = getCoreOrigin();
+    if (!serviceToken || !coreOrigin) {
+        throw new HostySecretsError(serviceToken ? "HOSTY_CORE_ORIGIN is not configured." : "HOSTY_APP_SERVICE_TOKEN is not configured.", null, serviceToken ? "core_origin_missing" : "app_service_token_missing");
+    }
+    const appId = getAppId(config);
+    const path = key === null
+        ? `/api/internal/apps/${encodeURIComponent(appId)}/secrets`
+        : `/api/internal/apps/${encodeURIComponent(appId)}/secrets/${encodeURIComponent(key)}`;
+    let endpoint;
+    try {
+        endpoint = new URL(path, coreOrigin).toString();
+    }
+    catch {
+        throw new HostySecretsError("HOSTY_CORE_ORIGIN is not a valid URL.", null, "core_origin_invalid");
+    }
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method,
+            headers: {
+                authorization: `Bearer ${serviceToken}`,
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            body,
+            cache: "no-store",
+            signal: AbortSignal.timeout(CORE_SECRETS_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const timeout = error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError");
+        throw new HostySecretsError(error instanceof Error ? error.message : "The app secrets request to Core failed.", null, timeout ? "core_secrets_timeout" : "core_secrets_unavailable");
+    }
+    if (response.ok) {
+        return response;
+    }
+    const payload = (await readJson(response));
+    // Core answers 404 on a per-key GET in two distinct cases, and only one is an answer: no secret
+    // stored under the key (`app_secret_not_found`) versus the routed app being unknown or removed
+    // (`app_not_found`). Collapsing them would report a removed app as a routine reconnect.
+    if (method === "GET" &&
+        key !== null &&
+        response.status === 404 &&
+        readErrorField(payload, "code") !== "app_not_found") {
+        return null;
+    }
+    throw new HostySecretsError(readErrorField(payload, "message") ?? `Core returned HTTP ${response.status} for an app secrets request.`, response.status, readErrorField(payload, "code") ?? "app_secrets_request_failed");
+}
+// Lenient: used only for error bodies, where a missing code/message costs nothing.
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+// Strict: on a 2xx an unparseable body means Core or something in front of it is broken, and
+// degrading that to "no secret" / "no keys" would hide the fault behind a plausible-looking
+// answer. Mirrors the .NET client and the revalidation path's core_response_invalid outcome.
+async function readJsonOrThrow(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new HostySecretsError("Core returned an unreadable app secrets response.", response.status, "core_response_invalid");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.1.2",
+  "version": "0.5.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -30,8 +30,8 @@
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": ">=16",
-    "react": ">=19"
+    "next": "^16.2.10",
+    "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -42,10 +42,10 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5",
-    "vitest": "^4",
     "@types/node": "^24",
-    "@types/react": "^19"
+    "@types/react": "^19.2.18",
+    "typescript": "^6",
+    "vitest": "^4"
   },
   "repository": {
     "type": "git",