@supersuit/artifacts 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.4.1 (2026-09-26)
+
+**Big files upload straight to the bucket.**
+
+- A route handler on Vercel refuses a body over 4.5 MB (`FUNCTION_PAYLOAD_TOO_LARGE`), about five
+  minutes of narration, so a long page's audio could never publish; `PUT_ASSET`'s own 16 MiB cap
+  was never reached. New route `UPLOAD` (`POST /api/artifacts/<id>/uploads/<name>`, publish key,
+  JSON `{ digest }`) returns a v4 signed URL and the headers to send; the publisher PUTs the bytes
+  there, then calls again with `{ digest, done: true }`, which makes the object readable and
+  returns its URL (409 if nothing arrived). The key is the same hashed name `put()` writes, with
+  the same `immutable` cache header. `ArtifactAssets` gains optional `signUpload` and
+  `finishUpload`; `createArtifactAssets` implements both. `storedName`, `hashedName` and
+  `ASSET_DIGEST` are exported.
+- **DETECTOR:** publishing a page whose narration is longer than about five minutes fails with
+  `narration upload failed 413: ... FUNCTION_PAYLOAD_TOO_LARGE`.
+- **REMEDY:** add `app/api/artifacts/[id]/uploads/[name]/route.ts` exporting `POST` that calls
+  the routes' `UPLOAD`, the same shape as the assets route. The bucket's service account needs no
+  new permission when the host signs with a service-account key. Until the route exists the
+  publisher gets a 404 and falls back to `PUT_ASSET`.
+- **Tests:** signing targets put()'s key with its cache header; finishing refuses a missing
+  object; the route's refusals match `PUT_ASSET`'s, a bad digest is 400, and a host whose assets
+  cannot sign answers 501.
+
 ## 0.4.0 (2026-09-26)
 
 **Light and dark modes, a table of contents, and an animated ground.**

package/lib/artifacts/assets.d.ts

@@ -2,7 +2,21 @@ import type { Bucket } from '@google-cloud/storage';
 export interface ArtifactAssets {
     /** Store `bytes` for artifact `id` under `name`; return the public URL. */
     put(id: string, name: string, bytes: Buffer, contentType: string): Promise<string>;
+    /**
+     * A signed URL the publisher PUTs a big file to directly, skipping the route handler.
+     * `digest` is the first 8 hex of the bytes' sha256, so the key is the one put() would use.
+     * Optional: a host without it answers 501 and the publisher falls back to put().
+     */
+    signUpload?(id: string, name: string, digest: string, contentType: string): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+        url: string;
+    }>;
+    /** After a signed upload: make it readable and return its URL, or null if nothing arrived. */
+    finishUpload?(id: string, name: string, digest: string): Promise<string | null>;
 }
+/** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
+export declare const ASSET_DIGEST: RegExp;
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export declare const ASSET_NAME: RegExp;
 export declare const ASSET_TYPES: Record<string, string>;
@@ -24,4 +38,6 @@ export declare function contentTypeFor(name: string): string | undefined;
  * URL and stay cached, which is the whole benefit.
  */
 export declare function hashedName(name: string, bytes: Buffer): string;
+/** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
+export declare function storedName(name: string, digest: string): string;
 export declare function createArtifactAssets(bucket: Bucket, prefix: string): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -3,6 +3,9 @@
 // publisher shelled out to gsutil against the maintainer's bucket, which no other operator
 // could do, so every operator gets the same door: PUT bytes with their key, get a URL back.
 import { createHash } from 'node:crypto';
+/** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
+export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
+const CACHE_CONTROL = 'public, max-age=31536000, immutable';
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
 export const ASSET_TYPES = {
@@ -35,7 +38,10 @@ export function contentTypeFor(name) {
  * URL and stay cached, which is the whole benefit.
  */
 export function hashedName(name, bytes) {
-    const digest = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    return storedName(name, createHash('sha256').update(bytes).digest('hex').slice(0, 8));
+}
+/** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
+export function storedName(name, digest) {
     const dot = name.lastIndexOf('.');
     // A name with no extension is legal here, so append rather than assume there is a dot.
     return dot <= 0 ? `${name}.${digest}` : `${name.slice(0, dot)}.${digest}${name.slice(dot)}`;
@@ -49,7 +55,7 @@ export function createArtifactAssets(bucket, prefix) {
             await file.save(bytes, {
                 contentType,
                 resumable: false,
-                metadata: { cacheControl: 'public, max-age=31536000, immutable' },
+                metadata: { cacheControl: CACHE_CONTROL },
             });
             try {
                 await file.makePublic();
@@ -59,5 +65,35 @@ export function createArtifactAssets(bucket, prefix) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        // A route handler on Vercel refuses a body over 4.5 MB (FUNCTION_PAYLOAD_TOO_LARGE), which is
+        // about five minutes of narration. An hour-long paper's audio (~55 MB) could never publish.
+        // So a big file goes to the bucket directly, on a URL signed with the host's own service
+        // account, to the same hashed key and with the same cache header put() writes.
+        async signUpload(id, name, digest, contentType) {
+            const key = `${clean}/${id}/${storedName(name, digest)}`;
+            const headers = { 'content-type': contentType, 'cache-control': CACHE_CONTROL };
+            const [uploadUrl] = await bucket.file(key).getSignedUrl({
+                version: 'v4',
+                action: 'write',
+                expires: Date.now() + 15 * 60 * 1000,
+                contentType,
+                extensionHeaders: { 'cache-control': CACHE_CONTROL },
+            });
+            return { uploadUrl, headers, url: `https://storage.googleapis.com/${bucket.name}/${key}` };
+        },
+        async finishUpload(id, name, digest) {
+            const key = `${clean}/${id}/${storedName(name, digest)}`;
+            const file = bucket.file(key);
+            const [there] = await file.exists();
+            if (!there)
+                return null;
+            try {
+                await file.makePublic();
+            }
+            catch {
+                // uniform bucket access: already public
+            }
+            return `https://storage.googleapis.com/${bucket.name}/${key}`;
+        },
     };
 }

package/lib/artifacts/index.d.ts

@@ -3,7 +3,7 @@ export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, type ArtifactStore, type ArtifactRecord, type SaveResult } from './store.js';
 export { isPublishAuthed } from './auth.js';
-export { createArtifactAssets, contentTypeFor, ASSET_NAME, type ArtifactAssets } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc } from './readers-store.js';

package/lib/artifacts/index.js

@@ -3,7 +3,7 @@ export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId } from './store.js';
 export { isPublishAuthed } from './auth.js';
-export { createArtifactAssets, contentTypeFor, ASSET_NAME } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';

package/lib/routes/artifacts.d.ts

@@ -102,6 +102,18 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         name: string;
         url: string;
     }>>;
+    UPLOAD: (request: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+            name: string;
+        }>;
+    }) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        id: string;
+        name: string;
+        url: string;
+    }>>;
     SHARE_IMAGE: (_request: NextRequest, { params }: Params) => Promise<Response>;
     ENTER: (request: NextRequest) => Promise<NextResponse<unknown>>;
     LEAVE: (request: NextRequest) => Promise<NextResponse<unknown>>;

package/lib/routes/artifacts.js

@@ -9,7 +9,7 @@ import { ArtifactMarkdown } from '../artifacts/render.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
 import { shapeChanges } from '../artifacts/state.js';
-import { ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
+import { ASSET_DIGEST, ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
 import { themedPack } from '../brand/theme.js';
 import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
@@ -358,6 +358,40 @@ export function createArtifactRoutes(config) {
         const url = await config.assets.put(id, name, bytes, type);
         return NextResponse.json({ id, name, url }, { status: 201 });
     }
+    /**
+     * POST /api/artifacts/<id>/uploads/<name> with `{ digest }`: a signed URL to PUT a big file to
+     * directly, because a route handler cannot take one (Vercel caps a body at 4.5 MB). Then the
+     * same call with `{ digest, done: true }` makes it readable and returns its URL; 409 when the
+     * bytes never arrived. 501 on a host whose assets cannot sign, so the publisher falls back.
+     */
+    async function UPLOAD(request, { params }) {
+        if (!isPublishAuthed(request, config.publishKey()))
+            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        const assets = config.assets;
+        if (!assets?.signUpload || !assets.finishUpload)
+            return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });
+        const { id, name } = await params;
+        if (!ARTIFACT_ID.test(id))
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        if (!(await store.get(id)))
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        if (!ASSET_NAME.test(name))
+            return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
+        const type = contentTypeFor(name);
+        if (!type)
+            return NextResponse.json({ error: 'asset type not allowed; use webp, png, jpg, gif, mp3 or json' }, { status: 415 });
+        const body = (await request.json().catch(() => ({})));
+        const digest = typeof body.digest === 'string' ? body.digest : '';
+        if (!ASSET_DIGEST.test(digest))
+            return NextResponse.json({ error: 'digest must be the first 8 hex of the sha256 of the bytes' }, { status: 400 });
+        if (body.done === true) {
+            const url = await assets.finishUpload(id, name, digest);
+            if (!url)
+                return NextResponse.json({ error: 'nothing was uploaded to that url' }, { status: 409 });
+            return NextResponse.json({ id, name, url }, { status: 201 });
+        }
+        return NextResponse.json({ id, name, ...(await assets.signUpload(id, name, digest, type)) }, { status: 201 });
+    }
     /** GET /<id>/share.png: the page's title card. 404 when the pack draws none, so a
      *  tenant on the static default never serves a half-styled card. */
     async function SHARE_IMAGE(_request, { params }) {
@@ -379,5 +413,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",