@supersuit/artifacts 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 `@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.36.0
+
+**Private media moves to its own private bucket, and a host without one refuses it.** 0.35.0 kept
+`media: private` files under `<prefix>/<id>/private/` in the same bucket as public assets and
+never called `makePublic` on them. That is no protection on a bucket that carries a bucket-wide
+public read grant: every "private" object was readable by anyone holding its URL.
+
+- `createArtifactAssets(bucket, prefix, { privateBucket })`. With `privateBucket`, `putPrivate`,
+  `signPrivateUpload`, `finishPrivateUpload` and `privateUrl` use it (same `<prefix>/<id>/private/`
+  keys); `put`, `signUpload`, `finishUpload`, covers and narration stay on `bucket`. `deletePage`
+  clears the page from both. Passing the public bucket again as the private one throws.
+- Without `privateBucket` the four private methods are not defined, so the host fails closed:
+  `POST /api/artifacts` refuses a page with `media: private` (or a republish of a page that already
+  keeps private media) with 501 and saves nothing, and `?private=1` uploads answer 501, all with
+  the same words naming `privateBucket`.
+- `PRIVATE_READ_TTL_MS` (exported, `60 * 60 * 1000`): the life of a signed V4 read URL. One is
+  minted per private file on every render that passed the per-reader gate, and none for a revoked
+  or expired link.
+- DETECTOR: your host passes `media: private` pages and calls `createArtifactAssets(bucket, prefix)`
+  with two arguments; or `gcloud storage buckets get-iam-policy` on your bucket lists `allUsers`
+  and you have objects under `*/private/`.
+- REMEDY: create a separate bucket (uniform access, public access prevention enforced, object
+  access for the host's service account only), pass it as `privateBucket`, give it CORS for `PUT`
+  from your origin if browsers upload to it directly, and republish any page whose private media
+  sits in the public bucket (then delete those old objects). A host that publishes no private
+  media needs nothing; until it adds a private bucket, `media: private` is refused.
+- TESTS: `src/artifacts/assets.test.ts` (private media), `src/routes/private-media.test.tsx`
+  (publishing media: private), `src/routes/per-reader.test.tsx` (mints a fresh signed URL on every
+  passing render), `src/artifacts/index.test.ts`.
+
 ## 0.35.0
 
 **Per-reader links, private media, video with sound, quiet views, and expiry.** A page can now go

package/README.md

@@ -22,7 +22,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactRoutes(config)` | Every route handler: the page, its metadata, the publish API, the share card, the reader sign-in exchange, access control |
 | `createArtifactStore(db, path)` | Firestore store for pages and their version history, under any collection path |
 | `createReadersStore(db, path)` | The record for confidential pages: allowlist, agreements, reading sessions, flags |
-| `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
+| `createArtifactAssets(bucket, prefix, { privateBucket? })` | Uploaded images for a page, in a Cloud Storage bucket; private media in a separate private bucket |
 | `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
 | `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
 | `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
@@ -849,6 +849,14 @@ media: private
 
 `links: per-reader` shuts the page to everyone who does not arrive through a valid, unrevoked, unexpired link. It cannot be combined with `password`, `access` or `comments_visible: readers` (readers never see each other's comments). `media: private` keeps body media under the page's private prefix; `.mp4` and `.m4a` (and `.mp3`) are supported, and `sound:` at the start of a video's alt makes it a clip with controls and sound. Both lines are sticky: republishing a file that leaves them out changes nothing.
 
+### Private media lives in its own bucket
+
+`media: private` needs a private store: `createArtifactAssets(bucket, prefix, { privateBucket })`. Private files go to `privateBucket` under `<prefix>/<id>/private/`; covers, images and narration stay on the public `bucket`. Without `privateBucket` the private methods are not defined, and the host refuses private media with 501 at every door: publishing a page with `media: private` (or republishing a page that already keeps it), and `?private=1` uploads. Nothing is saved. This is on purpose: a public bucket often carries a bucket-wide public read grant, so an object written there is readable by anyone who has its URL, whatever the object's own settings say.
+
+The private bucket must be a different bucket from the public one (passing the same bucket twice throws), with uniform bucket-level access, public access prevention enforced, and object access granted only to the host's own service account. The page signs a V4 read URL per private file on every render that passed the per-reader gate, valid `PRIVATE_READ_TTL_MS` (one hour); a revoked or expired link renders nothing and mints nothing. A reader revoked after a render can keep loading a URL already handed to them for at most that hour. Expiry's `deletePage` clears the page from both buckets.
+
+If the publisher uploads straight to the private bucket from a browser (`?private=1` on `UPLOAD`), give that bucket a CORS rule allowing `PUT` from your origin with the `content-type` and `cache-control` headers; a reader's browser playing a signed URL needs `GET` (and `HEAD`) from your origin only if your player fetches it with CORS.
+
 Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `VIEWS`, `SEEN`, and `sweepExpired`.
 
 | Route | Who | What |
@@ -868,7 +876,7 @@ A view is the page rendered in a real browser, visible, for at least 2 seconds.
 
 ### Expiry
 
-`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
+`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
 
 ## Brand packs
 

package/lib/artifacts/assets.d.ts

@@ -35,15 +35,27 @@ export interface ArtifactAssets {
     }>;
     /** After a signed private upload: `private:<stored name>`, or null if nothing arrived. */
     finishPrivateUpload?(id: string, name: string, digest: string): Promise<string | null>;
-    /** A signed read URL for a stored private name, valid one hour. */
+    /** A V4 signed read URL for a stored private name, valid PRIVATE_READ_TTL_MS (one hour). */
     privateUrl?(id: string, stored: string): Promise<string>;
-    /** Delete every object under `<prefix>/<id>/`; returns how many. */
+    /** Delete every object under `<prefix>/<id>/`, in the public bucket and the private one; returns how many. */
     deletePage?(id: string): Promise<number>;
 }
 /** A reference to a private file as it appears in a page: `private:<stored name>`. */
 export declare const PRIVATE_REF: RegExp;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export declare const ASSET_DIGEST: RegExp;
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export declare const PRIVATE_READ_TTL_MS: number;
+export interface ArtifactAssetsOptions {
+    /**
+     * The bucket private media lives in. It must be a different bucket from the public one, with
+     * uniform access, public access prevention enforced, and object access granted only to the
+     * host's own service account. Without it the private methods are not defined at all, so a
+     * `media: private` page is refused instead of being stored where anyone could read it by URL.
+     */
+    privateBucket?: Bucket;
+}
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export declare const ASSET_NAME: RegExp;
 export declare const ASSET_TYPES: Record<string, string>;
@@ -67,4 +79,4 @@ export declare function contentTypeFor(name: string): string | undefined;
 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;
+export declare function createArtifactAssets(bucket: Bucket, prefix: string, options?: ArtifactAssetsOptions): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -10,6 +10,9 @@ export const PRIVATE_REF = /^private:([A-Za-z0-9][A-Za-z0-9._-]{0,140})$/;
 /** 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';
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export const PRIVATE_READ_TTL_MS = 60 * 60 * 1000;
 /** 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 = {
@@ -52,9 +55,13 @@ export function storedName(name, digest) {
     // 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)}`;
 }
-export function createArtifactAssets(bucket, prefix) {
+export function createArtifactAssets(bucket, prefix, options = {}) {
     const clean = prefix.replace(/^\/+|\/+$/g, '');
-    return {
+    const priv = options.privateBucket;
+    // The same bucket twice would put "private" media back where a public read grant reaches it.
+    if (priv && priv.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const assets = {
         async put(id, name, bytes, contentType) {
             const key = `${clean}/${id}/${hashedName(name, bytes)}`;
             const file = bucket.file(key);
@@ -135,36 +142,46 @@ export function createArtifactAssets(bucket, prefix) {
             const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
             return url;
         },
+        async deletePage(id) {
+            // An empty or path-shaped id would make the prefix wider than one page.
+            if (!ARTIFACT_ID_RE.test(id))
+                throw new Error('not an artifact id');
+            let n = 0;
+            for (const b of priv ? [bucket, priv] : [bucket]) {
+                const [files] = await b.getFiles({ prefix: `${clean}/${id}/` });
+                for (const f of files)
+                    await f.delete();
+                n += files.length;
+            }
+            return n;
+        },
+    };
+    if (!priv)
+        return assets;
+    const privateFile = (id, stored) => priv.file(`${clean}/${id}/private/${stored}`);
+    return {
+        ...assets,
         async putPrivate(id, name, bytes, contentType) {
             const stored = hashedName(name, bytes);
-            await bucket.file(`${clean}/${id}/private/${stored}`).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
+            await privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
             return `private:${stored}`;
         },
         async signPrivateUpload(id, name, digest, contentType) {
             const stored = storedName(name, digest);
             const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600' };
-            const [uploadUrl] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
+            const [uploadUrl] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
             return { uploadUrl, headers, url: `private:${stored}` };
         },
         async finishPrivateUpload(id, name, digest) {
             const stored = storedName(name, digest);
-            const [there] = await bucket.file(`${clean}/${id}/private/${stored}`).exists();
+            const [there] = await privateFile(id, stored).exists();
             return there ? `private:${stored}` : null;
         },
         async privateUrl(id, stored) {
             if (!PRIVATE_REF.test(`private:${stored}`))
                 throw new Error('not a private file name');
-            const [url] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            const [url] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + PRIVATE_READ_TTL_MS });
             return url;
         },
-        async deletePage(id) {
-            // An empty or path-shaped id would make the prefix wider than one page.
-            if (!ARTIFACT_ID_RE.test(id))
-                throw new Error('not an artifact id');
-            const [files] = await bucket.getFiles({ prefix: `${clean}/${id}/` });
-            for (const f of files)
-                await f.delete();
-            return files.length;
-        },
     };
 }

package/lib/artifacts/index.d.ts

@@ -4,7 +4,7 @@ export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narra
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
 export { isPublishAuthed, isPublisherAuthed, type PublishAuth } from './auth.js';
 export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS, type Publisher } from './publisher.js';
-export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS, type ArtifactAssets, type ArtifactAssetsOptions } 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, type ReaderSummary } from './readers-store.js';

package/lib/artifacts/index.js

@@ -4,7 +4,7 @@ export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narra
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
 export { isPublishAuthed, isPublisherAuthed } from './auth.js';
 export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS } from './publisher.js';
-export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS } 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.js

@@ -41,6 +41,8 @@ import { createVoiceRoutes } from './voice-routes.js';
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
 /** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
 const VERSION_N = /^[1-9]\d{0,5}$/;
+/** What a host with no private store answers to private media, in words that say what to set up. */
+const NO_PRIVATE_STORE = 'this host keeps no private store, so media: private is refused and nothing was published. Give createArtifactAssets a privateBucket (its own bucket, never the public one) to keep private media';
 async function defaultReadCookie(name) {
     const { cookies } = await import('next/headers');
     return (await cookies()).get(name)?.value;
@@ -697,6 +699,8 @@ export function createArtifactRoutes(config) {
         const [sessions, flags, acks] = await Promise.all([config.readers.sessions(id), config.readers.flags(id), config.readers.acks(id)]);
         return NextResponse.json({ id, title: a.title, access: a.access ?? null, views: a.views, ...summarize(sessions, flags), acks: acks.map((k) => ({ email: k.email, name: k.name, at: k.at })) }, { headers: { 'cache-control': 'no-store' } });
     }
+    /** Whether this host can store and serve private media: both halves come from a private bucket. */
+    const keepsPrivateMedia = () => Boolean(config.assets?.putPrivate && config.assets.privateUrl);
     async function POST(request) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
@@ -705,6 +709,11 @@ export function createArtifactRoutes(config) {
         if (!parsed.ok)
             return NextResponse.json({ error: parsed.error }, { status: 400 });
         const id = request.nextUrl.searchParams.get('id') ?? parsed.meta.id ?? undefined;
+        // Fail closed: private media needs a private store. Without one the media would have to sit in
+        // the public bucket, which may carry a bucket-wide public read grant, so nothing is saved.
+        // `media:` is sticky, so a stored page that already keeps private media counts too.
+        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await store.get(id))?.privateMedia)))
+            return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         if (id && parsed.meta.state) {
             const existing = await store.get(id);
             const changed = shapeChanges(existing?.state, parsed.meta.state);
@@ -759,7 +768,7 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'this host does not store assets' }, { status: 501 });
         const priv = request.nextUrl.searchParams.get('private') === '1';
         if (priv && !config.assets.putPrivate)
-            return NextResponse.json({ error: 'this host keeps no private media' }, { status: 501 });
+            return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
@@ -806,7 +815,7 @@ export function createArtifactRoutes(config) {
         const priv = request.nextUrl.searchParams.get('private') === '1';
         if (priv) {
             if (!assets?.signPrivateUpload || !assets.finishPrivateUpload)
-                return NextResponse.json({ error: 'this host keeps no private media' }, { status: 501 });
+                return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         }
         else if (!assets?.signUpload || !assets.finishUpload)
             return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "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",