@oxyhq/crowdsource-contracts 0.1.0

package/dist/webhooks.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Outbound webhooks (§10.6–§10.9) and the signature contract (§10.8).
+ *
+ * §10.11 asks for two behaviours that pull in opposite directions: unknown
+ * EVENTS must be ignored safely, and unknown FIELDS must not break clients.
+ * This module gives each its own schema rather than compromising on one.
+ *
+ *   * `WebhookEventEnvelopeSchema` validates only what every event has —
+ *     identity, type, timing, tenant — and leaves `data` opaque. A receiver
+ *     verifies the signature, records the event id for idempotency, and ignores
+ *     what it does not recognise, without a schema update ever being the reason
+ *     a delivery fails.
+ *   * `KnownWebhookEventSchema` is the discriminated union of the eight events
+ *     §10.6 defines, for the branch that actually handles one.
+ *
+ * Everything here is `.loose()`. These payloads travel from CrowdSource to a
+ * tenant, so an unknown field is a newer server, not an attack; stripping it
+ * would silently discard data from a receiver that persists `event.data` for
+ * later processing — which is precisely what §10.8's "respond 2xx quickly and
+ * queue the processing" tells receivers to do.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_RETRY_SCHEDULE_SECONDS = exports.WebhookSignatureHeaderSchema = exports.WebhookTimestampHeaderSchema = exports.WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_VERSION = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_ID_HEADER = exports.KnownWebhookEventSchema = exports.WebhookEventEnvelopeSchema = exports.AnyWebhookEventTypeSchema = exports.WebhookEventTypeSchema = exports.WEBHOOK_EVENT_TYPES = void 0;
+exports.buildWebhookSignedPayload = buildWebhookSignedPayload;
+const zod_1 = require("zod");
+const case_envelope_1 = require("./case-envelope");
+const decisions_1 = require("./decisions");
+const primitives_1 = require("./primitives");
+/** §10.6. */
+exports.WEBHOOK_EVENT_TYPES = [
+    'report.received',
+    'case.created',
+    'case.escalated',
+    'case.decided',
+    'decision.corrected',
+    'appeal.created',
+    'appeal.decided',
+    'case.closed',
+];
+exports.WebhookEventTypeSchema = zod_1.z.enum(exports.WEBHOOK_EVENT_TYPES);
+/**
+ * Any event type, including ones this version of the contract does not know.
+ *
+ * Shape-checked but not enumerated, so that "unknown events must be ignored
+ * safely" is something a receiver can DO rather than something it is told about
+ * after its parse has already thrown.
+ */
+exports.AnyWebhookEventTypeSchema = zod_1.z
+    .string()
+    .min(3)
+    .max(64)
+    .regex(/^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/, 'must be a dotted lowercase event type');
+const webhookEnvelopeShape = {
+    id: primitives_1.IdentifierSchema,
+    createdAt: primitives_1.TimestampSchema,
+    organizationId: primitives_1.IdentifierSchema,
+    applicationId: primitives_1.IdentifierSchema,
+};
+/**
+ * The envelope every delivery shares (§10.7), with `data` left opaque.
+ *
+ * Parse with this first. `id` is the idempotency key §10.8 requires receivers
+ * to store; `type` decides whether there is anything to do.
+ */
+exports.WebhookEventEnvelopeSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: exports.AnyWebhookEventTypeSchema,
+    data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+const ReportReceivedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('report.received'),
+    /** §10.6: "optional confirmation of receipt and merge" — §10.4's response. */
+    data: case_envelope_1.CreateReportResponseSchema,
+});
+const CaseCreatedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('case.created'),
+    data: zod_1.z.looseObject({ caseId: primitives_1.IdentifierSchema }),
+});
+const CaseEscalatedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('case.escalated'),
+    data: zod_1.z.looseObject({ caseId: primitives_1.IdentifierSchema }),
+});
+const CaseDecidedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('case.decided'),
+    data: zod_1.z.looseObject({ caseId: primitives_1.IdentifierSchema, decision: decisions_1.DecisionSchema }),
+});
+/**
+ * §10.6: "a later revision replaces the previous decision".
+ *
+ * The carried decision must therefore name what it superseded. `DecisionSchema`
+ * already requires that of any revision past the first; requiring it again here
+ * is what stops a correction from carrying revision 1.
+ */
+const DecisionCorrectedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('decision.corrected'),
+    data: zod_1.z.looseObject({
+        caseId: primitives_1.IdentifierSchema,
+        decision: decisions_1.DecisionSchema.refine((decision) => decision.supersedesDecisionId !== undefined, { message: 'a corrected decision must supersede the decision it replaces' }),
+    }),
+});
+const AppealCreatedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('appeal.created'),
+    data: zod_1.z.looseObject({ caseId: primitives_1.IdentifierSchema, appealId: primitives_1.IdentifierSchema }),
+});
+const AppealDecidedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('appeal.decided'),
+    data: zod_1.z.looseObject({
+        caseId: primitives_1.IdentifierSchema,
+        appealId: primitives_1.IdentifierSchema,
+        decision: decisions_1.DecisionSchema,
+    }),
+});
+const CaseClosedEventSchema = zod_1.z.looseObject({
+    ...webhookEnvelopeShape,
+    type: zod_1.z.literal('case.closed'),
+    data: zod_1.z.looseObject({ caseId: primitives_1.IdentifierSchema }),
+});
+/**
+ * The eight events of §10.6, discriminated on `type`.
+ *
+ * Only `case.decided` has its payload specified in the plan (§10.7). The other
+ * seven carry the case they are about and whatever identifies the object that
+ * moved; they are loose, so filling them in later is additive and needs no
+ * version bump (§10.11).
+ */
+exports.KnownWebhookEventSchema = zod_1.z.discriminatedUnion('type', [
+    ReportReceivedEventSchema,
+    CaseCreatedEventSchema,
+    CaseEscalatedEventSchema,
+    CaseDecidedEventSchema,
+    DecisionCorrectedEventSchema,
+    AppealCreatedEventSchema,
+    AppealDecidedEventSchema,
+    CaseClosedEventSchema,
+]);
+/** §10.8 headers, in their canonical casing. HTTP header names are case-insensitive; look them up accordingly. */
+exports.WEBHOOK_EVENT_ID_HEADER = 'X-CrowdSource-Event-Id';
+exports.WEBHOOK_TIMESTAMP_HEADER = 'X-CrowdSource-Timestamp';
+exports.WEBHOOK_SIGNATURE_HEADER = 'X-CrowdSource-Signature';
+/** The signature scheme prefix, as in `v1=<hex>`. */
+exports.WEBHOOK_SIGNATURE_VERSION = 'v1';
+/** §10.8: reject timestamps more than five minutes away from now. */
+exports.WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = 300;
+/** Unix seconds, as the header carries them. */
+exports.WebhookTimestampHeaderSchema = zod_1.z
+    .string()
+    .regex(/^[0-9]{1,15}$/, 'must be unix seconds');
+/** `v1=<64 lowercase hex>` — HMAC-SHA256 of the signed payload. */
+exports.WebhookSignatureHeaderSchema = zod_1.z
+    .string()
+    .regex(/^v1=[0-9a-f]{64}$/, 'must be "v1=" followed by 64 lowercase hex characters');
+/**
+ * The exact bytes both sides sign: `timestamp + "." + rawBody` (§10.8).
+ *
+ * This lives in the contract, not in the signer or the verifier, because a
+ * disagreement between those two about what gets signed is invisible until
+ * every delivery starts failing — or, far worse, until a signature validates
+ * over bytes that are not the ones the receiver goes on to parse. There is no
+ * cryptography here and no transport; the HMAC belongs to the backend's signer
+ * and the SDK's middleware.
+ *
+ * `timestamp` is the header value VERBATIM. Re-deriving it from a parsed number
+ * is the mistake this signature exists to catch, and the receiver must verify
+ * over exactly what arrived.
+ */
+function buildWebhookSignedPayload(timestamp, rawBody) {
+    return `${timestamp}.${rawBody}`;
+}
+/**
+ * §10.9's backoff, in seconds after the initial attempt.
+ *
+ * Published behaviour a tenant plans around, so it belongs to the contract
+ * rather than to the delivery worker. After the last one the delivery is
+ * `dead_letter`, the tenant is alerted, and replay is manual.
+ */
+exports.WEBHOOK_RETRY_SCHEDULE_SECONDS = Object.freeze([
+    30,
+    120,
+    900,
+    3600,
+    21600,
+    86400,
+]);
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@oxyhq/crowdsource-contracts",
+  "version": "0.1.0",
+  "description": "Versioned CrowdSource contracts: case envelope, resources, taxonomy, policies, reviews, decisions, webhooks and reputation events",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters && tsc -p tsconfig.test.json",
+    "test": "node ../../node_modules/vitest/vitest.mjs run",
+    "test:watch": "node ../../node_modules/vitest/vitest.mjs",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "crowdsource",
+    "moderation",
+    "contracts",
+    "typescript"
+  ],
+  "author": "OxyHQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OxyHQ/CrowdSource",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/OxyHQ/CrowdSource/tree/main/packages/contracts#readme",
+  "bugs": "https://github.com/OxyHQ/CrowdSource/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "!src/**/__tests__/**"
+  ]
+}

package/src/case-envelope.ts

@@ -0,0 +1,433 @@
+/**
+ * The Case Envelope (§5.1) — the universal content contract.
+ *
+ * §5 opens by naming the mistake this contract exists to avoid: designing
+ * moderation around `post`, `comment`, `room` or `product`. Nothing below knows
+ * what a post is. An envelope is resources, relations, pseudonymous principals,
+ * allegations, a policy reference and privacy terms; what the material happens
+ * to be called in the application that sent it lives in `subject.type`, which
+ * is a namespaced label, not a branch in this file.
+ *
+ * Two rules govern the whole module.
+ *
+ * **Everything inbound is strict.** An unknown key on an envelope is either a
+ * typo — in which case the application believes it sent context that the jury
+ * will never see — or a field somebody hopes will reach the reviewer's screen.
+ * Both are rejected loudly. §10.11's "unknown fields must not break clients"
+ * governs what CrowdSource SENDS; see `decisions.ts` and `webhooks.ts` for the
+ * other half of that rule.
+ *
+ * **References resolve inside the envelope.** §5.5 requires the backend to
+ * check that every referenced id exists. That check lives here, in the schema,
+ * because it is a property of the document and nothing downstream can restate
+ * it as reliably. It is extended past `relations` to every in-envelope
+ * reference — `subject.primaryResourceId`, `allegation.resourceIds`,
+ * `authorPrincipalRef`, conversation members, listing media and seller, profile
+ * avatar — since a dangling id is the same defect wherever it appears.
+ */
+
+import { z } from 'zod';
+
+import {
+  CONTRACT_LIMITS,
+  ExternalIdSchema,
+  HttpUrlSchema,
+  IdentifierSchema,
+  MetadataBagSchema,
+  TimestampSchema,
+} from './primitives';
+import { CasePolicyRefSchema } from './policies';
+import {
+  PRINCIPAL_TARGETED_RELATION_TYPES,
+  PrincipalRefSchema,
+  RelationSchema,
+  ResourceIdSchema,
+  ResourceSchema,
+} from './resources';
+import { SensitivityHintSchema, TaxonomyCodeSchema } from './taxonomy';
+
+/**
+ * The contract version carried inside the payload.
+ *
+ * §10.11 keeps this separate from the `/v1` route version on purpose: the HTTP
+ * surface and the document shape evolve at different speeds, and an additive
+ * change to either bumps neither.
+ */
+export const CASE_ENVELOPE_SCHEMA_VERSION = 'crowdsource.case.v1';
+
+export const CaseEnvelopeSchemaVersionSchema = z.literal(CASE_ENVELOPE_SCHEMA_VERSION);
+
+/** §5.4 namespaced subject types. */
+export const STANDARD_SUBJECT_TYPES = [
+  'social.post',
+  'social.comment',
+  'chat.message',
+  'chat.conversation',
+  'identity.profile',
+  'commerce.listing',
+  'commerce.review',
+  'forum.thread',
+  'video.live_segment',
+  'document.file',
+  'gaming.username',
+] as const;
+
+/**
+ * A subject type: one of §5.4's standard types, or an application's own
+ * `custom.<organization>.<object_type>`.
+ *
+ * The custom branch is a pattern rather than an open string so a tenant's
+ * private vocabulary is always visibly namespaced and can never collide with a
+ * standard type or be mistaken for one.
+ */
+export const SubjectTypeSchema = z.union([
+  z.enum(STANDARD_SUBJECT_TYPES),
+  z
+    .string()
+    .max(CONTRACT_LIMITS.IDENTIFIER_MAX_LENGTH)
+    .regex(
+      /^custom\.[a-z0-9][a-z0-9_-]*\.[a-z0-9][a-z0-9_-]*$/,
+      'a custom subject type must be "custom.<organization>.<object_type>"',
+    ),
+]);
+export type SubjectType = z.infer<typeof SubjectTypeSchema>;
+
+/** §5.1 / Appendix A `subject`. */
+export const CaseSubjectSchema = z.strictObject({
+  externalId: ExternalIdSchema,
+  type: SubjectTypeSchema,
+  primaryResourceId: ResourceIdSchema,
+  /** Where the application's own users see the object. Never fetched by a jury. */
+  permalink: HttpUrlSchema.optional(),
+});
+export type CaseSubject = z.infer<typeof CaseSubjectSchema>;
+
+/**
+ * §3 principal kinds.
+ *
+ * The plan defines a principal in prose — "an Oxy user, a local user, an
+ * organization, a bot or a federated actor" — and only ever writes `oxy_user`
+ * in an example. These are those five in the plan's own order; the tokens are
+ * this contract's, the concepts are the plan's.
+ */
+export const PRINCIPAL_TYPES = [
+  'oxy_user',
+  'local_user',
+  'organization',
+  'bot',
+  'federated_actor',
+] as const;
+export const PrincipalTypeSchema = z.enum(PRINCIPAL_TYPES);
+export type PrincipalType = z.infer<typeof PrincipalTypeSchema>;
+
+/**
+ * §5.1 `principalBindings` — proof that a pseudonymous ref corresponds to a
+ * verifiable identity.
+ *
+ * `bindingProofId` is REQUIRED for `oxy_user` and optional for every other
+ * principal type. That is the "no binding proof, no Oxy Trust effect" invariant
+ * made structural at the earliest possible point: an Oxy identity asserted
+ * without a proof cannot be expressed. The other four types can never move Oxy
+ * reputation anyway — they have no Oxy identity to move — and requiring a proof
+ * from them would lock out every tenant whose users are not Oxy users, which is
+ * the multi-tenant case this whole product exists for.
+ */
+export const PrincipalBindingSchema = z
+  .strictObject({
+    principalRef: PrincipalRefSchema,
+    type: PrincipalTypeSchema,
+    /** The application's own id for the actor. Pseudonymous to the jury. */
+    externalPrincipalId: ExternalIdSchema.optional(),
+    bindingProofId: IdentifierSchema.optional(),
+    boundAt: TimestampSchema.optional(),
+  })
+  .superRefine((binding, ctx) => {
+    if (binding.type === 'oxy_user' && binding.bindingProofId === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['bindingProofId'],
+        message: 'an oxy_user binding must carry a bindingProofId',
+      });
+    }
+  });
+export type PrincipalBinding = z.infer<typeof PrincipalBindingSchema>;
+
+/**
+ * §5.1 `allegations` — what the reporter claims, not what is true.
+ *
+ * §9.1 requires the jury to see this as an unverified allegation, and §6.2
+ * shows the allegation and the finding diverging as the normal case. Only
+ * `code` is required: §5.8's example carries nothing else.
+ */
+export const AllegationSchema = z.strictObject({
+  code: TaxonomyCodeSchema,
+  resourceIds: z
+    .array(ResourceIdSchema)
+    .max(CONTRACT_LIMITS.RESOURCE_REFS_PER_FINDING_MAX)
+    .optional(),
+  reporterPrincipalRef: PrincipalRefSchema.optional(),
+  details: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+});
+export type Allegation = z.infer<typeof AllegationSchema>;
+
+/**
+ * The environment the report came from, as the APPLICATION sees it.
+ *
+ * `staging` is deliberately absent. The plan's §12.4 three-environment model is
+ * not what this ecosystem runs — CrowdSource has one deployment, and
+ * tenant-facing sandboxing is an application-trust state inside it. A report
+ * from a tenant's own pre-production is a sandbox report or it is a real one.
+ */
+export const SOURCE_ENVIRONMENTS = ['production', 'sandbox'] as const;
+export const SourceEnvironmentSchema = z.enum(SOURCE_ENVIRONMENTS);
+
+/** Appendix A `source`. */
+export const CaseSourceSchema = z.strictObject({
+  environment: SourceEnvironmentSchema,
+  submittedAt: TimestampSchema,
+});
+export type CaseSource = z.infer<typeof CaseSourceSchema>;
+
+/** §5.1 / Appendix A `privacy`. */
+export const CasePrivacySchema = z.strictObject({
+  /** §13.6 defaults to 30 days after a final decision, configurable by policy. */
+  retentionDays: z.number().int().positive().max(CONTRACT_LIMITS.RETENTION_DAYS_MAX),
+  /**
+   * Whether a community jury may see this at all. `false` routes the case to a
+   * specialist pool (§7.5); it is not a preference the triage may override
+   * upwards.
+   */
+  allowCommunityReview: z.boolean(),
+  containsPersonalData: z.boolean().optional(),
+  sensitivityHint: SensitivityHintSchema.optional(),
+});
+export type CasePrivacy = z.infer<typeof CasePrivacySchema>;
+
+/**
+ * §5.1 / Appendix A `urgency` — an input to triage, never to a verdict.
+ *
+ * `hint` stays an open lowercase token for the same reason as
+ * `sensitivityHint`: the plan names exactly one value (`normal`) and §7.4 makes
+ * clear the authoritative priority is computed server-side from several
+ * signals, of which this is one. Closing the list is a product decision that
+ * has not been made.
+ */
+export const CaseUrgencySchema = z.strictObject({
+  hint: z
+    .string()
+    .min(1)
+    .max(40)
+    .regex(/^[a-z][a-z0-9_]*$/, 'must be a lowercase token'),
+  /** How many people the material reached, as the application counts it. */
+  reach: z.number().int().nonnegative().optional(),
+  activeDistribution: z.boolean().optional(),
+});
+export type CaseUrgency = z.infer<typeof CaseUrgencySchema>;
+
+const caseEnvelopeShape = {
+  schemaVersion: CaseEnvelopeSchemaVersionSchema,
+  /**
+   * An assertion by the caller, never the source of tenancy.
+   *
+   * `applicationId` comes from the credential (Appendix F). This field exists
+   * so a mismatch can be DETECTED — the ingress route compares it to the
+   * credential-derived id and rejects a disagreement rather than trusting
+   * either side silently. No schema can enforce that; it is stated here so the
+   * rule travels with the field it constrains.
+   */
+  applicationId: IdentifierSchema,
+  externalReportId: ExternalIdSchema,
+  source: CaseSourceSchema.optional(),
+  subject: CaseSubjectSchema,
+  principalBindings: z
+    .array(PrincipalBindingSchema)
+    .max(CONTRACT_LIMITS.PRINCIPAL_BINDINGS_PER_ENVELOPE_MAX),
+  resources: z.array(ResourceSchema).min(1).max(CONTRACT_LIMITS.RESOURCES_PER_ENVELOPE_MAX),
+  relations: z.array(RelationSchema).max(CONTRACT_LIMITS.RELATIONS_PER_ENVELOPE_MAX),
+  allegations: z.array(AllegationSchema).min(1).max(CONTRACT_LIMITS.ALLEGATIONS_PER_ENVELOPE_MAX),
+  policy: CasePolicyRefSchema,
+  privacy: CasePrivacySchema,
+  urgency: CaseUrgencySchema.optional(),
+  metadata: MetadataBagSchema.optional(),
+};
+
+/**
+ * The Case Envelope.
+ *
+ * `principalBindings`, `resources`, `relations` and `allegations` are all
+ * required keys, matching §5.1's declared root structure and both worked
+ * examples; `resources` and `allegations` additionally require at least one
+ * entry, because an envelope with nothing to look at or no claim to evaluate is
+ * not a case. `source`, `urgency` and `metadata` are optional — §5.8 omits all
+ * three, Appendix A carries all three.
+ */
+export const CaseEnvelopeSchema = z
+  .strictObject(caseEnvelopeShape)
+  .superRefine((envelope, ctx) => {
+    const resourceIds = new Set<string>();
+    envelope.resources.forEach((resource, index) => {
+      if (resourceIds.has(resource.id)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['resources', index, 'id'],
+          message: `duplicate resource id "${resource.id}"`,
+        });
+      }
+      resourceIds.add(resource.id);
+    });
+
+    const principalRefs = new Set<string>();
+    envelope.principalBindings.forEach((binding, index) => {
+      if (principalRefs.has(binding.principalRef)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['principalBindings', index, 'principalRef'],
+          message: `duplicate principalRef "${binding.principalRef}"`,
+        });
+      }
+      principalRefs.add(binding.principalRef);
+    });
+
+    const requireResource = (id: string, path: (string | number)[]): void => {
+      if (!resourceIds.has(id)) {
+        ctx.addIssue({
+          code: 'custom',
+          path,
+          message: `no resource in this envelope has id "${id}"`,
+        });
+      }
+    };
+    const requirePrincipal = (ref: string, path: (string | number)[]): void => {
+      if (!principalRefs.has(ref)) {
+        ctx.addIssue({
+          code: 'custom',
+          path,
+          message: `no principal binding in this envelope has principalRef "${ref}"`,
+        });
+      }
+    };
+
+    requireResource(envelope.subject.primaryResourceId, ['subject', 'primaryResourceId']);
+    const primary = envelope.resources.find(
+      (resource) => resource.id === envelope.subject.primaryResourceId,
+    );
+    if (primary !== undefined && primary.role !== 'subject') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['subject', 'primaryResourceId'],
+        message: `the primary resource must have role "subject", not "${primary.role}"`,
+      });
+    }
+
+    envelope.resources.forEach((resource, index) => {
+      if (resource.authorPrincipalRef !== undefined) {
+        requirePrincipal(resource.authorPrincipalRef, ['resources', index, 'authorPrincipalRef']);
+      }
+      switch (resource.type) {
+        case 'profile':
+          if (resource.data.avatarRef !== undefined) {
+            requireResource(resource.data.avatarRef, ['resources', index, 'data', 'avatarRef']);
+          }
+          break;
+        case 'conversation':
+          resource.data.messageResourceIds.forEach((messageId, messageIndex) => {
+            requireResource(messageId, [
+              'resources',
+              index,
+              'data',
+              'messageResourceIds',
+              messageIndex,
+            ]);
+          });
+          break;
+        case 'listing':
+          if (resource.data.sellerRef !== undefined) {
+            requirePrincipal(resource.data.sellerRef, ['resources', index, 'data', 'sellerRef']);
+          }
+          resource.data.mediaRefs?.forEach((mediaId, mediaIndex) => {
+            requireResource(mediaId, ['resources', index, 'data', 'mediaRefs', mediaIndex]);
+          });
+          break;
+        default:
+          break;
+      }
+    });
+
+    const seenRelations = new Set<string>();
+    envelope.relations.forEach((relation, index) => {
+      requireResource(relation.from, ['relations', index, 'from']);
+      if (PRINCIPAL_TARGETED_RELATION_TYPES.some((type) => type === relation.type)) {
+        requirePrincipal(relation.to, ['relations', index, 'to']);
+      } else {
+        requireResource(relation.to, ['relations', index, 'to']);
+        if (relation.from === relation.to) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['relations', index, 'to'],
+            message: 'a resource cannot relate to itself',
+          });
+        }
+      }
+      const key = `${relation.from}${relation.type}${relation.to}`;
+      if (seenRelations.has(key)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['relations', index],
+          message: 'duplicate relation',
+        });
+      }
+      seenRelations.add(key);
+    });
+
+    envelope.allegations.forEach((allegation, index) => {
+      allegation.resourceIds?.forEach((resourceId, resourceIndex) => {
+        requireResource(resourceId, ['allegations', index, 'resourceIds', resourceIndex]);
+      });
+      if (allegation.reporterPrincipalRef !== undefined) {
+        requirePrincipal(allegation.reporterPrincipalRef, [
+          'allegations',
+          index,
+          'reporterPrincipalRef',
+        ]);
+      }
+    });
+  });
+export type CaseEnvelope = z.infer<typeof CaseEnvelopeSchema>;
+
+/** §3.2 report states. */
+export const REPORT_STATUSES = ['received', 'merged', 'invalid', 'withdrawn', 'closed'] as const;
+export const ReportStatusSchema = z.enum(REPORT_STATUSES);
+export type ReportStatus = z.infer<typeof ReportStatusSchema>;
+
+/**
+ * `POST /v1/reports` (§10.4).
+ *
+ * The request repeats `externalReportId` outside the envelope, so the two must
+ * agree — a mismatch means the idempotency key and the document disagree about
+ * which report this is, and §12.7's `application_id + external_report_id`
+ * uniqueness would then be enforced against the wrong value.
+ */
+export const CreateReportRequestSchema = z
+  .strictObject({
+    externalReportId: ExternalIdSchema,
+    envelope: CaseEnvelopeSchema,
+  })
+  .superRefine((request, ctx) => {
+    if (request.externalReportId !== request.envelope.externalReportId) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['envelope', 'externalReportId'],
+        message: 'externalReportId must match the envelope',
+      });
+    }
+  });
+export type CreateReportRequest = z.infer<typeof CreateReportRequestSchema>;
+
+/** The `202 Accepted` body of §10.4. Loose: it travels outbound (§10.11). */
+export const CreateReportResponseSchema = z.looseObject({
+  reportId: IdentifierSchema,
+  caseId: IdentifierSchema,
+  status: ReportStatusSchema,
+  merged: z.boolean(),
+});
+export type CreateReportResponse = z.infer<typeof CreateReportResponseSchema>;