@supersuit/artifacts 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.36.0
+
+**Private media moves to its own private bucket, and a host without one refuses it.** 0.35.0 kept
+`media: private` files under `<prefix>/<id>/private/` in the same bucket as public assets and
+never called `makePublic` on them. That is no protection on a bucket that carries a bucket-wide
+public read grant: every "private" object was readable by anyone holding its URL.
+
+- `createArtifactAssets(bucket, prefix, { privateBucket })`. With `privateBucket`, `putPrivate`,
+  `signPrivateUpload`, `finishPrivateUpload` and `privateUrl` use it (same `<prefix>/<id>/private/`
+  keys); `put`, `signUpload`, `finishUpload`, covers and narration stay on `bucket`. `deletePage`
+  clears the page from both. Passing the public bucket again as the private one throws.
+- Without `privateBucket` the four private methods are not defined, so the host fails closed:
+  `POST /api/artifacts` refuses a page with `media: private` (or a republish of a page that already
+  keeps private media) with 501 and saves nothing, and `?private=1` uploads answer 501, all with
+  the same words naming `privateBucket`.
+- `PRIVATE_READ_TTL_MS` (exported, `60 * 60 * 1000`): the life of a signed V4 read URL. One is
+  minted per private file on every render that passed the per-reader gate, and none for a revoked
+  or expired link.
+- DETECTOR: your host passes `media: private` pages and calls `createArtifactAssets(bucket, prefix)`
+  with two arguments; or `gcloud storage buckets get-iam-policy` on your bucket lists `allUsers`
+  and you have objects under `*/private/`.
+- REMEDY: create a separate bucket (uniform access, public access prevention enforced, object
+  access for the host's service account only), pass it as `privateBucket`, give it CORS for `PUT`
+  from your origin if browsers upload to it directly, and republish any page whose private media
+  sits in the public bucket (then delete those old objects). A host that publishes no private
+  media needs nothing; until it adds a private bucket, `media: private` is refused.
+- TESTS: `src/artifacts/assets.test.ts` (private media), `src/routes/private-media.test.tsx`
+  (publishing media: private), `src/routes/per-reader.test.tsx` (mints a fresh signed URL on every
+  passing render), `src/artifacts/index.test.ts`.
+
+## 0.35.0
+
+**Per-reader links, private media, video with sound, quiet views, and expiry.** A page can now go
+to several people at once with one link each, revocable one at a time, with a tailored note per
+reader.
+
+- `links: per-reader` in front matter: the page opens only through a link made for one reader
+  (`?r=<rid>.<sig>`, signed with the host's recipient secret). Each link can be revoked alone.
+  `createRecipientsStore(db, base)` and `memoryRecipientsStore()` hold the readers; the routes are
+  `RECIPIENTS` (GET and POST: add, revoke, set a note), `VIEWS` (GET) and `SEEN` (POST).
+- `media: private`: body media is stored under the page's private prefix and served only by signed
+  URL to a valid reader. The cover stays public so the share card works.
+- Video with sound: `![sound: caption](clip.mp4)` renders a clip with controls. `.m4a` voice notes
+  are supported.
+- A quiet view beacon. DETECTOR: an unfurl fetch or a background tab used to count as an open.
+  REMEDY: a view is the page visible for two seconds with a single-use render token; known unfurl
+  agents and the owner are dropped server side. TESTS: `src/routes/seen.test.tsx`,
+  `src/reader/quiet-view.test.tsx`.
+- `sweepExpired()` for dated pages: deletes the page, its media, readers, views and comments, and
+  returns `{ pages, files, skipped, failed }`. Call it daily from a cron route.
+- Config on `createArtifactRoutes`: `recipients` and `recipientSecret` (a function; at least 32
+  characters, shorter is treated as unset).
+
 ## 0.34.0
 
 **Commenters hear when their comments are resolved, in one email per page per burst** (Gary,

package/README.md

@@ -22,7 +22,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactRoutes(config)` | Every route handler: the page, its metadata, the publish API, the share card, the reader sign-in exchange, access control |
 | `createArtifactStore(db, path)` | Firestore store for pages and their version history, under any collection path |
 | `createReadersStore(db, path)` | The record for confidential pages: allowlist, agreements, reading sessions, flags |
-| `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
+| `createArtifactAssets(bucket, prefix, { privateBucket? })` | Uploaded images for a page, in a Cloud Storage bucket; private media in a separate private bucket |
 | `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
 | `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
 | `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
@@ -251,6 +251,8 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `pack` | A brand pack the host registered by name (`packs` in the routes config). An unknown name renders in the host's default pack; a republish without the line goes back to it |
 | `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
 | `definitions` | Terms defined inline (below). A republish without it removes them |
+| `links` | `per-reader`: the page opens only through a link made for one reader (see Per-reader links). Sticky: a republish whose file leaves the line out changes nothing |
+| `media` | `private`: the page's body media is kept private and served through short-lived signed URLs. Needs `links: per-reader`. Sticky like `links` |
 | `change` | One line saying what this version changed (see Version history) |
 | `template` | `document`, the only one so far |
 
@@ -830,6 +832,52 @@ composite index: **`slot` ascending, `at` ascending**, collection scope. Without
 refuses the query and the error names a link that creates the index. A host with its own
 `StateStore` implements `slotSince(slot, after, limit)`; without it the feed answers 501.
 
+## Per-reader links
+
+One page, sent to many people, where every person gets their own link. The link names an opaque reader id and a signature over the page and that id, so a link cannot be guessed or carried to another page. The host knows an opaque id, a label you gave it and that link's views and comments, and nothing else about the reader.
+
+```markdown
+---
+title: The river
+summary: Eleven minutes on the water.
+links: per-reader
+media: private
+---
+![sound: the first night](river.mp4)
+![a voice note, as it came](note.m4a)
+```
+
+`links: per-reader` shuts the page to everyone who does not arrive through a valid, unrevoked, unexpired link. It cannot be combined with `password`, `access` or `comments_visible: readers` (readers never see each other's comments). `media: private` keeps body media under the page's private prefix; `.mp4` and `.m4a` (and `.mp3`) are supported, and `sound:` at the start of a video's alt makes it a clip with controls and sound. Both lines are sticky: republishing a file that leaves them out changes nothing.
+
+### Private media lives in its own bucket
+
+`media: private` needs a private store: `createArtifactAssets(bucket, prefix, { privateBucket })`. Private files go to `privateBucket` under `<prefix>/<id>/private/`; covers, images and narration stay on the public `bucket`. Without `privateBucket` the private methods are not defined, and the host refuses private media with 501 at every door: publishing a page with `media: private` (or republishing a page that already keeps it), and `?private=1` uploads. Nothing is saved. This is on purpose: a public bucket often carries a bucket-wide public read grant, so an object written there is readable by anyone who has its URL, whatever the object's own settings say.
+
+The private bucket must be a different bucket from the public one (passing the same bucket twice throws), with uniform bucket-level access, public access prevention enforced, and object access granted only to the host's own service account. The page signs a V4 read URL per private file on every render that passed the per-reader gate, valid `PRIVATE_READ_TTL_MS` (one hour); a revoked or expired link renders nothing and mints nothing. A reader revoked after a render can keep loading a URL already handed to them for at most that hour. Expiry's `deletePage` clears the page from both buckets.
+
+If the publisher uploads straight to the private bucket from a browser (`?private=1` on `UPLOAD`), give that bucket a CORS rule allowing `PUT` from your origin with the `content-type` and `cache-control` headers; a reader's browser playing a signed URL needs `GET` (and `HEAD`) from your origin only if your player fetches it with CORS.
+
+Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `VIEWS`, `SEEN`, and `sweepExpired`.
+
+| Route | Who | What |
+|---|---|---|
+| `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
+| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group? }], revoke?: [rid] or '*', expires?: ISO time or null }`. `add` answers each new reader's link; `expires: null` is Keep |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
+| `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
+
+Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
+
+The `Page` route must stay `force-dynamic` (the package's `dynamic` export says so; re-export it), because the page carries a fresh render token and answers per link.
+
+### What counts as a view
+
+A view is the page rendered in a real browser, visible, for at least 2 seconds. The page then sends one signal carrying a single-use render token minted for that render; the token is spent on first use and expires after a day. Known unfurl fetchers (and any request with no user agent) are ignored, and so is a signal for a revoked or expired reader. The owner's own opens record zero. After the first signal the page sends a beat every few seconds while it stays visible (and a final one on hide, by `sendBeacon`), and a play signal when a clip starts. A signed-in owner or admin opens the page with no link and no tracking, so test a reader's link in a signed-out browser, never in the browser you are signed in to.
+
+### Expiry
+
+`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,
@@ -881,6 +929,7 @@ the page's pack.
 | your publish key (named by you, read in `publishKey`) | Authorises publish, delete and access changes |
 | `ARTIFACT_PASS_SECRET` (named by you, read in `readerSecret`) | Verifies reader passes and signs grants; shared with your sign-in side |
 | a publisher-pass secret (named by you, read in `publisherSecret`; may be the same one) | Verifies publisher passes; shared with whatever mints them |
+| a recipient secret (named by you, read in `recipientSecret`; at least 32 characters) | Signs per-reader links and render tokens; shorter is treated as unset |
 | Firebase Admin credentials | The store and readers store |
 
 ## Contributing

package/lib/artifacts/assets.d.ts

@@ -25,9 +25,37 @@ export interface ArtifactAssets {
     readAudio?(id: string, path: string): Promise<Buffer | null>;
     /** A signed URL to play the recording, valid for about an hour. */
     audioUrl?(id: string, path: string): Promise<string>;
+    /** Store bytes privately; return `private:<stored name>`. */
+    putPrivate?(id: string, name: string, bytes: Buffer, contentType: string): Promise<string>;
+    /** Like signUpload, to the private key; `url` is `private:<stored name>`. */
+    signPrivateUpload?(id: string, name: string, digest: string, contentType: string): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+        url: string;
+    }>;
+    /** After a signed private upload: `private:<stored name>`, or null if nothing arrived. */
+    finishPrivateUpload?(id: string, name: string, digest: string): Promise<string | null>;
+    /** A V4 signed read URL for a stored private name, valid PRIVATE_READ_TTL_MS (one hour). */
+    privateUrl?(id: string, stored: string): Promise<string>;
+    /** Delete every object under `<prefix>/<id>/`, in the public bucket and the private one; returns how many. */
+    deletePage?(id: string): Promise<number>;
 }
+/** A reference to a private file as it appears in a page: `private:<stored name>`. */
+export declare const PRIVATE_REF: RegExp;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export declare const ASSET_DIGEST: RegExp;
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export declare const PRIVATE_READ_TTL_MS: number;
+export interface ArtifactAssetsOptions {
+    /**
+     * The bucket private media lives in. It must be a different bucket from the public one, with
+     * uniform access, public access prevention enforced, and object access granted only to the
+     * host's own service account. Without it the private methods are not defined at all, so a
+     * `media: private` page is refused instead of being stored where anyone could read it by URL.
+     */
+    privateBucket?: Bucket;
+}
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export declare const ASSET_NAME: RegExp;
 export declare const ASSET_TYPES: Record<string, string>;
@@ -51,4 +79,4 @@ export declare function contentTypeFor(name: string): string | undefined;
 export declare function hashedName(name: string, bytes: Buffer): string;
 /** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
 export declare function storedName(name: string, digest: string): string;
-export declare function createArtifactAssets(bucket: Bucket, prefix: string): ArtifactAssets;
+export declare function createArtifactAssets(bucket: Bucket, prefix: string, options?: ArtifactAssetsOptions): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -4,9 +4,15 @@
 // could do, so every operator gets the same door: PUT bytes with their key, get a URL back.
 import { createHash } from 'node:crypto';
 import { MAX_AUDIO_BYTES } from './audio.js';
+import { ARTIFACT_ID_RE } from '../routes/ids.js';
+/** A reference to a private file as it appears in a page: `private:<stored name>`. */
+export const PRIVATE_REF = /^private:([A-Za-z0-9][A-Za-z0-9._-]{0,140})$/;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
 const CACHE_CONTROL = 'public, max-age=31536000, immutable';
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export const PRIVATE_READ_TTL_MS = 60 * 60 * 1000;
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
 export const ASSET_TYPES = {
@@ -16,6 +22,7 @@ export const ASSET_TYPES = {
     jpeg: 'image/jpeg',
     gif: 'image/gif',
     mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
     mp4: 'video/mp4',
     json: 'application/json',
 };
@@ -48,9 +55,13 @@ export function storedName(name, digest) {
     // A name with no extension is legal here, so append rather than assume there is a dot.
     return dot <= 0 ? `${name}.${digest}` : `${name.slice(0, dot)}.${digest}${name.slice(dot)}`;
 }
-export function createArtifactAssets(bucket, prefix) {
+export function createArtifactAssets(bucket, prefix, options = {}) {
     const clean = prefix.replace(/^\/+|\/+$/g, '');
-    return {
+    const priv = options.privateBucket;
+    // The same bucket twice would put "private" media back where a public read grant reaches it.
+    if (priv && priv.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const assets = {
         async put(id, name, bytes, contentType) {
             const key = `${clean}/${id}/${hashedName(name, bytes)}`;
             const file = bucket.file(key);
@@ -131,5 +142,46 @@ export function createArtifactAssets(bucket, prefix) {
             const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
             return url;
         },
+        async deletePage(id) {
+            // An empty or path-shaped id would make the prefix wider than one page.
+            if (!ARTIFACT_ID_RE.test(id))
+                throw new Error('not an artifact id');
+            let n = 0;
+            for (const b of priv ? [bucket, priv] : [bucket]) {
+                const [files] = await b.getFiles({ prefix: `${clean}/${id}/` });
+                for (const f of files)
+                    await f.delete();
+                n += files.length;
+            }
+            return n;
+        },
+    };
+    if (!priv)
+        return assets;
+    const privateFile = (id, stored) => priv.file(`${clean}/${id}/private/${stored}`);
+    return {
+        ...assets,
+        async putPrivate(id, name, bytes, contentType) {
+            const stored = hashedName(name, bytes);
+            await privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
+            return `private:${stored}`;
+        },
+        async signPrivateUpload(id, name, digest, contentType) {
+            const stored = storedName(name, digest);
+            const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600' };
+            const [uploadUrl] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
+            return { uploadUrl, headers, url: `private:${stored}` };
+        },
+        async finishPrivateUpload(id, name, digest) {
+            const stored = storedName(name, digest);
+            const [there] = await privateFile(id, stored).exists();
+            return there ? `private:${stored}` : null;
+        },
+        async privateUrl(id, stored) {
+            if (!PRIVATE_REF.test(`private:${stored}`))
+                throw new Error('not a private file name');
+            const [url] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + PRIVATE_READ_TTL_MS });
+            return url;
+        },
     };
 }

package/lib/artifacts/front-matter.d.ts

@@ -31,6 +31,10 @@ export type ArtifactMeta = {
      *  ABSENT CHANGES NOTHING: the level is host-side state, so a republish that omits the line
      *  (or a publisher that strips unknown keys) can never reopen a confidential page. */
     access?: Access | 'public';
+    /** `per-reader`: the page opens only through a link made for one reader (recipients.ts). */
+    links?: 'per-reader';
+    /** `media: private` in the file: body media are stored unlisted and served only to a valid reader. */
+    privateMedia?: true;
     /** What readers may put into the page. Content, like the body: a republish without it removes
      *  the slots from the page and KEEPS the answers already given. */
     state?: StateConfig;

package/lib/artifacts/front-matter.js

@@ -11,7 +11,7 @@ import { parseDefinitions } from './definitions.js';
 export const PACK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export const MAX_TO_CHARS = 60;
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -54,6 +54,18 @@ export function parseArtifactSource(text) {
             return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };
         meta.access = d.access;
     }
+    if (d.links !== undefined && d.links !== null) {
+        if (d.links !== 'per-reader')
+            return { ok: false, error: 'links must be per-reader' };
+        if (meta.password || meta.access)
+            return { ok: false, error: 'per-reader links stand alone: drop password and access' };
+        meta.links = 'per-reader';
+    }
+    if (d.media !== undefined && d.media !== null) {
+        if (d.media !== 'private')
+            return { ok: false, error: 'media must be private' };
+        meta.privateMedia = true;
+    }
     if (d.theme !== undefined) {
         if (!THEME_MODES.includes(d.theme))
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
@@ -94,6 +106,12 @@ export function parseArtifactSource(text) {
             return { ok: false, error: 'comments_visible must be owner or readers' };
         meta.commentsVisible = d.comments_visible;
     }
+    // Only the per-reader page resolves private media, so on any other page it would ship broken.
+    if (meta.privateMedia && meta.links !== 'per-reader')
+        return { ok: false, error: 'media: private needs links: per-reader' };
+    // People on one broadcast never see each other's comments, so a per-reader page cannot share them.
+    if (meta.links === 'per-reader' && meta.commentsVisible === 'readers')
+        return { ok: false, error: 'a per-reader page keeps each reader\'s comments to the owner: drop comments_visible: readers' };
     // Widgets declare their own slots, so a notes block (and a checklist with send) is merged into state: here, before the
     // page is stored, and the state API and the republish shape checks see it like any slot.
     // Errors name the line in the FILE: the body's lines are counted after the front matter's.

package/lib/artifacts/index.d.ts

@@ -4,7 +4,7 @@ export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narra
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
 export { isPublishAuthed, isPublisherAuthed, type PublishAuth } from './auth.js';
 export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS, type Publisher } from './publisher.js';
-export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS, type ArtifactAssets, type ArtifactAssetsOptions } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc, type ReaderSummary } from './readers-store.js';
@@ -24,3 +24,5 @@ export { deepgramTranscriber, openaiTranscriber, type Transcriber } from './tran
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey, type DeclaredSettings, type LiveSettings, type SettingsPatch } from './settings.js';
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
+export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
+export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';

package/lib/artifacts/index.js

@@ -4,7 +4,7 @@ export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narra
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
 export { isPublishAuthed, isPublisherAuthed } from './auth.js';
 export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS } from './publisher.js';
-export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';
@@ -23,3 +23,6 @@ export { createPersonalStore, createMemoryPersonalStore, validatePersonal, perso
 export { deepgramTranscriber, openaiTranscriber } from './transcribe.js';
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey } from './settings.js';
+// Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
+export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
+export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';

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

@@ -0,0 +1,75 @@
+import type { Firestore } from 'firebase-admin/firestore';
+export type Recipient = {
+    rid: string;
+    label: string;
+    note?: string;
+    owner?: true;
+    group?: true;
+    addedAt: string;
+    revokedAt?: string;
+};
+export type RecipientsRecord = {
+    recipients: Record<string, Recipient>;
+    expireAt: string | null;
+    keep: boolean;
+    revokedAll?: string;
+};
+export type ViewDoc = {
+    artifactId: string;
+    rid: string;
+    session: string;
+    device: string;
+    firstAt: string;
+    lastAt: string;
+    activeSeconds: number;
+    plays: Record<string, number>;
+};
+export type RecipientSummary = {
+    rid: string;
+    label: string;
+    group: boolean;
+    revoked: boolean;
+    opened: boolean;
+    firstOpenAt: string | null;
+    cameBack: boolean;
+    activeSeconds: number;
+    plays: number;
+    devices: number;
+    comments: {
+        at: string;
+        text: string;
+    }[];
+};
+export interface RecipientsStore {
+    get(artifactId: string): Promise<RecipientsRecord | null>;
+    add(artifactId: string, input: {
+        label: string;
+        note?: string;
+        owner?: boolean;
+        group?: boolean;
+    }[]): Promise<Recipient[]>;
+    revoke(artifactId: string, rids: string[] | '*'): Promise<string[]>;
+    setExpiry(artifactId: string, expireAt: string | null): Promise<void>;
+    useToken(key: string, expiresAt: number): Promise<boolean>;
+    recordView(v: {
+        artifactId: string;
+        rid: string;
+        session: string;
+        device: string;
+        at: string;
+        addSeconds: number;
+        play?: string;
+    }): Promise<void>;
+    views(artifactId: string): Promise<ViewDoc[]>;
+    expiring(nowIso: string): Promise<string[]>;
+    forget(artifactId: string): Promise<void>;
+}
+export declare const CAME_BACK_MS = 3600000;
+export declare function memoryRecipientsStore(): RecipientsStore;
+export declare function createRecipientsStore(db: Firestore, base: string): RecipientsStore;
+/** One line per reader (never the owner), in the order they were added. */
+export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[], comments: {
+    readerKey: string;
+    at: string;
+    text: string;
+}[]): RecipientSummary[];

package/lib/artifacts/recipients-store.js

@@ -0,0 +1,160 @@
+import { newRid } from './recipients.js';
+export const CAME_BACK_MS = 3_600_000;
+const LABEL_MAX = 60;
+const NOTE_MAX = 2000;
+function makeRecipients(input, taken) {
+    const at = new Date().toISOString();
+    return input.map((i) => {
+        const label = String(i.label ?? '').trim().slice(0, LABEL_MAX);
+        if (!label)
+            throw new Error('a reader needs a label');
+        let rid = newRid();
+        while (taken.has(rid))
+            rid = newRid();
+        taken.add(rid);
+        const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}) };
+    });
+}
+function revokeIn(rec, rids) {
+    const at = new Date().toISOString();
+    const hit = [];
+    for (const r of Object.values(rec.recipients)) {
+        if (r.revokedAt || (rids !== '*' && !rids.includes(r.rid)))
+            continue;
+        r.revokedAt = at;
+        hit.push(r.rid);
+    }
+    if (rids === '*')
+        rec.revokedAll = at;
+    return hit;
+}
+function addView(prev, v) {
+    const doc = prev ? { ...prev, plays: { ...prev.plays } } : { artifactId: v.artifactId, rid: v.rid, session: v.session, device: v.device, firstAt: v.at, lastAt: v.at, activeSeconds: 0, plays: {} };
+    doc.activeSeconds += Math.max(0, Math.min(60, v.addSeconds));
+    if (v.at > doc.lastAt)
+        doc.lastAt = v.at;
+    if (v.play)
+        doc.plays[v.play] = (doc.plays[v.play] ?? 0) + 1;
+    return doc;
+}
+const viewId = (artifactId, rid, session) => `${artifactId}__${rid}__${session}`;
+export function memoryRecipientsStore() {
+    const recs = new Map();
+    const views = new Map();
+    const tokens = new Set();
+    return {
+        async get(id) { const r = recs.get(id); return r ? structuredClone(r) : null; },
+        async add(id, input) {
+            const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
+            const out = makeRecipients(input, new Set(Object.keys(rec.recipients)));
+            for (const r of out)
+                rec.recipients[r.rid] = r;
+            recs.set(id, rec);
+            return structuredClone(out);
+        },
+        async revoke(id, rids) { const rec = recs.get(id); return rec ? revokeIn(rec, rids) : []; },
+        async setExpiry(id, expireAt) {
+            const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
+            rec.expireAt = expireAt;
+            rec.keep = expireAt === null;
+            recs.set(id, rec);
+        },
+        async useToken(key) { if (tokens.has(key))
+            return false; tokens.add(key); return true; },
+        async recordView(v) { const k = viewId(v.artifactId, v.rid, v.session); views.set(k, addView(views.get(k), v)); },
+        async views(id) { return [...views.values()].filter((v) => v.artifactId === id).map((v) => structuredClone(v)); },
+        async expiring(now) { return [...recs.entries()].filter(([, r]) => r.expireAt && r.expireAt <= now).map(([id]) => id); },
+        async forget(id) { recs.delete(id); for (const k of [...views.keys()])
+            if (k.startsWith(`${id}__`))
+                views.delete(k); },
+    };
+}
+export function createRecipientsStore(db, base) {
+    const recsCol = () => db.collection(`${base}Recipients`);
+    const viewsCol = () => db.collection(`${base}RecipientViews`);
+    const tokensCol = () => db.collection(`${base}RecipientTokens`);
+    const read = async (id) => {
+        const snap = await recsCol().doc(id).get();
+        if (!snap.exists)
+            return null;
+        const d = snap.data();
+        return { recipients: d.recipients ?? {}, expireAt: d.expireAt ?? null, keep: d.keep === true, ...(d.revokedAll ? { revokedAll: d.revokedAll } : {}) };
+    };
+    return {
+        get: read,
+        async add(id, input) {
+            const rec = (await read(id)) ?? { recipients: {}, expireAt: null, keep: false };
+            const out = makeRecipients(input, new Set(Object.keys(rec.recipients)));
+            // Write only the readers: a merge deep-merges the map and leaves expireAt/keep alone, so a
+            // Keep that landed after the read above is never put back to keep:false.
+            const patch = { recipients: Object.fromEntries(out.map((r) => [r.rid, r])) };
+            await recsCol().doc(id).set(patch, { merge: true });
+            return out;
+        },
+        async revoke(id, rids) {
+            const rec = await read(id);
+            if (!rec)
+                return [];
+            const hit = revokeIn(rec, rids);
+            if (!hit.length && rids !== '*')
+                return hit;
+            const patch = { recipients: Object.fromEntries(hit.map((rid) => [rid, { revokedAt: rec.recipients[rid].revokedAt }])) };
+            if (rec.revokedAll)
+                patch.revokedAll = rec.revokedAll;
+            await recsCol().doc(id).set(patch, { merge: true });
+            return hit;
+        },
+        async setExpiry(id, expireAt) {
+            await recsCol().doc(id).set({ expireAt, keep: expireAt === null }, { merge: true });
+        },
+        async useToken(key, expiresAt) {
+            // A Date is a Firestore Timestamp, which is what a TTL policy on `expireAt` reads.
+            try {
+                await tokensCol().doc(key).create({ expireAt: new Date(expiresAt) });
+                return true;
+            }
+            catch (e) {
+                if (e.code === 6)
+                    return false;
+                throw e;
+            }
+        },
+        async recordView(v) {
+            const ref = viewsCol().doc(viewId(v.artifactId, v.rid, v.session));
+            const snap = await ref.get();
+            await ref.set(addView(snap.exists ? snap.data() : undefined, v));
+        },
+        async views(id) {
+            const snap = await viewsCol().where('artifactId', '==', id).get();
+            return snap.docs.map((d) => d.data());
+        },
+        async expiring(now) {
+            const snap = await recsCol().where('expireAt', '<=', now).get();
+            return snap.docs.filter((d) => d.data().expireAt).map((d) => d.id);
+        },
+        async forget(id) {
+            await recsCol().doc(id).delete();
+            const snap = await viewsCol().where('artifactId', '==', id).get();
+            for (const d of snap.docs)
+                await d.ref.delete();
+        },
+    };
+}
+/** One line per reader (never the owner), in the order they were added. */
+export function summarizeViews(rec, views, comments) {
+    return Object.values(rec.recipients).filter((r) => !r.owner).sort((a, b) => a.addedAt.localeCompare(b.addedAt)).map((r) => {
+        const mine = views.filter((v) => v.rid === r.rid).sort((a, b) => a.firstAt.localeCompare(b.firstAt));
+        const firsts = mine.map((v) => Date.parse(v.firstAt));
+        return {
+            rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt,
+            opened: mine.length > 0,
+            firstOpenAt: mine[0]?.firstAt ?? null,
+            cameBack: firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= CAME_BACK_MS,
+            activeSeconds: mine.reduce((n, v) => n + v.activeSeconds, 0),
+            plays: mine.reduce((n, v) => n + Object.values(v.plays).reduce((a, b) => a + b, 0), 0),
+            devices: new Set(mine.map((v) => v.device)).size,
+            comments: comments.filter((c) => c.readerKey === `r:${r.rid}`).map((c) => ({ at: c.at, text: c.text })),
+        };
+    });
+}

package/lib/artifacts/recipients.d.ts

@@ -0,0 +1,31 @@
+export declare const RID_RE: RegExp;
+export declare const RID_COOKIE_MAX_AGE = 7776000;
+export declare const VIEW_AFTER_MS = 2000;
+export declare const TOKEN_MAX_AGE_MS = 86400000;
+/** A signing secret shorter than this is treated as unset by the routes: the page shuts. */
+export declare const RECIPIENT_SECRET_MIN = 32;
+export declare function usableSecret(secret: string | null | undefined): string | undefined;
+export declare function newRid(): string;
+export declare function ridSig(secret: string, id: string, rid: string): string;
+export declare function ridLink(pageUrl: string, id: string, rid: string, secret: string): string;
+export declare function parseRidParam(v: string | null | undefined): {
+    rid: string;
+    sig: string;
+} | null;
+export declare function verifyRid(secret: string, id: string, rid: string, sig: string): boolean;
+export declare function ridCookieName(id: string): string;
+/** `<time base36>.<nonce 16 hex>.<mac 16 hex>`, minted once per server render. */
+export declare function mintRenderToken(secret: string, id: string, rid: string, now?: number): string;
+export declare function verifyRenderToken(secret: string, id: string, rid: string, token: string, now?: number): {
+    ok: true;
+    key: string;
+    expiresAt: number;
+} | {
+    ok: false;
+    why: string;
+};
+export declare function beatKey(secret: string, id: string, rid: string, session: string): string;
+/** 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 declare const UNFURL_AGENTS: RegExp;
+export declare function isUnfurlAgent(ua: string | null | undefined): boolean;