@hosty-sdk/app 0.2.0 → 0.6.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,32 @@ 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.
+
+Delegated tokens — the credential a browser client (Shell) presents when calling a system
+app's API directly. Core signs them (ECDSA P-256, 5-minute TTL) and injects the verification
+key as `HOSTY_DELEGATED_TOKEN_PUBLIC_KEY`, so validation is fully local — no Core round-trip:
+
+```ts
+import { validateDelegatedToken } from "@hosty-sdk/app/server";
+
+// null for anything invalid (bad signature, wrong audience, expired) — treat like a missing token.
+const claims = validateDelegatedToken(bearerToken);
+if (claims?.role !== "host.admin") { /* 401/403 */ }
+```
+
 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/delegated.d.ts

@@ -0,0 +1,23 @@
+export interface DelegatedTokenClaims {
+    /** Acting Host user id. */
+    sub: string;
+    /** The actor's Host role at issuance (e.g. "host.admin"); gate admin surfaces on it. */
+    role: string;
+    /** Audience app id — must equal this app's own id. */
+    aud: string;
+    iat: number;
+    exp: number;
+    jti: string;
+}
+export interface ValidateDelegatedTokenOptions {
+    /** Audience to require; defaults to HOSTY_APP_ID. Validation fails when neither is set. */
+    appId?: string;
+    /** Base64 SPKI verification key; defaults to HOSTY_DELEGATED_TOKEN_PUBLIC_KEY. */
+    publicKey?: string;
+    /** Clock override for tests, ms since epoch. */
+    nowMs?: number;
+}
+/** Validates a delegated token locally and returns its claims, or null for anything invalid:
+ * bad format, unknown key, wrong audience, expiry, or signature mismatch. Deliberately never
+ * throws — a route treats null exactly like a missing token (401). */
+export declare function validateDelegatedToken(token: string, options?: ValidateDelegatedTokenOptions): DelegatedTokenClaims | null;

package/dist/delegated.js

@@ -0,0 +1,54 @@
+// Delegated-token validation, in its own entry so plain Node services (not just Next apps) can
+// import it: the server slice pulls in "server-only", which throws outside a React server bundle.
+import { createPublicKey, verify as verifySignature } from "node:crypto";
+const DELEGATED_TOKEN_PREFIX = "hosty_delegated";
+const DELEGATED_TOKEN_VERSION = "1";
+/** Validates a delegated token locally and returns its claims, or null for anything invalid:
+ * bad format, unknown key, wrong audience, expiry, or signature mismatch. Deliberately never
+ * throws — a route treats null exactly like a missing token (401). */
+export function validateDelegatedToken(token, options = {}) {
+    const publicKeyBase64 = options.publicKey?.trim() || process.env.HOSTY_DELEGATED_TOKEN_PUBLIC_KEY?.trim();
+    const expectedAppId = options.appId?.trim() || process.env.HOSTY_APP_ID?.trim();
+    if (!publicKeyBase64 || !expectedAppId) {
+        return null;
+    }
+    const parts = token.split(".");
+    const [prefix, version, payloadPart, signaturePart] = parts;
+    if (parts.length !== 4 ||
+        prefix !== DELEGATED_TOKEN_PREFIX ||
+        version !== DELEGATED_TOKEN_VERSION ||
+        payloadPart === undefined ||
+        signaturePart === undefined) {
+        return null;
+    }
+    try {
+        const signingInput = `${prefix}.${version}.${payloadPart}`;
+        const key = createPublicKey({
+            key: Buffer.from(publicKeyBase64, "base64"),
+            format: "der",
+            type: "spki",
+        });
+        const signatureValid = verifySignature("sha256", Buffer.from(signingInput, "utf8"), { key, dsaEncoding: "ieee-p1363" }, Buffer.from(signaturePart, "base64url"));
+        if (!signatureValid) {
+            return null;
+        }
+        const claims = JSON.parse(Buffer.from(payloadPart, "base64url").toString("utf8"));
+        if (typeof claims.sub !== "string" ||
+            typeof claims.role !== "string" ||
+            typeof claims.aud !== "string" ||
+            typeof claims.exp !== "number") {
+            return null;
+        }
+        if (claims.aud !== expectedAppId) {
+            return null;
+        }
+        const nowSeconds = Math.floor((options.nowMs ?? Date.now()) / 1000);
+        if (claims.exp <= nowSeconds) {
+            return null;
+        }
+        return claims;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -106,3 +106,33 @@ 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[]>;
+export { validateDelegatedToken, type DelegatedTokenClaims, type ValidateDelegatedTokenOptions, } from "./delegated.js";

package/dist/server.js

@@ -372,3 +372,186 @@ function readErrorField(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");
+    }
+}
+// Delegated tokens live in their own entry ("./delegated") because that module must stay
+// importable from plain Node services (the ai-gateway system app) — this file's "server-only"
+// import would throw there. Re-exported here so Next apps keep one import surface.
+export { validateDelegatedToken, } from "./delegated.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "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"
     },
+    "./delegated": {
+      "types": "./dist/delegated.d.ts",
+      "default": "./dist/delegated.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "default": "./dist/react.js"
@@ -30,8 +34,8 @@
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": ">=16",
-    "react": ">=19"
+    "next": "^16.2.10",
+    "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -42,10 +46,10 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5",
-    "vitest": "^4",
     "@types/node": "^24",
-    "@types/react": "^19"
+    "@types/react": "^19.2.18",
+    "typescript": "^6",
+    "vitest": "^4"
   },
   "repository": {
     "type": "git",