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

source/conf.py

@@ -0,0 +1,10 @@
+project = "NATS Service Endpoints"
+copyright = "2026, Verae"
+author = "Verae / George Lambert"
+extensions = []
+html_theme = "alabaster"
+latex_engine = "pdflatex"
+latex_documents = [
+    ("index", "nats-service-endpoints.tex", "NATS Service Endpoints", "Verae", "manual"),
+]
+latex_elements = {"papersize": "letterpaper", "pointsize": "11pt"}

source/config.rst

@@ -0,0 +1,18 @@
+Signed configuration
+====================
+
+A config file is unusable unless it is an Ed25519 wrapper::
+
+   { "payload": { ... }, "sig": { "alg": "ed25519", "key_id": "...", "signature": "hex" } }
+
+Select algorithms inside **payload** (the signed object):
+
+* ``crypto.mode``: ``npe`` | ``lab-xor`` | ``plain-lab``
+* ``routing.mode``: ``passthrough``
+* ``admin.history_cube``: cube id for admin-history
+* ``crypto.system_key_id``: system public key id
+* ``logging.mode``: ``summary``
+
+After an admin console change: sign again, then append previous file, new
+file, and unified diff to the admin-history DataCube
+(``verae.admin.history.append``).

source/endpoints.rst

@@ -0,0 +1,17 @@
+Endpoint records
+================
+
+Full JSON: ``catalog/endpoints.json``. PFC import:
+``catalog/pfc-derived.json`` from
+https://git.georgelambert.org/marchon/peergos-for-compliance/src/branch/main/schemas/subjects.json
+
+Secure-messaging subjects
+-------------------------
+
+* ``verae.sm.send`` -- passthrough deliver; from console/leaf; reject unsigned
+  config and empty ciphertext (unless ``plain-lab``).
+* ``verae.sm.dead`` -- dead letter; Network Error Bundle in body.
+* ``verae.sm.error`` -- emit bundle: ``ct_sender`` + ``ct_system``.
+* ``verae.sm.log.summary`` -- central summaries (codes, lookup_id, dest_class).
+* ``verae.admin.config.sign`` -- Ed25519 wrap; unsigned files rejected.
+* ``verae.admin.history.append`` -- prev, new, unified diff on DataCube chain.

source/errors.rst

@@ -0,0 +1,13 @@
+Errors and Network Error Bundle
+================================
+
+Never put the intended recipient payload in an error object.
+
+* **ct_sender** -- failure status encrypted so **only the sender** can read it.
+* **ct_system** -- bounce report encrypted to the **system public key** for
+  logging/recovery (lookup_id, error_code, dest_class, respond flag).
+* **Dead letter** -- ``verae.sm.dead`` with the same bundle.
+* **Central log** -- ``verae.sm.log.summary``: codes only.
+
+The sender identifies the original message with ``lookup_id``, not by
+decrypting what they sent.

source/index.rst

@@ -0,0 +1,29 @@
+NATS Service Endpoints
+======================
+
+Canonical catalog for Verae / PFC / secure-messaging on
+https://git.georgelambert.org/marchon/nats-service-endpoints
+
+The NATS broker is **untrusted**. Production E2E is NPE (HPKE). Lab may use
+``pfc-lab-xor``. This is **not** a HIPAA/SOC 2/ISO certificate.
+
+Related: `system-git-sync <https://git.georgelambert.org/marchon/system-git-sync>`_,
+`secure-messaging <https://git.georgelambert.org/marchon/secure-messaging>`_,
+`peergos-for-compliance <https://git.georgelambert.org/marchon/peergos-for-compliance>`_.
+
+.. toctree::
+   :maxdepth: 2
+
+   passthrough
+   endpoints
+   errors
+   config
+   tracing
+
+Passthrough
+-----------
+
+Destination mailbox id and the NATS subject may be in the clear so routers
+can work. The **body** is ciphertext. After send, the sender cannot open
+that ciphertext; they keep a ``lookup_id`` only. The same rule applies to
+the responder.

source/passthrough.rst

@@ -0,0 +1,15 @@
+Passthrough routing
+===================
+
+::
+
+   sender --(ct, to, lookup_id)--> NATS subject
+        |                              |
+        |                              v
+        |                         sm-leaf / NPE
+        |                              |
+        +---- lookup_id only ----      v
+                                 recipient mailbox
+
+Header (clear): ``to``, ``from_lookup_id``, ``alg``, ``error_token``.
+Body: ciphertext. Broker must not log ``ct``.

source/tracing.rst

@@ -0,0 +1,18 @@
+Message tracing
+===============
+
+Happy path::
+
+   1. Load signed config (reject if unsigned).
+   2. seal(body) -> envelope with to + ct + lookup_id.
+   3. Publish verae.sm.send.
+   4. Leaf acks {accepted:true, lookup_id}.
+   5. Recipient opens ct with NPE (prod) or lab-xor (lab).
+
+Failure path::
+
+   1. Leaf cannot deliver.
+   2. Build Network Error Bundle (no mail body).
+   3. Publish verae.sm.dead and verae.sm.error.
+   4. Sender opens ct_sender; ops opens ct_system.
+   5. Summary to verae.sm.log.summary.