@hosty-sdk/app 0.9.0 → 0.11.0

package/dist/oauth-resource.d.ts

@@ -0,0 +1,35 @@
+/** The RFC 9728 document for one MCP endpoint. */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+}
+export interface ResourceMetadataOptions {
+    /** The app's own MCP endpoint URL as clients reach it. Wins over any derivation. */
+    resourceUrl?: string;
+    /** The public origin of the endpoint serving MCP. Defaults to `HOSTY_PUBLIC_ORIGIN_API` — the
+     * per-endpoint variable Core injects when an endpoint is published, for the reference layout
+     * where the MCP interface rides the `api` endpoint. An app with a different layout passes its
+     * own endpoint's origin (or the full resourceUrl). */
+    publicOrigin?: string;
+    /** The MCP endpoint's path under that origin. */
+    resourcePath?: string;
+    /** The authorization server's browser-reachable origin. Defaults to HOSTY_CORE_PUBLIC_ORIGIN —
+     * the flow's whole point is a remote client and a browser completing it, so the loopback origin
+     * this app dials Core on would send both to the wrong machine. */
+    authorizationServerOrigin?: string;
+}
+/**
+ * Builds the metadata document, or null when the environment cannot name the two URLs it consists
+ * of — which is the ordinary state of an app that is not published to a public origin. Null rather
+ * than a guess: a wrong resource identity here would have clients requesting tokens for a URL
+ * nothing serves, and no metadata simply means the manual token path, which always works.
+ */
+export declare function buildProtectedResourceMetadata(options?: ResourceMetadataOptions): ProtectedResourceMetadata | null;
+/**
+ * The `WWW-Authenticate` value a 401 from the MCP endpoint should carry, pointing a stock client at
+ * the metadata. The metadata URL is the RFC 9728 derivation: the well-known prefix inserted before
+ * the resource's path.
+ */
+export declare function buildWwwAuthenticate(metadata: ProtectedResourceMetadata): string;

package/dist/oauth-resource.js

@@ -0,0 +1,42 @@
+// The resource-server half of the MCP authorization handshake (RFC 9728), for an app's MCP
+// endpoint: the metadata document naming Core as the authorization server, and the 401 challenge
+// header pointing at it.
+//
+// In its own entry like ./scoped-token, and for the same reason: an MCP endpoint is usually not a
+// Next route, and the server slice pulls in "server-only".
+//
+// The app serves the *pointer*; Core is the authorization server and serves everything else. An app
+// never mints, validates, or even sees an OAuth exchange — a client that follows this pointer comes
+// back carrying an ordinary scoped access token, which the app validates through introspection
+// exactly as if the operator had pasted one by hand.
+/**
+ * Builds the metadata document, or null when the environment cannot name the two URLs it consists
+ * of — which is the ordinary state of an app that is not published to a public origin. Null rather
+ * than a guess: a wrong resource identity here would have clients requesting tokens for a URL
+ * nothing serves, and no metadata simply means the manual token path, which always works.
+ */
+export function buildProtectedResourceMetadata(options = {}) {
+    const core = options.authorizationServerOrigin?.trim() || process.env.HOSTY_CORE_PUBLIC_ORIGIN?.trim();
+    const publicOrigin = options.publicOrigin?.trim() || process.env.HOSTY_PUBLIC_ORIGIN_API?.trim();
+    const path = options.resourcePath?.trim() || "/api/mcp";
+    const resource = options.resourceUrl?.trim() || (publicOrigin ? `${publicOrigin.replace(/\/$/, "")}${path}` : undefined);
+    if (!core || !resource) {
+        return null;
+    }
+    return {
+        resource,
+        authorization_servers: [core.replace(/\/$/, "")],
+        scopes_supported: ["mcp:read"],
+        bearer_methods_supported: ["header"],
+    };
+}
+/**
+ * The `WWW-Authenticate` value a 401 from the MCP endpoint should carry, pointing a stock client at
+ * the metadata. The metadata URL is the RFC 9728 derivation: the well-known prefix inserted before
+ * the resource's path.
+ */
+export function buildWwwAuthenticate(metadata) {
+    const resource = new URL(metadata.resource);
+    const metadataUrl = `${resource.origin}/.well-known/oauth-protected-resource${resource.pathname.replace(/\/$/, "")}`;
+    return `Bearer resource_metadata="${metadataUrl}"`;
+}

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.9.0",
+  "version": "0.11.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,14 @@
       "types": "./dist/delegated.d.ts",
       "default": "./dist/delegated.js"
     },
+    "./scoped-token": {
+      "types": "./dist/scoped-token.d.ts",
+      "default": "./dist/scoped-token.js"
+    },
+    "./oauth-resource": {
+      "types": "./dist/oauth-resource.d.ts",
+      "default": "./dist/oauth-resource.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "default": "./dist/react.js"