@igstack/app-catalog-backend-core 1.0.1 → 2.0.0-alpha-20260914220838

package/dist/modules/comments/service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.mts","names":[],"sources":["../../../src/modules/comments/service.ts"],"mappings":";AAIA;AAAA,cAAa,cAAA;AAAA,cAEA,eAAA;;UAGI,WAAA;EACf,EAAA;EACA,UAAA;EACA,IAAA;EACA,SAAA;EAP0B;EAS1B,QAAA;EAN0B;EAQ1B,MAAA;EAR0B;;;;;;EAe1B,YAAA;AAAA"}

package/dist/modules/comments/service.mjs

@@ -0,0 +1,86 @@
+import { getDbClient } from "../../db/client.mjs";
+
+//#region src/modules/comments/service.ts
+/** How long an author may edit or delete their own comment. */
+const EDIT_WINDOW_MS = 3600 * 1e3;
+const MAX_BODY_LENGTH = 1e3;
+function toView(row, visitor) {
+	const isMine = !!visitor && row.authorHash === visitor.hash;
+	return {
+		id: row.id,
+		authorName: row.authorAlias,
+		body: row.body,
+		createdAt: row.createdAt.toISOString(),
+		editedAt: row.editedAt?.toISOString() ?? null,
+		isMine,
+		canEditUntil: isMine ? new Date(row.createdAt.getTime() + EDIT_WINDOW_MS).toISOString() : null
+	};
+}
+async function resourceIdForSlug(slug) {
+	return (await getDbClient().dbResource.findUnique({
+		where: { slug },
+		select: { id: true }
+	}))?.id ?? null;
+}
+/** Oldest first: a comment thread reads top to bottom. */
+async function listComments(resourceSlug, visitor) {
+	const resourceId = await resourceIdForSlug(resourceSlug);
+	if (!resourceId) return [];
+	return (await getDbClient().dbComment.findMany({
+		where: { resourceId },
+		orderBy: { createdAt: "asc" }
+	})).map((row) => toView(row, visitor));
+}
+var CommentError = class extends Error {
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+	}
+};
+function normaliseBody(body) {
+	const trimmed = body.trim();
+	if (!trimmed) throw new CommentError("empty", "A comment cannot be empty");
+	return trimmed.slice(0, MAX_BODY_LENGTH);
+}
+async function addComment(resourceSlug, body, visitor) {
+	const resourceId = await resourceIdForSlug(resourceSlug);
+	if (!resourceId) throw new CommentError("not-found", `Unknown resource: ${resourceSlug}`);
+	return toView(await getDbClient().dbComment.create({ data: {
+		resourceId,
+		authorHash: visitor.hash,
+		authorAlias: visitor.alias,
+		body: normaliseBody(body)
+	} }), visitor);
+}
+/**
+* Load a comment and check this visitor may still change it.
+*
+* The window is enforced here, not in the UI: the controls disappearing is a
+* courtesy, and a request that arrives a second late must still be refused.
+*/
+async function loadOwn(id, visitor) {
+	const row = await getDbClient().dbComment.findUnique({ where: { id } });
+	if (!row) throw new CommentError("not-found", "Comment no longer exists");
+	if (row.authorHash !== visitor.hash) throw new CommentError("not-author", "Only the author can change a comment");
+	if (Date.now() > row.createdAt.getTime() + 36e5) throw new CommentError("window-closed", "A comment can only be changed in the first hour");
+	return row;
+}
+async function editComment(id, body, visitor) {
+	await loadOwn(id, visitor);
+	return toView(await getDbClient().dbComment.update({
+		where: { id },
+		data: {
+			body: normaliseBody(body),
+			editedAt: /* @__PURE__ */ new Date()
+		}
+	}), visitor);
+}
+async function deleteComment(id, visitor) {
+	await loadOwn(id, visitor);
+	await getDbClient().dbComment.delete({ where: { id } });
+	return { id };
+}
+
+//#endregion
+export { CommentError, EDIT_WINDOW_MS, MAX_BODY_LENGTH, addComment, deleteComment, editComment, listComments };
+//# sourceMappingURL=service.mjs.map

package/dist/modules/comments/service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/modules/comments/service.ts"],"sourcesContent":["import { getDbClient } from '../../db/client'\nimport type { Visitor } from './visitorIdentity'\n\n/** How long an author may edit or delete their own comment. */\nexport const EDIT_WINDOW_MS = 60 * 60 * 1000\n\nexport const MAX_BODY_LENGTH = 1000\n\n/** One comment as a client sees it. Never carries an author hash. */\nexport interface CommentView {\n  id: string\n  authorName: string\n  body: string\n  createdAt: string\n  /** Null when the comment has never been edited. */\n  editedAt: string | null\n  /** Whether this browser wrote it — what makes Edit and Delete appear. */\n  isMine: boolean\n  /**\n   * The absolute instant this browser's edit window closes, or null when it is not\n   * this browser's comment. Absolute rather than a remaining duration so a client\n   * with a skewed clock still hides the controls at the same moment the server\n   * starts refusing the edit.\n   */\n  canEditUntil: string | null\n}\n\nfunction toView(\n  row: {\n    id: string\n    authorHash: string\n    authorAlias: string\n    body: string\n    editedAt: Date | null\n    createdAt: Date\n  },\n  visitor: Visitor | null,\n): CommentView {\n  const isMine = !!visitor && row.authorHash === visitor.hash\n  return {\n    id: row.id,\n    authorName: row.authorAlias,\n    body: row.body,\n    createdAt: row.createdAt.toISOString(),\n    editedAt: row.editedAt?.toISOString() ?? null,\n    isMine,\n    canEditUntil: isMine\n      ? new Date(row.createdAt.getTime() + EDIT_WINDOW_MS).toISOString()\n      : null,\n  }\n}\n\nasync function resourceIdForSlug(slug: string): Promise<string | null> {\n  const resource = await getDbClient().dbResource.findUnique({\n    where: { slug },\n    select: { id: true },\n  })\n  return resource?.id ?? null\n}\n\n/** Oldest first: a comment thread reads top to bottom. */\nexport async function listComments(\n  resourceSlug: string,\n  visitor: Visitor | null,\n): Promise<CommentView[]> {\n  const resourceId = await resourceIdForSlug(resourceSlug)\n  if (!resourceId) return []\n\n  const rows = await getDbClient().dbComment.findMany({\n    where: { resourceId },\n    orderBy: { createdAt: 'asc' },\n  })\n  return rows.map((row) => toView(row, visitor))\n}\n\nexport class CommentError extends Error {\n  constructor(\n    readonly reason: 'not-found' | 'not-author' | 'window-closed' | 'empty',\n    message: string,\n  ) {\n    super(message)\n  }\n}\n\nfunction normaliseBody(body: string): string {\n  const trimmed = body.trim()\n  if (!trimmed) throw new CommentError('empty', 'A comment cannot be empty')\n  return trimmed.slice(0, MAX_BODY_LENGTH)\n}\n\nexport async function addComment(\n  resourceSlug: string,\n  body: string,\n  visitor: Visitor,\n): Promise<CommentView> {\n  const resourceId = await resourceIdForSlug(resourceSlug)\n  if (!resourceId) {\n    throw new CommentError('not-found', `Unknown resource: ${resourceSlug}`)\n  }\n\n  const row = await getDbClient().dbComment.create({\n    data: {\n      resourceId,\n      authorHash: visitor.hash,\n      authorAlias: visitor.alias,\n      body: normaliseBody(body),\n    },\n  })\n  return toView(row, visitor)\n}\n\n/**\n * Load a comment and check this visitor may still change it.\n *\n * The window is enforced here, not in the UI: the controls disappearing is a\n * courtesy, and a request that arrives a second late must still be refused.\n */\nasync function loadOwn(id: string, visitor: Visitor) {\n  const row = await getDbClient().dbComment.findUnique({ where: { id } })\n  if (!row) throw new CommentError('not-found', 'Comment no longer exists')\n  if (row.authorHash !== visitor.hash) {\n    throw new CommentError('not-author', 'Only the author can change a comment')\n  }\n  if (Date.now() > row.createdAt.getTime() + EDIT_WINDOW_MS) {\n    throw new CommentError(\n      'window-closed',\n      'A comment can only be changed in the first hour',\n    )\n  }\n  return row\n}\n\nexport async function editComment(\n  id: string,\n  body: string,\n  visitor: Visitor,\n): Promise<CommentView> {\n  await loadOwn(id, visitor)\n\n  const row = await getDbClient().dbComment.update({\n    where: { id },\n    data: { body: normaliseBody(body), editedAt: new Date() },\n  })\n  return toView(row, visitor)\n}\n\nexport async function deleteComment(\n  id: string,\n  visitor: Visitor,\n): Promise<{ id: string }> {\n  await loadOwn(id, visitor)\n  await getDbClient().dbComment.delete({ where: { id } })\n  return { id }\n}\n"],"mappings":";;;;AAIA,MAAa,iBAAiB,OAAU;AAExC,MAAa,kBAAkB;AAqB/B,SAAS,OACP,KAQA,SACa;CACb,MAAM,SAAS,CAAC,CAAC,WAAW,IAAI,eAAe,QAAQ;AACvD,QAAO;EACL,IAAI,IAAI;EACR,YAAY,IAAI;EAChB,MAAM,IAAI;EACV,WAAW,IAAI,UAAU,aAAa;EACtC,UAAU,IAAI,UAAU,aAAa,IAAI;EACzC;EACA,cAAc,SACV,IAAI,KAAK,IAAI,UAAU,SAAS,GAAG,eAAe,CAAC,aAAa,GAChE;EACL;;AAGH,eAAe,kBAAkB,MAAsC;AAKrE,SAJiB,MAAM,aAAa,CAAC,WAAW,WAAW;EACzD,OAAO,EAAE,MAAM;EACf,QAAQ,EAAE,IAAI,MAAM;EACrB,CAAC,GACe,MAAM;;;AAIzB,eAAsB,aACpB,cACA,SACwB;CACxB,MAAM,aAAa,MAAM,kBAAkB,aAAa;AACxD,KAAI,CAAC,WAAY,QAAO,EAAE;AAM1B,SAJa,MAAM,aAAa,CAAC,UAAU,SAAS;EAClD,OAAO,EAAE,YAAY;EACrB,SAAS,EAAE,WAAW,OAAO;EAC9B,CAAC,EACU,KAAK,QAAQ,OAAO,KAAK,QAAQ,CAAC;;AAGhD,IAAa,eAAb,cAAkC,MAAM;CACtC,YACE,AAAS,QACT,SACA;AACA,QAAM,QAAQ;EAHL;;;AAOb,SAAS,cAAc,MAAsB;CAC3C,MAAM,UAAU,KAAK,MAAM;AAC3B,KAAI,CAAC,QAAS,OAAM,IAAI,aAAa,SAAS,4BAA4B;AAC1E,QAAO,QAAQ,MAAM,GAAG,gBAAgB;;AAG1C,eAAsB,WACpB,cACA,MACA,SACsB;CACtB,MAAM,aAAa,MAAM,kBAAkB,aAAa;AACxD,KAAI,CAAC,WACH,OAAM,IAAI,aAAa,aAAa,qBAAqB,eAAe;AAW1E,QAAO,OARK,MAAM,aAAa,CAAC,UAAU,OAAO,EAC/C,MAAM;EACJ;EACA,YAAY,QAAQ;EACpB,aAAa,QAAQ;EACrB,MAAM,cAAc,KAAK;EAC1B,EACF,CAAC,EACiB,QAAQ;;;;;;;;AAS7B,eAAe,QAAQ,IAAY,SAAkB;CACnD,MAAM,MAAM,MAAM,aAAa,CAAC,UAAU,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,KAAI,CAAC,IAAK,OAAM,IAAI,aAAa,aAAa,2BAA2B;AACzE,KAAI,IAAI,eAAe,QAAQ,KAC7B,OAAM,IAAI,aAAa,cAAc,uCAAuC;AAE9E,KAAI,KAAK,KAAK,GAAG,IAAI,UAAU,SAAS,QACtC,OAAM,IAAI,aACR,iBACA,kDACD;AAEH,QAAO;;AAGT,eAAsB,YACpB,IACA,MACA,SACsB;AACtB,OAAM,QAAQ,IAAI,QAAQ;AAM1B,QAAO,OAJK,MAAM,aAAa,CAAC,UAAU,OAAO;EAC/C,OAAO,EAAE,IAAI;EACb,MAAM;GAAE,MAAM,cAAc,KAAK;GAAE,0BAAU,IAAI,MAAM;GAAE;EAC1D,CAAC,EACiB,QAAQ;;AAG7B,eAAsB,cACpB,IACA,SACyB;AACzB,OAAM,QAAQ,IAAI,QAAQ;AAC1B,OAAM,aAAa,CAAC,UAAU,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvD,QAAO,EAAE,IAAI"}

package/dist/modules/comments/visitorIdentity.d.mts

@@ -0,0 +1,15 @@
+//#region src/modules/comments/visitorIdentity.d.ts
+/**
+ * Who the server thinks is commenting.
+ *
+ * The catalog is browsable without logging in, so there is no session to hang a
+ * comment on. `hash` is the only thing that authorises editing or deleting a
+ * comment later, and `alias` is the only name a reader ever sees.
+ */
+interface Visitor {
+  hash: string;
+  alias: string;
+}
+//#endregion
+export { Visitor };
+//# sourceMappingURL=visitorIdentity.d.mts.map

package/dist/modules/comments/visitorIdentity.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitorIdentity.d.mts","names":[],"sources":["../../../src/modules/comments/visitorIdentity.ts"],"mappings":";;;;;;;;UAeiB,OAAA;EACf,IAAA;EACA,KAAA;AAAA"}

package/dist/modules/comments/visitorIdentity.mjs

@@ -0,0 +1,121 @@
+import { getCookie } from "../../utils/cookies.mjs";
+import { createHash, randomUUID } from "node:crypto";
+
+//#region src/modules/comments/visitorIdentity.ts
+/** Opaque per-browser token. httpOnly, so page scripts cannot read or forge it. */
+const VISITOR_COOKIE = "ac_cid";
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1e3;
+const ADJECTIVES = [
+	"Ancient",
+	"Brave",
+	"Calm",
+	"Clever",
+	"Curious",
+	"Eager",
+	"Gentle",
+	"Happy",
+	"Honest",
+	"Humble",
+	"Jolly",
+	"Keen",
+	"Kind",
+	"Lively",
+	"Loyal",
+	"Merry",
+	"Mighty",
+	"Modest",
+	"Noble",
+	"Patient",
+	"Polite",
+	"Proud",
+	"Quiet",
+	"Rapid",
+	"Silent",
+	"Smooth",
+	"Steady",
+	"Subtle",
+	"Sunny",
+	"Swift",
+	"Tidy",
+	"Witty"
+];
+const ANIMALS = [
+	"Badger",
+	"Beaver",
+	"Bison",
+	"Crane",
+	"Dolphin",
+	"Falcon",
+	"Ferret",
+	"Finch",
+	"Fox",
+	"Gecko",
+	"Heron",
+	"Ibex",
+	"Jackal",
+	"Kestrel",
+	"Lemur",
+	"Lynx",
+	"Magpie",
+	"Marten",
+	"Mole",
+	"Narwhal",
+	"Ocelot",
+	"Osprey",
+	"Otter",
+	"Panda",
+	"Puffin",
+	"Raven",
+	"Seal",
+	"Shrew",
+	"Stoat",
+	"Tapir",
+	"Vole",
+	"Walrus"
+];
+/**
+* A stable, readable name for a visitor hash, e.g. "Curious Ferret".
+*
+* Deterministic, so the same browser keeps the same name across comments — but it
+* is derived once and stored on the row, because widening these lists later would
+* otherwise rename every comment ever written.
+*/
+function aliasForHash(hash) {
+	return `${ADJECTIVES[parseInt(hash.slice(0, 8), 16) % ADJECTIVES.length]} ${ANIMALS[parseInt(hash.slice(8, 16), 16) % ANIMALS.length]}`;
+}
+function hashToken(token) {
+	return createHash("sha256").update(token).digest("hex");
+}
+/**
+* Read the visitor token, issuing one when this browser has none yet.
+*
+* Called on every tRPC request rather than only when commenting: the cookie has to
+* already exist by the time someone clicks Post, and issuing it on the read that
+* renders the comment list is the one moment we know a page is open.
+*
+* `res` is absent on internally-created contexts (see createAcMiddleware), and
+* those never comment — they get an identity derived from the token they carry, if
+* any, and cannot be issued a new one.
+*/
+function resolveVisitor(req, res) {
+	let token = getCookie(req, VISITOR_COOKIE);
+	if (!token) {
+		if (!res) return null;
+		token = randomUUID();
+		res.cookie(VISITOR_COOKIE, token, {
+			httpOnly: true,
+			sameSite: "lax",
+			path: "/",
+			maxAge: ONE_YEAR_MS
+		});
+	}
+	const hash = hashToken(token);
+	return {
+		hash,
+		alias: aliasForHash(hash)
+	};
+}
+
+//#endregion
+export { resolveVisitor };
+//# sourceMappingURL=visitorIdentity.mjs.map

package/dist/modules/comments/visitorIdentity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitorIdentity.mjs","names":[],"sources":["../../../src/modules/comments/visitorIdentity.ts"],"sourcesContent":["import { createHash, randomUUID } from 'node:crypto'\nimport { getCookie } from '../../utils/cookies'\n\n/** Opaque per-browser token. httpOnly, so page scripts cannot read or forge it. */\nexport const VISITOR_COOKIE = 'ac_cid'\n\nconst ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000\n\n/**\n * Who the server thinks is commenting.\n *\n * The catalog is browsable without logging in, so there is no session to hang a\n * comment on. `hash` is the only thing that authorises editing or deleting a\n * comment later, and `alias` is the only name a reader ever sees.\n */\nexport interface Visitor {\n  hash: string\n  alias: string\n}\n\nconst ADJECTIVES = [\n  'Ancient',\n  'Brave',\n  'Calm',\n  'Clever',\n  'Curious',\n  'Eager',\n  'Gentle',\n  'Happy',\n  'Honest',\n  'Humble',\n  'Jolly',\n  'Keen',\n  'Kind',\n  'Lively',\n  'Loyal',\n  'Merry',\n  'Mighty',\n  'Modest',\n  'Noble',\n  'Patient',\n  'Polite',\n  'Proud',\n  'Quiet',\n  'Rapid',\n  'Silent',\n  'Smooth',\n  'Steady',\n  'Subtle',\n  'Sunny',\n  'Swift',\n  'Tidy',\n  'Witty',\n]\n\nconst ANIMALS = [\n  'Badger',\n  'Beaver',\n  'Bison',\n  'Crane',\n  'Dolphin',\n  'Falcon',\n  'Ferret',\n  'Finch',\n  'Fox',\n  'Gecko',\n  'Heron',\n  'Ibex',\n  'Jackal',\n  'Kestrel',\n  'Lemur',\n  'Lynx',\n  'Magpie',\n  'Marten',\n  'Mole',\n  'Narwhal',\n  'Ocelot',\n  'Osprey',\n  'Otter',\n  'Panda',\n  'Puffin',\n  'Raven',\n  'Seal',\n  'Shrew',\n  'Stoat',\n  'Tapir',\n  'Vole',\n  'Walrus',\n]\n\n/**\n * A stable, readable name for a visitor hash, e.g. \"Curious Ferret\".\n *\n * Deterministic, so the same browser keeps the same name across comments — but it\n * is derived once and stored on the row, because widening these lists later would\n * otherwise rename every comment ever written.\n */\nexport function aliasForHash(hash: string): string {\n  // Two independent slices of the hash, so the two words vary independently.\n  const adjective =\n    ADJECTIVES[parseInt(hash.slice(0, 8), 16) % ADJECTIVES.length]\n  const animal = ANIMALS[parseInt(hash.slice(8, 16), 16) % ANIMALS.length]\n  return `${adjective} ${animal}`\n}\n\nfunction hashToken(token: string): string {\n  return createHash('sha256').update(token).digest('hex')\n}\n\n/**\n * Read the visitor token, issuing one when this browser has none yet.\n *\n * Called on every tRPC request rather than only when commenting: the cookie has to\n * already exist by the time someone clicks Post, and issuing it on the read that\n * renders the comment list is the one moment we know a page is open.\n *\n * `res` is absent on internally-created contexts (see createAcMiddleware), and\n * those never comment — they get an identity derived from the token they carry, if\n * any, and cannot be issued a new one.\n */\nexport function resolveVisitor(\n  req: { headers: { cookie?: string } },\n  res?: {\n    cookie: (\n      name: string,\n      value: string,\n      options: Record<string, unknown>,\n    ) => unknown\n  },\n): Visitor | null {\n  let token = getCookie(req, VISITOR_COOKIE)\n\n  if (!token) {\n    if (!res) return null\n    token = randomUUID()\n    res.cookie(VISITOR_COOKIE, token, {\n      httpOnly: true,\n      sameSite: 'lax',\n      path: '/',\n      maxAge: ONE_YEAR_MS,\n    })\n  }\n\n  const hash = hashToken(token)\n  return { hash, alias: aliasForHash(hash) }\n}\n"],"mappings":";;;;;AAIA,MAAa,iBAAiB;AAE9B,MAAM,cAAc,MAAM,KAAK,KAAK,KAAK;AAczC,MAAM,aAAa;CACjB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAED,MAAM,UAAU;CACd;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,SAAgB,aAAa,MAAsB;AAKjD,QAAO,GAFL,WAAW,SAAS,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,GAAG,WAAW,QAErC,GADL,QAAQ,SAAS,KAAK,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,QAAQ;;AAInE,SAAS,UAAU,OAAuB;AACxC,QAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;;;;;;;;;;;;AAczD,SAAgB,eACd,KACA,KAOgB;CAChB,IAAI,QAAQ,UAAU,KAAK,eAAe;AAE1C,KAAI,CAAC,OAAO;AACV,MAAI,CAAC,IAAK,QAAO;AACjB,UAAQ,YAAY;AACpB,MAAI,OAAO,gBAAgB,OAAO;GAChC,UAAU;GACV,UAAU;GACV,MAAM;GACN,QAAQ;GACT,CAAC;;CAGJ,MAAM,OAAO,UAAU,MAAM;AAC7B,QAAO;EAAE;EAAM,OAAO,aAAa,KAAK;EAAE"}

package/dist/server/acTrpcContext.d.mts

@@ -1,4 +1,5 @@
 import { AppCatalogCompanySpecificBackend } from "../types/backend/companySpecificBackend.mjs";
+import { Visitor } from "../modules/comments/visitorIdentity.mjs";
 import { User } from "better-auth/types";
 
 //#region src/server/acTrpcContext.d.ts
@@ -6,16 +7,24 @@ interface AcTrpcContext {
   companySpecificBackend: AppCatalogCompanySpecificBackend;
   user: User | null;
   isAdmin: boolean;
+  /**
+   * The anonymous browser behind this request, independent of `user` — the catalog
+   * is browsable logged out, and comments are attributed to this instead. Null when
+   * the context was built without a response to issue the cookie on.
+   */
+  visitor: Visitor | null;
 }
 interface AcTrpcContextOptions {
   companySpecificBackend: AppCatalogCompanySpecificBackend;
   user?: User | null;
   isAdmin?: boolean;
+  visitor?: Visitor | null;
 }
 declare function createAcTrpcContext({
   companySpecificBackend,
   user,
-  isAdmin
+  isAdmin,
+  visitor
 }: AcTrpcContextOptions): AcTrpcContext;
 //#endregion
 export { AcTrpcContext, AcTrpcContextOptions, createAcTrpcContext };

package/dist/server/acTrpcContext.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"acTrpcContext.d.mts","names":[],"sources":["../../src/server/acTrpcContext.ts"],"mappings":";;;;UAGiB,aAAA;EACf,sBAAA,EAAwB,gCAAA;EACxB,IAAA,EAAM,IAAA;EACN,OAAA;AAAA;AAAA,UAGe,oBAAA;EACf,sBAAA,EAAwB,gCAAA;EACxB,IAAA,GAAO,IAAA;EACP,OAAA;AAAA;AAAA,iBAGc,mBAAA,CAAA;EACd,sBAAA;EACA,IAAA;EACA;AAAA,GACC,oBAAA,GAAuB,aAAA"}
+{"version":3,"file":"acTrpcContext.d.mts","names":[],"sources":["../../src/server/acTrpcContext.ts"],"mappings":";;;;;UAIiB,aAAA;EACf,sBAAA,EAAwB,gCAAA;EACxB,IAAA,EAAM,IAAA;EACN,OAAA;;;;;;EAMA,OAAA,EAAS,OAAA;AAAA;AAAA,UAGM,oBAAA;EACf,sBAAA,EAAwB,gCAAA;EACxB,IAAA,GAAO,IAAA;EACP,OAAA;EACA,OAAA,GAAU,OAAA;AAAA;AAAA,iBAGI,mBAAA,CAAA;EACd,sBAAA;EACA,IAAA;EACA,OAAA;EACA;AAAA,GACC,oBAAA,GAAuB,aAAA"}

package/dist/server/acTrpcContext.mjs

@@ -1,9 +1,10 @@
 //#region src/server/acTrpcContext.ts
-function createAcTrpcContext({ companySpecificBackend, user = null, isAdmin = false }) {
+function createAcTrpcContext({ companySpecificBackend, user = null, isAdmin = false, visitor = null }) {
 	return {
 		companySpecificBackend,
 		user,
-		isAdmin
+		isAdmin,
+		visitor
 	};
 }
 

package/dist/server/acTrpcContext.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"acTrpcContext.mjs","names":[],"sources":["../../src/server/acTrpcContext.ts"],"sourcesContent":["import type { AppCatalogCompanySpecificBackend } from '../types'\nimport type { User } from 'better-auth/types'\n\nexport interface AcTrpcContext {\n  companySpecificBackend: AppCatalogCompanySpecificBackend\n  user: User | null\n  isAdmin: boolean\n}\n\nexport interface AcTrpcContextOptions {\n  companySpecificBackend: AppCatalogCompanySpecificBackend\n  user?: User | null\n  isAdmin?: boolean\n}\n\nexport function createAcTrpcContext({\n  companySpecificBackend,\n  user = null,\n  isAdmin = false,\n}: AcTrpcContextOptions): AcTrpcContext {\n  return { companySpecificBackend, user, isAdmin }\n}\n"],"mappings":";AAeA,SAAgB,oBAAoB,EAClC,wBACA,OAAO,MACP,UAAU,SAC4B;AACtC,QAAO;EAAE;EAAwB;EAAM;EAAS"}
+{"version":3,"file":"acTrpcContext.mjs","names":[],"sources":["../../src/server/acTrpcContext.ts"],"sourcesContent":["import type { AppCatalogCompanySpecificBackend } from '../types'\nimport type { Visitor } from '../modules/comments/visitorIdentity'\nimport type { User } from 'better-auth/types'\n\nexport interface AcTrpcContext {\n  companySpecificBackend: AppCatalogCompanySpecificBackend\n  user: User | null\n  isAdmin: boolean\n  /**\n   * The anonymous browser behind this request, independent of `user` — the catalog\n   * is browsable logged out, and comments are attributed to this instead. Null when\n   * the context was built without a response to issue the cookie on.\n   */\n  visitor: Visitor | null\n}\n\nexport interface AcTrpcContextOptions {\n  companySpecificBackend: AppCatalogCompanySpecificBackend\n  user?: User | null\n  isAdmin?: boolean\n  visitor?: Visitor | null\n}\n\nexport function createAcTrpcContext({\n  companySpecificBackend,\n  user = null,\n  isAdmin = false,\n  visitor = null,\n}: AcTrpcContextOptions): AcTrpcContext {\n  return { companySpecificBackend, user, isAdmin, visitor }\n}\n"],"mappings":";AAuBA,SAAgB,oBAAoB,EAClC,wBACA,OAAO,MACP,UAAU,OACV,UAAU,QAC4B;AACtC,QAAO;EAAE;EAAwB;EAAM;EAAS;EAAS"}

package/dist/server/controller.d.mts

@@ -1,6 +1,7 @@
 import { AppCatalogData, Resource } from "../types/common/appCatalogTypes.mjs";
 import { AcTrpcContext } from "./acTrpcContext.mjs";
 import { BetterAuth } from "../modules/auth/auth.mjs";
+import { CommentView } from "../modules/comments/service.mjs";
 import * as _trpc_server0 from "@trpc/server";
 
 //#region src/server/controller.d.ts
@@ -52,6 +53,45 @@ declare function createTrpcRouter(auth?: BetterAuth, options?: {
       meta: object;
     }>;
   }>>;
+  comments: _trpc_server0.TRPCBuiltRouter<{
+    ctx: AcTrpcContext;
+    meta: object;
+    errorShape: _trpc_server0.TRPCDefaultErrorShape;
+    transformer: false;
+  }, _trpc_server0.TRPCDecorateCreateRouterOptions<{
+    list: _trpc_server0.TRPCQueryProcedure<{
+      input: {
+        resourceSlug: string;
+      };
+      output: CommentView[];
+      meta: object;
+    }>;
+    add: _trpc_server0.TRPCMutationProcedure<{
+      input: {
+        resourceSlug: string;
+        body: string;
+      };
+      output: CommentView;
+      meta: object;
+    }>;
+    edit: _trpc_server0.TRPCMutationProcedure<{
+      input: {
+        id: string;
+        body: string;
+      };
+      output: CommentView;
+      meta: object;
+    }>;
+    remove: _trpc_server0.TRPCMutationProcedure<{
+      input: {
+        id: string;
+      };
+      output: {
+        id: string;
+      };
+      meta: object;
+    }>;
+  }>>;
   auth: _trpc_server0.TRPCBuiltRouter<{
     ctx: AcTrpcContext;
     meta: {};

package/dist/server/controller.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.mts","names":[],"sources":["../../src/server/controller.ts"],"mappings":";;;;;;;;;AAkCA;iBAAgB,gBAAA,CACd,IAAA,GAAO,UAAA,EACP,OAAA;EAAY,eAAA;AAAA,kBAA2B,eAAA;OADtB,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCP,UAAA,GAAa,UAAA,QAAkB,gBAAA"}
+{"version":3,"file":"controller.d.mts","names":[],"sources":["../../src/server/controller.ts"],"mappings":";;;;;;;;;;;iBAmCgB,gBAAA,CACd,IAAA,GAAO,UAAA,EACP,OAAA;EAAY,eAAA;AAAA,kBAA2B,eAAA;OADtB,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAwCP,UAAA,GAAa,UAAA,QAAkB,gBAAA"}

package/dist/server/controller.mjs

@@ -1,6 +1,7 @@
 import { getAppCatalogData, updateAiMemory, updateApp } from "../modules/appCatalog/service.mjs";
 import { createAuthRouter } from "../modules/auth/authRouter.mjs";
 import { publicProcedure, router, t } from "./trpcSetup.mjs";
+import { createCommentsRouter } from "../modules/comments/commentsRouter.mjs";
 import { z } from "zod";
 
 //#region src/server/controller.ts
@@ -41,6 +42,7 @@ function createTrpcRouter(auth, options) {
 				return updateAiMemory(input);
 			})
 		}),
+		comments: createCommentsRouter(),
 		auth: createAuthRouter(t, auth, options)
 	});
 }

package/dist/server/controller.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"controller.mjs","names":["updateAppService","updateAiMemoryService"],"sources":["../../src/server/controller.ts"],"sourcesContent":["import {\n  getAppCatalogData,\n  updateAiMemory as updateAiMemoryService,\n  updateApp as updateAppService,\n} from '../modules/appCatalog/service'\nimport type { AppCatalogData } from '../types'\nimport type { Resource } from '../types/common/appCatalogTypes'\n\nimport type { BetterAuth } from '../modules/auth/auth'\nimport { createAuthRouter } from '../modules/auth/authRouter.js'\nimport { publicProcedure, router, t } from './trpcSetup'\nimport { z } from 'zod'\n\nconst updateAppInputSchema = z.object({\n  id: z.string(),\n  data: z\n    .object({\n      displayName: z.string().optional(),\n      abbreviation: z.string().max(20).nullable().optional(),\n      slug: z.string().optional(),\n      appUrl: z.string().optional(),\n      description: z.string().optional(),\n      sources: z.array(z.string()).optional(),\n      aiPrompt: z.string().nullable().optional(),\n    })\n    .refine((d) => Object.keys(d).length > 0, {\n      message: 'At least one field required',\n    }),\n})\n\n/**\n * Create the main tRPC router with optional auth instance\n * @param auth - Optional Better Auth instance for auth-related queries\n */\nexport function createTrpcRouter(\n  auth?: BetterAuth,\n  options?: { devLoginEnabled?: boolean },\n) {\n  return router({\n    appCatalog: router({\n      getData: publicProcedure.query(\n        async ({ ctx }): Promise<AppCatalogData> => {\n          const baseData = await getAppCatalogData()\n          const versions = await ctx.companySpecificBackend.getVersionInfo?.()\n\n          return {\n            ...baseData,\n            ...(versions && { versions }),\n          }\n        },\n      ),\n      updateApp: publicProcedure\n        .input(updateAppInputSchema)\n        .mutation(async ({ input }): Promise<Resource> => {\n          return updateAppService(input)\n        }),\n      updateAiMemory: publicProcedure\n        .input(\n          z.object({\n            id: z.string(),\n            aiMemory: z.string().nullable(),\n          }),\n        )\n        .mutation(async ({ input }): Promise<Resource> => {\n          return updateAiMemoryService(input)\n        }),\n    }),\n\n    // Auth routes (requires auth instance)\n    auth: createAuthRouter(t, auth, options),\n  })\n}\n\nexport type TRPCRouter = ReturnType<typeof createTrpcRouter>\n"],"mappings":";;;;;;AAaA,MAAM,uBAAuB,EAAE,OAAO;CACpC,IAAI,EAAE,QAAQ;CACd,MAAM,EACH,OAAO;EACN,aAAa,EAAE,QAAQ,CAAC,UAAU;EAClC,cAAc,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU;EACtD,MAAM,EAAE,QAAQ,CAAC,UAAU;EAC3B,QAAQ,EAAE,QAAQ,CAAC,UAAU;EAC7B,aAAa,EAAE,QAAQ,CAAC,UAAU;EAClC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU;EACvC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,UAAU;EAC3C,CAAC,CACD,QAAQ,MAAM,OAAO,KAAK,EAAE,CAAC,SAAS,GAAG,EACxC,SAAS,+BACV,CAAC;CACL,CAAC;;;;;AAMF,SAAgB,iBACd,MACA,SACA;AACA,QAAO,OAAO;EACZ,YAAY,OAAO;GACjB,SAAS,gBAAgB,MACvB,OAAO,EAAE,UAAmC;IAC1C,MAAM,WAAW,MAAM,mBAAmB;IAC1C,MAAM,WAAW,MAAM,IAAI,uBAAuB,kBAAkB;AAEpE,WAAO;KACL,GAAG;KACH,GAAI,YAAY,EAAE,UAAU;KAC7B;KAEJ;GACD,WAAW,gBACR,MAAM,qBAAqB,CAC3B,SAAS,OAAO,EAAE,YAA+B;AAChD,WAAOA,UAAiB,MAAM;KAC9B;GACJ,gBAAgB,gBACb,MACC,EAAE,OAAO;IACP,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,QAAQ,CAAC,UAAU;IAChC,CAAC,CACH,CACA,SAAS,OAAO,EAAE,YAA+B;AAChD,WAAOC,eAAsB,MAAM;KACnC;GACL,CAAC;EAGF,MAAM,iBAAiB,GAAG,MAAM,QAAQ;EACzC,CAAC"}
+{"version":3,"file":"controller.mjs","names":["updateAppService","updateAiMemoryService"],"sources":["../../src/server/controller.ts"],"sourcesContent":["import {\n  getAppCatalogData,\n  updateAiMemory as updateAiMemoryService,\n  updateApp as updateAppService,\n} from '../modules/appCatalog/service'\nimport type { AppCatalogData } from '../types'\nimport type { Resource } from '../types/common/appCatalogTypes'\n\nimport type { BetterAuth } from '../modules/auth/auth'\nimport { createAuthRouter } from '../modules/auth/authRouter.js'\nimport { createCommentsRouter } from '../modules/comments/commentsRouter'\nimport { publicProcedure, router, t } from './trpcSetup'\nimport { z } from 'zod'\n\nconst updateAppInputSchema = z.object({\n  id: z.string(),\n  data: z\n    .object({\n      displayName: z.string().optional(),\n      abbreviation: z.string().max(20).nullable().optional(),\n      slug: z.string().optional(),\n      appUrl: z.string().optional(),\n      description: z.string().optional(),\n      sources: z.array(z.string()).optional(),\n      aiPrompt: z.string().nullable().optional(),\n    })\n    .refine((d) => Object.keys(d).length > 0, {\n      message: 'At least one field required',\n    }),\n})\n\n/**\n * Create the main tRPC router with optional auth instance\n * @param auth - Optional Better Auth instance for auth-related queries\n */\nexport function createTrpcRouter(\n  auth?: BetterAuth,\n  options?: { devLoginEnabled?: boolean },\n) {\n  return router({\n    appCatalog: router({\n      getData: publicProcedure.query(\n        async ({ ctx }): Promise<AppCatalogData> => {\n          const baseData = await getAppCatalogData()\n          const versions = await ctx.companySpecificBackend.getVersionInfo?.()\n\n          return {\n            ...baseData,\n            ...(versions && { versions }),\n          }\n        },\n      ),\n      updateApp: publicProcedure\n        .input(updateAppInputSchema)\n        .mutation(async ({ input }): Promise<Resource> => {\n          return updateAppService(input)\n        }),\n      updateAiMemory: publicProcedure\n        .input(\n          z.object({\n            id: z.string(),\n            aiMemory: z.string().nullable(),\n          }),\n        )\n        .mutation(async ({ input }): Promise<Resource> => {\n          return updateAiMemoryService(input)\n        }),\n    }),\n\n    comments: createCommentsRouter(),\n\n    // Auth routes (requires auth instance)\n    auth: createAuthRouter(t, auth, options),\n  })\n}\n\nexport type TRPCRouter = ReturnType<typeof createTrpcRouter>\n"],"mappings":";;;;;;;AAcA,MAAM,uBAAuB,EAAE,OAAO;CACpC,IAAI,EAAE,QAAQ;CACd,MAAM,EACH,OAAO;EACN,aAAa,EAAE,QAAQ,CAAC,UAAU;EAClC,cAAc,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU;EACtD,MAAM,EAAE,QAAQ,CAAC,UAAU;EAC3B,QAAQ,EAAE,QAAQ,CAAC,UAAU;EAC7B,aAAa,EAAE,QAAQ,CAAC,UAAU;EAClC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU;EACvC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,UAAU;EAC3C,CAAC,CACD,QAAQ,MAAM,OAAO,KAAK,EAAE,CAAC,SAAS,GAAG,EACxC,SAAS,+BACV,CAAC;CACL,CAAC;;;;;AAMF,SAAgB,iBACd,MACA,SACA;AACA,QAAO,OAAO;EACZ,YAAY,OAAO;GACjB,SAAS,gBAAgB,MACvB,OAAO,EAAE,UAAmC;IAC1C,MAAM,WAAW,MAAM,mBAAmB;IAC1C,MAAM,WAAW,MAAM,IAAI,uBAAuB,kBAAkB;AAEpE,WAAO;KACL,GAAG;KACH,GAAI,YAAY,EAAE,UAAU;KAC7B;KAEJ;GACD,WAAW,gBACR,MAAM,qBAAqB,CAC3B,SAAS,OAAO,EAAE,YAA+B;AAChD,WAAOA,UAAiB,MAAM;KAC9B;GACJ,gBAAgB,gBACb,MACC,EAAE,OAAO;IACP,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,QAAQ,CAAC,UAAU;IAChC,CAAC,CACH,CACA,SAAS,OAAO,EAAE,YAA+B;AAChD,WAAOC,eAAsB,MAAM;KACnC;GACL,CAAC;EAEF,UAAU,sBAAsB;EAGhC,MAAM,iBAAiB,GAAG,MAAM,QAAQ;EACzC,CAAC"}

package/dist/utils/cookies.mjs

@@ -0,0 +1,12 @@
+//#region src/utils/cookies.ts
+/** Parse a single cookie value from the Cookie header. */
+function getCookie(req, name) {
+	const cookies = req.headers.cookie ?? "";
+	if (!cookies) return void 0;
+	const match = cookies.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+	return match?.[1] !== void 0 ? decodeURIComponent(match[1]) : void 0;
+}
+
+//#endregion
+export { getCookie };
+//# sourceMappingURL=cookies.mjs.map

package/dist/utils/cookies.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.mjs","names":[],"sources":["../../src/utils/cookies.ts"],"sourcesContent":["/** Parse a single cookie value from the Cookie header. */\nexport function getCookie(\n  req: { headers: { cookie?: string } },\n  name: string,\n): string | undefined {\n  const cookies = req.headers.cookie ?? ''\n  if (!cookies) return undefined\n  const match = cookies.match(new RegExp(`(?:^|;\\\\s*)${name}=([^;]*)`))\n  return match?.[1] !== undefined ? decodeURIComponent(match[1]) : undefined\n}\n"],"mappings":";;AACA,SAAgB,UACd,KACA,MACoB;CACpB,MAAM,UAAU,IAAI,QAAQ,UAAU;AACtC,KAAI,CAAC,QAAS,QAAO;CACrB,MAAM,QAAQ,QAAQ,MAAM,IAAI,OAAO,cAAc,KAAK,UAAU,CAAC;AACrE,QAAO,QAAQ,OAAO,SAAY,mBAAmB,MAAM,GAAG,GAAG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-backend-core",
-  "version": "1.0.1",
+  "version": "2.0.0-alpha-20260914220838",
   "description": "Backend core library for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -45,8 +45,8 @@
     "tsyringe": "^4.10.0",
     "yaml": "^2.8.0",
     "zod": "^4.3.5",
-    "@igstack/app-catalog-shared-core": "1.0.1",
-    "@igstack/app-catalog-table-sync": "1.0.1"
+    "@igstack/app-catalog-shared-core": "2.0.0-alpha-20260914220838",
+    "@igstack/app-catalog-table-sync": "2.0.0-alpha-20260914220838"
   },
   "devDependencies": {
     "@tanstack/vite-config": "^0.4.3",
@@ -73,7 +73,7 @@
   "engines": {
     "node": ">=24"
   },
-  "gitHead": "8714433058e9d88d5033d7625c7a62c143d3cea2",
+  "gitHead": "ce99b1bc970f7d70497ce0eda46dbd41f5a9c248",
   "scripts": {
     "build": "tsdown",
     "build:lenient": "tsdown",

package/prisma/migrations/20260914000000_add_comments/migration.sql

@@ -0,0 +1,22 @@
+-- CreateTable
+CREATE TABLE "DbComment" (
+    "id" TEXT NOT NULL,
+    "resourceId" TEXT NOT NULL,
+    "authorHash" TEXT NOT NULL,
+    "authorAlias" TEXT NOT NULL,
+    "body" TEXT NOT NULL,
+    "editedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "DbComment_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "DbComment_resourceId_createdAt_idx" ON "DbComment"("resourceId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "DbComment_authorHash_idx" ON "DbComment"("authorHash");
+
+-- AddForeignKey
+ALTER TABLE "DbComment" ADD CONSTRAINT "DbComment_resourceId_fkey" FOREIGN KEY ("resourceId") REFERENCES "DbResource"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -152,6 +152,7 @@ model DbResource {
   /// [TierVariant[]]
   tiers                      Json?
   sourceRefs                 SourceReference[]
+  comments                   DbComment[]
   // Self-referential tree: sub-resources point to their parent
   parentSlug                 String?
   parent                     DbResource?       @relation("ResourceTree", fields: [parentSlug], references: [slug])
@@ -181,6 +182,32 @@ model DbResource {
   @@index([parentSlug])
 }
 
+/// A visitor's comment on one resource.
+///
+/// The catalog is browsable without logging in, so a comment carries no user id.
+/// Instead the server issues an opaque visitor token in an httpOnly cookie and
+/// stores its hash: enough to let an author edit or delete their own comment for
+/// a short window, and nothing a reader can forge.
+model DbComment {
+  id         String     @id @default(cuid())
+  // The resource's id, not its slug — a slug is user-facing and gets renamed.
+  resourceId String
+  resource   DbResource @relation(fields: [resourceId], references: [id], onDelete: Cascade)
+  // sha256 of the visitor token. Authorises edit/delete; never sent to a client.
+  authorHash String
+  // The pseudonym shown next to the comment, stored rather than derived at render
+  // time so editing the wordlist later cannot rename everybody's history.
+  authorAlias String
+  body        String
+  // Set on a later edit, so the UI can mark a comment as edited. Null when never edited.
+  editedAt    DateTime?
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([resourceId, createdAt])
+  @@index([authorHash])
+}
+
 model DbAppTagDefinition {
   id          String   @id @default(cuid())
   prefix      String   @unique

package/src/__tests__/comments.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  VISITOR_COOKIE,
+  aliasForHash,
+  resolveVisitor,
+} from '../modules/comments/visitorIdentity'
+
+/**
+ * A comment carries no user id — the catalog is browsable logged out. The visitor
+ * cookie is therefore the only thing standing between an author editing their own
+ * comment and anyone editing anyone's, and the stored alias is the only name a
+ * reader ever sees.
+ */
+describe('visitor identity', () => {
+  function reqWith(cookie?: string) {
+    return { headers: cookie ? { cookie } : {} }
+  }
+
+  it('issues an httpOnly cookie when the browser has none', () => {
+    const res = { cookie: vi.fn() }
+    const visitor = resolveVisitor(reqWith(), res)
+
+    expect(visitor).not.toBeNull()
+    expect(res.cookie).toHaveBeenCalledTimes(1)
+    const call = res.cookie.mock.calls[0] ?? []
+    expect(call[0]).toBe(VISITOR_COOKIE)
+    expect(call[1]).toMatch(/^[0-9a-f-]{36}$/)
+    expect(
+      call[2],
+      'a token page scripts can read is a token anyone can forge',
+    ).toMatchObject({ httpOnly: true, sameSite: 'lax', path: '/' })
+  })
+
+  it('reuses an existing token without re-issuing it', () => {
+    const res = { cookie: vi.fn() }
+    const visitor = resolveVisitor(
+      reqWith(`other=1; ${VISITOR_COOKIE}=fixed-token; another=2`),
+      res,
+    )
+
+    expect(res.cookie).not.toHaveBeenCalled()
+    // sha256('fixed-token')
+    expect(visitor?.hash).toHaveLength(64)
+    expect(
+      resolveVisitor(reqWith(`${VISITOR_COOKIE}=fixed-token`), res)?.hash,
+      'the same browser must resolve to the same author every time',
+    ).toBe(visitor?.hash)
+  })
+
+  it('never stores the raw token as the author key', () => {
+    const visitor = resolveVisitor(reqWith(`${VISITOR_COOKIE}=fixed-token`))
+    expect(visitor?.hash).not.toContain('fixed-token')
+  })
+
+  it('gives a request with no cookie and no response no identity at all', () => {
+    // Internally-created contexts have no response to set a cookie on, and must
+    // not silently share one identity.
+    expect(resolveVisitor(reqWith())).toBeNull()
+  })
+
+  it('derives a stable two-word alias, varying both words', () => {
+    const alias = aliasForHash('a'.repeat(64))
+    expect(alias).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    expect(aliasForHash('a'.repeat(64))).toBe(alias)
+
+    // The two words come from independent slices of the hash: hashes sharing a
+    // first slice must still differ in the second.
+    const shared = '00000000'
+    expect(aliasForHash(`${shared}00000001${'0'.repeat(48)}`)).not.toBe(
+      aliasForHash(`${shared}00000002${'0'.repeat(48)}`),
+    )
+  })
+})

package/src/generated/prisma/browser.ts

@@ -62,6 +62,16 @@ export type DbApprovalMethod = Prisma.DbApprovalMethodModel
  * 
  */
 export type DbResource = Prisma.DbResourceModel
+/**
+ * Model DbComment
+ * A visitor's comment on one resource.
+ * 
+ * The catalog is browsable without logging in, so a comment carries no user id.
+ * Instead the server issues an opaque visitor token in an httpOnly cookie and
+ * stores its hash: enough to let an author edit or delete their own comment for
+ * a short window, and nothing a reader can forge.
+ */
+export type DbComment = Prisma.DbCommentModel
 /**
  * Model DbAppTagDefinition
  * 

package/src/generated/prisma/client.ts

@@ -86,6 +86,16 @@ export type DbApprovalMethod = Prisma.DbApprovalMethodModel
  * 
  */
 export type DbResource = Prisma.DbResourceModel
+/**
+ * Model DbComment
+ * A visitor's comment on one resource.
+ * 
+ * The catalog is browsable without logging in, so a comment carries no user id.
+ * Instead the server issues an opaque visitor token in an httpOnly cookie and
+ * stores its hash: enough to let an author edit or delete their own comment for
+ * a short window, and nothing a reader can forge.
+ */
+export type DbComment = Prisma.DbCommentModel
 /**
  * Model DbAppTagDefinition
  *