{
  "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "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",
      "timeout_sec": 5.0,
      "filter": "passthrough dest/subject clear; reject missing to, empty ct, plaintext body"
    },
    {
      "name": "verae.npe.dir.lookup",
      "pattern": "request-reply",
      "for": "Look up an endpoint HPKE public key",
      "from": [
        "any npe endpoint"
      ],
      "to": [
        "pubkey-directory"
      ],
      "in": {
        "handle": "string"
      },
      "out": {
        "enc_pk": "hex",
        "inbox": "npe.inbox.*"
      },
      "encryption": "public keys only (not content)",
      "reject": [
        "unknown handle"
      ],
      "dead": "none",
      "timeout_sec": 5.0,
      "filter": "never returns private keys or message bodies"
    },
    {
      "name": "verae.npe.dir.list",
      "pattern": "request-reply",
      "for": "List all endpoint public keys so availability is visible",
      "from": [
        "any npe endpoint"
      ],
      "to": [
        "pubkey-directory"
      ],
      "in": {},
      "out": {
        "handles": "array",
        "keys": "public records"
      },
      "encryption": "public keys only (not content)",
      "reject": [],
      "dead": "none",
      "timeout_sec": 5.0,
      "filter": "public directory; no private keys"
    }
  ]
}