Skip to content

STF-1906: Add phone verification inputs to minFraud #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oschwald wants to merge 5 commits into
base: main
Choose a base branch
from
+74 −0
Open

STF-1906: Add phone verification inputs to minFraud #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
25b86c5
Add phone verification inputs to minFraud
oschwald Oct 9, 2026
4cf5879
Use the dev docs wording for phone verification inputs
oschwald Oct 19, 2026
f662b29
Require the RFC 3339 form that the web service accepts
oschwald Oct 19, 2026
30399f3
Use the same shipping verification time as the dev docs
oschwald Oct 19, 2026
5f17866
Mark the bundled specs as generated
oschwald Oct 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
bundled/** linguist-generated=true
27 changes: 27 additions & 0 deletions bundled/minfraud.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

40 changes: 40 additions & 0 deletions components/minfraud-request.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ schemas:
time:
type: string
format: date-time
pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$"
description: >-
The time the event occurred, in RFC 3339 format. If you omit this
field, MaxMind uses the time it receives the request. MaxMind does not
Expand Down Expand Up @@ -246,6 +247,45 @@ schemas:
description: >-
The phone number, without the country code. MaxMind strips punctuation
characters. After that, the number must contain only digits.
phone_verification_method:

@horgh horgh Oct 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The real target is specs/minfraud.yaml (info.version: 0.1.0) and CHANGELOG.md, which are not in the diff.

This PR adds three request fields but does not change info.version or add a changelog entry. The README says that info.version follows SemVer and tracks changes to the spec. No tag or release exists yet, so this is fine if 0.1.0 is still unreleased. But mm_website already uses a pseudo-version of this module, so two different minFraud documents will both say 0.1.0. Is the plan to bump to 0.2.0 (with a changelog entry) at the first release, or now?

🤖 Comment by Claude Opus 5.5.

@oschwald oschwald Oct 19, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will leave info.version at 0.1.0. Nothing is tagged or released yet, so the first release sets the version and adds the changelog entry.

Reply by Claude Opus 5.5 on Greg's behalf.

type: string
enum:
- network
- delivered_code
- other
description: >-
The method used for the most recent verification attempt of the phone
number. Do not include this field if no verification was attempted.


- `network`: carrier or SIM-based silent network authentication. No
code is sent to the device.

- `delivered_code`: a one-time code delivered to the phone number by
SMS, an automated voice call, or an over-the-top messaging channel
such as WhatsApp or RCS, and entered by the user.

- `other`: a method not listed above, such as flash or missed call
verification, or a method you do not know because a third party
performed the check.
phone_verification_time:
type: string
format: date-time

@horgh horgh Oct 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

format: date-time accepts some timestamps that the server rejects. JSON Schema follows RFC 3339, which allows a lowercase t and z and a leap second (:60). The server parses with time.Parse(time.RFC3339, ...), which rejects all of these:

2026-10-01t14:30:00z  -> cannot parse "t14:30:00z" as "T"
2026-10-01T14:30:00z  -> cannot parse "z" as "Z07:00"
2016-12-31T23:59:60Z  -> second out of range

The server then returns INPUT_INVALID and drops the field. A client that validates against this spec does not see the problem until it reads the warning. The Python client PR for the same change uses an uppercase-only pattern, so the spec and that client disagree.

Suggestion: add a pattern that requires an uppercase T and Z, or say in the description that the server requires them and rejects leap seconds. The existing time input has the same gap, so a shared pattern for both fields can fix it in one place.

🤖 Comment by Claude Opus 5.5.

@oschwald oschwald Oct 19, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in f662b29. Both phone_verification_time and the event time now have a pattern that allows only an uppercase T and Z, seconds 00 to 59, and offsets up to 23:59.

Reply by Claude Opus 5.5 on Greg's behalf.

pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$"
description: >-
The most recent date and time a verification of the phone number was
attempted, if known, in RFC 3339 date-time format. The time must not
be before 1970-01-01T00:00:00Z or more than two days in the future.
For a time outside this range, MaxMind ignores the input and returns a
warning.
phone_was_verification_successful:
type: boolean
description: >-
Whether the most recent verification that the end user controls this
phone number was successful, using the method named in
`phone_verification_method`. `true` if the phone verification was
successful, or `false` if the user failed phone verification. Do not
include this field if you have not performed this check.
postal:
type: string
maxLength: 255
Expand Down
6 changes: 6 additions & 0 deletions examples/minfraud/request.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ value:
last_name: Doe
phone_country_code: "1"
phone_number: 203-000-0000
phone_verification_method: delivered_code
phone_verification_time: "2026-10-01T14:30:00Z"
phone_was_verification_successful: true
postal: "06511"
region: CT
credit_card:
Expand Down Expand Up @@ -70,6 +73,9 @@ value:
last_name: Doe
phone_country_code: "1"
phone_number: 203-000-0000
phone_verification_method: delivered_code
phone_verification_time: "2026-10-01T14:30:00Z"
phone_was_verification_successful: true
postal: "06515"
region: CT
shopping_cart:
Expand Down
Loading