[Task][Web] Add automatic LOCK timeout setting

[miso-develop]

Parent spec

#137

Decision dependency

• [Decision] Define configurable automatic-lock semantics #138 — RESOLVED, including 2026-09-17 Vault Format 2 compatibility/migration amendment.

Owner

• ACTIVE_ROLE: implementation
• DOMAIN: web

State

INTEGRATED

Objective

Add the Web-side configuration surface for the automatic LOCK policy defined by #138 and implement the Web-canonical Vault Format 1 -> Format 2 migration/synchronization contract required for that setting.

Final functional contract from #138

• Feature is optional.
• Unset/absent = disabled = unlimited continuous UNLOCKED lifetime.
• Enabled value is an integer number of days from 1 through 31.
• No hour/minute settings.
• When enabling with no prior enabled value, the UI selector starts at 1 day.
• 1 day is not the global default: until explicitly enabled/saved, effective behavior remains disabled/unlimited.
• Active-session changes apply against the original UNLOCKED start time; they do not start a fresh lifetime.

Vault compatibility / migration contract

• Continue to read/decrypt canonical Vault Format 1 and new Vault Format 2.
• Format-1 decode maps auto_lock_days to unset/disabled.
• New canonical generations created by a Format-2-capable Web mutation use Vault Format 2.
• Format 2 layout/AAD is exactly defined by [Decision] Define configurable automatic-lock semantics #138.
• Before migrating/sending Format 2, Device hello must explicitly advertise supported_vault_formats containing 2.
• Absence of that capability is treated conservatively as no proven Format-2 write support; do not send Format 2 to shipped v0.1.0 firmware.
• Format-1 -> Format-2 migration preserves vault_id and VMK, increments generation as an ordinary canonical mutation, uses a fresh random nonce, and uses the existing browser transaction journal / exact Device reconciliation path.
• Reconciliation must compare Vault format in addition to vault_id and generation.
• Once canonical state is Format 2, ordinary Format-2 -> Format-1 downgrade is not offered or generated.
• Recovery Package version remains 1; new Web accepts packages carrying Vault Format 1 or 2 and exports Format-2 canonical state with explicit vaultFormatVersion = 2.
• A Format-1 Recovery Package maps auto-lock to disabled until a Format-2 canonical mutation occurs.
• VMK wrap version remains 1; Vault-format migration alone does not require Passphrase entry, VMK rotation, or new physical confirmation.

Scope

• Add an enable/disable control for automatic LOCK under the appropriate Settings surface.
• When disabled/unset, clearly communicate that no automatic maximum UNLOCKED lifetime is configured.
• When enabled, allow selection of whole days 1..31 inclusive.
• If enabling with no previously stored valid value, initialize the selector to 1 day.
• Validate before attempting a canonical update.
• Extend logical Vault model/codec/crypto support to read Format 1 and Format 2 and write Format 2 per [Decision] Define configurable automatic-lock semantics #138.
• Implement capability-gated V1 -> V2 canonical migration inside the existing authenticated generation transaction.
• Persist/synchronize the optional setting through the authenticated encrypted canonical Vault generation/update path; do not add a separate settings side channel.
• Keep browser canonical / Recovery Package Vault-format metadata consistent with the active envelope.
• Show the currently effective configured state/value without exposing secret material.

Acceptance criteria

• Existing v0.1.0 Browser canonical/Recovery Format-1 state can be read without destructive migration and maps to disabled/unlimited.
• Existing v0.1.0 Device that does not advertise Format 2 is never sent a Format-2 candidate.
• New Device firmware advertising [1,2] can receive a Web-created Format-2 canonical generation.
• Format-1 -> Format-2 migration uses same VMK/vault_id, generation+1, fresh nonce, and existing transaction journal/reconciliation semantics.
• Pending/reconciled exact identity includes Vault format; format mismatch is not reported as successful exact reconciliation.
• New canonical writes after migration remain Format 2; Web does not ordinary-downgrade to Format 1.
• Recovery Package v1 import supports Vault Format 1 and 2; unknown newer formats fail closed.
• Recovery Package export for current Format-2 state identifies Vault Format 2 consistently.
• Newly provisioned state is disabled/unlimited until explicitly enabled/saved.
• Enabling an unset option presents 1 day initially.
• Only integer values 1..31 can be saved while enabled.
• No hour/minute configuration is offered.
• Disabling persists absence/null semantics in Format 2 rather than an invalid numeric sentinel.
• Saving uses the existing authenticated/canonical generation update path rather than an ad-hoc side channel.
• Successful save is reflected in Web and Device state according to [Decision] Define configurable automatic-lock semantics #138.
• If a shorter limit applied to the current session is already expired, UI correctly handles the Device immediately transitioning to LOCKED after successful application.
• Failed/ambiguous writes do not falsely report success, prematurely change the canonical setting, or silently diverge from Device state.
• Disabled mode, 1-day, 31-day, invalid values, enable/disable, reconnect, refresh, Format-1 migration, Device capability absence, Recovery Package F1/F2, and reconciliation are covered by tests.
• Japanese/English localization introduced by [Task][Web] Add Japanese localization, usage guide, and navigation/layout refinements #142 covers this setting and its explanatory text.
• No plaintext TOTP secret, Passphrase, VMK, session key, Recovery Package, or other key material is added to browser persistence/logging.

Security constraints

• Preserve active Trusted Browser ownership, generation conflict handling, browser journal, exact reconciliation, and transactional canonical update semantics.
• Do not weaken physical-confirmation or unlock requirements.
• No runtime remote dependencies or analytics.
• Do not represent disabled mode using a numeric value such as 0.
• Do not persist auto_lock_days outside the authenticated encrypted Vault.
• Do not claim v0.1.0 Web/firmware rollback compatibility after canonical state has migrated to Vault Format 2; older clients must fail closed.

Out of scope

• Device timer/runtime implementation ([Task][Device] Implement configurable automatic LOCK policy #140).
• Changing semantics or Vault-format contract fixed by [Decision] Define configurable automatic-lock semantics #138.

References

• [Spec] Post-v0.1.0 usability and automatic-lock improvements #137
• [Decision] Define configurable automatic-lock semantics #138 compatibility/versioning amendment
• [Task][Device] Implement configurable automatic LOCK policy #140 Device counterpart
• [Task][Web] Add Japanese localization, usage guide, and navigation/layout refinements #142
• [Spec] M5 Authenticator V1 #7
• [Decision] Adopt RAM-only vault key with Trusted Browser quick unlock #40, [Decision] Define Vault ciphertext granularity and metadata privacy boundary #45-[Decision] Define fresh unlock-session cryptography and user-presence scope #48
• SECURITY.md
• docs/SECRET_VAULT.md
• docs/STORAGE.md
• docs/PROVISIONING_PROTOCOL.md
• docs/ARCHITECTURE.md

[miso-develop]

HANDOFF

FROM: specification
TO: implementation
DOMAIN: web
ISSUE: #141
STATE: BLOCKED_DEPENDENCY
BLOCKING: yes

Finding

Web automatic-LOCK configuration depends on unresolved policy/representation semantics in #138.

Required action

Do not implement #141 until #138 is resolved. After resolution, implement the selected values/default/off behavior and canonical synchronization contract.

Completion condition

#138 is resolved, then this Task may move to READY_FOR_IMPLEMENTATION.

[miso-develop]

HANDOFF

FROM: specification
TO: implementation
DOMAIN: web
ISSUE: #141
STATE: READY_FOR_IMPLEMENTATION
BLOCKING: no

Decision resolved

#138 is closed/completed. Unset/disabled means unlimited, enabled values are whole days 1..31, and enabling an unset option starts the selector at 1 day.

Required action

Implement #141 exactly as updated using the authenticated canonical Vault generation/update path. Do not silently persist 1 day until the user explicitly enables/saves the option.

Completion condition

Acceptance Criteria and relevant Web/security/foundation tests pass, then hand off to Review.

[miso-develop]

SPECIFICATION UPDATE

FROM: specification
TO: implementation
DOMAIN: web
ISSUE: #141
STATE: READY_FOR_IMPLEMENTATION

Decision #138 now includes the 2026-09-17 Vault Format 2 compatibility amendment. The Web Task body has been updated accordingly.

Web must capability-gate F1->F2 migration using Device supported_vault_formats, preserve the existing canonical transaction journal/reconciliation semantics, support Recovery Package v1 carrying Vault Format 1 or 2, and never send Format 2 to a Device that has not explicitly advertised Format-2 support.

[miso-develop]

CLAIM

ACTIVE_ROLE: implementation
DOMAIN: web
ISSUE: #141
BRANCH: task/141
BASE: d99d4824990b6ebd7ddb670ee31aed4aeb4fc3f8
STATE: ACTIVE_CLAIMED

/resume selected #141 as the next actionable durable handoff for the current implementation / web role.

Preflight:

• [Task][Web] Add automatic LOCK timeout setting #141 is READY_FOR_IMPLEMENTATION including the latest Vault Format 2 compatibility amendment from [Decision] Define configurable automatic-lock semantics #138
• no open PR currently exists in the repository
• no task/141 branch existed before this claim
• no active Web implementation overlap was found
• [Task][Device] Implement configurable automatic LOCK policy #140 is Device-domain counterpart and remains outside this Web implementation scope

Implementing #141 only. Review/merge remain outside the Implementation role.

[miso-develop]

HANDOFF

FROM: implementation
TO: review
DOMAIN: web
ISSUE: #141
PR: #150
STATE: READY_FOR_REVIEW
BLOCKING: no

Implementation complete

Web automatic-LOCK configuration and the #138 Vault Format 2 compatibility/migration contract are implemented on task/141.

Key completed boundaries:

• F1 read/decrypt compatibility with F2 PT2/AAD2 support
• F1 -> F2 writes only when Device explicitly advertises Vault Format 2 support
• format-aware canonical transaction reconciliation and no ordinary F2 -> F1 downgrade
• Recovery Package v1 support for Vault Format 1/2 while VMK wrap remains version 1
• encrypted canonical auto_lock_days persistence only; disabled remains null/unset
• EN/JA Settings UI with enable/disable and 1..31-day selection
• successful/failed/ambiguous save, reconnect/refresh, capability absence, immediate Device LOCK, and Recovery/Passphrase concurrency regression coverage

Evidence

Exact PR head: 7816dab6f6b8bdef9ac062d8a3dfe201999cbd05

• Foundation #742: SUCCESS
  • Web 32 test files / 228 tests passed
  • Linux Chrome production smoke: SUCCESS
  • Windows Chrome production smoke: SUCCESS
  • TypeScript/Vite production build: SUCCESS
  • firmware baseline build/package: SUCCESS
  • dependency lockfile checks: SUCCESS
• Security #745: SUCCESS
• main/base remains d99d4824990b6ebd7ddb670ee31aed4aeb4fc3f8
• concurrent Device PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152 has no changed-file overlap with PR feat(web): add automatic LOCK setting and Vault Format 2 #150
• PR feat(web): add automatic LOCK setting and Vault Format 2 #150 is open, non-Draft, unmerged

Required action

Review PR #150 at the exact head above against Issue #141 and Decision #138. Review should independently verify compatibility, canonical transaction/reconciliation behavior, Recovery Package handling, automatic-LOCK UI semantics/localization, and security boundaries. Do not merge as part of Review.

Completion condition

If no blocking findings remain, record READY_FOR_INTEGRATION. Otherwise record REWORK_REQUIRED with evidence and hand back to Implementation.

[miso-develop]

HANDOFF

FROM: review
TO: implementation
DOMAIN: web
ISSUE: #141
PR: #150
STATE: REWORK_REQUIRED
BLOCKING: yes

Finding

The new automatic-LOCK Settings controller retains an unsaved dirty draft across disconnect/reconnect and can apply a draft created for Device A to a different Device B instead of loading B's authoritative canonical setting.

Evidence

Reviewed exact head: 7816dab6f6b8bdef9ac062d8a3dfe201999cbd05.

web/src/auto-lock-settings.ts only refreshes draft from canonical state when dirty === false; it does not clear/bind dirty or draft when snapshot/Device context disappears or changes. web/src/main.ts creates one controller for the page lifetime and reuses it after disconnectDevice() clears the active Device snapshot.

Concrete sequence: edit A without Save -> disconnect A -> connect writable B with a different canonical setting -> B render keeps A's draft because dirty=true -> Save writes the stale A draft to B. A stale disabled/null draft can therefore disable B's configured automatic-LOCK policy.

Current auto-lock-settings.test.ts covers helper parsing/mapping only and does not exercise this controller lifecycle.

Required action

Bind/reset editable draft state at Device/canonical context boundaries so a newly connected/different Device renders its own authoritative setting and cannot save a stale draft from the prior context. Add controller/form regression coverage for dirty Device A -> disconnect/context loss -> Device B with a distinct canonical value.

Preserve the reviewed Vault Format 1/2, capability-gating, canonical transaction/reconciliation, Recovery Package, and secret-handling semantics.

Completion condition

The cross-Device stale-draft path is closed with regression evidence, exact-head relevant CI is green, and Implementation hands the new exact head back to Review.