From 67f6c8aff64851ad94b91f587545947d22b343ae Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 03:26:54 +0530 Subject: [PATCH 01/29] Cache match explanations per viewer and candidate pair (R18) Every rerank asked the model to explain the whole shortlist again, even when nothing about the pairs had changed. - Migration 0009: pair_explanations (cache key, event, viewer, candidate, reason, expiry), deleted with the event - domain/matching/explanation-key.ts: the key covers event, the viewer -> candidate direction, both profile revisions (last saved), model, prompt version, scoring version, and the context: "profile" or the normalized search query - LlmRerankStage reads cached reasons first. When every shortlisted pair has one, the model is not called and the scored order stands: a cached reason never decides a shortlist's order. Otherwise the model ranks as before and its new reasons are cached for a week. If the model fails, cached reasons are used where they exist; a cache outage never blocks matching - ExplanationCache port with a Postgres adapter; LlmProvider exposes a prompt version; the hourly sweep removes expired explanations --- .../application/ports/explanation-cache.ts | 5 + .../web/src/application/ports/llm-provider.ts | 2 + apps/web/src/composition/container.ts | 3 +- .../src/domain/matching/explanation-key.ts | 32 ++++++ apps/web/src/domain/matching/pipeline.ts | 9 +- .../matching/stages/llm-rerank.stage.ts | 53 ++++++++- .../domain/participant/participant.entity.ts | 2 + .../cache/postgres-explanation-cache.ts | 26 +++++ .../postgres/participant.repo.ts | 1 + .../providers/gemini-llm.provider.ts | 2 + .../db/migrations/0009_pair_explanations.sql | 19 ++++ packages/db/src/repositories/housekeeping.ts | 7 +- tests/integration/explanation-cache.test.ts | 52 +++++++++ tests/unit/explanation-cache.test.ts | 104 ++++++++++++++++++ 14 files changed, 307 insertions(+), 10 deletions(-) create mode 100644 apps/web/src/application/ports/explanation-cache.ts create mode 100644 apps/web/src/domain/matching/explanation-key.ts create mode 100644 apps/web/src/infrastructure/cache/postgres-explanation-cache.ts create mode 100644 packages/db/migrations/0009_pair_explanations.sql create mode 100644 tests/integration/explanation-cache.test.ts create mode 100644 tests/unit/explanation-cache.test.ts diff --git a/apps/web/src/application/ports/explanation-cache.ts b/apps/web/src/application/ports/explanation-cache.ts new file mode 100644 index 0000000..55a1204 --- /dev/null +++ b/apps/web/src/application/ports/explanation-cache.ts @@ -0,0 +1,5 @@ +/** Cached match reasons for single viewer -> candidate pairs (never a ranking). */ +export interface ExplanationCache { + getMany(keys: string[]): Promise>; + setMany(entries: Array<{ key: string; eventId: string; viewerId: string; candidateId: string; reason: string }>, ttlSeconds: number): Promise; +} diff --git a/apps/web/src/application/ports/llm-provider.ts b/apps/web/src/application/ports/llm-provider.ts index fb5bbb1..8e38241 100644 --- a/apps/web/src/application/ports/llm-provider.ts +++ b/apps/web/src/application/ports/llm-provider.ts @@ -4,5 +4,7 @@ import type { ParticipantProfile } from "../../domain/participant/participant.en export interface LlmProvider { /** Identifies the provider and model, recorded with every reranked result. */ readonly id: string; + /** Bump when the prompt changes, so cached explanations are not reused across prompts. */ + readonly promptVersion: string; rerank(viewer: ParticipantProfile, candidates: MatchCandidate[]): Promise; } diff --git a/apps/web/src/composition/container.ts b/apps/web/src/composition/container.ts index d0f73be..636323a 100644 --- a/apps/web/src/composition/container.ts +++ b/apps/web/src/composition/container.ts @@ -6,6 +6,7 @@ import { PostgresRateLimiter } from "../infrastructure/cache/postgres-rate-limit import { PostgresEventRepository } from "../infrastructure/postgres/event.repo"; import { PostgresMatchQueue } from "../infrastructure/postgres/match-queue.repo"; import { PostgresCandidateCache } from "../infrastructure/cache/postgres-candidate-cache"; +import { PostgresExplanationCache } from "../infrastructure/cache/postgres-explanation-cache"; import { UpstashCandidateCache } from "../infrastructure/cache/upstash-candidate-cache"; import { RealtimeNotifier } from "../infrastructure/notifications/realtime.notifier"; import { ProviderRegistry } from "../infrastructure/providers/provider-registry"; @@ -32,7 +33,7 @@ function buildContainer() { matchQueue: new PostgresMatchQueue(), notifications: new RealtimeNotifier(), limiter: new PostgresRateLimiter(), - pipeline: new MatchingPipeline(participants, matches, embeddings, llm, candidateCache), + pipeline: new MatchingPipeline(participants, matches, embeddings, llm, candidateCache, new PostgresExplanationCache()), enqueueMatching: matchingJobs.enqueue, enqueueEmbedding: (eventId: string, participantId: string) => matchingJobs.enqueue(eventId, participantId, "embed"), }; diff --git a/apps/web/src/domain/matching/explanation-key.ts b/apps/web/src/domain/matching/explanation-key.ts new file mode 100644 index 0000000..5b21c1b --- /dev/null +++ b/apps/web/src/domain/matching/explanation-key.ts @@ -0,0 +1,32 @@ +import { createHash } from "node:crypto"; +import type { ParticipantProfile } from "../participant/participant.entity"; +import { SCORING_CONFIG } from "./scoring-config"; + +/** Reasons are reused for a week at most, and earlier when anything in the key changes. */ +export const EXPLANATION_TTL_SECONDS = 7 * 24 * 60 * 60; + +/** + * Identifies one directional explanation: why `candidate` suits `viewer`, at + * these profile revisions, from this model and prompt, under this scoring + * configuration, for this context ("profile" or a normalized search query). + */ +export function explanationKey(input: { + eventId: string; + viewer: ParticipantProfile; + candidate: ParticipantProfile; + model: string; + promptVersion: string; + context: string; +}): string { + return createHash("sha256").update(JSON.stringify([ + input.eventId, + input.viewer.attendeeId, input.viewer.profileRevision ?? null, + input.candidate.attendeeId, input.candidate.profileRevision ?? null, + input.model, input.promptVersion, SCORING_CONFIG.version, input.context, + ])).digest("hex"); +} + +/** The context for search explanations: the normalized query. */ +export function queryContext(query: string): string { + return `query:${query.trim().toLowerCase().replace(/\s+/g, " ")}`; +} diff --git a/apps/web/src/domain/matching/pipeline.ts b/apps/web/src/domain/matching/pipeline.ts index 8f1e2f8..ca04f62 100644 --- a/apps/web/src/domain/matching/pipeline.ts +++ b/apps/web/src/domain/matching/pipeline.ts @@ -1,5 +1,7 @@ import type { EmbeddingProvider } from "../../application/ports/embedding-provider"; import type { CandidateCache } from "../../application/ports/candidate-cache"; +import type { ExplanationCache } from "../../application/ports/explanation-cache"; +import { queryContext } from "./explanation-key"; import type { LlmProvider } from "../../application/ports/llm-provider"; import type { MatchRepository } from "../../application/ports/match-repository"; import type { ParticipantRepository } from "../../application/ports/participant-repository"; @@ -60,10 +62,11 @@ export class MatchingPipeline { matches: MatchRepository, private readonly embeddings: EmbeddingProvider, llm: LlmProvider | null, - cache: CandidateCache + cache: CandidateCache, + explanations: ExplanationCache | null = null ) { this.retrieve = new RetrieveStage(participants, cache); - this.rerank = new LlmRerankStage(llm); + this.rerank = new LlmRerankStage(llm, explanations); this.persist = new PersistStage(matches); } @@ -124,7 +127,7 @@ export class MatchingPipeline { }; }).sort((a, b) => b.score - a.score); const top = this.topK.execute(scored, input.limit ?? 12); - const { candidates: ranked } = await this.rerank.execute(viewer, top); + const { candidates: ranked } = await this.rerank.execute(viewer, top, queryContext(query)); return ranked; } } diff --git a/apps/web/src/domain/matching/stages/llm-rerank.stage.ts b/apps/web/src/domain/matching/stages/llm-rerank.stage.ts index 60e39c5..df0e8c2 100644 --- a/apps/web/src/domain/matching/stages/llm-rerank.stage.ts +++ b/apps/web/src/domain/matching/stages/llm-rerank.stage.ts @@ -1,6 +1,8 @@ import type { LlmProvider } from "../../../application/ports/llm-provider"; import type { ParticipantProfile } from "../../participant/participant.entity"; import type { MatchCandidate } from "../match-strategy"; +import type { ExplanationCache } from "../../../application/ports/explanation-cache"; +import { EXPLANATION_TTL_SECONDS, explanationKey } from "../explanation-key"; export interface RerankResult { candidates: MatchCandidate[]; @@ -8,18 +10,59 @@ export interface RerankResult { rankedBy: string; } +/** + * Orders the shortlist with the model and explains each match. Explanations + * are cached per viewer -> candidate pair: when every pair already has one, + * the model is not called and the scored order stands. A cached reason never + * decides the order of a shortlist. + */ export class LlmRerankStage { - constructor(private readonly provider: LlmProvider | null) {} + constructor( + private readonly provider: LlmProvider | null, + private readonly cache: ExplanationCache | null = null + ) {} - async execute(viewer: ParticipantProfile, candidates: MatchCandidate[]): Promise { + async execute(viewer: ParticipantProfile, candidates: MatchCandidate[], context = "profile"): Promise { const scored = { candidates: candidates.map(addFallbackReason), rankedBy: "score" }; if (!this.provider || candidates.length === 0) return scored; + const provider = this.provider; + const keyFor = (candidate: MatchCandidate) => explanationKey({ + eventId: viewer.eventId, viewer, candidate: candidate.participant, + model: provider.id, promptVersion: provider.promptVersion, context, + }); + const keys = candidates.map(keyFor); + const cached = await this.readCache(keys); + const withCached = candidates.map((candidate, index) => ({ ...candidate, reason: cached.get(keys[index]) ?? candidate.reason })); + if (cached.size === candidates.length) return { candidates: withCached, rankedBy: "score" }; + try { - const reranked = await this.provider.rerank(viewer, candidates); - return { candidates: reranked.map(addFallbackReason), rankedBy: `llm:${this.provider.id}` }; + const reranked = await provider.rerank(viewer, candidates); + await this.writeCache(viewer, reranked.filter((candidate) => candidate.reason).map((candidate) => ({ + key: keyFor(candidate), candidateId: candidate.participant.attendeeId, reason: candidate.reason!, + }))); + return { candidates: reranked.map(addFallbackReason), rankedBy: `llm:${provider.id}` }; } catch (error) { console.warn("[matching] LLM rerank unavailable; using scored order", error); - return scored; + return { candidates: withCached.map(addFallbackReason), rankedBy: "score" }; + } + } + + private async readCache(keys: string[]): Promise> { + if (!this.cache) return new Map(); + try { + return await this.cache.getMany(keys); + } catch (error) { + console.warn("[matching] explanation cache unavailable", error); + return new Map(); + } + } + + private async writeCache(viewer: ParticipantProfile, entries: Array<{ key: string; candidateId: string; reason: string }>) { + if (!this.cache || !entries.length) return; + try { + await this.cache.setMany(entries.map((entry) => ({ ...entry, eventId: viewer.eventId, viewerId: viewer.attendeeId })), EXPLANATION_TTL_SECONDS); + } catch (error) { + console.warn("[matching] could not cache explanations", error); } } } diff --git a/apps/web/src/domain/participant/participant.entity.ts b/apps/web/src/domain/participant/participant.entity.ts index e9b51a7..c82b367 100644 --- a/apps/web/src/domain/participant/participant.entity.ts +++ b/apps/web/src/domain/participant/participant.entity.ts @@ -19,6 +19,8 @@ export interface ParticipantProfile { venueZone: string | null; visible: boolean; profileComplete?: boolean; + /** When the profile was last saved; part of cached explanation keys. */ + profileRevision?: string | null; /** Version of the event's profile form this profile was saved under. */ formVersion?: number; embedding?: number[] | null; diff --git a/apps/web/src/infrastructure/cache/postgres-explanation-cache.ts b/apps/web/src/infrastructure/cache/postgres-explanation-cache.ts new file mode 100644 index 0000000..575a555 --- /dev/null +++ b/apps/web/src/infrastructure/cache/postgres-explanation-cache.ts @@ -0,0 +1,26 @@ +import { query } from "@match-maker/db"; +import type { ExplanationCache } from "../../application/ports/explanation-cache"; + +export class PostgresExplanationCache implements ExplanationCache { + async getMany(keys: string[]): Promise> { + if (!keys.length) return new Map(); + const { rows } = await query<{ cache_key: string; reason: string }>( + `select cache_key, reason from pair_explanations where cache_key = any($1::text[]) and expires_at > now()`, + [keys] + ); + return new Map(rows.map((row) => [row.cache_key, row.reason])); + } + + async setMany(entries: Parameters[0], ttlSeconds: number): Promise { + if (!entries.length) return; + await query( + `insert into pair_explanations (cache_key, event_id, viewer_id, candidate_id, reason, expires_at) + select e.key, e.event_id, e.viewer_id, e.candidate_id, e.reason, now() + make_interval(secs => $2) + from jsonb_to_recordset($1::jsonb) as e(key text, event_id uuid, viewer_id uuid, candidate_id uuid, reason text) + on conflict (cache_key) do update set reason = excluded.reason, expires_at = excluded.expires_at`, + [JSON.stringify(entries.map((entry) => ({ + key: entry.key, event_id: entry.eventId, viewer_id: entry.viewerId, candidate_id: entry.candidateId, reason: entry.reason, + }))), ttlSeconds] + ); + } +} diff --git a/apps/web/src/infrastructure/postgres/participant.repo.ts b/apps/web/src/infrastructure/postgres/participant.repo.ts index 0fbcf1d..8318ef0 100644 --- a/apps/web/src/infrastructure/postgres/participant.repo.ts +++ b/apps/web/src/infrastructure/postgres/participant.repo.ts @@ -176,6 +176,7 @@ function mapProfile(row: ProfileRow): ParticipantProfile { visible: row.visible, profileComplete: Boolean(row.profile_updated_at), formVersion: row.profile_form_version ?? 0, + profileRevision: row.profile_updated_at ? new Date(row.profile_updated_at).toISOString() : null, embedding: parseEmbedding(row.embedding), }; } diff --git a/apps/web/src/infrastructure/providers/gemini-llm.provider.ts b/apps/web/src/infrastructure/providers/gemini-llm.provider.ts index d3a3188..d0c9d5d 100644 --- a/apps/web/src/infrastructure/providers/gemini-llm.provider.ts +++ b/apps/web/src/infrastructure/providers/gemini-llm.provider.ts @@ -5,6 +5,8 @@ import type { ParticipantProfile } from "../../domain/participant/participant.en const DEFAULT_MODEL = "gemini-3.8-flash"; export class GeminiLlmProvider implements LlmProvider { + readonly promptVersion = "p1"; + get id(): string { return `gemini:${process.env.GEMINI_LLM_MODEL || DEFAULT_MODEL}`; } diff --git a/packages/db/migrations/0009_pair_explanations.sql b/packages/db/migrations/0009_pair_explanations.sql new file mode 100644 index 0000000..04b5467 --- /dev/null +++ b/packages/db/migrations/0009_pair_explanations.sql @@ -0,0 +1,19 @@ +-- Cached one-sentence reasons for a viewer -> candidate pair. +-- +-- The key covers the event, both people (in that direction), both profile +-- revisions, the model, prompt and scoring versions, and the query context, +-- so a changed profile or query never reuses stale reasoning. Only reasons +-- are cached here, never a shortlist order. + +create table if not exists pair_explanations ( + cache_key text primary key, + event_id uuid not null references events(id) on delete cascade, + viewer_id uuid not null, + candidate_id uuid not null, + reason text not null, + expires_at timestamptz not null, + created_at timestamptz not null default now() +); + +create index if not exists idx_pair_explanations_expires on pair_explanations (expires_at); +create index if not exists idx_pair_explanations_people on pair_explanations (event_id, candidate_id); diff --git a/packages/db/src/repositories/housekeeping.ts b/packages/db/src/repositories/housekeeping.ts index ec8e6fc..42226c9 100644 --- a/packages/db/src/repositories/housekeeping.ts +++ b/packages/db/src/repositories/housekeeping.ts @@ -13,6 +13,7 @@ export interface SweepResult { loginChallenges: number; rateLimitBuckets: number; retrievalCache: number; + pairExplanations: number; } /** Deletes rows that can no longer be used. Safe to run on any schedule. */ @@ -23,5 +24,9 @@ export async function sweepExpired(): Promise { [RETENTION.rateLimitBucketHours] ); const cache = await query(`delete from retrieval_cache where expires_at < now()`); - return { loginChallenges, rateLimitBuckets: buckets.rowCount ?? 0, retrievalCache: cache.rowCount ?? 0 }; + const explanations = await query(`delete from pair_explanations where expires_at < now()`); + return { + loginChallenges, rateLimitBuckets: buckets.rowCount ?? 0, retrievalCache: cache.rowCount ?? 0, + pairExplanations: explanations.rowCount ?? 0, + }; } diff --git a/tests/integration/explanation-cache.test.ts b/tests/integration/explanation-cache.test.ts new file mode 100644 index 0000000..28142eb --- /dev/null +++ b/tests/integration/explanation-cache.test.ts @@ -0,0 +1,52 @@ +/** + * The Postgres explanation cache: reads, overwrites, expiry, the housekeeping + * sweep and deletion with the event. Uses its own organization and event. + * Skipped when DATABASE_URL is unset. + */ +import { randomUUID } from "node:crypto"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { closePool, housekeeping, query } from "@match-maker/db"; +import { migrate } from "../../packages/db/src/migrate"; +import { PostgresExplanationCache } from "../../apps/web/src/infrastructure/cache/postgres-explanation-cache"; + +const describeDb = process.env.DATABASE_URL ? describe : describe.skip; +const ORG = `explain-${Date.now().toString(36)}`; + +describeDb("Postgres explanation cache", () => { + const cache = new PostgresExplanationCache(); + let eventId: string; + const viewerId = randomUUID(); + const candidateId = randomUUID(); + const entry = (key: string, reason: string) => ({ key: `${ORG}:${key}`, eventId, viewerId, candidateId, reason }); + + beforeAll(async () => { + await migrate(); + const { rows: [org] } = await query<{ id: string }>(`insert into organizations (name, slug) values ($1, $1) returning id`, [ORG]); + eventId = (await query<{ id: string }>(`insert into events (organization_id, name, slug) values ($1, $2, $2) returning id`, [org.id, ORG])).rows[0].id; + }); + + afterAll(async () => { + await query(`delete from organizations where slug = $1`, [ORG]); + await closePool(); + }); + + it("returns stored reasons and overwrites on a second write", async () => { + await cache.setMany([entry("one", "First reason"), entry("two", "Second reason")], 60); + await cache.setMany([entry("one", "Updated reason")], 60); + const found = await cache.getMany([`${ORG}:one`, `${ORG}:two`, `${ORG}:missing`]); + expect(Object.fromEntries(found)).toEqual({ [`${ORG}:one`]: "Updated reason", [`${ORG}:two`]: "Second reason" }); + }); + + it("ignores expired entries and the sweep removes them", async () => { + await cache.setMany([entry("old", "Old reason")], 60); + await query(`update pair_explanations set expires_at = now() - interval '1 minute' where cache_key = $1`, [`${ORG}:old`]); + expect((await cache.getMany([`${ORG}:old`])).size).toBe(0); + await housekeeping.sweepExpired(); + expect((await query(`select 1 from pair_explanations where cache_key = $1`, [`${ORG}:old`])).rows).toHaveLength(0); + }); + + it("is deleted with its event", async () => { + await query(`delete from events where id = $1`, [eventId]); + expect((await cache.getMany([`${ORG}:one`, `${ORG}:two`])).size).toBe(0); + }); +}); diff --git a/tests/unit/explanation-cache.test.ts b/tests/unit/explanation-cache.test.ts new file mode 100644 index 0000000..509e30a --- /dev/null +++ b/tests/unit/explanation-cache.test.ts @@ -0,0 +1,104 @@ +import { describe, expect, it, vi } from "vitest"; +import { LlmRerankStage } from "@/src/domain/matching/stages/llm-rerank.stage"; +import { explanationKey, queryContext } from "@/src/domain/matching/explanation-key"; +import type { ExplanationCache } from "@/src/application/ports/explanation-cache"; +import type { LlmProvider } from "@/src/application/ports/llm-provider"; +import type { MatchCandidate } from "@/src/domain/matching/match-strategy"; +import { Intent } from "@/src/domain/participant/intent"; +import type { ParticipantProfile } from "@/src/domain/participant/participant.entity"; + +const person = (attendeeId: string, profileRevision = "r1"): ParticipantProfile => ({ + eventId: "event", attendeeId, name: attendeeId, designation: null, domain: "AI", aboutMe: null, selfDescription: null, + yearsOfExperience: null, mostImpressiveBuild: null, intent: Intent.NETWORKING, interests: [], venueZone: null, visible: true, + profileComplete: true, embedding: null, profileRevision, +}); +const candidate = (profile: ParticipantProfile, score: number): MatchCandidate => ({ participant: profile, score, scoreBreakdown: {}, mutualInterest: false, reason: null }); + +function memoryCache(): ExplanationCache & { store: Map } { + const store = new Map(); + return { + store, + getMany: vi.fn(async (keys: string[]) => new Map(keys.filter((key) => store.has(key)).map((key) => [key, store.get(key)!]))), + setMany: vi.fn(async (entries) => { for (const entry of entries) store.set(entry.key, entry.reason); }), + }; +} + +function llm(): LlmProvider & { rerank: ReturnType } { + return { + id: "test:model", + promptVersion: "p1", + // Reverses the order and writes a reason naming the candidate. + rerank: vi.fn(async (_viewer: ParticipantProfile, list: MatchCandidate[]) => + [...list].reverse().map((item) => ({ ...item, reason: `LLM says ${item.participant.attendeeId}` }))), + }; +} + +const viewer = person("viewer"); +const shortlist = () => [candidate(person("a"), 90), candidate(person("b"), 80)]; +const order = (result: { candidates: MatchCandidate[] }) => result.candidates.map((item) => item.participant.attendeeId); + +describe("pair explanation cache", () => { + it("stores the model's reasons, then reuses them without calling the model", async () => { + const cache = memoryCache(); + const provider = llm(); + const stage = new LlmRerankStage(provider, cache); + + const first = await stage.execute(viewer, shortlist()); + expect(order(first)).toEqual(["b", "a"]); + expect(first.rankedBy).toBe("llm:test:model"); + expect(cache.store.size).toBe(2); + + const second = await stage.execute(viewer, shortlist()); + expect(provider.rerank).toHaveBeenCalledTimes(1); + expect(second.candidates.map((item) => item.reason)).toEqual(["LLM says a", "LLM says b"]); + // Cached reasons never carry the model's order: the scored order stands. + expect(order(second)).toEqual(["a", "b"]); + expect(second.rankedBy).toBe("score"); + }); + + it("asks the model again when a profile changes", async () => { + const cache = memoryCache(); + const provider = llm(); + const stage = new LlmRerankStage(provider, cache); + await stage.execute(viewer, shortlist()); + await stage.execute(viewer, [candidate(person("a", "r2"), 90), candidate(person("b"), 80)]); + expect(provider.rerank).toHaveBeenCalledTimes(2); + }); + + it("never reuses one viewer's explanations for another", async () => { + const cache = memoryCache(); + const provider = llm(); + const stage = new LlmRerankStage(provider, cache); + await stage.execute(viewer, shortlist()); + await stage.execute(person("someone-else"), shortlist()); + expect(provider.rerank).toHaveBeenCalledTimes(2); + }); + + it("keeps query explanations apart from profile ones and from other queries", () => { + const base = { eventId: "event", viewer, candidate: person("a"), model: "m", promptVersion: "p1" }; + const profile = explanationKey({ ...base, context: "profile" }); + const climate = explanationKey({ ...base, context: queryContext(" Climate tools") }); + expect(climate).toBe(explanationKey({ ...base, context: queryContext("climate tools") })); + expect(new Set([profile, climate, explanationKey({ ...base, context: queryContext("finance") })]).size).toBe(3); + expect(explanationKey({ ...base, context: "profile", promptVersion: "p2" })).not.toBe(profile); + }); + + it("falls back to cached reasons when the model fails", async () => { + const cache = memoryCache(); + const provider = llm(); + const stage = new LlmRerankStage(provider, cache); + await stage.execute(viewer, [candidate(person("a"), 90)]); + provider.rerank.mockRejectedValueOnce(new Error("timeout")); + vi.spyOn(console, "warn").mockImplementation(() => {}); + const result = await stage.execute(viewer, shortlist()); + expect(result.candidates.map((item) => item.reason)).toEqual(["LLM says a", expect.stringMatching(/perspective|fit/)]); + }); + + it("keeps working when the cache itself fails", async () => { + const provider = llm(); + vi.spyOn(console, "warn").mockImplementation(() => {}); + const broken: ExplanationCache = { getMany: vi.fn().mockRejectedValue(new Error("down")), setMany: vi.fn().mockRejectedValue(new Error("down")) }; + const result = await new LlmRerankStage(provider, broken).execute(viewer, shortlist()); + expect(result.rankedBy).toBe("llm:test:model"); + }); +}); From bec5ce7d906a53b8345dbd587ca98cdfaae82bce Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 03:31:20 +0530 Subject: [PATCH 02/29] Add connection abuse controls and profile visibility (R19 part 1) - A declined request is final for the event: re-requesting used to reset it to pending, letting someone keep asking - If the other person already asked, the requester is pointed to their request instead of creating a second one; accepted pairs are refused - At most 20 intro requests an hour and 25 waiting for an answer per person and event; self-requests are refused in the use case too - An attendee removed from the event disappears from other people's connections and their contact is no longer shown; restoring access brings both back. Accepting a request from a removed person fails - Participants can hide their profile from matches and search; hidden, they keep browsing and their accepted connections (consent already given), and nobody new can request them - Tests: request rules, abuse limits, and real-Postgres checks of decline finality and removal --- .../e/[eventSlug]/profile/page.tsx | 2 +- apps/web/app/actions/participant.actions.ts | 1 + .../components/participant/ProfileForm.tsx | 9 +++ .../src/application/ports/intro-repository.ts | 4 ++ .../application/use-cases/request-intro.ts | 13 +++- .../application/use-cases/respond-to-intro.ts | 3 + .../src/domain/connection/connection.rules.ts | 23 +++++++ .../domain/participant/participant.entity.ts | 2 +- .../src/infrastructure/postgres/intro.repo.ts | 31 ++++++++-- .../postgres/participant.repo.ts | 5 +- tests/integration/connection-privacy.test.ts | 62 +++++++++++++++++++ tests/unit/candidate-eligibility.test.ts | 4 +- tests/unit/intro-rules.test.ts | 59 ++++++++++++++++++ 13 files changed, 206 insertions(+), 12 deletions(-) create mode 100644 tests/integration/connection-privacy.test.ts create mode 100644 tests/unit/intro-rules.test.ts diff --git a/apps/web/app/(participant)/e/[eventSlug]/profile/page.tsx b/apps/web/app/(participant)/e/[eventSlug]/profile/page.tsx index ff7ffa2..277c435 100644 --- a/apps/web/app/(participant)/e/[eventSlug]/profile/page.tsx +++ b/apps/web/app/(participant)/e/[eventSlug]/profile/page.tsx @@ -28,7 +28,7 @@ export default async function ProfilePage({ params }: { params: Promise<{ eventS ; } diff --git a/apps/web/app/actions/participant.actions.ts b/apps/web/app/actions/participant.actions.ts index 5db11f3..e0f0aa0 100644 --- a/apps/web/app/actions/participant.actions.ts +++ b/apps/web/app/actions/participant.actions.ts @@ -45,6 +45,7 @@ async function saveProfile(eventSlug: string, formData: FormData) { selfDescription: nullable(formData.get("selfDescription")), yearsOfExperience: parseYears(formData.get("yearsOfExperience")), mostImpressiveBuild: nullable(formData.get("mostImpressiveBuild")), + visible: formData.get("visible") === "on", }, { participants: container.participants, enqueueMatching: container.enqueueEmbedding }, readProfileForm(event.form_config)); } diff --git a/apps/web/components/participant/ProfileForm.tsx b/apps/web/components/participant/ProfileForm.tsx index 35b1672..e05f743 100644 --- a/apps/web/components/participant/ProfileForm.tsx +++ b/apps/web/components/participant/ProfileForm.tsx @@ -17,6 +17,7 @@ export interface ProfileFormValues { interests: string[]; intent: string; venueZone: string | null; + visible: boolean; } const label = (intent: string) => intent.replaceAll("_", " ").toLowerCase(); @@ -52,6 +53,14 @@ export default function ProfileForm({ action, profile, intents, zones, form }: { options={intents.map((intent) => ({ value: intent, label: label(intent) }))} /> {zones.length > 0 && ({ value: zone, label: zone }))} />} +
+ + Hidden, you can still browse and keep your accepted connections; nobody new can find you or request an introduction. +
Save profile and find matches
; } diff --git a/apps/web/src/application/ports/intro-repository.ts b/apps/web/src/application/ports/intro-repository.ts index 2b1167c..bc9e54b 100644 --- a/apps/web/src/application/ports/intro-repository.ts +++ b/apps/web/src/application/ports/intro-repository.ts @@ -4,6 +4,10 @@ export interface IntroRepository { create(input: { eventId: string; requesterId: string; recipientId: string; message?: string | null }): Promise; findById(eventId: string, introId: string): Promise; respond(eventId: string, introId: string, actorId: string, status: Extract): Promise; + /** Requests in either direction between two people. */ + findBetween(eventId: string, a: string, b: string): Promise; + countPendingOutgoing(eventId: string, requesterId: string): Promise; + /** The participant's requests, excluding those with someone removed from the event. */ listForParticipant(eventId: string, participantId: string): Promise; getRevealedContacts(eventId: string, participantId: string): Promise>; } diff --git a/apps/web/src/application/use-cases/request-intro.ts b/apps/web/src/application/use-cases/request-intro.ts index 1dc00b1..ed31eee 100644 --- a/apps/web/src/application/use-cases/request-intro.ts +++ b/apps/web/src/application/use-cases/request-intro.ts @@ -2,11 +2,14 @@ import type { IntroRepository } from "../ports/intro-repository"; import type { ParticipantRepository } from "../ports/participant-repository"; import type { NotificationPort } from "../ports/notification"; import { boundedText, LIMITS } from "../../domain/shared/validation"; +import { INTRO_LIMITS, introRequestRefusal } from "../../domain/connection/connection.rules"; +import type { RateLimiter } from "../ports/rate-limiter"; export async function requestIntro( input: { eventId: string; requesterId: string; recipientId: string; message?: string | null; eventName?: string }, - dependencies: { participants: ParticipantRepository; intros: IntroRepository; notifications?: NotificationPort } + dependencies: { participants: ParticipantRepository; intros: IntroRepository; notifications?: NotificationPort; limiter?: RateLimiter } ) { + if (input.requesterId === input.recipientId) throw new Error("You cannot request an intro to yourself"); if (!(await dependencies.participants.hasEventAccess(input.eventId, input.requesterId))) throw new Error("You are not registered for this event"); if (!(await dependencies.participants.hasEventAccess(input.eventId, input.recipientId))) throw new Error("This participant is not in the event"); const [requester, recipient] = await Promise.all([ @@ -15,6 +18,14 @@ export async function requestIntro( ]); if (!requester || !recipient || !recipient.visible || !recipient.profileComplete) throw new Error("This participant is unavailable"); const message = boundedText(input.message, "message", "Message", LIMITS.introMessage); + const refusal = introRequestRefusal(input.requesterId, await dependencies.intros.findBetween(input.eventId, input.requesterId, input.recipientId)); + if (refusal) throw new Error(refusal); + if (await dependencies.intros.countPendingOutgoing(input.eventId, input.requesterId) >= INTRO_LIMITS.pendingOutgoing) { + throw new Error(`You have ${INTRO_LIMITS.pendingOutgoing} requests waiting for an answer. Wait for replies before asking more people.`); + } + if (dependencies.limiter && !(await dependencies.limiter.consume(`intro:${input.eventId}:${input.requesterId}`, INTRO_LIMITS.perHour, 3600))) { + throw new Error("You have sent many introduction requests this hour. Please try again later."); + } const intro = await dependencies.intros.create({ ...input, message }); if (recipient.email && dependencies.notifications) { await dependencies.notifications.introRequested({ diff --git a/apps/web/src/application/use-cases/respond-to-intro.ts b/apps/web/src/application/use-cases/respond-to-intro.ts index c7f880c..3ee9ba2 100644 --- a/apps/web/src/application/use-cases/respond-to-intro.ts +++ b/apps/web/src/application/use-cases/respond-to-intro.ts @@ -8,6 +8,9 @@ export async function respondToIntro( ) { const existing = await dependencies.intros.findById(input.eventId, input.introId); if (!existing) throw new Error("Intro request not found"); + if (input.accept && !(await dependencies.participants.hasEventAccess(input.eventId, existing.requesterId))) { + throw new Error("This person is no longer part of the event"); + } const updated = await dependencies.intros.respond(input.eventId, input.introId, input.actorId, input.accept ? "accepted" : "declined"); if (updated.status === "accepted" && dependencies.notifications) { const requester = await dependencies.participants.findProfile(input.eventId, updated.requesterId); diff --git a/apps/web/src/domain/connection/connection.rules.ts b/apps/web/src/domain/connection/connection.rules.ts index e18d7f7..684899d 100644 --- a/apps/web/src/domain/connection/connection.rules.ts +++ b/apps/web/src/domain/connection/connection.rules.ts @@ -4,3 +4,26 @@ import type { IntroRequest } from "./intro-request.entity"; export function mayRevealContact(request: IntroRequest): boolean { return request.status === "accepted"; } + +/** Limits on introduction requests, per requester and event. */ +export const INTRO_LIMITS = { + perHour: 20, + pendingOutgoing: 25, +} as const; + +/** + * Whether a new request from `requesterId` may be created, given the requests + * already existing between the two people (either direction). A decline is + * final for the event, and a pending request the other way should be + * answered rather than duplicated. + */ +export function introRequestRefusal(requesterId: string, existing: IntroRequest[]): string | null { + for (const intro of existing) { + const mine = intro.requesterId === requesterId; + if (intro.status === "accepted") return "You are already connected"; + if (mine && intro.status === "pending") return "You already asked to meet them"; + if (mine && intro.status === "declined") return "They declined an earlier request, so you cannot ask again at this event"; + if (!mine && intro.status === "pending") return "They already asked to meet you. Accept their request on your Connections page"; + } + return null; +} diff --git a/apps/web/src/domain/participant/participant.entity.ts b/apps/web/src/domain/participant/participant.entity.ts index c82b367..53fe075 100644 --- a/apps/web/src/domain/participant/participant.entity.ts +++ b/apps/web/src/domain/participant/participant.entity.ts @@ -40,7 +40,7 @@ export type ParticipantProfileInput = Pick< | "interests" | "venueZone" | "formVersion" ->; +> & { visible?: boolean }; export function profileText(profile: ParticipantProfile): string { return [ diff --git a/apps/web/src/infrastructure/postgres/intro.repo.ts b/apps/web/src/infrastructure/postgres/intro.repo.ts index 4f58db0..88595fe 100644 --- a/apps/web/src/infrastructure/postgres/intro.repo.ts +++ b/apps/web/src/infrastructure/postgres/intro.repo.ts @@ -23,9 +23,7 @@ export class PostgresIntroRepository implements IntroRepository { const { rows } = await query( `insert into intro_requests (event_id, requester_id, recipient_id, message) values ($1, $2, $3, $4) - on conflict (event_id, requester_id, recipient_id) do update - set status = 'pending', message = excluded.message, created_at = now(), responded_at = null - where intro_requests.status = 'declined' + on conflict (event_id, requester_id, recipient_id) do nothing returning ${INTRO_COLUMNS}`, [input.eventId, input.requesterId, input.recipientId, message] ); @@ -52,11 +50,30 @@ export class PostgresIntroRepository implements IntroRepository { return mapIntro(rows[0]); } - async listForParticipant(eventId: string, participantId: string): Promise { + async findBetween(eventId: string, a: string, b: string): Promise { const { rows } = await query( `select ${INTRO_COLUMNS} from intro_requests - where event_id = $1 and (requester_id = $2 or recipient_id = $2) - order by created_at desc`, + where event_id = $1 and ((requester_id = $2 and recipient_id = $3) or (requester_id = $3 and recipient_id = $2))`, + [eventId, a, b] + ); + return rows.map(mapIntro); + } + + async countPendingOutgoing(eventId: string, requesterId: string): Promise { + const { rows } = await query<{ count: number }>( + `select count(*)::int as count from intro_requests where event_id = $1 and requester_id = $2 and status = 'pending'`, + [eventId, requesterId] + ); + return rows[0]?.count ?? 0; + } + + async listForParticipant(eventId: string, participantId: string): Promise { + const { rows } = await query( + `select ${INTRO_COLUMNS_R} from intro_requests r + join event_participants other on other.event_id = r.event_id + and other.attendee_id = case when r.requester_id = $2 then r.recipient_id else r.requester_id end + where r.event_id = $1 and (r.requester_id = $2 or r.recipient_id = $2) and other.revoked_at is null + order by r.created_at desc`, [eventId, participantId] ); return rows.map(mapIntro); @@ -71,6 +88,8 @@ export class PostgresIntroRepository implements IntroRepository { left join event_participants cp on cp.event_id = r.event_id and cp.attendee_id = c.id where r.event_id = $1 and r.status = 'accepted' and (r.requester_id = $2 or r.recipient_id = $2) + -- Someone removed from the event no longer has their contact shown. + and cp.revoked_at is null order by r.responded_at desc`, [eventId, participantId] ); diff --git a/apps/web/src/infrastructure/postgres/participant.repo.ts b/apps/web/src/infrastructure/postgres/participant.repo.ts index 8318ef0..c6bddb0 100644 --- a/apps/web/src/infrastructure/postgres/participant.repo.ts +++ b/apps/web/src/infrastructure/postgres/participant.repo.ts @@ -63,11 +63,12 @@ export class PostgresParticipantRepository implements ParticipantRepository { intent = $3, interests = $4, venue_zone = $5, about_me = $6, designation = $7, domain = $8, self_description = $9, years_of_experience = $10, - most_impressive_build = $11, profile_form_version = $12, embedding = null, profile_updated_at = now(), updated_at = now() + most_impressive_build = $11, profile_form_version = $12, visible = coalesce($13, visible), + embedding = null, profile_updated_at = now(), updated_at = now() where event_id = $1 and attendee_id = $2`, [input.eventId, input.attendeeId, input.intent, input.interests, input.venueZone, input.aboutMe, input.designation, input.domain, input.selfDescription, - input.yearsOfExperience, input.mostImpressiveBuild, input.formVersion ?? 0] + input.yearsOfExperience, input.mostImpressiveBuild, input.formVersion ?? 0, input.visible ?? null] ); if (!rowCount) throw new Error("This attendee is not on the event roster"); const saved = await this.findProfile(input.eventId, input.attendeeId); diff --git a/tests/integration/connection-privacy.test.ts b/tests/integration/connection-privacy.test.ts new file mode 100644 index 0000000..ddd16b9 --- /dev/null +++ b/tests/integration/connection-privacy.test.ts @@ -0,0 +1,62 @@ +/** + * Connection privacy against a real Postgres: a declined request stays + * declined, and an attendee removed from the event disappears from other + * people's connections and contacts. Uses its own organization, event and + * attendees. Skipped when DATABASE_URL is unset. + */ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { attendees, closePool, events, query } from "@match-maker/db"; +import { migrate } from "../../packages/db/src/migrate"; +import { PostgresIntroRepository } from "../../apps/web/src/infrastructure/postgres/intro.repo"; + +const describeDb = process.env.DATABASE_URL ? describe : describe.skip; +const RUN = Date.now().toString(36); +const ORG = `privacy-${RUN}`; +const email = (key: string) => `privacy-${key}-${RUN}@example.com`; + +describeDb("connection privacy", () => { + const intros = new PostgresIntroRepository(); + const ids: Record = {}; + let eventId: string; + + beforeAll(async () => { + await migrate(); + await attendees.upsertMany(["ann", "bo", "cy"].map((key) => ({ name: key, email: email(key), phone: null }))); + for (const key of ["ann", "bo", "cy"]) ids[key] = (await attendees.findByEmail(email(key)))!.id; + const { rows: [org] } = await query<{ id: string }>(`insert into organizations (name, slug) values ($1, $1) returning id`, [ORG]); + eventId = (await query<{ id: string }>(`insert into events (organization_id, name, slug, status) values ($1, $2, $2, 'open') returning id`, [org.id, ORG])).rows[0].id; + await events.attachRoster(eventId, Object.values(ids)); + }); + + afterAll(async () => { + await query(`delete from organizations where slug = $1`, [ORG]); + await query(`delete from registered_attendees where email like $1`, [`privacy-%-${RUN}@example.com`]); + await closePool(); + }); + + it("keeps a declined request declined", async () => { + const declined = await intros.create({ eventId, requesterId: ids.ann, recipientId: ids.bo }); + await intros.respond(eventId, declined.id, ids.bo, "declined"); + await expect(intros.create({ eventId, requesterId: ids.ann, recipientId: ids.bo })).rejects.toThrow(/already exists/); + expect((await intros.findById(eventId, declined.id))?.status).toBe("declined"); + expect(await intros.findBetween(eventId, ids.bo, ids.ann)).toHaveLength(1); + }); + + it("counts pending outgoing requests", async () => { + await intros.create({ eventId, requesterId: ids.cy, recipientId: ids.bo }); + expect(await intros.countPendingOutgoing(eventId, ids.cy)).toBe(1); + }); + + it("hides a removed attendee from connections and contacts", async () => { + const accepted = await intros.create({ eventId, requesterId: ids.ann, recipientId: ids.cy }); + await intros.respond(eventId, accepted.id, ids.cy, "accepted"); + expect((await intros.getRevealedContacts(eventId, ids.ann)).map((row) => row.contact.id)).toEqual([ids.cy]); + + await events.setRevoked(eventId, ids.cy, true); + expect((await intros.listForParticipant(eventId, ids.ann)).some((intro) => intro.id === accepted.id)).toBe(false); + expect(await intros.getRevealedContacts(eventId, ids.ann)).toEqual([]); + + await events.setRevoked(eventId, ids.cy, false); + expect((await intros.getRevealedContacts(eventId, ids.ann)).map((row) => row.contact.id)).toEqual([ids.cy]); + }); +}); diff --git a/tests/unit/candidate-eligibility.test.ts b/tests/unit/candidate-eligibility.test.ts index 5ac19bc..eab1454 100644 --- a/tests/unit/candidate-eligibility.test.ts +++ b/tests/unit/candidate-eligibility.test.ts @@ -64,7 +64,9 @@ describe("intro request recipient", () => { hasEventAccess: vi.fn(async () => true), findProfile: vi.fn(async (_eventId: string, id: string) => (id === "requester" ? profile("requester") : recipient)), } as unknown as ParticipantRepository; - const intros = { create: vi.fn(async () => ({ id: "intro" })) } as unknown as IntroRepository; + const intros = { + create: vi.fn(async () => ({ id: "intro" })), findBetween: vi.fn(async () => []), countPendingOutgoing: vi.fn(async () => 0), + } as unknown as IntroRepository; return { participants, intros }; } const send = (dependencies: ReturnType, recipientId: string) => diff --git a/tests/unit/intro-rules.test.ts b/tests/unit/intro-rules.test.ts new file mode 100644 index 0000000..e6ffc3e --- /dev/null +++ b/tests/unit/intro-rules.test.ts @@ -0,0 +1,59 @@ +import { describe, expect, it, vi } from "vitest"; +import { INTRO_LIMITS, introRequestRefusal } from "@/src/domain/connection/connection.rules"; +import { requestIntro } from "@/src/application/use-cases/request-intro"; +import type { IntroRequest } from "@/src/domain/connection/intro-request.entity"; + +const intro = (requesterId: string, recipientId: string, status: IntroRequest["status"]): IntroRequest => ({ + id: `${requesterId}-${recipientId}`, eventId: "event", requesterId, recipientId, status, message: null, createdAt: new Date(), respondedAt: null, +}); + +describe("intro request rules", () => { + it.each([ + [[], null], + [[intro("a", "b", "pending")], /already asked to meet them/], + [[intro("a", "b", "declined")], /declined an earlier request/], + [[intro("b", "a", "pending")], /already asked to meet you/], + [[intro("b", "a", "accepted")], /already connected/], + [[intro("b", "a", "declined")], null], + ] as const)("refuses or allows a request from a given %o", (existing, expected) => { + const refusal = introRequestRefusal("a", [...existing]); + if (expected === null) expect(refusal).toBeNull(); + else expect(refusal).toMatch(expected); + }); +}); + +function deps(overrides: { existing?: IntroRequest[]; pending?: number; allowed?: boolean } = {}) { + const profile = (id: string) => ({ attendeeId: id, name: id, visible: true, profileComplete: true, email: `${id}@example.com` }); + return { + participants: { hasEventAccess: vi.fn(async () => true), findProfile: vi.fn(async (_e: string, id: string) => profile(id)) }, + intros: { + findBetween: vi.fn(async () => overrides.existing ?? []), + countPendingOutgoing: vi.fn(async () => overrides.pending ?? 0), + create: vi.fn(async () => intro("a", "b", "pending")), + }, + limiter: { consume: vi.fn(async () => overrides.allowed ?? true) }, + }; +} +// eslint-disable-next-line @typescript-eslint/no-explicit-any +const ask = (dependencies: ReturnType) => requestIntro({ eventId: "event", requesterId: "a", recipientId: "b" }, dependencies as any); + +describe("requestIntro abuse controls", () => { + it("creates a request when nothing blocks it", async () => { + const d = deps(); + await ask(d); + expect(d.intros.create).toHaveBeenCalled(); + expect(d.limiter.consume).toHaveBeenCalledWith("intro:event:a", INTRO_LIMITS.perHour, 3600); + }); + + it("refuses a request to yourself", async () => { + const d = deps(); + // eslint-disable-next-line @typescript-eslint/no-explicit-any + await expect(requestIntro({ eventId: "event", requesterId: "a", recipientId: "a" }, d as any)).rejects.toThrow(/yourself/); + }); + + it("refuses after a decline, with too many pending, or over the hourly limit", async () => { + await expect(ask(deps({ existing: [intro("a", "b", "declined")] }))).rejects.toThrow(/declined/); + await expect(ask(deps({ pending: INTRO_LIMITS.pendingOutgoing }))).rejects.toThrow(/waiting for an answer/); + await expect(ask(deps({ allowed: false }))).rejects.toThrow(/this hour/); + }); +}); From b81b1e5d22112a3f8fd3a251553d2dcae0ce2788 Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 03:35:15 +0530 Subject: [PATCH 03/29] Record sensitive actions and enforce data retention (R19 part 2) - Migration 0010: audit_events (event, actor, action, subject, details with counts and field names only). Recorded: roster imports, invitations, access removed/restored, settings and profile-form changes, introductions accepted (contacts shared), and account disable/enable/revoke/erase. Recording failures are logged and never block the action. Organizers see "Recent activity" on the analytics page. Records are kept for a year by the hourly sweep and survive their event's deletion - Removing someone from an event deletes cached explanations written about or for them; hiding a profile deletes explanations of it - npm run account:erase -- --yes for deletion requests: deletes the Keycloak user first (so a failure leaves data to retry), then the attendee and everything cascading from it, cached explanations and login challenges; refuses without --yes - Tests: real Postgres for records, sweep, retention on removal and hiding, and erasure against the local Keycloak realm --- ReadMe.md | 1 + .../events/[eventSlug]/analytics/page.tsx | 25 ++++- apps/web/app/actions/organizer.actions.ts | 8 +- apps/web/src/application/ports/audit-log.ts | 14 +++ .../src/application/use-cases/manage-event.ts | 15 ++- .../use-cases/manage-invitations.ts | 12 ++- .../application/use-cases/respond-to-intro.ts | 6 +- apps/web/src/composition/container.ts | 2 + .../src/infrastructure/postgres/audit.repo.ts | 19 ++++ .../postgres/participant.repo.ts | 4 + package.json | 3 +- packages/auth/src/index.ts | 1 + packages/auth/src/keycloak.ts | 7 ++ packages/db/migrations/0010_audit_events.sql | 17 ++++ packages/db/src/index.ts | 1 + packages/db/src/repositories/attendees.ts | 17 ++++ packages/db/src/repositories/audit.ts | 43 ++++++++ packages/db/src/repositories/events.ts | 4 + packages/db/src/repositories/housekeeping.ts | 5 +- tests/integration/audit-retention.test.ts | 97 +++++++++++++++++++ tests/unit/invitations.test.ts | 11 +++ tools/manage-account.ts | 37 +++++-- 22 files changed, 329 insertions(+), 20 deletions(-) create mode 100644 apps/web/src/application/ports/audit-log.ts create mode 100644 apps/web/src/infrastructure/postgres/audit.repo.ts create mode 100644 packages/db/migrations/0010_audit_events.sql create mode 100644 packages/db/src/repositories/audit.ts create mode 100644 tests/integration/audit-retention.test.ts diff --git a/ReadMe.md b/ReadMe.md index a5d93b0..818de3f 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -110,6 +110,7 @@ The first command imports the global attendee directory so the organizer account | `npm run keycloak:sync` | Bring an existing realm up to date: client secret, Google credentials, the account-linking flow (Google joins an account an e-mail code created), and the site login theme. Run after the first Keycloak start and after upgrades | | `npm run account:disable -- ` | Block sign-in and end every session (database and Keycloak); `account:enable` undoes it | | `npm run account:revoke-sessions -- ` | Sign the person out everywhere without disabling the account | +| `npm run account:erase -- --yes` | Deletion request: delete the person, their event profiles, matches, introductions, cached explanations and Keycloak user (recorded in the audit log) | | `npm run docker:up` | Build images and start the local Compose stack | `DATABASE_URL` should point at `localhost` for commands run on the host. Compose sets the service hostname `postgres` inside containers. diff --git a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx index a7a028c..f246a3f 100644 --- a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx +++ b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx @@ -5,7 +5,7 @@ import { requireOrganizerEvent } from "@/src/lib/auth"; export default async function AnalyticsPage({ params }: { params: Promise<{ orgSlug: string; eventSlug: string }> }) { const { orgSlug, eventSlug } = await params; const { event, container } = await requireOrganizerEvent(orgSlug, eventSlug); - const analytics = await container.events.analytics(event.id); + const [analytics, activity] = await Promise.all([container.events.analytics(event.id), container.audit.recent(event.id)]); const completion = analytics.roster ? Math.round(analytics.profiles / analytics.roster * 100) : 0; return
@@ -20,9 +20,32 @@ export default async function AnalyticsPage({ params }: { params: Promise<{ orgS +

Recent activity

+ {!activity.length ?

No recorded activity yet.

:
    + {activity.map((item) =>
  • + {ACTIVITY_LABELS[item.action] ?? item.action} + {item.subjectName && <> · {item.subjectName}} +
    {item.actorName ?? "System"} · {item.createdAt.toLocaleString("en-IN", { dateStyle: "medium", timeStyle: "short" })}{summary(item.details)} +
  • )} +
}
; } +const ACTIVITY_LABELS: Record = { + "roster.imported": "Roster imported", + "invitations.sent": "Invitations sent", + "access.removed": "Access removed", + "access.restored": "Access restored", + "event.updated": "Settings changed", + "profile_form.updated": "Profile form changed", + "contacts.revealed": "Introduction accepted, contacts shared", +}; + +function summary(details: Record): string { + const parts = ["attached", "sent", "failed", "version"].filter((key) => typeof details[key] === "number").map((key) => `${key} ${details[key]}`); + return parts.length ? ` · ${parts.join(", ")}` : ""; +} + function Card({ label, value, note }: { label: string; value: number | string; note?: string }) { return
{label}{value}{note && {note}}
; } diff --git a/apps/web/app/actions/organizer.actions.ts b/apps/web/app/actions/organizer.actions.ts index a1d756a..fa5c761 100644 --- a/apps/web/app/actions/organizer.actions.ts +++ b/apps/web/app/actions/organizer.actions.ts @@ -43,7 +43,7 @@ async function importRoster(organizationSlug: string, eventSlug: string, formDat const event = await container.events.findBySlug(organizationSlug, eventSlug); if (!event) throw new Error("Event not found"); const { records, skipped } = parseRosterWorkbook(await file.arrayBuffer()); - const result = await importEventRoster({ eventId: event.id, organizerId: session.attendeeId, records }, container.events); + const result = await importEventRoster({ eventId: event.id, organizerId: session.attendeeId, records }, container.events, container.audit); const report = new URLSearchParams({ imported: String(result.attached), skipped: String(skipped), already: String(result.alreadyOnRoster), kept: String(result.keptExisting), phones: String(result.phoneConflicts), @@ -73,7 +73,7 @@ async function saveEvent(organizationSlug: string, eventSlug: string, formData: status: status as "draft" | "open" | "closed", intents, zones, - }, container.events); + }, container.events, container.audit); redirect(`/orgs/${organizationSlug}/events/${eventSlug}?saved=1`); } @@ -88,7 +88,7 @@ async function queueMatches(organizationSlug: string, eventSlug: string) { const event = await container.events.findBySlug(organizationSlug, eventSlug); if (!event) throw new Error("Event not found"); assertEventAllows(event.status, "computeMatches"); - if (event.status === "draft") await updateEvent({ eventId: event.id, organizerId: session.attendeeId, status: "open" }, container.events); + if (event.status === "draft") await updateEvent({ eventId: event.id, organizerId: session.attendeeId, status: "open" }, container.events, container.audit); const queued = await queueEventMatches({ eventId: event.id, organizerId: session.attendeeId }, container.events, container.enqueueEmbedding); redirect(`/orgs/${organizationSlug}/events/${eventSlug}/matching?queued=${queued}`); } @@ -138,7 +138,7 @@ export async function updateProfileFormAction(organizationSlug: string, eventSlu shown: formData.get(`${key}.shown`) === "on", required: formData.get(`${key}.required`) === "on", }])) as Record; - await configureProfileForm({ eventId: event.id, organizerId: session.attendeeId, fields, currentConfig: event.form_config }, container.events); + await configureProfileForm({ eventId: event.id, organizerId: session.attendeeId, fields, currentConfig: event.form_config }, container.events, container.audit); redirect(`/orgs/${organizationSlug}/events/${eventSlug}?form=saved`); }); } diff --git a/apps/web/src/application/ports/audit-log.ts b/apps/web/src/application/ports/audit-log.ts new file mode 100644 index 0000000..228950f --- /dev/null +++ b/apps/web/src/application/ports/audit-log.ts @@ -0,0 +1,14 @@ +/** Records sensitive actions. Recording must never block or fail the action itself. */ +export interface AuditLog { + record(entry: { + eventId?: string | null; + actorId?: string | null; + action: string; + subjectId?: string | null; + details?: Record; + }): Promise; + /** The event's most recent records, newest first, with people's names. */ + recent(eventId: string, limit?: number): Promise; createdAt: Date; + }>>; +} diff --git a/apps/web/src/application/use-cases/manage-event.ts b/apps/web/src/application/use-cases/manage-event.ts index fcbd9f2..d800e8f 100644 --- a/apps/web/src/application/use-cases/manage-event.ts +++ b/apps/web/src/application/use-cases/manage-event.ts @@ -1,4 +1,5 @@ import type { EventRepository, RosterAttendeeInput } from "../ports/event-repository"; +import type { AuditLog } from "../ports/audit-log"; import { slugify } from "../../domain/shared/value-objects"; import { Intent } from "../../domain/participant/intent"; import { boundedItems, boundedText, LIMITS, ValidationError } from "../../domain/shared/validation"; @@ -29,7 +30,7 @@ export async function updateEvent(input: { status?: "draft" | "open" | "closed"; intents?: string[]; zones?: string[]; -}, events: EventRepository) { +}, events: EventRepository, audit?: AuditLog) { await authorizeOrganizer(events, input.eventId, input.organizerId, "configure"); const updated = await events.update({ ...input, @@ -41,13 +42,17 @@ export async function updateEvent(input: { : boundedItems(input.zones, "zones", "venue zones", { count: LIMITS.zoneCount, length: LIMITS.zoneLength }), }); if (!updated) throw new Error("Event not found"); + const fields = Object.keys(input).filter((key) => !["eventId", "organizerId"].includes(key) && input[key as keyof typeof input] !== undefined); + await audit?.record({ eventId: input.eventId, actorId: input.organizerId, action: "event.updated", details: { fields, status: updated.status } }); return updated; } -export async function importEventRoster(input: { eventId: string; organizerId: string; records: RosterAttendeeInput[] }, events: EventRepository) { +export async function importEventRoster(input: { eventId: string; organizerId: string; records: RosterAttendeeInput[] }, events: EventRepository, audit?: AuditLog) { await authorizeOrganizer(events, input.eventId, input.organizerId, "importRoster"); if (!input.records.length) return { created: 0, attached: 0, alreadyOnRoster: 0, keptExisting: 0, phoneConflicts: 0 }; - return events.importRoster(input.eventId, input.records); + const result = await events.importRoster(input.eventId, input.records); + await audit?.record({ eventId: input.eventId, actorId: input.organizerId, action: "roster.imported", details: { rows: input.records.length, ...result } }); + return result; } export async function queueEventMatches(input: { eventId: string; organizerId: string }, events: EventRepository, enqueue: (eventId: string, participantId: string) => Promise) { @@ -73,11 +78,13 @@ function eventIntents(values: string[]) { /** Saves the organizer's profile form settings as a new form version. */ export async function configureProfileForm( input: { eventId: string; organizerId: string; fields: Record; currentConfig: unknown }, - events: EventRepository + events: EventRepository, + audit?: AuditLog ) { await authorizeOrganizer(events, input.eventId, input.organizerId, "configure"); const form = buildProfileForm(input.fields, readProfileForm(input.currentConfig)); const updated = await events.update({ eventId: input.eventId, organizerId: input.organizerId, formConfig: { ...form } }); if (!updated) throw new Error("Event not found"); + await audit?.record({ eventId: input.eventId, actorId: input.organizerId, action: "profile_form.updated", details: { version: form.version } }); return form; } diff --git a/apps/web/src/application/use-cases/manage-invitations.ts b/apps/web/src/application/use-cases/manage-invitations.ts index 869c987..f6bb05d 100644 --- a/apps/web/src/application/use-cases/manage-invitations.ts +++ b/apps/web/src/application/use-cases/manage-invitations.ts @@ -2,6 +2,7 @@ import { RESEND_AFTER_MINUTES } from "../../domain/participant/invitation"; import type { EventRepository } from "../ports/event-repository"; import type { NotificationPort } from "../ports/notification"; import { authorizeOrganizer } from "./manage-event"; +import type { AuditLog } from "../ports/audit-log"; export interface InvitationResult { sent: number; @@ -15,7 +16,7 @@ export interface InvitationResult { */ export async function sendInvitations( input: { eventId: string; organizerId: string; eventName: string; organizationName: string; eventUrl: string; attendeeId?: string }, - dependencies: { events: EventRepository; notifications: NotificationPort } + dependencies: { events: EventRepository; notifications: NotificationPort; audit?: AuditLog } ): Promise { await authorizeOrganizer(dependencies.events, input.eventId, input.organizerId, "invite"); const targets = await dependencies.events.invitationTargets(input.eventId, input.attendeeId ?? null, RESEND_AFTER_MINUTES); @@ -40,6 +41,10 @@ export async function sendInvitations( result.failed += 1; } } + await dependencies.audit?.record({ + eventId: input.eventId, actorId: input.organizerId, action: "invitations.sent", + subjectId: input.attendeeId ?? null, details: { ...result, resend: Boolean(input.attendeeId) }, + }); return result; } @@ -50,10 +55,13 @@ export async function sendInvitations( */ export async function setAttendeeAccess( input: { eventId: string; organizerId: string; attendeeId: string; revoked: boolean }, - dependencies: { events: EventRepository } + dependencies: { events: EventRepository; audit?: AuditLog } ): Promise { await authorizeOrganizer(dependencies.events, input.eventId, input.organizerId, "manageAccess"); if (!(await dependencies.events.setRevoked(input.eventId, input.attendeeId, input.revoked))) { throw new Error("This attendee is not on the event roster"); } + await dependencies.audit?.record({ + eventId: input.eventId, actorId: input.organizerId, action: input.revoked ? "access.removed" : "access.restored", subjectId: input.attendeeId, + }); } diff --git a/apps/web/src/application/use-cases/respond-to-intro.ts b/apps/web/src/application/use-cases/respond-to-intro.ts index 3ee9ba2..fe9492d 100644 --- a/apps/web/src/application/use-cases/respond-to-intro.ts +++ b/apps/web/src/application/use-cases/respond-to-intro.ts @@ -1,10 +1,11 @@ import type { IntroRepository } from "../ports/intro-repository"; import type { NotificationPort } from "../ports/notification"; import type { ParticipantRepository } from "../ports/participant-repository"; +import type { AuditLog } from "../ports/audit-log"; export async function respondToIntro( input: { eventId: string; introId: string; actorId: string; accept: boolean; eventName?: string }, - dependencies: { intros: IntroRepository; participants: ParticipantRepository; notifications?: NotificationPort } + dependencies: { intros: IntroRepository; participants: ParticipantRepository; notifications?: NotificationPort; audit?: AuditLog } ) { const existing = await dependencies.intros.findById(input.eventId, input.introId); if (!existing) throw new Error("Intro request not found"); @@ -12,6 +13,9 @@ export async function respondToIntro( throw new Error("This person is no longer part of the event"); } const updated = await dependencies.intros.respond(input.eventId, input.introId, input.actorId, input.accept ? "accepted" : "declined"); + if (updated.status === "accepted") { + await dependencies.audit?.record({ eventId: input.eventId, actorId: input.actorId, action: "contacts.revealed", subjectId: updated.requesterId }); + } if (updated.status === "accepted" && dependencies.notifications) { const requester = await dependencies.participants.findProfile(input.eventId, updated.requesterId); const recipient = await dependencies.participants.findProfile(input.eventId, updated.recipientId); diff --git a/apps/web/src/composition/container.ts b/apps/web/src/composition/container.ts index 636323a..05b44b7 100644 --- a/apps/web/src/composition/container.ts +++ b/apps/web/src/composition/container.ts @@ -4,6 +4,7 @@ import { PostgresMatchRepository } from "../infrastructure/postgres/match.repo"; import { PostgresParticipantRepository } from "../infrastructure/postgres/participant.repo"; import { PostgresRateLimiter } from "../infrastructure/cache/postgres-rate-limiter"; import { PostgresEventRepository } from "../infrastructure/postgres/event.repo"; +import { PostgresAuditLog } from "../infrastructure/postgres/audit.repo"; import { PostgresMatchQueue } from "../infrastructure/postgres/match-queue.repo"; import { PostgresCandidateCache } from "../infrastructure/cache/postgres-candidate-cache"; import { PostgresExplanationCache } from "../infrastructure/cache/postgres-explanation-cache"; @@ -31,6 +32,7 @@ function buildContainer() { llm, candidateCache, matchQueue: new PostgresMatchQueue(), + audit: new PostgresAuditLog(), notifications: new RealtimeNotifier(), limiter: new PostgresRateLimiter(), pipeline: new MatchingPipeline(participants, matches, embeddings, llm, candidateCache, new PostgresExplanationCache()), diff --git a/apps/web/src/infrastructure/postgres/audit.repo.ts b/apps/web/src/infrastructure/postgres/audit.repo.ts new file mode 100644 index 0000000..69603c3 --- /dev/null +++ b/apps/web/src/infrastructure/postgres/audit.repo.ts @@ -0,0 +1,19 @@ +import { audit } from "@match-maker/db"; +import type { AuditLog } from "../../application/ports/audit-log"; + +export class PostgresAuditLog implements AuditLog { + async record(entry: Parameters[0]): Promise { + try { + await audit.record(entry); + } catch (error) { + // An unavailable audit table must not undo or block the action it records. + console.error("[audit] could not record", entry.action, error); + } + } + + async recent(eventId: string, limit = 20) { + return (await audit.listForEvent(eventId, limit)).map((row) => ({ + id: row.id, action: row.action, actorName: row.actor_name, subjectName: row.subject_name, details: row.details, createdAt: row.created_at, + })); + } +} diff --git a/apps/web/src/infrastructure/postgres/participant.repo.ts b/apps/web/src/infrastructure/postgres/participant.repo.ts index c6bddb0..6063788 100644 --- a/apps/web/src/infrastructure/postgres/participant.repo.ts +++ b/apps/web/src/infrastructure/postgres/participant.repo.ts @@ -71,6 +71,10 @@ export class PostgresParticipantRepository implements ParticipantRepository { input.yearsOfExperience, input.mostImpressiveBuild, input.formVersion ?? 0, input.visible ?? null] ); if (!rowCount) throw new Error("This attendee is not on the event roster"); + if (input.visible === false) { + // Hidden profiles are not explained to others any more. + await query(`delete from pair_explanations where event_id = $1 and candidate_id = $2`, [input.eventId, input.attendeeId]); + } const saved = await this.findProfile(input.eventId, input.attendeeId); if (!saved) throw new Error("Could not load the saved profile"); return saved; diff --git a/package.json b/package.json index 4e6833c..3001b6e 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,8 @@ "keycloak:sync": "tsx tools/sync-keycloak.ts", "account:disable": "tsx tools/manage-account.ts disable", "account:enable": "tsx tools/manage-account.ts enable", - "account:revoke-sessions": "tsx tools/manage-account.ts revoke-sessions" + "account:revoke-sessions": "tsx tools/manage-account.ts revoke-sessions", + "account:erase": "tsx tools/manage-account.ts erase" }, "devDependencies": { "@types/node": "^22.10.2", diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts index 2a7239b..6c82d83 100644 --- a/packages/auth/src/index.ts +++ b/packages/auth/src/index.ts @@ -33,6 +33,7 @@ export { isUserEnabled, setUserEnabled, logoutUser, + deleteUser, resetCaches, type Pkce, type TokenSet, diff --git a/packages/auth/src/keycloak.ts b/packages/auth/src/keycloak.ts index da23cae..aca8fe5 100644 --- a/packages/auth/src/keycloak.ts +++ b/packages/auth/src/keycloak.ts @@ -387,6 +387,13 @@ export async function setUserEnabled(sub: string, enabled: boolean): Promise { + const res = await adminFetch(`/users/${encodeURIComponent(sub)}`, { method: "DELETE" }); + if (!res.ok && res.status !== 404) throw new Error(`Keycloak user deletion failed (${res.status})`); + userStatus.delete(sub); +} + /** Ends the user's Keycloak (SSO) sessions, so Google sign-in asks again. */ export async function logoutUser(sub: string): Promise { const res = await adminFetch(`/users/${encodeURIComponent(sub)}/logout`, { method: "POST" }); diff --git a/packages/db/migrations/0010_audit_events.sql b/packages/db/migrations/0010_audit_events.sql new file mode 100644 index 0000000..d9c0983 --- /dev/null +++ b/packages/db/migrations/0010_audit_events.sql @@ -0,0 +1,17 @@ +-- Security audit records: who did what to whom, for sensitive actions +-- (roster imports, invitations, access changes, settings, contact reveals, +-- account administration). Details hold counts and field names, never +-- contact data. Kept for a year by the housekeeping sweep. + +create table if not exists audit_events ( + id bigserial primary key, + event_id uuid references events(id) on delete set null, + actor_id uuid, + action text not null, + subject_id uuid, + details jsonb not null default '{}'::jsonb, + created_at timestamptz not null default now() +); + +create index if not exists idx_audit_events_event on audit_events (event_id, created_at desc); +create index if not exists idx_audit_events_created on audit_events (created_at); diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index 8d37dd8..596eb49 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -12,3 +12,4 @@ export * as matches from "./repositories/matches"; export * as events from "./repositories/events"; export * as matchingJobs from "./repositories/matching-jobs"; export * as housekeeping from "./repositories/housekeeping"; +export * as audit from "./repositories/audit"; diff --git a/packages/db/src/repositories/attendees.ts b/packages/db/src/repositories/attendees.ts index 32866ad..d41a6ee 100644 --- a/packages/db/src/repositories/attendees.ts +++ b/packages/db/src/repositories/attendees.ts @@ -93,6 +93,23 @@ export async function revokeSessions(email: string): Promise { return (rowCount ?? 0) > 0; } +/** + * Erases a person for a deletion request: their attendee row and everything + * that cascades from it (event participation, matches, introductions, login + * challenges), plus cached explanations and login challenges by e-mail. + * Returns the erased id, or null when the e-mail is unknown. + */ +export async function erase(email: string): Promise { + const normalized = normalizeEmail(email); + const { rows } = await query<{ id: string }>(`select id from registered_attendees where email = $1`, [normalized]); + const id = rows[0]?.id; + if (!id) return null; + await query(`delete from pair_explanations where viewer_id = $1 or candidate_id = $1`, [id]); + await query(`delete from login_challenges where email = $1`, [normalized]); + await query(`delete from registered_attendees where id = $1`, [id]); + return id; +} + /** True when the e-mail is on the attendee roster — the gate for every login. */ export async function isRegisteredEmail(email: string): Promise { const { rows } = await query<{ exists: boolean }>( diff --git a/packages/db/src/repositories/audit.ts b/packages/db/src/repositories/audit.ts new file mode 100644 index 0000000..e433f61 --- /dev/null +++ b/packages/db/src/repositories/audit.ts @@ -0,0 +1,43 @@ +import { query } from "../client"; + +export interface AuditEntry { + eventId?: string | null; + actorId?: string | null; + action: string; + subjectId?: string | null; + /** Counts and field names only, never contact data. */ + details?: Record; +} + +export interface AuditRecord { + id: string; + action: string; + actor_name: string | null; + subject_name: string | null; + details: Record; + created_at: Date; +} + +/** Audit records are kept this long, then swept. */ +export const AUDIT_RETENTION_DAYS = 365; + +export async function record(entry: AuditEntry): Promise { + await query( + `insert into audit_events (event_id, actor_id, action, subject_id, details) values ($1, $2, $3, $4, $5::jsonb)`, + [entry.eventId ?? null, entry.actorId ?? null, entry.action, entry.subjectId ?? null, JSON.stringify(entry.details ?? {})] + ); +} + +export async function listForEvent(eventId: string, limit = 20): Promise { + const { rows } = await query( + `select e.id::text as id, e.action, actor.name as actor_name, subject.name as subject_name, e.details, e.created_at + from audit_events e + left join registered_attendees actor on actor.id = e.actor_id + left join registered_attendees subject on subject.id = e.subject_id + where e.event_id = $1 + order by e.created_at desc, e.id desc + limit $2`, + [eventId, limit] + ); + return rows; +} diff --git a/packages/db/src/repositories/events.ts b/packages/db/src/repositories/events.ts index 97b8ede..979dc01 100644 --- a/packages/db/src/repositories/events.ts +++ b/packages/db/src/repositories/events.ts @@ -246,6 +246,10 @@ export async function setRevoked(eventId: string, attendeeId: string, revoked: b where event_id = $1 and attendee_id = $2`, [eventId, attendeeId, revoked] ); + // Explanations written about or for a removed attendee are not kept. + if (revoked && rowCount) { + await query(`delete from pair_explanations where event_id = $1 and (viewer_id = $2 or candidate_id = $2)`, [eventId, attendeeId]); + } return (rowCount ?? 0) > 0; } diff --git a/packages/db/src/repositories/housekeeping.ts b/packages/db/src/repositories/housekeeping.ts index 42226c9..36f995e 100644 --- a/packages/db/src/repositories/housekeeping.ts +++ b/packages/db/src/repositories/housekeeping.ts @@ -1,5 +1,6 @@ import { query } from "../client"; import { deleteExpired as deleteExpiredChallenges } from "./login-challenges"; +import { AUDIT_RETENTION_DAYS } from "./audit"; /** How long a dead row is kept before the sweep removes it. */ export const RETENTION = { @@ -14,6 +15,7 @@ export interface SweepResult { rateLimitBuckets: number; retrievalCache: number; pairExplanations: number; + auditEvents: number; } /** Deletes rows that can no longer be used. Safe to run on any schedule. */ @@ -25,8 +27,9 @@ export async function sweepExpired(): Promise { ); const cache = await query(`delete from retrieval_cache where expires_at < now()`); const explanations = await query(`delete from pair_explanations where expires_at < now()`); + const audits = await query(`delete from audit_events where created_at < now() - make_interval(days => $1)`, [AUDIT_RETENTION_DAYS]); return { loginChallenges, rateLimitBuckets: buckets.rowCount ?? 0, retrievalCache: cache.rowCount ?? 0, - pairExplanations: explanations.rowCount ?? 0, + pairExplanations: explanations.rowCount ?? 0, auditEvents: audits.rowCount ?? 0, }; } diff --git a/tests/integration/audit-retention.test.ts b/tests/integration/audit-retention.test.ts new file mode 100644 index 0000000..d9b8b61 --- /dev/null +++ b/tests/integration/audit-retention.test.ts @@ -0,0 +1,97 @@ +/** + * Audit records and data retention against a real Postgres (and the local + * Keycloak realm for erasure). Uses its own organization, event and people. + * Skipped when DATABASE_URL is unset; the erase case also needs Keycloak. + */ +import { randomUUID } from "node:crypto"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { attendees, audit, closePool, events, housekeeping, query } from "@match-maker/db"; +import { ensureUser, findUserByEmail } from "@match-maker/auth"; +import { migrate } from "../../packages/db/src/migrate"; +import { PostgresParticipantRepository } from "../../apps/web/src/infrastructure/postgres/participant.repo"; +import { manageAccount } from "../../tools/manage-account"; +import { Intent } from "../../apps/web/src/domain/participant/intent"; + +const describeDb = process.env.DATABASE_URL ? describe : describe.skip; +const issuer = (process.env.KEYCLOAK_INTERNAL_ISSUER || process.env.KEYCLOAK_ISSUER || "").replace(/\/$/, ""); +const keycloakUp = await fetch(`${issuer}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(3000) }).then((res) => res.ok).catch(() => false); +const RUN = Date.now().toString(36); +const ORG = `audit-${RUN}`; +const email = (key: string) => `audit-${key}-${RUN}@example.com`; + +describeDb("audit records and retention", () => { + const participants = new PostgresParticipantRepository(); + const ids: Record = {}; + let eventId: string; + + const explain = (viewer: string, candidate: string) => query( + `insert into pair_explanations (cache_key, event_id, viewer_id, candidate_id, reason, expires_at) + values ($1, $2, $3, $4, 'reason', now() + interval '1 day')`, [randomUUID(), eventId, viewer, candidate]); + const explanationsAbout = async (id: string) => + (await query(`select 1 from pair_explanations where viewer_id = $1 or candidate_id = $1`, [id])).rows.length; + + beforeAll(async () => { + await migrate(); + await attendees.upsertMany(["org", "kim", "lou", "max"].map((key) => ({ name: `Audit ${key}`, email: email(key) }))); + for (const key of ["org", "kim", "lou", "max"]) ids[key] = (await attendees.findByEmail(email(key)))!.id; + const { rows: [org] } = await query<{ id: string }>(`insert into organizations (name, slug) values ($1, $1) returning id`, [ORG]); + eventId = (await query<{ id: string }>(`insert into events (organization_id, name, slug, status) values ($1, $2, $2, 'open') returning id`, [org.id, ORG])).rows[0].id; + await events.attachRoster(eventId, [ids.kim, ids.lou, ids.max]); + }); + + afterAll(async () => { + await query(`delete from audit_events where subject_id = any($1::uuid[]) or actor_id = any($1::uuid[])`, [Object.values(ids)]); + await query(`delete from organizations where slug = $1`, [ORG]); + await query(`delete from registered_attendees where email like $1`, [`audit-%-${RUN}@example.com`]); + await closePool(); + }); + + it("records actions with the people involved, newest first", async () => { + await audit.record({ eventId, actorId: ids.org, action: "roster.imported", details: { attached: 3 } }); + await audit.record({ eventId, actorId: ids.org, action: "access.removed", subjectId: ids.kim }); + const recent = await audit.listForEvent(eventId); + expect(recent.map((row) => row.action)).toEqual(["access.removed", "roster.imported"]); + expect(recent[0]).toMatchObject({ actor_name: "Audit org", subject_name: "Audit kim" }); + expect(recent[1].details).toEqual({ attached: 3 }); + }); + + it("sweeps records older than the retention period", async () => { + await audit.record({ eventId, action: "old.action", subjectId: ids.lou }); + await query(`update audit_events set created_at = now() - interval '400 days' where action = 'old.action' and subject_id = $1`, [ids.lou]); + await housekeeping.sweepExpired(); + expect((await query(`select 1 from audit_events where action = 'old.action' and subject_id = $1`, [ids.lou])).rows).toHaveLength(0); + }); + + it("drops cached explanations about someone removed from the event", async () => { + await explain(ids.kim, ids.lou); + await explain(ids.lou, ids.kim); + await events.setRevoked(eventId, ids.kim, true); + expect(await explanationsAbout(ids.kim)).toBe(0); + }); + + it("drops explanations of a profile that is hidden", async () => { + await explain(ids.max, ids.lou); + await participants.saveProfile({ + eventId, attendeeId: ids.lou, designation: "Engineer", domain: "AI", aboutMe: "x", selfDescription: null, + yearsOfExperience: null, mostImpressiveBuild: null, intent: Intent.NETWORKING, interests: [], venueZone: null, visible: false, + }); + expect(await explanationsAbout(ids.lou)).toBe(0); + }); + + (keycloakUp && process.env.KEYCLOAK_ADMIN_PASSWORD ? it : it.skip)("erases a person, their event data and their Keycloak user", async () => { + await ensureUser(email("max"), "Audit max"); + await explain(ids.lou, ids.max); + const report = await manageAccount("erase", email("max")); + expect(report.join("\n")).toMatch(/keycloak: user deleted/); + expect(await attendees.findByEmail(email("max"))).toBeNull(); + expect((await query(`select 1 from event_participants where attendee_id = $1`, [ids.max])).rows).toHaveLength(0); + expect(await explanationsAbout(ids.max)).toBe(0); + expect(await findUserByEmail(email("max"))).toBeNull(); + expect((await query(`select 1 from audit_events where action = 'account.erased' and subject_id = $1`, [ids.max])).rows).toHaveLength(1); + }); + + it("keeps records when their event is deleted", async () => { + await query(`delete from events where id = $1`, [eventId]); + expect((await query(`select event_id from audit_events where action = 'roster.imported' and actor_id = $1`, [ids.org])).rows[0].event_id).toBeNull(); + }); +}); diff --git a/tests/unit/invitations.test.ts b/tests/unit/invitations.test.ts index 35c176b..595497e 100644 --- a/tests/unit/invitations.test.ts +++ b/tests/unit/invitations.test.ts @@ -84,6 +84,17 @@ describe("setAttendeeAccess", () => { }); }); +describe("audit records", () => { + it("records invitations sent and access changes", async () => { + const { events, notifications } = ports([{ attendee_id: "a", email: "a@example.com", name: "A" }]); + const audit = { record: vi.fn(async () => {}), recent: vi.fn() }; + await sendInvitations(event, { events, notifications, audit }); + await setAttendeeAccess({ eventId: "event", organizerId: "organizer", attendeeId: "a", revoked: true }, { events, audit }); + expect(audit.record).toHaveBeenCalledWith(expect.objectContaining({ action: "invitations.sent", actorId: "organizer", details: expect.objectContaining({ sent: 1 }) })); + expect(audit.record).toHaveBeenCalledWith(expect.objectContaining({ action: "access.removed", subjectId: "a" })); + }); +}); + describe("renderInvitationEmail", () => { it("links to the event and escapes names in the HTML", () => { const mail = renderInvitationEmail({ name: "