@tokenoftrust/storefront-runner 3.10.2 → 3.10.4

package/apps/storefront/src/lib/orders/data/sourceAuthorityContract.ts

@@ -0,0 +1,379 @@
+/** Strict signed source authority controls. Business event bytes remain independent. */
+import {
+  canonicalJson,
+  sha256Hex,
+  type CommerceStage,
+} from "@tot/public-runtime";
+export const SOURCE_SCHEMA = "commerce-source-authority/v1";
+export const SOURCE_LIMIT = 64;
+export const SOURCE_LEASE_MS = 120_000;
+export const FAULT_KINDS = [
+  "fork",
+  "committed-payload-missing",
+  "committed-payload-corrupt",
+  "source-resource-invalid",
+  "census-incomplete",
+  "census-changing",
+  "source-unavailable",
+  "authority-budget",
+] as const;
+export type FaultKind = (typeof FAULT_KINDS)[number];
+export interface SourceKey {
+  tenantId: string;
+  stage: CommerceStage;
+  source: "foxycart";
+  providerStoreId: string;
+  sourceOrderId: string;
+}
+export interface ManifestCore {
+  v: 2;
+  store: string;
+  order: string;
+  revision: number;
+  parent: string | null;
+  parts: number;
+  bytes: number;
+  sha256: string;
+}
+export interface BusinessPair {
+  sourceEventId: string;
+  originalEventDigest: string;
+}
+export interface FaultProof {
+  faultKind: FaultKind;
+  conditionDigest: string;
+  completeValidatedManifestSetOrNull: ManifestCore[] | null;
+  divergenceParentOrNull: string | null;
+  conflictingValidatedGenerationsOrNull: string[] | null;
+}
+export interface SourceBegin {
+  kind: "source-check-begin";
+  schema: typeof SOURCE_SCHEMA;
+  source: "foxycart";
+  providerStoreId: string;
+  sourceOrderId: string;
+  requestId: string;
+}
+interface ResultCommon {
+  kind: "source-check-result";
+  schema: typeof SOURCE_SCHEMA;
+  source: "foxycart";
+  providerStoreId: string;
+  sourceOrderId: string;
+  checkId: string;
+  observationId: string;
+  expectedCheckRevision: number;
+  expectedSourceStateVersion: number;
+}
+export type SourceResult = ResultCommon &
+  (
+    | ({ outcome: "fault" } & FaultProof)
+    | {
+        outcome: "healthy";
+        actualObservedAt: string;
+        tipGeneration: string;
+        validatedManifestCores: ManifestCore[];
+        recognizedResourceSetDigest: string;
+        businessEventDigestPairs: BusinessPair[];
+        businessEventSetDigest: string;
+        resolvesHoldIds: string[];
+      }
+  );
+export interface Provenance {
+  acceptedLedgerGeneration: string;
+  businessEventSetDigest: string;
+  exactOriginalEventDigest: string;
+}
+export interface SourceOrderWrapper {
+  kind: "source-order-event";
+  schema: typeof SOURCE_SCHEMA;
+  event: Record<string, unknown>;
+  provenance: Provenance;
+}
+export interface SourceHold {
+  holdId: string;
+  conditionDigest: string;
+  faultKind: FaultKind;
+  openingObservationId: string;
+  openingProof: FaultProof;
+}
+export interface BeginAck {
+  ok: true;
+  duplicate: boolean;
+  checkId: string;
+  checkRevision: number;
+  sourceStateVersion: number;
+  acceptedLedgerGeneration: string | null;
+  acceptedBusinessEventSetDigest: string | null;
+  unresolvedHolds: SourceHold[];
+}
+export interface ResultAck {
+  ok: true;
+  duplicate: boolean;
+  checkId: string;
+  observationId: string;
+  sourceStateVersion: number;
+  acceptedLedgerGeneration: string | null;
+  acceptedBusinessEventSetDigest: string | null;
+  sourceProofExpiresAt: string | null;
+  pendingCheck: boolean;
+  unresolvedHoldIdsDigest: string;
+  sourceSyncPending: boolean;
+}
+export type AuthorityCode =
+  | "malformed"
+  | "signature"
+  | "tenant"
+  | "stage"
+  | "source-state-changed"
+  | "source-authority-unavailable"
+  | "source-sync-pending"
+  | "authority-budget"
+  | "control-identity-conflict";
+export class SourceAuthorityError extends Error {
+  constructor(readonly code: AuthorityCode) {
+    super(code);
+  }
+}
+export const isRecord = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+export const isHash = (v: unknown): v is string =>
+  typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
+export const isSourceId = (v: unknown): v is string =>
+  typeof v === "string" && /^[1-9][0-9]{0,30}$/.test(v);
+const opaque = (v: unknown): v is string =>
+  typeof v === "string" && /^[A-Za-z0-9:_-]{1,128}$/.test(v);
+const integer = (v: unknown, min = 0, max = Number.MAX_SAFE_INTEGER) =>
+  Number.isSafeInteger(v) && Number(v) >= min && Number(v) <= max;
+export function exactKeys(
+  v: unknown,
+  keys: readonly string[],
+): v is Record<string, unknown> {
+  return (
+    isRecord(v) &&
+    Object.keys(v).length === keys.length &&
+    keys.every((k) => Object.hasOwn(v, k))
+  );
+}
+export function canonicalInstant(v: unknown): v is string {
+  if (typeof v !== "string") return false;
+  const n = Date.parse(v);
+  return Number.isFinite(n) && new Date(n).toISOString() === v;
+}
+const BASE = ["kind", "schema", "source", "providerStoreId", "sourceOrderId"];
+const COMMON = [
+  ...BASE,
+  "checkId",
+  "observationId",
+  "expectedCheckRevision",
+  "expectedSourceStateVersion",
+  "outcome",
+];
+const FAULT = [
+  "faultKind",
+  "conditionDigest",
+  "completeValidatedManifestSetOrNull",
+  "divergenceParentOrNull",
+  "conflictingValidatedGenerationsOrNull",
+];
+function core(v: unknown): v is ManifestCore {
+  return (
+    exactKeys(v, [
+      "v",
+      "store",
+      "order",
+      "revision",
+      "parent",
+      "parts",
+      "bytes",
+      "sha256",
+    ]) &&
+    v.v === 2 &&
+    typeof v.store === "string" &&
+    typeof v.order === "string" &&
+    integer(v.revision, 1) &&
+    (v.parent === null || isHash(v.parent)) &&
+    integer(v.parts, 1, 350) &&
+    integer(v.bytes, 1, 262144) &&
+    isHash(v.sha256)
+  );
+}
+function cores(v: unknown): v is ManifestCore[] {
+  return (
+    Array.isArray(v) &&
+    v.length > 0 &&
+    v.length <= SOURCE_LIMIT &&
+    v.every(core)
+  );
+}
+export function faultProof(v: SourceResult & { outcome: "fault" }): FaultProof {
+  return {
+    faultKind: v.faultKind,
+    conditionDigest: v.conditionDigest,
+    completeValidatedManifestSetOrNull: v.completeValidatedManifestSetOrNull,
+    divergenceParentOrNull: v.divergenceParentOrNull,
+    conflictingValidatedGenerationsOrNull:
+      v.conflictingValidatedGenerationsOrNull,
+  };
+}
+export function parseSourceWire(
+  v: unknown,
+): SourceBegin | SourceResult | SourceOrderWrapper | null {
+  if (!isRecord(v) || v.schema !== SOURCE_SCHEMA) return null;
+  if (v.kind === "source-order-event") {
+    if (
+      !exactKeys(v, ["kind", "schema", "event", "provenance"]) ||
+      !isRecord(v.event) ||
+      !exactKeys(v.provenance, [
+        "acceptedLedgerGeneration",
+        "businessEventSetDigest",
+        "exactOriginalEventDigest",
+      ]) ||
+      !Object.values(v.provenance).every(isHash)
+    )
+      return null;
+    return v as unknown as SourceOrderWrapper;
+  }
+  if (
+    v.source !== "foxycart" ||
+    !isSourceId(v.providerStoreId) ||
+    !isSourceId(v.sourceOrderId)
+  )
+    return null;
+  if (v.kind === "source-check-begin")
+    return exactKeys(v, [...BASE, "requestId"]) && opaque(v.requestId)
+      ? (v as unknown as SourceBegin)
+      : null;
+  if (
+    v.kind !== "source-check-result" ||
+    !opaque(v.checkId) ||
+    !isHash(v.observationId) ||
+    !integer(v.expectedCheckRevision) ||
+    !integer(v.expectedSourceStateVersion)
+  )
+    return null;
+  if (v.outcome === "fault") {
+    if (
+      !exactKeys(v, [...COMMON, ...FAULT]) ||
+      !FAULT_KINDS.includes(v.faultKind as FaultKind) ||
+      !isHash(v.conditionDigest)
+    )
+      return null;
+    if (
+      v.completeValidatedManifestSetOrNull !== null &&
+      !cores(v.completeValidatedManifestSetOrNull)
+    )
+      return null;
+    if (v.divergenceParentOrNull !== null && !isHash(v.divergenceParentOrNull))
+      return null;
+    const ids = v.conflictingValidatedGenerationsOrNull;
+    if (
+      ids !== null &&
+      (!Array.isArray(ids) ||
+        ids.length < 2 ||
+        ids.length > SOURCE_LIMIT ||
+        !ids.every(isHash) ||
+        new Set(ids).size !== ids.length)
+    )
+      return null;
+    return v as unknown as SourceResult;
+  }
+  if (
+    v.outcome !== "healthy" ||
+    !exactKeys(v, [
+      ...COMMON,
+      "actualObservedAt",
+      "tipGeneration",
+      "validatedManifestCores",
+      "recognizedResourceSetDigest",
+      "businessEventDigestPairs",
+      "businessEventSetDigest",
+      "resolvesHoldIds",
+    ])
+  )
+    return null;
+  if (
+    !canonicalInstant(v.actualObservedAt) ||
+    !isHash(v.tipGeneration) ||
+    !cores(v.validatedManifestCores) ||
+    !isHash(v.recognizedResourceSetDigest) ||
+    !isHash(v.businessEventSetDigest)
+  )
+    return null;
+  if (
+    !Array.isArray(v.resolvesHoldIds) ||
+    v.resolvesHoldIds.length > SOURCE_LIMIT ||
+    !v.resolvesHoldIds.every(opaque) ||
+    new Set(v.resolvesHoldIds).size !== v.resolvesHoldIds.length
+  )
+    return null;
+  const pairs = v.businessEventDigestPairs;
+  if (!Array.isArray(pairs) || pairs.length > SOURCE_LIMIT) return null;
+  for (let i = 0; i < pairs.length; i++) {
+    const p = pairs[i];
+    if (
+      !exactKeys(p, ["sourceEventId", "originalEventDigest"]) ||
+      typeof p.sourceEventId !== "string" ||
+      !/^[-A-Za-z0-9._:]{1,128}$/.test(p.sourceEventId) ||
+      !isHash(p.originalEventDigest) ||
+      (i > 0 && pairs[i - 1].sourceEventId >= p.sourceEventId)
+    )
+      return null;
+  }
+  return v as unknown as SourceResult;
+}
+export const digestJson = (v: unknown): Promise<string> =>
+  sha256Hex(canonicalJson(v));
+export function conditionDigest(
+  key: SourceKey,
+  proof: Omit<FaultProof, "conditionDigest">,
+): Promise<string> {
+  return digestJson({ v: 1, key, ...proof });
+}
+export function observationId(
+  key: SourceKey,
+  result: Omit<SourceResult, "observationId"> | Record<string, unknown>,
+): Promise<string> {
+  const r = { ...result };
+  delete (r as Record<string, unknown>).observationId;
+  return digestJson({
+    domain: "commerce-source-observation/v1",
+    key,
+    result: r,
+  });
+}
+export async function validateManifestSet(
+  key: SourceKey,
+  items: readonly ManifestCore[],
+): Promise<Map<string, ManifestCore>> {
+  const map = new Map<string, ManifestCore>();
+  for (const item of items) {
+    if (
+      item.store !== `https://api.foxycart.com/stores/${key.providerStoreId}` ||
+      item.order !==
+        `https://api.foxycart.com/transactions/${key.sourceOrderId}`
+    )
+      throw new SourceAuthorityError("malformed");
+    const id = await digestJson(item);
+    if (map.has(id)) throw new SourceAuthorityError("malformed");
+    map.set(id, item);
+  }
+  return map;
+}
+export function uniqueLineage(
+  map: Map<string, ManifestCore>,
+  tip: string,
+): boolean {
+  let id: string | null = tip;
+  let child: ManifestCore | null = null;
+  const seen = new Set<string>();
+  while (id !== null) {
+    const c = map.get(id);
+    if (!c || seen.has(id) || (child && child.revision !== c.revision + 1))
+      return false;
+    seen.add(id);
+    child = c;
+    id = c.parent;
+  }
+  return child?.revision === 1 && seen.size === map.size;
+}