[Task][Device] Add TOTP validity countdown and semantic status colors

[miso-develop]

Parent spec

#137

Owner

• ACTIVE_ROLE: implementation
• DOMAIN: device

State

READY_FOR_IMPLEMENTATION

Dependency / collision boundary — re-evaluated 2026-09-17

The original blocker on #139 / PR #143 is resolved.

Current baseline at this re-evaluation:

• main: 5a0242d7723e5d264edc7544eb1398cd661cf7f5
• [Task][Device] Refine StickS3 OTP screen readability and interactions #139 / PR feat(device): refine StickS3 OTP UI interactions (#139) #143: INTEGRATED; Device UI/readability baseline is in main and its physical Human Gate passed 16/16.
• [Task][Device] Implement configurable automatic LOCK policy #140 / PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152: INTEGRATED; automatic-LOCK/Vault Format 2 Device implementation is in main at the current head.
• Open PRs in this repository: none.
• No [Task][Device] Add TOTP validity countdown and semantic status colors #148 implementation branch exists.
• No active overlapping Device-UI implementation claim was found. Remaining historical Device-named branches are associated with already-closed earlier work and do not own this scope.

Implementation ownership for this Task is the StickS3 Device UI/countdown/status-color surface defined below. Start from the current main at implementation bootstrap and re-run the normal Issue/PR/branch collision check before mutation.

Known integrated-file considerations:

• [Task][Device] Refine StickS3 OTP screen readability and interactions #139 already established the current firmware/components/m5auth_device_sticks3/... UI/layout/scroll baseline and related UI tests; [Task][Device] Add TOTP validity countdown and semantic status colors #148 extends that integrated baseline rather than reopening [Task][Device] Refine StickS3 OTP screen readability and interactions #139.
• [Task][Device] Implement configurable automatic LOCK policy #140/feat(device): add configurable automatic lock and Vault Format 2 (#140) #152 touched automatic-LOCK/Vault/runtime behavior and tests/sticks3_runtime_contract_test.py; [Task][Device] Add TOTP validity countdown and semantic status colors #148 may extend shared tests where necessary but must preserve the integrated automatic-LOCK contract and must not change its semantics.

There is no remaining dependency blocker at this handoff.

Objective

Improve the M5StickS3 OTP screen and status readability by showing the remaining validity of the currently displayed TOTP and by applying semantic text colors to Device State and Time values.

Scope

1. TOTP validity countdown

While an OTP is revealed, show how much validity remains in the current RFC 6238 30-second TOTP period.

Preferred presentation:

• a compact circular countdown/progress animation similar in concept to common authenticator apps;
• optionally include remaining seconds when legible on the 240x135 display.

Fallback:

• if a circular indicator cannot be rendered without materially reducing OTP readability or causing flicker, a clear numeric remaining-seconds indicator is acceptable.

The countdown represents TOTP validity, not the existing 10-second reveal timeout.

2. TOTP rollover while revealed

The UI must never present a countdown for a new TOTP period while leaving the old OTP code visible.

If the 30-second TOTP boundary is crossed while reveal remains active:

• regenerate the selected credential's TOTP for the new period;
• replace the displayed OTP atomically with the new code;
• reset the validity indicator for the new 30-second period;
• do not extend the original 10-second reveal deadline.

If trusted time becomes non-ready or generation fails, follow the existing fail-closed reveal behavior rather than showing a stale OTP.

3. Semantic colors for State / Time

Color only the status value (or an equivalently clear status region); retain the State: / Time: labels and textual value so color is never the sole carrier of meaning.

State color mapping

• UNLOCKED -> green
• LOCKED -> amber/yellow (normal but not currently usable for OTP)
• UNPROVISIONED -> amber/yellow (setup required)
• REPROVISION -> red
• SECURITY ERROR / unknown error -> red

Time color mapping

• READY -> green
• NOT SYNCED -> amber/yellow
• TIME STALE -> red
• TIME ERROR / unknown error -> red

Use display-native RGB565 or equivalent constants with enough contrast against the current black background. Exact hue may be adjusted for M5StickS3 readability, but semantic categories above must remain stable.

Acceptance criteria

• OTP reveal still has the existing maximum 10-second visibility window.
• While OTP is visible, the UI presents remaining validity for the current 30-second TOTP period.
• Preferred implementation uses a compact circular countdown/progress indicator if physical readability/performance permit; otherwise a numeric seconds fallback is clearly implemented and documented.
• The indicator progresses smoothly enough to be understandable without introducing whole-screen flicker.
• Countdown rendering does not reduce the six-digit OTP below the readable size/layout established by [Task][Device] Refine StickS3 OTP screen readability and interactions #139.
• Countdown is derived from trusted TOTP time/period semantics, not from the 10-second reveal timer.
• Crossing a 30-second TOTP boundary during an active reveal refreshes the OTP and countdown together.
• TOTP rollover does not reset/extend the original reveal deadline.
• If trusted time becomes NOT SYNCED / TIME STALE or generation otherwise becomes unavailable, stale OTP is not retained on screen.
• State and Time textual values remain visible and readable; color supplements rather than replaces text.
• UNLOCKED and READY are visually green.
• expected-but-not-ready states (LOCKED, UNPROVISIONED, NOT SYNCED) use amber/yellow rather than being presented as fatal errors.
• REPROVISION, SECURITY ERROR, TIME STALE, and TIME ERROR are visually red.
• Presence / unlock-request and other existing Device UI modes remain readable and retain their current security semantics.
• No OTP value, secret, credential label, or additional secret-bearing state is logged or persisted for the animation.
• Firmware/UI model/runtime contract tests cover countdown/rollover behavior and color-category mapping where practical.
• Physical M5StickS3 validation confirms readable colors, no unacceptable flicker, and no OTP readability regression.

Security / timing constraints

• Existing trusted-time gating remains authoritative.
• The visual indicator must be computed from the same trusted time basis used for TOTP generation; do not introduce a second independent wall-clock truth.
• OTP rollover must use existing bounded/transient generation paths and zeroization expectations.
• Preserve the integrated [Task][Device] Implement configurable automatic LOCK policy #140 automatic-LOCK behavior and its explicit-Lock security boundary.
• No change to Protocol v2, Vault format, credential export boundary, Trusted Browser behavior, or automatic LOCK semantics.

Out of scope

• Changing the RFC 6238 period from 30 seconds.
• Extending OTP reveal beyond the existing 10 seconds.
• Web UI countdown/status colors.
• Changing the meanings of Device runtime/time states.
• Reworking [Task][Device] Refine StickS3 OTP screen readability and interactions #139 UI requirements already integrated in PR feat(device): refine StickS3 OTP UI interactions (#139) #143.
• Reworking [Task][Device] Implement configurable automatic LOCK policy #140 automatic-LOCK/Vault Format 2 behavior already integrated in PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152.

References

• [Spec] Post-v0.1.0 usability and automatic-lock improvements #137 parent usability Spec
• [Task][Device] Refine StickS3 OTP screen readability and interactions #139 / PR feat(device): refine StickS3 OTP UI interactions (#139) #143 integrated Device UI baseline
• [Task][Device] Implement configurable automatic LOCK policy #140 / PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152 integrated automatic-LOCK Device baseline
• [Task] Implement trusted time synchronization and TOTP core #10 trusted time / TOTP core
• [Task] Implement StickS3 account selection and 10-second OTP reveal UI #11 StickS3 OTP UI baseline
• [Human Task] V1正式Release前のM5StickS3実機E2E確認 #75 Human E2E validation
• docs/V1_REQUIREMENTS.md
• SECURITY.md

[miso-develop]

HANDOFF

FROM: specification
TO: implementation
DOMAIN: device
ISSUE: #148
STATE: BLOCKED_DEPENDENCY
BLOCKING: #139 / PR #143 integration

Finding

The requested TOTP-validity indicator and State/Time semantic colors belong to the same StickS3 runtime UI currently being changed by #139 / PR #143.

Required action

Do not extend or rework PR #143 for this scope. After #139 is integrated, bootstrap from current main, re-check ownership/collision state (including #140), then implement #148 against the integrated Device UI baseline.

Completion condition

#139/PR #143 is integrated and no conflicting Device ownership exists; then #148 may move to READY_FOR_IMPLEMENTATION. Implementation must preserve the existing 10-second reveal ceiling and trusted-time/security boundaries.

[miso-develop]

HANDOFF

FROM: specification
TO: implementation
DOMAIN: device
ISSUE: #148
STATE: READY_FOR_IMPLEMENTATION
BLOCKING: no

Finding

The prior dependency on #139 / PR #143 is resolved: #139 is completed and PR #143 is integrated with the 16/16 physical Human Gate passed. Device automatic LOCK #140 / PR #152 is also integrated; its merge 5a0242d7723e5d264edc7544eb1398cd661cf7f5 is the current main head at this handoff.

Current collision re-check found no open PRs, no #148 implementation branch, and no active overlapping Device-UI implementation claim. Historical residual Device-named branches correspond to already-closed earlier work and are not current ownership claims for this scope.

Ownership / file boundary

#148 owns only the StickS3 TOTP-validity countdown/rollover presentation and State/Time semantic-color behavior specified in this Issue. Implement against the integrated #139 Device-UI baseline. Preserve the integrated #140 automatic-LOCK/Vault/runtime contract; shared regression files such as tests/sticks3_runtime_contract_test.py may be extended as necessary but existing #139/#140 contracts must remain green.

Required action

Bootstrap from the then-current main, re-run the standard Issue/PR/branch collision check, and implement #148 only. Preserve the existing 10-second reveal ceiling, trusted-time authority, secret zeroization/logging boundaries, Protocol/Vault/Trusted-Browser behavior, and automatic-LOCK semantics.

Completion condition

Acceptance Criteria and relevant firmware/UI/runtime/security checks pass, then hand off to Review. Physical M5StickS3 readability/flicker validation remains an explicit Human Gate before final integration where required. Implementation must not self-merge.

[miso-develop]

IMPLEMENTATION CLAIM

ACTIVE_ROLE: implementation
DOMAIN: device
ISSUE: #148
BASE: 5a0242d7723e5d264edc7544eb1398cd661cf7f5
BRANCH: task/148-device-totp-countdown-colors
STATE: ACTIVE_CLAIMED

Bootstrap/collision check is clear: #139/#143 and #140/#152 are integrated, no open PR exists, and no active overlapping Device-UI branch/claim was found. Implementation will preserve Issue #148 Acceptance Criteria and existing trusted-time / secret / Vault / Protocol / automatic-LOCK boundaries. Physical M5StickS3 readability/flicker/color validation remains an explicit Human Gate.

[miso-develop]

Implementation evidence

Implementation for #148 is complete at exact PR head e1194abe15c2fa0f1a4f3f1cc70e9a41c500a1b3 on PR #166.

Implemented behavior

• TOTP validity is derived from the RFC6238 30-second trusted-time period (30..1 seconds remaining), independently from the existing 10-second reveal deadline.
• The generator returns only the non-secret trusted Unix-second sample actually used for generation, allowing UI period metadata to stay bound to the visible OTP without changing trusted-time, Vault, VMK, or Protocol boundaries.
• If the period rolls while OTP remains revealed, the Device regenerates the OTP and validity metadata together. This path does not write or extend reveal_deadline_ms_.
• If trusted time becomes unavailable/stale, or rollover regeneration cannot produce a code for the current period, the visible OTP is cleared fail-closed.
• Countdown ticks redraw only the validity band; rollover redraws only the validity + OTP bands. Existing [Task][Device] Refine StickS3 OTP screen readability and interactions #139 six-digit size/spacing and label-scroll low-flicker behavior are preserved.
• State/Time text remains visible and authoritative. Only the value text is colored: green for UNLOCKED/READY, yellow for LOCKED/UNPROVISIONED/NOT SYNCED, red for REPROVISION/SECURITY ERROR/TIME STALE/TIME ERROR.
• The allowed numeric validity fallback (Valid: Ns) is used instead of a circular indicator to preserve the established 240x135 OTP layout and avoid reducing the size-4 six-digit OTP.

Verification at exact head

• Foundation #757: SUCCESS, including RFC6238 period tests, existing [Task][Device] Refine StickS3 OTP screen readability and interactions #139 StickS3 runtime/display contracts, Vault/runtime/re-key/Protocol contracts, ESP-IDF 5.5.5 build, merged-image package validation, dependency lockfile check, and Web/Chrome regressions.
• Security #760: SUCCESS, including repository security scan, automatic-LOCK Protocol-v2 contract, and screen-snapshot production boundary.
• Issue 117 Screen Snapshot fix(web): decode dense Google Authenticator migration QR images #131: SUCCESS, including sanitized snapshot contract and diagnostics-enabled ESP-IDF 5.5.5 build.

Human Gate

HUMAN_GATE_REQUIRED remains pending and is not self-certified by Implementation. Physical M5StickS3 verification is still required for:

1. six-digit OTP readability with the validity indicator;
2. countdown / period-rollover flicker behavior;
3. green/yellow/red State/Time readability and contrast.

No merge was performed.

[miso-develop]

HANDOFF
FROM: implementation
TO: review
DOMAIN: device
ISSUE: #148
PR: #166
HEAD: e1194ab
STATE: READY_FOR_REVIEW

[miso-develop]

HANDOFF
FROM: review
TO: implementation
DOMAIN: device
ISSUE: #148
PR: #166
HEAD: e1194ab
STATE: REWORK_REQUIRED

[miso-develop]

HANDOFF
FROM: review
TO: integration
DOMAIN: device
ISSUE: #148
PR: #166
HEAD: 7d21bfd
STATE: HUMAN_GATE_REQUIRED