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

package/src/modules/comments/service.ts

@@ -0,0 +1,154 @@
+import { getDbClient } from '../../db/client'
+import type { Visitor } from './visitorIdentity'
+
+/** How long an author may edit or delete their own comment. */
+export const EDIT_WINDOW_MS = 60 * 60 * 1000
+
+export const MAX_BODY_LENGTH = 1000
+
+/** One comment as a client sees it. Never carries an author hash. */
+export interface CommentView {
+  id: string
+  authorName: string
+  body: string
+  createdAt: string
+  /** Null when the comment has never been edited. */
+  editedAt: string | null
+  /** Whether this browser wrote it — what makes Edit and Delete appear. */
+  isMine: boolean
+  /**
+   * The absolute instant this browser's edit window closes, or null when it is not
+   * this browser's comment. Absolute rather than a remaining duration so a client
+   * with a skewed clock still hides the controls at the same moment the server
+   * starts refusing the edit.
+   */
+  canEditUntil: string | null
+}
+
+function toView(
+  row: {
+    id: string
+    authorHash: string
+    authorAlias: string
+    body: string
+    editedAt: Date | null
+    createdAt: Date
+  },
+  visitor: Visitor | null,
+): CommentView {
+  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: string): Promise<string | null> {
+  const resource = await getDbClient().dbResource.findUnique({
+    where: { slug },
+    select: { id: true },
+  })
+  return resource?.id ?? null
+}
+
+/** Oldest first: a comment thread reads top to bottom. */
+export async function listComments(
+  resourceSlug: string,
+  visitor: Visitor | null,
+): Promise<CommentView[]> {
+  const resourceId = await resourceIdForSlug(resourceSlug)
+  if (!resourceId) return []
+
+  const rows = await getDbClient().dbComment.findMany({
+    where: { resourceId },
+    orderBy: { createdAt: 'asc' },
+  })
+  return rows.map((row) => toView(row, visitor))
+}
+
+export class CommentError extends Error {
+  constructor(
+    readonly reason: 'not-found' | 'not-author' | 'window-closed' | 'empty',
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+function normaliseBody(body: string): string {
+  const trimmed = body.trim()
+  if (!trimmed) throw new CommentError('empty', 'A comment cannot be empty')
+  return trimmed.slice(0, MAX_BODY_LENGTH)
+}
+
+export async function addComment(
+  resourceSlug: string,
+  body: string,
+  visitor: Visitor,
+): Promise<CommentView> {
+  const resourceId = await resourceIdForSlug(resourceSlug)
+  if (!resourceId) {
+    throw new CommentError('not-found', `Unknown resource: ${resourceSlug}`)
+  }
+
+  const row = await getDbClient().dbComment.create({
+    data: {
+      resourceId,
+      authorHash: visitor.hash,
+      authorAlias: visitor.alias,
+      body: normaliseBody(body),
+    },
+  })
+  return toView(row, 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: string, visitor: 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() + EDIT_WINDOW_MS) {
+    throw new CommentError(
+      'window-closed',
+      'A comment can only be changed in the first hour',
+    )
+  }
+  return row
+}
+
+export async function editComment(
+  id: string,
+  body: string,
+  visitor: Visitor,
+): Promise<CommentView> {
+  await loadOwn(id, visitor)
+
+  const row = await getDbClient().dbComment.update({
+    where: { id },
+    data: { body: normaliseBody(body), editedAt: new Date() },
+  })
+  return toView(row, visitor)
+}
+
+export async function deleteComment(
+  id: string,
+  visitor: Visitor,
+): Promise<{ id: string }> {
+  await loadOwn(id, visitor)
+  await getDbClient().dbComment.delete({ where: { id } })
+  return { id }
+}

package/src/modules/comments/visitorIdentity.ts

@@ -0,0 +1,146 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { getCookie } from '../../utils/cookies'
+
+/** Opaque per-browser token. httpOnly, so page scripts cannot read or forge it. */
+export const VISITOR_COOKIE = 'ac_cid'
+
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000
+
+/**
+ * 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.
+ */
+export interface Visitor {
+  hash: string
+  alias: string
+}
+
+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.
+ */
+export function aliasForHash(hash: string): string {
+  // Two independent slices of the hash, so the two words vary independently.
+  const adjective =
+    ADJECTIVES[parseInt(hash.slice(0, 8), 16) % ADJECTIVES.length]
+  const animal = ANIMALS[parseInt(hash.slice(8, 16), 16) % ANIMALS.length]
+  return `${adjective} ${animal}`
+}
+
+function hashToken(token: string): string {
+  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.
+ */
+export function resolveVisitor(
+  req: { headers: { cookie?: string } },
+  res?: {
+    cookie: (
+      name: string,
+      value: string,
+      options: Record<string, unknown>,
+    ) => unknown
+  },
+): Visitor | null {
+  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) }
+}

package/src/server/acTrpcContext.ts

@@ -1,22 +1,31 @@
 import type { AppCatalogCompanySpecificBackend } from '../types'
+import type { Visitor } from '../modules/comments/visitorIdentity'
 import type { User } from 'better-auth/types'
 
 export 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
 }
 
 export interface AcTrpcContextOptions {
   companySpecificBackend: AppCatalogCompanySpecificBackend
   user?: User | null
   isAdmin?: boolean
+  visitor?: Visitor | null
 }
 
 export function createAcTrpcContext({
   companySpecificBackend,
   user = null,
   isAdmin = false,
+  visitor = null,
 }: AcTrpcContextOptions): AcTrpcContext {
-  return { companySpecificBackend, user, isAdmin }
+  return { companySpecificBackend, user, isAdmin, visitor }
 }

package/src/server/controller.ts

@@ -8,6 +8,7 @@ import type { Resource } from '../types/common/appCatalogTypes'
 
 import type { BetterAuth } from '../modules/auth/auth'
 import { createAuthRouter } from '../modules/auth/authRouter.js'
+import { createCommentsRouter } from '../modules/comments/commentsRouter'
 import { publicProcedure, router, t } from './trpcSetup'
 import { z } from 'zod'
 
@@ -66,6 +67,8 @@ export function createTrpcRouter(
         }),
     }),
 
+    comments: createCommentsRouter(),
+
     // Auth routes (requires auth instance)
     auth: createAuthRouter(t, auth, options),
   })

package/src/utils/cookies.ts

@@ -0,0 +1,10 @@
+/** Parse a single cookie value from the Cookie header. */
+export function getCookie(
+  req: { headers: { cookie?: string } },
+  name: string,
+): string | undefined {
+  const cookies = req.headers.cookie ?? ''
+  if (!cookies) return undefined
+  const match = cookies.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+  return match?.[1] !== undefined ? decodeURIComponent(match[1]) : undefined
+}