Technical audit & integration guide

01Threat model

Start here. An attestation layer that doesn't state its threat model isn't auditable.

02The audit: five checks, in dependency order

This is exactly what the browser verifier at /verify executes. Run it on a receipt you did not generate.

Checks 1–4 require no network access and no trust in anyone. Check 5 requires only the token bytes already in the receipt. Check 5b is the only one that reaches outside — and it is scoped as informational precisely so that the audit's core is offline-completable.

// The whole of check 1, in Node. No dependencies.
import { createHash } from 'node:crypto'

const jcs = o => Array.isArray(o) ? '[' + o.map(jcs).join(',') + ']'
  : (o && typeof o === 'object')
    ? '{' + Object.keys(o).sort().map(k => JSON.stringify(k) + ':' + jcs(o[k])).join(',') + '}'
    : JSON.stringify(o)

const r = JSON.parse(await readFile('receipt.json', 'utf8'))
const { receipt_hash, chain, anchor, _trust_anchors_pem, ...content } = r
const computed = 'sha256:' + createHash('sha256').update(jcs(content), 'utf8').digest('hex')
console.log(computed === receipt_hash ? 'PASS' : 'FAIL')

03Canonical encoding specification

Version identifier attest-canon/2, sealed into every receipt.

Each value is encoded as a type tag, the byte length of its literal form, and the literal, joined by a delimiter:

The browser-facing receipt JSON is additionally RFC 8785 (JCS) canonicalizable, so a verifier can be written with nothing but a sort and JSON.stringify — which is what makes the ~200-line independent verifier possible.

04Gating semantics and determinism

Determinism requirements. The engine must be a pure function of (inputs, policy, engine version). Concretely, that rules out: wall-clock reads during evaluation (the horizon is passed in, not read), map/set iteration order dependence, locale-sensitive formatting, floating-point accumulation in the aggregation path, and any network call inside the scoring path. Source resolution happens before evaluation and its results — including outages — are recorded as inputs.

// verify() re-executes gating over the recorded inputs — it does not trust the stated verdict.
const { ok, checks, recomputed } = verify(receipt)
// checks: { content, chain, gate, verdict, horizon, anchor }
// recomputed: { confidence_bp, bound_by, verdict }

05Known limitations, stated plainly

If these aren't in the document, the document isn't an audit aid.

06Integration architectures

Only the anchoring step touches the network in the embedded pattern, and it transmits a single hash — the chain head — to the timestamping authority. No field value, no product identifier, no counterparty name.

07Hooking into a live SCM application

Assume a functioning supply chain management system: supplier master, PO workflow with an approval step, goods receipt, and a document store. Nine steps, none of which require changing the SCM's data model.

// policy/po_release.json — the whole policy is data, versioned in your repo
{
  "domain": "scm.po_release",
  "weight_version": "wv-2026-01",
  "thresholds": { "approve": 0.80, "caution": 0.50 },
  "aggregation": "minimum",
  "fields": {
    "supplier_sanctions_screen":  { "critical": true,  "max_age_days": 30 },
    "quality_cert_current":       { "critical": true,  "max_age_days": 365 },
    "coc_material_origin":        { "critical": true,  "max_age_days": 180 },
    "insurance_certificate":      { "critical": true,  "max_age_days": 365 },
    "financial_health_score":     { "critical": false, "max_age_days": 90  },
    "prior_defect_rate":          { "critical": false, "max_age_days": 180 }
  }
}

npm install @corobate/sdk        # or the sidecar image
export COROBATE_DATA_DIR=/var/lib/corobate/data   # defaults to ~/.corobate/data

import { attest, verify } from '@corobate/sdk'
import policy from './policy/po_release.json' with { type: 'json' }

async function onPurchaseOrderRelease(po, actor) {
  // 1. resolve sources -> inputs (outages become MISSING, with a named reason)
  const inputs = await resolveInputs(po.supplier_id, policy)

  // 2. seal BEFORE the approval is written
  const receipt = await attest({
    decision_id : `dcn_po_${po.id}`,
    question    : `Release PO ${po.id} to supplier ${po.supplier_id}?`,
    domain      : policy.domain,
    actor       : `actor:human:${actor.email}`,
    period_end  : po.decision_time,      // point-in-time gate
    policy, inputs
  })

  // 3. persist the receipt alongside the PO, and index by hash
  await db.receipts.insert({ po_id: po.id, hash: receipt.receipt_hash, body: receipt })

  // 4. branch on the verdict
  switch (receipt.verdict) {
    case 'APPROVE':
      return { action: 'RELEASE', receipt }
    case 'CAUTION':
      return { action: 'RELEASE_WITH_CONDITIONS',
               conditions: conditionsFor(receipt.bound_by), receipt }
    case 'WITHHELD':
      return { action: 'HOLD',
               evidence_request: requestFor(receipt.coverage_gaps), receipt }
  }
}

08Field maps: integration as configuration

The zero-code-change path. A field map declares how an upstream payload becomes classed inputs.

// fieldmaps/supplier_master.json
{
  "map_version": "fm-scm-3",
  "source_id": "actor:sys:sap-supplier-master",
  "fetch": { "url": "https://erp.internal/api/v2/supplier/{id}/compliance",
             "allowlist": true },
  "fields": {
    "supplier_sanctions_screen": {
      "path": "$.screening.status",
      "class": "VERIFIED",
      "class_requires": { "resolve": "$.screening.provider_ref" },
      "observed_at": "$.screening.checked_at"
    },
    "quality_cert_current": {
      "path": "$.certs[?(@.type=='ISO9001')].valid_until",
      "class": "VERIFIED",
      "class_requires": { "resolve": "$.certs[?(@.type=='ISO9001')].cert_no" },
      "observed_at": "$.certs[?(@.type=='ISO9001')].issued_at"
    },
    "coc_material_origin": {
      "path": "$.declarations.material_origin",
      "class": "SELLER-ASSERTED",          // supplier says so; classed accordingly
      "observed_at": "$.declarations.submitted_at"
    }
  }
}

Three properties worth noting. class_requires.resolve means the declared class is conditional — if the referenced identifier does not resolve externally, the input is demoted and the demotion is recorded. observed_at is mandatory; a field with no timestamp cannot be freshness-checked and is treated as stale. And map_version is sealed into every receipt built through it, so a mapping change is a visible event in the audit trail rather than a silent reinterpretation of history.

09Operational concerns

10Pre-production checklist