@crowdsource.you/core 1.2.0

package/src/credential.ts

@@ -0,0 +1,100 @@
+/**
+ * The service key, and the only place `applicationId` may come from.
+ *
+ * Appendix F: "`applicationId` comes from the credential, never from the request
+ * body." The backend already honours that — it derives the tenant from the
+ * presented token and 403s an envelope naming a different application. But the
+ * Case Envelope contract still REQUIRES `applicationId` on the wire, so a client
+ * has to put one there, and the question this module answers is where it gets it
+ * from without ever asking the integrator.
+ *
+ * The answer is that it comes out of the credential, literally. CrowdSource
+ * issues three values together (`provisioning.service.ts`
+ * `IssuedCredential`): the application the credential belongs to, the credential
+ * id, and the secret. Joined into ONE opaque string, they are a single
+ * environment variable an integrator pastes and never reads — and the
+ * `applicationId` in an envelope is then a value the client READ OFF THE
+ * CREDENTIAL, not a parameter anyone can pass. There is no `applicationId`
+ * option on the client, none on any method, and none an envelope input can
+ * carry; supplying one is not "discouraged", it is unexpressible.
+ *
+ * `:` is the separator because the contract's identifier grammar excludes it and
+ * credential secrets are base64url, so the split is unambiguous for every value
+ * CrowdSource can issue. A `.` separator would not be: `IdentifierSchema` allows
+ * dots inside an id.
+ *
+ * NOTE FOR THE CONSOLE: `issueApplicationCredential` returns the three values
+ * separately and the bearer token as `<credentialId>.<secret>`. Whatever surface
+ * shows an integrator their key must show `formatServiceKey(issued)` — the
+ * composite below — or the integrator has two values to configure instead of
+ * one, and the client has no way to know its own application.
+ */
+
+import { IdentifierSchema } from '@crowdsource.you/contracts';
+
+import { CrowdSourceConfigurationError } from './errors.js';
+
+const SERVICE_KEY_SEPARATOR = ':';
+
+/** The credential CrowdSource issues, parsed. */
+export interface ServiceCredential {
+  /** The application this credential belongs to. The tenant, and its only source. */
+  readonly applicationId: string;
+  readonly credentialId: string;
+  /**
+   * The bearer token the API authenticates — `<credentialId>.<secret>`, exactly
+   * what `credential.service.ts` parses. The secret is never held on its own,
+   * so nothing in this client can log or serialise it by touching a field.
+   */
+  readonly bearerToken: string;
+}
+
+/** The three values `issueApplicationCredential` returns, as one opaque key. */
+export function formatServiceKey(issued: {
+  applicationId: string;
+  credentialId: string;
+  secret: string;
+}): string {
+  return [issued.applicationId, issued.credentialId, issued.secret].join(SERVICE_KEY_SEPARATOR);
+}
+
+/**
+ * Parses a service key.
+ *
+ * Every rejection names which part is wrong and none of them echoes the secret:
+ * a configuration error is read from a log, and a log line is the second most
+ * common way a credential leaks after a screenshot.
+ */
+export function parseServiceKey(serviceKey: string): ServiceCredential {
+  const trimmed = serviceKey.trim();
+  if (!trimmed) {
+    throw new CrowdSourceConfigurationError('The CrowdSource service key is empty.');
+  }
+
+  const parts = trimmed.split(SERVICE_KEY_SEPARATOR);
+  if (parts.length !== 3) {
+    throw new CrowdSourceConfigurationError(
+      `A CrowdSource service key is three colon-separated parts (applicationId:credentialId:secret); this one has ${parts.length}.`,
+    );
+  }
+
+  const [applicationId, credentialId, secret] = parts;
+
+  if (!IdentifierSchema.safeParse(applicationId).success) {
+    throw new CrowdSourceConfigurationError(
+      'The first part of a CrowdSource service key must be the applicationId it was issued for.',
+    );
+  }
+  if (!IdentifierSchema.safeParse(credentialId).success) {
+    throw new CrowdSourceConfigurationError(
+      'The second part of a CrowdSource service key must be the credentialId it was issued for.',
+    );
+  }
+  if (!secret) {
+    throw new CrowdSourceConfigurationError(
+      'The third part of a CrowdSource service key must be the credential secret.',
+    );
+  }
+
+  return { applicationId, credentialId, bearerToken: `${credentialId}.${secret}` };
+}

package/src/defaults.ts

@@ -0,0 +1,87 @@
+/**
+ * What an integrator does not have to declare, and why each default is safe to
+ * apply without being asked.
+ *
+ * The product requirement is near-zero configuration: an application should be
+ * able to report a piece of content with a credential and the object itself. The
+ * plan's requirement pulling the other way is §6.4 — every decision records the
+ * policy version it was decided under, and a policy update must never silently
+ * change what a past decision meant.
+ *
+ * Both hold only if the default is a PINNED VERSION rather than "whatever is
+ * current". `DEFAULT_POLICY` below names a specific immutable published version.
+ * When CrowdSource publishes a newer baseline, this constant changes in a
+ * release of this package and integrators adopt it by upgrading — which is
+ * visible in a lockfile, reviewable in a diff, and dated. The alternative
+ * (resolving "latest" server-side) would move the policy version under an
+ * application that never changed a line, and would silently split
+ * `caseDedupKey` — §7.3 makes the policy version part of that key, so the day it
+ * moved, two reports about one post would open two cases.
+ */
+
+import type { CasePolicyRef, CasePrivacy, TaxonomyCode } from '@crowdsource.you/contracts';
+
+/** Where the service lives. One deployment; there is no sandbox host. */
+export const DEFAULT_BASE_URL = 'https://api.crowdsource.oxy.so';
+
+/**
+ * The policy set a report is evaluated under when the application declares
+ * none: the baseline CrowdSource ships over its own universal taxonomy (§6.3).
+ *
+ * Must stay equal to `BASELINE_POLICY_SET_ID` / `BASELINE_POLICY_VERSION` in the
+ * backend's `modules/policy/policyBaseline.ts`, which is the registry that
+ * resolves it. A drift is not a type error and not a test failure anywhere else:
+ * it is a 422 on every zero-config report, in production, at the moment of
+ * upgrade. `__tests__/defaults.test.ts` reads that file and asserts the pair.
+ */
+export const DEFAULT_POLICY: CasePolicyRef = Object.freeze({
+  policySetId: 'crowdsource.baseline',
+  version: '2026.07',
+});
+
+/**
+ * §13.6's default retention: 30 days after a final decision, configurable by
+ * policy.
+ */
+export const DEFAULT_RETENTION_DAYS = 30;
+
+/**
+ * Allegation codes that must never reach a community jury (§7.5).
+ *
+ * §7.5 routes child sexual abuse and potentially illegal material to a
+ * specialist team under legal protocol, and non-consensual intimate material to
+ * specialist review. An integrator who never read §7.5 still gets that: an
+ * envelope alleging one of these is composed with `allowCommunityReview: false`,
+ * and an application that explicitly asks for `true` alongside one of them is
+ * REFUSED rather than quietly corrected — the belief that this material can be
+ * community-reviewed is the defect, and silently fixing the field would leave
+ * the belief in place.
+ *
+ * This is a floor, never a ceiling. Triage may route a case away from the
+ * community for reasons this list cannot see; nothing here can route one
+ * towards it.
+ */
+export const COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS: readonly TaxonomyCode[] = Object.freeze([
+  'child_safety.sexualization',
+  'child_safety.grooming',
+  'child_safety.exploitation',
+  'sexual_content.non_consensual',
+  'sexual_content.exploitation',
+]);
+
+const FORBIDDEN_SET: ReadonlySet<string> = new Set(COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS);
+
+/** The allegations in `codes` that §7.5 keeps away from a community jury. */
+export function allegationsForbiddingCommunityReview(
+  codes: readonly TaxonomyCode[],
+): readonly TaxonomyCode[] {
+  return codes.filter((code) => FORBIDDEN_SET.has(code));
+}
+
+/** The privacy terms of a report that declares none. */
+export function defaultPrivacy(allegationCodes: readonly TaxonomyCode[]): CasePrivacy {
+  return {
+    retentionDays: DEFAULT_RETENTION_DAYS,
+    allowCommunityReview: allegationsForbiddingCommunityReview(allegationCodes).length === 0,
+  };
+}

package/src/digest.ts

@@ -0,0 +1,91 @@
+/**
+ * Resource digests (§5.2 `sha256`, §5.6 "SHA 256 of each resource").
+ *
+ * Every inline resource in an envelope must carry a digest of "the exact
+ * representation reviewed", and asking an integrator to compute one is asking
+ * them to get canonical serialisation right — which they will do differently
+ * from the next integrator, and differently again from themselves next quarter.
+ * So the client computes it, from one rule applied to every resource type:
+ *
+ *     sha256:<hex of SHA-256 over canonicalJson({ type, data }) in UTF-8>
+ *
+ * `type` is inside the digest so a `text` resource and a `metadata` resource
+ * carrying identical fields do not produce the same digest. `custom` hashes its
+ * registered `schemaId` and `payload` for the same reason.
+ *
+ * Determinism is not a nicety here, it is the deduplication invariant. §7.3
+ * requires two people reporting the same version of the same post to land on ONE
+ * case, and the server's `caseDedupKey` is computed over a projection of the
+ * envelope that INCLUDES every resource verbatim, digest and all. A digest that
+ * varied with key order — or with which reporter sent it — would give the same
+ * post two cases, and "one penalty per incident" would be broken by a JSON
+ * serialiser.
+ *
+ * Asset-backed resources are the exception the contract already makes: their
+ * bytes live outside the envelope and `asset.sha256` is the digest of those
+ * bytes, so nothing here computes one for them.
+ */
+
+import { createHash } from 'node:crypto';
+
+/** A JSON value that can be canonicalised. */
+export type CanonicalValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly CanonicalValue[]
+  | { readonly [key: string]: CanonicalValue | undefined };
+
+/**
+ * JSON with object keys in a fixed order and `undefined` members dropped.
+ *
+ * Array order is PRESERVED. In a conversation's `messageResourceIds` the order
+ * is the meaning, and the backend's own canonicaliser makes the same choice for
+ * the same reason.
+ */
+export function canonicalJson(value: CanonicalValue): string {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError('A resource cannot carry a non-finite number: it has no JSON form.');
+    }
+    return JSON.stringify(value);
+  }
+
+  if (isCanonicalArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(',')}]`;
+  }
+
+  const members = Object.keys(value)
+    .sort()
+    .flatMap((key) => {
+      const member = value[key];
+      return member === undefined ? [] : [`${JSON.stringify(key)}:${canonicalJson(member)}`];
+    });
+
+  return `{${members.join(',')}}`;
+}
+
+/**
+ * A written-out predicate rather than a bare `Array.isArray`, because
+ * `Array.isArray` narrows `readonly T[]` in its TRUE branch only — the false
+ * branch keeps the array in the union and the object branch below stops
+ * type-checking.
+ */
+function isCanonicalArray(value: CanonicalValue): value is readonly CanonicalValue[] {
+  return Array.isArray(value);
+}
+
+/** `sha256:<64 lowercase hex>` — the only digest form the contract accepts. */
+export function sha256Digest(bytes: Uint8Array | string): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+/** The digest of an inline resource's reviewable representation. */
+export function resourceDigest(reviewable: CanonicalValue): string {
+  return sha256Digest(Buffer.from(canonicalJson(reviewable), 'utf8'));
+}