@supersuit/artifacts 0.11.1 → 0.12.0

package/lib/routes/personal-routes.d.ts

@@ -10,6 +10,8 @@ export type PersonalRoutesContext = {
     pageUrl: (id: string) => string;
     signInOrigin?: string;
     siteUrl: string;
+    /** A signed URL to play one of the reader's own recordings. */
+    audioUrl?: (id: string, path: string) => Promise<string>;
 };
 type Params = {
     params: Promise<{

package/lib/routes/personal-routes.js

@@ -12,7 +12,8 @@ import { NextResponse } from 'next/server';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { GRANT_COOKIE, decide, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
-import { validatePersonal } from '../artifacts/personal-store.js';
+import { personalAudioDir, validatePersonal } from '../artifacts/personal-store.js';
+import { isPersonalAudioPath } from '../artifacts/audio.js';
 const MAX_BODY = 16 * 1024;
 export function createPersonalRoutes(ctx) {
     const json = (body, status = 200) => NextResponse.json(body, { status, headers: { 'cache-control': 'no-store' } });
@@ -43,7 +44,16 @@ export function createPersonalRoutes(ctx) {
             return { error: json({ error: 'sign in to keep notes everywhere', device: true, signIn }, 401) };
         return { id, uid: reader.uid, personal: ctx.personal };
     }
-    const list = async (o) => json({ notes: await o.personal.list(o.id, o.uid) });
+    // Each note with a recording carries a signed URL to play it, issued to its owner here and nowhere else.
+    const list = async (o) => {
+        const notes = await o.personal.list(o.id, o.uid);
+        const dir = personalAudioDir(o.uid);
+        if (ctx.audioUrl)
+            for (const n of notes)
+                if (isPersonalAudioPath(n.value.audio, dir))
+                    n.audioUrl = await ctx.audioUrl(o.id, n.value.audio);
+        return json({ notes });
+    };
     // A write carries the reader's cookies; a browser always names its Origin on one, so a foreign one is refused.
     const foreign = (req) => { const origin = req.headers.get('origin'); return origin !== null && origin !== siteOrigin; };
     async function PERSONAL_GET(req, { params }) {
@@ -75,6 +85,9 @@ export function createPersonalRoutes(ctx) {
         const v = validatePersonal(b.value);
         if (!v.ok)
             return json({ error: v.error }, 400);
+        // A note's recording is one this reader uploaded as a personal note: never a comment's, never another reader's.
+        if (v.value.audio !== undefined && !isPersonalAudioPath(v.value.audio, personalAudioDir(o.uid)))
+            return json({ error: 'a note\'s audio is the path its upload returned' }, 400);
         if (b.entry !== undefined) {
             if (typeof b.entry !== 'string' || !(await o.personal.replace(o.id, o.uid, b.entry, v.value)))
                 return json({ error: 'no note of yours with that id' }, 404);

package/lib/routes/state-routes.d.ts

@@ -24,6 +24,9 @@ export type StateRoutesContext = {
     /** The page owner's sign-in email. Signed in as them, a page's comments show every entry with
      *  full names, whatever `comments_visible:` says. */
     ownerEmail?: string;
+    /** A signed URL to play a comment's recording. Called only for `comments/` paths, and only for
+     *  comments the asker is already being shown. Without it a recording has no play control. */
+    audioUrl?: (id: string, path: string) => Promise<string>;
 };
 type Params = {
     params: Promise<{

package/lib/routes/state-routes.js

@@ -16,6 +16,7 @@ import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../arti
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
 import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters, slotVisibility } from '../artifacts/state.js';
 import { COMMENTS_SLOT, validateComment } from '../artifacts/comments.js';
+import { isCommentAudioPath } from '../artifacts/audio.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
 import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
@@ -70,6 +71,18 @@ export function createStateRoutes(ctx) {
     /** Comments are on for this page: the slot exists because `comments:` put it there. */
     const commentsOn = (a) => !!a.comments && a.comments !== 'off' && Object.hasOwn(a.state.slots, COMMENTS_SLOT);
     const writerFor = (r) => ({ key: readerKeyFor.signedIn(r.uid), uid: r.uid, email: r.email, name: r.name, anonymous: false });
+    /** Beside each comment row with a recording, a signed URL to play it. Only ever a `comments/`
+     *  path: a personal recording can never be named by a comment, and is never signed here. */
+    async function withAudioUrls(id, rows) {
+        if (!ctx.audioUrl)
+            return rows;
+        for (const r of rows) {
+            const audio = r.value?.audio;
+            if (isCommentAudioPath(audio))
+                r.audioUrl = await ctx.audioUrl(id, audio);
+        }
+        return rows;
+    }
     async function viewBody(a, reader, readerKey) {
         const allow = reader && ctx.readers && a.access ? await ctx.readers.allowList(a.id) : [];
         const entries = await ctx.state.entries(a.id);
@@ -81,6 +94,11 @@ export function createStateRoutes(ctx) {
                 .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id))
                 .map((e) => ({ id: e.id, name: e.writer.name?.trim() || 'a reader', value: e.value, at: e.at, mine: e.readerKey === readerKey }));
         }
+        if (commentsOn(a) && slots[COMMENTS_SLOT]) {
+            const v = slots[COMMENTS_SLOT];
+            await withAudioUrls(a.id, Array.isArray(v.mine) ? v.mine : []);
+            await withAudioUrls(a.id, v.shared ?? []);
+        }
         return {
             reader: reader ? { firstName: firstName(reader, allow) } : null,
             canWrite: !!reader || effectiveWriters(a.state, a.access) === 'anyone',
@@ -217,6 +235,10 @@ export function createStateRoutes(ctx) {
                 const c = validateComment(b.value, (cid) => seen.get(cid) ?? null);
                 if (!c.ok)
                     return json({ error: c.error }, 400);
+                // A shared comment's recording is one uploaded as a comment, never a path elsewhere under the
+                // page: naming a personal recording here would get it signed for the publisher.
+                if (c.value.audio !== undefined && !isCommentAudioPath(c.value.audio))
+                    return json({ error: 'a comment\'s audio is the path its upload returned' }, 400);
                 // An edit keeps the comment where it is in its thread: a reply stays a reply to the same one.
                 if (op === 'replace' && seen.has(entryId) && (seen.get(entryId).parent ?? null) !== (c.value.parent ?? null))
                     return json({ error: 'an edit cannot move a comment into or out of a thread' }, 400);
@@ -269,6 +291,8 @@ export function createStateRoutes(ctx) {
         const rows = responsesOf(await ctx.state.entries(id));
         if (req.nextUrl.searchParams.get('format') === 'csv')
             return new NextResponse(responsesCsv(rows), { headers: { 'content-type': 'text/csv; charset=utf-8', 'cache-control': 'no-store' } });
+        // The publisher hears a shared comment's recording from here; the rows are signed in place.
+        await withAudioUrls(id, rows.filter((r) => r.slot === COMMENTS_SLOT));
         return json({ id, title: a.title, responses: rows });
     }
     return { STATE_GET, STATE_POST, RESPONSES };

package/lib/routes/voice-routes.d.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+import type { StateStore } from '../artifacts/state-store.js';
+import { type PersonalStore } from '../artifacts/personal-store.js';
+import type { ArtifactStore } from '../artifacts/store.js';
+import type { ReadersStore } from '../artifacts/readers-store.js';
+import type { ArtifactAssets } from '../artifacts/assets.js';
+import type { Transcriber } from '../artifacts/transcribe.js';
+/** Host transcriptions per reader per page per hour. */
+export declare const TRANSCRIBE_PER_HOUR = 20;
+export type VoiceRoutesContext = {
+    store: ArtifactStore;
+    state?: StateStore;
+    personal?: PersonalStore;
+    readers?: ReadersStore;
+    assets?: ArtifactAssets;
+    transcribe?: Transcriber;
+    readerSecret: () => string | undefined;
+    pageUrl: (id: string) => string;
+    signInOrigin?: string;
+    siteUrl: string;
+    clientIp?: (req: NextRequest) => string;
+};
+type Params = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+export declare function createVoiceRoutes(ctx: VoiceRoutesContext): {
+    TRANSCRIBE: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    readerUpload: (req: NextRequest, id: string, name: string, body: {
+        audio?: unknown;
+        done?: unknown;
+    }) => Promise<NextResponse<unknown>>;
+};
+export {};

package/lib/routes/voice-routes.js

@@ -0,0 +1,176 @@
+// Readers' voice memos: the upload, and the host's transcription of it.
+//
+//   POST /api/artifacts/<id>/uploads/<memo>.<ext>  { audio: 'comment'|'personal' [, done: true] }
+//        the same UPLOAD route the publisher uses, dispatched here when the body names `audio`:
+//        a signed URL to PUT one recording to, then `done` to confirm it arrived
+//   POST /api/artifacts/<id>/transcribe            { asset: <path the upload returned> }
+//
+// Who may upload or transcribe: for a shared comment, whoever may write the page's comments slot
+// (the same doors the state POST opens: password, access, agreement, `comments:` writers); for a
+// personal note, a signed-in reader, into a directory only their uid derives. A reader who is not
+// signed in keeps a personal memo on their device and never reaches this file.
+//
+// The transcription key lives in `ctx.transcribe`'s closure and is never read here. Every
+// failure of the service answers one fixed line: whatever it threw is dropped, never echoed.
+import { createHash } from 'node:crypto';
+import { NextResponse } from 'next/server';
+import { ARTIFACT_ID_RE } from './ids.js';
+import { GRANT_COOKIE, decide, signInUrl, verifyGrant } from '../artifacts/reader.js';
+import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
+import { ANON_WRITES_PER_MINUTE, effectiveWriters } from '../artifacts/state.js';
+import { COMMENTS_SLOT } from '../artifacts/comments.js';
+import { personalAudioDir } from '../artifacts/personal-store.js';
+import { MAX_AUDIO_BYTES, MEMO_NAME, audioTypeFor, commentAudioPath, isCommentAudioPath, isPersonalAudioPath, personalAudioPath, } from '../artifacts/audio.js';
+import { ANON_COOKIE, rateKey } from './state-routes.js';
+/** Host transcriptions per reader per page per hour. */
+export const TRANSCRIBE_PER_HOUR = 20;
+const ANON_ID = /^[A-Za-z0-9]{24}$/;
+export function createVoiceRoutes(ctx) {
+    const json = (body, status = 200) => NextResponse.json(body, { status, headers: { 'cache-control': 'no-store' } });
+    const siteOrigin = new URL(ctx.siteUrl).origin;
+    const foreign = (req) => { const o = req.headers.get('origin'); return o !== null && o !== siteOrigin; };
+    const clientIp = (req) => (ctx.clientIp ? ctx.clientIp(req) : (req.headers.get('x-forwarded-for') ?? '').split(',')[0].trim());
+    const hash = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+    /** The page and the reader, through every door the page has; or the refusal. */
+    async function open(req, id) {
+        const a = ARTIFACT_ID_RE.test(id) ? await ctx.store.get(id) : null;
+        if (!a)
+            return { error: json({ error: `no artifact with id ${id}` }, 404) };
+        if (a.password && !isUnlocked({ id, password: a.password, cookie: req.cookies.get(unlockCookieName(id))?.value }))
+            return { error: json({ error: 'this page is locked' }, 403) };
+        const reader = verifyGrant(ctx.readerSecret(), req.cookies.get(GRANT_COOKIE)?.value);
+        const signIn = ctx.signInOrigin ? signInUrl(ctx.signInOrigin, ctx.pageUrl(id)) : null;
+        if (a.access) {
+            if (!ctx.readers)
+                return { error: json({ error: 'this page is closed' }, 403) };
+            if (!reader)
+                return { error: json({ error: 'sign in to read this page', signIn }, 401) };
+            if (!decide(a.access, reader, await ctx.readers.allowList(id)).open)
+                return { error: json({ error: 'this page is not open to you' }, 403) };
+            if (!(await ctx.readers.acknowledged(id, reader.email)))
+                return { error: json({ error: 'accept the agreement first' }, 403) };
+        }
+        return { a, reader, signIn };
+    }
+    /** May this reader write in `scope` on page `a`? Null when yes, else the refusal. */
+    function mayWrite(a, reader, scope, signIn) {
+        if (scope === 'personal') {
+            if (!ctx.personal)
+                return json({ error: 'this host keeps no personal notes', device: true }, 501);
+            if (!reader)
+                return json({ error: 'sign in to keep recordings everywhere', device: true, signIn }, 401);
+            return null;
+        }
+        const on = !!ctx.state && !!a.state && !!a.comments && a.comments !== 'off' && Object.hasOwn(a.state.slots, COMMENTS_SLOT);
+        if (!on)
+            return json({ error: 'this page takes no comments' }, 403);
+        if (!reader && effectiveWriters(a.state, a.access, COMMENTS_SLOT) !== 'anyone')
+            return json({ error: 'sign in to comment', signIn }, 401);
+        return null;
+    }
+    /** Who is asking, for the per-reader counters: the account, else the anonymous cookie, else the address. */
+    const askerKey = (req, reader) => {
+        if (reader)
+            return `u:${reader.uid}`;
+        const anon = req.cookies.get(ANON_COOKIE)?.value;
+        return anon && ANON_ID.test(anon) ? `a:${anon}` : `ip:${rateKey(clientIp(req), ctx.siteUrl, ctx.readerSecret())}`;
+    };
+    /** The reader branch of UPLOAD. `body` is already parsed; `name` is `<memo>.<ext>`. */
+    async function readerUpload(req, id, name, body) {
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const assets = ctx.assets;
+        if (!assets?.signAudioUpload || !assets.audioSize)
+            return json({ error: 'this host does not keep recordings' }, 501);
+        const scope = body.audio;
+        if (scope !== 'comment' && scope !== 'personal')
+            return json({ error: 'audio is comment or personal' }, 400);
+        if (!MEMO_NAME.test(name))
+            return json({ error: 'a recording is named <id>.<webm|m4a|mp3|ogg>' }, 400);
+        const type = audioTypeFor(name);
+        const o = await open(req, id);
+        if ('error' in o)
+            return o.error;
+        const refused = mayWrite(o.a, o.reader, scope, o.signIn);
+        if (refused)
+            return refused;
+        const path = scope === 'comment' ? commentAudioPath(name) : personalAudioPath(personalAudioDir(o.reader.uid), name);
+        if (body.done === true) {
+            const size = await assets.audioSize(id, path);
+            if (size === null)
+                return json({ error: 'nothing was uploaded to that url' }, 409);
+            if (size > MAX_AUDIO_BYTES)
+                return json({ error: 'a recording is at most 4 MB' }, 413);
+            return json({ path }, 201);
+        }
+        // An anonymous signer is counted like an anonymous answer, so a public page is not free storage.
+        if (!o.reader) {
+            const n = ctx.state ? await ctx.state.countAnonWrite(id, `au.${hash(askerKey(req, null))}`, Math.floor(Date.now() / 60000)) : 0;
+            if (n > ANON_WRITES_PER_MINUTE)
+                return json({ error: 'too many recordings from here; try again in a minute' }, 429);
+        }
+        return json({ path, ...(await assets.signAudioUpload(id, path, type)) }, 201);
+    }
+    async function TRANSCRIBE(req, { params }) {
+        // No transcriber: the reader's browser is the floor, and a 404 is how it learns that.
+        if (!ctx.transcribe)
+            return json({ error: 'this host does not transcribe' }, 404);
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const raw = await req.text();
+        if (raw.length > 1024)
+            return json({ error: 'request over 1 KB' }, 413);
+        let asset;
+        try {
+            asset = JSON.parse(raw)?.asset;
+        }
+        catch {
+            return json({ error: 'body is { asset }' }, 400);
+        }
+        const o = await open(req, (await params).id);
+        if ('error' in o)
+            return o.error;
+        const { a, reader, signIn } = o;
+        let scope;
+        if (isCommentAudioPath(asset))
+            scope = 'comment';
+        else if (typeof asset === 'string' && asset.startsWith('personal/')) {
+            if (!reader)
+                return json({ error: 'sign in to transcribe a personal note', signIn }, 401);
+            // A personal recording is transcribed only for the reader it belongs to.
+            if (!isPersonalAudioPath(asset, personalAudioDir(reader.uid)))
+                return json({ error: 'no recording of yours at that path' }, 404);
+            scope = 'personal';
+        }
+        else
+            return json({ error: 'asset is the path the upload returned' }, 400);
+        const refused = mayWrite(a, reader, scope, signIn);
+        if (refused)
+            return refused;
+        if (!ctx.state)
+            return json({ error: 'this host keeps no counters' }, 501);
+        if (!ctx.assets?.readAudio)
+            return json({ error: 'this host does not keep recordings' }, 501);
+        const n = await ctx.state.countAnonWrite(a.id, `tx.${hash(askerKey(req, reader))}`, Math.floor(Date.now() / 3_600_000));
+        if (n > TRANSCRIBE_PER_HOUR)
+            return json({ error: 'that is enough transcriptions for this hour; type it instead' }, 429);
+        const path = asset;
+        const bytes = await ctx.assets.readAudio(a.id, path);
+        if (!bytes)
+            return json({ error: 'no recording at that path' }, 404);
+        if (bytes.length > MAX_AUDIO_BYTES)
+            return json({ error: 'a recording is at most 4 MB' }, 413);
+        const mime = audioTypeFor(path);
+        let out = null;
+        try {
+            out = await ctx.transcribe(new Blob([new Uint8Array(bytes)], { type: mime }), mime);
+        }
+        catch {
+            out = null;
+        }
+        if (!out || typeof out.text !== 'string')
+            return json({ error: 'the transcription service did not answer' }, 502);
+        return json({ text: out.text });
+    }
+    return { TRANSCRIBE, readerUpload };
+}

package/package.json

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