@oxyhq/crowdsource-contracts 0.2.0 → 0.4.0

package/src/primitives.ts

@@ -179,6 +179,31 @@ export const LanguageTagSchema = z
  */
 export const HttpUrlSchema = z.url({ protocol: /^https?$/ }).max(2_048);
 
+/**
+ * A bare Oxy file id — the one way bytes enter a case.
+ *
+ * Evidence goes through the Oxy media chokepoint (`getFileDownloadUrl`) rather
+ * than a presigned bucket, which is the §12.3 divergence recorded in
+ * `AGENTS.md`. A file id is what that chokepoint takes, so it is what an asset
+ * carries: never a URL, never a host, never a variant. The reviewer client
+ * resolves it once through Bloom's `ImageResolver`, so nothing downstream needs
+ * to know where `cloud.oxy.so` is.
+ *
+ * Deliberately opaque, for the same reason `IdentifierSchema` is: the format
+ * belongs to Oxy, not to CrowdSource, and pinning it here would make an Oxy
+ * change look like a CrowdSource contract violation. What is pinned is that it
+ * is a bounded, non-empty token with no separators that could smuggle a path or
+ * a scheme into a resolver — `..`, `/` and `:` are all excluded by the pattern.
+ */
+export const OxyFileIdSchema = z
+  .string()
+  .min(1)
+  .max(CONTRACT_LIMITS.IDENTIFIER_MAX_LENGTH)
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9_-]*$/,
+    'must be a bare Oxy file id: letters, digits, "_" or "-", starting with a letter or digit',
+  );
+
 /** A `type/subtype` media type, without parameters. */
 export const MimeTypeSchema = z
   .string()

package/src/reputation-events.ts

@@ -36,15 +36,15 @@
 
 import { z } from 'zod';
 
-import { CONTRACT_LIMITS, IdentifierSchema, Sha256DigestSchema } from './primitives';
-import { PrincipalTypeSchema } from './case-envelope';
-import { ReputationPolicyVersionsSchema } from './policies';
+import { CONTRACT_LIMITS, IdentifierSchema, Sha256DigestSchema } from './primitives.js';
+import { PrincipalTypeSchema } from './case-envelope.js';
+import { ReputationPolicyVersionsSchema } from './policies.js';
 import {
   FindingAttributionSchema,
   ReputationEligibleFindingScopeSchema,
   SeveritySchema,
   TaxonomyCodeSchema,
-} from './taxonomy';
+} from './taxonomy.js';
 
 /**
  * §11.6 names one event type. §11.5 names four bridge operations — apply,

package/src/resources.ts

@@ -38,11 +38,12 @@ import {
   LanguageTagSchema,
   MetadataBagSchema,
   MimeTypeSchema,
+  OxyFileIdSchema,
   Sha256DigestSchema,
   TimestampSchema,
-} from './primitives';
-import { PolicyVersionSchema } from './policies';
-import { SensitivityHintSchema } from './taxonomy';
+} from './primitives.js';
+import { PolicyVersionSchema } from './policies.js';
+import { SensitivityHintSchema } from './taxonomy.js';
 
 /** A resource id, unique within one envelope (§5.2 `id`). */
 export const ResourceIdSchema = IdentifierSchema;
@@ -98,34 +99,43 @@ export type TextFormatting = z.infer<typeof TextFormattingSchema>;
 /**
  * A reference to bytes held outside the envelope (§5.2 `asset`).
  *
- * Exactly one of `uploadId` and `url` — never both, never neither. Two
- * locations for one piece of evidence means two answers to "what exactly did
- * the jury look at", and §5.6 requires the case to pin the exact version that
- * was reported. `sha256` is required for the same reason: it is what makes the
- * answer verifiable after the application has deleted the original.
+ * **`fileId` is where the bytes are. `url` is where they came from.** Those are
+ * not alternatives, and the earlier contract encoding them as "exactly one of
+ * `uploadId` or `url`" is what left an integrator with no safe way to attach an
+ * image at all: the `uploadId` branch needed a presigned upload route that was
+ * superseded by the Oxy media chokepoint before it was ever built, and the `url`
+ * branch put a URL on the reporting application's own host in front of a
+ * reviewer — breaking §9.1's branding rule and the chokepoint rule at once.
+ *
+ * So `fileId` is required and `url` is optional provenance:
+ *
+ *   * **`fileId`** — a bare Oxy file id. The application uploads the bytes
+ *     through the Oxy media chokepoint with its own Oxy credentials and passes
+ *     the id. That is why CrowdSource serves no upload route of its own.
+ *   * **`url`** — a PROVENANCE RECORD, and never a fetch target. A third-party
+ *     URL is not wrong the way a first-party one is (a federated post's image
+ *     genuinely lives elsewhere), but no reviewer client may dereference it:
+ *     fetching it would tell that host exactly when its content is under review,
+ *     which lets the reported party correlate reviewer accesses, and it would
+ *     deliver bytes live rather than the pinned ones §5.6 requires.
+ *
+ * `sha256` stays required, and requiring `fileId` alongside it costs an
+ * integrator nothing new — an application able to compute that digest already
+ * holds the bytes. What changes is that it puts bytes it already has somewhere a
+ * reviewer can read safely, instead of pointing at its own host.
  */
-export const AssetRefSchema = z
-  .strictObject({
-    uploadId: IdentifierSchema.optional(),
-    url: HttpUrlSchema.optional(),
-    mimeType: MimeTypeSchema,
-    sha256: Sha256DigestSchema,
-    sizeBytes: z.number().int().positive().optional(),
-    width: z.number().int().positive().optional(),
-    height: z.number().int().positive().optional(),
-    durationSeconds: z.number().positive().optional(),
-  })
-  .superRefine((asset, ctx) => {
-    const hasUpload = asset.uploadId !== undefined;
-    const hasUrl = asset.url !== undefined;
-    if (hasUpload === hasUrl) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['uploadId'],
-        message: 'an asset must reference exactly one of uploadId or url',
-      });
-    }
-  });
+export const AssetRefSchema = z.strictObject({
+  /** Bare Oxy file id. The only source of the bytes a jury sees. */
+  fileId: OxyFileIdSchema,
+  /** Where the material was found. Recorded, never fetched — see above. */
+  url: HttpUrlSchema.optional(),
+  mimeType: MimeTypeSchema,
+  sha256: Sha256DigestSchema,
+  sizeBytes: z.number().int().positive().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  durationSeconds: z.number().positive().optional(),
+});
 export type AssetRef = z.infer<typeof AssetRefSchema>;
 
 const mediaTypeMismatch = (
@@ -166,13 +176,46 @@ const resourceBaseShape = {
 const inlineResourceShape = { ...resourceBaseShape, sha256: Sha256DigestSchema };
 const assetResourceShape = { ...resourceBaseShape, sha256: Sha256DigestSchema.optional() };
 
+/**
+ * The `data` of each resource type, named.
+ *
+ * Extracted so the reviewer surface (`reviewer-surface.ts`) can build its own
+ * resource union — same content, no `sha256`, a media handle instead of an asset
+ * locator — out of THESE schemas rather than restating twelve content shapes.
+ * A second copy would drift, and the direction it would drift in is a jury shown
+ * less than the application sent.
+ */
+export const TextResourceDataSchema = z.strictObject({
+  text: z.string().min(1).max(CONTRACT_LIMITS.TEXT_RESOURCE_MAX_LENGTH),
+  formatting: TextFormattingSchema.optional(),
+});
+
 const TextResourceSchema = z.strictObject({
   ...inlineResourceShape,
   type: z.literal('text'),
-  data: z.strictObject({
-    text: z.string().min(1).max(CONTRACT_LIMITS.TEXT_RESOURCE_MAX_LENGTH),
-    formatting: TextFormattingSchema.optional(),
-  }),
+  data: TextResourceDataSchema,
+});
+
+export const VideoResourceDataSchema = z.strictObject({
+  timeRange: z
+    .strictObject({
+      startSeconds: z.number().nonnegative(),
+      endSeconds: z.number().positive(),
+    })
+    .refine((range) => range.endSeconds > range.startSeconds, {
+      message: 'endSeconds must be greater than startSeconds',
+      path: ['endSeconds'],
+    })
+    .optional(),
+});
+
+export const AudioResourceDataSchema = z.strictObject({
+  transcript: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
+});
+
+export const DocumentResourceDataSchema = z.strictObject({
+  title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+  extractedText: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
 });
 
 const ImageResourceSchema = z
@@ -188,20 +231,7 @@ const VideoResourceSchema = z
     ...assetResourceShape,
     type: z.literal('video'),
     asset: AssetRefSchema,
-    data: z
-      .strictObject({
-        timeRange: z
-          .strictObject({
-            startSeconds: z.number().nonnegative(),
-            endSeconds: z.number().positive(),
-          })
-          .refine((range) => range.endSeconds > range.startSeconds, {
-            message: 'endSeconds must be greater than startSeconds',
-            path: ['endSeconds'],
-          })
-          .optional(),
-      })
-      .optional(),
+    data: VideoResourceDataSchema.optional(),
   })
   .superRefine((resource, ctx) => {
     mediaTypeMismatch(ctx, resource.asset.mimeType, ['video/']);
@@ -219,11 +249,7 @@ const AudioResourceSchema = z
     ...assetResourceShape,
     type: z.literal('audio'),
     asset: AssetRefSchema,
-    data: z
-      .strictObject({
-        transcript: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
-      })
-      .optional(),
+    data: AudioResourceDataSchema.optional(),
   })
   .superRefine((resource, ctx) => {
     mediaTypeMismatch(ctx, resource.asset.mimeType, ['audio/']);
@@ -241,34 +267,30 @@ const DocumentResourceSchema = z
     ...assetResourceShape,
     type: z.literal('document'),
     asset: AssetRefSchema,
-    data: z.strictObject({
-      title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
-      extractedText: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
-    }),
+    data: DocumentResourceDataSchema,
   })
   .superRefine((resource, ctx) =>
     mediaTypeMismatch(ctx, resource.asset.mimeType, ['application/', 'text/']),
   );
 
+export const LinkResourceDataSchema = z.strictObject({
+  url: HttpUrlSchema,
+  title: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+  resolvedHost: z
+    .string()
+    .max(253)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/, 'must be a hostname')
+    .optional(),
+  snapshot: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
+});
+
 const LinkResourceSchema = z.strictObject({
   ...inlineResourceShape,
   type: z.literal('link'),
-  data: z.strictObject({
-    url: HttpUrlSchema,
-    title: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
-    resolvedHost: z
-      .string()
-      .max(253)
-      .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/, 'must be a hostname')
-      .optional(),
-    snapshot: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
-  }),
+  data: LinkResourceDataSchema,
 });
 
-const ProfileResourceSchema = z.strictObject({
-  ...inlineResourceShape,
-  type: z.literal('profile'),
-  data: z.strictObject({
+export const ProfileResourceDataSchema = z.strictObject({
     /**
      * Every field is optional on purpose. A federated or unresolved actor
      * routinely has no display name, and requiring one would push applications
@@ -279,41 +301,50 @@ const ProfileResourceSchema = z.strictObject({
     bio: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
     /** An `image` resource in the same envelope. */
     avatarRef: ResourceIdSchema.optional(),
-    claims: MetadataBagSchema.optional(),
-  }),
+  claims: MetadataBagSchema.optional(),
 });
 
-const ConversationResourceSchema = z.strictObject({
+const ProfileResourceSchema = z.strictObject({
   ...inlineResourceShape,
-  type: z.literal('conversation'),
-  data: z.strictObject({
+  type: z.literal('profile'),
+  data: ProfileResourceDataSchema,
+});
+
+export const ConversationResourceDataSchema = z.strictObject({
     /**
      * Ordered (§5.3). §13.5 asks for five messages around the incident rather
      * than the whole thread, which is why this is a bounded list of ids the
      * application chose, not a pointer to a conversation.
      */
-    messageResourceIds: z
-      .array(ResourceIdSchema)
-      .min(1)
-      .max(CONTRACT_LIMITS.CONVERSATION_MESSAGES_MAX),
-  }),
+  messageResourceIds: z
+    .array(ResourceIdSchema)
+    .min(1)
+    .max(CONTRACT_LIMITS.CONVERSATION_MESSAGES_MAX),
+});
+
+const ConversationResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('conversation'),
+  data: ConversationResourceDataSchema,
+});
+
+export const ListingResourceDataSchema = z.strictObject({
+  title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+  description: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+  price: z.number().finite().nonnegative().optional(),
+  currency: z
+    .string()
+    .regex(/^[A-Z]{3}$/, 'must be an ISO 4217 alphabetic code')
+    .optional(),
+  sellerRef: PrincipalRefSchema.optional(),
+  mediaRefs: z.array(ResourceIdSchema).max(CONTRACT_LIMITS.LISTING_MEDIA_REFS_MAX).optional(),
 });
 
 const ListingResourceSchema = z
   .strictObject({
     ...inlineResourceShape,
     type: z.literal('listing'),
-    data: z.strictObject({
-      title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
-      description: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
-      price: z.number().finite().nonnegative().optional(),
-      currency: z
-        .string()
-        .regex(/^[A-Z]{3}$/, 'must be an ISO 4217 alphabetic code')
-        .optional(),
-      sellerRef: PrincipalRefSchema.optional(),
-      mediaRefs: z.array(ResourceIdSchema).max(CONTRACT_LIMITS.LISTING_MEDIA_REFS_MAX).optional(),
-    }),
+    data: ListingResourceDataSchema,
   })
   .superRefine((resource, ctx) => {
     const hasPrice = resource.data.price !== undefined;
@@ -333,15 +364,17 @@ const COARSE_COORDINATE_DECIMALS = 2;
 const isCoarse = (value: number): boolean =>
   Number.isInteger(value * 10 ** COARSE_COORDINATE_DECIMALS);
 
+export const LocationResourceDataSchema = z.strictObject({
+  label: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+  latitude: z.number().min(-90).max(90).optional(),
+  longitude: z.number().min(-180).max(180).optional(),
+});
+
 const LocationResourceSchema = z
   .strictObject({
     ...inlineResourceShape,
     type: z.literal('location'),
-    data: z.strictObject({
-      label: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
-      latitude: z.number().min(-90).max(90).optional(),
-      longitude: z.number().min(-180).max(180).optional(),
-    }),
+    data: LocationResourceDataSchema,
   })
   .superRefine((resource, ctx) => {
     const { label, latitude, longitude } = resource.data;
@@ -381,12 +414,15 @@ const LocationResourceSchema = z
     }
   });
 
+export const MetadataResourceDataSchema = MetadataBagSchema.refine(
+  (bag) => Object.keys(bag).length >= 1,
+  { message: 'a metadata resource must carry at least one field' },
+);
+
 const MetadataResourceSchema = z.strictObject({
   ...inlineResourceShape,
   type: z.literal('metadata'),
-  data: MetadataBagSchema.refine((bag) => Object.keys(bag).length >= 1, {
-    message: 'a metadata resource must carry at least one field',
-  }),
+  data: MetadataResourceDataSchema,
 });
 
 const CustomResourceSchema = z.strictObject({