@hosty-sdk/app 0.1.2 → 0.2.0

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;

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,16 @@ 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;
 }

package/package.json

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