Pattern 04 · Bytes
AIOL fetches the bytes itself — signed, scoped, and never guessable
Events carry facts, not files. When AIOL ingests a document it comes and asks for it, machine to machine, outside anybody’s session.
01What you see
# AIOL → ADR, server to server GET /api/v1/aiol/documents/doc-4231 X-ADR-Timestamp: … X-ADR-Nonce: … X-ADR-Signature: … # ADR → AIOL 200 application/pdf · decrypted, as an attachment X-Content-Type-Options: nosniff Cache-Control: no-store
No user, no cookie, no session — the signature is the authorization.
There is nothing to see on screen, and that is the design: the two systems reconcile themselves. Nightly, AIOL asks ADR for a snapshot of each dispute and compares it with its own — a drift is caught by the systems, not by a person noticing a missing exhibit in a hearing.
| Route | Purpose |
|---|---|
| /api/v1/aiol/documents/<id> | the document’s bytes, when AIOL ingests it |
| /api/v1/aiol/disputes/<id> | the reconciliation snapshot, nightly |
02How it is used
By an operator, twice in the life of the integration: when the secrets are set, and when they are rotated.
flask aiol keygen writes the private key at mode 0600, refuses to overwrite an existing one, prints the public half for AIOL and a fresh webhook secret — and never prints the private key.
- Turning it off is one empty variable. With no base URL configured nothing is recorded, nothing is sent, and these routes answer 404 like any unknown path.
- Rotation loses nothing. Events queued under the old secret are re-signed when they are sent.
- Entry keys need no overlap window — tokens live 120 seconds, so the switch is instant.
03Technically
- Constant-time, then recorded. The signature is compared before the nonce is stored, so an unsigned flood cannot fill the nonce table.
- Throttled and logged. Failed signature checks are rate-limited per source address (20 per 5 minutes → 429) and logged as security events with a reason code only.
- Scoped to the merits. A document is served only if it is a filed, transferred PDF or DOCX of a case AIOL has been told about. Identity papers and receipts are not fetchable at all.
- Decrypted at the edge. Documents sit watermarked and encrypted at rest; they are decrypted only to be served, as an attachment, with no caching.
outbound posture
| host | exactly one, from configuration — never from data |
| redirects | not followed |
| TLS | always verified |
| timeouts | 5 s connect · 20 s read |
Every decision on this page is written down against the OWASP ASVS 5.0 requirement it answers, in docs/security/aiol-integration.md.