@supersuit/artifacts 0.37.0 → 0.38.0

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.38.0
+
+**Readers' voice memos live in the private bucket.** A memo left on a page (`comments/<memo>`, or a
+reader's own `personal/<dir>/<memo>`) was written to the PUBLIC bucket. Every URL the package handed
+out was signed, but that bucket carries a bucket-wide public read grant, so the memo itself answered
+an unsigned GET to anyone holding its path. Memos are now written to and read from the private
+bucket (`privateBucket`), under the same key. A host with no private bucket defines no memo method,
+so memos stay on the reader's device instead of going anywhere public.
+
+DETECTOR: an unsigned `curl -o /dev/null -w '%{http_code}'` of
+`https://storage.googleapis.com/<public bucket>/<prefix>/<id>/comments/<memo>.webm` answers 200.
+
+REMEDY: take 0.38.0, then move what is already there:
+`node scripts/migrate-memos-private.mjs --public <bucket> --private <bucket> --prefix tenants/<t>/artifacts`
+(copies each memo to the same key in the private bucket, confirms it arrived, then deletes the
+public one; safe to re-run; `--dry-run` lists). Until a memo is moved the package reads it from the
+public bucket, so nothing stops playing during the move. The same unsigned GET then answers 403.
+
+Tests: `assets.test.ts` (memos sign, size, read and play in the private bucket and never touch the
+public one; an unmoved memo is still read; no private bucket, no memo methods),
+`migrate-memos.test.ts` (moves only memos, never deletes a public memo whose copy did not arrive,
+dry run, same bucket refused).
+
 ## 0.37.0
 
 **A broadcast is its own page kind.** `template: broadcast` in front matter makes a page one

package/README.md

@@ -673,12 +673,13 @@ recognition, the words appear in the box as the reader speaks. A memo stops at t
 
 Recordings go up through the same `uploads/<name>` route the publisher uses, to
 `<page>/comments/<memo>.<ext>` or, for a signed-in reader's personal note,
-`<page>/personal/<dir>/<memo>.<ext>`. They are never made public: playback is a signed URL
-issued beside the comment or note it belongs to. That needs the four audio methods
-`createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`, `audioUrl`); a host
-with its own `ArtifactAssets` and none of them keeps memos on the reader's device. On a bucket
-with bucket-wide public read, a recording is readable by anyone holding its path (the paths are
-unguessable); keep the bucket per-object public to have the signed-URL guarantee.
+`<page>/personal/<dir>/<memo>.<ext>`, in the PRIVATE bucket (`privateBucket`, the same one
+`media: private` uses). They are never made public: playback is a signed URL, valid about an hour,
+issued beside the comment or note it belongs to, and an unsigned GET is refused (403). That needs the
+four audio methods `createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`,
+`audioUrl`), which it defines only when it is given a private bucket; a host without one, or with
+its own `ArtifactAssets` and none of them, keeps memos on the reader's device. Memos recorded before
+0.38.0 sat in the public bucket: `scripts/migrate-memos-private.mjs` moves them (see CHANGELOG).
 
 To transcribe on the server, pass `transcribe` and add the route. The key stays on the server;
 without `transcribe` the route answers 404 and readers keep the browser's live transcript (or an

package/lib/artifacts/assets.js

@@ -108,12 +108,44 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        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}`);
+    // READERS' VOICE MEMOS LIVE IN THE PRIVATE BUCKET (0.38.0). Until then they went to the public
+    // bucket, unlisted and read through signed URLs, but a bucket-wide public read grant served any
+    // memo to anyone holding its path, unsigned. A memo recorded before 0.38.0 is still read from the
+    // public bucket until scripts/migrate-memos-private.mjs moves it; nothing new is written there.
+    const memo = (id, path) => priv.file(`${clean}/${id}/${path}`);
+    const legacyMemo = (id, path) => bucket.file(`${clean}/${id}/${path}`);
+    const memoFile = async (id, path) => {
+        const f = memo(id, path);
+        if ((await f.exists())[0])
+            return f;
+        const old = legacyMemo(id, path);
+        return (await old.exists())[0] ? old : null;
+    };
+    return {
+        ...assets,
         // The size cap rides in the signature (`x-goog-content-length-range`), so the bucket itself
         // refuses an oversize body; the browser must send the returned headers verbatim.
         async signAudioUpload(id, path, contentType) {
             const range = `0,${MAX_AUDIO_BYTES}`;
             const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600', 'x-goog-content-length-range': range };
-            const [uploadUrl] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({
+            const [uploadUrl] = await memo(id, path).getSignedUrl({
                 version: 'v4',
                 action: 'write',
                 expires: Date.now() + 15 * 60 * 1000,
@@ -123,44 +155,24 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             return { uploadUrl, headers };
         },
         async audioSize(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [meta] = await file.getMetadata();
             return Number(meta.size ?? 0);
         },
         async readAudio(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [bytes] = await file.download();
             return bytes;
         },
         async audioUrl(id, path) {
-            const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            const file = (await memoFile(id, path)) ?? memo(id, path);
+            const [url] = await file.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 privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });

package/lib/artifacts/index.d.ts

@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';

package/lib/artifacts/index.js

@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 // Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';

package/lib/artifacts/migrate-memos.d.ts

@@ -0,0 +1,14 @@
+import type { Bucket } from '@google-cloud/storage';
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export declare const MEMO_KEY: RegExp;
+export interface MemoMigration {
+    moved: string[];
+    alreadyPrivate: string[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+export declare function migrateMemosToPrivate(bucket: Bucket, privateBucket: Bucket, prefix: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<MemoMigration>;

package/lib/artifacts/migrate-memos.js

@@ -0,0 +1,36 @@
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export const MEMO_KEY = /^[^/]+\/(?:comments\/[^/]+|personal\/[^/]+\/[^/]+)\.(?:webm|m4a|mp4|ogg|wav)$/;
+export async function migrateMemosToPrivate(bucket, privateBucket, prefix, { dryRun = false } = {}) {
+    if (privateBucket.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const clean = prefix.replace(/^\/+|\/+$/g, '');
+    const [files] = await bucket.getFiles({ prefix: `${clean}/` });
+    const out = { moved: [], alreadyPrivate: [], failed: [] };
+    for (const f of files) {
+        const rel = f.name.slice(clean.length + 1);
+        if (!MEMO_KEY.test(rel))
+            continue;
+        try {
+            const dest = privateBucket.file(f.name);
+            if ((await dest.exists())[0]) {
+                if (!dryRun)
+                    await f.delete();
+                out.alreadyPrivate.push(f.name);
+                continue;
+            }
+            if (dryRun) {
+                out.moved.push(f.name);
+                continue;
+            }
+            await f.copy(dest);
+            if (!(await dest.exists())[0])
+                throw new Error('the copy did not arrive in the private bucket');
+            await f.delete();
+            out.moved.push(f.name);
+        }
+        catch (e) {
+            out.failed.push({ key: f.name, error: e.message });
+        }
+    }
+    return out;
+}

package/package.json

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