@hosty-sdk/app 0.8.0 → 0.10.0

package/dist/embedder.d.ts

@@ -51,6 +51,18 @@ export interface AskAssistantIntent {
  * 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.
  */
+/**
+ * Verifies an attention count posted by a frame the embedder deliberately embeds.
+ *
+ * Read from the frame rather than polled by the embedder: the page that holds the session list and
+ * its event stream is the one source, and a shell asking the same question on a timer would be a
+ * second source that disagrees with the first for the length of its interval.
+ *
+ * Sender-verified like every other message here, though the payload is only a count: a wrong badge is
+ * a small harm, and a wrong badge that any page could set is a way to make an operator stop trusting
+ * the badge that matters.
+ */
+export declare function parseActiveFrameAttention(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): number | null;
 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

package/dist/embedder.js

@@ -12,7 +12,7 @@
 // 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";
+import { ASK_ASSISTANT_MAX_CHARS, ASK_ASSISTANT_TYPE, ATTENTION_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:
@@ -66,6 +66,31 @@ export function parseActiveFrameDelegatedTokenRequest(event, activeFrameWindow,
  * 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.
  */
+/**
+ * Verifies an attention count posted by a frame the embedder deliberately embeds.
+ *
+ * Read from the frame rather than polled by the embedder: the page that holds the session list and
+ * its event stream is the one source, and a shell asking the same question on a timer would be a
+ * second source that disagrees with the first for the length of its interval.
+ *
+ * Sender-verified like every other message here, though the payload is only a count: a wrong badge is
+ * a small harm, and a wrong badge that any page could set is a way to make an operator stop trusting
+ * the badge that matters.
+ */
+export function parseActiveFrameAttention(event, activeFrameWindow, activeFrameUrl) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return null;
+    }
+    const candidate = event.data;
+    // `typeof NaN === "number"`, and NaN survives every clamp below to arrive as a badge count no
+    // renderer can do anything with. Finiteness is the check that was actually meant.
+    if (candidate.type !== ATTENTION_TYPE || !Number.isFinite(candidate.count)) {
+        return null;
+    }
+    // Clamped rather than trusted: a negative or absurd count would render as a badge nobody can
+    // explain, and the frame has no business deciding how large a number the shell displays.
+    return Math.max(0, Math.min(99, Math.floor(candidate.count)));
+}
 export function parseActiveFrameAskAssistant(event, activeFrameWindow, activeFrameUrl) {
     if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
         return null;

package/dist/index.d.ts

@@ -34,6 +34,13 @@ export declare function createAuthRequiredIntent(appId: string): AuthRequiredInt
  * 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";
+/**
+ * How many of an embedded assistant's sessions are waiting for the operator.
+ *
+ * Published by the page that holds them, not asked for on a timer: one source, so a shell's badge and
+ * the list behind it can never disagree.
+ */
+export declare const ATTENTION_TYPE = "hosty:assistant-attention";
 /** 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 {

package/dist/index.js

@@ -37,6 +37,13 @@ export function createAuthRequiredIntent(appId) {
  * 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";
+/**
+ * How many of an embedded assistant's sessions are waiting for the operator.
+ *
+ * Published by the page that holds them, not asked for on a timer: one source, so a shell's badge and
+ * the list behind it can never disagree.
+ */
+export const ATTENTION_TYPE = "hosty:assistant-attention";
 /** Longer than a prompt fragment is a page dumping itself into someone's draft. */
 export const ASK_ASSISTANT_MAX_CHARS = 4000;
 /**

package/dist/scoped-token.d.ts

@@ -0,0 +1,48 @@
+/** What Core says about a credential. `active` is sufficient on its own: a caller that reads
+ * nothing else is not thereby insecure, because everything else is present only when it is true. */
+export type ScopedTokenIntrospection = {
+    active: true;
+    sub: string;
+    role: string | null;
+    scopes: string[];
+} | {
+    active: false;
+    error?: ScopedTokenError;
+};
+/** Why the answer could not be obtained. Present only when Core was never reached or answered
+ * something unusable — an ordinary "this credential is not valid" is a plain `active: false` with
+ * no error, because it is an answer rather than a failure. */
+export interface ScopedTokenError {
+    status: number | null;
+    code: string;
+    message: string;
+}
+export interface IntrospectScopedTokenOptions {
+    /** The tool or method this call is about. Core records it as the audit line for the action, so an
+     * external client's use of an app is visible to the host — pass it for a tool call, and leave it
+     * out for protocol traffic that is not itself an action. */
+    tool?: string;
+    /** Audience to introspect for; defaults to HOSTY_APP_ID. An app introspects only for itself —
+     * Core validates this against the service token regardless, so overriding it cannot widen reach. */
+    appId?: string;
+    /** Core origin; defaults to HOSTY_CORE_ORIGIN. */
+    coreOrigin?: string;
+    /** This app's service token; defaults to HOSTY_APP_SERVICE_TOKEN. */
+    serviceToken?: string;
+    /** Request budget. Core is on the same host, so the default is short. */
+    timeoutMs?: number;
+}
+/**
+ * Ask Core whether a bearer this app received is a live credential scoped to this app.
+ *
+ * Deliberately uncached, and callers must not add one: the credential's whole advantage over a
+ * delegated token is that revocation takes effect on the next call, and a cache is exactly the
+ * window that would take back.
+ */
+export declare function introspectScopedToken(token: string, options?: IntrospectScopedTokenOptions): Promise<ScopedTokenIntrospection>;
+/** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
+ * constant rather than text a caller should normalize. */
+export declare function hasScope(result: ScopedTokenIntrospection, scope: string): boolean;
+/** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
+ * that introduces mutations. */
+export declare const SCOPE_MCP_READ = "mcp:read";

package/dist/scoped-token.js

@@ -0,0 +1,142 @@
+// Scoped access tokens: the credential an external client presents directly to this app
+// (docs/features/scoped-access-tokens/feature.md).
+//
+// In its own entry, like ./delegated, so a plain Node service can import it — an app's MCP endpoint
+// is usually not a Next route, and the server slice pulls in "server-only", which throws outside a
+// React server bundle.
+//
+// The contrast with ./delegated is the whole point of this credential. A delegated token is signed
+// and checked locally: fast, but unrevocable, so it lives five minutes and cannot sit in a client's
+// configuration file. A scoped token is opaque and worth nothing until Core says otherwise, which is
+// why it can live in a config and still stop the moment an operator revokes it.
+// Core is a loopback hop away, so a generous budget would only hold a request open while something
+// is already wrong.
+const DEFAULT_TIMEOUT_MS = 2_000;
+/**
+ * Ask Core whether a bearer this app received is a live credential scoped to this app.
+ *
+ * Deliberately uncached, and callers must not add one: the credential's whole advantage over a
+ * delegated token is that revocation takes effect on the next call, and a cache is exactly the
+ * window that would take back.
+ */
+export async function introspectScopedToken(token, options = {}) {
+    const appId = options.appId?.trim() || process.env.HOSTY_APP_ID?.trim();
+    const serviceToken = options.serviceToken?.trim() || process.env.HOSTY_APP_SERVICE_TOKEN?.trim();
+    // No fallback origin is invented when the variable is missing. Core injects HOSTY_CORE_ORIGIN
+    // already resolved for the runtime this app is in — a container reaches Core by a different
+    // address than a host process does — so a guessed `localhost` would be right in one runtime and
+    // silently wrong in the other. This is the same origin every other Core call in this SDK uses.
+    const coreOrigin = options.coreOrigin?.trim() || process.env.HOSTY_CORE_ORIGIN?.trim();
+    if (!token) {
+        // Nothing was presented, which is the caller's own business and not a failure of this app.
+        return { active: false, error: { status: null, code: "credential_missing", message: "No credential was presented." } };
+    }
+    // Distinct from the above on purpose: here a credential *was* presented and could not be checked,
+    // because this app is not configured to reach Core. Answering the client "invalid credential"
+    // would send someone to rotate a token that may be perfectly good, to fix a fault on this side.
+    if (!appId || !serviceToken || !coreOrigin) {
+        return {
+            active: false,
+            error: {
+                status: null,
+                code: "introspection_unconfigured",
+                message: "HOSTY_APP_ID, HOSTY_APP_SERVICE_TOKEN, and HOSTY_CORE_ORIGIN must all be configured.",
+            },
+        };
+    }
+    let endpoint;
+    try {
+        endpoint = new URL(`/api/internal/apps/${encodeURIComponent(appId)}/token/introspect`, coreOrigin).toString();
+    }
+    catch {
+        return {
+            active: false,
+            error: { status: null, code: "core_origin_invalid", message: "HOSTY_CORE_ORIGIN is not a valid URL." },
+        };
+    }
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { authorization: `Bearer ${serviceToken}`, "content-type": "application/json" },
+            body: JSON.stringify({ token, ...(options.tool ? { tool: options.tool } : {}) }),
+            cache: "no-store",
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        // Core unreachable is a failure, never an inactive credential. The distinction matters to the
+        // caller: this is a 503, not a 401, and answering "inactive" would tell a legitimate client its
+        // credential is bad while the truth is that nothing could be checked.
+        const timedOut = error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError");
+        return {
+            active: false,
+            error: {
+                status: null,
+                code: timedOut ? "introspection_timeout" : "introspection_unavailable",
+                message: error instanceof Error ? error.message : "The introspection request to Core failed.",
+            },
+        };
+    }
+    if (!response.ok) {
+        return {
+            active: false,
+            error: {
+                status: response.status,
+                code: "introspection_failed",
+                message: `Core answered ${response.status} for the introspection request.`,
+            },
+        };
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        return {
+            active: false,
+            error: { status: response.status, code: "core_response_invalid", message: "Core returned an unreadable body." },
+        };
+    }
+    const body = payload;
+    // A literal `false` is an answer: Core checked and said no.
+    if (body?.active === false) {
+        return { active: false };
+    }
+    // Anything else is a body this helper could not read, and the two must not collapse into one
+    // result. Fail closed either way — an unreadable answer is never a grant — but report it as an
+    // error, because a caller turns "not valid" into 401 and "could not be established" into 503, and
+    // a wire-format change or a mangling proxy would otherwise look exactly like a bad credential.
+    //
+    // The whole active shape is required, not just `active`: a payload claiming success with no
+    // subject, or with scopes that are not a list of strings, cannot authorize anything, and a caller
+    // reading only `active` must not be handed one.
+    if (body?.active !== true ||
+        typeof body.sub !== "string" ||
+        !body.sub ||
+        !Array.isArray(body.scopes) ||
+        body.scopes.some((scope) => typeof scope !== "string")) {
+        return {
+            active: false,
+            error: {
+                status: response.status,
+                code: "core_response_invalid",
+                message: "Core answered with a body this client could not read as an introspection result.",
+            },
+        };
+    }
+    return {
+        active: true,
+        sub: body.sub,
+        role: typeof body.role === "string" ? body.role : null,
+        scopes: body.scopes,
+    };
+}
+/** Whether an introspection result carries a scope. Exact match, because a scope is a protocol
+ * constant rather than text a caller should normalize. */
+export function hasScope(result, scope) {
+    return result.active && result.scopes.includes(scope);
+}
+/** The scope every read-only MCP tool is gated on today. Mutation scopes arrive with the feature
+ * that introduces mutations. */
+export const SCOPE_MCP_READ = "mcp:read";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/delegated.d.ts",
       "default": "./dist/delegated.js"
     },
+    "./scoped-token": {
+      "types": "./dist/scoped-token.d.ts",
+      "default": "./dist/scoped-token.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "default": "./dist/react.js"