@supersuit/artifacts 0.33.1 → 0.35.0

package/lib/routes/artifacts.js

@@ -21,6 +21,8 @@ import { ArtifactReader } from '../reader/artifact-reader.js';
 import { CommentLayer } from '../reader/comment-layer.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
 import { UpdatedTime } from '../reader/updated-time.js';
+import { perReaderGate, withPrivateUrls, NO_LINK, UNAVAILABLE } from './per-reader.js';
+import { ridCookieName, mintRenderToken, usableSecret, RID_COOKIE_MAX_AGE } from '../artifacts/recipients.js';
 import { PageMenu } from '../reader/page-menu.js';
 import { COMMENTS_MODES } from '../artifacts/comments.js';
 import { newPageKey } from '../artifacts/settings.js';
@@ -31,6 +33,8 @@ import { readSecondsFor, wordCount } from '../artifacts/read-alerts.js';
 import { AckDoor, ConfidentialBanner, NO_PRINT_CSS, NotAllowedDoor, SignInDoor, Watermark, ackText } from '../artifacts/confidential.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
+import { createRecipientsRoutes } from './recipients-routes.js';
+import { QuietView } from '../reader/quiet-view.js';
 import { createPersonalRoutes } from './personal-routes.js';
 import { createVoiceRoutes } from './voice-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
@@ -87,9 +91,13 @@ export function createArtifactRoutes(config) {
     const publishAuth = { publishKey: config.publishKey, publisherSecret: config.publisherSecret, publisherHost: config.publisherHost };
     const authed = (request) => isPublisherAuthed(request, publishAuth);
     const stateRoutes = createStateRoutes({
-        store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey,
+        store, state: config.state, readers: config.readers, readerSecret, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
         publisherSecret: config.publisherSecret, publisherHost: config.publisherHost, pageUrl, signInOrigin, siteUrl,
-        clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl,
+        clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl, onResolve: config.onResolve,
+    });
+    const recipientsRoutes = createRecipientsRoutes({
+        store, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
+        state: config.state, assets: config.assets, pageUrl, authed,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({
@@ -272,6 +280,32 @@ export function createArtifactRoutes(config) {
         const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
+        if (a.links === 'per-reader') {
+            if (n !== null)
+                notFound(); // a past version of a per-reader page is never served
+            const sp = (await searchParams) ?? {};
+            const param = Array.isArray(sp.r) ? sp.r[0] : sp.r;
+            const readCookie = config.readCookie ?? defaultReadCookie;
+            const privateUrl = config.assets?.privateUrl?.bind(config.assets);
+            // A signed-in owner or admin gets through as the owner, with no link and no tracking.
+            const me = readerSecret() ? verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE).catch(() => undefined)) : null;
+            if (isAdmin(me)) {
+                const markdown = a.privateMedia ? await withPrivateUrls(a.markdown, id, privateUrl) : a.markdown;
+                return _jsx(BrandGround, { pack: pack, mode: a.theme, children: await Body({ ...a, markdown }, { top: true, reader: me }) });
+            }
+            const secret = usableSecret(config.recipientSecret?.());
+            const g = await perReaderGate({ id, param, cookie: await readCookie(ridCookieName(id)).catch(() => undefined), secret, recipients: config.recipients });
+            if (g.state === 'shut') {
+                return (_jsx(BrandGround, { pack: pack, mode: a.theme, children: _jsx("p", { "data-per-reader-shut": true, className: "mx-auto max-w-xl px-6 pt-32 text-center text-lg opacity-80", children: g.why === 'no-link' ? NO_LINK : UNAVAILABLE }) }));
+            }
+            const token = mintRenderToken(secret, id, g.rid);
+            const remember = g.fromLink
+                ? [pagePath(id), `/api/artifacts/${id}`].map((p) => `document.cookie=${JSON.stringify(`${ridCookieName(id)}=${g.rid}.${g.sig}; Path=${p}; Max-Age=${RID_COOKIE_MAX_AGE}; SameSite=Lax; Secure`)}`).join(';')
+                : null;
+            const markdown = a.privateMedia ? await withPrivateUrls(a.markdown, id, privateUrl) : a.markdown;
+            const body = await Body({ ...a, markdown }, { top: true, reader: null, perReader: { rid: g.rid, sig: g.sig, label: g.label, note: g.note, owner: g.owner, token } });
+            return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, body] }));
+        }
         // A password shuts the body, never the title: the header stays so the reader knows which
         // page they were sent, and the unfurl (generateMetadata) keeps reading as the page.
         const sp = (await searchParams) ?? {};
@@ -385,7 +419,7 @@ export function createArtifactRoutes(config) {
         return (_jsxs(_Fragment, { children: [_jsx(Menu, { a: a, reader: reader, history: history, viewing: n, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, { title, subtitle: v.subtitle, summary, to: v.to }, v.markdown) : null }), toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { n: n, at: v.at }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { n: n, at: v.at })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
-    async function Body(a, { top, reader }) {
+    async function Body(a, { top, reader, perReader }) {
         const { pack, brand } = lookOf(a);
         let words = [];
         if (a.narration && a.timings) {
@@ -407,10 +441,10 @@ export function createArtifactRoutes(config) {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
-                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
+                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));
-                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
     }
@@ -523,6 +557,8 @@ export function createArtifactRoutes(config) {
         if (request.method === 'GET')
             return NextResponse.json({ id, access: a.access ?? null, readers: await config.readers.allowList(id) });
         const b = (await request.json().catch(() => null));
+        if (a.links === 'per-reader' && b?.access !== undefined)
+            return NextResponse.json({ error: 'a per-reader page opens only from its own links, so its access and password cannot be changed' }, { status: 409 });
         let access = a.access ?? null;
         if (b?.access !== undefined) {
             if (b.access !== 'public' && !ACCESS_LEVELS.includes(b.access))
@@ -587,6 +623,8 @@ export function createArtifactRoutes(config) {
         }
         if (!b || typeof b !== 'object' || Array.isArray(b))
             return no('the body is an object', 400);
+        if (a.links === 'per-reader' && (b.access !== undefined || b.password !== undefined))
+            return no('a per-reader page opens only from its own links, so its access and password cannot be changed', 409);
         const KEYS = ['access', 'password', 'comments', 'commentsVisible', 'add', 'remove'];
         const unknown = Object.keys(b).filter((k) => !KEYS.includes(k));
         if (unknown.length)
@@ -719,6 +757,9 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         if (!config.assets)
             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 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
@@ -734,7 +775,7 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'empty body' }, { status: 400 });
         if (bytes.length > 16 * 1024 * 1024)
             return NextResponse.json({ error: 'asset over 16 MiB' }, { status: 413 });
-        const url = await config.assets.put(id, name, bytes, type);
+        const url = priv ? await config.assets.putPrivate(id, name, bytes, type) : await config.assets.put(id, name, bytes, type);
         return NextResponse.json({ id, name, url }, { status: 201 });
     }
     /**
@@ -762,7 +803,12 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const assets = config.assets;
-        if (!assets?.signUpload || !assets.finishUpload)
+        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 });
+        }
+        else if (!assets?.signUpload || !assets.finishUpload)
             return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
@@ -778,12 +824,13 @@ export function createArtifactRoutes(config) {
         if (!ASSET_DIGEST.test(digest))
             return NextResponse.json({ error: 'digest must be the first 8 hex of the sha256 of the bytes' }, { status: 400 });
         if (body.done === true) {
-            const url = await assets.finishUpload(id, name, digest);
+            const url = priv ? await assets.finishPrivateUpload(id, name, digest) : await assets.finishUpload(id, name, digest);
             if (!url)
                 return NextResponse.json({ error: 'nothing was uploaded to that url' }, { status: 409 });
             return NextResponse.json({ id, name, url }, { status: 201 });
         }
-        return NextResponse.json({ id, name, ...(await assets.signUpload(id, name, digest, type)) }, { status: 201 });
+        const signed = priv ? await assets.signPrivateUpload(id, name, digest, type) : await assets.signUpload(id, name, digest, type);
+        return NextResponse.json({ id, name, ...signed }, { status: 201 });
     }
     /** GET /<id>/share.png: the page's title card. 404 when the pack draws none, so a
      *  tenant on the static default never serves a half-styled card. */
@@ -828,5 +875,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, ...recipientsRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/lib/routes/per-reader.d.ts

@@ -0,0 +1,25 @@
+import type { RecipientsStore } from '../artifacts/recipients-store.js';
+export type PerReaderOpen = {
+    state: 'open';
+    rid: string;
+    sig: string;
+    label: string;
+    note: string | null;
+    owner: boolean;
+    fromLink: boolean;
+};
+export type PerReaderShut = {
+    state: 'shut';
+    why: 'no-link' | 'revoked' | 'expired' | 'closed';
+};
+export declare const UNAVAILABLE = "This page is no longer available.";
+export declare const NO_LINK = "This page opens from the link it was sent with.";
+export declare function perReaderGate(o: {
+    id: string;
+    param: string | undefined;
+    cookie: string | undefined;
+    secret: string | undefined;
+    recipients: RecipientsStore | undefined;
+    now?: number;
+}): Promise<PerReaderOpen | PerReaderShut>;
+export declare function withPrivateUrls(markdown: string, id: string, privateUrl: ((id: string, stored: string) => Promise<string>) | undefined): Promise<string>;

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,7 +1,9 @@
 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';
+import type { ResolveEvent } from '../artifacts/resolve-digest.js';
 export declare const ANON_COOKIE = "artifact_anon";
 /** The most comments one feed answer carries. A caller that gets this many moves its cursor to the
  *  last row's `at` and asks again. */
@@ -19,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;
@@ -39,6 +45,10 @@ export type StateRoutesContext = {
     /** 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>;
+    /** Told after a thread is resolved or reopened (0.34.0), with the whole thread and who did it.
+     *  `createResolveDigests(...).onResolve` turns it into resolution emails. Awaited, and anything
+     *  it throws is logged and swallowed: a broken mailer never costs the owner their resolve. */
+    onResolve?: (event: ResolveEvent) => void | Promise<void>;
 };
 type Params = {
     params: Promise<{