[Task][Device] Implement configurable automatic LOCK policy

[miso-develop]

Parent spec

#137

Decision dependency

• [Decision] Define configurable automatic-lock semantics #138 — RESOLVED, including 2026-09-17 persistence/versioning amendment after this Task's SPEC_CHANGE_REQUIRED finding.

Owner

• ACTIVE_ROLE: implementation
• DOMAIN: device

State

READY_FOR_IMPLEMENTATION

Objective

Implement the Device side of the configurable automatic LOCK policy exactly as defined by Decision #138, including Vault Format 1 read compatibility and Vault Format 2 support.

Final functional contract from #138

• Timer basis: fixed maximum continuous UNLOCKED lifetime, not inactivity timeout.
• Unset/absent setting = disabled/unlimited.
• Enabled value = whole integer days 1..31.
• Timer starts at the original transition into UNLOCKED.
• Ordinary interaction, USB/Web Serial activity, OTP reveal/hide, navigation, management, or time sync never resets/extends it.
• Setting changes during an active session are recalculated against the original UNLOCKED start time.
• Expiry must use the same security boundary as explicit Lock.

Persistence / compatibility contract

Version tuple

Implement without changing:

• PROTOCOL_VERSION = 2
• STORAGE_SCHEMA_VERSION = 2

Add/support:

• legacy Vault Format 1 read/runtime support
• current Vault Format 2 read/runtime/write support
• unknown newer Vault formats fail closed

Do not add a plaintext auto_lock_days NVS key or separate unauthenticated settings store.

Vault Format 1

Preserve the shipped v0.1.0 PT1/AAD1 behavior byte-for-byte.

• Format-1 plaintext still ends after credentials + optional Wi-Fi.
• Exact end-of-input remains mandatory.
• Decoding Format 1 yields logical auto_lock_days = unset.
• Do not reinterpret PT1 trailing bytes as extensions.

Vault Format 2

Implement the Decision #138 PT2 structure:

M5AUTH-VLT-PT2\0
u16 format = 2
credential_count + credential records   // same semantics/order as PT1
wifi_present + optional wifi record      // same semantics/order as PT1
u8 auto_lock_present
  0 => disabled/unset, end
  1 => following u8 auto_lock_days (1..31)
other presence/value => invalid
exact end required

Use Format-2-specific authenticated AAD domain (M5AUTH-VLT-AAD2\0 or equivalent explicit domain) binding Format 2 + Storage Schema 2 + vault_id + generation. Retain the existing Format-1 AAD domain for Format-1 decrypt/authentication.

Accepted format transitions in Device canonical update path

• current F1 -> candidate F1: allowed for legacy compatible Web while current persisted state is F1
• current F1 -> candidate F2: allowed
• current F2 -> candidate F2: allowed
• current F2 -> candidate F1: reject as ordinary-update format downgrade
• any unsupported/unknown format: reject fail-closed

Generation, vault_id, AEAD, state, and existing atomic-commit checks remain authoritative in addition to the format-transition rule.

Protocol 2 capability advertisement

Add non-secret optional capability metadata to hello:

"supported_vault_formats": [1, 2]

The existing vault_format_version field continues to report the currently persisted Vault format.

Do not reinterpret supported_vault_formats as persisted state. It describes firmware capability.

Protocol version stays 2: this is additive compatibility/status metadata and the encrypted-envelope update operation remains the existing Protocol-2 operation.

v0.1.0 firmware-update behavior

A normal firmware update from v0.1.0 must:

• preserve Schema-2 NVS and the existing Format-1 envelope;
• initialize/read/report Format 1 successfully;
• start LOCKED after reboot as before;
• permit normal V1 unlock/runtime use;
• treat automatic Lock as disabled until a Format-2 canonical generation is committed.

Device must not autonomously migrate Format 1 on boot or unlock. Web/canonical management owns the migration transaction.

Active runtime setting

• On successful unlock of Format 1: effective auto_lock_days = unset.
• On successful unlock of Format 2: transiently decrypt/validate the Vault and derive the effective optional day value; retain only bounded non-secret runtime policy/deadline state, not the decrypted Vault.
• On successful F1->F2 or F2->F2 vault.update, derive/apply the newly committed setting only after the new authenticated generation has committed successfully.
• Apply setting changes against the current session's original UNLOCKED start timestamp.
• If enabling/shortening the value makes the current session already expired, invoke the explicit-Lock security boundary immediately after successful commit/application.
• A failed/ambiguous Vault update must not change the effective automatic-lock policy to an uncommitted candidate value.

Scope

• Add dual Format-1/Format-2 Vault codec/authentication support required above.
• Add optional auto_lock_days to the logical Device Vault model for Format 2.
• Keep Format-1 logical mapping as disabled/unset.
• Add safe format-transition validation to Runtime / Protocol-2 update handling.
• Advertise supported_vault_formats: [1, 2] in hello.
• Consume and validate optional auto_lock_days: absent/null = disabled; 1..31 = enabled; otherwise reject.
• Track the original current-session UNLOCKED start time using a monotonic runtime source suitable for multi-day intervals.
• Enforce the deadline without relying on mutable wall-clock/NTP time.
• On automatic expiry, transition through the same security boundary as explicit Lock.
• Apply committed setting changes immediately according to [Decision] Define configurable automatic-lock semantics #138.
• Preserve normal firmware-update compatibility with existing v0.1.0 Format-1 state.

Acceptance criteria

Format / compatibility

• Existing synthetic and shipped-contract Format-1 vectors still decode/authenticate unchanged.
• Format-1 exact-end behavior remains unchanged; appended unknown data is rejected.
• Format-1 runtime maps to automatic Lock disabled/unset.
• Format-2 encode/decode uses the PT2 framing and exact-end contract from [Decision] Define configurable automatic-lock semantics #138.
• Format-2 absent setting is accepted as disabled.
• Format-2 values 1 and 31 are accepted; 0, >31, invalid presence, truncated, malformed, or trailing data are rejected.
• Format-1 and Format-2 use distinct correct AAD domains and cannot be cross-authenticated by version substitution.
• Runtime/Protocol accepts F1->F1, F1->F2, F2->F2 according to normal generation rules.
• Runtime/Protocol rejects F2->F1 downgrade even with a numerically newer generation.
• Unknown newer Vault format fails closed without Factory Reset or speculative migration.
• Storage Schema remains 2; no destructive NVS migration is introduced.
• Protocol remains 2 and hello advertises supported_vault_formats: [1, 2] while vault_format_version reports persisted format.
• Normal update from an actual/synthetic v0.1.0 Format-1 persisted snapshot initializes safely and returns LOCKED without data loss.

Automatic LOCK behavior

• Missing/Format-1 setting behaves exactly like v0.1.0: no automatic lifetime limit.
• A fresh unlock starts one continuous-lifetime timer.
• User/device/Web activity does not restart or extend the timer.
• Deadline enforcement uses monotonic elapsed runtime and is independent of trusted-time/NTP adjustments.
• On automatic expiry, visible OTP is hidden immediately and runtime reaches LOCKED.
• Automatic expiry wipes VMK/session/secret-bearing transient state to the same standard as explicit Lock.
• OTP reveal and credential access are rejected after automatic Lock until valid re-unlock.
• Re-unlock starts a new lifetime.
• Disabled -> N days during an active session uses the original unlock start; if already beyond N days, Device locks immediately after successful application.
• N -> M days recalculates against the same original unlock start and never grants a fresh M-day interval.
• Enabled -> disabled cancels the current automatic deadline only after the disabling generation is successfully committed/applied.
• Failed/rejected update leaves the previous committed policy in force.
• Reboot/power-loss/explicit-Lock behavior remains unchanged.
• Normal later firmware update preserves a committed Format-2 setting while reboot still returns the Device to LOCKED.

Tests

• Native/interoperability vectors cover PT1/AAD1 and PT2/AAD2.
• Runtime tests cover format-transition matrix, downgrade rejection, malformed Format 2, and legacy Format-1 boot/unlock.
• Protocol tests cover capability advertisement and F1/F2 envelope acceptance/rejection.
• Automatic-lock tests cover disabled mode, 1-day and 31-day boundaries, elapsed-deadline behavior, setting changes, reboot, explicit Lock, and re-unlock.

Security constraints

• No new persistent plaintext secret/key material.
• auto_lock_days stays inside encrypted authenticated Vault content.
• Do not weaken fresh physical confirmation / Trusted Browser rules for re-unlock.
• Reuse the existing lock/zeroization path rather than implementing a reduced cleanup path.
• Do not use mutable wall-clock trusted time as the security timer source.
• Do not autonomously migrate or downgrade canonical Vault state outside the Web-owned generation transaction.
• Existing generation conflict, request-ID, transaction journal/reconciliation, and fail-closed semantics remain unchanged.
• Protocol/storage version changes beyond those explicitly fixed in [Decision] Define configurable automatic-lock semantics #138 require another Specification handoff; do not invent them locally.

Out of scope

• Web-side Format-1 -> Format-2 canonical migration / settings UI ([Task][Web] Add automatic LOCK timeout setting #141).
• Recovery Package Web import/export implementation changes ([Task][Web] Add automatic LOCK timeout setting #141 as required by [Decision] Define configurable automatic-lock semantics #138).
• Changing automatic-lock semantics fixed by [Decision] Define configurable automatic-lock semantics #138.
• Device UI countdown/status-color Task [Task][Device] Add TOTP validity countdown and semantic status colors #148.

References

• [Spec] Post-v0.1.0 usability and automatic-lock improvements #137
• [Decision] Define configurable automatic-lock semantics #138 compatibility/versioning amendment
• [Task][Web] Add automatic LOCK timeout setting #141 Web counterpart
• [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

[miso-develop]

HANDOFF

FROM: specification
TO: implementation
DOMAIN: device
ISSUE: #140
STATE: BLOCKED_DEPENDENCY
BLOCKING: yes

Finding

Device automatic-LOCK implementation depends on unresolved policy/contract semantics in #138.

Required action

Do not implement #140 until #138 is resolved. After resolution, implement exactly the selected semantics and security boundary.

Completion condition

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

[miso-develop]

HANDOFF

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

Decision resolved

#138 is closed/completed. Automatic LOCK is a fixed maximum continuous UNLOCKED lifetime, disabled when unset, configurable as whole days 1..31.

Required action

Implement #140 exactly as updated. Use the current session's original UNLOCKED start time; ordinary interaction must never reset the timer. Automatic expiry must reuse the explicit-Lock security boundary.

Completion condition

Acceptance Criteria and relevant firmware/contract/security tests pass, then hand off to Review.

[miso-develop]

HANDOFF

FROM: implementation
TO: specification
DOMAIN: device
ISSUE: #140
STATE: SPEC_CHANGE_REQUIRED
BLOCKING: yes

Finding

Bootstrap is READY and #138 is resolved, but implementation source review found a format/version boundary that #138 does not currently resolve.

The current canonical V1 Vault plaintext (M5AUTH-VLT-PT1, VAULT_FORMAT_VERSION = 1) has a fixed binary layout ending after the optional Wi-Fi record. Both Device and Web decoders require exact end-of-input (reader.at_end() / reader.expectEnd()), so appending auto_lock_days under the existing format is not backward-compatible with the shipped v0.1.0 decoder.

The existing canonical vault.update path transports only the authenticated encrypted Vault envelope; Runtime/Persistence exposes no separate settings field in that transaction. Persisting/synchronizing auto_lock_days outside the Vault would therefore contradict #138's current requirement that it be an optional encrypted logical-Vault setting flowing through the canonical generation/update path unless the Decision is explicitly revised.

Issue #140 explicitly requires Specification review rather than locally inventing a Protocol/storage/version change when implementation proves one necessary.

Required decision

Please define the compatibility/versioning mechanism for auto_lock_days, for example one explicitly approved direction:

1. introduce a new Vault plaintext/format version with defined V1 -> new-version compatibility/migration and Web/Recovery implications; or
2. explicitly define an approved compatible extension mechanism for the existing Vault Format 1, including old-firmware/rollback behavior; or
3. revise [Decision] Define configurable automatic-lock semantics #138 to place this non-secret setting outside the encrypted Vault and define the authenticated/transactional canonical synchronization and persistence semantics.

Do not infer one of these choices from the current wording.

Evidence

• firmware/components/m5auth_vault/include/m5auth/vault.hpp: VaultPlaintext currently contains only credentials and optional wifi; kVaultFormatVersion = 1.
• firmware/components/m5auth_vault/vault_format.cpp: fixed PT1 encoding; decoder requires reader.at_end().
• web/src/security/vault-format.ts: matching V1 layout; decoder calls reader.expectEnd() and rejects trailing plaintext data.
• firmware/components/m5auth_vault_runtime/include/m5auth/vault_runtime/runtime.hpp: persisted snapshot/runtime metadata contains encrypted envelope plus last_used; no canonical settings field.
• firmware/components/m5auth_provisioning/canonical_protocol_v2.cpp: canonical Vault update installs/replaces the encrypted envelope; no existing auto_lock_days synchronization field.

No production code, branch, PR, protocol, Vault, or persistence mutation was made for #140 after discovering this blocker.

Completion condition

Update #138/#140 with an explicit approved persistence/format compatibility contract, then hand #140 back to Device Implementation as READY_FOR_IMPLEMENTATION.

[miso-develop]

HANDOFF

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

Specification resolution

The latest SPEC_CHANGE_REQUIRED finding is resolved by the 2026-09-17 amendment to #138.

Approved persistence/versioning direction:

• auto_lock_days remains inside the authenticated encrypted Vault.
• Add Vault Format 2 (PT2/AAD2) with optional auto_lock_days.
• Preserve byte-compatible Vault Format 1 read/runtime support; Format 1 means auto-lock disabled.
• Keep Storage Schema 2 and Protocol 2.
• Advertise supported_vault_formats: [1, 2] in hello.
• Allow F1->F1, F1->F2, F2->F2; reject ordinary F2->F1 downgrade.
• Device never autonomously migrates F1; Web canonical transaction owns F1->F2 migration.

Required action

Bootstrap again against current main and implement the updated Issue #140 contract exactly. Do not introduce additional protocol/storage/version changes locally. Coordinate only through the defined #141 Web counterpart; do not implement Web scope here.

Completion condition

All #140 Acceptance Criteria and relevant Vault/runtime/Protocol/security tests pass, then hand off to independent Review. Implementation must not merge its own PR.

[miso-develop]

IMPLEMENTATION CLAIM

ACTIVE_ROLE: implementation
DOMAIN: device
ISSUE: #140
STATE: ACTIVE_CLAIMED
BRANCH: task/140-device-auto-lock
BASE: d99d4824990b6ebd7ddb670ee31aed4aeb4fc3f8

Specificationの最新 READY_FOR_IMPLEMENTATION handoffを確認し、PT2/AAD2・Format 1互換・F1/F2 transition policy・continuous UNLOCKED lifetime automatic LOCKをIssue #140のupdated contractどおり実装します。

Web #141 / Device UI #148には変更を加えません。Implementation Agentは自身のPRをmergeしません。

[miso-develop]

HANDOFF

FROM: implementation
TO: review
DOMAIN: device
ISSUE: #140
PR: #152
STATE: READY_FOR_REVIEW
BLOCKING: no

Finding

Device implementation for configurable automatic LOCK and Vault Format 2 is complete against Decision #138. Review head is 579347e7e9a53884425b7b405a32ed8f772f8cf1.

Implementation includes Format-1 read/runtime compatibility, PT2/AAD2 Format-2 support, F1/F2 transition enforcement, supported_vault_formats: [1, 2], authenticated auto_lock_days, monotonic continuous-UNLOCKED lifetime enforcement, active-session policy application, and the existing explicit-Lock security boundary for expiry.

Unknown Vault formats fail closed without speculative migration/reset; known-format corruption preserves the existing Recovery Reset eligibility boundary.

Evidence

• Foundation #743: SUCCESS on exact review head, including native Vault/runtime tests, StickS3 contracts, ESP-IDF 5.5.5 build/package, and dependency-lock verification.
• Security #746: SUCCESS, including automatic-lock Protocol-v2 security contract.
• Issue 117 Screen Snapshot [Security][Supply Chain] Pin ESP-IDF build image by digest and isolate privileged release publishing #123: SUCCESS on exact review head.
• PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152 is Ready for Review and remains open/unmerged.
• main was not behind when implementation completed; Web [Task][Web] Add automatic LOCK timeout setting #141 and Device UI [Task][Device] Add TOTP validity countdown and semantic status colors #148 were not modified.

Required action

Independently review PR #152 against Issue #140 Acceptance Criteria and Decision #138, including security/compatibility boundaries. Do not rely on Implementation self-review as final disposition.

Completion condition

Record Review disposition and hand off according to the Review Role Contract.

[miso-develop]

HANDOFF

FROM: review
TO: implementation
DOMAIN: device
ISSUE: #140
PR: #152
STATE: REWORK_REQUIRED
BLOCKING: yes

Exact reviewed head: 579347e7e9a53884425b7b405a32ed8f772f8cf1

Finding

VMK re-key restarts the automatic-LOCK lifetime even though #140 / Decision #138 require Web activity not to restart or extend the fixed continuous UNLOCKED lifetime.

Evidence

Runtime::enter_vmk_rekey_boundary() clears the active unlock-session state. After the re-keyed generation commits, Runtime::rekey_encrypted_vault(...) calls begin_unlock_session(policy, now_ms), and CanonicalVmkSink::install_rekeyed_vault(...) passes the current monotonic time. Thus a re-key late in an enabled session moves the automatic-LOCK origin forward.

The normal vault.update setting path correctly retains the original unlocked_since_ms_; the defect is specific to VMK re-key lifecycle handling.

Required action

Fix the VMK re-key flow so a successful Web-originated re-key cannot extend the active automatic-LOCK lifetime. Preserve the existing re-key security boundary/zeroization and physical-confirmation semantics.

Add a regression proving an enabled session started at T0 still expires from T0 after a later VMK re-key, including the due-at-rekey boundary where relevant.

Completion condition

New exact head satisfies the above regression and relevant Foundation/Security checks, then hand back to Review as READY_FOR_REVIEW.

[miso-develop]

HANDOFF

FROM: implementation
TO: review
DOMAIN: device
ISSUE: #140
PR: #152
STATE: READY_FOR_REVIEW
BLOCKING: no

Finding

Review finding 5701446229 is resolved at exact head 1375cac4f6a2c412d776879a424f9a59806fdacf.

VMK re-key still destroys the resident VMK and enters LOCKED, but it now preserves only the bounded non-secret automatic-lock policy/original monotonic T0 needed to keep the same continuous-UNLOCKED lifetime. A successful authenticated re-key installs the new VMK/candidate policy without restarting T0. If the original deadline is already reached at re-key completion, Protocol v2 immediately invokes the existing shared lock_security_boundary().

Failure/ambiguity remains fail-closed. Physical confirmation/session flow, VMK zeroization, Vault Format transition/downgrade guards, Protocol 2, and Storage Schema 2 remain unchanged.

Evidence

• T0-preserving and exact-deadline re-key regressions: tests/vault_rekey_test.cpp
• re-key security/source contract: tests/vault_runtime_contract_test.py
• immediate post-re-key expiry/shared Lock-boundary contract: tests/automatic_lock_protocol_contract_test.py
• Foundation #752: SUCCESS, including VMK re-key test, runtime security contract, Protocol contracts, ESP-IDF 5.5.5 build/package, dependency lockfile
• Security #755: SUCCESS
• Issue 117 Screen Snapshot fix(web): support current Google Authenticator migration exports #129: SUCCESS
• main advanced via merged Web PR feat(web): add automatic LOCK setting and Vault Format 2 #150 only; no changed-file overlap with this Device rework. PR feat(device): add configurable automatic lock and Vault Format 2 (#140) #152 is mergeable against current main.

Required action

Independently review PR #152 at exact head 1375cac4f6a2c412d776879a424f9a59806fdacf. Implementation must not merge.

Completion condition

Review PASS or a new durable REWORK_REQUIRED finding.