Audit remediation and verification hardening

.env.example

@@ -1,47 +1,146 @@
 # DJD Agent Score — Environment Variables
-# Copy to .env and fill in values before running.
+# Copy to .env and fill in the values you actually need.
+#
+# There are two env namespaces in this repo:
+# - Runtime/app envs: ADMIN_KEY, PAY_TO, BASE_RPC_URL, etc.
+# - Evaluator contract ops envs: DJD_*, used by scripts/ for stage/deploy/verify/smoke/promote.
 
-# ── Server ────────────────────────────────────────────────────────
+# ── Runtime / server ───────────────────────────────────────────────────────
 PORT=3000
+# NODE_ENV=development
+# LOG_LEVEL=debug
 
-# ── Required ─────────────────────────────────────────────────────
-# Admin API key — must be >= 32 characters in production
+# Runtime metadata surfaced by /health and deploy checks.
+# DJD_RUNTIME_MODE=combined
+# DJD_RELEASE_SHA=
+# DJD_BUILD_TIMESTAMP=2026-03-17T00:00:00.000Z
+
+# ── Admin / public metadata ────────────────────────────────────────────────
+# Admin API key. Required in production and reused by some post-deploy checks.
 ADMIN_KEY=
 
-# Comma-separated allowed CORS origins (required in production)
+# Optional alias for deploy/smoke scripts. Use the same value as ADMIN_KEY when needed.
+# DJD_ADMIN_KEY=
+
+# Comma-separated allowed CORS origins. Required in production.
 # CORS_ORIGINS=https://djdagentscore.dev,https://yourfrontend.com
 
-# Canonical public site URL used in billing links, metadata, and published docs.
+# Canonical public site URL used in docs, legal pages, and generated links.
 # PUBLIC_BASE_URL=https://djdagentscore.dev
 
+# Optional fallback used by some billing/public helpers if PUBLIC_BASE_URL is unset.
+# BILLING_BASE_URL=https://djdagentscore.dev
+
 # Public support email surfaced in OpenAPI and legal pages.
 # [email protected]
 
-# ── Base L2 RPC ──────────────────────────────────────────────────
-# Primary RPC endpoint for Base mainnet. Falls back to BASE_RPC_FALLBACK_URL on failure.
+# ── Runtime chain access ────────────────────────────────────────────────────
+# Base mainnet RPC used by the scoring runtime, indexers, and publisher jobs.
 BASE_RPC_URL=https://base-mainnet.public.blastapi.io
 BASE_RPC_FALLBACK_URL=https://mainnet.base.org
 
-# ── x402 Payments ────────────────────────────────────────────────
-# Wallet address that receives x402 USDC micropayments (your revenue address).
+# Optional ERC-8004 identity registry contract address. When unset, ERC-8004 registration
+# remains informative/document-shaped but not backed by a configured registry contract.
+# ERC8004_IDENTITY_REGISTRY=0x0000000000000000000000000000000000000000
+
+# ── x402 payments ───────────────────────────────────────────────────────────
+# Wallet that receives x402 USDC micropayments and staking fee transfers.
 PAY_TO=0xYOUR_WALLET_ADDRESS_HERE
 
-# x402 facilitator service URL (default: https://x402.org/facilitator)
+# x402 facilitator service URL and contract address.
 FACILITATOR_URL=https://x402.org/facilitator
-
-# Facilitator contract address on Base (default: Coinbase facilitator)
 FACILITATOR_ADDRESS=0x97316FA4730BC7d3B295234F8e4D04a0a4C093e8
 
-# ── Stripe Billing (optional) ──────────────────────────────────────
-# When STRIPE_SECRET_KEY is set, /billing/* and /stripe/webhook routes are enabled.
-# All STRIPE_PRICE_* vars are required when Stripe is enabled.
+# ── Optional integrations ───────────────────────────────────────────────────
+# Stripe enables /billing/* and /stripe/webhook routes.
 # STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxx
 # STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
 # STRIPE_PRICE_STARTER=price_xxxxxxxxxxxxxxxxxxxxx
 # STRIPE_PRICE_GROWTH=price_xxxxxxxxxxxxxxxxxxxxx
 # STRIPE_PRICE_SCALE=price_xxxxxxxxxxxxxxxxxxxxx
 
-# ── GitHub Integration (optional) ────────────────────────────────
-# Personal access token for GitHub API. Without this, rate limits are 60 req/hr.
-# With a token, rate limits are 5000 req/hr. Used for agent GitHub URL verification.
+# GitHub API token used for agent registration / verification flows.
 # GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+
+# Insumer integration for additional identity context.
+# INSUMER_API_URL=https://api.insumermodel.com
+# INSUMER_API_KEY=
+
+# ── Evaluator signing / publication ────────────────────────────────────────
+# Signed oracle verdicts require ORACLE_SIGNER_PRIVATE_KEY or fallback PUBLISHER_PRIVATE_KEY.
+# ORACLE_SIGNER_PRIVATE_KEY=0xyour64byteprivatekey
+# PUBLISHER_PRIVATE_KEY=0xyour64byteprivatekey
+
+# ── Evaluator contract ops (scripts/) ──────────────────────────────────────
+# Supported networks today: base, base-sepolia
+# DJD_NETWORK=base-sepolia
+
+# Optional global RPC override for scripts. If unset, scripts look for the per-network vars below.
+# DJD_RPC_URL=
+
+# Preferred per-network RPC vars for deploy/verify/smoke/stage.
+# DJD_BASE_RPC_URL=https://mainnet.base.org
+# DJD_BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+
+# Private key used by contracts:deploy and contracts:stage.
+# DJD_DEPLOYER_PRIVATE_KEY=0xyour64byteprivatekey
+
+# API-driven bundle resolution: use these when fetching the deploy bundle from the live API.
+# DJD_API_BASE_URL=https://djdagentscore.dev
+# DJD_VERDICT_ID=verdict_123e4567-e89b-42d3-a456-426614174000
+
+# Optional explicit verifier override when building a deployment bundle.
+# DJD_VERIFIER_CONTRACT=0x0000000000000000000000000000000000000000
+
+# File-driven bundle/result resolution. Use these when running scripts against local artifacts.
+# DJD_DEPLOY_BUNDLE_PATH=.tmp/djd-evaluator-deploy-bundle.json
+# DJD_DEPLOY_BUNDLE_URL=https://djdagentscore.dev/v1/score/evaluator/deploy/bundle?id=verdict_...
+# DJD_DEPLOY_RESULT_PATH=.tmp/djd-evaluator-deploy-result.json
+
+# Published deployment registry location. Local scripts default to data/evaluator-deployments.json.
+# DJD_EVALUATOR_DEPLOYMENTS_PATH=data/evaluator-deployments.json
+# DJD_DEPLOYMENTS_URL=https://djdagentscore.dev/v1/score/evaluator/deployments?network=base-sepolia
+
+# ── Stage / preflight / smoke ──────────────────────────────────────────────
+# Stage report file written by contracts:stage.
+# DJD_STAGE_REPORT_PATH=.tmp/djd-evaluator-stage-report.json
+
+# Optional env bootstrap output written by contracts:bootstrap-env.
+# DJD_ENV_BOOTSTRAP_FORMAT=dotenv
+# DJD_ENV_BOOTSTRAP_OUTPUT_PATH=.tmp/djd-evaluator-bootstrap.env
+
+# Enable post-deploy health verification inside contracts:stage.
+# DJD_STAGE_RUN_HEALTH=true
+# DJD_HEALTHCHECK_URL=https://djdagentscore.dev/health
+
+# Expected runtime metadata for post-deploy smoke.
+# DJD_EXPECT_RUNTIME_MODE=combined
+# DJD_EXPECT_RELEASE_SHA=
+
+# Timeouts for post-deploy smoke.
+# DJD_DEPLOY_SMOKE_TIMEOUT_MS=180000
+# DJD_DEPLOY_SMOKE_INTERVAL_MS=5000
+
+# Publishing and promotion toggles for contracts:stage.
+# DJD_STAGE_PUBLISH_REGISTRY=true
+# DJD_STAGE_PROMOTE=true
+
+# Allow publishing a deployment registry entry even if preflight/verify/smoke did not all pass.
+# DJD_PUBLISH_ALLOW_PARTIAL=false
+
+# ── Promotion outputs ───────────────────────────────────────────────────────
+# Generic output paths used by contracts:promote.
+# DJD_PROMOTION_OUTPUT_PATH=.tmp/djd-evaluator-promotion.json
+# DJD_PROMOTION_DOTENV_PATH=.tmp/djd-evaluator-promotion.env
+# DJD_PROMOTION_SHELL_PATH=.tmp/djd-evaluator-promotion.sh
+# DJD_PROMOTION_GITHUB_OUTPUT_PATH=.tmp/djd-evaluator-github-output.txt
+
+# Optional stage-specific overrides. If unset, contracts:stage falls back to the generic
+# DJD_PROMOTION_* paths above.
+# DJD_STAGE_PROMOTION_OUTPUT_PATH=.tmp/djd-stage-promotion.json
+# DJD_STAGE_PROMOTION_DOTENV_PATH=.tmp/djd-stage-promotion.env
+# DJD_STAGE_PROMOTION_SHELL_PATH=.tmp/djd-stage-promotion.sh
+# DJD_STAGE_PROMOTION_GITHUB_OUTPUT_PATH=.tmp/djd-stage-github-output.txt
+
+# In GitHub Actions, the runner usually provides this automatically.
+# GITHUB_OUTPUT=

.gitignore

@@ -10,9 +10,9 @@ data/
 __pycache__/
 .serena/
 .claude/
+.worktrees/
 x402/
 server.json
-docs/plans/
 DEPLOY.md
 evaluate.sh
 program.md

README.md

@@ -14,6 +14,82 @@ DJD Agent Score is the trust and governance layer for agent wallets on Base. Tod
 
 ---
 
+## Local and operator setup
+
+Copy [`.env.example`](./.env.example) to `.env`. The repo now uses two env groups:
+
+- **Runtime envs** power the API itself: `ADMIN_KEY`, `PAY_TO`, `BASE_RPC_URL`, `PUBLIC_BASE_URL`, Stripe, GitHub, and signing keys.
+- **`DJD_*` contract-ops envs** power the deploy pipeline in [`scripts/`](./scripts): preflight, deploy, verify, smoke, stage, publish, and promote.
+
+For normal local API work, the minimum is usually:
+
+```bash
+cp .env.example .env
+# then set at least:
+# ADMIN_KEY=...
+# PAY_TO=0x...
+# BASE_RPC_URL=https://...
+```
+
+Start the combined runtime:
+
+```bash
+npm install
+npm run dev
+```
+
+### Evaluator contract staging
+
+The evaluator/onchain pipeline is file- and API-driven. The cleanest Base Sepolia path is:
+
+```bash
+# required for a real public stage run
+export DJD_NETWORK=base-sepolia
+export DJD_BASE_SEPOLIA_RPC_URL=https://...
+export DJD_DEPLOYER_PRIVATE_KEY=0x...
+export DJD_API_BASE_URL=https://your-runtime.example
+export DJD_VERDICT_ID=verdict_...
+```
+
+The `contracts:*` npm commands now auto-load `.env` if it exists, so you can either export these in your shell or keep them in the repo-local `.env`.
+
+Optional but commonly needed:
+
+```bash
+export ORACLE_SIGNER_PRIVATE_KEY=0x...
+export DJD_EVALUATOR_DEPLOYMENTS_PATH=data/evaluator-deployments.json
+export DJD_STAGE_PUBLISH_REGISTRY=true
+export DJD_STAGE_PROMOTE=true
+export DJD_STAGE_REPORT_PATH=.tmp/djd-stage-report.json
+export DJD_PROMOTION_OUTPUT_PATH=.tmp/djd-promotion.json
+export DJD_PROMOTION_DOTENV_PATH=.tmp/djd-promotion.env
+export DJD_PROMOTION_SHELL_PATH=.tmp/djd-promotion.sh
+```
+
+Then run:
+
+```bash
+npm run contracts:bootstrap-env
+npm run contracts:preflight
+npm run contracts:stage
+```
+
+`contracts:bootstrap-env` is the quickest way to generate a ready-to-fill network-specific env snippet before you try a real stage run.
+
+If you only want the env/export bundle for the active published deployment:
+
+```bash
+npm run contracts:promote
+```
+
+Important env naming detail:
+
+- `BASE_RPC_URL` is used by the runtime/indexer side of the app.
+- `DJD_BASE_RPC_URL` and `DJD_BASE_SEPOLIA_RPC_URL` are used by the contract deployment scripts.
+- `ADMIN_KEY` secures the app; `DJD_ADMIN_KEY` is an optional alias for post-deploy health checks.
+
+---
+
 ## Start here: gate an x402 route
 
 If you run a paid Hono endpoint, this is the best first integration.
@@ -264,6 +340,8 @@ Paid endpoints return `402 Payment Required` without a valid payment proof or AP
 
 If you want to use DJD Agent Score in production and want help choosing a starting score threshold or rollout policy, reach out at [[email protected]](mailto:[email protected]).
 
+Design partners can start with the [Pilot Integration Guide](./docs/pilot-integration-guide.md).
+
 ---
 
 ## Report fraud