POST / dispatcher must read attachments from CESR-ATTACHMENT header (keripy wire format)

[seriouscoderone]

Summary

POST / returns the signed receipt only when the request body is the full CESR stream — event JSON plus all inline attachments (signatures, seal-source couples, datetime). Standard keripy HTTP-witness clients (keri.app.agenting.HTTPMessenger → keri.app.agenting.streamCESRRequests) don't put attachments in the body: they split them into the CESR-ATTACHMENT HTTP header and send only the event JSON in the body. The kerihost witness dispatcher reads only the body, sees no inline signatures, can't verify the event, and returns HTTP 204 No Content with an empty body instead of a signed receipt.

End-to-end effect: every Locksmith wallet (and any other standard keripy wallet using stock WitnessReceiptor) ends up with baser.wigs = 0 on inceptions it submits to keri.host. The wallet's WitnessReceiptor.receiptDo then loops indefinitely on "Waiting for witness receipts for ...", even though the Lambda fires and accepts the event.

This is the fourth in the keri.host compatibility series:

• /oobi/<aid>/witness should serve witness-role endpoint replies, not just inception #1 — /oobi/<aid>/witness should serve witness-role endpoint replies ✅ landed
• POST / should route to a CESR-typed dispatcher (standard keripy wallets post to URL root, not /process) #2 — POST / should route to a CESR-typed dispatcher ✅ landed
• POST / must return signed witness receipt in response body, not HTTP 204 empty #3 — POST / must return signed receipts in the response body ✅ landed (verified working when sigs are inline in body)
• POST / dispatcher must read attachments from CESR-ATTACHMENT header (keripy wire format) #4 — POST / dispatcher must read attachments from the CESR-ATTACHMENT HTTP header, not just the body ← this issue

Diagnostic

Standard keripy streamCESRRequests in keri/app/agenting.py (keripy 2.0.0.dev6) splits each CESR event into the request body (the event JSON or msgpack) and the CESR-ATTACHMENT header (the attachments — signatures, seal source couples, datetime stamps, etc.). I captured a real wallet-produced request:

POST /
Content-Type: application/cesr
Content-Length: 345                                     ← only the JSON event
CESR-ATTACHMENT: -VAn-AABAAA...AAA1AAG2026-05-22T22c05c55d990493p00c00
CESR-DESTINATION: BNbRfMPQQge6wKO0uof9Y0e_QYOfiF08k9drc6pOgzjt

{"v":"KERI10JSON000159_","t":"icp","d":"EE56...","i":"EE56...",...}

The body has zero CESR attachments. All signatures + the datetime stamp are in the CESR-ATTACHMENT header value as a CESR-encoded counter group.

Repro

Same EE56 event posted two different ways:

Way 1: everything inline in body (curl --data-binary @file) → 200 + receipt

$ curl -X POST "https://witness.keri.host/" \
       -H "Content-Type: application/cesr" \
       --data-binary @/tmp/inception-full.cesr     # 505 bytes: event + sig + datetime
HTTP/2 200
content-type: application/cesr
content-length: 281

<rct event + -CAB<witness eid><signature> attachment>

Way 2: keripy wire format (body=event-only, sigs in header) → 204 empty

$ curl -X POST "https://witness.keri.host/" \
       -H "Content-Type: application/cesr" \
       -H "CESR-DESTINATION: BNbRfMPQQge6wKO0uof9Y0e_QYOfiF08k9drc6pOgzjt" \
       -H "CESR-ATTACHMENT: -VAn-AABAAA..." \
       --data-binary @/tmp/event-only.json          # 345 bytes: just the icp JSON
HTTP/2 204
content-length: 0

Same event SAID (EE56hav20fixmmszoObJomTHBLPirN_yCs2h8NtrQFTZ), same witness, same destination. Only the wire-format split differs. The receipt only comes back for Way 1.

Locksmith's wallet always sends Way 2. The Lambda IS invoked (verified via CloudWatch), it just returns 204 because it has nothing to verify.

Reference implementation

keri.app.indirecting.HttpEnd.on_post (keripy reference HTTP-witness server) reassembles the full CESR stream from body + headers['CESR-ATTACHMENT'] before parsing. Roughly:

async def on_post(self, req, rep):
    cr = httping.parseCesrHttpRequest(req=req)
    # cr.payload is the JSON event; cr.attachments is the CESR-ATTACHMENT header value
    full_stream = (
        json.dumps(cr.payload).encode() if isinstance(cr.payload, dict)
        else cr.payload
    ) + cr.attachments
    self.exc.parser.parse(ims=bytearray(full_stream), ...)

The parseCesrHttpRequest helper in keri.app.httping does the body+header reassembly. Any standard keripy witness binary built on top of keripy will use this path implicitly.

Suggested fix

In the kerihost witness-handler Lambda's request-decoding step (the part that runs before the CESR parser), reassemble the full stream from body + CESR-ATTACHMENT header before passing to the parser:

// Pseudocode for the Rust handler
let body = event.body.unwrap_or_default();
let attachment = event.headers
    .get("CESR-ATTACHMENT")
    .or_else(|| event.headers.get("cesr-attachment"))    // case-insensitive
    .map(|v| v.as_bytes())
    .unwrap_or_default();

let full_stream: Vec<u8> = [body.as_bytes(), attachment].concat();
parser.parse(&full_stream)?;

After that change, the existing receipt-on-fresh-event logic (#3's fix) will see the inline signatures it needs to verify, and standard keripy wallets will get the receipt they expect.

Test that would have caught this

def test_post_root_parses_cesr_attachment_header():
    # Build an inception event using a hab
    icp_serder, sigs = hab.makeOwnEvent(sn=0)
    body = icp_serder.raw                       # just the JSON
    attachment = sigs                           # signatures as CESR

    response = client.post(
        "/",
        headers={
            "Content-Type": "application/cesr",
            "CESR-DESTINATION": witness_pre,
            "CESR-ATTACHMENT": attachment.decode(),
        },
        data=body,
    )

    assert response.status_code == 200, "should return 200 + receipt for split-attachment request"
    assert response.headers["content-type"] == "application/cesr"
    assert len(response.content) > 0, "should include the receipt CESR in the body"
    # Parse the response and confirm it's a `rct` event + -CAB attachment

This complements the existing test_post_root_returns_synchronous_witness_receipt (which appears to test the all-in-body shape only).

Environment

• Witness AID: BNbRfMPQQge6wKO0uof9Y0e_QYOfiF08k9drc6pOgzjt
• Deployment: serverless-witness stack in us-east-1
• keripy: 2.0.0.dev6
• Reference for the wire-format expectations: keri.app.agenting.streamCESRRequests (sender) and keri.app.indirecting.HttpEnd.on_post (receiver)
• Test AID: EE56hav20fixmmszoObJomTHBLPirN_yCs2h8NtrQFTZ in joseph vault — wits=[BNbRf...], toad=1, wigs=0

[seriouscoderone]

Verified fixed in production via kli on 2026-05-29.

The witness handler now reads the CESR-ATTACHMENT header and reassembles the full stream before parsing, exactly matching the reference keri.app.indirecting.HttpEnd.on_post shape the OP cited.

End-to-end repro via the actual keripy CLI (the canonical client whose streamCESRRequests always splits the body and CESR-ATTACHMENT header):

mkdir /tmp/kli-witness-test && cd /tmp/kli-witness-test
export HOME=/tmp/kli-witness-test

cat > alice-icp.json <<EOF2
{"transferable": true, "wits": ["BNbRfMPQQge6wKO0uof9Y0e_QYOfiF08k9drc6pOgzjt"],
 "toad": 1, "icount": 1, "ncount": 1, "isith": "1", "nsith": "1"}
EOF2

kli init --name testwitclient --nopasscode --salt "0AAFXLLJgmKbTLBoFExFM_iL"
kli oobi resolve --name testwitclient --oobi-alias witness \
    --oobi "https://witness.keri.host/oobi/BNbRfMPQQge6wKO0uof9Y0e_QYOfiF08k9drc6pOgzjt/witness"
kli incept --name testwitclient --alias alice --file alice-icp.json
kli status --name testwitclient --alias alice --verbose | head -10

Output:

Witnesses:
Count:      1
Receipts:   1
Threshold:  1

kli incept invokes WitnessReceiptor → streamCESRRequests, which always uses the wire-format split (event JSON in body, sigs in CESR-ATTACHMENT header — the OP's "Way 2"). If the handler still read the body only (the bug), the inline-sig-less event would fail signature verification and the wallet would never see a receipt — exactly the OP's baser.wigs = 0 symptom. Here we get Receipts: 1 straight from the canonical client.

Direct wire-format probe (the OP's "Way 2") also confirms — a transferable AID with wits=[BNbRf...], posted with body=event-JSON only + CESR-ATTACHMENT header carrying the sig group, returns HTTP 200 + application/cesr with a signed t:rct receipt body:

HTTP 200 | CT=application/cesr | len=285
body: b'{"v":"KERI10JSON000091_","t":"rct","d":"EDuNAZTzbBD0-...","i":"EDuNAZTzbBD0-...","s":"0"}-VAi-CABBNbRf...0BBaaNOfK2d...'

The -VAi-CAB<witness-eid><sig> attachment on the receipt is the witness's non-transferable signature over the event SAID — the wallet ingests this into db.wigs.

A note for anyone re-running the OP's repro and getting empty responses:

• Use a transferable controller (keripy v2 rejects non-trans + wits at eventing.py:2230). The original repro implies transferable; just calling it out.
• Make sure the witness's KEL is loaded into your local kevers before makeHab(wits=[...]) — the OOBI resolve step above does this.

Suggest closing.