@supersuit/artifacts 0.9.0 → 0.11.0

package/lib/routes/personal-routes.js

@@ -0,0 +1,100 @@
+// The reader's own notes on a page, and nobody else's.
+//
+//   GET    /api/artifacts/<id>/personal              the signed-in reader's notes on this page
+//   POST   /api/artifacts/<id>/personal              { value } adds one; { entry, value } edits one
+//   DELETE /api/artifacts/<id>/personal?entry=<id>   deletes one
+//
+// Signed-in readers only, by the grant cookie. A reader who is not signed in gets 401 with
+// `{ device: true }` and keeps the note in their browser instead, where no server (this host's
+// owner included) can read it. There is deliberately NO publisher variant of any of these: the
+// publish key opens nothing here, and personal-privacy.test.ts holds every handler to that.
+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';
+const MAX_BODY = 16 * 1024;
+export function createPersonalRoutes(ctx) {
+    const json = (body, status = 200) => NextResponse.json(body, { status, headers: { 'cache-control': 'no-store' } });
+    const siteOrigin = new URL(ctx.siteUrl).origin;
+    /** The page, the signed-in reader, and every door the page itself 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) };
+        }
+        // The client reads `device: true` as "keep this note in the browser".
+        if (!ctx.personal)
+            return { error: json({ error: 'this host keeps no personal notes', device: true }, 501) };
+        if (!reader)
+            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) });
+    // 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 }) {
+        const o = await open(req, (await params).id);
+        return 'error' in o ? o.error : list(o);
+    }
+    async function PERSONAL_POST(req, { params }) {
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const declared = Number(req.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > MAX_BODY)
+            return json({ error: 'request over 16 KB' }, 413);
+        const raw = await req.text();
+        if (Buffer.byteLength(raw, 'utf8') > MAX_BODY)
+            return json({ error: 'request over 16 KB' }, 413);
+        let b;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return json({ error: 'body must be JSON' }, 400);
+            b = parsed;
+        }
+        catch {
+            return json({ error: 'body must be JSON' }, 400);
+        }
+        const o = await open(req, (await params).id);
+        if ('error' in o)
+            return o.error;
+        const v = validatePersonal(b.value);
+        if (!v.ok)
+            return json({ error: v.error }, 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);
+            return list(o);
+        }
+        const r = await o.personal.add(o.id, o.uid, v.value);
+        if ('full' in r)
+            return json({ error: 'you have left the most notes this page keeps' }, 409);
+        return list(o);
+    }
+    async function PERSONAL_DELETE(req, { params }) {
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const o = await open(req, (await params).id);
+        if ('error' in o)
+            return o.error;
+        const entry = req.nextUrl.searchParams.get('entry') ?? '';
+        if (!(await o.personal.remove(o.id, o.uid, entry)))
+            return json({ error: 'no note of yours with that id' }, 404);
+        return list(o);
+    }
+    return { PERSONAL_GET, PERSONAL_POST, PERSONAL_DELETE };
+}

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

@@ -21,6 +21,9 @@ export type StateRoutesContext = {
      *  which is correct on Vercel (it overwrites XFF with the real client IP) and wrong behind any
      *  other proxy that appends rather than replaces; a host behind one of those passes its own. */
     clientIp?: (req: NextRequest) => string;
+    /** 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;
 };
 type Params = {
     params: Promise<{

package/lib/routes/state-routes.js

@@ -1,7 +1,7 @@
 // The state routes: what readers put into a page, and what the publisher gets back.
 //
 //   GET  /api/artifacts/<id>/state      the reader's own answers + what the page lets them see
-//   POST /api/artifacts/<id>/state      { slot, op: set|append|remove, value?, entry? }
+//   POST /api/artifacts/<id>/state      { slot, op: set|append|remove|replace, value?, entry? }
 //   GET  /api/artifacts/<id>/responses  publish key; every answer with who (?format=csv)
 //   DELETE /api/artifacts/<id>/responses?reader=<key>  publish key; one reader's answers
 //
@@ -14,7 +14,8 @@ import { isPublishAuthed } from '../artifacts/auth.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
-import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters } from '../artifacts/state.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 { readerKeyFor } from '../artifacts/state-store.js';
 import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
@@ -64,15 +65,39 @@ export function createStateRoutes(ctx) {
         const anonId = rawAnon && ANON_ID.test(rawAnon) ? rawAnon : null;
         return { a, reader, anonId, signIn };
     }
+    const ownerEmail = ctx.ownerEmail?.trim().toLowerCase();
+    const isOwner = (r) => !!r && !!ownerEmail && r.email === ownerEmail;
+    /** 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 });
     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);
+        const slots = stateView(a.state, entries, readerKey);
+        const owner = isOwner(reader);
+        // The owner reads every comment with its writer's full name, whatever the page shows readers.
+        if (owner && commentsOn(a)) {
+            slots[COMMENTS_SLOT].shared = entries.filter((e) => e.slot === COMMENTS_SLOT)
+                .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 }));
+        }
         return {
             reader: reader ? { firstName: firstName(reader, allow) } : null,
             canWrite: !!reader || effectiveWriters(a.state, a.access) === 'anyone',
-            slots: stateView(a.state, await ctx.state.entries(a.id), readerKey),
+            ...(owner ? { owner: true } : {}),
+            slots,
         };
     }
+    /** The comments a writer can see, by id: every one on a readers-visible page, else their own,
+     *  and every one for the owner. A reply may name only a comment its writer was shown. */
+    async function visibleComments(a, writerKey, reader) {
+        const all = slotVisibility(a.state, COMMENTS_SLOT) === 'shared' || isOwner(reader);
+        const byId = new Map();
+        for (const e of await ctx.state.entries(a.id))
+            if (e.slot === COMMENTS_SLOT && (all || e.readerKey === writerKey))
+                byId.set(e.id, e.value);
+        return byId;
+    }
     // A GET that writes, on purpose: when a signed-in reader still carries an anonymous cookie, the
     // answers move here, because this is the first request that sees both. It is safe as a GET:
     // moveReader is idempotent (a second run finds nothing under the cleared key), and the grant
@@ -134,28 +159,40 @@ export function createStateRoutes(ctx) {
         if (!def)
             return json({ error: `no slot named ${slot} on this page` }, 400);
         const op = b.op;
-        if (op !== 'set' && op !== 'append' && op !== 'remove')
-            return json({ error: 'op must be set, append or remove' }, 400);
+        if (op !== 'set' && op !== 'append' && op !== 'remove' && op !== 'replace')
+            return json({ error: 'op must be set, append, remove or replace' }, 400);
         if (op === 'set' && def.shape !== 'one')
             return json({ error: `slot ${slot} takes append` }, 400);
-        if (op === 'append' && def.shape !== 'many')
+        if ((op === 'append' || op === 'replace') && def.shape !== 'many')
             return json({ error: `slot ${slot} takes set` }, 400);
+        const entryId = typeof b.entry === 'string' ? b.entry : undefined;
+        if (op === 'replace' && !entryId)
+            return json({ error: 'replace names the entry it edits' }, 400);
+        if (op === 'replace' && !ctx.state.replace)
+            return json({ error: 'this host cannot edit an answer' }, 501);
+        const isComments = slot === COMMENTS_SLOT && commentsOn(a);
         let setCookie = null;
         let writer;
         if (reader)
             writer = writerFor(reader);
         else {
-            if (effectiveWriters(a.state, a.access) !== 'anyone')
+            if (effectiveWriters(a.state, a.access, slot) !== 'anyone')
                 return json({ error: 'sign in to answer', signIn }, 401);
             // A remove adds nothing, so it is never counted and never mints a cookie: with no cookie
             // there is nothing of theirs to remove, and the answer is simply the page as it stands.
+            // Comments say so instead: deleting a comment that is not yours is a refusal, not a no-op.
             if (op === 'remove') {
                 if (!anonId)
-                    return json(await viewBody(a, null, null));
+                    return isComments && entryId ? json({ error: 'no comment of yours with that id' }, 404) : json(await viewBody(a, null, null));
                 const key = readerKeyFor.anonymous(anonId);
-                await ctx.state.remove({ artifactId: id, slot, readerKey: key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
+                const n = await ctx.state.remove({ artifactId: id, slot, readerKey: key, entryId });
+                if (isComments && entryId && !n)
+                    return json({ error: 'no comment of yours with that id' }, 404);
                 return json(await viewBody(a, null, key));
             }
+            // An edit with no cookie has nothing of theirs to edit.
+            if (op === 'replace' && !anonId)
+                return json({ error: 'no answer of yours with that id' }, 404);
             const n = await ctx.state.countAnonWrite(id, ipHash(req), Math.floor(Date.now() / 60000));
             if (n > ANON_WRITES_PER_MINUTE)
                 return json({ error: 'too many answers from here; try again in a minute' }, 429);
@@ -166,12 +203,34 @@ export function createStateRoutes(ctx) {
             writer = { key: readerKeyFor.anonymous(anonId), name: null, anonymous: true };
         }
         if (op === 'remove') {
-            await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
+            const n = await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId });
+            if (isComments && entryId && !n)
+                return json({ error: 'no comment of yours with that id' }, 404);
         }
         else {
             const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
             if (bad)
                 return json({ error: bad }, 400);
+            let value = b.value;
+            if (isComments) {
+                const seen = await visibleComments(a, writer.key, reader);
+                const c = validateComment(b.value, (cid) => seen.get(cid) ?? null);
+                if (!c.ok)
+                    return json({ error: c.error }, 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);
+                value = c.value;
+            }
+            if (op === 'replace') {
+                const r = await ctx.state.replace({ artifactId: id, slot, readerKey: writer.key, entryId: entryId, value });
+                if (!r)
+                    return json({ error: 'no answer of yours with that id' }, 404);
+                const res = json(await viewBody(a, reader, writer.key));
+                if (setCookie)
+                    res.headers.append('set-cookie', setCookie);
+                return res;
+            }
             // The page-wide cap per slot. Counted before the write and not atomically with it, so a
             // burst can overshoot by the writes in flight; it bounds the slot, it is not a quota.
             if ((await ctx.state.countSlot(id, slot)) >= MAX_ENTRIES_PER_SLOT) {
@@ -182,8 +241,8 @@ export function createStateRoutes(ctx) {
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }
             const r = op === 'set'
-                ? await ctx.state.set({ artifactId: id, slot, writer, value: b.value })
-                : await ctx.state.append({ artifactId: id, slot, writer, value: b.value });
+                ? await ctx.state.set({ artifactId: id, slot, writer, value })
+                : await ctx.state.append({ artifactId: id, slot, writer, value });
             if ('full' in r)
                 return json({ error: 'you have left the most answers this page takes here' }, 409);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.9.0",
+  "version": "0.11.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",
@@ -38,8 +38,8 @@
       "default": "./lib/brand/index.js"
     },
     "./reader": {
-      "types": "./lib/reader/artifact-reader.d.ts",
-      "default": "./lib/reader/artifact-reader.js"
+      "types": "./lib/reader/index.d.ts",
+      "default": "./lib/reader/index.js"
     },
     "./gate": {
       "types": "./lib/gate.d.ts",