# Integration kit

For broker-software vendors, and anyone else putting RiskRouter behind their own product. Each
example does the same five things, in the language your product is probably written in, with no
dependencies beyond the language's own standard library:

1. **Price** a configuration. The server prices it; your code never does. No key is sent, so
   nothing is recorded.
2. **Record** a quote against your key, with an `Idempotency-Key`, then retry with the same key and
   get the same entry back. A double-click or a network retry can never record twice.
3. **Record evidence** of a regulated decision without sending it: a broker's demands-and-needs
   note is salted and hashed on your side; only the SHA-256 reaches us.
4. **Export** your entries, the chain they sit in and the signed head.
5. **Prove** one evidence entry against the signed head.

The Python example also **signs its claim** with its own key (`python/signer.py`, standard library
only): the key is generated once into `signing-key.json`, its public half registered with
`POST /api/v2/evidence/keys`, and each evidence entry carries the broker's own signature inside the
leaf (a v3 leaf, see the [specification](https://riskrouter.eu/spec#signed)). The other languages
record unsigned (v2) leaves; signing is optional per entry.

`record_structured()` in the Python client records a structured record, such as one written to a
[regime pack](https://riskrouter.eu/regime-packs): it canonicalises the record (RFC 8785), salts and
hashes it, and returns the salt. With the proof, the record and the salt make a bundle anyone can
check offline (`RiskRouter.bundle()`).

| Language | Files | Run |
| --- | --- | --- |
| Python 3.8+ | `python/riskrouter.py`, `python/signer.py`, `python/demo.py` | `python3 demo.py` |
| PHP 8.1+ (curl) | `php/RiskRouter.php`, `php/demo.php` | `php demo.php` |
| C# (.NET 8) | `dotnet/RiskRouter.cs`, `dotnet/Program.cs` | `dotnet run` |
| Java 17+ | `java/RiskRouterDemo.java` | `java RiskRouterDemo.java` |

Every example reads `RISKROUTER_API_KEY` (take a sandbox key in seconds at
<https://riskrouter.eu/integrate#get-a-key>) and optionally `RISKROUTER_BASE` (defaults to
`https://api.riskrouter.eu`). Keys belong on your server, never in a browser.

## The reference app

`reference-app/app.py` is a one-file "broker desk": configure cover, write the demands-and-needs
note, price and record. The note and the customer's name stay in the app's own data file; only the
note's salted fingerprint is recorded. "Evidence pack" bundles, for one customer, the note, its
salt, the single-entry proof of the quote and the Merkle proof of the note.
`reference-app/check_pack.py` checks a pack offline with the independent Python verifier:

```
OK    the note and its salt produce the recorded digest
OK    the note's digest is entry 4 of the evidence log
OK    the quote is entry 6 of the quote ledger, linked to its head
OK    the evidence head is signed
OK    the quote ledger head is signed
```

That is IDD Article 20 evidence a broker can hand to an inspector, for one customer, without
revealing any other, and without RiskRouter ever holding the personal data in it.

## Implementing the format yourself: the conformance suite

You do not have to use these clients. The formats are published at <https://riskrouter.eu/spec>,
and `conformance/` in this kit is how you check an implementation of them in any language:

```bash
node conformance/conformance.mjs cases > cases.json            # every frozen form, with the expected answer
# your code answers each case as { "<case id>": <answer> } ...
node conformance/conformance.mjs grade answers.json --name "Your product 12.4" > result.json
# ... or is driven directly, one case on stdin, its answer on stdout:
node conformance/conformance.mjs run --command "python3 my_impl.py" --name "Your product 12.4"
# and the files your product writes are checked with the reference verifiers:
node conformance/conformance.mjs artefacts ./evidence/ --key signing-key.json
```

The cases are the specification's own test vectors plus proofs that have been deliberately broken
and must be refused, so an implementation that verifies nothing cannot pass. The result is your
statement about your software, named by the vector set and the digest of the cases so anyone can
re-run it; RiskRouter certifies nothing. `node conformance/conformance.mjs self` runs the reference
code through the same cases, which is how the suite itself is tested.

## Tested, not just written

`npm run test:kit` runs every example and the reference app against the real Worker on an
in-memory backend that chains, replays and proves like the real schema
(`RISKROUTER_BACKEND=fake node tests/harness.mjs` serves the same thing on port 8787 for your own
experiments). Every file the examples write is checked by both independent verifiers, and the test
fails if the customer's name or note reaches the backend. CI runs it on every push.

Format and proofs: <https://riskrouter.eu/spec>. API: <https://riskrouter.eu/docs>.

## Licence

These examples are Apache-2.0 (`LICENSE` in each kit directory): copy them into your own product as you need.
