@hosty-sdk/app 0.5.0 → 0.6.0

package/README.md

@@ -46,6 +46,18 @@ 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/server.d.ts

@@ -135,3 +135,4 @@ export declare function deleteAppSecret(key: string, config: HostyAppConfig): Pr
 /** 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

@@ -551,3 +551,7 @@ async function readJsonOrThrow(response) {
         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.5.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"