@onlineapps/external-io-contract 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @onlineapps/external-io-contract
+
+Sdílený kontrakt pro HTTP komunikaci OA Drive s vnějším světem.
+
+Zdrojem pravdy jsou **JSON Schemata v `schemas/`**; kód v `src/` je jen
+jejich spustitelná podoba (validátory se kompilují při načtení modulu).
+
+## Kdo to používá
+
+| Konzument | K čemu |
+|---|---|
+| `api_gateway` | ověření podpisu příchozích webhooků, rozbor correlation reference, validace obálky |
+| `api_delivery_dispatcher` | podpis odchozích volání, validace outbound obálky a výsledku |
+| `pdke_orion-grit` | podpis odchozích callbacků |
+
+**Biz služby tuhle knihovnu nepoužívají.** Dostávají a vracejí prosté
+objekty; transport, podpisy ani obálky neznají. Vlastní-li biz služba
+nějaký typ correlation reference (např. `ing_job`), má nad toutéž
+gramatikou vlastní tenkou vrstvu — bez runtime vazby na tuto knihovnu.
+Kompatibilitu obou stran drží sdílené vektory v `test-vectors/`.
+
+## Použití
+
+```js
+const { correlation, hmac, validators, SIGNATURE_HEADER } = require('@onlineapps/external-io-contract');
+
+// odchozí: podepsat přesné bajty těla
+const signature = hmac.sign(rawBody, secret);   // "sha256=<hex>"
+res.setHeader(SIGNATURE_HEADER, signature);
+
+// příchozí: ověřit (false = odmítnout, nikdy výjimka)
+if (!hmac.verify(req.rawBody, secret, req.get(SIGNATURE_HEADER))) return res.sendStatus(401);
+
+// zjistit, komu callback patří
+const jobUuid = correlation.refOfType(body.correlation_id, 'ing_job');
+
+// zvalidovat tvar payloadu
+const { valid, errors } = validators.orionGritCallbackV1(body);
+```
+
+## Zásady, na kterých kód stojí
+
+- **Podepisují se raw bajty**, nikdy znovu-serializovaný objekt. Kdo
+  ověřuje, musí mít původní tělo (`express.json({ verify })`), jinak se
+  podpis rozejde na pořadí klíčů nebo mezerách.
+- **Ověření vrací `false`, nevyhazuje.** Nevalidní vstup od cizí strany
+  je očekávaný stav. Výjimka je vyhrazená programátorské chybě (špatný
+  typ těla, prázdný secret).
+- **Secret sem chodí jako hodnota, ale do configu se zapisuje jako
+  reference.** Volající si ji vyzvedne ze SecretBoxu těsně před použitím.
+- **Slovníky partnerů se sem nepromítají.** `status: "confirmed"` je
+  slovník orion-gritu; překlad na platformní `delivered|failed` dělá
+  cookbook, ne tato knihovna a ne biz služba.
+
+## Formát podpisu (zmrazený)
+
+```
+X-Signature: sha256=<lowercase hex>
+             HMAC-SHA256(raw body bytes, shared secret)
+```
+
+Jazykově neutrální — ověřeno proti nezávislé implementaci (`openssl
+dgst -sha256 -hmac`, vektory v `test-vectors/hmac.json`) i proti PHP
+`hash_hmac` na straně Meditestu. Změna schématu musí projít verzováním
+prefixu, ne tichou úpravou.
+
+## Correlation gramatika
+
+```
+<biz_ref_type>:<ref>        např. ing_job:9a8b7c6d-1234-4567-89ab-cdef01234567
+```
+
+Dělí se na **první** dvojtečce, takže reference smí další obsahovat.
+Typ: `^[a-z][a-z0-9_]{1,31}$`. Reference:
+`^[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$`.
+
+Skládá ji biz služba (zná byznys význam), propaguje dispatcher, vrací
+echem externí systém, rozebírá gateway při zjišťování tenanta.
+
+## Schémata
+
+| Soubor | Stav |
+|---|---|
+| `schemas/correlation-ref.schema.json` | stabilní |
+| `schemas/callbacks/orion-grit.v1.schema.json` | stabilní (odpovídá `buildPayload` v pdke_orion-grit) |
+| `schemas/envelopes/outbound-envelope.v0.schema.json` | **draft** — stabilizuje se s OAuth2 adapterem |
+| `schemas/envelopes/inbound-webhook-envelope.v0.schema.json` | **draft** — stabilizuje se s gateway receiverem |
+| `schemas/envelopes/delivery-result.v0.schema.json` | **draft** |
+
+Obálky nesou `envelope_version`. Evoluce je additive-only; nekompatibilní
+změna dostane nové `v<N>` schéma, ne tichou úpravu stávajícího.
+
+## Testy
+
+```bash
+npm test
+```
+
+## Kontext
+
+- `api/docs/architecture/external-io-contract.md` — cílová architektura
+- `api/docs/decisions/0001-external-io-through-platform-infra.md` — proč

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@onlineapps/external-io-contract",
+  "version": "0.1.0",
+  "description": "Shared contract for external HTTP I/O — correlation grammar, HMAC webhook signing, and JSON Schemas for outbound/inbound envelopes. Consumed by api_gateway, api_delivery_dispatcher and pdke_orion-grit.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schemas/*": "./schemas/*"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "webhook",
+    "hmac",
+    "correlation",
+    "envelope",
+    "contract",
+    "external-io"
+  ],
+  "author": "OnlineApps",
+  "license": "PROPRIETARY",
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "test-vectors"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/callbacks/orion-grit.v1.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/external-io/callbacks/orion-grit.v1.schema.json",
+  "title": "pdke_orion-grit delivery callback (v1)",
+  "description": "Tělo webhooku, kterým pdke_orion-grit hlásí výsledek doručení zásilky. Odpovídá funkci buildPayload v pdke_orion-grit/src/lib/webhook/webhookSender.js. Podepsáno HMAC-SHA256 v hlavičce X-Signature. Pozn.: 'status' je slovník ORION-GRITU, ne platformy — na platformní 'delivered|failed' ho překládá cookbook input_mapping, nikdy biz služba.",
+  "type": "object",
+  "required": ["delivery_id", "client_id", "status", "occurred_at"],
+  "additionalProperties": false,
+  "properties": {
+    "delivery_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Identifikátor zásilky přidělený orion-gritem"
+    },
+    "client_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Cílový klient v orion-gritu (např. 'phoenix')"
+    },
+    "doc_type": {
+      "type": ["string", "null"],
+      "description": "Typ dokumentu ve slovníku partnera (INVOIC, DESADV, ORDERS)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["confirmed", "failed", "failed_timeout"],
+      "description": "Slovník orion-gritu. Překlad na platformní delivered|failed dělá cookbook."
+    },
+    "external_ref": {
+      "type": ["string", "null"],
+      "maxLength": 255,
+      "description": "Reference, kterou jsme poslali v odchozím volání (např. fak_id)"
+    },
+    "correlation_id": {
+      "type": ["string", "null"],
+      "pattern": "^[a-z][a-z0-9_]{1,31}:[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$",
+      "description": "Echo naší correlation reference; podle ní gateway zjistí tenanta"
+    },
+    "ack_ref": {
+      "type": ["string", "null"],
+      "maxLength": 255,
+      "description": "Jak bylo doručení potvrzeno (např. 'pickup:file_gone')"
+    },
+    "error": {
+      "type": ["string", "null"],
+      "description": "Text chyby při status != confirmed"
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Kdy událost nastala na straně orion-gritu (ISO 8601)"
+    }
+  }
+}

package/schemas/correlation-ref.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/external-io/correlation-ref.schema.json",
+  "title": "Correlation reference",
+  "description": "Vazba mezi odchozím voláním a příchozím callbackem. Tvar '<biz_ref_type>:<ref>'; dělí se na první dvojtečce, takže ref smí dvojtečku obsahovat. Skládá ji biz služba, vrací echem externí systém, rozebírá ji gateway při resolution tenanta.",
+  "type": "string",
+  "pattern": "^[a-z][a-z0-9_]{1,31}:[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$",
+  "examples": [
+    "ing_job:9a8b7c6d-1234-4567-89ab-cdef01234567",
+    "invoice:INV-2026-00042"
+  ]
+}

package/schemas/envelopes/delivery-result.v0.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/external-io/envelopes/delivery-result.v0.schema.json",
+  "title": "Delivery result (v0 draft)",
+  "description": "Výsledek jednoho pokusu o doručení; dispatcher ho publikuje do fronty delivery.result pro audit a monitoring. DRAFT — stabilizuje se s OAuth2 adapterem (ADR-0001 Track B).",
+  "type": "object",
+  "required": ["envelope_version", "workflow_id", "destination_name", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "envelope_version": { "type": "string", "const": "0" },
+    "workflow_id": { "type": "string", "minLength": 1 },
+    "destination_name": { "type": "string" },
+    "destination_type": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["success", "failed", "retrying", "dead_letter", "skipped"]
+    },
+    "http_status": { "type": ["integer", "null"] },
+    "attempts_made": { "type": "integer", "minimum": 0 },
+    "first_attempt_at": { "type": ["string", "null"], "format": "date-time" },
+    "last_attempt_at": { "type": ["string", "null"], "format": "date-time" },
+    "next_retry_at": { "type": ["string", "null"], "format": "date-time" },
+    "external_reference": {
+      "type": ["string", "null"],
+      "description": "Identifikátor, který partner vrátil v odpovědi (např. delivery_id)"
+    },
+    "error": { "type": ["string", "null"] },
+    "expects_callback": {
+      "type": ["object", "null"],
+      "description": "Vyplněno, pokud tato destination očekává asynchronní callback",
+      "additionalProperties": false,
+      "properties": {
+        "provider_slug": { "type": "string" },
+        "correlation_id_sent": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/schemas/envelopes/inbound-webhook-envelope.v0.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/external-io/envelopes/inbound-webhook-envelope.v0.schema.json",
+  "title": "Inbound webhook envelope (v0 draft)",
+  "description": "Co gateway sestaví z ověřeného příchozího webhooku předtím, než z něj složí vstup workflow. DRAFT — stabilizuje se implementací gateway webhook receiveru (ADR-0001 Track C). Pozn.: samostatná fronta 'webhook.received' se nestaví; gateway publikuje standardní workflow start, tato obálka je vnitřní mezistupeň a podklad pro audit.",
+  "type": "object",
+  "required": ["envelope_version", "provider_slug", "received_at", "correlation"],
+  "additionalProperties": false,
+  "properties": {
+    "envelope_version": { "type": "string", "const": "0" },
+    "webhook_received_id": {
+      "type": "string",
+      "description": "UUID přidělené gateway pro audit trail"
+    },
+    "provider_slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,63}$",
+      "description": "Který provider config zprávu ověřil"
+    },
+    "provider_message_id": {
+      "type": ["string", "null"],
+      "description": "Identifikátor zprávy u partnera; klíč pro deduplikaci"
+    },
+    "received_at": { "type": "string", "format": "date-time" },
+    "correlation": {
+      "type": "object",
+      "required": ["correlation_id", "tenant_id"],
+      "additionalProperties": false,
+      "properties": {
+        "correlation_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]{1,31}:[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$"
+        },
+        "tenant_id": {
+          "type": "integer",
+          "description": "Bez resolvovaného tenanta se nesmí publikovat nic — jinak by šlo o neautorizovaný tok dat"
+        },
+        "workspace_id": { "type": ["integer", "null"] },
+        "resolved_reference": {
+          "type": ["object", "null"],
+          "description": "Co lookup našel (tabulka + uuid), pro audit",
+          "properties": {
+            "table": { "type": "string" },
+            "uuid": { "type": "string" }
+          }
+        }
+      }
+    },
+    "cookbook_trigger": {
+      "type": "object",
+      "required": ["cookbook_slug", "input"],
+      "additionalProperties": false,
+      "properties": {
+        "cookbook_slug": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,63}$",
+          "description": "Název souboru cookbooku (bez přípony) v api/config/cookbooks/"
+        },
+        "input": {
+          "type": "object",
+          "description": "Vstup workflow sestavený podle input_mapping v provider configu; už v platformním slovníku"
+        }
+      }
+    }
+  }
+}

package/schemas/envelopes/outbound-envelope.v0.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.cz/schemas/external-io/envelopes/outbound-envelope.v0.schema.json",
+  "title": "Outbound delivery envelope (v0 draft)",
+  "description": "Normalizovaný tvar, který dispatcher předá destination adapteru. DRAFT — stabilizuje se implementací OAuth2 adapteru (ADR-0001 Track B). Auth se sem NIKDY nedostane v otevřené podobě; adapter si hodnotu vyzvedne ze SecretBoxu podle reference.",
+  "type": "object",
+  "required": ["envelope_version", "workflow_id", "destination", "body"],
+  "additionalProperties": false,
+  "properties": {
+    "envelope_version": { "type": "string", "const": "0" },
+    "workflow_id": { "type": "string", "minLength": 1 },
+    "correlation_id": {
+      "type": ["string", "null"],
+      "pattern": "^[a-z][a-z0-9_]{1,31}:[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$"
+    },
+    "destination": {
+      "type": "object",
+      "required": ["type", "url"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Klíč adapteru v DestinationFactory (webhook, webhook.oauth2_client_credentials, …)"
+        },
+        "name": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "method": { "type": "string", "enum": ["POST", "PUT"], "default": "POST" },
+        "timeout_ms": { "type": "integer", "minimum": 1 },
+        "idempotency_key": {
+          "type": ["string", "null"],
+          "description": "Zpravidla workflow_id — retry nesmí u partnera zdvojit efekt"
+        },
+        "headers": {
+          "type": "object",
+          "description": "Už vyhodnocené hlavičky (bez auth — tu doplní adapter)",
+          "additionalProperties": { "type": "string" }
+        },
+        "auth_ref": {
+          "type": ["object", "null"],
+          "description": "Reference na tajemství, nikdy hodnota",
+          "additionalProperties": true
+        }
+      }
+    },
+    "body": {
+      "type": "object",
+      "description": "Tělo vyhodnocené z body_template v cookbooku"
+    },
+    "audit_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tenant_id": { "type": ["integer", "null"] },
+        "workspace_id": { "type": ["integer", "null"] },
+        "cookbook_name": { "type": ["string", "null"] },
+        "dispatched_at": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/src/correlation.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Correlation reference — gramatika `<biz_ref_type>:<ref>`.
+ *
+ * Correlation id je jediná vazba mezi odchozím voláním a příchozím
+ * callbackem. Skládá ho biz služba (zná byznys význam), propaguje
+ * dispatcher, vrací echem externí systém a rozebírá gateway, aby zjistil
+ * tenanta.
+ *
+ * Tento modul je ZÁMĚRNĚ generický — nezná žádný konkrétní typ reference
+ * (`ing_job`, `invoice`, …). Znalost typu patří té biz službě, která ho
+ * vlastní; ta má vlastní tenkou vrstvu nad touto gramatikou. Kompatibilitu
+ * obou stran drží sdílené vektory v `test-vectors/correlation.json`.
+ *
+ * @module src/correlation
+ */
+
+/** Typ byznys entity: lowercase snake_case, 2..32 znaků. */
+const REF_TYPE_RE = /^[a-z][a-z0-9_]{1,31}$/;
+
+/** Referenční hodnota: bezpečné znaky, 1..128; dvojtečka smí být uvnitř. */
+const REF_VALUE_RE = /^[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$/;
+
+/** Celý correlation id — pro použití v JSON Schema `pattern`. */
+const CORRELATION_RE = /^[a-z][a-z0-9_]{1,31}:[A-Za-z0-9._-][A-Za-z0-9._:-]{0,127}$/;
+
+class CorrelationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CorrelationError';
+    this.code = 'INVALID_CORRELATION_REF';
+  }
+}
+
+/**
+ * Sestaví correlation id.
+ *
+ * @param {string} refType  typ byznys entity, např. 'ing_job'
+ * @param {string} ref      identifikátor v rámci typu
+ * @returns {string}        `<refType>:<ref>`
+ * @throws {CorrelationError}
+ */
+function build(refType, ref) {
+  if (typeof refType !== 'string' || !REF_TYPE_RE.test(refType)) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] refType must match ${REF_TYPE_RE} - got ${JSON.stringify(refType)}`
+    );
+  }
+  if (typeof ref !== 'string' || !REF_VALUE_RE.test(ref)) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] ref must match ${REF_VALUE_RE} - got ${JSON.stringify(ref)}`
+    );
+  }
+  return `${refType}:${ref}`;
+}
+
+/**
+ * Rozebere correlation id na složky. Dělí se na PRVNÍ dvojtečce, takže
+ * `ing_job:a:b` → typ `ing_job`, ref `a:b`.
+ *
+ * @param {string} correlationId
+ * @returns {{ refType: string, ref: string }}
+ * @throws {CorrelationError}
+ */
+function parse(correlationId) {
+  if (typeof correlationId !== 'string' || correlationId.length === 0) {
+    throw new CorrelationError(
+      '[external-io-contract/correlation] correlation_id must be a non-empty string'
+    );
+  }
+  const sep = correlationId.indexOf(':');
+  if (sep <= 0 || sep === correlationId.length - 1) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] correlation_id must be "<biz_ref_type>:<ref>" - got ${JSON.stringify(correlationId)}`
+    );
+  }
+  const refType = correlationId.slice(0, sep);
+  const ref = correlationId.slice(sep + 1);
+  if (!REF_TYPE_RE.test(refType)) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] refType part must match ${REF_TYPE_RE} - got ${JSON.stringify(refType)}`
+    );
+  }
+  if (!REF_VALUE_RE.test(ref)) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] ref part must match ${REF_VALUE_RE} - got ${JSON.stringify(ref)}`
+    );
+  }
+  return { refType, ref };
+}
+
+/**
+ * Nevýjimková varianta `parse` — pro validační cesty, kde je nevalidní
+ * vstup očekávaný stav (příchozí webhook od cizí strany), ne chyba kódu.
+ *
+ * @param {string} correlationId
+ * @returns {boolean}
+ */
+function isValid(correlationId) {
+  return typeof correlationId === 'string' && CORRELATION_RE.test(correlationId);
+}
+
+/**
+ * Vytáhne referenci, jen pokud je očekávaného typu. Callback pro cizí
+ * bounded context (`invoice:…` tam, kde se čeká `ing_job:…`) tak nikdy
+ * neprojde omylem.
+ *
+ * @param {string} correlationId
+ * @param {string} expectedRefType
+ * @returns {string} samotná reference
+ * @throws {CorrelationError}
+ */
+function refOfType(correlationId, expectedRefType) {
+  const { refType, ref } = parse(correlationId);
+  if (refType !== expectedRefType) {
+    throw new CorrelationError(
+      `[external-io-contract/correlation] expected refType "${expectedRefType}" - got "${refType}" ` +
+      '(correlation_id belongs to another bounded context)'
+    );
+  }
+  return ref;
+}
+
+module.exports = {
+  build,
+  parse,
+  isValid,
+  refOfType,
+  CorrelationError,
+  patterns: Object.freeze({
+    REF_TYPE_RE,
+    REF_VALUE_RE,
+    CORRELATION_RE
+  })
+};

package/src/hmac.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Webhook payload signing — HMAC-SHA256 nad raw tělem requestu.
+ *
+ * Schéma (zmrazené, jazykově neutrální):
+ *   hlavička `X-Signature: sha256=<lowercase hex>`
+ *   hodnota  = HMAC-SHA256(raw body bytes, shared secret)
+ *
+ * Podepisuje se VŽDY přesně ten bajtový obsah, který jde po drátě —
+ * nikdy znovu-serializovaný objekt. Kdo ověřuje, musí mít raw tělo
+ * (v Expressu: `express.json({ verify })` nebo `express.raw`), jinak
+ * se podpis rozejde na pořadí klíčů či mezerách.
+ *
+ * @module src/hmac
+ */
+
+const { createHmac, timingSafeEqual } = require('node:crypto');
+
+/** Název hlavičky, ve které podpis cestuje. */
+const SIGNATURE_HEADER = 'X-Signature';
+
+/** Prefix hodnoty hlavičky — drží prostor pro budoucí algoritmy. */
+const SIGNATURE_PREFIX = 'sha256=';
+
+function assertBody(rawBody) {
+  if (typeof rawBody !== 'string' && !Buffer.isBuffer(rawBody)) {
+    throw new TypeError(
+      '[external-io-contract/hmac] rawBody must be a string or Buffer - ' +
+      'sign and verify the exact bytes sent over the wire, never a re-serialized object'
+    );
+  }
+}
+
+function assertSecret(secret) {
+  if (typeof secret !== 'string' || secret.length === 0) {
+    throw new TypeError('[external-io-contract/hmac] secret must be a non-empty string');
+  }
+}
+
+/**
+ * Spočítá hodnotu podpisové hlavičky.
+ *
+ * @param {string|Buffer} rawBody  přesné bajty těla requestu
+ * @param {string} secret          sdílené tajemství (z SecretBoxu, nikdy z configu)
+ * @returns {string}               `sha256=<hex>` — hodnota pro hlavičku X-Signature
+ */
+function sign(rawBody, secret) {
+  assertBody(rawBody);
+  assertSecret(secret);
+  const digest = createHmac('sha256', secret)
+    .update(Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8'))
+    .digest('hex');
+  return `${SIGNATURE_PREFIX}${digest}`;
+}
+
+/**
+ * Ověří podpis proti raw tělu. Konstantní v čase vůči obsahu podpisu.
+ *
+ * Vrací `false` místo výjimky pro každý případ „nesedí to" (chybí
+ * hlavička, jiný prefix, jiná délka, jiná hodnota) — volající tak má
+ * jednu větev pro odmítnutí. Výjimka je jen pro programátorskou chybu
+ * (nesmyslný typ těla nebo prázdný secret).
+ *
+ * @param {string|Buffer} rawBody   přesné bajty přijatého těla
+ * @param {string} secret           sdílené tajemství
+ * @param {string} headerValue      obsah hlavičky X-Signature
+ * @returns {boolean}
+ */
+function verify(rawBody, secret, headerValue) {
+  assertBody(rawBody);
+  assertSecret(secret);
+  if (typeof headerValue !== 'string' || !headerValue.startsWith(SIGNATURE_PREFIX)) {
+    return false;
+  }
+  const expected = Buffer.from(sign(rawBody, secret), 'utf8');
+  const received = Buffer.from(headerValue, 'utf8');
+  // timingSafeEqual vyžaduje shodnou délku; rozdílná délka = nesedí
+  if (expected.length !== received.length) return false;
+  return timingSafeEqual(expected, received);
+}
+
+module.exports = { sign, verify, SIGNATURE_HEADER, SIGNATURE_PREFIX };

package/src/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * @onlineapps/external-io-contract
+ *
+ * Sdílený kontrakt pro HTTP komunikaci s vnějším světem. Používají ho:
+ *   - api_gateway               — ověření podpisu příchozích webhooků,
+ *                                 rozbor correlation reference
+ *   - api_delivery_dispatcher   — podpis odchozích volání, validace obálek
+ *   - pdke_orion-grit           — podpis odchozích callbacků
+ *
+ * Zdroj pravdy jsou JSON Schemata v `schemas/`; kód je jen jejich
+ * spustitelná podoba. Biz služby tuhle knihovnu NEPOUŽÍVAJÍ — dostávají
+ * a vracejí prosté objekty, transport neznají.
+ *
+ * @module @onlineapps/external-io-contract
+ */
+
+const correlation = require('./correlation');
+const hmac = require('./hmac');
+const { validators, schemas } = require('./validators');
+
+module.exports = {
+  correlation,
+  hmac,
+  validators,
+  schemas,
+  SIGNATURE_HEADER: hmac.SIGNATURE_HEADER
+};

package/src/validators.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Validátory kompilované ze schémat při načtení modulu.
+ *
+ * Schémata v `schemas/` jsou zdroj pravdy; tenhle modul je jen jejich
+ * spustitelná podoba. Kompilace probíhá jednou za život procesu.
+ *
+ * @module src/validators
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+
+const correlationRefSchema = require('../schemas/correlation-ref.schema.json');
+const orionGritCallbackV1 = require('../schemas/callbacks/orion-grit.v1.schema.json');
+const outboundEnvelopeV0 = require('../schemas/envelopes/outbound-envelope.v0.schema.json');
+const inboundWebhookEnvelopeV0 = require('../schemas/envelopes/inbound-webhook-envelope.v0.schema.json');
+const deliveryResultV0 = require('../schemas/envelopes/delivery-result.v0.schema.json');
+
+const schemas = Object.freeze({
+  correlationRef: correlationRefSchema,
+  orionGritCallbackV1,
+  outboundEnvelopeV0,
+  inboundWebhookEnvelopeV0,
+  deliveryResultV0
+});
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+/**
+ * Jedna chyba validace v čitelné podobě.
+ * @typedef {{ path: string, message: string }} ValidationIssue
+ */
+
+/**
+ * Výsledek validace. `valid: false` NENÍ výjimka — nevalidní vstup od
+ * externí strany je očekávaný stav, ne chyba kódu.
+ * @typedef {{ valid: boolean, errors: ValidationIssue[] }} ValidationResult
+ */
+
+function toIssues(ajvErrors) {
+  if (!ajvErrors) return [];
+  return ajvErrors.map((e) => ({
+    path: e.instancePath === '' ? '/' : e.instancePath,
+    message: e.message || 'invalid'
+  }));
+}
+
+function compile(schema, label) {
+  const validateFn = ajv.compile(schema);
+  /**
+   * @param {*} data
+   * @returns {ValidationResult}
+   */
+  return function validate(data) {
+    const ok = validateFn(data);
+    return ok
+      ? { valid: true, errors: [] }
+      : { valid: false, errors: toIssues(validateFn.errors), schema: label };
+  };
+}
+
+const validators = Object.freeze({
+  correlationRef: compile(correlationRefSchema, 'correlation-ref'),
+  orionGritCallbackV1: compile(orionGritCallbackV1, 'callbacks/orion-grit.v1'),
+  outboundEnvelopeV0: compile(outboundEnvelopeV0, 'envelopes/outbound-envelope.v0'),
+  inboundWebhookEnvelopeV0: compile(inboundWebhookEnvelopeV0, 'envelopes/inbound-webhook-envelope.v0'),
+  deliveryResultV0: compile(deliveryResultV0, 'envelopes/delivery-result.v0')
+});
+
+module.exports = { validators, schemas };

package/test-vectors/correlation.json

@@ -0,0 +1,49 @@
+{
+  "$comment": "Sdílené vektory gramatiky correlation reference. Tuto knihovnu používá gateway; biz služby mají vlastní tenkou implementaci nad toutéž gramatikou (např. api_biz/ingest/src/lib/correlation.js). Runtime závislost mezi nimi NENÍ — kompatibilitu drží právě tyto vektory. Když se změní gramatika, musí se změnit tady i tam, jinak testy padnou.",
+  "valid": [
+    {
+      "input": "ing_job:9a8b7c6d-1234-4567-89ab-cdef01234567",
+      "refType": "ing_job",
+      "ref": "9a8b7c6d-1234-4567-89ab-cdef01234567",
+      "note": "typický případ — biz-ingest job"
+    },
+    {
+      "input": "invoice:INV-2026-00042",
+      "refType": "invoice",
+      "ref": "INV-2026-00042",
+      "note": "jiný bounded context, ref není uuid"
+    },
+    {
+      "input": "ing_job:a:b:c",
+      "refType": "ing_job",
+      "ref": "a:b:c",
+      "note": "dělí se na PRVNÍ dvojtečce, ref smí další obsahovat"
+    },
+    {
+      "input": "raw_doc:abc",
+      "refType": "raw_doc",
+      "ref": "abc",
+      "note": "snake_case v typu"
+    },
+    {
+      "input": "ing_job:ABC.def_ghi-123",
+      "refType": "ing_job",
+      "ref": "ABC.def_ghi-123",
+      "note": "v referenci jsou povolené tečka, podtržítko, pomlčka a velká písmena"
+    }
+  ],
+  "invalid": [
+    { "input": "IngJob:abc", "reason": "velká písmena v typu" },
+    { "input": "1job:abc", "reason": "typ začíná číslicí" },
+    { "input": "_job:abc", "reason": "typ začíná podtržítkem" },
+    { "input": "ing-job:abc", "reason": "pomlčka v typu" },
+    { "input": "i:abc", "reason": "typ kratší než 2 znaky" },
+    { "input": "ing_job", "reason": "chybí dvojtečka" },
+    { "input": ":abc", "reason": "prázdný typ" },
+    { "input": "ing_job:", "reason": "prázdná reference" },
+    { "input": "ing_job::abc", "reason": "reference začíná dvojtečkou" },
+    { "input": "ing_job:a b", "reason": "mezera v referenci" },
+    { "input": "ing_job:../etc/passwd", "reason": "lomítko v referenci (path traversal)" },
+    { "input": "", "reason": "prázdný řetězec" }
+  ]
+}

package/test-vectors/hmac.json

@@ -0,0 +1,26 @@
+{
+  "$comment": "Known-good HMAC-SHA256 vectors generated by an INDEPENDENT implementation (openssl dgst -sha256 -hmac) on 2026-08-19. They freeze the wire format: any change to the signing scheme breaks these tests on purpose. Regenerate only when the scheme is intentionally versioned. Command: printf '%s' \"<body>\" | openssl dgst -sha256 -hmac \"<secret>\"",
+  "algorithm": "HMAC-SHA256",
+  "header": "X-Signature",
+  "value_format": "sha256=<lowercase hex>",
+  "vectors": [
+    {
+      "name": "typical orion-grit callback body",
+      "secret": "test-secret-1234567890abcdef",
+      "body": "{\"delivery_id\":\"9a8b7c6d\",\"status\":\"confirmed\"}",
+      "expected_hex": "e249e8f33480153865e9969d148442d2911520c28da114ebf462f862606aa6bb"
+    },
+    {
+      "name": "empty JSON object",
+      "secret": "another-secret-key-for-vectors",
+      "body": "{}",
+      "expected_hex": "b98e92437622a66fce33026d4407af51ce15b34ca7b2e4847336650fe284b58e"
+    },
+    {
+      "name": "utf8 in both secret and body (diacritics must be signed as utf8 bytes)",
+      "secret": "utf8-secret-ěščřž",
+      "body": "{\"note\":\"diakritika ěščřžýáíé\"}",
+      "expected_hex": "ef802847967892dc388df4eddbcea26f37478bc82e11852d005dfc2c9e620c05"
+    }
+  ]
+}