@kazzle/app 0.1.821 → 0.1.823

package/dist/client.d.ts

@@ -8,16 +8,23 @@ export declare function componentUrlEnvName(componentName: string): string;
  * a wrong/empty address makes cross-component calls fail silently.
  */
 export declare function componentUrl(componentName: string): string;
-/** Extract the install identity Authorization header from an incoming tool request. */
-export declare function installAuthHeader(req: Request): string;
+/** Header Kazzle sets to carry the verified install identity into the app. */
+export declare const KAZZLE_IDENTITY_HEADER = "x-kazzle-identity";
 /**
- * Client scoped to one install, built from the identity header on an incoming
+ * Extract the install identity token from an incoming tool request. Kazzle
+ * delivers it in `X-Kazzle-Identity`; the app's own `Authorization` header is
+ * left untouched for the app's own use.
+ */
+export declare function installIdentityToken(req: Request): string;
+/**
+ * Client scoped to one install, built from the identity token on an incoming
  * tool request. Use it to persist and read per-install runtime secrets.
  */
 export declare class KazzleInstallClient {
-    private readonly auth;
+    private readonly token;
     private readonly apiUrl;
-    constructor(reqOrAuthHeader: Request | string);
+    constructor(reqOrIdentityToken: Request | string);
+    private authHeader;
     /** Read a per-install secret by fixed name. Returns null when not set yet (404). */
     getSecret(name: string): Promise<string | null>;
     /** Write a per-install secret by fixed name. */

package/dist/client.js

@@ -4,10 +4,12 @@
 // comments in the templates:
 //
 //   1. Per-install secrets. When the AI calls an app tool, Kazzle POSTs the
-//      request with `Authorization: Bearer <install identity>`. The app reads
-//      or writes runtime secrets by calling Kazzle back with that SAME header;
-//      Kazzle scopes the secret to this install. Use a fixed secret name — never
-//      key by user yourself.
+//      request with the install identity in the `X-Kazzle-Identity` header
+//      (Kazzle owns that header; your app's own `Authorization` is never
+//      touched). The app reads or writes runtime secrets by calling Kazzle back
+//      with that identity as `Authorization: Bearer <identity>`; Kazzle scopes
+//      the secret to this install. Use a fixed secret name — never key by user
+//      yourself.
 //   2. Sibling component URLs. A component reaches another component in the same
 //      app via the injected `KAZZLE_APP_COMPONENT_<NAME>_URL` env var. That URL
 //      is server-to-server only — never expose it to the browser.
@@ -42,29 +44,38 @@ export function componentUrl(componentName) {
     }
     return url;
 }
-/** Extract the install identity Authorization header from an incoming tool request. */
-export function installAuthHeader(req) {
-    const auth = req.headers.get('authorization');
-    if (!auth) {
-        throw new Error('Missing Authorization header — expected the install identity from a Kazzle tool call.');
+/** Header Kazzle sets to carry the verified install identity into the app. */
+export const KAZZLE_IDENTITY_HEADER = 'x-kazzle-identity';
+/**
+ * Extract the install identity token from an incoming tool request. Kazzle
+ * delivers it in `X-Kazzle-Identity`; the app's own `Authorization` header is
+ * left untouched for the app's own use.
+ */
+export function installIdentityToken(req) {
+    const token = req.headers.get(KAZZLE_IDENTITY_HEADER);
+    if (!token) {
+        throw new Error(`Missing ${KAZZLE_IDENTITY_HEADER} header — expected the install identity from a Kazzle tool call.`);
     }
-    return auth;
+    return token;
 }
 /**
- * Client scoped to one install, built from the identity header on an incoming
+ * Client scoped to one install, built from the identity token on an incoming
  * tool request. Use it to persist and read per-install runtime secrets.
  */
 export class KazzleInstallClient {
-    auth;
+    token;
     apiUrl;
-    constructor(reqOrAuthHeader) {
-        this.auth = typeof reqOrAuthHeader === 'string' ? reqOrAuthHeader : installAuthHeader(reqOrAuthHeader);
+    constructor(reqOrIdentityToken) {
+        this.token = typeof reqOrIdentityToken === 'string' ? reqOrIdentityToken : installIdentityToken(reqOrIdentityToken);
         this.apiUrl = kazzleApiUrl();
     }
+    authHeader() {
+        return `Bearer ${this.token}`;
+    }
     /** Read a per-install secret by fixed name. Returns null when not set yet (404). */
     async getSecret(name) {
         const res = await fetch(`${this.apiUrl}/apps/secrets/${encodeURIComponent(name)}`, {
-            headers: { authorization: this.auth },
+            headers: { authorization: this.authHeader() },
         });
         if (res.status === 404)
             return null;
@@ -77,7 +88,7 @@ export class KazzleInstallClient {
     async setSecret(name, value) {
         const res = await fetch(`${this.apiUrl}/apps/secrets/${encodeURIComponent(name)}`, {
             method: 'PUT',
-            headers: { authorization: this.auth, 'content-type': 'application/json' },
+            headers: { authorization: this.authHeader(), 'content-type': 'application/json' },
             body: JSON.stringify({ value }),
         });
         if (!res.ok)

package/dist/tools.js

@@ -18,7 +18,8 @@
 // If you change this contract, update that compiler and its tests together.
 //
 // Tool handlers (POST /tools/...) receive:
-//   - `Authorization: Bearer <install identity>` — scope secrets via KazzleInstallClient
+//   - `X-Kazzle-Identity: <install identity>` — scope secrets via KazzleInstallClient
+//     (your app's own `Authorization` header is never touched by Kazzle)
 //   - `Kazzle-Tool-Context: <json>` — thread vs Tools API (`toolContext(req)`)
 // Handlers may return plain text, `{ content }`, or `{ type: "action_required", ... }`
 // to pause the thread until the user acts (see documents/tool-required-action.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kazzle/app",
-  "version": "0.1.821",
+  "version": "0.1.823",
   "description": "Contracts, tool helpers, Vite helper, and templates for building Kazzle apps.",
   "license": "UNLICENSED",
   "repository": {

package/templates/process-app/components/process/index.ts

@@ -110,8 +110,9 @@ const server = Bun.serve({
     //
     // Each tool declared in skills/tools/tools.ts is backed by a route here.
     // When the AI calls `save_bookmark`, Kazzle POSTs the tool input to this path
-    // with the app identity as `Authorization: Bearer <token>`. Return either
-    // plain text or JSON { content } — that becomes the tool result the AI sees.
+    // with the app identity in the `X-Kazzle-Identity` header (your app's own
+    // `Authorization` header is never touched). Return either plain text or JSON
+    // { content } — that becomes the tool result the AI sees.
     //
     // To add a tool: add it to tools.ts (name + Zod input + path), then add
     // its matching `POST <path>` route below.
@@ -119,24 +120,20 @@ const server = Bun.serve({
       const input = await req.json().catch(() => ({}));
       const parsed = SaveBookmarkInput.safeParse(input);
       if (!parsed.success) {
-        return Response.json({ content: parsed.error.issues.map(issue => issue.message).join('; ') }, { status: 400 });
+        return Response.json({ content: parsed.error.issues.map(issue => `${issue.path.join('.') || 'input'}: ${issue.message}`).join('; ') }, { status: 400 });
       }
       const toolInput = parsed.data;
       // Do the real work here (write to your DB, call an API, etc.).
       //
       // Per-install runtime secrets (e.g. a connected user's OAuth token) are
-      // saved/read by calling Kazzle back with the SAME identity header this
-      // tool call arrived with — Kazzle scopes them to this install. Use a
+      // saved/read via KazzleInstallClient, which reads the `X-Kazzle-Identity`
+      // header from this request and scopes the secret to this install. Use a
       // fixed name; never key by user yourself:
       //
-      //   const auth = req.headers.get('authorization')!;
-      //   const api = process.env.KAZZLE_API_URL;
-      //   await fetch(`${api}/apps/secrets/gmail_token`, {
-      //     method: 'PUT', headers: { authorization: auth, 'content-type': 'application/json' },
-      //     body: JSON.stringify({ value: accessToken }),
-      //   });
-      //   const res = await fetch(`${api}/apps/secrets/gmail_token`, { headers: { authorization: auth } });
-      //   const token = res.ok ? (await res.json()).value : null; // 404 → not connected yet
+      //   import { KazzleInstallClient } from '@kazzle/app/client';
+      //   const kazzle = new KazzleInstallClient(req);
+      //   await kazzle.setSecret('gmail_token', accessToken);
+      //   const token = await kazzle.getSecret('gmail_token'); // null → not connected yet
       console.log(`[{{APP_NAME}}] save_bookmark:`, toolInput.title ?? '(untitled)', toolInput.url);
       return Response.json({ content: `Saved bookmark: ${toolInput.title ?? toolInput.url}` });
     }