Display policy: "Timeout duration" text field has no client-side format validation

[HummelsTech]

Summary

The Display settings step's "Timeout duration" field (screen_timeout in config_flow.py, DISPLAY_SCHEMA) is a free-text TextSelector with no format validation. Applying a policy with a malformed value fails with a raw googleapiclient.errors.HttpError traceback instead of a friendly form error.

Reproduction

1. Open the integration's options flow → Display settings.
2. Enter a value in "Timeout duration" that doesn't match Google's protobuf Duration string format (e.g. a bare 0 instead of 0s).
3. Apply the policy.

Result

googleapiclient.errors.HttpError: <HttpError 400 ...
"Invalid value at 'policy.display_settings.screen_timeout_settings.screen_timeout' ...
Illegal duration format; duration must end with 's'">

Traceback: config_flow.py async_step_apply_policy → api.py async_set_policy → _set_policy → googleapiclient http.execute().

Root cause

I traced the field end-to-end and confirmed there is no string transformation anywhere in the integration — async_step_display does self._options.update(user_input) verbatim, build_policy_from_options does timeout["screenTimeout"] = opts["screen_timeout"] verbatim, and api.py forwards the policy body unchanged to the Google Android Management API. So whatever string is typed into the field is sent to Google exactly as-is, with no local validation first. If the field doesn't end in s (or otherwise doesn't match Google's Duration string format), the failure only surfaces as an unhandled 400 from Google, logged via _LOGGER.exception("Failed to apply policy '%s'", policy_id) and surfaced to the user as a generic apply_failed form error — the underlying "must end with 's'" detail isn't shown in the UI at all.

The field's data_description hint text ("Duration string, e.g. 220s, 60s, 0s (never)") only appears as help text next to the field — it's not a placeholder/prefill, so it's easy to type a bare number by mistake and only find out via a stack trace in the HA log.

Suggested fix

Add a vol.Match (or equivalent) validator to the screen_timeout field in DISPLAY_SCHEMA, e.g.:

vol.Optional("screen_timeout", default="220s"): vol.All(_text(), vol.Match(r"^\d+(\.\d+)?s$")),

so a malformed duration is rejected locally with a clear form error instead of round-tripping to Google's API first.

Happy to send a PR for this if useful — just wanted to confirm the root cause here first.

[HummelsTech]

Update — reproduced this live, and the real root cause is different from what I originally wrote above.

I set screen_timeout to exactly 0s (as the field's own hint text suggests) and got a form error ("Failed to apply the policy. Check logs for details."). The actual traceback in Home Assistant's log:

File "custom_components/android_management_api/config_flow.py", line 1431, in async_step_apply_policy
  await coordinator.client.async_set_policy(self.hass, policy_id, policy)
File "custom_components/android_management_api/api.py", line 254, in async_set_policy
  ...
File "custom_components/android_management_api/api.py", line 264, in _set_policy
  return self._execute_request(...)
googleapiclient.errors.HttpError: <HttpError 400 when requesting https://androidmanagement.googleapis.com/v1/enterprises/.../policies/policy1?alt=json returned "displaySettings.screenTimeoutSettings.screenTimeout must be set to a duration greater than 0.". Details: "displaySettings.screenTimeoutSettings.screenTimeout must be set to a duration greater than 0.">

So this isn't just a missing-format-validation issue (my regex suggestion above doesn't actually fix it — 0s matches ^\d+(\.\d+)?s$ fine, Google just rejects the value outright). The Android Management API requires screenTimeout to be strictly greater than 0 — there's no "0 = never" value for this field.

That means the field's own hint text is incorrect:

"screen_timeout": "Duration string, e.g. 220s, 60s, 0s (never)"

0s is not a valid way to say "never" — Google's API flatly rejects it. As far as I can tell, the closest equivalent to "don't enforce a timeout" is setting screen_timeout_mode to SCREEN_TIMEOUT_USER_CHOICE instead of SCREEN_TIMEOUT_ENFORCED, and leaving screen_timeout unset/irrelevant in that mode — rather than trying to force screen_timeout itself to 0s.

Suggested fix, revised:

1. Drop the , 0s (never) part of the data_description hint for screen_timeout — it describes a value the API doesn't accept.
2. Add local validation rejecting 0s / non-positive durations for this field (still worth doing, e.g. vol.Match(r"^(?!0(\.0*)?s$)\d+(\.\d+)?s$") or a simpler positive-value check), so this fails fast in the form instead of round-tripping to Google's API with a generic "Check logs for details" error.
3. If "never enforce a timeout" is a use case worth supporting, document/point users to screen_timeout_mode: SCREEN_TIMEOUT_USER_CHOICE as the actual mechanism for that, rather than screen_timeout: 0s.

Happy to send a PR for the hint-text + validation fix if that's useful.

[sickkick]

Thanks for the follow-up repro — that revised root cause checks out against the Android Management API docs.

screenTimeout must be a Duration greater than 0 (so 0s is rejected), and for SCREEN_TIMEOUT_USER_CHOICE Google requires that screenTimeout is not set at all. The old 0s (never) hint was incorrect.

A fix is up in #42:

• Local validation for positive Duration values (Display options + set_kiosk_policy)
• Omit screenTimeout when mode is SCREEN_TIMEOUT_USER_CHOICE
• Remove the 0s (never) wording from UI strings / service docs / README
• Clearer form error instead of a generic apply failure

Happy to adjust further if anything still looks off after review.