feat: admin whitelist API (#313)

* feat(api): admin whitelist API

Add admin endpoints to manage the registration whitelist, gated by a
static bearer token (Authorization: Bearer), enabled via the `admin`
config block with the token supplied through ADMIN_API_KEY.

Endpoints (under /admin):
- POST   /admin/whitelist          add/upsert an address (idempotent)
- DELETE /admin/whitelist/{address} remove (404 when not whitelisted)
- GET    /admin/whitelist          cursor-paginated list

Details:
- New whitelist domain in pkg/user/whitelist: a Service providing the
  authorization gate (Checker) plus admin add/remove/list (Manager),
  with EIP-55 validation/normalization. The admin HTTP handlers and
  bearer middleware live here.
- userstore: RemoveFromWhitelist reports rows-affected (for 404);
  ListWhitelist is cursor-based (ORDER BY evm_address, the unique PK);
  whitelist lookups (IsWhitelisted/Remove) are case-insensitive via
  LOWER(evm_address), backed by a functional index (migration 15).
- config: optional AdminAPI block; api_key required_if enabled.
- e2e: whitelisting now goes through the admin endpoint instead of a
  direct DB insert; adds full lifecycle + pagination tests.

* fix(api): address review feedback on whitelist

- ListWhitelist: order and compare the cursor on LOWER(evm_address) so
  cursor pagination is case-insensitive and stable for mixed-case (EIP-55)
  addresses, consistent with the IsWhitelisted/Remove lookups and the
  LOWER(evm_address) functional index. Uses OrderExpr so the LOWER(...)
  is emitted as raw SQL rather than quoted as a column. Adds a mixed-case
  cursor test.
- writeJSON: marshal the payload before writing the status line so a
  serialization failure returns 500 instead of a 200 with a truncated
  body (whitelist admin + registration handlers).

* fix(api): make admin opt-in via ADMIN_API_ENABLED

admin.enabled was hardcoded true in the default configs, so every process
that loads the api-server config — including the bootstrap (bootstrap-demo
/ bootstrap-bridge call config.LoadAPIServer) — required ADMIN_API_KEY to
pass required_if validation. The bootstrap container has no such token, so
its config load failed and the DEMO TokenConfig / bridge TransferFactory
were never created, breaking the transfer/balance/registry e2e tests.

Make admin opt-in: enabled is now driven by ${ADMIN_API_ENABLED} (default
off, mirroring skip_canton_sig_verify). The api-server service sets it to
true in compose; the bootstrap leaves it unset, so its config load no
longer needs a token. Also keeps admin off-by-default for mainnet.

Author: sadiq1971

docker-compose.yaml

@@ -299,6 +299,12 @@ services:
       CANTON_AUTH_CLIENT_SECRET: "${CANTON_AUTH_CLIENT_SECRET:-local-test-secret}"
       CANTON_MASTER_KEY: "${CANTON_MASTER_KEY}"  # Generate with: openssl rand -base64 32
       SKIP_CANTON_SIG_VERIFY: "${SKIP_CANTON_SIG_VERIFY:-false}"  # Set to "true" for local testing
+      # Admin API: enabled on the api-server only. The bootstrap loads the same
+      # config but leaves ADMIN_API_ENABLED unset, so admin stays off there and
+      # its config load doesn't require a token. The key default MUST match
+      # defaultAdminAPIKey in tests/e2e/devstack/shim/apiserver.go.
+      ADMIN_API_ENABLED: "true"
+      ADMIN_API_KEY: "${ADMIN_API_KEY:-local-admin-key}"
     depends_on:
       bootstrap:
         condition: service_completed_successfully

pkg/app/api/server.go

@@ -160,7 +160,18 @@ func (s *Server) Run() error {
 		)
 	}
 
-	router := s.setupRouter(svcs.evmStore, wl, cantonClient, svcs.tokenService, svcs.regSvc, svcs.transferSvc, metrics, logger)
+	// Admin config is optional (nil when the `admin` block is omitted). The token
+	// is resolved by the config loader (api_key: "${ADMIN_API_KEY}") and validated
+	// as required when enabled, so setupRouter can read it straight off the value.
+	var adminCfg config.AdminAPI
+	if cfg.Admin != nil {
+		adminCfg = *cfg.Admin
+	}
+
+	router := s.setupRouter(
+		svcs.evmStore, wl, cantonClient, svcs.tokenService, svcs.regSvc, svcs.transferSvc,
+		adminCfg, metrics, logger,
+	)
 
 	s.registerServers(g, gCtx, router, logger)
 
@@ -364,11 +375,12 @@ func (s *Server) registerServers(g *errgroup.Group, gCtx context.Context, router
 
 func (s *Server) setupRouter(
 	evmStore ethrpc.Store,
-	wl whitelist.Checker,
+	wl *whitelist.Service,
 	cantonClient *canton.Client,
 	tokenService *token.Service,
-	registrationService userservice.Service,
+	userService userservice.Service,
 	transferSvc transfer.Service,
+	adminCfg config.AdminAPI,
 	metrics *apphttp.HTTPMetrics,
 	logger *zap.Logger,
 ) chi.Router {
@@ -392,7 +404,12 @@ func (s *Server) setupRouter(
 	token.RegisterRoutes(r, tokenService, logger)
 
 	// Registration endpoints
-	userservice.RegisterRoutes(r, registrationService, logger)
+	userservice.RegisterRoutes(r, userService, logger)
+
+	// Admin endpoints (whitelist management), gated by a static bearer token.
+	if adminCfg.Enabled {
+		whitelist.RegisterAdminRoutes(r, wl, adminCfg.APIKey, logger)
+	}
 
 	// Non-custodial transfer endpoints (prepare/execute)
 	transfer.RegisterRoutes(r, transferSvc, logger)

pkg/config/config.go

@@ -82,6 +82,18 @@ type APIServer struct {
 	SkipCantonSigVerify bool                          `yaml:"skip_canton_sig_verify" default:"false"`
 	SkipWhitelistCheck  bool                          `yaml:"skip_whitelist_check" default:"false"`
 	CORSOrigins         []string                      `yaml:"cors" default:"[\"*\"]"`
+	Admin               *AdminAPI                     `yaml:"admin" default:"-"` // nil disables the admin endpoints
+}
+
+// AdminAPI configures the optional admin HTTP endpoints (whitelist management).
+// Access is gated by a static bearer token. Supply it via env substitution
+// (api_key: "${ADMIN_API_KEY}")
+type AdminAPI struct {
+	// Enabled turns the admin endpoints on. When false (the default) no admin
+	// routes are mounted.
+	Enabled bool `yaml:"enabled" default:"false"`
+	// APIKey is the admin bearer token. Required when Enabled is true.
+	APIKey string `yaml:"api_key" validate:"required_if=Enabled true"`
 }
 
 // RelayerServer represents the application configuration for relayer.

pkg/config/config_test.go

@@ -257,6 +257,18 @@ func TestLoadAPIServer_RequiredValidation(t *testing.T) {
 	}
 }
 
+func TestLoadAPIServer_AdminEnabledRequiresKey(t *testing.T) {
+	path := testConfigPath(t, "admin-enabled-no-key.api.yaml")
+
+	_, err := LoadAPIServer(path)
+	if err == nil {
+		t.Fatal("expected required validation error for admin.api_key, got nil")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "api_key") {
+		t.Fatalf("expected admin.api_key validation error, got: %v", err)
+	}
+}
+
 func TestLoadAPIServer_InvalidDatabaseURL(t *testing.T) {
 	path := testConfigPath(t, "invalid-database-url.api.yaml")
 
@@ -409,4 +421,5 @@ func setDefaultConfigEnv(t *testing.T) {
 	t.Setenv("INDEXER_URL", "http://indexer:8082")
 	t.Setenv("CANTON_USDCX_ISSUER_PARTY", "usdcx-issuer::1220test")
 	t.Setenv("CANTON_USDCX_REGISTRY_URL", "http://usdcx-registry:8090")
+	t.Setenv("ADMIN_API_KEY", "test-admin-key")
 }

pkg/config/defaults/config.api-server.docker.yaml

@@ -134,5 +134,12 @@ key_management:
 skip_canton_sig_verify: ${SKIP_CANTON_SIG_VERIFY}
 skip_whitelist_check: false
 
+# Admin API for whitelist management (POST/DELETE/GET /admin/whitelist).
+# Enabled by ADMIN_API_ENABLED=true (default off); gated by a static bearer
+# token supplied via ADMIN_API_KEY (required when enabled).
+admin:
+  enabled: ${ADMIN_API_ENABLED}
+  api_key: "${ADMIN_API_KEY}"
+
 cors:
   - "*"

pkg/config/defaults/config.api-server.local-devnet.yaml

@@ -125,5 +125,12 @@ key_management:
 
 skip_whitelist_check: true
 
+# Admin API for whitelist management (POST/DELETE/GET /admin/whitelist).
+# Enabled by ADMIN_API_ENABLED=true (default off); gated by a static bearer
+# token supplied via ADMIN_API_KEY (required when enabled).
+admin:
+  enabled: ${ADMIN_API_ENABLED}
+  api_key: "${ADMIN_API_KEY}"
+
 cors:
   - "*"

pkg/config/defaults/config.api-server.mainnet.yaml

@@ -99,5 +99,12 @@ key_management:
 
 skip_canton_sig_verify: false
 
+# Admin API for whitelist management (POST/DELETE/GET /admin/whitelist).
+# Enabled by ADMIN_API_ENABLED=true (default off); gated by a static bearer
+# token supplied via ADMIN_API_KEY (required when enabled).
+admin:
+  enabled: ${ADMIN_API_ENABLED}
+  api_key: "${ADMIN_API_KEY}"
+
 cors:
   - "${CORS_ALLOWED_ORIGINS}"

pkg/config/tests/admin-enabled-no-key.api.yaml

@@ -0,0 +1,48 @@
+server:
+  host: "0.0.0.0"
+  port: 8081
+
+database:
+  url: "postgres://postgres:pass@localhost:5432/erc20_api"
+  ssl_mode: "disable"
+
+canton:
+  domain_id: "domain"
+  issuer_party: "issuer"
+  ledger:
+    rpc_url: "localhost:5011"
+    tls: {}
+    auth:
+      client_id: "client"
+      client_secret: "secret"
+      audience: "audience"
+      token_url: "http://localhost/token"
+  identity:
+    package_id: "identity-package"
+  token:
+    cip56_package_id: "cip56-package"
+    splice_transfer_package_id: "splice-package"
+    splice_holding_package_id: "test-splice-holding-pkg-id"
+
+token:
+  supported_tokens:
+    "0x0000000000000000000000000000000000000001":
+      name: "PROMPT"
+      symbol: "PROMPT"
+      decimals: 18
+      instrument_id: "PROMPT"
+
+eth_rpc:
+  chain_id: 31337
+
+logging:
+  level: "info"
+  format: "json"
+
+key_management: {}
+monitoring:
+  enabled: false
+
+# Admin enabled but no api_key — must fail required_if validation.
+admin:
+  enabled: true

pkg/ethrpc/service/service.go

@@ -96,7 +96,7 @@ const (
 )
 
 // NewService creates a new ethService. whitelist authorizes transaction senders
-// in SendRawTransaction and must be non-nil; pass whitelist.New(src, true) to
+// in SendRawTransaction and must be non-nil; pass whitelist.New(store, true) to
 // disable the gate (skip_whitelist_check).
 func NewService(
 	cfg *ethrpc.Config,

pkg/user/service/http.go

@@ -145,9 +145,15 @@ func (h *HTTP) getUser(w http.ResponseWriter, r *http.Request) error {
 }
 
 func (h *HTTP) writeJSON(w http.ResponseWriter, status int, data any) {
+	// Marshal before writing the status line so a serialization failure yields a
+	// 500 rather than the intended status with a truncated body.
+	buf, err := json.Marshal(data)
+	if err != nil {
+		h.logger.Error("failed to marshal JSON response", zap.Error(err))
+		http.Error(w, "internal server error", http.StatusInternalServerError)
+		return
+	}
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	if err := json.NewEncoder(w).Encode(data); err != nil {
-		h.logger.Error("failed to write JSON response", zap.Error(err))
-	}
+	_, _ = w.Write(buf)
 }