card-fraud-rule-engine-auth

Imported from fraud-platform/card-fraud-rule-engine-auth (AGENTS.md). Install upstream with npx skills add fraud-platform/card-fraud-rule-engine-auth. Copyright stays with the author.

AGENTS.md

This is the canonical instruction file for all coding agents working in card-fraud-rule-engine-auth.

Split Info: This repo was split from card-fraud-rule-engine on 2026-02-13 (baseline tag: split-baseline-2026-02-13). This is the AUTH-only service.

• CLAUDE.md must stay a thin pointer to this file.
• If any other document conflicts with this file, follow AGENTS.md.
• Keep docs and implementation aligned in the same PR.

Cross-Repo Agent Standards

• Secrets: Doppler-only workflows. Do not create or commit .env files.
• Commands: use repository wrappers from pyproject.toml or package.json; avoid ad-hoc commands.
• Git hooks: run git config core.hooksPath .githooks after clone to enable pre-push guards.
• Git workflow: work only on local main; do not create branches or linked worktrees. Push only origin/main. The pre-push guard covers Codex and Claude sessions; agents require CARD_FRAUD_ALLOW_GIT_PUSH=1 for an explicitly requested push.
• Docs publishing: keep only curated docs in docs/01-setup through docs/07-reference, plus docs/README.md and docs/codemap.md.
• Docs naming: use lowercase kebab-case for docs files. Exceptions: README.md, codemap.md, and generated contract files.
• Never commit docs/planning artifacts named todo, status, archive, or session notes.
• If behavior, routes, scripts, ports, or setup steps change, update README.md, AGENTS.md, docs/README.md, and docs/codemap.md in the same change.
• Keep health endpoint references consistent with current service contracts (for APIs, prefer /api/v1/health).
• preserve shared local port conventions from card-fraud-platform unless an explicit migration is planned.
• Before handoff, run the repo's local lint/type/test gate and report the exact command + result.

1) Non-Negotiable Rules

Doppler is mandatory

Do not run the app or tests with raw Maven commands.

• Dev server: uv run doppler-local
• Unit tests: uv run test-unit
• Integration tests: uv run test-integration
• Full test suite: uv run test-all

Never use:

• mvn quarkus:dev
• mvn test
• .env files for this repository

Secrets model

This project uses Doppler only.

• Project: card-fraud-rule-engine-auth
• Primary config: local

API path casing

Evaluation endpoint paths are lowercase and case-sensitive:

• POST /v1/evaluate/auth

Do not document or test uppercase route variants.

2) Quickstart For Any Agent

# 1) Install dependencies
uv sync

# 2) Start local infra (fallback compose)
uv run infra-local-up

# 3) Verify Redis
uv run redis-local-verify

# 4) Start app with Doppler secrets
uv run doppler-local

Recommended shared platform flow:

cd ../card-fraud-platform
uv run platform-up
uv run platform-status
cd ../card-fraud-rule-engine-auth
uv run doppler-local

3) Command Catalog (Source: pyproject.toml)

Infrastructure

• uv run infra-local-up
• uv run infra-local-down
• uv run redis-local-up
• uv run redis-local-down
• uv run redis-local-reset
• uv run redis-local-verify

Runtime

• uv run doppler-local
• uv run doppler-local-test
• uv run doppler-load-test
• uv run doppler-secrets-verify

Gateway Auth

• Authentication is enforced at API Gateway; rule engine does not validate tokens on-box.
• Do not add password-realm logins or role-user credentials to this service. Auth0 setup helpers use M2M client credentials, and the load harness sends no per-request token.

Java and E2E tests

• uv run test-unit
• uv run test-smoke
• uv run test-integration
• uv run test-all
• uv run test-coverage
• uv run test-e2e
• uv run test-load

Quality

• uv run lint
• uv run format
• uv run snyk-test

4) Runtime Architecture

This service is a stateless Quarkus rule engine for AUTH card fraud decisioning.

Primary responsibilities:

• AUTH evaluation: first-match, fail-open default APPROVE
• Redis velocity checks (atomic counters + Lua)
• Ruleset loading/hot reload from MinIO/S3
• Ruleset namespace is fixed to CARD_AUTH
• Decision path: returns immediately after evaluation and enqueues for async durability; background writer persists to Redis Streams, publishes to Redpanda/Kafka with ack
• AUTH evaluation (evaluateAuth) runs on virtual threads (@RunOnVirtualThread), so blocking Redis velocity calls park the virtual thread instead of consuming the bounded worker pool

Core dependencies:

• Redis 8.x
• Redpanda (Kafka API)
• MinIO (artifact read path)
• API Gateway-authenticated ingress (token verification offloaded upstream)
• Doppler secrets

5) API Surface

Evaluation endpoints

• POST /v1/evaluate/auth
• GET /v1/evaluate/health
• GET /v1/evaluate/rulesets/registry/status
• GET /v1/evaluate/rulesets/registry/{country}
• POST /v1/evaluate/rulesets/hotswap
• POST /v1/evaluate/rulesets/load
• POST /v1/evaluate/rulesets/bulk-load

Management endpoints

• POST /v1/manage/replay
• POST /v1/manage/replay/batch
• POST /v1/manage/simulate
• GET /v1/manage/metrics
• Prometheus scrape endpoint: GET /q/metrics

OpenAPI and UI when running:

• http://localhost:8081/openapi
• http://localhost:8081/swagger-ui

6) Authentication and Authorization

Token verification and scope authorization are handled by the API Gateway layer. The rule engine trusts gateway-forwarded traffic and does not perform in-process token validation.

7) Test Reality (Verified 2026-02-13)

Commands executed:

• uv run test-unit -> PASS
• uv run test-integration -> PASS

Observed results:

• Unit profile: Tests run: 440, Failures: 0, Errors: 0, Skipped: 3
• Note: Test count is lower than baseline (504) due to removal of monitoring-specific tests

8) Documentation Policy

When behavior changes, update all relevant docs in the same change:

• README.md
• AGENTS.md
• openapi.yaml (if contract changed)

9) Cross-Repo Context

This repo is part of:

• card-fraud-platform (shared infra)
• card-fraud-rule-management (rules authoring + artifact publish)
• card-fraud-transaction-management
• card-fraud-intelligence-portal
• card-fraud-e2e-load-testing
• card-fraud-rule-engine-monitoring (sibling MONITORING service)

MinIO write path is owned by rule-management. Rule engine reads artifacts only.

10) Common Failure Modes

• Redis unavailable -> start with uv run redis-local-up or platform-up
• Doppler missing/invalid session -> run doppler login
• Wrong path casing (/AUTH) -> use lowercase path
• Running raw Maven directly -> switch to uv run ... wrappers
• Redis Streams outbox down -> AUTH must fail fast; ensure Redis is up with AOF + replica before load tests (see ADR-0014)
• Load test shows 250ms+ P50 -> do NOT use mvn quarkus:dev for load testing; JaCoCo agent + dev mode adds massive overhead. Use the packaged JAR instead.
• LoadSheddingFilter rejects requests -> app.load-shedding.enabled: false in %load-test profile
• Redis operations hang -> all Redis ops now have 5s bounded timeouts

11) Agent Handoff Checklist

Before ending a session:

• Confirm changed commands and endpoint paths are accurate
• Run the minimum relevant test command(s)
• Run uv run snyk-test before push when dependency/runtime versions change
• Keep CLAUDE.md pointing to AGENTS.md
• Record only factual, verified metrics/dates

12) Load Testing

CRITICAL: Both uv run doppler-local and uv run doppler-load-test use mvn quarkus:dev which includes JaCoCo instrumentation and dev mode overhead. These are NOT suitable for performance measurement.

For valid load test results, use the packaged JAR:

# Build (once)
doppler run --config local -- mvn package -DskipTests -Dquarkus.package.jar.type=uber-jar

# Run with load-test profile (disables load shedding, sets WARN logging)
doppler run --config local -- \
  java -jar target/card-fraud-rule-engine-1.0.0-SNAPSHOT-runner.jar \
  -Dquarkus.profile=load-test

Load test configuration (%load-test profile):

• app.load-shedding.enabled: false - Measure true capacity
• app.auth.async-durability.enabled: false - Disable AUTH async durability side-effects
• app.outbox.worker.enabled: false - Disable the MONITORING outbox worker for AUTH-only perf runs
• app.outbox.auth-publisher.enabled: false - Disable the AUTH outbox publisher
• quarkus.log.level: WARN - Suppress hot-path logging
• app.evaluation.timing-sample-every-n: 100 - Sample the detailed TimingBreakdown on ~1 of every 100 AUTH requests
• quarkus.redis.max-waiting-handlers: 500 - Raised from the base 100: with load shedding off and AUTH evaluation on virtual threads, concurrent blocking Redis calls are no longer capped by the worker pool and can exceed the base waiting-handler queue

For split-service end-to-end load testing via Docker (recommended for AUTH+MONITORING flow), use:

cd ../card-fraud-platform
doppler run -- uv run platform-up -- --apps

cd ../card-fraud-e2e-load-testing
uv run lt-rule-engine --users=50 --spawn-rate=10 --run-time=2m --scenario baseline --headless

Last updated: 2026-02-13