Harden oracle: attestation spam guard, Prometheus metrics, ops hygiene

[RunTimeAdmin]

Summary

Hardens the off-chain reputation oracle for mainnet readiness with three key improvements:

1. Attestation spam guard: Prevents score inflation by enforcing a cooldown between attestations from the same attester for the same agent
2. Prometheus metrics: Adds a /metrics endpoint for operational monitoring and alerting
3. Ops hygiene: Enhanced health checks, comprehensive documentation, and clearer failure signals

Changes

Attestation Cooldown Guard

The /attest endpoint now requires an attester field identifying the party submitting the attestation. The same attester cannot re-attest the same agent within the cooldown period (default: 1 hour, configurable via ATTEST_COOLDOWN_MS).

• Prevents a single party from artificially inflating an agent's fee/success scores
• Cooldowns persist across restarts in the state file
• Returns clear 429 error with remaining time when blocked:

{
  "error": "Attestation cooldown active",
  "attester": "unique-id",
  "didHash": "0x...",
  "remainingSeconds": 2400,
  "cooldownMs": 3600000
}

Prometheus Metrics (GET /metrics)

New endpoint exposing operational metrics in Prometheus text format:

• countersig_oracle_epochs_total{status="started|succeeded|failed"} — epoch execution
• countersig_oracle_propose_total{result="success|error"} — score proposals
• countersig_oracle_finalize_total{result="success|error"} — score finalizations
• countersig_oracle_attest_total{result="accepted|rejected_cooldown|rejected_other"} — attestation handling
• countersig_oracle_flags_total, countersig_oracle_links_total — flag/link counts
• countersig_oracle_rate_limit_hits_total — rate limit rejections
• countersig_oracle_last_successful_epoch_timestamp_seconds — for staleness alerts
• countersig_oracle_uptime_seconds, countersig_oracle_active_agents

Enhanced Health Check (GET /health)

The /health endpoint now returns operational signals useful for production alerting:

{
  "ok": true,
  "epochMs": 3600000,
  "uptimeSeconds": 12345,
  "lastSuccessfulEpochMs": 1234567890000,
  "timeSinceLastEpochMs": 120000,
  "storeWritable": true,
  "statePath": "/data/oracle-state.json",
  "attestCooldownMs": 3600000,
  "epochRunning": false
}

Returns 503 when:

• State file path is not writable (volume mount issue)
• No successful epoch in the last 2× epoch interval (stale scoring)

Documentation

• New oracle/README.md: Comprehensive operator documentation with API reference, environment variables, Docker deployment, and production checklist
• Updated .env.example: Added ORACLE_STATE_PATH and ATTEST_COOLDOWN_MS with descriptions

Testing

All 88 tests pass:

node --test
# tests 88, pass 88, fail 0

New tests cover:

• Cooldown check/record/prune functions in store.test.js
• Metrics inc/set/get/reset and Prometheus export in metrics.test.js

How to Verify

1. Attest cooldown:

# First attest succeeds
curl -X POST localhost:3030/attest \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"didHash":"0x...","success":true,"attester":"test-client"}'
# Response: 200 with attestation counts

# Immediate re-attest blocked
curl -X POST localhost:3030/attest \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"didHash":"0x...","success":true,"attester":"test-client"}'
# Response: 429 with remainingSeconds

# Different attester works
curl -X POST localhost:3030/attest \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"didHash":"0x...","success":true,"attester":"other-client"}'
# Response: 200

2. Metrics:

curl localhost:3030/metrics
# Prometheus text format output

3. Health check:

curl localhost:3030/health
# JSON with operational signals

Breaking Changes

POST /attest now requires the attester field. Existing clients must be updated to include this field.

Checklist

• Attestation spam blocked with tests proving it
• /metrics returns scrapeable Prometheus metrics
• /health includes signals for production alerting
• oracle/README.md documents env vars and operations
• .env.example updated with new configuration options
• All tests pass (node --test)