@crowdsource.you/core 1.2.0

package/src/outbox/webhook.ts

@@ -0,0 +1,165 @@
+import { Router } from 'express';
+import { crowdsourceWebhooks, type ProcessedEventStore } from '../express/index.js';
+import type { InboundService } from './inbound.js';
+import type { ModerationLogger, ModerationMetrics } from './types.js';
+
+/**
+ * `POST /crowdsource` — where decisions come back.
+ *
+ * ## The mount is part of the correctness
+ *
+ * This router MUST be mounted BEFORE `express.json()`. The signature covers
+ * `timestamp + "." + rawBody` — the bytes that arrived — and once a JSON parser
+ * has run, those bytes are gone. `@crowdsource.you/core/express` looks for a raw
+ * Buffer; handed a parsed `req.body` it refuses and raises a configuration error
+ * rather than verifying a signature over a re-serialisation. That refusal is the
+ * correct behaviour and it is also why the mount order cannot be got wrong
+ * silently.
+ *
+ * The property to TEST is not the mount order — that only proves the order. It
+ * is that no parser ran: assert `typeof req.body === 'undefined'` from inside
+ * the route.
+ *
+ * ## What this handler does and does not do
+ *
+ * It records and returns. A receiver should answer 2xx quickly and queue the
+ * processing, and the reason is not latency: applying a decision means reading
+ * objects, planning enforcement and writing several collections, and a receiver
+ * that did all that inline would time out under a burst and be retried while the
+ * first attempt was still running. So the event and a durable `decision.apply`
+ * outbox row commit in ONE transaction, and the dispatcher does the work.
+ *
+ * Nothing here is authenticated by Oxy. The HMAC IS the authentication, and an
+ * Oxy session must never satisfy this route — it is not a user endpoint.
+ */
+
+/**
+ * One string field out of an event payload this version does not know.
+ *
+ * A webhook envelope's `data` is deliberately OPAQUE in the contract: an
+ * unrecognised event's payload is whatever a newer CrowdSource decided to send,
+ * and the exported type says so — property access on it does not compile. That
+ * is the contract being honest rather than an obstacle, so this reads the key
+ * defensively instead of asserting a shape nobody has verified. Anything that is
+ * not a string is treated as absent, which is the only safe reading of a field
+ * this deployment has never seen.
+ */
+function stringField(source: unknown, key: string): string | undefined {
+  if (typeof source !== 'object' || source === null) return undefined;
+  const value: unknown = Reflect.get(source, key);
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function createWebhookRouter(input: {
+  inbound: InboundService;
+  store: ProcessedEventStore;
+  secret?: string;
+  previousSecret?: string;
+  logger: ModerationLogger;
+  metrics?: ModerationMetrics;
+  /** Defaults to `/crowdsource`. */
+  path?: string;
+}): Router {
+  const router = Router();
+
+  if (!input.secret) {
+    /**
+     * Not mounted, rather than mounted and permissive.
+     *
+     * A route that answers anything at all without a secret is a route that will
+     * one day be reasoned about as if it verified something. An unconfigured
+     * deployment 404s here, which is indistinguishable from not having the
+     * feature — which is exactly what it is.
+     */
+    input.logger.info(
+      '[CrowdSource] webhook route not mounted: no webhook secret is configured',
+    );
+    return router;
+  }
+
+  router.post(
+    input.path ?? '/crowdsource',
+    crowdsourceWebhooks({
+      secret: input.secret,
+      ...(input.previousSecret === undefined
+        ? {}
+        : { previousSecret: input.previousSecret }),
+      // Shared across tasks: the in-process default would dedupe only the
+      // instance that happened to receive both copies of a redelivery.
+      store: input.store,
+      on: {
+        /**
+         * A decision, provisional or final. Both are queued: a provisional
+         * decision is real and is recorded; what may be ACTED on is decided by
+         * the enforcement mode, not by discarding the event here.
+         */
+        'case.decided': async (event) => {
+          await input.inbound.recordDecisionEvent({
+            eventId: event.id,
+            type: event.type,
+            caseId: event.data.caseId,
+            decision: event.data.decision,
+          });
+        },
+        /**
+         * A later revision replacing an earlier one. The SAME path: the decision
+         * worker compares revisions and the enforcement executor reverses what
+         * the superseded revision did. A correction is not a special case with
+         * its own code — it is an ordinary decision that supersedes another, and
+         * giving it a separate path is how a restore ends up not being
+         * idempotent.
+         */
+        'decision.corrected': async (event) => {
+          await input.inbound.recordDecisionEvent({
+            eventId: event.id,
+            type: event.type,
+            caseId: event.data.caseId,
+            decision: event.data.decision,
+          });
+        },
+        /**
+         * An appeal's outcome carries a decision too, and it is the current
+         * answer for the case, so it takes the same path.
+         */
+        'appeal.decided': async (event) => {
+          await input.inbound.recordDecisionEvent({
+            eventId: event.id,
+            type: event.type,
+            caseId: event.data.caseId,
+            decision: event.data.decision,
+          });
+        },
+      },
+      /**
+       * Every other event type — including one this version of the contracts
+       * package has never heard of.
+       *
+       * Recorded rather than dropped. `case.created`, `case.escalated` and
+       * `case.closed` carry no decision and nothing to enforce, but "did
+       * CrowdSource tell us about this case, and when" is the first question
+       * asked when a report appears stuck, and the answer has to exist
+       * somewhere.
+       */
+      onUnhandled: async (event) => {
+        const caseId = stringField(event.data, 'caseId');
+        await input.inbound.recordIgnoredEvent({
+          eventId: event.id,
+          type: event.type,
+          ...(caseId === undefined ? {} : { caseId }),
+        });
+      },
+      /**
+       * A refusal reason and nothing else — never a body, a header or a
+       * signature. It is a bounded label, so it can be a metric.
+       */
+      onRejected: (rejection) => {
+        input.metrics?.incrementCounter('crowdsource_webhook_rejected_total', 1, {
+          rejection,
+        });
+        input.logger.warn('[CrowdSource] webhook delivery refused', { rejection });
+      },
+    }),
+  );
+
+  return router;
+}

package/src/reports.ts

@@ -0,0 +1,138 @@
+/**
+ * `POST /v1/reports` and `GET /v1/reports/{id}` (§10.2, §10.4).
+ *
+ * The 202 this returns means what §7.1 says it means: the report is stored and
+ * durable rows exist for everything that happens next. It does not mean a jury
+ * exists, a decision exists, or that any downstream call succeeded — and an
+ * application that treats it as "moderation is done" has misread the contract.
+ * The decision comes back later, over a webhook.
+ */
+
+import {
+  CreateReportResponseSchema,
+  type CreateReportResponse,
+  type ReportStatus,
+} from '@crowdsource.you/contracts';
+import { z } from 'zod';
+
+import { composeCaseEnvelope, defaultIdempotencyKey, type ReportInput } from './envelope.js';
+import { CrowdSourceTransportError } from './errors.js';
+import type { Transport } from './transport.js';
+
+/**
+ * `GET /v1/reports/{id}` (§10.2 "receipt, caseId and limited status").
+ *
+ * Declared here because `@crowdsource.you/contracts` publishes the DOCUMENTS
+ * that travel over the API and not every HTTP response shape. The receipt and
+ * the case view below both belong in contracts; until they move, these are the
+ * types integrators compile against and the loose parse is what keeps a newer
+ * server from breaking an older client (§10.11).
+ */
+export interface ReportReceipt {
+  readonly reportId: string;
+  readonly externalReportId: string;
+  readonly caseId: string;
+  /**
+   * §3.2's report states, kept open. §10.11 requires a newer server not to break
+   * an older client, and a state added to §3.2 is exactly that case: the union
+   * still autocompletes the four this version knows and still type-checks the
+   * fifth when it arrives.
+   */
+  readonly status: ReportStatus | (string & {});
+  /** ISO-8601 UTC, as the API sends it. */
+  readonly receivedAt: string;
+}
+
+const ReportReceiptSchema = z.looseObject({
+  reportId: z.string(),
+  externalReportId: z.string(),
+  caseId: z.string(),
+  status: z.string(),
+  receivedAt: z.string(),
+});
+
+export interface ReportRequestOptions {
+  readonly signal?: AbortSignal;
+}
+
+export class Reports {
+  private readonly transport: Transport;
+  /**
+   * Awaited rather than read: with an Oxy service token the client has no
+   * credential to read an application id off, so the id is resolved from
+   * CrowdSource once and this holds that answer (settled or still in flight).
+   * A service key resolves to a plain string, and awaiting one costs nothing.
+   */
+  private readonly applicationId: string | Promise<string>;
+  private readonly environment: 'production' | 'sandbox';
+
+  constructor(input: {
+    transport: Transport;
+    applicationId: string | Promise<string>;
+    environment: 'production' | 'sandbox';
+  }) {
+    this.transport = input.transport;
+    this.applicationId = input.applicationId;
+    this.environment = input.environment;
+  }
+
+  /**
+   * Delivers a report.
+   *
+   * Call this from a delivery worker draining the application's own outbox, not
+   * from the request handler that answered the user (§7.1). The user is told
+   * their report was received the moment it is stored locally; this call is what
+   * eventually makes it CrowdSource's problem, and it is allowed to fail and be
+   * retried without the user ever knowing.
+   *
+   * Re-delivering the same report is safe and returns the same `reportId`. What
+   * is NOT safe is re-delivering the same `externalReportId` with a CHANGED
+   * body: §10.5 answers 409 and this client surfaces it as
+   * `CrowdSourceApiError` with `isPayloadConflict` and `retryable: false`,
+   * because no number of retries makes two different payloads one report.
+   */
+  async create(
+    input: ReportInput,
+    options: ReportRequestOptions = {},
+  ): Promise<CreateReportResponse> {
+    const envelope = composeCaseEnvelope(input, {
+      applicationId: await this.applicationId,
+      environment: this.environment,
+    });
+
+    const response = await this.transport.request<unknown>({
+      method: 'POST',
+      path: '/v1/reports',
+      body: { externalReportId: input.externalReportId, envelope },
+      idempotencyKey: input.idempotencyKey ?? defaultIdempotencyKey(input.externalReportId),
+      signal: options.signal,
+    });
+
+    const parsed = CreateReportResponseSchema.safeParse(response);
+    if (!parsed.success) {
+      throw new CrowdSourceTransportError(
+        'CrowdSource accepted the report but answered with a body this client does not recognise.',
+        { retryable: false, cause: parsed.error },
+      );
+    }
+    return parsed.data;
+  }
+
+  /** Reads back the receipt for a report this application delivered. */
+  async get(reportId: string, options: ReportRequestOptions = {}): Promise<ReportReceipt> {
+    const response = await this.transport.request<unknown>({
+      method: 'GET',
+      path: `/v1/reports/${encodeURIComponent(reportId)}`,
+      signal: options.signal,
+    });
+
+    const parsed = ReportReceiptSchema.safeParse(response);
+    if (!parsed.success) {
+      throw new CrowdSourceTransportError(
+        'CrowdSource answered with a report receipt this client does not recognise.',
+        { retryable: false, cause: parsed.error },
+      );
+    }
+    return parsed.data;
+  }
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,183 @@
+/**
+ * Fixtures.
+ *
+ * Every builder below runs its result through the published contract before
+ * returning it. A fixture that does not validate is a failing test, not
+ * something to loosen — it is how an integrator finds out a contract moved, and
+ * it is the only mechanism that stops this package from teaching a shape
+ * CrowdSource will refuse.
+ *
+ * Everything here is synthetic. No real reported material, no real evidence, no
+ * real reviewer or reporter identity ever ships in a test package: §13.5
+ * minimises what exists at all, and a fixture file is forever.
+ */
+
+import {
+  CASE_ENVELOPE_SCHEMA_VERSION,
+  CaseEnvelopeSchema,
+  DecisionSchema,
+  KnownWebhookEventSchema,
+  UNIVERSAL_TAXONOMY_VERSION,
+  type CaseEnvelope,
+  type Decision,
+  type KnownWebhookEvent,
+  type TaxonomyCode,
+} from '@crowdsource.you/contracts';
+import { createHash } from 'node:crypto';
+
+/** Deterministic, so a fixture used twice produces the same bytes. */
+function digestOf(value: unknown): string {
+  return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}
+
+export interface CaseEnvelopeFixtureOptions {
+  readonly applicationId?: string;
+  readonly externalReportId?: string;
+  readonly externalSubjectId?: string;
+  readonly text?: string;
+  readonly allegations?: readonly TaxonomyCode[];
+  /** An `oxy_user` binding carries a proof; §11.14 admits no effect without one. */
+  readonly authorOxyUserId?: string;
+  readonly allowCommunityReview?: boolean;
+}
+
+/**
+ * A minimal valid Case Envelope: one text resource, one allegation, one author.
+ *
+ * Deliberately the SMALLEST thing the contract accepts rather than a showcase of
+ * every field. A fixture that exercises everything hides which field a test
+ * actually depends on, and every optional field it carries is one more thing a
+ * contract change can break for a reason unrelated to the test.
+ */
+export function caseEnvelopeFixture(options: CaseEnvelopeFixtureOptions = {}): CaseEnvelope {
+  const text = options.text ?? 'Synthetic reported text for an integration test.';
+  const authorOxyUserId = options.authorOxyUserId ?? 'oxy_test_author';
+
+  return CaseEnvelopeSchema.parse({
+    schemaVersion: CASE_ENVELOPE_SCHEMA_VERSION,
+    applicationId: options.applicationId ?? 'app_test',
+    externalReportId: options.externalReportId ?? 'report_test_1',
+    source: { environment: 'sandbox', submittedAt: '2026-07-29T00:00:00.000Z' },
+    subject: {
+      externalId: options.externalSubjectId ?? 'post_test_1',
+      type: 'social.post',
+      primaryResourceId: 'res_subject',
+    },
+    principalBindings: [
+      {
+        principalRef: 'p_author',
+        type: 'oxy_user',
+        externalPrincipalId: authorOxyUserId,
+        bindingProofId: authorOxyUserId,
+      },
+    ],
+    resources: [
+      {
+        id: 'res_subject',
+        type: 'text',
+        role: 'subject',
+        language: 'en',
+        data: { text },
+        sha256: digestOf({ type: 'text', data: { text } }),
+        authorPrincipalRef: 'p_author',
+      },
+    ],
+    relations: [],
+    allegations: (options.allegations ?? ['harassment.targeted_abuse']).map((code) => ({ code })),
+    policy: { policySetId: 'crowdsource.baseline', version: '2026.07' },
+    privacy: {
+      retentionDays: 30,
+      allowCommunityReview: options.allowCommunityReview ?? true,
+    },
+  });
+}
+
+export interface DecisionFixtureOptions {
+  readonly id?: string;
+  readonly caseId?: string;
+  readonly revision?: number;
+  readonly outcome?: Decision['outcome'];
+  readonly status?: Decision['status'];
+  readonly findingCode?: TaxonomyCode;
+  readonly supersedesDecisionId?: string;
+}
+
+/**
+ * A published decision (Appendix B).
+ *
+ * The jury arithmetic is real, not decorative: `agreement` must equal
+ * `winningVotes / decisiveVotes` or the contract refuses the document. That
+ * check is the auditable trace of "one qualified person, one vote", so a fixture
+ * that faked it would teach a shape the service will never emit.
+ */
+export function decisionFixture(options: DecisionFixtureOptions = {}): Decision {
+  const outcome = options.outcome ?? 'violation';
+  const revision = options.revision ?? 1;
+
+  return DecisionSchema.parse({
+    id: options.id ?? 'dec_test_1',
+    caseId: options.caseId ?? 'case_test_1',
+    revision,
+    status: options.status ?? 'final',
+    outcome,
+    contextSufficiency: 'sufficient',
+    confidence: 1,
+    findings:
+      outcome === 'violation'
+        ? [
+            {
+              code: options.findingCode ?? 'harassment.targeted_abuse',
+              resourceIds: ['res_subject'],
+              severity: 'medium',
+              scope: 'application_local',
+              attribution: 'author',
+            },
+          ]
+        : [],
+    recommendedActions:
+      outcome === 'violation'
+        ? [{ action: 'remove_or_restrict', targetResourceIds: ['res_subject'] }]
+        : [{ action: 'no_action' }],
+    jury: {
+      size: 3,
+      decisiveVotes: 3,
+      winningVotes: 3,
+      agreement: 1,
+      specialistPresent: false,
+    },
+    policyVersions: {
+      taxonomy: UNIVERSAL_TAXONOMY_VERSION,
+      application: '2026.07',
+      oxyConduct: '2026.07',
+    },
+    ...(options.supersedesDecisionId === undefined
+      ? {}
+      : { supersedesDecisionId: options.supersedesDecisionId }),
+    publishedAt: '2026-07-29T12:00:00.000Z',
+  });
+}
+
+export interface WebhookEventFixtureOptions {
+  readonly id?: string;
+  readonly organizationId?: string;
+  readonly applicationId?: string;
+  readonly createdAt?: string;
+  readonly caseId?: string;
+  readonly decision?: Decision;
+}
+
+/** A `case.decided` delivery (§10.7) — the one event §10.7 specifies in full. */
+export function caseDecidedEventFixture(
+  options: WebhookEventFixtureOptions = {},
+): KnownWebhookEvent {
+  const decision = options.decision ?? decisionFixture({ caseId: options.caseId });
+
+  return KnownWebhookEventSchema.parse({
+    id: options.id ?? 'evt_test_1',
+    type: 'case.decided',
+    createdAt: options.createdAt ?? '2026-07-29T12:00:00.000Z',
+    organizationId: options.organizationId ?? 'org_test',
+    applicationId: options.applicationId ?? 'app_test',
+    data: { caseId: options.caseId ?? decision.caseId, decision },
+  });
+}

package/src/testing/index.ts

@@ -0,0 +1,57 @@
+/**
+ * `@crowdsource.you/core/testing` — integrate against CrowdSource before a jury
+ * exists.
+ *
+ * ```ts
+ * import { createCrowdSourceSandbox } from '@crowdsource.you/core/testing';
+ * import { CrowdSource } from '@crowdsource.you/core';
+ *
+ * const sandbox = createCrowdSourceSandbox();
+ * const crowdsource = new CrowdSource({
+ *   serviceKey: sandbox.serviceKey,
+ *   baseUrl: sandbox.baseUrl,
+ *   fetch: sandbox.fetch,
+ * });
+ *
+ * const { caseId } = await crowdsource.reports.create({ ... });
+ * const decision = sandbox.decide(caseId, { outcome: 'violation' });
+ * await sandbox.deliver('http://localhost:3000/webhooks/crowdsource', sandbox.eventFor(decision));
+ * ```
+ *
+ * The report goes through the real client, the sandbox applies the real rules
+ * (tenant from the credential, idempotency, 409 on a changed body, one case per
+ * reported version), and the webhook that comes back is genuinely signed — so
+ * the receiver being tested is the receiver that will run in production.
+ *
+ * The simulator can also deliver a stale, forged or tampered event on purpose.
+ * Asserting that a receiver REFUSES those is the half of a webhook test that
+ * actually proves something.
+ */
+
+export {
+  caseDecidedEventFixture,
+  caseEnvelopeFixture,
+  decisionFixture,
+} from './fixtures.js';
+export type {
+  CaseEnvelopeFixtureOptions,
+  DecisionFixtureOptions,
+  WebhookEventFixtureOptions,
+} from './fixtures.js';
+
+export { CrowdSourceSandbox, createCrowdSourceSandbox } from './sandbox.js';
+export type {
+  CrowdSourceSandboxOptions,
+  SandboxCase,
+  SandboxDecisionInput,
+  SandboxReport,
+} from './sandbox.js';
+
+export { WebhookSimulator, signWebhookDelivery } from './webhook-simulator.js';
+export type {
+  SignWebhookInput,
+  SignedWebhookDelivery,
+  WebhookDeliveryOverrides,
+  WebhookDeliveryResult,
+  WebhookSimulatorOptions,
+} from './webhook-simulator.js';