Skip to content

[Spec] Post-v0.1.0 usability and automatic-lock improvements #137

Closed
Closed
[Spec] Post-v0.1.0 usability and automatic-lock improvements#137

Description

@miso-develop
miso-develop
opened on Sep 16, 2026

Context

Hands-on use of M5Authenticator v0.1.0 identified several Device and Web usability issues plus a new configurable automatic-lock requirement.

This Spec records the requested behavior and provides traceability to domain-specific implementation Tasks. It does not itself authorize cross-domain implementation.

Owner

  • ACTIVE_ROLE: specification
  • Implementation domains: device, web

Current status snapshot — 2026-09-19

Requirements

Device UI

  1. While OTP code is visible, a single click hides the code immediately.
  2. Add vertical margin above the OTP code.
  3. Add at least minimal line spacing throughout the Device UI so adjacent lines do not visually touch.
  4. Reduce or remove the on-screen click-operation legend if space is insufficient. If retained, prefer a compact form such as 1x next / 2x prev / hold OTP.
  5. Add character spacing to the OTP code, including approximately half-character additional separation between the first 3 digits and last 3 digits.
  6. Text that is horizontally clipped should begin horizontal scrolling after approximately 2 seconds so the full text can be read.

Automatic Lock

  1. Add an optional automatic LOCK based on a fixed maximum continuous UNLOCKED lifetime.
  2. Unset/disabled means no automatic maximum lifetime; this preserves existing v0.1.0 behavior.
  3. When enabled, configure the lifetime in whole days from 1 through 31 inclusive.
  4. The Web enable-time selector starts at 1 day when no prior enabled value exists, but 1 day is not persisted until the user explicitly enables/saves it.
  5. User activity, OTP use, account navigation, Web/USB activity, or trusted-time sync never resets or extends the lifetime.
  6. Automatic expiry uses the same security boundary as explicit Lock.
  7. Details of persistence, active-session updates, and compatibility are fixed by Decision [Decision] Define configurable automatic-lock semantics #138.

Web UI — localization/navigation baseline

  1. Add Japanese UI and allow the user to switch language.
  2. Add a usage/help page.
  3. Replace the current Flash-page link treatment with normal tab/navigation treatment consistent with the rest of the application.
  4. Normalize product branding to M5Authenticator without a space between 5 and A wherever the product name appears.
  5. Correct the Flash screen layout so its content is not visibly left-aligned compared with the rest of the application.

Web UI — follow-up shell/layout/build identification

  1. Increase the visual prominence/size of the top M5Authenticator title.
  2. The title itself is not a navigation link; navigation is owned by the tab controls.
  3. User-facing product-name casing is exactly M5Authenticator across the Web UI.
  4. Center the three top-level tabs as a group.
  5. Make the Firmware page primary content width consistent with Provisioning / Usage.
  6. Increase vertical spacing before Provisioning section headings so section boundaries are clear.
  7. Provisioning shows the deployed Web/Provisioning release baseline plus build identity.
  8. Firmware shows the actual Flash-target firmware release baseline plus firmware artifact build identity.
  9. Exact release builds are recognizable as vX.Y.Z; post-release builds retain the release baseline and add a short build-commit identifier, e.g. v0.1.0 + abc1234.
  10. Web and firmware build identities must remain independently sourced when their provenance differs; Firmware must not simply display the current Web commit.
  11. Version/build identity is injected/derived at build/package time and must not require runtime GitHub/network lookup solely for version rendering.

Device UI — TOTP validity / semantic status colors

  1. While OTP is revealed, show remaining validity for the current RFC 6238 30-second TOTP period. Prefer a compact circular progress/countdown indicator similar in concept to authenticator applications; a numeric seconds fallback is acceptable if the circle materially harms readability or causes flicker.
  2. The TOTP-validity indicator is distinct from the existing maximum 10-second reveal timeout; the reveal timeout remains unchanged.
  3. If the 30-second TOTP period rolls over while OTP is still revealed, refresh the visible OTP and validity indicator together without extending the original reveal deadline.
  4. State/Time status values use semantic colors while retaining readable text so color is never the only status signal.
  5. UNLOCKED / READY use green; LOCKED / UNPROVISIONED / NOT SYNCED use amber/yellow; REPROVISION / SECURITY ERROR / TIME STALE / TIME ERROR use red.
  6. Countdown/status-color rendering must preserve the readable 240x135 layout established by [Task][Device] Refine StickS3 OTP screen readability and interactions #139 and must not introduce whole-screen flicker or new secret persistence/logging.

Device UI — visual hierarchy follow-up

  1. Render the Device M5Authenticator product heading in a readable blue accent while preserving the current 240x135 information hierarchy.
  2. Make the physical-confirmation instruction equivalent to Press A to confirm visibly prominent using a high-contrast action accent distinct from the blue title and red/amber/green status semantics; explicit text remains required so color is never the sole cue.
  3. Preserve the existing production StickS3 audio-disable contract (internal_spk=false, internal_mic=false, explicit speaker end). [Defect] Production First Install candidate再Flash後にStickS3の可聴/高周波ノイズが再発 #92 already investigated intermittent noise with this mitigation active; do not make speculative audio/PMIC changes without a newly reproducible current-main defect.

Web UI — post-provisioning and layout-stability follow-up

  1. In normal already-provisioned management/import state, do not show an editable Recovery Passphrase field when the current operation cannot consume it. Passphrase input remains available where legitimately required for initial provisioning, recovery/new-Browser replacement, and explicit Passphrase change.
  2. The Firmware route establishes its final primary content container geometry on first render. Asynchronous firmware/build/device metadata resolution must not cause visible horizontal container/header/tab shift.
  3. Preserve [Task][Web] Refine application header/layout and expose release/build versions #146 build-provenance semantics but place Web build/commit and Firmware build/commit metadata after the primary operational content on their respective pages.
  4. Increase top separation before non-first Provisioning major section headings beyond the [Task][Web] Refine application header/layout and expose release/build versions #146 baseline; at normal desktop width use at least 2rem / 32px-equivalent separation while avoiding the same large leading margin on the first section.

Device UI / hardware — 2026-09-18 follow-up

  1. Render the Device product title on a black background with a brighter blue M5Authenticator text accent. The revised blue must be visibly brighter than the prior [Task][Device] Refine title and physical-confirmation visual emphasis #176 blue (RGB565 0x1c9f) while remaining clearly distinct from the cyan confirmation accent (0x07ff). Use 4 px title-top padding, 4 px title-bottom padding, and retain 1 px title-left padding, followed by the existing 1 px blank black spacing row; do not restore the rejected white title band.
  2. All left-aligned non-title Device UI content starts at x = 4 px. Centered content such as the six-digit OTP remains geometrically centered; account-label scrolling must respect the 4 px inset without creating new secret persistence.
  3. Preserve the existing StickS3 audio-disable contract (internal_spk=false, internal_mic=false, M5.Speaker.end()) and treat residual audible/high-frequency noise as evidence-gated. A faint intermittent/residual noise observation by itself is nonblocking when it is not accompanied by heat, reboot, display corruption/flicker, USB protocol instability, or visible power instability and no new audio/PMIC mitigation is proposed. Record the observation and track further characterization separately. If noise becomes sustained at normal handling distance and/or any stop-condition anomaly appears, or if additional speaker/PMIC mitigation is proposed, require causal amplifier-state/before-after evidence before changing firmware. Do not make speculative broad PMIC/power/USB changes.

Web UI — 2026-09-18 follow-up

  1. Present Web/Firmware build provenance at the bottom of each page as a dedicated, localized, visually secondary Build information / ビルド情報 semantic section inside the normal page shell, preserving independent Web-vs-Firmware provenance and stable responsive geometry.
  2. Every major Provisioning peer section below the page-level introduction has one visible horizontal divider immediately before its section heading. Reuse the shared section/panel boundary, avoid double rules, and preserve the danger-tinted Factory Reset boundary.

Web Usage / Help — diagram follow-up

  1. The Usage / Help page must use diagrams where they materially improve understanding of multi-step workflows, trust/storage relationships, or destructive/recovery distinctions. Diagrams supplement the prose; they do not replace the complete textual operating guide.
  2. At minimum, provide localized EN/JA diagrams for: (a) normal setup and daily Unlock/OTP flow, (b) the M5StickS3 / active Trusted Browser / Recovery Package relationship, and (c) the distinction among normal firmware Update, First install/erase, healthy Factory Reset, and Recovery Factory Reset.
  3. Help diagrams must remain local-only, responsive, accessible, and synthetic/generic. They must not include real credentials, QR payloads, Recovery Passphrases/Packages, key material, Device IDs, or runtime external diagram/image services. Color must not be the sole carrier of meaning.

Web lifecycle / automatic PC-time sync

  1. Closing/reloading the Web page, browser lifecycle termination, Web Serial transport teardown, or USB data disconnect must not implicitly Lock a still-running Device. Explicit Lock & Disconnect, Device automatic-lock expiry, reboot/actual power loss, and existing security boundaries remain the Lock mechanisms.
  2. The official Web app may automatically synchronize PC time after a normal Connect or successful Trusted Browser Unlock only when active Trusted Browser ownership and exact binding are valid, the Device is freshly confirmed UNLOCKED, and current time readiness is not_synced or stale. Automatic sync must be skipped when time is already ready.
  3. Automatic PC-time sync is best-effort: failure must not roll back a successful Connect/Unlock, implicitly Lock the Device, or trigger unbounded retries. Manual Sync PC time remains available, and PC time remains labeled as local-host asserted rather than cryptographically authenticated.

Web shell / divider follow-up

  1. Keep the shared Web header visible at the top of the viewport during vertical scrolling on Provisioner, Firmware Flash, and Help. The fixed/sticky header includes the product title, top-level tabs, and language switcher; responsive navigation, localization, keyboard access, overlay priority, and page geometry must remain correct.
  2. Within Provisioning's Security & Recovery panel, render exactly one visible subsection divider immediately above both Recovery Package and Change Recovery Passphrase, while preserving all recovery/passphrase security behavior and the existing major-section divider contract.
  3. On Firmware Flash, render exactly one visible divider before First install — erase device rather than the current duplicated boundary, while retaining one clear boundary before Update and preserving First install vs state-preserving Update semantics.
  4. Add visibly larger whitespace above the divider before Provisioning's Change Recovery Passphrase subsection. At normal desktop width use at least 40px-equivalent top separation, while preserving exactly one divider, existing divider-to-heading spacing, responsive EN/JA layout, and all Recovery/Passphrase security behavior.

Non-functional constraints

  • Existing secret-handling, Trusted Browser, Protocol v2, Vault, and LOCKED/UNLOCKED security invariants must not be weakened.
  • Device layout changes must remain usable on the M5StickS3 240x135 display.
  • Horizontal scrolling must not cause OTP, secret, or credential data to persist or leak beyond existing UI behavior.
  • TOTP countdown must use the same trusted time basis as TOTP generation and must not create a second independent time truth.
  • Automatic-lock enforcement must use monotonic runtime elapsed time rather than mutable wall-clock/NTP time.
  • Web localization/build display must not introduce runtime CDN/remote-resource/GitHub API dependencies.
  • Product/Firmware SemVer remains distinct from Protocol / Storage Schema / Vault Format versions per [Decision] Define licensing and versioning policy #24/[Spec] M5 Authenticator V1 #7.
  • Supported production browser remains latest stable Desktop Chrome unless separately changed by a Decision.
  • Recovery Passphrase presentation changes must never create persistence/prefill/logging of the Passphrase and must not suppress legitimate recovery/change flows.
  • Firmware-page layout stability should be achieved through stable container geometry/reserved async-content space rather than a viewport-specific hard-coded page width.
  • Existing speaker/microphone disable behavior must remain unchanged unless a separately evidenced Device defect justifies a new specification decision.

Acceptance

References

Child work

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions