@supersuit/artifacts 0.34.0 → 0.36.0

package/lib/artifacts/recipients.js

@@ -0,0 +1,87 @@
+// src/artifacts/recipients.ts
+// A page published with `links: per-reader` opens only through a link made for one reader. The
+// link names an opaque rid and a signature over the page and the rid, so a rid cannot be guessed
+// or carried to another page. A view is counted only from a signal the rendered page sends, and
+// that signal carries a token minted for this one render: a fetch that never runs the page (every
+// messaging app's preview fetcher) can never produce one.
+import { createHmac, randomBytes, timingSafeEqual, createHash } from 'node:crypto';
+export const RID_RE = /^[a-z0-9]{12}$/;
+const SIG_RE = /^[0-9a-f]{16}$/;
+export const RID_COOKIE_MAX_AGE = 7_776_000;
+export const VIEW_AFTER_MS = 2000;
+export const TOKEN_MAX_AGE_MS = 86_400_000;
+const ALPHA = 'abcdefghijklmnopqrstuvwxyz0123456789';
+/** A signing secret shorter than this is treated as unset by the routes: the page shuts. */
+export const RECIPIENT_SECRET_MIN = 32;
+export function usableSecret(secret) {
+    return typeof secret === 'string' && secret.length >= RECIPIENT_SECRET_MIN ? secret : undefined;
+}
+const mac = (secret, text) => {
+    // An empty key still produces a valid MAC that anyone can compute; never sign with one.
+    if (!secret)
+        throw new Error('a signing secret is required');
+    return createHmac('sha256', secret).update(text).digest('hex').slice(0, 16);
+};
+const same = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+export function newRid() {
+    const bytes = randomBytes(12);
+    let s = '';
+    for (const b of bytes)
+        s += ALPHA[b % ALPHA.length];
+    return s;
+}
+export function ridSig(secret, id, rid) {
+    return mac(secret, `${id}\n${rid}`);
+}
+export function ridLink(pageUrl, id, rid, secret) {
+    return `${pageUrl}?r=${rid}.${ridSig(secret, id, rid)}`;
+}
+export function parseRidParam(v) {
+    if (typeof v !== 'string')
+        return null;
+    const [rid, sig, extra] = v.split('.');
+    if (extra !== undefined || !RID_RE.test(rid ?? '') || !SIG_RE.test(sig ?? ''))
+        return null;
+    return { rid, sig };
+}
+export function verifyRid(secret, id, rid, sig) {
+    if (!secret || !RID_RE.test(rid) || !SIG_RE.test(sig))
+        return false;
+    return same(ridSig(secret, id, rid), sig);
+}
+export function ridCookieName(id) {
+    return `artifact_r_${id}`;
+}
+/** `<time base36>.<nonce 16 hex>.<mac 16 hex>`, minted once per server render. */
+export function mintRenderToken(secret, id, rid, now = Date.now()) {
+    const ts = now.toString(36);
+    const nonce = randomBytes(8).toString('hex');
+    return `${ts}.${nonce}.${mac(secret, `${id}\n${rid}\n${ts}\n${nonce}`)}`;
+}
+export function verifyRenderToken(secret, id, rid, token, now = Date.now()) {
+    const parts = String(token ?? '').split('.');
+    if (parts.length !== 3)
+        return { ok: false, why: 'malformed' };
+    if (!secret)
+        return { ok: false, why: 'no secret' };
+    const [ts, nonce, m] = parts;
+    if (!/^[0-9a-z]{1,12}$/.test(ts) || !SIG_RE.test(nonce) || !SIG_RE.test(m))
+        return { ok: false, why: 'malformed' };
+    if (!same(mac(secret, `${id}\n${rid}\n${ts}\n${nonce}`), m))
+        return { ok: false, why: 'not minted here' };
+    const at = parseInt(ts, 36);
+    if (!Number.isFinite(at) || now - at > TOKEN_MAX_AGE_MS || at - now > 60_000)
+        return { ok: false, why: 'expired' };
+    return { ok: true, key: createHash('sha256').update(token).digest('hex').slice(0, 32), expiresAt: at + TOKEN_MAX_AGE_MS };
+}
+export function beatKey(secret, id, rid, session) {
+    return mac(secret, `beat\n${id}\n${rid}\n${session}`);
+}
+/** Messaging apps' and search engines' preview fetchers. Apple's LinkPresentation presents as
+ *  `facebookexternalhit/1.1 Facebot Twitterbot/1.0`. A request with no user agent is treated as one. */
+export const UNFURL_AGENTS = /facebookexternalhit|facebot|twitterbot|slackbot|whatsapp|linkedinbot|discordbot|telegrambot|skypeuripreview|redditbot|applebot|googlebot|bingbot|embedly|iframely|pinterest|bitlybot|vkshare|mastodon|preview/i;
+export function isUnfurlAgent(ua) {
+    if (!ua || !ua.trim())
+        return true;
+    return UNFURL_AGENTS.test(ua);
+}

package/lib/artifacts/render.js

@@ -77,7 +77,18 @@ const VIDEO = /\.mp4(?:[?#].*)?$/i;
 /** `![caption](x.mp3)` is a clip the reader plays: an annotated conversation, a voice note, a
  *  quote heard rather than read. Native controls, and `preload="none"` so a page of clips fetches
  *  nothing until one is pressed. The alt is its caption, shown above the player. */
-const AUDIO = /\.mp3(?:[?#].*)?$/i;
+const AUDIO = /\.(mp3|m4a)(?:[?#].*)?$/i;
+/** The stored file's name, for play tracking: the last path segment before any query. */
+const mediaName = (src) => {
+    const last = src.split(/[?#]/)[0].split('/').pop() ?? '';
+    try {
+        return decodeURIComponent(last);
+    }
+    catch {
+        return last;
+    }
+};
+const SOUND = /^sound:\s*/i;
 const VIDEO_IN_MD = /\]\([^)\s]+\.mp4(?:[?#][^)]*)?\)/i;
 // A fenced block, which `links` and `notes` fences are too; mounting for those costs one
 // no-op effect and is cheaper than parsing the markdown twice to find out.
@@ -88,11 +99,15 @@ const escapeAttr = (s) => s.replace(/&/g, '&').replace(/"/g, '"').repla
 // iPhone from going full screen. No `autoplay`: VideoAutoplay starts each one as it nears the
 // screen, so a page of videos does not download them all on open.
 function InlineVideo({ src, label }) {
-    const html = `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-video muted loop playsinline preload="metadata" disablepictureinpicture class="block w-full"></video>`;
+    const name = escapeAttr(mediaName(src));
+    // `sound:` in the alt is a moment to watch: controls and sound, started by the reader.
+    const html = SOUND.test(label)
+        ? `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label.replace(SOUND, ''))}" data-artifact-media="${name}" controls playsinline preload="metadata" class="block w-full"></video>`
+        : `<video src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-video data-artifact-media="${name}" muted loop playsinline preload="metadata" disablepictureinpicture class="block w-full"></video>`;
     return _jsx("span", { className: "my-6 block overflow-hidden rounded-lg border border-[color:var(--a-line)]", dangerouslySetInnerHTML: { __html: html } });
 }
 function InlineAudio({ src, label }) {
-    const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio controls preload="none" class="block w-full"></audio>`;
+    const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio data-artifact-media="${escapeAttr(mediaName(src))}" controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
 /** An embed block (```simulator, ```messages): the player in a frame when the host names one, its

package/lib/artifacts/state-store.d.ts

@@ -81,6 +81,7 @@ export interface StateStore {
 export declare const readerKeyFor: {
     signedIn: (uid: string) => string;
     anonymous: (id: string) => string;
+    recipient: (rid: string) => string;
 };
 export declare function createStateStore(db: Firestore, base: string): StateStore;
 /** The same contract in memory: for tests, and for hosts' own tests. */

package/lib/artifacts/state-store.js

@@ -17,6 +17,7 @@ import { MAX_MANY_PER_READER } from './state.js';
 export const readerKeyFor = {
     signedIn: (uid) => `u:${uid}`,
     anonymous: (id) => `a:${id}`,
+    recipient: (rid) => `r:${rid}`,
 };
 const writerOf = (w) => ({
     ...(w.uid ? { uid: w.uid } : {}), ...(w.email ? { email: w.email } : {}), name: w.name, anonymous: w.anonymous,

package/lib/artifacts/store.d.ts

@@ -22,6 +22,10 @@ export type ArtifactRecord = {
     narrationHash?: string;
     password?: string;
     access?: Access;
+    /** `per-reader`: opens only through a link made for one reader. */
+    links?: 'per-reader';
+    /** Body media are stored unlisted and served only to a valid reader. */
+    privateMedia?: true;
     state?: StateConfig;
     theme?: ThemeMode;
     /** The brand pack the page asked for by name; see ArtifactMeta.pack. */

package/lib/artifacts/store.js

@@ -193,6 +193,10 @@ async function saveArtifact(col, input) {
         const to = input.meta.to ? {} : { to: FieldValue.delete() };
         // How the page looks is content too: a line the file no longer carries goes back to the default.
         const look = {
+            // Who may open the page is a door, not content: like `access`, a file that leaves these lines
+            // out changes nothing, so a publisher that strips unknown keys can never reopen the page.
+            ...(input.meta.links ? { links: input.meta.links } : {}),
+            ...(input.meta.privateMedia ? { privateMedia: true } : {}),
             ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
             ...(input.meta.pack ? {} : { pack: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
@@ -219,6 +223,8 @@ async function saveArtifact(col, input) {
         ...fields,
         ...(live.access ? { access: live.access } : {}),
         ...(live.password ? { password: live.password } : {}),
+        ...(input.meta.links ? { links: input.meta.links } : {}),
+        ...(input.meta.privateMedia ? { privateMedia: true } : {}),
         ...(live.state ? { state: live.state } : {}),
         ...(live.comments ? { comments: live.comments } : {}),
         ...(live.commentsVisible ? { commentsVisible: live.commentsVisible } : {}),
@@ -238,6 +244,9 @@ async function deleteArtifact(col, id) {
     const snap = await ref.get();
     if (!snap.exists)
         return false;
+    // Every prior body lives in the versions subcollection and outlives the page doc unless it goes too.
+    const past = await ref.collection('versions').get();
+    await Promise.all(past.docs.map((d) => ref.collection('versions').doc(d.id).delete()));
     await ref.delete();
     return true;
 }

package/lib/reader/index.d.ts

@@ -1,5 +1,6 @@
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming } from './artifact-reader.js';
 export { PlayerBar } from './player-bar.js';
+export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems, type PageMenuProps, type PageRole } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY, type PageSettings, type SettingsFact, type SheetKind, type AccessLevel } from './settings-sheet.js';

package/lib/reader/index.js

@@ -2,6 +2,7 @@
 // own 'use client'; this barrel is plain re-exports so it can be imported from either side.
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex } from './artifact-reader.js';
 export { PlayerBar } from './player-bar.js';
+export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY } from './settings-sheet.js';

package/lib/reader/quiet-view.d.ts

@@ -0,0 +1,7 @@
+export declare function QuietView({ id, rid, sig, token, endpoint }: {
+    id: string;
+    rid: string;
+    sig: string;
+    token: string;
+    endpoint?: string;
+}): null;

package/lib/reader/quiet-view.js

@@ -0,0 +1,118 @@
+'use client';
+// The page's own word that a person looked at it. Silent: it renders nothing and never tells the
+// reader (the publisher chose that). It waits until the page is actually on screen for two
+// seconds, which a link preview fetcher never does because it never runs the page.
+import { useEffect } from 'react';
+const VIEW_AFTER_MS = 2000;
+const BEAT_MS = 15_000;
+const ALPHA = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const rand = (n) => Array.from(crypto.getRandomValues(new Uint8Array(n)), (b) => ALPHA[b % 36]).join('');
+function deviceId() {
+    try {
+        let d = localStorage.getItem('artifact_device');
+        if (!d || !/^[a-z0-9]{16}$/.test(d)) {
+            d = rand(16);
+            localStorage.setItem('artifact_device', d);
+        }
+        return d;
+    }
+    catch {
+        return rand(16);
+    }
+}
+export function QuietView({ id, rid, sig, token, endpoint }) {
+    useEffect(() => {
+        const url = endpoint ?? `/api/artifacts/${id}/seen`;
+        const session = rand(16);
+        const device = deviceId();
+        const base = { rid, sig, session, device };
+        let beat = null;
+        let viewSent = false;
+        let wait = null;
+        let tick = null;
+        let since = 0;
+        const post = async (body) => {
+            try {
+                const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...base, ...body }), keepalive: true });
+                return r.ok ? (await r.json().catch(() => ({}))) : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const visible = () => document.visibilityState === 'visible' && !document.prerendering;
+        const flush = (useBeacon) => {
+            if (!beat || !since)
+                return;
+            const seconds = Math.round((Date.now() - since) / 1000);
+            since = 0;
+            if (seconds <= 0)
+                return;
+            if (useBeacon && typeof navigator.sendBeacon === 'function') {
+                navigator.sendBeacon(url, new Blob([JSON.stringify({ ...base, event: 'beat', beat, seconds })], { type: 'application/json' }));
+            }
+            else
+                void post({ event: 'beat', beat, seconds });
+        };
+        const startBeats = () => {
+            since = Date.now();
+            tick = setInterval(() => { flush(false); since = Date.now(); }, BEAT_MS);
+        };
+        const arm = () => {
+            if (!visible())
+                return;
+            if (beat) {
+                if (!tick)
+                    startBeats();
+                return;
+            }
+            // One render token, one view: once it is sent, a later show never sends another.
+            if (viewSent || wait)
+                return;
+            wait = setTimeout(async () => {
+                wait = null;
+                if (!visible())
+                    return;
+                viewSent = true;
+                const r = await post({ event: 'view', token });
+                if (r?.beat && visible()) {
+                    beat = r.beat;
+                    startBeats();
+                }
+                else if (r?.beat)
+                    beat = r.beat;
+            }, VIEW_AFTER_MS);
+        };
+        const disarm = () => {
+            if (wait) {
+                clearTimeout(wait);
+                wait = null;
+            }
+            if (tick) {
+                clearInterval(tick);
+                tick = null;
+                flush(true);
+            }
+        };
+        const onVisibility = () => (visible() ? arm() : disarm());
+        const onPlay = (e) => {
+            const el = e.target;
+            const media = el?.getAttribute?.('data-artifact-media');
+            if (media && beat)
+                void post({ event: 'play', beat, media });
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        document.addEventListener('prerenderingchange', onVisibility);
+        document.addEventListener('play', onPlay, true);
+        window.addEventListener('pagehide', disarm);
+        arm();
+        return () => {
+            document.removeEventListener('visibilitychange', onVisibility);
+            document.removeEventListener('prerenderingchange', onVisibility);
+            document.removeEventListener('play', onPlay, true);
+            window.removeEventListener('pagehide', disarm);
+            disarm();
+        };
+    }, [id, rid, sig, token, endpoint]);
+    return null;
+}

package/lib/routes/artifacts.d.ts

@@ -4,6 +4,7 @@ import { type ArtifactRecord, type ArtifactStore, type VersionEntry } from '../a
 import type { StateStore } from '../artifacts/state-store.js';
 import { type ArtifactAssets } from '../artifacts/assets.js';
 import type { BrandPack } from '../brand/pack.js';
+import type { RecipientsStore } from '../artifacts/recipients-store.js';
 import type { PageSettings, SettingsFact } from '../reader/settings-sheet.js';
 import { type Access, type AllowEntry } from '../artifacts/reader.js';
 import { type ReadersStore } from '../artifacts/readers-store.js';
@@ -104,6 +105,11 @@ export type ArtifactRoutesConfig = {
      *  bare URL sees, and search engines). Called only for the owner and admins; a throw falls back
      *  to the package's rows. */
     shareFacts?: (artifact: ArtifactRecord) => SettingsFact[] | Promise<SettingsFact[]>;
+    /** Who each per-reader page was sent to (recipients-store.ts). Without it, or without
+     *  `recipientSecret`, a `links: per-reader` page is shut to everyone. */
+    recipients?: RecipientsStore;
+    /** Signs per-reader links and render tokens. At least 32 characters. Read at request time. */
+    recipientSecret?: () => string | undefined;
 };
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export declare const ARTIFACT_ID: RegExp;
@@ -115,6 +121,7 @@ type Params = {
 type PageProps = Params & {
     searchParams?: Promise<{
         key?: string | string[];
+        r?: string | string[];
     }>;
 };
 type VersionParams = {
@@ -126,11 +133,33 @@ type VersionParams = {
 type VersionProps = VersionParams & {
     searchParams?: Promise<{
         key?: string | string[];
+        r?: string | string[];
     }>;
 };
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     dynamic: "force-dynamic";
     maxDuration: number;
+    SEEN: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    RECIPIENTS: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    VIEWS: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    sweepExpired: (now?: Date) => Promise<{
+        pages: number;
+        files: number;
+        skipped: string[];
+        failed: string[];
+    }>;
     PERSONAL_GET: (req: NextRequest, { params }: {
         params: Promise<{
             id: string;

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,12 +33,16 @@ 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. */
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
 /** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
 const VERSION_N = /^[1-9]\d{0,5}$/;
+/** What a host with no private store answers to private media, in words that say what to set up. */
+const NO_PRIVATE_STORE = 'this host keeps no private store, so media: private is refused and nothing was published. Give createArtifactAssets a privateBucket (its own bucket, never the public one) to keep private media';
 async function defaultReadCookie(name) {
     const { cookies } = await import('next/headers');
     return (await cookies()).get(name)?.value;
@@ -87,10 +93,14 @@ 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, 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({
         store, state: config.state, personal: config.personal, readers: config.readers, assets: config.assets, transcribe: config.transcribe,
@@ -272,6 +282,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 +421,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 +443,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 +559,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 +625,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)
@@ -659,6 +699,8 @@ export function createArtifactRoutes(config) {
         const [sessions, flags, acks] = await Promise.all([config.readers.sessions(id), config.readers.flags(id), config.readers.acks(id)]);
         return NextResponse.json({ id, title: a.title, access: a.access ?? null, views: a.views, ...summarize(sessions, flags), acks: acks.map((k) => ({ email: k.email, name: k.name, at: k.at })) }, { headers: { 'cache-control': 'no-store' } });
     }
+    /** Whether this host can store and serve private media: both halves come from a private bucket. */
+    const keepsPrivateMedia = () => Boolean(config.assets?.putPrivate && config.assets.privateUrl);
     async function POST(request) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
@@ -667,6 +709,11 @@ export function createArtifactRoutes(config) {
         if (!parsed.ok)
             return NextResponse.json({ error: parsed.error }, { status: 400 });
         const id = request.nextUrl.searchParams.get('id') ?? parsed.meta.id ?? undefined;
+        // Fail closed: private media needs a private store. Without one the media would have to sit in
+        // the public bucket, which may carry a bucket-wide public read grant, so nothing is saved.
+        // `media:` is sticky, so a stored page that already keeps private media counts too.
+        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await store.get(id))?.privateMedia)))
+            return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         if (id && parsed.meta.state) {
             const existing = await store.get(id);
             const changed = shapeChanges(existing?.state, parsed.meta.state);
@@ -719,6 +766,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: NO_PRIVATE_STORE }, { 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 +784,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 +812,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: NO_PRIVATE_STORE }, { 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 +833,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 +884,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>;