S05: NATS endpoint catalog, passthrough and error-bundle docs

catalog/endpoints.json

@@ -0,0 +1,93 @@
+{
+  "version": "1.0.0",
+  "broker": "untrusted",
+  "git": "https://git.georgelambert.org/marchon/nats-service-endpoints",
+  "related": [
+    "https://git.georgelambert.org/marchon/secure-messaging",
+    "https://git.georgelambert.org/marchon/peergos-for-compliance",
+    "https://git.georgelambert.org/marchon/system-git-sync"
+  ],
+  "encryption_modes": {
+    "npe": "HPKE X25519-HKKE-SHA256-ChaCha20-Poly1305; dest inbox npe.inbox.<id_fp>",
+    "lab-xor": "pfc-lab-xor PSK; lab only",
+    "plain-lab": "JSON body; lab tests only",
+    "passthrough": "destination and NATS subject in the clear; payload ciphertext"
+  },
+  "endpoints": [
+    {
+      "name": "verae.sm.send",
+      "pattern": "core",
+      "for": "Deliver a passthrough secure message to a mailbox identity",
+      "from": ["console", "go-leaf", "access-api"],
+      "to": ["sm-leaf", "npe sidecar"],
+      "in": {
+        "header": ["to", "from_lookup_id", "alg", "error_token"],
+        "body": "ciphertext (not readable by broker or sender after send)"
+      },
+      "out": {"ack": {"lookup_id": "string", "accepted": true}},
+      "encryption": "passthrough-full-body",
+      "reject": ["missing to", "unsigned config", "alg not in signed config", "empty ciphertext when mode!=plain-lab"],
+      "dead": "verae.sm.dead"
+    },
+    {
+      "name": "verae.sm.dead",
+      "pattern": "core",
+      "for": "Dead-letter failed service requests",
+      "from": ["sm-leaf"],
+      "to": ["error-handler"],
+      "in": {"header": ["error_code", "lookup_id", "to"], "body": "Network Error Bundle"},
+      "out": "none",
+      "encryption": "system-key bundle plus sender-only status",
+      "reject": ["bundle missing ct_system"],
+      "dead": "none"
+    },
+    {
+      "name": "verae.sm.error",
+      "pattern": "core",
+      "for": "Build and emit a Network Error Bundle",
+      "from": ["sm-leaf", "pfc-admin"],
+      "to": ["sender (ct_sender)", "system logger (ct_system)"],
+      "in": {"error_code": "string", "lookup_id": "string", "dest_class": "mailbox|service"},
+      "out": {"ct_sender": "box to sender", "ct_system": "box to system public key"},
+      "encryption": "no recipient payload; bounce metadata only",
+      "reject": ["unknown error_code"],
+      "dead": "verae.sm.log.summary"
+    },
+    {
+      "name": "verae.sm.log.summary",
+      "pattern": "core",
+      "for": "Central log summaries of system failures (no message bodies)",
+      "from": ["sm-leaf", "pfc-admin"],
+      "to": ["central-log"],
+      "in": {"code": "string", "lookup_id": "string", "dest_class": "string"},
+      "out": "ack",
+      "encryption": "summary plaintext allowed; never ciphertext of mail",
+      "reject": ["body-like fields present"],
+      "dead": "none"
+    },
+    {
+      "name": "verae.admin.config.sign",
+      "pattern": "core",
+      "for": "Sign a new configuration payload; reject unsigned files at load",
+      "from": ["pfc-console", "pfc-config TUI"],
+      "to": ["admin-history cube"],
+      "in": {"payload": "object", "prev_signed": "object|null"},
+      "out": "signed wrapper",
+      "encryption": "Ed25519 signature; payload may be lab-clear",
+      "reject": ["bad key_id", "canonical JSON mismatch"],
+      "dead": "verae.sm.dead"
+    },
+    {
+      "name": "verae.admin.history.append",
+      "pattern": "core",
+      "for": "Append prev file, new file, and unified diff to DataCube admin-history",
+      "from": ["verae.admin.config.sign"],
+      "to": ["pfc CubeStore kind=admin-history"],
+      "in": {"prev": "string", "new": "string", "diff": "string", "actor": "string"},
+      "out": "chain row",
+      "encryption": "chain hashes; not NPE (admin audit)",
+      "reject": ["empty actor"],
+      "dead": "none"
+    }
+  ]
+}

catalog/schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "NATS-Service-Endpoints catalog",
+  "type": "object",
+  "required": ["version", "endpoints"],
+  "properties": {
+    "version": {"type": "string"},
+    "endpoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "for", "from", "to", "in", "out", "encryption", "reject"],
+        "properties": {
+          "name": {"type": "string"},
+          "pattern": {"type": "string"},
+          "for": {"type": "string"},
+          "from": {"type": "array", "items": {"type": "string"}},
+          "to": {"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
+          "in": {},
+          "out": {},
+          "encryption": {"type": "string"},
+          "reject": {"type": "array", "items": {"type": "string"}},
+          "dead": {"type": "string"}
+        }
+      }
+    }
+  }
+}