Trusted data exchange
between parties that share a chain.

§1What is this, and why should you care?

Whenever multiple organisations need to coordinate on the same underlying thing — a shipment, a patient referral, a customs declaration, a financial settlement, an energy-grid dispatch, a regulatory filing — each party usually holds a fragment of the truth. Stitching those fragments together is slow, expensive, and dominated by one-off bilateral integrations.

The pattern that solves it is older than any one industry: agree on a tiny set of protocols instead of forcing everyone onto a single platform. Two parties who have never met before share data about a shared object once they prove they belong together in a chain of custody, with cryptographic guarantees, and without a central operator sitting in the request path.

This repository implements that pattern. Concretely, it is a reference implementation of the BDI — the Dutch national initiative that originated this design for logistics and supply chains — but the mechanism (federated identity register, chain-of-custody token issuer, local policy enforcement at each member) applies to any domain where:

• multiple independent parties need to exchange data,
• membership and counterparty trust must be cryptographically verifiable,
• a specific exchange is bounded by a chain — referral pathway, shipment, custody chain, transaction graph, regulatory case file,
• and no single party can — for legal, competitive, or operational reasons — be the central data hub.

§2The three components, in plain language

The protocol splits the responsibility for a data exchange into three small services. Each does one thing well, and each can be operated by a different party. The names are BDI's; the roles are domain-neutral.

Why the dual-token boundary matters. Most data-sharing platforms put the operator in the middle of every call — and therefore see, log, and potentially leak every payload. This design deliberately doesn't. Connectors verify cryptographic envelopes against a cached trustlist, so the registers can be temporarily unreachable without stopping legitimate traffic — and they never see the payloads at all.

§3Install from npm

The three core services are published to npm under the @transportial scope and run on Node ≥20 or Bun ≥1.2. Every component ships both a CLI binary and a library entry point, with full TypeScript types.

Run a service straight from the CLI

# Associatie Register on :8080
PORT=8080 npx -y @transportial/asr

# Orkestratie Register on :8081
PORT=8081 npx -y @transportial/ors

# Connector on :8443
PORT=8443 npx -y @transportial/con

Common environment variables: PORT, ASR_ISSUER, ORS_ISSUER, ASSOCIATION_ID, CONNECTOR_ID, CON_AUDIENCE. See Setup for the full list and production notes.

Bootstrap a full association deployment

If you're standing up the registers (ASR + ORS) for a new association rather than running a single service, the bundled bdi CLI generates a complete deployment directory in one step:

bunx -p @transportial/cli bdi init-association \
  --id eu.nl.bdi.acme \
  --name "Acme Logistics Association" \
  --domain bdi.acme.example \
  --admin-email [email protected] \
  --out ./acme-deploy

cd ./acme-deploy && docker compose up -d

The generated directory contains:

• compose.yml — Postgres, Valkey, Keycloak, ASR, ORS (member-side connectors install separately).
• .env.asr and .env.ors — pre-filled with the association id, signing kid, DB credentials, and issuer URLs.
• keys/ — freshly generated EdDSA signing JWKs for ASR and ORS.
• db/init-multi-db.sh — bootstraps asr_db and ors_db on first start.
• admin/bootstrap.json — single-use credential to claim the first admin account in Keycloak.
• README.md — exact next-step commands for inviting your first member.

The generator refuses to overwrite an existing deployment, so it's safe to re-run while you tweak flags. Private signing keys land on disk and are acceptable for development; for production, swap them for HSM- or PKCS#11-backed signing as documented in the generated README.

Embed as a library

npm install @transportial/asr
# or: bun add @transportial/asr

import { createServer } from '@transportial/asr';

const { fetch, composition } = await createServer({
  port: 8080,
  issuer: 'https://asr.example.org',
});

// Bun
Bun.serve({ port: 8080, fetch });

@transportial/ors and @transportial/con expose the same createServer shape. The shared building blocks — kernel, contracts, crypto, crypto-ca, events, observability, identity, policy, config, testing, openapi — are published alongside and can be consumed independently.

§4Or hack on the source in 60 seconds

No database to install, no broker to configure, no keys to generate. The reference adapters are real implementations that simply keep state in memory, so the entire test suite is offline and self-contained.

# Install Bun 1.3+
curl -fsSL https://bun.sh/install | bash

# Clone and install
git clone https://github.com/Transportial/basic-data-infrastructure.git
cd basic-data-infrastructure
bun install

# Run every test (offline, no external services)
bun test

# Boot any service
bun run --filter '@transportial/asr' dev
bun run --filter '@transportial/ors' dev
bun run --filter '@transportial/con' dev

§5Where to go next

§6Who is this for?

• Logistics, transport, and supply-chain integrators — the originating use case for BDI, and still the most direct fit (carriers, shippers, terminals, customs brokers, platform operators).
• Healthcare and public-health networks building referral pathways, cross-institution patient data exchange, or clinical-research collaborations across hospitals, GPs, payers, and regulators.
• Financial settlement, KYC, and trade-finance networks where multiple institutions must coordinate on a transaction graph without one party becoming the central operator.
• Energy, utilities, and grid-balancing operators sharing dispatch, metering, or congestion data across TSOs, DSOs, aggregators, and prosumers.
• Regulatory and compliance reporting chains — supervisor, supervised entity, auditor, sectoral register — where authenticity and provenance must be verifiable end-to-end.
• Public-sector teams building national or sectoral data spaces, and anyone building on EU data-space concepts (Gaia-X, IDSA, EONA-X) — the trust machinery here maps directly onto those frameworks.
• Researchers and students who want a working, auditable example of a modern federated data-sharing protocol to study or extend.

Contributions, questions, and "this surprised me" reports are all welcome on GitHub.