One signed record. Every cross-border module. Verifiable by anyone who has our public key.

A Cruzar Ticket carries the result of every Cruzar module that fired on a single cross-border shipment, packaged into one Ed25519-signed JSON record. The signature is over the deterministic-canonical encoding of the payload (sorted keys, no whitespace, undefined values omitted). Re-canonicalize, recompute the SHA-256 content hash, and verify against our public key.

The canonical form is what gets signed. Any byte-level change to the payload (re-formatting, re-ordering keys, escaping differences) breaks verification.

{
  "schema_version": "v1",
  "ticket_id": "cr_<YYYY>_<MM>_<DD>_<rand>",
  "issued_at": "<ISO 8601 UTC>",
  "issuer": "Cruzar Insights, Inc.",
  "modules_present": [ "customs" | "regulatory" | "paperwork" | "drivers"
                     | "refunds"  | "drawback"   | "pedimento" | "cbam"
                     | "uflpa"    | "driver_pass" ],
  "shipment": {
    "origin":      { "country": "<ISO-2>", "city"?: "<string>" },
    "destination": { "country": "<ISO-2>", "port_code"?: "<string>" },
    "importer_name"?: "<string>",
    "bol_ref"?: "<string>",
    "carrier"?: "<string>",
    "consignee"?: "<string>"
  },
  "customs"?:     <TicketCustomsBlock>,
  "regulatory"?:  <TicketRegulatoryBlock>,
  "paperwork"?:   <TicketPaperworkBlock>,
  "drivers"?:     <TicketDriversBlock>,
  "refunds"?:     <TicketRefundsBlock>,
  "drawback"?:    <TicketDrawbackBlock>,
  "pedimento"?:   <TicketPedimentoBlock>,
  "cbam"?:        <TicketCbamBlock>,
  "uflpa"?:       <TicketUflpaBlock>,
  "driver_pass"?: <TicketDriverPassBlock>,
  "audit_shield": {
    "prior_disclosure_eligible": <boolean>,
    "19_USC_1592_basis":         "<string>"
  },
  "calibration": { ... },
  "signing_key_id": "<string>",
  "verify_url":     "<https://www.cruzar.app/ticket/{ticket_id}>"
}

The fields under each module block (e.g. refunds.composition) are fully documented in the TypeScript types at lib/chassis/<module>/types.ts in the Cruzar source. Every module ships its own registry_version string inside its block so a regulator reading the Ticket years later can know exactly which schema and reference tables produced it.

A Ticket carries one block per Cruzar module that fired on the shipment. The modules_present array tells you which blocks to expect.

• customs

  HS classification + USMCA origin + RVC + LIGIE flag — composes US-side declaration.

• pedimento

  Anexo 22 clave + RFC + patente + aduana + DTA / IVA / IEPS — Mexican-side declaration.

• regulatory

  FDA Prior Notice + USDA APHIS + ISF 10+2 + CBP 7501 — pre-arrival multi-agency manifest.

• paperwork

  Multi-page document classification + Mexican health-cert validation + extraction.

• drivers

  USMCA Annex 31-A + IMSS + HOS dual-regime + DOT 49 CFR Part 40 + Borello drayage — operator-level driver compliance.

• driver_pass

  Per-trip driver readiness — CDL + DOT medical + TWIC + FAST + FMM + HAZMAT expiry.

• refunds

  IEEPA tariff refund composition — CAPE Phase 1 CSV + Form 19 protest packet + 80-day cliff routing + interest.

• drawback

  US §1313 duty drawback — 99% refund on imports that get exported / re-exported / rejected, 5yr window.

• cbam

  EU Carbon Border Adjustment — embedded emissions calc + cert cost at ETS reference price.

• uflpa

  Forced-labor risk evaluation — Xinjiang detection + UFLPA Entity List match + rebuttable-presumption logic.

• eudamed

  EU MDR EUDAMED — actor + UDI/Device readiness for May 28, 2026 deadline.

1. Build the payload object.
2. Canonicalize: sort keys, no whitespace, omit undefined values, JSON.stringify scalars.
3. SHA-256 the canonical UTF-8 bytes — that's the content_hash.
4. Ed25519-sign the SHA-256 digest with our private key — that's signature_b64.
5. Bundle everything: payload, payload_canonical, content_hash, signature_b64, signing_key_id.

The canonicalization algorithm is implemented in lib/ticket/json-signer.ts in our source. Any compatible JSON-canonicalization implementation that produces the same bytes will verify.

1 · By ticket ID (lookup our DB)

curl https://www.cruzar.app/api/ticket/verify?id=<ticket_id>

We return the signed Ticket from our database plus our server-side verification result. Use this when you have the ticket ID and trust Cruzar's database lookup.

2 · By payload (no DB trust)

curl -X POST https://www.cruzar.app/api/ticket/verify-payload \
  -H 'content-type: application/json' \
  -d '<signed_ticket_json>'

POST a SignedTicket payload you got out-of-band (from a PDF / email / portal). We re-canonicalize, recompute the content hash, fetch the public key, and verify. Same trust model as PGP — verify against the published public key.

3 · Locally (full self-custody)

# 1. Get our public key
curl https://www.cruzar.app/.well-known/cruzar-ticket-key.json

# 2. Get a real signed sample to test against
curl https://www.cruzar.app/api/ticket/sample

# 3. Verify locally with any Ed25519 library:
#    a. canonicalize signed.payload (sorted keys, no whitespace,
#       skip undefined)
#    b. SHA-256 the canonical bytes -> must match content_hash
#    c. Ed25519.verify(signature_b64, content_hash, public_key_b64)

• Cruzar issues + signs Tickets. Holders carry them. Anyone verifies them.
• The published public key at /.well-known/cruzar-ticket-key.json is the root of trust. Pin it. Audit it. Mirror it.
• If we rotate keys, the old key continues to verify historic Tickets; signing_key_id tells you which key signed which Ticket.
• Cruzar is software for preparing customs / regulatory / refund documentation. We do not transact CBP / VUCEM / EU Registry business. Filings prepared via Cruzar are reviewed and submitted by the licensed broker / declarant of record.

This document specifies cruzar-ticket-v1. Future schema changes either:

• Add new optional module blocks (forward-compatible — old verifiers ignore unknown blocks).
• Add new optional fields to existing blocks (forward-compatible).
• Bump schema_version to v2 for any breaking change. v1 verifiers will reject v2 payloads on the schema_version field.