[Proposal]: Expand Signals for Fraud Risk Assessment

[sw-tang]

Summary

Extend signals.json with 6 well-known signals that provide device environment and browser context to support fraud risk assessment. #630 proposes trust-level signals such as authentication, verification, and delegation. This proposal complements it by standardizing the device and browser environment signals that businesses need for fraud scoring — IP country, device timezone, screen dimensions, browser language, and Java support. Browser signals apply when the buyer interacts via a browser-based agent surface (e.g. Google AI Mode in Chrome); they will be absent in headless agent flows. Two signals in this proposal (dev.ucp.session_start_time, dev.ucp.device_type) overlap with the existing RFC and are included here for completeness.

Motivation

Businesses receiving checkout requests need device and browser environment data to run fraud scoring models. Today, signals.json provides dev.ucp.buyer_ip and dev.ucp.user_agent, which are insufficient for effective risk assessment.

In agent-originated commerce, the platform controls the buyer's session environment. The platform observes the buyer's IP country, device timezone, screen dimensions, and browser configuration — but has no standard keys to relay this context to businesses. Without these signals, businesses must either accept degraded fraud detection quality or fall back to proprietary signal exchanges with each platform individually.

The target beneficiaries are businesses performing fraud risk assessment at checkout time.

Goals

• Define well-known 6 signal keys for device and browser environment context
• Enable businesses to receive IP geolocation, device timezone, screen dimensions, browser language, and Java support status from platforms via a standardized vocabulary
• Maintain full backward compatibility — all new signals are optional
• Complement the existing agent-trust signals RFC with environment-level fraud context

Non-Goals

No response

Detailed Design

API Changes

No new API endpoints. This is an additive change to the signals object already present on catalog, cart, and checkout requests.

Data Structures

Add 6 properties to /schemas/common/types/signals.json:

Signal	Type	Description
dev.ucp.buyer_ip_country	string	IP Country
dev.ucp.device_time_zone	string	Current timezone of the device being used in session
dev.ucp.browser_screen_height	integer	Screen height
dev.ucp.browser_screen_width	integer	Screen width
dev.ucp.browser_language	string	Language being used in browser on the device
dev.ucp.browser_java_enabled	boolean	Java enabled

Additionally, two signals overlap with the existing RFC and are listed here for completeness:

Signal	Type	Description	RFC overlap
dev.ucp.session_start_time	string (date-time)	When the buyer's session began	Same signal in existing RFC
dev.ucp.device_type	string	Device category. Known values: mobile, desktop, tablet, smart_speaker, agent	Same signal in existing RFC; value set should be reconciled

Schema addition (new signals only):

{
  "dev.ucp.buyer_ip_country": {
    "type": "string",
    "description": "IP Country."
  },
  "dev.ucp.device_time_zone": {
    "type": "string",
    "description": "Current timezone of the device being used in session."
  },
  "dev.ucp.browser_screen_height": {
    "type": "integer",
    "description": "Screen height."
  },
  "dev.ucp.browser_screen_width": {
    "type": "integer",
    "description": "Screen width."
  },
  "dev.ucp.browser_language": {
    "type": "string",
    "description": "Language being used in browser on the device."
  },
  "dev.ucp.browser_java_enabled": {
    "type": "boolean",
    "description": "Java enabled."
  }
}

Behavioral Changes

No behavioral changes to the protocol. All new signals are optional. The signals object itself remains optional on requests. Platforms that do not provide these signals incur no errors. Businesses that do not consume them are unaffected.

Risks and Mitigations

Security: These signals expose device environment metadata, not device-leaked identifiers (no fingerprint hashes, no device IDs). buyer_ip_country is derived from an IP already available via buyer_ip — it adds convenience, not new data exposure. Screen dimensions and browser language are low-sensitivity environment facts. Mitigation: All values are observed by the platform, not supplied by the buyer.

Backward Compatibility: Fully backward compatible. The signals schema already specifies additionalProperties: true. Existing implementations that only consume dev.ucp.buyer_ip and dev.ucp.user_agent continue unchanged. No migration required.

Complexity: Low. Six flat key-value signals with primitive types (string, integer, boolean). No nested objects, no cross-referencing with other schema elements, no new behavioral requirements on platforms or businesses.

Test Plan

• Schema validation: type checking for each new signal
• Backward compatibility: requests without the new signals continue to validate
• Extensibility: unknown signal keys remain accepted (additionalProperties: true preserved)

Graduation Criteria

Working Draft → Candidate:

• Schema merged and documented (with Working Draft disclaimer).
• Unit and integration tests are passing.
• Initial documentation is written.
• TC majority vote to advance.

Candidate → Stable:

• Adoption feedback has been collected and addressed.
• Full documentation and migration guides are published.
• TC majority vote to advance.

Implementation History

• [YYYY-MM-DD]: Proposal submitted.
• [YYYY-MM-DD]: TC approved "Provisional"; capability enters "Working Draft".
• [YYYY-MM-DD]: TC approved advancement to "Candidate".
• [YYYY-MM-DD]: TC approved "Implemented"; capability enters "Stable".

Code of Conduct

• I agree to follow this project's Code of Conduct