KYC and Identity Verification Domain - KYC, AML, and Underwriting Eligibility Interactions

Overview

This domain ties together applicant identity verification, bureau access rules, consent enforcement, and underwriting eligibility gating. On the frontend side, frontend/components/underwriting-compliance.tsx presents an underwriting document preview with regenerate and send actions, while the KYC proxy routes in frontend/app/api/kyc/route.ts and frontend/app/api/kyc/[verificationId]/route.ts start identity verification and retrieve verification status. On the backend, backend/src/usecase/kyc.py passes KYC requests through to a KycGateway, and backend/src/usecase/japan_staff_credit.py enforces consent, operator authorization, and bureau-access constraints before a staff-initiated credit pull can proceed.

The compliance policy is not just about identity data collection. It also controls what happens after identity is verified: permissible purpose is carried into bureau access, consent expiry and revocation block pulls, unauthorized operators are rejected, and AML-related flags in the underwriting pipeline can decline an application before scoring. The planning document in documents/spinwheel-integration-plan.md describes a streamlined Equifax-based intake path, but the implemented route still applies stricter field requirements and uses existing KYC gateway orchestration.

Architecture Overview

flowchart TB
  subgraph PresentationLayer [Presentation Layer]
    UnderwritingCompliance[Underwriting Compliance component]
    KycCreateRoute[POST api kyc route]
    KycStatusRoute[GET api kyc verification route]
  end

  subgraph BusinessLayer [Business Layer]
    KycUseCases[Kyc use cases]
    JapanStaffCreditUseCases[Japan staff credit use cases]
    EligibilityGate[AML and underwriting gate]
  end

  subgraph DataAccessLayer [Data Access Layer]
    BackendCreateToken[create_link_token_id_verification]
    BackendVerificationStatus[identity_verification_status]
    ConsentRepository[StaffCreditConsentRepository]
    PullLogRepository[StaffCreditPullLogRepository]
    BureauClient[JapanCreditBureauHTTPClient]
  end

  subgraph ExternalSystems [External Systems]
    KycGateway[KycGateway]
    BureauNetwork[Bureau network]
    EmailOverlay[EmailOverlay]
  end

  UnderwritingCompliance --> EmailOverlay
  KycCreateRoute --> KycUseCases
  KycStatusRoute --> KycUseCases
  KycUseCases --> BackendCreateToken
  KycUseCases --> BackendVerificationStatus
  BackendCreateToken --> KycGateway
  BackendVerificationStatus --> KycGateway
  JapanStaffCreditUseCases --> ConsentRepository
  JapanStaffCreditUseCases --> PullLogRepository
  JapanStaffCreditUseCases --> BureauClient
  BureauClient --> BureauNetwork
  EligibilityGate --> KycUseCases
  EligibilityGate --> JapanStaffCreditUseCases

Policy and Eligibility Rules

[!NOTE] documents/spinwheel-integration-plan.md describes a phone number and date of birth intake, but buildPrefillPayload in frontend/app/api/kyc/route.ts requires email, phone, full name, date of birth, and address fields before the backend verifier is called. The current route does not implement the lighter intake shape described in the plan.

The code expresses a set of hard gates that determine whether identity verification can start, whether bureau access is allowed, and whether underwriting can proceed.

Rule Code Path Operational Effect
Identity payload must include email and phone buildPrefillPayload in frontend/app/api/kyc/route.ts The verification request is rejected with a 400 response if either field is missing.
Address fields must be present buildPrefillPayload Missing street, city, region, or postal code stops the KYC bootstrap.
Auth token must be present POST /api/kyc route Requests without a token return 401 before any backend lookup.
Consent expiration must be in the future register_staff_credit_consent Past-dated consent is rejected with ConsentExpiredError.
Consent must be active at request time perform_staff_credit_pull Expired or revoked consent blocks bureau access.
Operator must be allowed by consent perform_staff_credit_pull and consent.ensure_operator_allowed Unauthorized staff members are rejected with OperatorNotAllowedError.
Permissible purpose must be resolved perform_staff_credit_pull The resolved purpose is passed to the bureau client and becomes part of the audit trail.
AML risk blocks underwriting backend/src/ml/credit_pipeline_validation.py AML_RISK_DETECTED is a decline flag, so scoring is halted before model output.
KYC failure blocks underwriting backend/src/ml/credit_pipeline_validation.py KYC_NOT_PASSED is a decline flag, so the application does not continue to scoring.
Bureau absence can trigger refer status backend/src/ml/credit_pipeline_validation.py Missing bureau data, missing banking data, or insufficient history can refer the application instead of passing it.

Presentation Layer

Underwriting Compliance Document Preview

[!IMPORTANT] perform_staff_credit_pull does not let staff bypass consent. It checks the stored consent, rejects revoked or expired consent, verifies the operator ID, and only then calls the bureau client. The bureau call happens after those checks, so operator misconfiguration is blocked before any external pull is attempted.

frontend/components/underwriting-compliance.tsx

This component renders a mortgage underwriting document preview, animates the document text while it is “generating,” and opens an email overlay when the operator chooses to send the document onward. It does not call the KYC backend directly; it is the visible underwriting artifact that sits alongside the identity and compliance workflow.

Properties

Property Type Description
isGenerating boolean Controls the simulated document generation state and disables the regenerate button while active.
document string Holds the current underwriting document text rendered inside the preview.
isOverlayOpen boolean Controls whether EmailOverlay is displayed.
animatedDocument string Output from useAnimatedText(document, isGenerating) used in the preview area.

Internal Actions

Action Description
handleRegenerate Turns generation off, waits 100 ms, resets the document text to INITIAL_DOCUMENT, and re-enables generation.
handleSend Opens the EmailOverlay.
useEffect timer cleanup Starts a 10-second timer on mount and clears it on unmount.

Dependencies

Type Description
useState Local UI state for generation and overlay visibility.
useEffect Handles the generation timeout and cleanup.
useAnimatedText Animates the underwriting document text while generation is active.
EmailOverlay Modal-like sending surface used by the send action.
Card, Button Presentation controls for the preview and action buttons.

UI States

State Trigger Result
Generating Initial mount or handleRegenerate Text is animated and the regenerate button is disabled.
Ready Timer completes or document reset finishes Preview stops animating and the regenerate button becomes usable.
Overlay open handleSend EmailOverlay is shown.

API Integration

POST /api/kyc

{
    "title": "Create Identity Verification Link Token",
    "description": "Validates the applicant reference, loads the application, builds the prefill payload, and starts identity verification through the backend verifier",
    "method": "POST",
    "baseUrl": "<NextJsAppBaseUrl>",
    "endpoint": "/api/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicationId\": \"app_100024\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Identity verification started",
            "body": "{\n    \"linkToken\": \"link-sandbox-4d1f9d9f2c3a\",\n    \"verification\": {\n        \"status\": \"success\"\n    },\n    \"applicant\": {\n        \"id\": \"app_100024\",\n        \"email\": \"[email protected]\",\n        \"phone\": \"+1-202-555-0148\",\n        \"fullName\": \"Jane Doe\",\n        \"dateOfBirth\": \"1992-04-18\",\n        \"address\": {\n            \"street\": \"123 Main St\",\n            \"city\": \"Seattle\",\n            \"region\": \"WA\",\n            \"postalCode\": \"98101\",\n            \"country\": \"US\"\n        }\n    }\n}"
        },
        "400": {
            "description": "Invalid request payload or missing applicant data",
            "body": "{\n    \"detail\": \"Application id is required\"\n}"
        },
        "401": {
            "description": "Authentication is missing",
            "body": "{\n    \"detail\": \"Authentication required\"\n}"
        },
        "404": {
            "description": "Applicant not found",
            "body": "{\n    \"detail\": \"Application not found\"\n}"
        },
        "502": {
            "description": "Backend verification or application lookup failed",
            "body": "{\n    \"detail\": \"Failed to start Plaid identity verification\"\n}"
        }
    }
}

This route performs several checks before it reaches the backend verifier:

  1. Parses applicationId with zod.
  2. Extracts an auth token from the incoming headers.
  3. Loads application data from backend candidates.
  4. Builds the prefill payload from application fields.
  5. Calls the backend verifier with POST /create_link_token_id_verification.
  6. Returns the link token, backend verification payload, and applicant summary.

Request Model: requestSchema

Property Type Description
applicationId `string \ number`

Internal Prefill Model: PrefillPayload

Property Type Description
email string Applicant email forwarded to the backend verifier.
phone string Normalized phone number.
first_name string First name extracted from the application full name.
last_name string Last name extracted from the application full name or defaulted to Applicant.
dob_year number Year extracted from the application date of birth.
dob_month number Month extracted from the application date of birth.
dob_day number Day extracted from the application date of birth.
street string Required address line.
city string Required address city.
region string Required address region.
postal_code string Required postal code.
country string Address country, defaulting to US.

Response Model

Property Type Description
linkToken string Token returned by the backend verification service.
verification Record<string, unknown> Verification payload forwarded from the backend.
applicant object Applicant details used for the verification prefill.

[!NOTE] The route’s log and error strings still say “Plaid verification” and “Plaid KYC,” even though the surrounding plan document describes an Equifax-based identity flow. That mismatch affects operator-facing diagnostics and can make the integration look like a different provider than the one described in documents/spinwheel-integration-plan.md.


Get Identity Verification Status

GET /api/kyc/[verificationId]

{
    "title": "Get Identity Verification Status",
    "description": "Proxies verification status lookups to the backend identity-verification status endpoint",
    "method": "GET",
    "baseUrl": "<NextJsAppBaseUrl>",
    "endpoint": "/api/kyc/{verificationId}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "verificationId",
            "value": "verif_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Verification status returned",
            "body": "{\n    \"verification\": {\n        \"status\": \"success\"\n    }\n}"
        },
        "400": {
            "description": "Invalid verification id",
            "body": "{\n    \"detail\": \"Invalid verification id\"\n}"
        },
        "404": {
            "description": "Verification record not found",
            "body": "{\n    \"detail\": \"Verification not found\"\n}"
        },
        "502": {
            "description": "Backend status lookup failed",
            "body": "{\n    \"detail\": \"Failed to load verification status\"\n}"
        }
    }
}

This route does not require an auth token in the visible code path. It validates the path parameter, calls the backend identity status endpoint, and returns the result under a verification wrapper. The backend fetch uses cache: "no-store", so each request is evaluated fresh.

Response Model

Property Type Description
verification Record<string, unknown> Backend verification status payload forwarded without additional normalization.

POST /create_link_token_id_verification

{
    "title": "Create Verification Link Token",
    "description": "Builds a user record from the prefill request, invokes the KYC gateway, and returns the link token response",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/create_link_token_id_verification",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"phone\": \"+1-202-555-0148\",\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"dob_year\": 1992,\n    \"dob_month\": 4,\n    \"dob_day\": 18,\n    \"street\": \"123 Main St\",\n    \"city\": \"Seattle\",\n    \"region\": \"WA\",\n    \"postal_code\": \"98101\",\n    \"country\": \"US\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Backend verification bootstrap response",
            "body": "{\n    \"link_token\": \"link-sandbox-4d1f9d9f2c3a\",\n    \"verification\": {\n        \"status\": \"success\"\n    }\n}"
        },
        "500": {
            "description": "Gateway failure",
            "body": "{\n    \"detail\": \"Plaid response did not include a link_token\"\n}"
        }
    }
}

backend/src/interface/http_endpoints.py creates a user_id, maps request values into user_data, instantiates PlaidKycGateway, and passes the payload to generate_link_token_id_verification. If the gateway does not return a link token, the handler raises a 500 error.

Response Model

Property Type Description
link_token string Link token generated by the KYC gateway.
verification object Verification payload returned by the gateway if present.

Get Verification Status

GET /identity_verification_status/{verification_id}

{
    "title": "Get Verification Status",
    "description": "Returns the current identity verification status for the provided verification id",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/identity_verification_status/{verification_id}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "verification_id",
            "value": "verif_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Status payload returned by the gateway",
            "body": "{\n    \"status\": \"success\"\n}"
        }
    }
}

This endpoint passes the verification ID to the gateway and returns the resulting status object directly.

Response Model

Property Type Description
status string Gateway status response forwarded to the caller.

Business Layer

KYC Use Cases

backend/src/usecase/kyc.py

These use cases are thin delegators around KycGateway. They do not add policy logic themselves; they simply pass the input through and return the gateway payload.

Methods

Method Description Returns
generate_link_token_id_verification Calls create_link_token_id_verification on the injected KycGateway. Dict
kyc_get_identity_verification_status Calls get_identity_verification_status on the injected KycGateway. Dict[str, Any]

Dependencies

Type Description
KycGateway Gateway contract used to start verification and fetch verification status.
Dict Input and output payloads are dictionary-based.

Japan Staff Credit Use Cases

backend/src/usecase/japan_staff_credit.py

These use cases control the operator-initiated bureau workflow in Japan. They enforce consent validity, operator authorization, and bureau call logging before any credit report is returned.

Methods

Method Description Returns
register_staff_credit_consent Validates that the consent expiry is in the future, deduplicates and sorts allowed operator IDs, and persists the consent. StaffCreditConsent
perform_staff_credit_pull Validates consent existence, revocation state, expiry, and operator eligibility before requesting a bureau report and persisting the pull log. Dict[str, object]

Dependencies

Type Description
StaffCreditConsentRepository Stores and retrieves consent records by reference.
StaffCreditPullLogRepository Persists request logs for bureau pulls.
bureau_client Requests the bureau report using customer profile and permissible purpose.
StaffCreditConsentRequest Input model for consent registration.
StaffCreditPullRequest Input model for a staff-initiated bureau pull.

Eligibility Behavior

  • register_staff_credit_consent rejects past-dated expirations with ConsentExpiredError.
  • perform_staff_credit_pull raises ConsentNotFoundError if the consent reference does not exist.
  • perform_staff_credit_pull raises ConsentRevokedError or ConsentExpiredError when the stored consent is not active.
  • consent.ensure_operator_allowed(request.operator_id) blocks unauthorized operator IDs.
  • The bureau call uses request.permissible_purpose or consent.permissible_purpose, so the resolved purpose is what reaches the bureau client.
  • Bureau failures still create a persisted log entry before BureauRequestError is raised.

Eligibility Gate and AML Flags

backend/src/ml/credit_pipeline_validation.py

The scoring pipeline uses deterministic gate ordering before any model call. The documented priority is:

  1. DECLINE
  2. REFER
  3. PASS

Relevant flags from the code are:

  • KYC_NOT_PASSED
  • FRAUD_RISK_DETECTED
  • AML_RISK_DETECTED
  • BUREAU_REQUIRED_BUT_ABSENT
  • NO_BANKING_DATA
  • INSUFFICIENT_HISTORY

In practice, a KYC or AML problem can stop underwriting before credit scoring. A bureau gap can push the case into a refer path instead of a pass path.

Data Models

src.domain.japan_credit.StaffCreditConsentRequest as used in backend/tests/usecase/test_japan_staff_credit.py

Property Type Description
consent_reference str External reference used to retrieve consent.
customer_reference str Customer identifier associated with the consent.
customer_name str Customer display name.
permissible_purpose str Bureau purpose attached to the consent.
expires_at datetime Consent expiry timestamp.
allowed_operator_ids list[str] Allowed staff operator IDs.
customer_profile dict[str, object] Customer profile sent to the bureau client.
metadata `dict[str, object] \ None`

src.domain.japan_credit.StaffCreditConsent as used in backend/tests/usecase/test_japan_staff_credit.py

Property Type Description
id `int \ None`
consent_reference str External reference used to locate the consent.
customer_reference str Customer identifier.
customer_name str Customer name stored with consent.
permissible_purpose str Purpose tied to the consent.
expires_at datetime Expiration timestamp.
allowed_operator_ids tuple[str, ...] Deduplicated and sorted allowed operators.
customer_profile dict[str, object] Bureau payload context.
metadata `dict[str, object] \ None`
revoked_at `datetime \ None`

Staff Credit Pull Request

src.domain.japan_credit.StaffCreditPullRequest as used in backend/tests/usecase/test_japan_staff_credit.py

Property Type Description
consent_reference str Consent reference used to authorize the pull.
operator_id str Staff operator requesting the report.
requested_at datetime Timestamp of the pull request.
permissible_purpose `str \ None`
device_fingerprint `str \ None`

Staff Credit Pull Log

src.domain.japan_credit.StaffCreditPullLog as used in backend/tests/usecase/test_japan_staff_credit.py

Property Type Description
id `int \ None`
consent_id int Reference to the stored consent.
operator_id str Operator who initiated the pull.
requested_at datetime Timestamp of the request.
status str succeeded or failed in the visible flow.
bureau_reference `str \ None`
response_payload dict[str, object] Bureau response body stored in the log.
error_message `str \ None`
device_fingerprint `str \ None`

Bureau Credit Report

src.domain.japan_credit.BureauCreditReport as used in backend/tests/usecase/test_japan_staff_credit.py

Property Type Description
reference_id str Bureau request reference.
report dict[str, object] Full bureau report payload.
summary dict[str, object] Normalized summary returned to the caller.

KYC Gateway Contract

src.domain.kyc_gateway.KycGateway as used in backend/src/usecase/kyc.py and the KYC tests

Method Description
create_link_token_id_verification Returns the verification bootstrap payload used by the KYC frontend route.
get_identity_verification_status Returns the current verification status for a verification ID.

Feature Flows

Identity Verification Bootstrap

sequenceDiagram
  participant User as User
  participant Route as POST api kyc route
  participant Backend as Backend API
  participant UseCase as generate_link_token_id_verification
  participant Gateway as KycGateway

  User->>Route: Submit application id
  Route->>Route: Validate application id and auth token
  Route->>Backend: Load application data
  Backend-->>Route: Application payload
  Route->>Route: Build prefill payload
  Route->>Backend: POST create_link_token_id_verification
  Backend->>UseCase: generate_link_token_id_verification
  UseCase->>Gateway: create_link_token_id_verification
  Gateway-->>UseCase: link token and verification payload
  UseCase-->>Backend: verification payload
  Backend-->>Route: link token response
  Route-->>User: linkToken, verification, applicant

This flow is the primary verification bootstrap path. The frontend route validates the request, resolves the applicant, and forwards the prefill payload to the backend verifier.

Verification Status Lookup

sequenceDiagram
  participant User as User
  participant Route as GET api kyc verification route
  participant Backend as Backend API
  participant UseCase as kyc_get_identity_verification_status
  participant Gateway as KycGateway

  User->>Route: Request verification status
  Route->>Backend: GET identity_verification_status verification id
  Backend->>UseCase: kyc_get_identity_verification_status
  UseCase->>Gateway: get_identity_verification_status
  Gateway-->>UseCase: status payload
  UseCase-->>Backend: status payload
  Backend-->>Route: status payload
  Route-->>User: verification object

The route filters backend candidates, retries 404s across candidates, and returns the verification payload in a verification wrapper.

Staff-initiated Bureau Pull

sequenceDiagram
  participant Operator as Operator
  participant UseCase as perform_staff_credit_pull
  participant ConsentRepo as StaffCreditConsentRepository
  participant BureauClient as Bureau client
  participant LogRepo as StaffCreditPullLogRepository

  Operator->>UseCase: StaffCreditPullRequest
  UseCase->>ConsentRepo: get_by_reference
  ConsentRepo-->>UseCase: StaffCreditConsent
  UseCase->>UseCase: Validate expiry, revocation, operator access
  UseCase->>BureauClient: request_credit_report
  BureauClient-->>UseCase: BureauCreditReport
  UseCase->>LogRepo: create StaffCreditPullLog
  LogRepo-->>UseCase: persisted log
  UseCase-->>Operator: consent, log, summary, data_source, report

This flow is gated by consent state and operator authorization. If the bureau request fails, the log is still persisted and the use case raises BureauRequestError.

sequenceDiagram
  participant Operator as Operator
  participant UseCase as register_staff_credit_consent
  participant ConsentRepo as StaffCreditConsentRepository

  Operator->>UseCase: StaffCreditConsentRequest
  UseCase->>UseCase: Check expires_at is in the future
  UseCase->>ConsentRepo: create
  ConsentRepo-->>UseCase: StaffCreditConsent
  UseCase-->>Operator: persisted consent

Consent registration rejects expired records at creation time and normalizes the allowed operator list before persistence.

Error Handling

The feature uses explicit, domain-specific failure modes instead of silent fallthrough.

Area Error or Status Trigger Effect
KYC route 400 Invalid body or missing applicationId Request is rejected before any backend call.
KYC route 401 Missing auth token No application lookup occurs.
KYC route 404 Application cannot be found and no load error exists The caller receives “Application not found.”
KYC route 502 Backend load or verification bootstrap failure The route returns a backend error detail.
Verification route 400 Invalid verification ID The request is rejected immediately.
Verification route 404 No verification is found The caller receives “Verification not found.”
Verification route 502 Backend status lookup fails The error is surfaced as a proxy failure.
Consent registration ConsentExpiredError Expiry is in the past or now Consent is not persisted.
Staff pull ConsentNotFoundError Consent reference is absent Bureau access is blocked.
Staff pull ConsentRevokedError Stored consent is revoked Bureau access is blocked.
Staff pull ConsentExpiredError Stored consent is no longer active Bureau access is blocked.
Staff pull OperatorNotAllowedError Operator ID is not in the allowed set Bureau access is blocked.
Staff pull BureauRequestError Bureau client fails Pull log is persisted and the request fails closed.

Caching Strategy

The only explicit cache control in the visible flow is the identity status proxy, which fetches backend verification state with cache: "no-store". That makes every status request a fresh backend lookup rather than a cached response.

Method Cache Behavior Notes
GET /api/kyc/[verificationId] no-store Backend candidate fetches are retried without caching.
POST /api/kyc Not cached The route is a live POST that creates a new verification bootstrap request.
POST /create_link_token_id_verification Not cached The backend call is a live verification bootstrap request.
GET /identity_verification_status/{verification_id} Not cached by the frontend proxy The route is retrieved on demand for current status.
perform_staff_credit_pull N/A The use case persists a pull log and returns the bureau payload directly.

Integration Points

  • frontend/components/underwriting-compliance.tsx is the visible underwriting surface and uses EmailOverlay for the send action.
  • frontend/app/api/kyc/route.ts orchestrates applicant lookup, prefill construction, and verification bootstrap.
  • frontend/app/api/kyc/[verificationId]/route.ts proxies status lookups to the backend verifier.
  • backend/src/usecase/kyc.py delegates to KycGateway for verification link creation and status retrieval.
  • backend/src/usecase/japan_staff_credit.py enforces consent, operator access, and bureau request logging.
  • backend/src/ml/credit_pipeline_validation.py declares KYC and AML decline flags that stop underwriting before scoring.
  • documents/spinwheel-integration-plan.md describes the intended Equifax-based intake and compliance shape for a streamlined identity and credit workflow.
  • backend/tests/usecase/test_japan_staff_credit.py exercises the consent and operator rules that protect bureau access.

Testing Considerations

The visible tests cover the contract boundaries that matter most for this domain:

  • test_generate_link_token confirms generate_link_token_id_verification returns a link token.
  • test_get_verification_status confirms kyc_get_identity_verification_status returns a dictionary payload with status == "success".
  • test_register_staff_credit_consent_requires_future_expiry verifies that expired consent cannot be registered.
  • test_register_staff_credit_consent_rejects_past_expiry verifies the same policy from the registration path.
  • test_perform_staff_credit_pull_success confirms the bureau summary is returned and the pull log is written with status == "succeeded".
  • test_perform_staff_credit_pull_rejects_unregistered_operator verifies operator authorization enforcement.
  • test_perform_staff_credit_pull_rejects_expired_consent verifies the consent validity gate before bureau access.
  • TestKycGateway and MockKycGateway provide the gateway contract used by the use case tests.

Key Classes Reference

Class Responsibility
underwriting-compliance.tsx Renders the underwriting document preview, supports regeneration, and opens the email overlay.
route.ts Starts identity verification from the applicant ID and returns the link token response.
route.ts Proxies verification status lookups to the backend status endpoint.
kyc.py Passes KYC requests through to KycGateway for link token creation and status retrieval.
japan_staff_credit.py Enforces consent, operator permissions, and bureau logging for staff-initiated credit pulls.
test_japan_staff_credit.py Verifies the consent and operator rules that protect bureau access.
spinwheel-integration-plan.md Describes the planned Equifax-based intake and compliance requirements for streamlined identity verification.