@crowdsource.you/core 1.2.0

package/src/outbox/evidence.ts

@@ -0,0 +1,231 @@
+import { createHash } from 'crypto';
+import type { ReportInput } from '../index.js';
+import type {
+  ModerationReportFields,
+  ModerationSubjectProvider,
+  ModerationSubjectSnapshot,
+  ModerationTaxonomy,
+} from './types.js';
+
+/**
+ * Turning a stored report into the thing the SDK delivers.
+ *
+ * This is NOT a case-envelope builder, and the difference matters enough to
+ * name: `@crowdsource.you/core` builds the Case Envelope, and it deliberately does
+ * not export the function that does it. What this module produces is the SDK's
+ * `ReportInput` — a description of the material — and the SDK derives the
+ * envelope from it: resource ids, relations, digests, pseudonymous principal
+ * refs, the identity binding proof, the pinned policy version, the privacy terms
+ * and the idempotency key.
+ *
+ * That is not a technicality. Those derived values are exactly what the case
+ * dedup key is computed over, so an application that composed its own envelope
+ * would be the reason two reporters about one object opened two cases — and "one
+ * penalty per incident" would fail in production with nothing failing in a test.
+ * Building the description and letting the SDK build the document is what keeps
+ * that property true for every application at once.
+ *
+ * So this module does three things and no more: ask the registry for a snapshot
+ * of the reported object, translate the reporter's categories into allegations,
+ * and assemble both with the report's own identity.
+ */
+
+/**
+ * The material could not be described, because nothing can describe it.
+ *
+ * This is a DEFECT, not a state, and it should be unreachable. A report whose
+ * type has no subject provider never gets a delivery event in the first place —
+ * intake decides that from the same registry this module reads — so an event
+ * that arrives here has been created by something that bypassed intake, or by a
+ * deployment where a provider was removed while its reports were still in
+ * flight.
+ *
+ * `retryable: false` therefore dead-letters the outbox event, so the
+ * reconciliation sweep counts it and a human looks. The alternative — writing a
+ * local state — would file a genuine defect in the one place that looks
+ * identical to the deliberate local-only reports, and nothing would ever alert
+ * on it.
+ *
+ * Separate from "the object is gone": a deleted object is a fact about the world
+ * and closes the report normally.
+ */
+export class ModerationSubjectUnsupportedError extends Error {
+  readonly retryable = false;
+
+  constructor(reportedType: string) {
+    super(`No moderation subject provider is registered for '${reportedType}'.`);
+    this.name = 'ModerationSubjectUnsupportedError';
+  }
+}
+
+/**
+ * The application's taxonomy produced no allegation for a report.
+ *
+ * Not retryable and never silently defaulted. A report with no allegation is not
+ * a report, and substituting `other.unclassifiable` here would put a claim in
+ * front of a jury that no reporter made and that no version of the mapping
+ * records — the taxonomy is the application's to fix, and dead-lettering is what
+ * makes somebody fix it.
+ */
+export class ModerationTaxonomyError extends Error {
+  readonly retryable = false;
+
+  constructor(categories: readonly string[]) {
+    super(
+      `The report taxonomy produced no allegation for categories [${categories.join(', ')}]. ` +
+        'Map every category to a code; use `other.unclassifiable` for one the universal taxonomy cannot name.',
+    );
+    this.name = 'ModerationTaxonomyError';
+  }
+}
+
+/**
+ * SHA-256 of the snapshot, stored on the report.
+ *
+ * Taken over the described MATERIAL, not over the whole `ReportInput`: the
+ * report id, the reporter and the allegations are properties of the report, and
+ * including them would mean two people reporting identical content produced
+ * different hashes — which is the opposite of what this hash is for. Key order
+ * is fixed by the literal below rather than by `Object.keys`, so the digest is
+ * stable across Node versions and across a refactor that reorders a field.
+ */
+export function snapshotHash(snapshot: ModerationSubjectSnapshot): string {
+  const canonical = JSON.stringify({
+    subject: {
+      externalId: snapshot.subject.externalId,
+      type: snapshot.subject.type,
+      author: snapshot.subject.author?.oxyUserId ?? null,
+    },
+    content: snapshot.content,
+    attachments: snapshot.attachments ?? [],
+    context: snapshot.context ?? [],
+  });
+  return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+
+/** The subject providers, indexed by the application's own reported type. */
+export interface SubjectRegistry {
+  /**
+   * The provider for a reported type, or `undefined` when it is not deliverable.
+   *
+   * The single authority on whether a report leaves this deployment. Intake asks
+   * before queueing a delivery, and this module asks again when it builds one; a
+   * type this returns `undefined` for is stored and never enqueued.
+   */
+  providerFor(reportedType: string): ModerationSubjectProvider | undefined;
+  /**
+   * The reported types wired to CrowdSource, as the registry itself sees them.
+   *
+   * Exists so an application can pin the set in a test. That is not ceremony:
+   * the difference between a delivered type and a local-only one is invisible in
+   * a 201, so registering a provider — or forgetting to — is a change no
+   * response body would reveal.
+   */
+  deliverableTypes(): string[];
+}
+
+export function createSubjectRegistry(
+  providers: readonly ModerationSubjectProvider[],
+): SubjectRegistry {
+  const byType = new Map<string, ModerationSubjectProvider>();
+  for (const provider of providers) {
+    const existing = byType.get(provider.reportedType);
+    if (existing) {
+      /**
+       * Two providers for one noun is not a merge to resolve quietly: whichever
+       * one lost would describe nothing, and the subject type a jury reasons
+       * about would depend on array order.
+       */
+      throw new Error(
+        `Two moderation subject providers are registered for '${provider.reportedType}' ` +
+          `('${existing.subjectType}' and '${provider.subjectType}'). A reported type has one provider.`,
+      );
+    }
+    byType.set(provider.reportedType, provider);
+  }
+
+  return {
+    providerFor: (reportedType) => byType.get(reportedType),
+    deliverableTypes: () => Array.from(byType.keys()),
+  };
+}
+
+export interface ModerationReportInput {
+  /** What the SDK delivers. */
+  readonly reportInput: ReportInput;
+  /** The digest to store on the local report. */
+  readonly snapshotHash: string;
+}
+
+/**
+ * Describe a stored report for delivery, or report why it cannot be described.
+ *
+ * Returns `null` when the reported object no longer exists. That is not an error
+ * either: content deleted between the report and its delivery is ordinary, and
+ * evidence stays available through retention on CrowdSource's side — but an
+ * object the application never got to snapshot has no evidence to keep.
+ */
+export async function buildModerationReportInput(input: {
+  report: Pick<
+    ModerationReportFields,
+    'reportedType' | 'reportedId' | 'reporter' | 'categories' | 'details' | 'createdAt'
+  > & { id: string };
+  registry: SubjectRegistry;
+  taxonomy: ModerationTaxonomy;
+}): Promise<ModerationReportInput | null> {
+  const { report, registry, taxonomy } = input;
+  const provider = registry.providerFor(report.reportedType);
+  if (!provider) throw new ModerationSubjectUnsupportedError(report.reportedType);
+
+  const snapshot = await provider.snapshot(report.reportedId);
+  if (!snapshot) return null;
+
+  const allegationCodes = taxonomy.allegationsFor(report.categories);
+  if (allegationCodes.length === 0) throw new ModerationTaxonomyError(report.categories);
+  const details = report.details?.trim();
+
+  return {
+    reportInput: {
+      externalReportId: report.id,
+      subject: snapshot.subject,
+      content: snapshot.content,
+      ...(snapshot.attachments === undefined ? {} : { attachments: snapshot.attachments }),
+      ...(snapshot.context === undefined ? {} : { context: snapshot.context }),
+      /**
+       * The reporter's own words ride on the FIRST allegation only.
+       *
+       * Repeating one free-text field across every code would say the reporter
+       * wrote it about each of them separately, and details are the reporter's
+       * claim and never evidence for it.
+       */
+      allegations: allegationCodes.map((code, index) =>
+        index === 0 && details ? { code, details } : { code },
+      ),
+      /**
+       * The Oxy subject IS the binding proof. Reporters are stored as Oxy user
+       * ids, so there is no separate binding step to implement here.
+       */
+      reportedBy: { oxyUserId: report.reporter },
+      /**
+       * The moment the USER reported it — the local report's own timestamp, not
+       * the moment of delivery. Any value invented per attempt would make every
+       * retry from the outbox a permanent 409.
+       */
+      submittedAt: report.createdAt,
+      metadata: {
+        /**
+         * The application's own entries FIRST, so the two below cannot be
+         * shadowed. An adopter that names `taxonomyVersion` or `categories` gets
+         * them overwritten rather than winning — a case has to be readable back
+         * against the mapping that produced it, and that is not negotiable per
+         * application.
+         */
+        ...taxonomy.metadata,
+        /** So a case can be read back against the mapping that produced it. */
+        taxonomyVersion: taxonomy.version,
+        categories: [...report.categories].sort().join(','),
+      },
+    },
+    snapshotHash: snapshotHash(snapshot),
+  };
+}

package/src/outbox/inbound.ts

@@ -0,0 +1,140 @@
+import type { ProcessedEventStore } from '../express/index.js';
+import { decisionApplyEventId, type OutboxService } from './outbox/service.js';
+import { MODERATION_EVENT_RETENTION_SECONDS } from './retention.js';
+import type { ModerationEventStore, ModerationTransactionRunner } from './store/types.js';
+
+/**
+ * What happens between "a signed decision arrived" and "2xx".
+ *
+ * The receiver's contract is to answer quickly and queue the processing. So
+ * exactly two writes happen here, in ONE transaction — the event's audit row is
+ * completed and a durable `decision.apply` event is created — and the dispatcher
+ * does the rest.
+ *
+ * The transaction is what makes the dedupe safe. The middleware has already
+ * claimed the event id by inserting the row (see {@link createProcessedEventStore});
+ * if completing that row and queueing the work were two operations, a crash
+ * between them would leave an event that is permanently deduplicated with no
+ * work queued — a decision silently lost, with a row that says it arrived.
+ * Committing both together means the only two possible outcomes are "recorded
+ * and queued" or "neither", and "neither" releases the claim and gets
+ * redelivered.
+ */
+
+/**
+ * The webhook dedupe store, backed by the moderation event log.
+ *
+ * `@crowdsource.you/core/express` defaults to an in-process store and says exactly
+ * when that is not enough: two instances behind a load balancer each keep their
+ * own, so a redelivery landing on the other instance is not deduplicated. Every
+ * Oxy backend runs several tasks behind one load balancer, so this is that case.
+ *
+ * The claim/release contract is the SDK's, and it is the right one. A row
+ * inserted BEFORE the handler runs means a concurrent redelivery cannot also run
+ * it; deleting that row when the handler THROWS means the sender's retry
+ * schedule can still deliver the event later. Recording the id only after
+ * success would let two copies run at once; recording it before and never
+ * releasing would make a transient failure permanent and lose a decision
+ * silently.
+ *
+ * The retention window is computed HERE rather than in a store, so both backends
+ * keep an audit row for the same length of time.
+ */
+export function createProcessedEventStore<TTx>(
+  events: ModerationEventStore<TTx>,
+): ProcessedEventStore {
+  return {
+    async claim(eventId: string): Promise<boolean> {
+      const now = new Date();
+      return await events.claim({
+        eventId,
+        receivedAt: now,
+        expiresAt: new Date(now.getTime() + MODERATION_EVENT_RETENTION_SECONDS * 1_000),
+      });
+    },
+
+    async release(eventId: string): Promise<void> {
+      await events.release(eventId);
+    },
+  };
+}
+
+export interface RecordDecisionEventInput {
+  eventId: string;
+  type: string;
+  caseId: string;
+  /**
+   * The decision as delivered.
+   *
+   * `unknown`, deliberately. It is stored whole and parsed against the published
+   * contract by the worker that acts on it — these payloads are deliberately
+   * loose, and validating here would mean an event whose shape this deployment
+   * does not recognise yet is refused at the door and retried until it
+   * dead-letters, instead of being kept until the code catches up.
+   */
+  decision: unknown;
+}
+
+export interface InboundService {
+  /** Record a decision-bearing event and queue its application. */
+  recordDecisionEvent(input: RecordDecisionEventInput): Promise<void>;
+  /**
+   * Record an event there is nothing to do about.
+   *
+   * `case.created`, `case.escalated`, `case.closed` and any type a newer
+   * CrowdSource introduces. No outbox row, because no work — but the row is
+   * kept, because "did CrowdSource tell us about this case, and when" is the
+   * first question asked when a report looks stuck, and it has to be answerable.
+   */
+  recordIgnoredEvent(input: {
+    eventId: string;
+    type: string;
+    caseId?: string;
+  }): Promise<void>;
+}
+
+export function createInboundService<TTx>(input: {
+  transaction: ModerationTransactionRunner<TTx>;
+  events: ModerationEventStore<TTx>;
+  outbox: OutboxService<TTx>;
+}): InboundService {
+  return {
+    async recordDecisionEvent(event) {
+      await input.transaction.run(async (tx) => {
+        const now = new Date();
+        await input.events.markQueued(
+          {
+            eventId: event.eventId,
+            type: event.type,
+            caseId: event.caseId,
+            payload: { caseId: event.caseId, decision: event.decision },
+            now,
+          },
+          tx,
+        );
+
+        await input.outbox.enqueue(
+          {
+            eventId: decisionApplyEventId(event.eventId),
+            kind: 'decision.apply',
+            payload: {
+              eventId: event.eventId,
+              caseId: event.caseId,
+              decision: event.decision,
+            },
+          },
+          tx,
+        );
+      });
+    },
+
+    async recordIgnoredEvent(event) {
+      await input.events.markIgnored({
+        eventId: event.eventId,
+        type: event.type,
+        ...(event.caseId === undefined ? {} : { caseId: event.caseId }),
+        now: new Date(),
+      });
+    },
+  };
+}

package/src/outbox/index.ts

@@ -0,0 +1,160 @@
+/**
+ * `@crowdsource.you/core/outbox` — the application half of a CrowdSource integration.
+ *
+ * An application that adopts CrowdSource has to solve the same six problems
+ * every other application does: store a report and its promise of delivery
+ * atomically, deliver it with retries and a dead-letter path, receive signed
+ * decisions without a body parser destroying the signature, deduplicate
+ * redeliveries across several tasks, apply a decision without a stale revision
+ * overwriting a fresh one, and carry out consequences exactly once and
+ * reversibly. None of that has anything to do with what the application's
+ * objects are.
+ *
+ * So all of it is here, and an application supplies four things: its subjects,
+ * its category mapping, its enforcement tables, and a STORE built by the
+ * PostgreSQL store factory.
+ *
+ * ```ts
+ * import { createModerationIntegration } from '@crowdsource.you/core/outbox';
+ * import { postgresModerationStore } from '@crowdsource.you/core/outbox/postgres';
+ *
+ * const moderation = createModerationIntegration({
+ *   store,
+ *   crowdSource: { enabled: true, serviceKey, webhookSecret, enforcementMode: 'observe' },
+ *   subjects: [listingSubjectProvider(), reviewSubjectProvider()],
+ *   taxonomy: { version: '2026.07', allegationsFor },
+ *   enforcement: commerceEnforcement,
+ *   logger,
+ * });
+ *
+ * // Indexes before the first write: the unique ones ARE the exactly-once
+ * // mechanism, and an index that does not exist yet refuses nothing.
+ * await store.ensureSchema();
+ *
+ * // BEFORE express.json() — the signature covers the bytes that arrived.
+ * app.use('/webhooks', moderation.webhookRouter());
+ * app.use(express.json());
+ *
+ * moderation.dispatcher.start();
+ * ```
+ *
+ * Two invariants are ENFORCED here rather than documented, because both fail
+ * silently and neither shows up in a test that only asserts the happy path:
+ *
+ * 1. Nothing can be enqueued that is not already recorded in the outbox, in the
+ *    same transaction. {@link ModerationOutboxTransactionError} is thrown by the
+ *    only writer of that collection when the transaction it was handed is not
+ *    open.
+ * 2. The webhook receiver reads raw bytes. Mounted after a JSON parser it
+ *    refuses rather than verifying a signature over a re-serialisation.
+ *
+ * Types come from `@crowdsource.you/contracts` and `@crowdsource.you/core`. This
+ * package re-exports none of them: a `Decision` or a `TaxonomyCode` has exactly
+ * one definition.
+ */
+
+export { createModerationIntegration } from './integration.js';
+export type { ModerationIntegration } from './integration.js';
+
+/**
+ * The retention windows are storage-independent policy, so they stay here while
+ * PostgreSQL-specific tables and stores live behind the `/postgres` subpath.
+ */
+export {
+  MODERATION_EVENT_RETENTION_SECONDS,
+  MODERATION_OUTBOX_RETENTION_SECONDS,
+} from './retention.js';
+
+export {
+  ModerationOutboxTransactionError,
+  decisionApplyEventId,
+  isRetryableDeliveryError,
+  reportSubmitEventId,
+} from './outbox/service.js';
+export type {
+  ModerationOutboxFailure,
+  ModerationOutboxHandler,
+  OutboxDrain,
+  OutboxService,
+} from './outbox/service.js';
+
+export type {
+  ModerationEnforcementInsert,
+  ModerationEnforcementKey,
+  ModerationEnforcementStore,
+  ModerationEventStore,
+  ModerationOutboxStore,
+  ModerationReportDecisionUpdate,
+  ModerationReportInsert,
+  ModerationReportRef,
+  ModerationReportStore,
+  ModerationStore,
+  ModerationTransactionRunner,
+} from './store/types.js';
+
+export { ModerationOutboxDispatcher } from './outbox/dispatcher.js';
+export { ModerationReconciliationJob } from './reconciliation.js';
+export type { ReconcileModerationReports } from './reconciliation.js';
+
+export { DuplicateReportError } from './intake.js';
+
+export {
+  CrowdSourceUnavailableError,
+  ModerationDeliveryRejectedError,
+} from './delivery.js';
+
+export {
+  ModerationDecisionDeferredError,
+  ModerationDecisionRejectedError,
+} from './decision.js';
+
+export {
+  ModerationSubjectUnsupportedError,
+  ModerationTaxonomyError,
+  createSubjectRegistry,
+  snapshotHash,
+} from './evidence.js';
+export type { ModerationReportInput, SubjectRegistry } from './evidence.js';
+
+export {
+  ModerationRestoreDirectionError,
+  assertRestoreDirection,
+  planEnforcement,
+  primaryAction,
+} from './enforcement/planner.js';
+export type { EnforcementExecutor } from './enforcement/executor.js';
+
+export { localStatusForDecision } from './reportStatus.js';
+
+export { createProcessedEventStore } from './inbound.js';
+export type { InboundService, RecordDecisionEventInput } from './inbound.js';
+
+export type {
+  CreateReportInput,
+  CreateReportResult,
+  CrowdSourceConnectionConfig,
+  EnforcementEffect,
+  EnforcementOutcome,
+  EnforcementPreviousState,
+  EnforcementSubject,
+  ModerationContextResource,
+  ModerationDispatchResult,
+  ModerationEnforcementConfig,
+  ModerationEnforcementMode,
+  ModerationIntegrationConfig,
+  ModerationLocalStatus,
+  ModerationLogger,
+  ModerationMetrics,
+  ModerationOutboxEvent,
+  ModerationOutboxKind,
+  ModerationOutboxPayload,
+  ModerationOutboxStatus,
+  ModerationReconciliationResult,
+  ModerationReportFields,
+  ModerationResource,
+  ModerationSubjectProvider,
+  ModerationSubjectSnapshot,
+  ModerationTaxonomy,
+  PlannedEnforcementAction,
+  ReportDecisionExtraFields,
+} from './types.js';