@supersuit/artifacts 0.34.0 → 0.36.0

package/lib/routes/per-reader.js

@@ -0,0 +1,38 @@
+// Who is reading a `links: per-reader` page, decided before anything of the page is rendered.
+// Every refusal is the same quiet page; a revoked or expired reader learns only that it is gone.
+import { parseRidParam, verifyRid } from '../artifacts/recipients.js';
+import { PRIVATE_REF } from '../artifacts/assets.js';
+export const UNAVAILABLE = 'This page is no longer available.';
+export const NO_LINK = 'This page opens from the link it was sent with.';
+export async function perReaderGate(o) {
+    // An unset or empty secret verifies nothing: fail closed before any signature is compared.
+    if (!o.secret || !o.recipients)
+        return { state: 'shut', why: 'closed' };
+    const fromParam = parseRidParam(o.param);
+    const fromCookie = parseRidParam(o.cookie);
+    const pick = fromParam && verifyRid(o.secret, o.id, fromParam.rid, fromParam.sig) ? { ...fromParam, fromLink: true }
+        : fromCookie && verifyRid(o.secret, o.id, fromCookie.rid, fromCookie.sig) ? { ...fromCookie, fromLink: false } : null;
+    if (!pick)
+        return { state: 'shut', why: 'no-link' };
+    const rec = await o.recipients.get(o.id);
+    const r = rec?.recipients[pick.rid];
+    if (!rec || !r)
+        return { state: 'shut', why: 'no-link' };
+    if (r.revokedAt)
+        return { state: 'shut', why: 'revoked' };
+    // A malformed expireAt parses to NaN: treat it as expired, never as no expiry.
+    if (rec.expireAt && !(Date.parse(rec.expireAt) > (o.now ?? Date.now())))
+        return { state: 'shut', why: 'expired' };
+    return { state: 'open', rid: pick.rid, sig: pick.sig, label: r.label, note: r.note ?? null, owner: r.owner === true, fromLink: pick.fromLink };
+}
+const REF_IN_MD = /\]\((private:[A-Za-z0-9][A-Za-z0-9._-]{0,140})\)/g;
+export async function withPrivateUrls(markdown, id, privateUrl) {
+    const refs = [...new Set([...markdown.matchAll(REF_IN_MD)].map((m) => m[1]))];
+    let out = markdown;
+    for (const ref of refs) {
+        const stored = PRIVATE_REF.exec(ref)?.[1];
+        const url = stored && privateUrl ? await privateUrl(id, stored) : '#';
+        out = out.split(`](${ref})`).join(`](${url})`);
+    }
+    return out;
+}

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

@@ -0,0 +1,34 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { type RecipientsStore } from '../artifacts/recipients-store.js';
+import type { ArtifactStore } from '../artifacts/store.js';
+import type { StateStore } from '../artifacts/state-store.js';
+import type { ArtifactAssets } from '../artifacts/assets.js';
+type Params = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+export type RecipientsRoutesCtx = {
+    store: ArtifactStore;
+    recipients?: RecipientsStore;
+    recipientSecret?: () => string | undefined;
+    publishKey: () => string | undefined;
+    state?: StateStore;
+    assets?: ArtifactAssets;
+    pageUrl: (id: string) => string;
+    authed: (r: Request) => boolean;
+    /** Where the sweep reports a page it skipped or could not finish. Defaults to console.warn. */
+    log?: (message: string) => void;
+};
+export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
+    SEEN: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    RECIPIENTS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    VIEWS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    sweepExpired: (now?: Date) => Promise<{
+        pages: number;
+        files: number;
+        skipped: string[];
+        failed: string[];
+    }>;
+};
+export {};

package/lib/routes/recipients-routes.js

@@ -0,0 +1,182 @@
+// The per-reader routes. SEEN is public (the page calls it); everything else needs the publish key.
+import { NextResponse } from 'next/server';
+import { RID_RE, usableSecret, beatKey, isUnfurlAgent, ridLink, verifyRenderToken, verifyRid } from '../artifacts/recipients.js';
+import { summarizeViews } from '../artifacts/recipients-store.js';
+import { COMMENTS_SLOT } from '../artifacts/comments.js';
+import { ARTIFACT_ID_RE } from './ids.js';
+// Session and device ids become part of a stored view's id, so only a short plain shape is let in.
+const SESSION = /^[a-z0-9]{1,32}$/;
+const MEDIA = /^[A-Za-z0-9][A-Za-z0-9._-]{0,140}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const none = () => new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+const json = (b, status = 200) => NextResponse.json(b, { status, headers: { 'cache-control': 'no-store' } });
+export function createRecipientsRoutes(given) {
+    // A secret under the documented minimum is no secret: every route treats it as unset.
+    const ctx = { ...given, recipientSecret: () => usableSecret(given.recipientSecret?.()) };
+    /** POST /api/artifacts/<id>/seen: the page's own signal that a reader looked at it. */
+    async function SEEN(req, { params }) {
+        const { id } = await params;
+        // An unfurl agent is dropped before anything is read: no state, no answer worth reading.
+        if (isUnfurlAgent(req.headers.get('user-agent')))
+            return none();
+        // An unset or empty secret verifies nothing: fail closed before any signature is compared.
+        const secret = ctx.recipientSecret?.();
+        if (!secret || !ctx.recipients || !ARTIFACT_ID_RE.test(id))
+            return json({ error: 'not found' }, 404);
+        const b = (await req.json().catch(() => null));
+        const str = (v) => (typeof v === 'string' ? v : '');
+        const rid = str(b?.rid), sig = str(b?.sig), session = str(b?.session), device = str(b?.device);
+        if (!RID_RE.test(rid) || !SESSION.test(session) || !SESSION.test(device))
+            return json({ error: 'bad signal' }, 400);
+        if (!verifyRid(secret, id, rid, sig))
+            return json({ error: 'forbidden' }, 403);
+        // The rid must be one this page was sent to, still live: a signature alone proves only that
+        // the host minted it once.
+        const rec = await ctx.recipients.get(id);
+        const r = rec?.recipients[rid];
+        // A malformed expireAt parses to NaN: treat it as expired, never as no expiry.
+        if (!rec || !r || r.revokedAt || (rec.expireAt && !(Date.parse(rec.expireAt) > Date.now())))
+            return json({ error: 'gone' }, 410);
+        // The owner's own opens record zero.
+        if (r.owner)
+            return none();
+        const at = new Date().toISOString();
+        const event = b?.event;
+        if (event === 'view') {
+            const t = verifyRenderToken(secret, id, rid, str(b?.token));
+            if (!t.ok || !(await ctx.recipients.useToken(t.key, t.expiresAt)))
+                return json({ error: 'not a fresh render' }, 409);
+            await ctx.recipients.recordView({ artifactId: id, rid, session, device, at, addSeconds: 2 });
+            return json({ beat: beatKey(secret, id, rid, session) });
+        }
+        if (event === 'beat' || event === 'play') {
+            if (str(b?.beat) !== beatKey(secret, id, rid, session))
+                return json({ error: 'forbidden' }, 403);
+            const media = event === 'play' && typeof b?.media === 'string' && MEDIA.test(b.media) ? b.media : undefined;
+            const seconds = event === 'beat' ? Math.max(0, Math.min(20, Number(b?.seconds) || 0)) : 0;
+            await ctx.recipients.recordView({ artifactId: id, rid, session, device, at, addSeconds: seconds, ...(media ? { play: media } : {}) });
+            return json({});
+        }
+        return json({ error: 'event must be view, beat or play' }, 400);
+    }
+    const unauth = () => json({ error: 'publish key required' }, 401);
+    async function listing(id) {
+        const secret = ctx.recipientSecret();
+        const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
+        return {
+            id, expireAt: rec.expireAt, keep: rec.keep,
+            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
+        };
+    }
+    /** GET and POST /api/artifacts/<id>/recipients: who a per-reader page was sent to (publish key). */
+    async function RECIPIENTS(req, { params }) {
+        const { id } = await params;
+        if (!ctx.authed(req))
+            return unauth();
+        if (!ctx.recipients || !ctx.recipientSecret?.())
+            return json({ error: 'this host keeps no per-reader links' }, 501);
+        const a = ARTIFACT_ID_RE.test(id) ? await ctx.store.get(id) : null;
+        if (!a)
+            return json({ error: `no artifact with id ${id}` }, 404);
+        if (req.method === 'GET')
+            return json(await listing(id));
+        if (a.links !== 'per-reader')
+            return json({ error: 'this page is not links: per-reader' }, 409);
+        const b = (await req.json().catch(() => null));
+        if (!b)
+            return json({ error: 'body must be JSON' }, 400);
+        const secret = ctx.recipientSecret();
+        let added = [];
+        if (Array.isArray(b.add) && b.add.some((x) => !x || typeof x !== 'object' || typeof x.label !== 'string' || !x.label.trim()))
+            return json({ error: 'each reader to add needs a label' }, 400);
+        if (typeof b.expires === 'string' && Number.isNaN(Date.parse(b.expires)))
+            return json({ error: 'expires must be an ISO time or null' }, 400);
+        if (typeof b.expires === 'string' && Date.parse(b.expires) <= Date.now())
+            return json({ error: 'expires must be in the future' }, 400);
+        if (Array.isArray(b.add) && b.add.length) {
+            const made = await ctx.recipients.add(id, b.add);
+            added = made.map((r) => ({ rid: r.rid, label: r.label, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) }));
+        }
+        const revoked = b.revoke === '*' || Array.isArray(b.revoke)
+            ? await ctx.recipients.revoke(id, b.revoke === '*' ? '*' : b.revoke.filter((x) => typeof x === 'string' && RID_RE.test(x)))
+            : [];
+        if (b.expires === null || typeof b.expires === 'string') {
+            await ctx.recipients.setExpiry(id, b.expires === null ? null : new Date(b.expires).toISOString());
+        }
+        return json({ ...(await listing(id)), added, revoked });
+    }
+    /** GET /api/artifacts/<id>/views: one line per reader, with their comments (publish key). */
+    async function VIEWS(req, { params }) {
+        const { id } = await params;
+        if (!ctx.authed(req))
+            return unauth();
+        if (!ctx.recipients)
+            return json({ error: 'this host keeps no per-reader links' }, 501);
+        const a = ARTIFACT_ID_RE.test(id) ? await ctx.store.get(id) : null;
+        if (!a)
+            return json({ error: `no artifact with id ${id}` }, 404);
+        // A page nobody has been added to yet has no readers, which is an answer and not a missing page.
+        const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
+        const entries = ctx.state ? await ctx.state.entries(id) : [];
+        const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, at: e.at, text: String(e.value?.body ?? '') }));
+        return json({ id, expireAt: rec.expireAt, keep: rec.keep, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments) });
+    }
+    /** The daily sweep: deletes only pages whose recipients record carries an expireAt that is a
+     *  well-formed time in the past and is not kept. An unparseable expireAt is never deleted (the
+     *  gate already shuts the page); it is reported in `skipped`. A page that fails midway stays
+     *  listed (the expiry record is forgotten last) and is retried by the next sweep. */
+    async function sweepExpired(now = new Date()) {
+        const out = { pages: 0, files: 0, skipped: [], failed: [] };
+        if (!ctx.recipients)
+            return out;
+        const log = ctx.log ?? ((m) => console.warn(m));
+        for (const id of await ctx.recipients.expiring(now.toISOString())) {
+            try {
+                const rec = await ctx.recipients.get(id);
+                const at = rec && !rec.keep && typeof rec.expireAt === 'string' && ISO.test(rec.expireAt) ? Date.parse(rec.expireAt) : NaN;
+                if (!rec || rec.keep || !(at <= now.getTime())) {
+                    if (rec && !rec.keep) {
+                        out.skipped.push(id);
+                        log(`sweepExpired: not deleting ${id}, expireAt is not a past ISO time`);
+                    }
+                    continue;
+                }
+                const page = await ctx.store.get(id);
+                // The page is gone already: only the leftover record is cleaned up.
+                if (!page) {
+                    await ctx.recipients.forget(id);
+                    continue;
+                }
+                // A page republished without per-reader links keeps its old record; it is no longer a broadcast page.
+                if (page.links !== 'per-reader') {
+                    out.skipped.push(id);
+                    log(`sweepExpired: not deleting ${id}, it is not a per-reader page`);
+                    continue;
+                }
+                if (!ctx.assets?.deletePage)
+                    throw new Error('media deletion is not configured, page record kept so no media is orphaned');
+                const files = await ctx.assets.deletePage(id);
+                // Keep may have landed while the files were being removed: the page record and comments stay.
+                const again = await ctx.recipients.get(id);
+                if (!again || again.keep) {
+                    log(`sweepExpired: ${id} was kept during the sweep`);
+                    continue;
+                }
+                // Reader text expires with the page: every comment and answer, whoever wrote it.
+                if (ctx.state)
+                    for (const key of new Set((await ctx.state.entries(id)).map((e) => e.readerKey)))
+                        await ctx.state.removeReader(id, key);
+                await ctx.store.delete(id);
+                await ctx.recipients.forget(id);
+                out.pages++;
+                out.files += files;
+            }
+            catch (e) {
+                out.failed.push(id);
+                log(`sweepExpired: ${id} not finished, will retry: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return out;
+    }
+    return { SEEN, RECIPIENTS, VIEWS, sweepExpired };
+}

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

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
+import type { RecipientsStore } from '../artifacts/recipients-store.js';
 import { type StateStore } from '../artifacts/state-store.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { ReadersStore } from '../artifacts/readers-store.js';
@@ -20,6 +21,10 @@ export type StateRoutesContext = {
     state?: StateStore;
     readers?: ReadersStore;
     readerSecret: () => string | undefined;
+    /** Who each per-reader page was sent to, and the secret their links are signed with. Without
+     *  both, a `links: per-reader` page takes no answers. */
+    recipients?: RecipientsStore;
+    recipientSecret?: () => string | undefined;
     publishKey: () => string | undefined;
     /** Publisher passes, as in ArtifactRoutesConfig. Both absent means passes are refused. */
     publisherSecret?: () => string | undefined;

package/lib/routes/state-routes.js

@@ -18,6 +18,8 @@ import { isPublisherAuthed } 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 { ridCookieName, usableSecret } from '../artifacts/recipients.js';
+import { perReaderGate } from './per-reader.js';
 import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters, slotVisibility } from '../artifacts/state.js';
 import { COMMENTS_SLOT, MAX_COMMENT_NAME_CHARS, cleanResolveNote, resolutionOf, validateComment } from '../artifacts/comments.js';
 import { isCommentAudioPath } from '../artifacts/audio.js';
@@ -83,9 +85,19 @@ export function createStateRoutes(ctx) {
             if (!(await ctx.readers.acknowledged(id, reader.email)))
                 return { error: json({ error: 'accept the agreement first' }, 403) };
         }
+        // A per-reader page is answered through the link it was sent with: the rid cookie names the
+        // reader, and what they write is theirs under that key. A revoked or expired rid is shut.
+        let recipient = null;
+        // The owner and the page's admins open it without a link: their comment layer is signed-in, never a reader's.
+        if (a.links === 'per-reader' && !isOwner(reader)) {
+            const g = await perReaderGate({ id, param: undefined, cookie: req.cookies.get(ridCookieName(id))?.value, secret: usableSecret(ctx.recipientSecret?.()), recipients: ctx.recipients });
+            if (g.state === 'shut')
+                return { error: json({ error: 'this page is locked' }, 403) };
+            recipient = { rid: g.rid, label: g.label };
+        }
         const rawAnon = req.cookies.get(ANON_COOKIE)?.value;
         const anonId = rawAnon && ANON_ID.test(rawAnon) ? rawAnon : null;
-        return { a, reader, anonId, signIn };
+        return { a, reader, anonId, signIn, recipient };
     }
     const ownerEmail = ctx.ownerEmail?.trim().toLowerCase();
     const admins = new Set((ctx.admins ?? []).map((e) => e.trim().toLowerCase()));
@@ -107,11 +119,19 @@ export function createStateRoutes(ctx) {
         }
         return rows;
     }
-    async function viewBody(a, reader, readerKey) {
+    async function viewBody(a, reader, readerKey, canWriteAs = false) {
         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);
+        // A reader who came through their own link sees only their own answers: whatever the page's
+        // settings say, nothing of another reader's is shared with them.
+        if (canWriteAs)
+            for (const v of Object.values(slots)) {
+                v.visibility = 'private';
+                delete v.shared;
+                delete v.tally;
+            }
+        const owner = !canWriteAs && 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)
@@ -125,15 +145,15 @@ export function createStateRoutes(ctx) {
         }
         return {
             reader: reader ? { firstName: firstName(reader, allow) } : null,
-            canWrite: !!reader || effectiveWriters(a.state, a.access) === 'anyone',
+            canWrite: !!reader || canWriteAs || effectiveWriters(a.state, a.access) === 'anyone',
             ...(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);
+    async function visibleComments(a, writerKey, reader, perReader = false) {
+        const all = !perReader && (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))
@@ -150,14 +170,14 @@ export function createStateRoutes(ctx) {
         const o = await open(req, id);
         if ('error' in o)
             return o.error;
-        const { a, reader, anonId, signIn } = o;
+        const { a, reader, anonId, signIn, recipient } = o;
         let clearAnon = false;
-        if (reader && anonId) {
+        if (reader && anonId && !recipient) {
             await ctx.state.moveReader(readerKeyFor.anonymous(anonId), writerFor(reader));
             clearAnon = true;
         }
-        const key = reader ? readerKeyFor.signedIn(reader.uid) : anonId ? readerKeyFor.anonymous(anonId) : null;
-        const res = json({ ...(await viewBody(a, reader, key)), ...(reader ? {} : { signIn }) });
+        const key = recipient ? readerKeyFor.recipient(recipient.rid) : reader ? readerKeyFor.signedIn(reader.uid) : anonId ? readerKeyFor.anonymous(anonId) : null;
+        const res = json({ ...(await viewBody(a, reader, key, !!recipient)), ...(reader || recipient ? {} : { signIn }) });
         if (clearAnon)
             res.headers.append('set-cookie', anonCookie('', 0));
         return res;
@@ -192,7 +212,7 @@ export function createStateRoutes(ctx) {
         const o = await open(req, id);
         if ('error' in o)
             return o.error;
-        const { a, reader, signIn } = o;
+        const { a, reader, signIn, recipient } = o;
         let { anonId } = o;
         const slot = typeof b.slot === 'string' ? b.slot : '';
         // Object.hasOwn, never a bracket read: `slots['__proto__']` or `slots['constructor']`
@@ -215,7 +235,9 @@ export function createStateRoutes(ctx) {
         const isComments = slot === COMMENTS_SLOT && commentsOn(a);
         let setCookie = null;
         let writer;
-        if (reader)
+        if (recipient)
+            writer = { key: readerKeyFor.recipient(recipient.rid), name: recipient.label, anonymous: true };
+        else if (reader)
             writer = writerFor(reader);
         else {
             if (effectiveWriters(a.state, a.access, slot) !== 'anyone')
@@ -258,7 +280,7 @@ export function createStateRoutes(ctx) {
                 return json({ error: bad }, 400);
             let value = b.value;
             if (isComments) {
-                const seen = await visibleComments(a, writer.key, reader);
+                const seen = await visibleComments(a, writer.key, reader, !!recipient);
                 const c = validateComment(b.value, (cid) => seen.get(cid) ?? null);
                 if (!c.ok)
                     return json({ error: c.error }, 400);
@@ -279,7 +301,7 @@ export function createStateRoutes(ctx) {
                 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));
+                const res = json(await viewBody(a, reader, writer.key, !!recipient));
                 if (setCookie)
                     res.headers.append('set-cookie', setCookie);
                 return res;
@@ -299,7 +321,7 @@ export function createStateRoutes(ctx) {
             if ('full' in r)
                 return json({ error: 'you have left the most answers this page takes here' }, 409);
         }
-        const res = json(await viewBody(a, reader, writer.key));
+        const res = json(await viewBody(a, reader, writer.key, !!recipient));
         if (setCookie)
             res.headers.append('set-cookie', setCookie);
         return res;

package/package.json

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