feat: Publish addresses with optional Herald email service

[macterra]

Summary

• Discover Herald relay agents from address-domain config during address add/import and store the relay DID with address metadata in TypeScript and Python keymaster.
• Add explicit publishAddress / unpublishAddress flows across Keymaster APIs, CLIs, clients, and UIs. Publishing always sets didDocumentData.address; it adds the #email mailto: service only when the stored address has a relay.
• Have Herald advertise relayAgent only when the email bridge is enabled, while still exposing serviceDID for general service identity.
• Document the new /addresses/publish API behavior and update the generated Keymaster API JSON.

Validation

• npm test -- tests/keymaster/address.test.ts tests/keymaster/client.test.ts --runInBand
• npm run build -w @didcid/keymaster
• npm run build in services/keymaster/server
• npm run build in services/herald/server
• npm run build in apps/react-wallet
• npm run build in apps/browser-extension
• npm run build in apps/keymaster-client
• npm run build in apps/gatekeeper-client
• .venv/bin/python -m pytest -q python/keymaster/tests/test_address.py
• .venv/bin/python -c "import argparse; from keymaster.cli import build_parser; p=build_parser(); sp=[a for a in p._actions if isinstance(a, argparse._SubParsersAction)][0]; assert len(sp.choices)==134"
• python3 -m py_compile python/keymaster/src/keymaster/core.py python/keymaster/src/keymaster/cli.py python/keymaster/tests/test_address.py
• git diff --check

[Copilot]

Pull request overview

Adds relay-agent discovery/storage for Herald-backed addresses and introduces explicit publish/unpublish address operations that update DID document profile data (and conditionally add an Email service) across Keymaster TypeScript + Python implementations, server APIs, CLIs, and UIs.

Changes:

• Discover Herald relayAgent via domain /config endpoints during address add/import and persist it as address metadata (relay), surfacing it via list/get address APIs.
• Add publishAddress / unpublishAddress flows (server endpoints, TS/Python implementations, CLIs, and UIs) that manage didDocumentData.address and an optional #email service entry.
• Extend tests and docs to cover relay discovery and publish/unpublish behavior.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/keymaster/client.test.ts	Adds client tests for publish/unpublish address API calls.
tests/keymaster/address.test.ts	Adds Keymaster unit tests for relay discovery and publish/unpublish DID updates.
services/keymaster/server/src/keymaster-api.ts	Exposes /api/v1/addresses/publish POST/DELETE endpoints and normalizes the route for logging/metrics.
services/herald/server/src/index.ts	Exposes serviceDID always; conditionally advertises relayAgent when email bridge is enabled.
python/keymaster/tests/test_address.py	Adds relay + publish/unpublish coverage for Python Keymaster.
python/keymaster/src/keymaster/core.py	Implements relay discovery + publish/unpublish logic and surfaces address metadata consistently.
python/keymaster/src/keymaster/cli.py	Adds publish-address / unpublish-address CLI commands.
packages/keymaster/src/types.ts	Extends stored address type with optional relay; adds Keymaster interface methods.
packages/keymaster/src/keymaster.ts	Implements relay discovery, address metadata surfacing, and publish/unpublish logic.
packages/keymaster/src/keymaster-client.ts	Adds client wrappers for new server publish/unpublish endpoints.
packages/keymaster/src/cli.ts	Adds CLI commands for publish/unpublish.
packages/keymaster/README.md	Documents new CLI commands.
docs/services/herald/README.md	Documents updated /api/config shape and relayAgent semantics.
apps/react-wallet/src/components/IdentitiesTab.tsx	Switches UI to publish/unpublish APIs instead of raw mergeData.
apps/keymaster-client/src/KeymasterUI.jsx	Switches UI to publish/unpublish APIs instead of raw mergeData.
apps/gatekeeper-client/src/KeymasterUI.jsx	Keeps parity with keymaster-client UI publish/unpublish behavior.
apps/browser-extension/src/components/IdentitiesTab.tsx	Switches UI to publish/unpublish APIs instead of raw mergeData.
AGENTS.md	Codifies relay metadata + publish/unpublish behavior parity across TS/Python.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.