MEMEH — Security

Security Overview

MEMEH enforces identity, integrity, replay protection, and operational governance at each integration boundary. Fintech requests are authenticated with HMAC. Participant adapter callbacks are authenticated with Ed25519 signatures.

Identity & integrity

Every message is signed. Any change to method, path, timestamp, nonce, or body invalidates verification.

Replay protection

Timestamp + nonce are mandatory. Nonces are single-use (multi-node safe via Redis in production).

Idempotency

Idempotency keys prevent duplicate processing and enable safe retries. Conflicts are rejected.

Operational governance

Credentials and keys are issued/rotated via controlled workflows with audit logs (actor, IP, before/after).

Security Boundary Matrix

The primitive used depends on the boundary. Bank/IPS outcomes are higher impact, therefore adapter callbacks use public-key signatures.

Boundary	Primitive	Why	Required headers
Fintech → MEMEH Core	HMAC-SHA256	Broad compatibility for fintechs; secure when combined with strict replay protection, idempotency, and key rotation.	X-Client-ID X-Key-Id X-Signature X-Timestamp X-Nonce X-Idempotency-Key
MEMEH Core → Participant Adapter	HMAC-SHA256	Service-to-service control; deterministic signing for instruction dispatch; rotation via key-id.	X-Client-ID X-Key-Id X-Signature X-Timestamp X-Nonce X-Idempotency-Key
Participant Adapter → MEMEH Core (Callbacks)	Ed25519 (public-key signatures)	Bank/IPS outcomes are authoritative; avoids shared secrets in Core; scales cleanly across many participants/adapters.	X-Adapter-ID X-Key-Id X-Signature X-Timestamp X-Nonce

Note

Ed25519 signing is not mTLS. mTLS can be added for transport hardening, but message-level signatures remain valid through gateways and proxies.

Canonical Signing String

Both HMAC and Ed25519 use the same canonical structure. The signature is computed over this string.

Canonical

METHOD
PATH
TIMESTAMP
NONCE
BODY

Timestamp skew

Requests outside the accepted skew window are rejected (401).

Nonce single-use

Reused nonces are rejected (401). Nonces should be random and unique.

Idempotency conflict

Same idempotency key with a different payload is rejected (409).

Deterministic body

Sign the raw request body exactly as sent; avoid reformatting differences across systems.

Callbacks (pain.014) Integrity

Participant adapters send authoritative RTP lifecycle outcomes into MEMEH Core. Callbacks are verified using Ed25519 public keys from the Control Plane bundle.

Example callback payload (JSON mapping)

Callback JSON

{
  "Document": {
    "CdtrPmtActvtnReqStsRpt": {
      "GrpHdr": {
        "MsgId": "MSG-001",
        "CreDtTm": "2026-03-30T10:00:00Z"
      },
      "OrgnlPmtInfAndSts": {
        "TxInfAndSts": {
          "OrgnlEndToEndId": "TXN-123",
          "TxSts": "ACSP"
        }
      }
    }
  }
}

Why callback signing is stricter

Callback status changes (PAID/REJECTED/CANCELLED) are high-impact outcomes. Public-key verification avoids shared secrets in Core and scales across many IPS participants.

Status mapping

TxSts	Partner status	Meaning
RCVD	RECEIVED	Request received/acknowledged; awaiting decision.
ACSP	PAID	Paid/completed outcome (terminal).
RJCT	REJECTED	Rejected outcome (terminal).
CANC	CANCELLED	Cancelled outcome (terminal).

Lifecycle Integrity

MEMEH enforces a strict lifecycle. Terminal states cannot be downgraded. Invalid transitions return 409 while still recording events for audit.

Current	Allowed next	Notes
RCVD	RCVD, ACSP, RJCT, CANC	Normal progression to terminal states.
ACSP	ACSP	Terminal; no downgrades allowed.
RJCT	RJCT	Terminal; no downgrades allowed.
CANC	CANC	Terminal; no downgrades allowed.

Key Rotation

Rotation is mandatory for enterprise operations. Always use an overlap window to avoid downtime.

HMAC rotation

Procedure

HMAC rotation (Fintech / Core → Adapter)
1) Add new key_id + secret in Control Plane and mark Active (keep old key active).
2) Roll client/service to sign with the new key_id.
3) Monitor signature failures and 401 rates.
4) Deactivate old key after the rollout window.

Ed25519 rotation (callbacks)

Procedure

Ed25519 rotation (Adapter callbacks)
1) Generate new Ed25519 keypair in adapter environment (private key never leaves adapter).
2) Register the public key in Control Plane as Active + Primary (keep old key active).
3) Deploy adapter to sign callbacks with new key_id.
4) Deactivate old key after rollout window.

Operational Security

Credential hygiene

Never email secrets. Store in KMS/Vault where possible. Rotate on personnel/vendor change.

Incident signals

Alert on spikes in 401, 409, 422; callback verification failures; DLQ growth; bundle refresh failures.

Audit trail

All sensitive changes must be auditable (actor + IP + before/after + reason).

Environment separation

Sandbox and production-path keys are distinct. Never reuse keys across environments.