BryanTheLai / BryanTheLai/fraud-v2

Gateway signal contract and mock vendor matrix

Open
#2 0 comments 0 reactions 0 assignees View on GitHub
area:data area:gateway blocked:production feasible:local priority:p0 spec-ready truth-first
Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Rank
P0. Feasible locally. Production blocked.

## Goal
Create one canonical gateway signal contract for KYC/KYB/liveness/device/consortium-shaped signals. Do not call real vendors.

## Why
Gateway signals feed features, decisions, graph evidence, compliance evidence, and cockpit UI. Without canonical events, later work will couple to mock vendor internals.

## Current Assets
- `src/fraud_v2/domain/events.py`
- `src/fraud_v2/domain/enums.py`
- `src/fraud_v2/connectors/mock_vendors.py`
- `src/fraud_v2/connectors/signal_lab.py`
- `src/fraud_v2/converters/raw_events.py`

## Build
- Add `GatewaySignalType`: `KYC`, `KYB`, `LIVENESS`, `DEVICE_INTEL`, `CAMERA_METADATA`, `CONSORTIUM`, `SANCTIONS_SHAPE`.
- Add `GatewaySignalStatus`: `OK`, `REVIEW`, `DENY_SHAPE`, `STALE`, `TIMEOUT`, `ERROR`, `UNKNOWN`.
- Add `GatewaySignalObserved` payload.
- Add `ConsortiumRiskObserved` payload.
- Extend `CanonicalPayload`.
- Build `GatewaySignalConverter` from `ConnectorResult` to `EventEnvelope`.
- Simulate timeout, stale, denied-shape, review, unknown, malformed.

## Missing
- Typed gateway payloads.
- Single connector-to-event converter.
- Tests proving features/decisions do not import vendor classes.

## Acceptance
- Canonical gateway and consortium events exist.
- Existing mock KYC/device/consortium/camera/KYB outputs map to canonical events.
- Converter tests cover valid, missing field, bad enum, duplicate idempotency key, stale, timeout, unsafe PII-like input.
- Docs say real vendors are blocked by contracts, legal review, credentials, and permitted use.

## Out Of Scope
- Real vendor calls.
- Real PII.
## Truth Boundary
- No real PII.
- No real KYC/KYB/liveness/sanctions/consortium calls.
- No real money movement.
- No real customer messages.
- No real SAR or adverse-action filing.
- If blocked, simulate locally and label it as simulated.
## Links
- Target article: https://www.bryanslab.com/blogs/fraud-2/
- Master spec: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/target-goal-gap-and-issue-spec.md
- Ranked issue map: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/issue-evaluation-ranking.md
- Production readiness: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/production-readiness.md
- Agent rules: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/AGENTS.md
## Required Proof
- `uv run ruff format --check .`
- `uv run ruff check .`
- `uv run mypy src`
- `uv run pytest -q`

If Docker/full profile changes:
- `docker compose -f infra\docker-compose.yml --profile full config --quiet`
- `docker build -t fraud-v2:local .`

Contributor guide

No contributing guide indexed for this repository

Research direction

Read src/fraud_v2/domain/events.py, src/fraud_v2/domain/enums.py, src/fraud_v2/connectors/mock_vendors.py, src/fraud_v2/connectors/signal_lab.py, and src/fraud_v2/converters/raw_events.py to map the existing event and connector shapes. Run the required pytest, ruff, and mypy commands while working; done means canonical gateway and consortium events, converter coverage for the listed cases, vendor-independent tests, and documentation of the production boundary.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.