nixamp 0.28.41 → 0.28.42

package/dist/ads.d.ts

@@ -0,0 +1,11 @@
+export type Advert = {
+    url: string;
+    kind: "audio" | "video";
+} | {
+    url: null;
+};
+export declare function nextAdvert(kindParam: string | null, deps?: {
+    fetchImpl?: typeof fetch;
+    origin?: string;
+    slot?: string;
+}): Promise<Advert>;

package/dist/ads.js

@@ -0,0 +1,73 @@
+// Where an advert for a break comes from.
+//
+// nixamp does not decide which advert plays, or record that it played. Both
+// belong to the ad network: it runs the auction and meters the impression, and
+// a second opinion here would be a second set of numbers. This module is a
+// proxy with an opinion about failure, nothing more.
+//
+// The opinion is that a break nobody can fill does not happen. The player
+// treats anything without a url as "no advert" and keeps playing music, which
+// is the only behaviour worth defaulting to when the alternative is silence in
+// somebody's ears.
+/** The network's break endpoint. Overridable so a deployment can point elsewhere. */
+const AD_ORIGIN = process.env.AD_ORIGIN ?? "https://crawlproof.com";
+/**
+ * This property's slot at the network.
+ *
+ * Without it there is nothing to ask about, and asking anyway would spend a
+ * request per break to be told the same thing. Unset means adverts are off for
+ * this deployment, which is the right default for somebody running nixamp on
+ * their own machine: their listeners are themselves.
+ */
+const AD_SLOT = process.env.AD_SLOT ?? "";
+/**
+ * How long to wait.
+ *
+ * A break is a gap in the music, so the budget is what a listener will not
+ * notice. Past it the advert is simply not worth having — the player falls back
+ * to content, which is a better outcome than a pause while a third party thinks
+ * about it.
+ */
+const TIMEOUT_MS = 1500;
+/** No advert. The shape the player expects, not an error. */
+const NONE = { url: null };
+export async function nextAdvert(kindParam, deps = {}) {
+    const slot = deps.slot ?? AD_SLOT;
+    if (!slot)
+        return NONE;
+    // Audio unless a caller says otherwise. nixamp is a music player: the artwork
+    // stays where it is and a video creative has nowhere to go.
+    const kind = kindParam === "video" ? "video" : "audio";
+    const doFetch = deps.fetchImpl ?? fetch;
+    const origin = deps.origin ?? AD_ORIGIN;
+    // AbortSignal.timeout rather than a race, so the socket is actually closed
+    // rather than left running behind a promise nobody reads.
+    try {
+        const res = await doFetch(`${origin}/api/ads/stream?slot=${encodeURIComponent(slot)}&kind=${kind}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+        if (!res.ok)
+            return NONE;
+        const body = (await res.json());
+        // Only https, and only a real string. This url is handed to a media element
+        // in somebody's browser, so a javascript: or data: value arriving from the
+        // network must not survive being proxied through here.
+        if (typeof body.url !== "string")
+            return NONE;
+        let parsed;
+        try {
+            parsed = new URL(body.url);
+        }
+        catch {
+            return NONE;
+        }
+        if (parsed.protocol !== "https:")
+            return NONE;
+        return {
+            url: parsed.toString(),
+            kind: body.kind === "video" ? "video" : "audio",
+        };
+    }
+    catch {
+        // A timeout, a refused connection, malformed JSON. All the same answer.
+        return NONE;
+    }
+}

package/dist/remote-subject.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Naming a join link by asking the server it points at.
+ *
+ * A link preview is read before any script runs, so the shell has to say what
+ * is on the air. When the linked server is in this directory, its listing says
+ * so and joinSubject answers from that. When it is not — somebody's own nixamp,
+ * shared directly — there was nothing to say and the card fell back to the
+ * site's generic title.
+ *
+ * The rule that produced that fallback is worth keeping: a name taken from the
+ * query string would let whoever wrote the link choose how the card reads on
+ * somebody else's domain, which is a phishing primitive rather than a feature.
+ * So the name is not taken from the query. It is fetched from the server the
+ * link points at, which can only describe itself.
+ *
+ * The share key travels in the link, and a server that is key-gated answers
+ * only with it. Using it here grants nothing new: whoever holds the link
+ * already holds the key.
+ */
+/** What a join card needs, matching joinSubject's shape. */
+export interface RemoteSubject {
+    title: string;
+    where: string;
+    image?: string;
+    kind?: "audio" | "video";
+}
+/** The share key a link carries, from /view/<key> or ?k=. */
+export declare function keyFromLink(link: URL): string;
+/**
+ * Ask the linked server what it is called, and what the wanted channel is
+ * called on it.
+ *
+ * Returns null for every failure — an unreachable server, a refusal, a shape
+ * that is not what we expect, an address we will not fetch. The caller then
+ * renders the generic shell, which is what it did before.
+ */
+export declare function remoteSubject(linkHref: string, wantedChannel: string, deps?: {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): Promise<RemoteSubject | null>;
+/** Testing seam: the cache outlives a request by design. */
+export declare function __clearRemoteSubjectCache(): void;

package/dist/remote-subject.js

@@ -0,0 +1,149 @@
+/**
+ * Naming a join link by asking the server it points at.
+ *
+ * A link preview is read before any script runs, so the shell has to say what
+ * is on the air. When the linked server is in this directory, its listing says
+ * so and joinSubject answers from that. When it is not — somebody's own nixamp,
+ * shared directly — there was nothing to say and the card fell back to the
+ * site's generic title.
+ *
+ * The rule that produced that fallback is worth keeping: a name taken from the
+ * query string would let whoever wrote the link choose how the card reads on
+ * somebody else's domain, which is a phishing primitive rather than a feature.
+ * So the name is not taken from the query. It is fetched from the server the
+ * link points at, which can only describe itself.
+ *
+ * The share key travels in the link, and a server that is key-gated answers
+ * only with it. Using it here grants nothing new: whoever holds the link
+ * already holds the key.
+ */
+/**
+ * How long to wait for a server to name itself.
+ *
+ * This runs before the page is sent, so it is a budget for somebody waiting on
+ * a tab to open. A server that is slow, asleep or gone simply does not name the
+ * card, which is exactly what happened before this existed.
+ */
+const TIMEOUT_MS = 1200;
+/**
+ * How long an answer is reused.
+ *
+ * A link shared into a busy channel is fetched once per crawler that unfurls
+ * it, and they arrive together. A minute is long enough to collapse that into
+ * one request and short enough that renaming a channel shows up while somebody
+ * is still looking at it.
+ */
+const TTL_MS = 60_000;
+const cache = new Map();
+/**
+ * Hosts a server must never be asked to fetch.
+ *
+ * The address comes from the query string, so without this the page is a probe
+ * anyone can point at anything this machine can reach — a cloud metadata
+ * endpoint, a database admin port, a service on the loopback interface. The
+ * cost of being wrong here is not a bad preview, it is an open proxy.
+ */
+function isPubliclyRoutable(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local"))
+        return false;
+    // IPv6 loopback and the unique-local / link-local ranges.
+    if (host === "::1" || host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80")) {
+        return false;
+    }
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        if (a === 10 || a === 127 || a === 0)
+            return false;
+        if (a === 172 && b >= 16 && b <= 31)
+            return false;
+        if (a === 192 && b === 168)
+            return false;
+        if (a === 169 && b === 254)
+            return false; // link-local, and AWS metadata
+        if (a >= 224)
+            return false; // multicast and reserved
+    }
+    return true;
+}
+/** The share key a link carries, from /view/<key> or ?k=. */
+export function keyFromLink(link) {
+    const viewed = /^\/view\/([^/]+)\/?$/.exec(link.pathname);
+    if (viewed?.[1])
+        return decodeURIComponent(viewed[1]);
+    return link.searchParams.get("k") ?? "";
+}
+/**
+ * Ask the linked server what it is called, and what the wanted channel is
+ * called on it.
+ *
+ * Returns null for every failure — an unreachable server, a refusal, a shape
+ * that is not what we expect, an address we will not fetch. The caller then
+ * renders the generic shell, which is what it did before.
+ */
+export async function remoteSubject(linkHref, wantedChannel, deps = {}) {
+    let link;
+    try {
+        link = new URL(linkHref);
+    }
+    catch {
+        return null;
+    }
+    // https only. An http link from an https page is blockable mixed content in
+    // the browser anyway, and fetching it here would be the one part of the
+    // journey that was not protected.
+    if (link.protocol !== "https:")
+        return null;
+    if (!isPubliclyRoutable(link.hostname))
+        return null;
+    const key = keyFromLink(link);
+    const cacheKey = `${link.origin}|${key}|${wantedChannel}`;
+    const now = deps.now ?? Date.now;
+    const hit = cache.get(cacheKey);
+    if (hit && now() - hit.at < TTL_MS)
+        return hit.subject;
+    const doFetch = deps.fetchImpl ?? fetch;
+    let subject = null;
+    try {
+        const asked = new URL("/api/streams", link.origin);
+        if (key !== "")
+            asked.searchParams.set("k", key);
+        const answer = await doFetch(asked.toString(), {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (answer.ok) {
+            const body = (await answer.json());
+            const where = typeof body.server?.name === "string" ? body.server.name : "";
+            const channels = Array.isArray(body.channels) ? body.channels : [];
+            const found = wantedChannel === ""
+                ? undefined
+                : channels.find((one) => one.id === wantedChannel || one.name === wantedChannel);
+            if (found && typeof found.name === "string" && found.name !== "") {
+                subject = {
+                    title: found.name,
+                    where,
+                    ...(typeof found.art === "string" && found.art !== "" ? { image: found.art } : {}),
+                    ...(found.kind === "audio" || found.kind === "video" ? { kind: found.kind } : {}),
+                };
+            }
+            else if (wantedChannel === "" && where !== "") {
+                // No channel asked for: the server itself is the subject.
+                subject = { title: where, where: "" };
+            }
+        }
+    }
+    catch {
+        // Unreachable, refused, timed out, or not JSON. All the same answer.
+        subject = null;
+    }
+    // Failures are cached too, deliberately: a server that is down should not be
+    // re-asked by every crawler unfurling the same link in the same minute.
+    cache.set(cacheKey, { at: now(), subject });
+    return subject;
+}
+/** Testing seam: the cache outlives a request by design. */
+export function __clearRemoteSubjectCache() {
+    cache.clear();
+}

package/dist/server.js

@@ -100,6 +100,8 @@ import { fileURLToPath } from "node:url";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
 import { Analyser, bandEdges, bands, decay } from "./fft.js";
 import { loadSource, loadTagged, readRemoteIndex } from "./playlist.js";
+import { nextAdvert } from "./ads.js";
+import { remoteSubject } from "./remote-subject.js";
 import { emptySnapshot, parseCommand, } from "./protocol.js";
 const FFT_SIZE = 2048;
 export const SERVE_BAND_COUNT = 24;
@@ -1146,6 +1148,13 @@ export function isSignInPath(path) {
         path.startsWith("/api/v1/me/profile/") ||
         // A stored photo is public: it is on every class the host runs.
         path.startsWith("/api/v1/profiles/") ||
+        // An advert for a break. It has to answer without a key for the same
+        // reason it exists: the listeners who get adverts are the ones who have
+        // not signed in or paid.
+        path === "/api/ads/next" ||
+        // What this listener has paid for, asked before every break by the same
+        // people and for the same reason, so it answers on the same terms.
+        path === "/api/entitlements" ||
         // "Connect nixamp" on a site that is a client of nixamp.com.
         nixampLinkPath(path) ||
         // Public to read, so it must not be behind a share key either.
@@ -1948,6 +1957,37 @@ export function createHandler(engine, options) {
             void partyLine.handle(event.data ?? {}).catch(() => { });
             return;
         }
+        // An advert for a break.
+        //
+        // Answered here, before the key check, because the listeners who get
+        // adverts are precisely the ones with no key and no session. The player
+        // asks for this when a break is due and treats anything but a url as "no
+        // advert", so every failure below is a silent null: a break nobody can
+        // fill simply does not happen and the listener keeps their music.
+        //
+        // Nothing about which advert to play is decided here. That is crawlproof's
+        // auction, and it meters the impression — so this must not cache, retry, or
+        // ask twice for one break.
+        if (path === "/api/ads/next" && request.method === "GET") {
+            json(response, 200, await nextAdvert(url.searchParams.get("kind")));
+            return;
+        }
+        // What this listener has paid for.
+        //
+        // Nothing yet, and saying so is the point. The player asks this before
+        // every break to decide whether to run one; with no route it asked, got a
+        // 404 on every page load, and read the miss as "holds nothing" — the right
+        // answer by the wrong road, and a console error that looked like a fault
+        // to anybody who opened the devtools.
+        //
+        // An empty list is the honest reply while nixamp has no OpenAccess client:
+        // there is no pass to hold, so nobody holds one. The shape is the one the
+        // player already reads, so wiring the hub later is a change here and
+        // nowhere else.
+        if (path === "/api/entitlements" && request.method === "GET") {
+            json(response, 200, { entitlements: [] });
+            return;
+        }
         // /api/health answers unauthenticated on purpose: it is how you check the
         // port is open from another device before wondering whether the link is
         // wrong, and it says nothing about the library.
@@ -5314,7 +5354,20 @@ export function createHandler(engine, options) {
                     catch { }
                 }
                 if (file.endsWith("index.html") && path === "/") {
-                    const subject = joinSubject(url, options);
+                    // The directory first: a listed server is named by the listing this
+                    // site already holds, with no request to anybody.
+                    let subject = joinSubject(url, options);
+                    if (subject === null) {
+                        // Not listed. Ask the server the link points at what it is called,
+                        // rather than reading a name out of the query — a name from the
+                        // query would let whoever wrote the link choose how the card reads
+                        // on this domain, which is a phishing primitive, not a feature.
+                        const link = url.searchParams.get("url") ?? "";
+                        const play = url.searchParams.get("play") ?? "";
+                        if (link !== "") {
+                            subject = await remoteSubject(link, play.startsWith("channel:") ? play.slice("channel:".length) : "");
+                        }
+                    }
                     const shell = subject ? readIfPossible(file) : null;
                     if (subject && shell !== null) {
                         html(response, 200, joinDocument(shell, subject, eventSite ?? "https://nixamp.com"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.28.41",
+  "version": "0.28.42",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/ads.ts

@@ -0,0 +1,84 @@
+// Where an advert for a break comes from.
+//
+// nixamp does not decide which advert plays, or record that it played. Both
+// belong to the ad network: it runs the auction and meters the impression, and
+// a second opinion here would be a second set of numbers. This module is a
+// proxy with an opinion about failure, nothing more.
+//
+// The opinion is that a break nobody can fill does not happen. The player
+// treats anything without a url as "no advert" and keeps playing music, which
+// is the only behaviour worth defaulting to when the alternative is silence in
+// somebody's ears.
+
+/** The network's break endpoint. Overridable so a deployment can point elsewhere. */
+const AD_ORIGIN = process.env.AD_ORIGIN ?? "https://crawlproof.com";
+
+/**
+ * This property's slot at the network.
+ *
+ * Without it there is nothing to ask about, and asking anyway would spend a
+ * request per break to be told the same thing. Unset means adverts are off for
+ * this deployment, which is the right default for somebody running nixamp on
+ * their own machine: their listeners are themselves.
+ */
+const AD_SLOT = process.env.AD_SLOT ?? "";
+
+/**
+ * How long to wait.
+ *
+ * A break is a gap in the music, so the budget is what a listener will not
+ * notice. Past it the advert is simply not worth having — the player falls back
+ * to content, which is a better outcome than a pause while a third party thinks
+ * about it.
+ */
+const TIMEOUT_MS = 1500;
+
+export type Advert = { url: string; kind: "audio" | "video" } | { url: null };
+
+/** No advert. The shape the player expects, not an error. */
+const NONE: Advert = { url: null };
+
+export async function nextAdvert(
+  kindParam: string | null,
+  deps: { fetchImpl?: typeof fetch; origin?: string; slot?: string } = {},
+): Promise<Advert> {
+  const slot = deps.slot ?? AD_SLOT;
+  if (!slot) return NONE;
+
+  // Audio unless a caller says otherwise. nixamp is a music player: the artwork
+  // stays where it is and a video creative has nowhere to go.
+  const kind = kindParam === "video" ? "video" : "audio";
+  const doFetch = deps.fetchImpl ?? fetch;
+  const origin = deps.origin ?? AD_ORIGIN;
+
+  // AbortSignal.timeout rather than a race, so the socket is actually closed
+  // rather than left running behind a promise nobody reads.
+  try {
+    const res = await doFetch(
+      `${origin}/api/ads/stream?slot=${encodeURIComponent(slot)}&kind=${kind}`,
+      { headers: { accept: "application/json" }, signal: AbortSignal.timeout(TIMEOUT_MS) },
+    );
+    if (!res.ok) return NONE;
+
+    const body = (await res.json()) as { url?: unknown; kind?: unknown };
+    // Only https, and only a real string. This url is handed to a media element
+    // in somebody's browser, so a javascript: or data: value arriving from the
+    // network must not survive being proxied through here.
+    if (typeof body.url !== "string") return NONE;
+    let parsed: URL;
+    try {
+      parsed = new URL(body.url);
+    } catch {
+      return NONE;
+    }
+    if (parsed.protocol !== "https:") return NONE;
+
+    return {
+      url: parsed.toString(),
+      kind: body.kind === "video" ? "video" : "audio",
+    };
+  } catch {
+    // A timeout, a refused connection, malformed JSON. All the same answer.
+    return NONE;
+  }
+}

package/src/remote-subject.ts

@@ -0,0 +1,166 @@
+/**
+ * Naming a join link by asking the server it points at.
+ *
+ * A link preview is read before any script runs, so the shell has to say what
+ * is on the air. When the linked server is in this directory, its listing says
+ * so and joinSubject answers from that. When it is not — somebody's own nixamp,
+ * shared directly — there was nothing to say and the card fell back to the
+ * site's generic title.
+ *
+ * The rule that produced that fallback is worth keeping: a name taken from the
+ * query string would let whoever wrote the link choose how the card reads on
+ * somebody else's domain, which is a phishing primitive rather than a feature.
+ * So the name is not taken from the query. It is fetched from the server the
+ * link points at, which can only describe itself.
+ *
+ * The share key travels in the link, and a server that is key-gated answers
+ * only with it. Using it here grants nothing new: whoever holds the link
+ * already holds the key.
+ */
+
+/** What /api/streams says about itself. Only the parts this file reads. */
+interface StreamsAnswer {
+  server?: { name?: unknown };
+  channels?: { id?: unknown; name?: unknown; art?: unknown; kind?: unknown }[];
+}
+
+/** What a join card needs, matching joinSubject's shape. */
+export interface RemoteSubject {
+  title: string;
+  where: string;
+  image?: string;
+  kind?: "audio" | "video";
+}
+
+/**
+ * How long to wait for a server to name itself.
+ *
+ * This runs before the page is sent, so it is a budget for somebody waiting on
+ * a tab to open. A server that is slow, asleep or gone simply does not name the
+ * card, which is exactly what happened before this existed.
+ */
+const TIMEOUT_MS = 1200;
+
+/**
+ * How long an answer is reused.
+ *
+ * A link shared into a busy channel is fetched once per crawler that unfurls
+ * it, and they arrive together. A minute is long enough to collapse that into
+ * one request and short enough that renaming a channel shows up while somebody
+ * is still looking at it.
+ */
+const TTL_MS = 60_000;
+
+const cache = new Map<string, { at: number; subject: RemoteSubject | null }>();
+
+/**
+ * Hosts a server must never be asked to fetch.
+ *
+ * The address comes from the query string, so without this the page is a probe
+ * anyone can point at anything this machine can reach — a cloud metadata
+ * endpoint, a database admin port, a service on the loopback interface. The
+ * cost of being wrong here is not a bad preview, it is an open proxy.
+ */
+function isPubliclyRoutable(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) return false;
+  // IPv6 loopback and the unique-local / link-local ranges.
+  if (host === "::1" || host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80")) {
+    return false;
+  }
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    if (a === 10 || a === 127 || a === 0) return false;
+    if (a === 172 && b >= 16 && b <= 31) return false;
+    if (a === 192 && b === 168) return false;
+    if (a === 169 && b === 254) return false; // link-local, and AWS metadata
+    if (a >= 224) return false; // multicast and reserved
+  }
+  return true;
+}
+
+/** The share key a link carries, from /view/<key> or ?k=. */
+export function keyFromLink(link: URL): string {
+  const viewed = /^\/view\/([^/]+)\/?$/.exec(link.pathname);
+  if (viewed?.[1]) return decodeURIComponent(viewed[1]);
+  return link.searchParams.get("k") ?? "";
+}
+
+/**
+ * Ask the linked server what it is called, and what the wanted channel is
+ * called on it.
+ *
+ * Returns null for every failure — an unreachable server, a refusal, a shape
+ * that is not what we expect, an address we will not fetch. The caller then
+ * renders the generic shell, which is what it did before.
+ */
+export async function remoteSubject(
+  linkHref: string,
+  wantedChannel: string,
+  deps: { fetchImpl?: typeof fetch; now?: () => number } = {},
+): Promise<RemoteSubject | null> {
+  let link: URL;
+  try {
+    link = new URL(linkHref);
+  } catch {
+    return null;
+  }
+
+  // https only. An http link from an https page is blockable mixed content in
+  // the browser anyway, and fetching it here would be the one part of the
+  // journey that was not protected.
+  if (link.protocol !== "https:") return null;
+  if (!isPubliclyRoutable(link.hostname)) return null;
+
+  const key = keyFromLink(link);
+  const cacheKey = `${link.origin}|${key}|${wantedChannel}`;
+  const now = deps.now ?? Date.now;
+  const hit = cache.get(cacheKey);
+  if (hit && now() - hit.at < TTL_MS) return hit.subject;
+
+  const doFetch = deps.fetchImpl ?? fetch;
+  let subject: RemoteSubject | null = null;
+
+  try {
+    const asked = new URL("/api/streams", link.origin);
+    if (key !== "") asked.searchParams.set("k", key);
+    const answer = await doFetch(asked.toString(), {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (answer.ok) {
+      const body = (await answer.json()) as StreamsAnswer;
+      const where = typeof body.server?.name === "string" ? body.server.name : "";
+      const channels = Array.isArray(body.channels) ? body.channels : [];
+      const found = wantedChannel === ""
+        ? undefined
+        : channels.find((one) => one.id === wantedChannel || one.name === wantedChannel);
+
+      if (found && typeof found.name === "string" && found.name !== "") {
+        subject = {
+          title: found.name,
+          where,
+          ...(typeof found.art === "string" && found.art !== "" ? { image: found.art } : {}),
+          ...(found.kind === "audio" || found.kind === "video" ? { kind: found.kind } : {}),
+        };
+      } else if (wantedChannel === "" && where !== "") {
+        // No channel asked for: the server itself is the subject.
+        subject = { title: where, where: "" };
+      }
+    }
+  } catch {
+    // Unreachable, refused, timed out, or not JSON. All the same answer.
+    subject = null;
+  }
+
+  // Failures are cached too, deliberately: a server that is down should not be
+  // re-asked by every crawler unfurling the same link in the same minute.
+  cache.set(cacheKey, { at: now(), subject });
+  return subject;
+}
+
+/** Testing seam: the cache outlives a request by design. */
+export function __clearRemoteSubjectCache(): void {
+  cache.clear();
+}