Add HTTP signature relay for WAN multi-sig (P4.3b).

Introduce SignatureRelayServer/Client with bearer auth, wire federated
broadcast/collect and MultiSigQuorumConfig relay URLs, and expose
`teaagent sync signature-relay` CLI. Includes integration tests and
governance-gate coverage.

Constraint: terminate TLS at reverse proxy; non-loopback bind requires tokens.
Tested: tests/test_signature_relay.py, tests/test_federated_sync.py (25 passed);
pre-commit smoke pytest (106 passed).
Confidence: high
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnteee

.github/workflows/ci.yml

@@ -192,7 +192,7 @@ jobs:
         run: pytest tests/test_tranche_b_governance.py -k "plan" -v
 
       - name: Run Phase 5 unit tests
-        run: pytest tests/test_phase5_context_bus.py tests/test_phase5_workflow_engine.py tests/test_phase5_jit_approval_server.py tests/test_federated_sync.py tests/test_remediation_p1_p2.py -v
+        run: pytest tests/test_phase5_context_bus.py tests/test_phase5_workflow_engine.py tests/test_phase5_jit_approval_server.py tests/test_federated_sync.py tests/test_signature_relay.py tests/test_remediation_p1_p2.py -v
 
       - name: Run Phase 4-5 acceptance and adversarial governance tests
         run: pytest tests/acceptance/test_consensus_flow.py tests/acceptance/test_sandbox_enhancement_flow.py tests/test_governance_adversarial_runtime.py tests/test_skill_executor.py -v

docs/adr/0008-p4-strategic-posture.md

@@ -34,8 +34,10 @@ CVE-2026-23949 on `jaraco.context`).
 - File-based multi-sig remains **experimental** (not production WAN transport).
 - **P4 tranche:** optional `TEAAGENT_FEDERATED_SIGNATURE_TOKEN` — signature JSON
   files must carry matching `auth_token` when the env var is set.
-- **Future:** HTTP webhook channel with Bearer token (same shape as vote relay);
-  reuse `surface_auth` token files.
+- **P4.3b (shipped):** HTTP signature relay (`teaagent sync signature-relay serve`,
+  `SignatureRelayClient`, `MultiSigQuorumConfig.peer_relay_urls` /
+  `local_relay_base_url`). Bearer tokens reuse relay token files / env
+  (`TEAAGENT_SIGNATURE_RELAY_TOKEN`, `TEAAGENT_RELAY_TOKEN`).
 
 ### 4. `jaraco.context` (CVE-2026-23949)
 
@@ -46,7 +48,7 @@ CVE-2026-23949 on `jaraco.context`).
 ## Consequences
 
 - Operators on NFS must not run concurrent TeaAgent writers on the same JSONL paths.
-- WAN MCP and federated multi-sig require reverse proxy + env tokens until HTTP P2P ships.
+- WAN MCP requires reverse proxy TLS; multi-sig uses signature relay + bearer tokens.
 - Dependabot alert #10 should clear once GitHub rescans `uv.lock` at 6.1.2+.
 
 ## Alternatives considered

docs/http-surface-auth.md

@@ -98,8 +98,32 @@ For remote clients:
 |----------|--------|
 | `TEAAGENT_FEDERATED_SIGNATURE_TOKEN` | When set, P2P signature files under `.teaagent/pending_approvals/` must include matching `auth_token` |
 
-File-based multi-sig remains experimental; WAN deployments should use relay/control-plane
-Bearer tokens until HTTP P2P transport ships (ADR 0008).
+### Signature relay (WAN multi-sig)
+
+```bash
+# Collector (requester workspace)
+teaagent sync signature-relay serve --api-token-file .teaagent/relay-tokens.json --port 8791
+
+# Peer submits signature (after receiving approval request)
+export TEAAGENT_SIGNATURE_RELAY_TOKEN=...
+teaagent sync signature-relay submit \
+  --relay-url https://requester.example:8791 \
+  --request-id <id> --peer-id peer-1 --signature "<ssh-blob>"
+```
+
+Configure `MultiSigQuorumConfig.local_relay_base_url` and `peer_relay_urls` in policy,
+or set `TEAAGENT_SIGNATURE_RELAY_TOKEN` / `TEAAGENT_RELAY_TOKEN` for HTTP client auth.
+
+API:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/api/v1/approval-requests` | Peer receives approval request |
+| POST | `/api/v1/approval-signatures` | Peer submits signature to collector |
+| GET | `/api/v1/approval-signatures?request_id=` | Collector polls signatures |
+
+File-based multi-sig remains available for local dev; production WAN should use the
+HTTP relay behind TLS termination (ADR 0008).
 
 ## Reverse proxy templates
 

docs/plans/remediation-roadmap.md

@@ -65,7 +65,7 @@ Principle: **smallest verifiable step** per phase; no big-bang refactors.
 | P4.1 | JSONL / NFS posture + migration ADR | ✅ tranche | [ADR 0008](../adr/0008-p4-strategic-posture.md), threat-model NFS row |
 | P4.2 | MCP TLS via reverse proxy (no native TLS) | ✅ documented | [http-surface-auth.md](../http-surface-auth.md), ADR 0008 |
 | P4.3 | File P2P signature `auth_token` when `TEAAGENT_FEDERATED_SIGNATURE_TOKEN` set | ✅ shipped | `federated_sync.py`, `security_env.py` |
-| P4.3b | HTTP P2P multi-sig channel | 🔲 future | ADR 0008 — reuse relay bearer shape |
+| P4.3b | HTTP P2P multi-sig channel | ✅ shipped | `signature_relay.py`, `teaagent sync signature-relay` |
 | P4.4 | `jaraco.context` CVE-2026-23949 (Dependabot #10) | ✅ constrained | `pyproject.toml` `jaraco-context>=6.1.0`, `selftest` version check |
 | P4.5 | Async `collect_approval_signatures` unit tests | ✅ shipped | `tests/test_federated_sync.py` |
 

docs/threat-model.md

@@ -25,7 +25,7 @@ This document maps threats to mitigations and verification. It complements [tool
 | Context Bus SQLite lock contention / transaction leaks | Medium | Per-thread SQLite connections (`threading.local`); `timeout=5.0` on connect; WAL pragmas on each new connection; `_execute_with_retry` with exponential backoff (5 retries) + generation-based reconnect (per-thread only); explicit `conn.rollback()` on write failure; `cleanup_old_deltas` scoped to `workflow_id` | `tests/test_phase5_context_bus.py` (incl. parallel publish + workflow-scoped cleanup), `tests/test_remediation_p1_p2.py` | — |
 | Federated sync state corruption on crash | Medium | `atomic_write_text` + file lock on `federated_sync_state.json`; lock on pending changes | `tests/test_federated_sync.py` | File-based multi-sig quorum still experimental |
 | JIT approval server race on approve/reject | Medium | `threading.Lock` on `_requests` / `_pending_events` | `tests/test_phase5_jit_approval_server.py` | Approve from thread without running event loop still drops SSE broadcast |
-| Asyncio event loop starvation from synchronous P2P approval polling | High | `collect_approval_signatures` is `async def` with `asyncio.sleep`; blocking I/O uses `run_in_executor`; `_collect_peer_signatures` dispatches via `run_coroutine_threadsafe` or `asyncio.run()` | `tests/test_federated_sync.py` (`test_collect_approval_signatures_async_non_blocking`, quorum/dedup) | — |
+| Asyncio event loop starvation from synchronous P2P approval polling | High | `collect_approval_signatures` is `async def` with `asyncio.sleep`; blocking I/O uses `run_in_executor`; HTTP WAN path uses `SignatureRelayClient` + bearer auth | `tests/test_federated_sync.py`, `tests/test_signature_relay.py` | — |
 | Shell normalization bypass via brace expansion / process substitution | High | Multi-pass `_normalize_shell_arg` now handles `{a,b}` expansion, `<()` process substitution, and non-string/non-list fallback | `tests/test_policy.py` | Catches `/pr{od,oduction}`, `<(echo /prod)`, dict-type command args |
 | Protected directory bypass via alternate write tools | High | `workspace_write_*` tool pattern + `.git*` argument pattern covers all write tools and subdirectory contents | `tests/test_policy.py`, `tests/test_file_policy.py` | Previously only `workspace_write_file` was covered |
 | Swarm hang / undetected thread deadlock | High | `ThreadPoolExecutor.as_completed(timeout=...)` with partial result collection; `Subagent` tracks `is_running`/`last_heartbeat`; `_heartbeat_monitor_loop` uses thread-ref liveness instead of defunct PID-based `is_process_alive`; heartbeat hangs merged into swarm `results` | `tests/test_swarm.py`, `tests/test_remediation_p1_p2.py` | Previously heartbeat monitor checked parent PID (always alive) — now detects actual thread hangs |

teaagent/cli/__init__.py

@@ -171,6 +171,8 @@
     status_short_command,
     sync_export,
     sync_import,
+    sync_signature_relay_serve_command,
+    sync_signature_submit_command,
     sync_status,
     tool_inspect_command,
     tool_lint_command,
@@ -310,6 +312,8 @@ def build_parser() -> argparse.ArgumentParser:
             'experiment_cancel': experiment_cancel,
             'sync_export': sync_export,
             'sync_import': sync_import,
+            'sync_signature_relay_serve': sync_signature_relay_serve_command,
+            'sync_signature_submit': sync_signature_submit_command,
             'sync_status': sync_status,
             'replay_list': replay_list,
             'replay_steps': replay_steps,

teaagent/cli/_handlers/__init__.py

@@ -213,6 +213,8 @@
 from ._sync import (
     sync_export,
     sync_import,
+    sync_signature_relay_serve_command,
+    sync_signature_submit_command,
     sync_status,
 )
 from ._tool import tool_inspect_command, tool_lint_command, tool_list_command
@@ -365,6 +367,8 @@
     'experiment_select',
     'sync_export',
     'sync_import',
+    'sync_signature_relay_serve_command',
+    'sync_signature_submit_command',
     'sync_status',
     'replay_list',
     'replay_steps',

teaagent/cli/_handlers/_sync.py

@@ -6,6 +6,7 @@
 import json
 import logging
 import sqlite3
+import ssl
 from pathlib import Path
 
 from teaagent.federated_sync import FederatedGraphSync, SyncAck
@@ -209,3 +210,83 @@ def sync_status(args: argparse.Namespace) -> int:
         }
     )
     return 0
+
+
+def _signature_relay_ssl_context(
+    args: argparse.Namespace,
+) -> ssl.SSLContext | None:
+    from teaagent.tls_server import build_server_ssl_context
+
+    if not getattr(args, 'tls_cert', None):
+        return None
+    client_ca = (
+        Path(args.tls_client_ca) if getattr(args, 'tls_client_ca', None) else None
+    )
+    return build_server_ssl_context(
+        cert_file=Path(args.tls_cert),
+        key_file=Path(args.tls_key),
+        client_ca_file=client_ca,
+    )
+
+
+def sync_signature_relay_serve_command(args: argparse.Namespace) -> int:
+    """Serve HTTP relay for WAN multi-sig approval signatures."""
+    from pathlib import Path
+
+    from teaagent.http_rate_limit import TokenRateLimiter
+    from teaagent.signature_relay import SignatureRelayServer
+    from teaagent.surface_auth import load_surface_auth_policy
+
+    token_file = (
+        Path(args.api_token_file) if getattr(args, 'api_token_file', None) else None
+    )
+    policy = load_surface_auth_policy(
+        api_token=getattr(args, 'api_token', None),
+        api_token_file=token_file,
+        relay_mode=True,
+    )
+    rate_limiter = None
+    rate_limit_calls = int(getattr(args, 'rate_limit_calls', 0))
+    if rate_limit_calls > 0:
+        rate_limiter = TokenRateLimiter(
+            max_calls=rate_limit_calls,
+            window_seconds=float(getattr(args, 'rate_limit_window', 60.0)),
+        )
+    try:
+        relay = SignatureRelayServer(
+            host=args.host,
+            port=args.port,
+            auth_policy=policy,
+            ssl_context=_signature_relay_ssl_context(args),
+            rate_limiter=rate_limiter,
+        )
+    except ValueError as exc:
+        print_json({'ok': False, 'error': str(exc)})
+        return 1
+    relay.serve_blocking()
+    return 0
+
+
+def sync_signature_submit_command(args: argparse.Namespace) -> int:
+    """POST an approval signature to a remote signature relay."""
+    from teaagent.signature_relay import SignatureRelayClient
+
+    client = SignatureRelayClient(api_token=getattr(args, 'api_token', None))
+    submit_url = (getattr(args, 'submit_url', None) or '').strip()
+    if not submit_url:
+        relay_url = (getattr(args, 'relay_url', None) or '').strip()
+        if not relay_url:
+            print_json({'ok': False, 'error': 'provide --submit-url or --relay-url'})
+            return 1
+        submit_url = f'{relay_url.rstrip("/")}/api/v1/approval-signatures'
+    result = client.post_signature(
+        submit_url,
+        {
+            'request_id': args.request_id,
+            'peer_id': args.peer_id,
+            'signature': args.signature,
+            'ssh_key_id': getattr(args, 'ssh_key_id', None),
+        },
+    )
+    print_json(result)
+    return 0 if result.get('ok') else 1

teaagent/cli/_misc_parsers.py

@@ -84,6 +84,8 @@ def register(
         handlers.get('sync_export'),
         handlers.get('sync_import'),
         handlers.get('sync_status'),
+        handlers.get('sync_signature_relay_serve'),
+        handlers.get('sync_signature_submit'),
     )
     _replay(
         subparsers,
@@ -888,6 +890,8 @@ def _sync(
     export_handler: Optional[Callable],
     import_handler: Optional[Callable],
     status_handler: Optional[Callable],
+    signature_relay_serve_handler: Optional[Callable] = None,
+    signature_submit_handler: Optional[Callable] = None,
 ) -> None:
     """Register sync subcommands."""
     sync_parser = subparsers.add_parser(
@@ -944,6 +948,53 @@ def _sync(
     )
     status_cmd.set_defaults(func=status_handler or _deprecation_warning)
 
+    sig_relay = subs.add_parser(
+        'signature-relay',
+        help='HTTP relay for WAN multi-sig approval requests and signatures',
+    )
+    sig_subs = sig_relay.add_subparsers(
+        dest='signature_relay_command', required=True, help='Signature relay commands'
+    )
+    sig_serve = sig_subs.add_parser('serve', help='Start signature relay HTTP server')
+    sig_serve.add_argument('--host', default='127.0.0.1')
+    sig_serve.add_argument('--port', type=int, default=8791)
+    sig_serve.add_argument('--api-token', help='Bearer token for relay requests')
+    sig_serve.add_argument('--api-token-file', help='JSON relay token file')
+    sig_serve.add_argument('--tls-cert', help='TLS certificate PEM')
+    sig_serve.add_argument('--tls-key', help='TLS private key PEM')
+    sig_serve.add_argument('--tls-client-ca', help='Client CA PEM for mTLS')
+    sig_serve.add_argument(
+        '--rate-limit-calls',
+        type=int,
+        default=120,
+        help='Max POSTs per token per window (0 disables)',
+    )
+    sig_serve.add_argument(
+        '--rate-limit-window',
+        type=float,
+        default=60.0,
+        help='Rate limit window seconds',
+    )
+    sig_serve.set_defaults(func=signature_relay_serve_handler or _deprecation_warning)
+
+    sig_submit = sig_subs.add_parser(
+        'submit', help='Submit a peer signature to a signature relay'
+    )
+    sig_submit.add_argument(
+        '--relay-url', help='Relay base URL if --submit-url omitted'
+    )
+    sig_submit.add_argument(
+        '--submit-url',
+        default='',
+        help='Full POST URL (defaults to {relay-url}/api/v1/approval-signatures)',
+    )
+    sig_submit.add_argument('--request-id', required=True)
+    sig_submit.add_argument('--peer-id', required=True)
+    sig_submit.add_argument('--signature', required=True)
+    sig_submit.add_argument('--ssh-key-id', help='SSH key id metadata')
+    sig_submit.add_argument('--api-token', help='Bearer token')
+    sig_submit.set_defaults(func=signature_submit_handler or _deprecation_warning)
+
 
 def _replay(
     subparsers: argparse._SubParsersAction,  # type: ignore[type-arg]