@assembly-js/app-foundation 0.0.30 → 0.0.31

package/CLAUDE.md

@@ -1162,7 +1162,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 <!-- /feature:app-owned-header -->
 - ❌ Don't let two mounted components call `useAssemblyHeader` at once — e.g. a parent shell's scaffolding-era stub CTA left in place after a child took real ownership. Strict Mode hides the race in dev; the hook throws in dev and ignores the second caller in production. Delete the parent's stub the moment a child owns the slot.
 - ❌ Don't `window.open(url, '_self')` or set `window.location` for external links — use `<a target="_blank" rel="noreferrer">`.
-- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Fetch it with `authFetch`, read the response with `res.blob()`, and click a programmatic anchor on `URL.createObjectURL(blob)` with a `download` name. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
+- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Use `downloadViaBlob(url, filename)` from `app/components/lib-client.ts` — it calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor on `URL.createObjectURL(blob)`. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
 - ❌ Don't hardcode brand colors. The portal applies the workspace theme.
 - ❌ Don't add dark mode support (`dark:` classes, `.dark` class toggling, `next-themes`, `ThemeProvider`, or `prefers-color-scheme` media queries). The assembly-ui registry is light-only and the layout forces `colorScheme: 'light'`.
 - ❌ Don't handle the session token at all — no cookie you set, no `useAssembly().token`, no `x-assembly-token` header, no `searchParams.token`. The middleware already exchanged it for a bearer cookie; call `getAssembly()` / `getAssemblyForRequest(req)` server-side and the call is authenticated.

package/dist/app-storage.js

@@ -1,9 +1,21 @@
 import { getAssembly } from './assembly.js';
+// A bearer token is a JWT: three base64url segments separated by dots, the
+// first always decoding to a JSON header (so it starts with 'eyJ'). Matching
+// the whole-string shape — not just the 'eyJ' prefix — avoids rejecting a
+// legitimate file name or storage key that happens to start with 'eyJ'.
+const JWT_SHAPE = /^eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$/;
 // fileName must be a bare file name (e.g. 'invoice.pdf'), never a path:
 // the platform rejects any value containing '/' or '..'. Do NOT prefix
 // folders or construct the S3 key yourself — the platform scopes the key
 // to the workspace and makes it unique. Store the key it returns.
+// NOTE: takes ONE argument. If you are calling this as getUploadUrl(token, fileName)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getUploadUrl(fileName) {
+    // Catches the old (token, fileName) call shape where a JWT ends up as the file name.
+    if (JWT_SHAPE.test(fileName)) {
+        throw new Error('getUploadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getUploadUrl(fileName) with the file name only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/upload-url', {
         method: 'POST',
@@ -13,7 +25,14 @@ export async function getUploadUrl(fileName) {
         throw new Error('Upload URL request failed: ' + res.status);
     return res.json();
 }
+// NOTE: takes ONE argument. If you are calling this as getDownloadUrl(token, key)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getDownloadUrl(key) {
+    // Catches the old (token, key) call shape where a JWT ends up as the storage key.
+    if (JWT_SHAPE.test(key)) {
+        throw new Error('getDownloadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getDownloadUrl(key) with the storage key only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/download-url?key=' + encodeURIComponent(key));
     if (!res.ok)

package/dist/lib-client.d.ts

@@ -1,5 +1,6 @@
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function downloadViaBlob(url: string, filename: string): Promise<void>;
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead

package/dist/lib-client.js

@@ -126,6 +126,28 @@ export async function authFetch(input, init) {
     }
     return fetch(input, { ...init, headers });
 }
+// Downloads a file from url via authFetch (bearer cookie, same-origin), then
+// triggers a browser download without opening a new tab. Use this instead of
+// window.open or <a download href=url>: a new top-level tab is a different cookie
+// partition under CHIPS, so the bearer is absent and the route 401s.
+export async function downloadViaBlob(url, filename) {
+    const res = await authFetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed: ${res.status}`);
+    const blob = await res.blob();
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+        const a = document.createElement('a');
+        a.href = objectUrl;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+    }
+    finally {
+        URL.revokeObjectURL(objectUrl);
+    }
+}
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-storage/SKILL.md

@@ -13,8 +13,8 @@ Use app-storage for files that belong to YOUR app. For files the user expects to
 
 **Both helpers ship in `@assembly-js/app-foundation/server`, an installed dependency** — import them; do NOT recreate or rewrite them:
 
-- `getUploadUrl(fileName)` → `{ key, uploadUrl }` — POSTs `{ fileName }` to the platform.
-- `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET.
+- `getUploadUrl(fileName)` → `{ key, uploadUrl }` — POSTs `{ fileName }` to the platform. Takes **one argument** (the file name only). If you were calling it as `getUploadUrl(token, fileName)` (an old two-arg shape), remove the token — auth is in the bearer cookie and the function will throw if a token is passed as the file name.
+- `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET. Takes **one argument** (the storage key only). Same note: remove any leading token argument.
 
 Store the `key` it returns; never construct an S3 key yourself, and never parse the original file name back out of the key — the platform normalizes the name when forming the key, so the stored `key` is not guaranteed to contain your exact `fileName`. Keep the display name as your own metadata (see "Storing and downloading"). `fileName` must be a bare file name (`invoice.pdf`), never a path — the platform rejects any fileName containing `/` or `..`. Don't prefix folders or namespaces onto it; the platform already scopes the key to the workspace and makes it unique. If you need grouping, store that in your own database alongside the key.
 
@@ -26,7 +26,7 @@ The pre-signed URL does not lock the `Content-Type`, so any value works — set
 
 ```typescript
 'use client';
-import { authFetch } from './lib-client';
+import { authFetch } from '@/app/components/lib-client';
 
 export async function uploadFile(file: File) {
   const res = await authFetch('/api/app-storage/upload-url', {
@@ -70,7 +70,9 @@ export async function POST(request: NextRequest) {
 
 Save the returned `key` (plus any metadata like `fileName`/`size`) in your app's own database. Pre-signed download URLs expire within hours, so generate them on demand — never embed one in rendered HTML or a cached server component.
 
-Create a route that returns the pre-signed URL as JSON, then trigger the download from a client component via `authFetch` + a programmatic anchor click. `authFetch` adds the CSRF header and the bearer rides the cookie, so the download route stays authenticated without any token in the URL.
+### Pattern A — route returns a pre-signed S3 URL (no proxy of bytes)
+
+Create a route that returns the pre-signed URL as JSON, then open that URL via a programmatic anchor click. The pre-signed URL carries S3 credentials directly, so no auth cookie is needed to access S3. Use `authFetch` only for the initial request to get the URL.
 
 **Route handler** (`app/api/app-storage/download/route.ts`):
 
@@ -92,6 +94,8 @@ export async function GET(request: NextRequest) {
 **Client-side download trigger:**
 
 ```typescript
+import { authFetch } from '@/app/components/lib-client';
+
 async function downloadFile(key: string) {
   const res = await authFetch(`/api/app-storage/download?key=${encodeURIComponent(key)}`);
   if (!res.ok) throw new Error('Failed to get download URL');
@@ -106,7 +110,18 @@ async function downloadFile(key: string) {
 }
 ```
 
-Do NOT use `<a href>` links to the download route — plain links can't send the CSRF header `authFetch` adds, so the route rejects them with 403. Always use a button with an `onClick` that calls `authFetch`.
+### Pattern B — route returns bytes directly (use `downloadViaBlob`)
+
+When your route fetches from S3 and streams the bytes back instead of a pre-signed URL, use `downloadViaBlob` from `app/components/lib-client.ts`. It calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor — the bearer cookie is sent because the fetch is same-origin, avoiding the CHIPS partition problem that breaks `window.open` and `<a download href=…>` to a new tab.
+
+```typescript
+import { downloadViaBlob } from '@/app/components/lib-client';
+
+// In a button onClick handler:
+await downloadViaBlob(`/api/items/${id}/download`, 'report.pdf');
+```
+
+Do NOT use `<a href>` links to the download route — plain links can't send the CSRF header `authFetch` adds, so the route rejects them with 403. Always use a button with an `onClick` that calls `authFetch` or `downloadViaBlob`.
 
 ## Server needs the bytes (parse / process an uploaded file)