@hosty-sdk/app 0.6.0 → 0.8.0

package/README.md

@@ -10,10 +10,10 @@ 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` | anywhere | status taxonomy, recovery decision, `hosty:auth-required` and `hosty:request-delegated-token` schemas, URL/env helpers |
 | `@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 |
+| `@hosty-sdk/app/embedder` | client | verified responders — launch-code recovery and delegated tokens — for anything that embeds Hosty apps |
 
 Minimal Next.js wiring:
 
@@ -58,7 +58,26 @@ const claims = validateDelegatedToken(bearerToken);
 if (claims?.role !== "host.admin") { /* 401/403 */ }
 ```
 
+An embedded page cannot mint a delegated token itself — that needs the user's Core session in a
+first-party context — so it asks whoever embeds it:
+
+```ts
+import { DELEGATED_TOKEN_REQUEST_TYPE, DELEGATED_TOKEN_TYPE } from "@hosty-sdk/app";
+import { parseActiveFrameDelegatedTokenRequest } from "@hosty-sdk/app/embedder";
+
+// In the embedder, per app frame. A verified request says who asked, never whether to answer: the
+// token is user-scoped, so grant it only to apps you decided to grant it to, and post it to that
+// frame's own origin — never "*". Attach the listener before the frame can run (apps ask as soon as
+// their document does, and they re-ask until answered), and honour `refresh`: it means the token the
+// app holds was refused, so a cached mint must not be handed back.
+const intent = parseActiveFrameDelegatedTokenRequest(event, frame.contentWindow, frame.src);
+if (intent) {
+  const { token, expiresAt } = await mintDelegatedTokenFromCore(appId, { force: intent.refresh });
+  frame.contentWindow.postMessage({ type: DELEGATED_TOKEN_TYPE, token, expiresAt }, frameOrigin);
+}
+```
+
 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).
+[`docs/features/hosty-app-sdk/feature.md`](https://github.com/alex-de-haas/docker-host/blob/main/docs/features/hosty-app-sdk/feature.md).
 
 License: AGPL-3.0-only.

package/dist/embedder.d.ts

@@ -1,8 +1,10 @@
-export interface AuthRequiredMessage {
+/** The three fields of a `message` event these parsers read. */
+export interface EmbedderMessage {
     data: unknown;
     origin: string;
     source: unknown;
 }
+export type AuthRequiredMessage = EmbedderMessage;
 /**
  * Verifies that a `message` event is a genuine auth-required intent from the active app
  * frame. Every check is about facts only the embedder can know:
@@ -13,6 +15,43 @@ export interface AuthRequiredMessage {
  * and the embedder answers by reissuing a code through its own authenticated Core call.
  */
 export declare function parseActiveFrameAuthRequired(event: AuthRequiredMessage, activeFrameWindow: unknown, activeFrameUrl: string, expectedAppId: string): boolean;
+/** A verified request, and the one thing its payload carries. */
+export interface DelegatedTokenRequestIntent {
+    /** The app says the token it holds was refused, so a cached mint must not be replayed. */
+    refresh: boolean;
+}
+/**
+ * Verifies that a `message` event is a delegated-token request from the active app frame, using
+ * the same sender checks as `parseActiveFrameAuthRequired`. There is nothing app-specific in the
+ * payload to check — and nothing to gain from one, since a frame's claim about which app it is
+ * would be the weakest fact in the room next to the embedder's own DOM.
+ *
+ * A non-null result says only *who asked*, never *whether to answer*. Answering hands the frame a
+ * user-scoped credential, so the embedder decides per app which ones it grants — Hosty Shell
+ * answers for the assistant gateway alone, the app it already mints delegated tokens for, so the
+ * handshake gives that app nothing it did not already hold. Wiring this responder to every frame
+ * would silently widen the delegated-token trust story to whatever an operator installed.
+ *
+ * An app may repeat the request (the first one can land before a listener is attached, and nothing
+ * makes an embedder attach one early), so answering must be idempotent — which minting from Core
+ * is.
+ */
+export declare function parseActiveFrameDelegatedTokenRequest(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): DelegatedTokenRequestIntent | null;
+/** A verified ask, and the one thing its payload carries. */
+export interface AskAssistantIntent {
+    /** Trimmed and capped here, so no embedder has to remember to do it. */
+    text: string;
+}
+/**
+ * Verifies that a `message` event is an ask-the-assistant intent from the active app frame, using
+ * the same sender checks as the pair above.
+ *
+ * The text is capped in the parser rather than by the caller: a cap is part of the contract, and an
+ * embedder that forgot it would let one app's page paste itself into the operator's draft. What the
+ * embedder must still decide is *where* the text goes — this function says an app asked, never that
+ * the assistant should send anything. Nothing here may be auto-sent.
+ */
+export declare function parseActiveFrameAskAssistant(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): AskAssistantIntent | null;
 /**
  * Per-app reissue throttle: a frame that keeps re-posting (e.g. it never accepts the new
  * code) must not drive an unbounded reissue storm. One reissue per app per interval is

package/dist/embedder.js

@@ -1,12 +1,18 @@
-// Embedder slice: the shell half of the recovery contract, for anything that embeds Hosty
-// apps in iframes (Hosty Shell or a third-party UI client). Pure functions plus a small
-// rate limiter — the embedder wires them to its own DOM and its own "open this app" flow.
+// Embedder slice: the shell half of the contracts an embedded app cannot serve itself, for
+// anything that embeds Hosty apps in iframes (Hosty Shell or a third-party UI client). Pure
+// functions plus a small rate limiter — the embedder wires them to its own DOM, its own "open
+// this app" flow, and its own Core session.
 //
-// The contract in one sentence: on a VERIFIED `hosty:auth-required` from an app you embed,
+// Recovery, in one sentence: on a VERIFIED `hosty:auth-required` from an app you embed,
 // re-run your normal open flow for that app (which mints a fresh launch code), rate-limited.
 // The re-open must take the full launch-code path — an "already open → reuse the URL
 // without a code" optimization must not short-circuit recovery.
-import { AUTH_REQUIRED_INTENT_TYPE } from "./index.js";
+//
+// Delegated tokens, in one sentence: on a VERIFIED `hosty:request-delegated-token` from an app
+// you have decided to grant one, mint a token from Core with your own session and post it back
+// to that frame's origin. Both requests are unauthenticated by design; what makes them safe is
+// that the embedder answers from facts about its own DOM rather than from what the frame claims.
+import { ASK_ASSISTANT_MAX_CHARS, ASK_ASSISTANT_TYPE, AUTH_REQUIRED_INTENT_TYPE, DELEGATED_TOKEN_REQUEST_TYPE, } from "./index.js";
 /**
  * Verifies that a `message` event is a genuine auth-required intent from the active app
  * frame. Every check is about facts only the embedder can know:
@@ -17,6 +23,62 @@ import { AUTH_REQUIRED_INTENT_TYPE } from "./index.js";
  * and the embedder answers by reissuing a code through its own authenticated Core call.
  */
 export function parseActiveFrameAuthRequired(event, activeFrameWindow, activeFrameUrl, expectedAppId) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return false;
+    }
+    const candidate = event.data;
+    return (candidate.type === AUTH_REQUIRED_INTENT_TYPE &&
+        typeof candidate.appId === "string" &&
+        candidate.appId === expectedAppId);
+}
+/**
+ * Verifies that a `message` event is a delegated-token request from the active app frame, using
+ * the same sender checks as `parseActiveFrameAuthRequired`. There is nothing app-specific in the
+ * payload to check — and nothing to gain from one, since a frame's claim about which app it is
+ * would be the weakest fact in the room next to the embedder's own DOM.
+ *
+ * A non-null result says only *who asked*, never *whether to answer*. Answering hands the frame a
+ * user-scoped credential, so the embedder decides per app which ones it grants — Hosty Shell
+ * answers for the assistant gateway alone, the app it already mints delegated tokens for, so the
+ * handshake gives that app nothing it did not already hold. Wiring this responder to every frame
+ * would silently widen the delegated-token trust story to whatever an operator installed.
+ *
+ * An app may repeat the request (the first one can land before a listener is attached, and nothing
+ * makes an embedder attach one early), so answering must be idempotent — which minting from Core
+ * is.
+ */
+export function parseActiveFrameDelegatedTokenRequest(event, activeFrameWindow, activeFrameUrl) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return null;
+    }
+    const candidate = event.data;
+    if (candidate.type !== DELEGATED_TOKEN_REQUEST_TYPE) {
+        return null;
+    }
+    return { refresh: candidate.refresh === true };
+}
+/**
+ * Verifies that a `message` event is an ask-the-assistant intent from the active app frame, using
+ * the same sender checks as the pair above.
+ *
+ * The text is capped in the parser rather than by the caller: a cap is part of the contract, and an
+ * embedder that forgot it would let one app's page paste itself into the operator's draft. What the
+ * embedder must still decide is *where* the text goes — this function says an app asked, never that
+ * the assistant should send anything. Nothing here may be auto-sent.
+ */
+export function parseActiveFrameAskAssistant(event, activeFrameWindow, activeFrameUrl) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return null;
+    }
+    const candidate = event.data;
+    if (candidate.type !== ASK_ASSISTANT_TYPE || typeof candidate.text !== "string") {
+        return null;
+    }
+    const text = candidate.text.trim().slice(0, ASK_ASSISTANT_MAX_CHARS);
+    return text ? { text } : null;
+}
+/** The sender half both parsers share: right frame, right origin, object payload. */
+function isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl) {
     if (!activeFrameWindow || event.source !== activeFrameWindow) {
         return false;
     }
@@ -28,13 +90,7 @@ export function parseActiveFrameAuthRequired(event, activeFrameWindow, activeFra
     catch {
         return false;
     }
-    if (!event.data || typeof event.data !== "object" || Array.isArray(event.data)) {
-        return false;
-    }
-    const candidate = event.data;
-    return (candidate.type === AUTH_REQUIRED_INTENT_TYPE &&
-        typeof candidate.appId === "string" &&
-        candidate.appId === expectedAppId);
+    return Boolean(event.data) && typeof event.data === "object" && !Array.isArray(event.data);
 }
 /**
  * Per-app reissue throttle: a frame that keeps re-posting (e.g. it never accepts the new

package/dist/index.d.ts

@@ -10,6 +10,66 @@ export interface AuthRequiredIntent {
     appId: string;
 }
 export declare function createAuthRequiredIntent(appId: string): AuthRequiredIntent;
+/**
+ * The postMessage types of the delegated-token handshake: an embedded app page asks its embedder
+ * for a short-TTL token scoped to itself, and the embedder answers with one it minted from Core.
+ * Same shape of contract as the launch-code recovery above — the app cannot self-serve, because
+ * minting needs the user's Core session in a first-party context, which only the embedder has.
+ *
+ * The request carries no secret, so it is safe to broadcast; the answer does, so an embedder must
+ * post it to the frame's own origin and never to `*`. Answering is a decision, not a reflex: the
+ * token is a user-scoped credential, so an embedder answers only for apps it deliberately grants
+ * one (Hosty Shell: the assistant gateway, which it already mints tokens for).
+ */
+/**
+ * An embedded app asking its embedder to put text in the assistant's draft.
+ *
+ * The embedder reveals its assistant surface and forwards the text there; the assistant fills the
+ * **draft** and stops. Nothing is sent. That is the contract, not a UX choice: app-provided text
+ * entering a model that holds host shell is the same trust boundary that keeps MCP providers off by
+ * default, and an error message is exactly the shape a prompt injection arrives in. The operator
+ * reads it, with its source shown, and decides.
+ *
+ * Plain text only, and no reply. A structured payload would invite apps to smuggle shape the
+ * operator cannot read at a glance, and an answer would turn a hand-off into a channel.
+ */
+export declare const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
+/** Longer than a prompt fragment is a page dumping itself into someone's draft. */
+export declare const ASK_ASSISTANT_MAX_CHARS = 4000;
+export interface AskAssistantMessage {
+    type: typeof ASK_ASSISTANT_TYPE;
+    /** Trimmed and capped by the embedder's parser; the app need not pre-truncate. */
+    text: string;
+}
+/**
+ * Asks the embedder to put `text` in the operator's assistant draft.
+ *
+ * Safe to call unconditionally: standalone there is no embedder to hear it, and an embedder that
+ * does not offer an assistant simply ignores it. Returns whether the message could be posted at
+ * all — never whether anyone acted on it, which is the operator's business and not the app's.
+ */
+export declare function askAssistant(text: string): boolean;
+export declare const DELEGATED_TOKEN_REQUEST_TYPE = "hosty:request-delegated-token";
+export declare const DELEGATED_TOKEN_TYPE = "hosty:delegated-token";
+export interface DelegatedTokenRequest {
+    type: typeof DELEGATED_TOKEN_REQUEST_TYPE;
+    /**
+     * Set when the app is asking because the token it holds was refused. Only the app learns that —
+     * it is the one calling the API — so without this flag an embedder that caches its mints would
+     * keep answering with the very token that just came back 401, and the app could not recover until
+     * the embedder's own copy aged out. Absent rather than false on an ordinary request.
+     */
+    refresh?: true;
+}
+export interface DelegatedTokenGrant {
+    type: typeof DELEGATED_TOKEN_TYPE;
+    token: string;
+    /** ISO-8601 expiry, so the page can reuse the token instead of asking once per request. */
+    expiresAt: string;
+}
+export declare function createDelegatedTokenRequest(options?: {
+    refresh?: boolean;
+}): DelegatedTokenRequest;
 /**
  * Recovery classification of an app session, per the platform identity error contract:
  * - `not-present`: no token at all (recoverable — same handling as `expired`).

package/dist/index.js

@@ -2,7 +2,7 @@
 // server.mjs). No React, no Next, no environment reads — everything is passed in.
 //
 // This is the single source of truth for the Hosty app-session contract described in
-// docker-host docs/ideas/hosty-app-sdk.md and docs/ideas/auth-session-lifecycle.md.
+// docker-host docs/features/hosty-app-sdk/feature.md and docs/features/auth-session-lifecycle/feature.md.
 /**
  * The postMessage type an embedded app sends its parent to request a fresh launch code.
  * A frozen protocol constant: it deliberately does not track product branding (precedent:
@@ -13,6 +13,64 @@ export const AUTH_REQUIRED_INTENT_TYPE = "hosty:auth-required";
 export function createAuthRequiredIntent(appId) {
     return { type: AUTH_REQUIRED_INTENT_TYPE, appId };
 }
+/**
+ * The postMessage types of the delegated-token handshake: an embedded app page asks its embedder
+ * for a short-TTL token scoped to itself, and the embedder answers with one it minted from Core.
+ * Same shape of contract as the launch-code recovery above — the app cannot self-serve, because
+ * minting needs the user's Core session in a first-party context, which only the embedder has.
+ *
+ * The request carries no secret, so it is safe to broadcast; the answer does, so an embedder must
+ * post it to the frame's own origin and never to `*`. Answering is a decision, not a reflex: the
+ * token is a user-scoped credential, so an embedder answers only for apps it deliberately grants
+ * one (Hosty Shell: the assistant gateway, which it already mints tokens for).
+ */
+/**
+ * An embedded app asking its embedder to put text in the assistant's draft.
+ *
+ * The embedder reveals its assistant surface and forwards the text there; the assistant fills the
+ * **draft** and stops. Nothing is sent. That is the contract, not a UX choice: app-provided text
+ * entering a model that holds host shell is the same trust boundary that keeps MCP providers off by
+ * default, and an error message is exactly the shape a prompt injection arrives in. The operator
+ * reads it, with its source shown, and decides.
+ *
+ * Plain text only, and no reply. A structured payload would invite apps to smuggle shape the
+ * operator cannot read at a glance, and an answer would turn a hand-off into a channel.
+ */
+export const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
+/** Longer than a prompt fragment is a page dumping itself into someone's draft. */
+export const ASK_ASSISTANT_MAX_CHARS = 4000;
+/**
+ * Asks the embedder to put `text` in the operator's assistant draft.
+ *
+ * Safe to call unconditionally: standalone there is no embedder to hear it, and an embedder that
+ * does not offer an assistant simply ignores it. Returns whether the message could be posted at
+ * all — never whether anyone acted on it, which is the operator's business and not the app's.
+ */
+export function askAssistant(text) {
+    if (typeof window === "undefined" || window.parent === window) {
+        return false;
+    }
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return false;
+    }
+    // Broadcast: the message carries no secret, and the embedder verifies the sender against its own
+    // DOM rather than trusting anything claimed here.
+    //
+    // Capped on the way out too. The parser remains where the contract is enforced — an app is not
+    // trusted to have done this — but there is no reason to structure-clone a megabyte across the
+    // boundary just to have the embedder discard it.
+    const capped = trimmed.slice(0, ASK_ASSISTANT_MAX_CHARS);
+    window.parent.postMessage({ type: ASK_ASSISTANT_TYPE, text: capped }, "*");
+    return true;
+}
+export const DELEGATED_TOKEN_REQUEST_TYPE = "hosty:request-delegated-token";
+export const DELEGATED_TOKEN_TYPE = "hosty:delegated-token";
+export function createDelegatedTokenRequest(options = {}) {
+    return options.refresh
+        ? { type: DELEGATED_TOKEN_REQUEST_TYPE, refresh: true }
+        : { type: DELEGATED_TOKEN_REQUEST_TYPE };
+}
 /**
  * Maps a Core revalidation HTTP status onto the session classification. Classification is
  * by status code only — never by error-code strings — so new Core codes cannot break an

package/dist/server.js

@@ -5,7 +5,7 @@ import { classifyRevalidationHttpStatus, } from "./index.js";
 // Core runs on the same host as the app services, so a short budget is plenty; a stalled
 // call must not hold a route open indefinitely.
 const CORE_AUTH_TIMEOUT_MS = 1_500;
-// Decision 9 (hosty-app-sdk.md): positive revalidations may be cached for 30s, clamped to
+// Per docs/features/hosty-app-sdk/feature.md: positive revalidations may be cached for 30s, clamped to
 // the grant's expiry; negative results are never cached, so a stuck-unauthenticated state
 // is impossible. Bounded so an attacker spraying tokens cannot grow the map unboundedly.
 const REVALIDATION_CACHE_TTL_MS = 30_000;

package/package.json

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