feat(gateway): DID signing for outbound A2A requests (Phase 1a)

[raahulrahl]

Closes the calling-side DID gap we identified earlier: gateway can now sign outbound A2A requests so DID-enforcing peers like agno_example accept them instead of returning 403 missing_signature_headers.

Scope (Phase 1a)

• ✅ Gateway DID identity primitive (loads seed from env, derives keypair, signs bodies)
• ✅ did_signed peer auth variant in the resolver
• ✅ Body-serialize-once invariant in rpc() — same bytes signed and sent
• ✅ Client layer injects identity into runCall / runCancel
• ✅ Boot-time env loading with fail-fast partial-config error
• ✅ Operator docs in gateway/.env.example + gateway/README.md
• ✅ Cross-language contract test — JS signer byte-for-byte identical to Python reference signer for a canonical fixture

Deferred to follow-ups (explicitly scoped in the last commit message):

• Phase 1b: auto Hydra client registration on boot (user decision was "Auto" — this PR supports Manual registration only; Auto needs a Hydra admin client module + OAuth token-refresh cache)
• Phase 1b: gateway's own /.well-known/did.json endpoint
• Phase 1c: frontend POC (localStorage + tweetnacl, per Decision 4)
• Phase 1d: dedicated Postman collection
• Phase 1e: deep docs in docs/GATEWAY_DID_SETUP.md

Each is a separate reviewable PR; this one keeps the diff focused on the core signing contract.

Three commits, reviewable in order

1. 22ca7bf — DID identity primitive with cross-language parity test. 466 lines. The signing primitive + 18 tests. The critical test asserts byte-exact match against a Python-generated fixture — any drift breaks CI before anyone sees a real-world 403.

2. f203827 — plumb DID signing through auth resolver and rpc. 358 lines. Adds did_signed variant; makes buildAuthHeaders async; rpc() serializes body once and signs. 11 new auth-resolver tests including regression guards.

3. 6520176 — boot-time identity loading + operator docs. 226 lines. buildAppLayer(identity?) factory, tryLoadIdentity() with fail-fast partial-config error, boot log printing the DID + public key so operators can register them, .env.example + README.md updates. 5 new boot tests.

Cross-language contract

The load-bearing assertion, from gateway/tests/bindu/identity-local.test.ts:

seed:       32 zero bytes
did:        did:bindu:test
body:       {"test": "value"}
timestamp:  1000
expected:   3SfU4VPTHLbzZzCn17ZqU6y2tnzHQbdo2nnXQr6XZXk34XgyzwSKRrCYEWRmmGXrV39mdkyhTsy5oasfTpNuqyM2

Generated by bindu/utils/did/signature.py (Python reference). If the JS signer ever drifts by one character — separator spacing, key order, encoding — this test flips red.

Operator enable flow

export BINDU_GATEWAY_DID_SEED="$(python -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())')"
export BINDU_GATEWAY_AUTHOR=ops@example.com
export BINDU_GATEWAY_NAME=gateway

npm run dev
# → [bindu-gateway] DID identity loaded: did:bindu:ops_at_example_com:gateway:...
# → [bindu-gateway] public key (base58): 7dNzT2ZzYKsib...

Copy both lines into each peer's Hydra, stash the issued OAuth token in an env var, and set auth.type: "did_signed" on the peer entry.

Failure modes — all fail fast at boot or call time with clear errors

Scenario	When it fails	Message
All three env vars unset	Never fails — pre-DID mode	no DID identity configured (set BINDU_GATEWAY_DID_SEED, _AUTHOR, _NAME to enable did_signed peer auth)
Two of three set	Boot	Partial DID identity config — set all three or none: ...
Seed malformed	Boot	BINDU_GATEWAY_DID_SEED must decode to exactly 32 bytes
did_signed peer but no identity loaded	First outbound call	did_signed peer requires a gateway LocalIdentity — check that BINDU_GATEWAY_DID_SEED is set at boot
did_signed peer with missing OAuth env var	First outbound call	env var "X" is not set (did_signed peer requires an OAuth bearer token alongside the DID signature)

No mystery 403s. No silent failures.

Test summary

77 gateway tests pass (61 existing + 16 new across three new test files).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added DID signing support for secure peer authentication. The gateway can now sign outbound requests using Ed25519 identity when configured with three new environment variables (BINDU_GATEWAY_DID_SEED, BINDU_GATEWAY_AUTHOR, BINDU_GATEWAY_NAME).

• Documentation

  • Added comprehensive configuration guide explaining DID signing setup and integration with downstream peer authentication.

• Tests

  • Added test coverage for DID identity loading, authentication header construction, and request signing functionality.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces DID-based Ed25519 signing for outbound A2A requests in the gateway. It adds a new did_signed auth variant, implements a LocalIdentity module for key derivation and payload signing, integrates per-request body signing into the RPC client workflow, and wires the identity through the service layer at boot time.

Changes

Cohort / File(s)	Summary
Configuration & Documentation gateway/.env.example, gateway/README.md	Added three new DID-related environment variables (BINDU_GATEWAY_DID_SEED, BINDU_GATEWAY_AUTHOR, BINDU_GATEWAY_NAME) with detailed documentation of the signing flow, registration process, and fail-fast boot behavior for partial configurations.
Auth System gateway/src/bindu/auth/resolver.ts, gateway/tests/bindu/auth-resolver.test.ts	Extended PeerAuth discriminated union with did_signed variant; converted authHeaders to async buildAuthHeaders accepting serialized body and optional LocalIdentity for per-request signing; added comprehensive test coverage for all auth variants and error handling.
Client Layer gateway/src/bindu/client/fetch.ts, gateway/src/bindu/client/index.ts, gateway/src/bindu/client/poll.ts	Replaced generic headers parameter with auth-driven construction via auth, identity, and extraHeaders fields; introduced single JSON-RPC serialization passed to both HTTP body and signing; updated RpcInput interface and wired identity through the layer factory; modified SendAndPollInput to accept auth/identity configuration.
Identity Module gateway/src/bindu/identity/local.ts, gateway/tests/bindu/identity-local.test.ts	Implemented new module for local DID identity with Ed25519 signing, agent ID derivation via SHA-256, and Python-compatible JSON serialization; provides loadLocalIdentity factory and sign method returning DID signature headers; includes cross-language parity test against Python reference implementation.
Entry Point & Boot gateway/src/index.ts, gateway/tests/index-identity.test.ts	Added tryLoadIdentity() to load DID config from environment with fail-fast partial-config validation; refactored service composition into buildAppLayer(identity) factory; wired identity loading and layer composition into main() with boot-time logging.

Sequence Diagram

sequenceDiagram
    participant Client
    participant RPC as RPC Client
    participant Auth as Auth Resolver
    participant Identity as LocalIdentity
    participant Peer

    Client->>RPC: rpc(input: {peer, body, identity})
    RPC->>RPC: bodyStr = JSON.stringify(body, {sort_keys})
    RPC->>Auth: buildAuthHeaders(auth, bodyStr, identity)
    
    alt auth.type === "did_signed"
        Auth->>Identity: sign(bodyStr)
        Identity->>Identity: payload = {body, did, timestamp}
        Identity->>Identity: signature = Ed25519.sign(payload)
        Identity-->>Auth: {X-DID, X-DID-Timestamp, X-DID-Signature}
        Auth->>Auth: merge with OAuth Authorization header
    else auth.type === "bearer_env"
        Auth->>Auth: resolve token from process.env
    else auth.type === "bearer"
        Auth->>Auth: use static token
    else auth.type === "none"
        Auth->>Auth: return empty headers
    end
    
    Auth-->>RPC: headers
    RPC->>Peer: HTTP POST(bodyStr, headers)
    Peer-->>RPC: response
    RPC-->>Client: outcome

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The changes span multiple interconnected modules with async pattern shifts, introduce cryptographic operations requiring cross-language parity verification, modify several public API signatures, and affect the service composition layer. However, good test coverage and clear separation of concerns help reduce review complexity.

Possibly related PRs

• feat: Bindu Gateway + bug-tracking infrastructure #463: Directly extends the same gateway modules (bindu/auth/resolver.ts, client/fetch.ts, client/index.ts, identity/*) with the core DID signing implementation and environment configuration that forms the foundation for this PR's integration work.

Poem

🐰 A gateway now signs with a key, so fine,
Ed25519 threads through each JSON line,
Headers adorned with Did's cryptic grace,
Python and TypeScript in signing embrace! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(gateway): DID signing for outbound A2A requests (Phase 1a)' clearly and specifically describes the main change: adding DID signing capability for outbound A2A requests in the gateway.
Description check	✅ Passed	The PR description is comprehensive and well-structured, covering problem/solution, scope, commit breakdown, cross-language contract details, operator flow, failure modes, and test results, though it deviates from the template structure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/gateway-did-signing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}