SMS-Receive/openspec/changes/build-sms-code-receiver-app/specs/sms-code-capture/spec.md

ADDED Requirements

Requirement: Receive new SMS messages through the system broadcast path

The app SHALL use Android's new SMS received broadcast path as the primary mechanism for capturing verification SMS messages on the user's own device.

Scenario: SMS broadcast is received with permission granted

• WHEN the app has RECEIVE_SMS permission and the device receives a text SMS
• THEN the app MUST process Telephony.Sms.Intents.SMS_RECEIVED_ACTION and extract message objects from the received intent

Scenario: SMS broadcast is unavailable because permission is missing

• WHEN the app does not have RECEIVE_SMS permission
• THEN the app MUST report that the primary SMS capture path is blocked by missing permission

Requirement: Parse complete SMS message bodies

The app SHALL parse SMS bodies using Android SMS message APIs rather than ad hoc PDU handling in business logic.

Scenario: Multi-part SMS is received

• WHEN the received intent contains multiple SMS message segments
• THEN the app MUST combine the message bodies in received order before verification code extraction

Scenario: Sender and timestamp are available

• WHEN Android exposes sender address or timestamp for the SMS message
• THEN the app MUST attach those values to the capture result for diagnostics and display

Requirement: Extract verification code candidates

The app SHALL extract verification code candidates from SMS bodies with a conservative parser optimized for common Chinese and English verification messages.

Scenario: Chinese verification keyword is present

• WHEN the SMS body contains a keyword such as 验证码、校验码 or 动态码 near a 4-8 character code
• THEN the app MUST extract the nearby code as the preferred verification code candidate

Scenario: English verification keyword is present

• WHEN the SMS body contains a keyword such as code, verification or OTP near a 4-8 character code
• THEN the app MUST extract the nearby code as the preferred verification code candidate

Scenario: Code contains spaces or hyphens

• WHEN the SMS body contains a verification code formatted with spaces or hyphens
• THEN the app MUST normalize the code before displaying it

Scenario: No reliable code candidate exists

• WHEN the SMS body does not contain a reliable verification code candidate
• THEN the app MUST return a structured parse failure instead of displaying a guessed code

Requirement: Support optional Google SMS verification APIs

The app SHALL support Google SMS verification APIs only as optional paths and MUST NOT depend on them for the primary capture behavior.

Scenario: SMS User Consent path is available

• WHEN Google Play services supports SMS User Consent and the user authorizes reading a single SMS
• THEN the app MUST parse that SMS body through the same verification code parser used by the primary path

Scenario: SMS Retriever path is used with app hash

• WHEN a controlled test SMS includes the app hash required by SMS Retriever
• THEN the app MUST accept the retrieved message and parse the verification code

Scenario: Google SMS API is unavailable

• WHEN Google Play services is missing, disabled, incompatible, times out, or the user declines consent
• THEN the app MUST keep the system SMS broadcast path usable and report the optional path failure separately