Use idle-based timer for auto-lock behavior

[piyalbasu]

Currently, a user's session is hardcoded at 24 hours. If a user's session is expired and the app is not open, on next open, the user will be prompted to enter their password. That's a very common UX and something most users are comfortable with.

If, however, a user's session expires (meaning they hit the 24 hour mark) while the app is open, the next time we need their private key (like when signing a tx in the send/swap or change trust flow), we will prompt them for their password. This can be disruptive to the UX and it also may be unclear to users why we're suddenly asking for their password.

Acceptance Criteria:

• Document the problem and some possible solutions to this
• Present these solutions to the team and reach consensus on the best solution
• Have the security team vet this solution (if we we're making a big change)

[JakeUrban]

Current Behavior:

• Freighter is expected to prompt users to enter a password every 24 hours

Why It's a Problem:

• Users get prompted to enter a password when making non-transactional actions (navigation to a new screen, etc)
• This causes friction
• 24 hours is too long a time period between password prompts

Solution:

• Changing Auto-Lock Timer logic from time since password was last entered to time since Freighter was last closed
• Setting the default to be 15m -> 1hr
• Adding a screen where users can change Auto-Lock Timer (see attached image from Charles), and setting the default to be 15m -> 1hr
• Only asking for password when opening the app/extension

Fast Follow:

• An additional timer for auto-locking active sessions (edge case)

[JakeUrban]

Updated approach: pure idle-based auto-lock

After looking at how other popular wallets handle this, we want to switch from the previously-discussed "time since last closed" model to a pure idle-based timer, which is the industry standard.

How the pure-idle model works (MetaMask, Rabby, Phantom, Trust Wallet, Coinbase Wallet, etc.):

• A single timer measures time since the user's last interaction with the wallet (clicks, key presses, navigation, dApp signing prompts, etc.).
• Any interaction resets the timer to zero.
• When the timer crosses the user-configured threshold, the wallet locks — regardless of whether the popup is currently open or closed, foregrounded or backgrounded.
• Focus / foreground state isn't tracked as its own signal. While the popup is closed no interaction events are generated, so the counter keeps ticking; while the popup is open and untouched, it ticks the same way and will lock you out on schedule.

Why this is preferable to time-since-last-closed:

• Closes the "extension left open indefinitely" gap (sidebar mode, expanded full tab, popped-out window) where a close-based timer never starts.
• Matches user expectations set by every other major wallet.
• Aligns with how sensitive-application timeouts are framed in PCI DSS and NIST SP 800-53 — both define re-auth thresholds in terms of idle-since-last-interaction.

Scope decisions for v1:

• Single configurable timeout value, surfaced through a settings screen.
• An "Immediately" / lock-on-blur mode is explicitly out of scope for the first cut — it's a separate code path and can be added later if there's demand.
• Specifics (default value, the set of options offered, settings UI) are still TBD and will be defined separately.

[JakeUrban]

📝 Proposal Draft (Round 1/5)

Proposal: Idle-based auto-lock for the Freighter extension

Closes #2082.

Problem

Today the extension's session length is hardcoded:

// extension/src/background/helpers/session.ts
const SESSION_LENGTH = 60 * 24; // minutes (24 hours)
…
startSession() {
  browser?.alarms.create(SESSION_ALARM_NAME, {
    delayInMinutes: SESSION_LENGTH,
  });
}

SessionTimer.startSession() is fired exactly once — from
loginToAllAccounts after the user enters their password
(login-all-accounts.ts).
24 h later, the session-timer alarm fires and clearSession wipes the
hash key and the encrypted private key store. The alarm is not reset
by any user interaction.

That produces two bad outcomes (per the issue and the JakeUrban comments):

1. Mid-session lock surprise. If the user has the extension open and
   the 24 h boundary passes, the next signTransaction /
   signAuthEntry / changeTrust etc. flow suddenly demands a password
   with no UX warning. Bad surprise during high-stakes signing.
2. Active sessions stay unlocked indefinitely when the user has the
   popup open or, more importantly, the side-panel / popped-out window
   open (which is the common power-user pattern). A close-based timer
   would not help here.

The fix the team converged on (see issue comments) is a pure
idle-based timer, matching MetaMask / Rabby / Phantom / Trust /
Coinbase: one timer, measuring time since the last user interaction
with the wallet; any interaction resets it; the wallet locks when it
crosses the configured threshold regardless of popup open/closed state.

Goals

• Replace the hardcoded 24 h session with a user-configurable idle
  timeout.
• A single interaction-resets-the-clock model. No focus / blur signal,
  no separate "popup closed" timer.
• Persist the user's preference; survive service-worker restarts (MV3
  service workers are ephemeral).
• Default that matches industry norms — propose 5 minutes (matches
  MetaMask's default; see Non-Goals for option list).
• Surface the setting in Settings → Preferences (existing screen) so
  no new top-level navigation is needed.

Non-goals (deferred follow-ups)

• "Immediately / lock on blur" mode — explicitly out of scope per the
  v1 scope decisions in the issue.
• An additional "active session" timer beyond pure idle (also called
  out as a fast-follow in the original comment).
• Re-prompting for password mid-transaction for high-value signing
  (separate security feature).
• Changing the encryption-at-rest model — this PR only changes
  when clearSession is called.

Design

Where the lock decision lives

Stays exactly where it is today: the existing session-timer alarm in
extension/src/background/index.ts::initAlarmListener. That listener
already calls clearSession({ sessionStore, localStore }) — we keep
that and only change when the alarm fires.

Why an alarm + persisted last-activity timestamp (not setTimeout, not chrome.idle)

MV3 service workers are unloaded after ~30 s of inactivity. That rules
out an in-memory setTimeout ticking down idle time — it would be
reset to 0 every time the worker spins back up, which is exactly the
opposite of what we want. (The current code already relies on
browser.alarms for this reason.)

chrome.idle is the wrong primitive too: it reports system idleness
(no keyboard/mouse on the OS), not "user has not interacted with the
wallet." A user actively browsing a dApp would never appear idle to
chrome.idle, defeating the whole point.

The correct model is:

• A single lastActivityAt: number (epoch ms) persisted in
  browser.storage.local via the existing DataStorageAccess helper.
• A single recurring alarm (session-timer) that fires at most every
  idleTimeoutMinutes and checks: Date.now() - lastActivityAt >= idleTimeoutMinutes * 60_000. If yes → clearSession. If no →
  reschedule for the remaining time.
• Any user action that proves the wallet is being used updates
  lastActivityAt.

This is robust across service-worker restarts (the timestamp is in
persistent storage), avoids polling, and is what MetaMask /
Rabby / Trust do in their MV3 ports.

What counts as "activity"

We define a single helper:

// extension/src/background/helpers/session.ts
export const recordActivity = async (localStore: DataStorageAccess) => {
  await localStore.setItem(LAST_ACTIVITY_AT_ID, Date.now());
};

and call it from exactly the surfaces that can prove the user is
interacting with the wallet:

1. Every popup-message handler in
   popupMessageListener.ts — these are dispatched only when the
   popup, side panel, or full-tab UI sends an authenticated request to
   the background. We add the recordActivity call once, at the top
   of the central popupMessageListener dispatch (NOT in every
   handler), so future handlers cannot forget.
2. Successful password entry — loginToAllAccounts already starts
   the session; it now also seeds lastActivityAt.
3. dApp-initiated signing prompts that the user must approve —
   when an EXTERNAL_SERVICE_TYPES message opens a UI prompt
   (grantAccess, signTransaction, signAuthEntry, signBlob,
   signMessage), we record activity when the user approves the
   prompt (i.e. inside the popup handler that resolves it), not when
   the dApp first asks. This avoids resetting the idle counter on
   passive dApp pings.

recordActivity is a no-op when there is no active session
(hashKey empty) so we do not "extend" a locked wallet by background
chatter.

Settings UI

Add an idleTimeoutMinutes: number field to:

• extension/src/constants/localStorageTypes.ts (new IDLE_TIMEOUT_MINUTES_ID).
• @shared/api/types/types.ts::Preferences.
• @shared/api/types/message-request.ts::SaveSettingsMessage.
• extension/src/background/messageListener/handlers/saveSettings.ts and
  loadSettings.ts.
• extension/src/popup/ducks/settings.ts (settingsInitialState,
  saveSettings thunk).
• extension/src/popup/views/Preferences/index.tsx — a single
  <Select> (using the existing @stellar/design-system Select
  used elsewhere in this screen for similar choices, or Input +
  options if no Select is available there) with the options below.

Options offered: 1, 5, 15, 30, 60, 240 (minutes), i.e.
1 min, 5 min, 15 min, 30 min, 1 h, 4 h. Default 5. Rationale: covers
MetaMask's (5 min default, options up to 30 days — we cap lower
because Freighter's threat model is dApp-signing-specific) and Rabby's
(1/5/10/30/60 min) ranges without going to "never" — "never" creates a
class of users who never lock and is out of scope for v1.

The setting persists across logout / re-login (it's a preference, not
session state). Existing users without the field default to 5
minutes on first read — this is a behavior change and worth
calling out explicitly in the PR description so the team can decide
whether to ship a one-time in-app notice. (The 24 h default today is
itself a security smell; quietly tightening it on upgrade is the
correct conservative default.)

Resetting the alarm

When recordActivity updates lastActivityAt, it also reschedules
the alarm:

browser.alarms.create(SESSION_ALARM_NAME, {
  delayInMinutes: idleTimeoutMinutes,
});

browser.alarms.create with an existing name replaces the existing
alarm, so this is the natural debounce primitive — the alarm cannot
fire while the user keeps interacting. We do not need to inspect or
clear the existing alarm.

When the user changes idleTimeoutMinutes in Preferences:

• If a session is active, immediately reschedule the alarm using the
  new value relative to the existing lastActivityAt (so changing the
  setting from 60 → 5 with a 4-minute-old lastActivityAt locks one
  minute later, not five). Same store: persist, then call
  recordActivity-style reschedule with the new value.
• If no session is active, just persist; the next loginToAllAccounts
  will pick it up.

Removing the old constant

SESSION_LENGTH = 60 * 24 is deleted. SessionTimer.startSession()
is renamed to scheduleIdleTimeout(idleTimeoutMinutes) and takes the
timeout as a parameter. loginToAllAccounts reads the user's stored
idleTimeoutMinutes (with the 5-minute default) and passes it in.

Files touched (concrete list)

• extension/src/background/helpers/session.ts — rewrite
  SessionTimer → idle-aware helpers; add LAST_ACTIVITY_AT_ID,
  recordActivity, scheduleIdleTimeout, getIdleTimeoutMinutes.
• extension/src/background/index.ts::initAlarmListener — when the
  alarm fires, re-check lastActivityAt and either lock or
  reschedule.
• extension/src/background/index.ts (top of the
  popupMessageListener dispatch) — call recordActivity for every
  inbound popup message.
• extension/src/background/messageListener/helpers/login-all-accounts.ts
  — call scheduleIdleTimeout(idleTimeoutMinutes) and seed
  lastActivityAt.
• extension/src/background/messageListener/handlers/saveSettings.ts
  & loadSettings.ts — read/write idleTimeoutMinutes; if it
  changed and a session is active, reschedule.
• extension/src/background/messageListener/handlers/signOut.ts —
  clear lastActivityAt and the alarm explicitly (defensive; alarm
  also clears on clearSession).
• extension/src/constants/localStorageTypes.ts — add
  LAST_ACTIVITY_AT_ID, IDLE_TIMEOUT_MINUTES_ID.
• @shared/api/types/types.ts::Preferences — add field.
• @shared/api/types/message-request.ts::SaveSettingsMessage — add field.
• extension/src/popup/ducks/settings.ts — wire field through initial
  state, saveSettings thunk, and selector.
• extension/src/popup/views/Preferences/index.tsx — UI control.
• extension/src/popup/locales/*/translation.json — strings ("Auto-lock
  timer", "Lock wallet after", "1 minute" … "4 hours", an explanatory
  caption).

Migration

For users upgrading from a build without idleTimeoutMinutes:

• getIdleTimeoutMinutes returns 5 when the key is absent. No
  forced migration write — it'll be persisted the first time the user
  opens Preferences or changes the value. This avoids racing with
  versionedMigration on first install.
• If the user has an active session at upgrade time (hashKey present
  in memory but lastActivityAt missing), seed lastActivityAt = Date.now() on the next background-message dispatch — i.e. treat
  "now" as their first activity under the new model. They will not be
  locked retroactively.

Testing

Unit tests under extension/src/background/messageListener/__tests__/
(existing test scaffolding for handlers):

• recordActivity writes lastActivityAt and reschedules the alarm.
• recordActivity is a no-op when hashKey is empty.
• Alarm-fired handler with lastActivityAt younger than the threshold
  reschedules, does NOT call clearSession.
• Alarm-fired handler with lastActivityAt older than the threshold
  calls clearSession.
• loginToAllAccounts seeds lastActivityAt and schedules with the
  user's configured timeout (and falls back to 5 min when absent).
• saveSettings reschedules the alarm when idleTimeoutMinutes
  changes mid-session.
• signOut clears lastActivityAt and the alarm.
• popupMessageListener records activity for incoming messages.

Mock browser.alarms.create, browser.alarms.clear, and the
localStore (the existing handler tests already mock these — follow
the pattern in confirmPassword.test.ts etc.).

Manual smoke (in PR description):

1. Set timeout to 1 minute, log in, leave popup closed for 90 s, open
   popup → password prompt.
2. Set timeout to 1 minute, log in, click around the popup every 30 s
   for 3 minutes → no password prompt.
3. Change timeout from 60 → 1 mid-session, 2 minutes after last
   action → password prompt within ~1 minute.
4. Sign out, wait, log back in → previously stored timeout still in
   effect.

Risks

• Behavior change on upgrade. Default tightens from 24 h to 5 min.
  Real risk of "why does Freighter keep asking for my password?" user
  reports during the first week. Mitigation: ship a one-time
  in-product notice on first launch after upgrade. Out of scope to
  implement here but flagged for the team — happy to land it in this
  PR if reviewers want.
• recordActivity performance. Writing to browser.storage.local
  on every popup message adds one async write per UI interaction.
  browser.storage.local writes are cheap (debounced internally,
  IndexedDB-backed) but we should not write on every keystroke. We
  only write on background-bound messages, which already incur an
  IPC round-trip — the marginal cost is negligible.
• Clock skew / DST. We use Date.now() (epoch ms, monotonic
  across DST). No Date parsing involved.
• Service worker dies between alarm-fire and clearSession. Not
  a concern: the alarm listener is registered at the top of
  background.min.js and rehydrates the worker; clearSession
  awaits its storage writes before returning.

---

Submitting to adversarial critic for review…

[JakeUrban]

📝 Proposal Draft (Round 1/5)

Use idle-based timer for auto-lock behavior

Problem

Today Freighter's session is a single hardcoded 24-hour absolute timer
(SESSION_LENGTH = 60 * 24 minutes in
extension/src/background/helpers/session.ts). The Chrome alarm
session-timer is created once at unlock by SessionTimer.startSession()
and never reset — so:

1. A user who actively works in Freighter for 24 hours straight gets
   bounced to the password prompt mid-flow.
2. A user who has left the extension idle for 23 hours and 59 minutes
   keeps a fully unlocked session — there is no idle protection at all.
3. The 24-hour value is hardcoded; users cannot change it.

The latest issue comment narrows the chosen direction: a pure
idle-based timer matching MetaMask / Rabby / Phantom / Trust Wallet /
Coinbase Wallet, with a user-configurable timeout surfaced in Settings.
An "Immediately / lock-on-blur" mode is explicitly out of scope for v1.

Approach

Replace the absolute alarm with an idle alarm that the background
service worker keeps re-scheduling at now + autoLockTimeoutMinutes
each time it observes user activity. When the alarm fires, the existing
clearSession path runs and the user is prompted to unlock.

Key properties:

• The Chrome alarms API is the source of truth for the deadline and
  survives service-worker teardown. The popup is treated as a transient
  reporter of activity, never as the timer itself.
• While the popup / sidebar is open, an activity hook installed at the
  app root sends a throttled "activity ping" message to the background;
  the background reschedules the alarm. Throttle interval: every 15 s
  of continuous activity (one ping at most per 15 s while events arrive)
  to keep message volume tiny.
• While the popup is closed, no pings arrive and the alarm runs out
  naturally — so closing the extension does not extend the deadline.
• Settings changes (changing the timeout) immediately reschedule the
  running alarm using the new duration relative to now.

This matches the industry-standard behavior described in the issue
comment and the principle that "an active session should not silently
exceed the configured idle window" without introducing an absolute cap
(the original issue's fast-follow item for active-session locking is
subsumed by pure idle).

Detailed design

1. Storage and types

Add a single new storage key and Settings field — no per-account
scoping (auto-lock is global to the wallet).

extension/src/constants/localStorageTypes.ts:

export const AUTO_LOCK_TIMEOUT_MINUTES_ID = "autoLockTimeoutMinutes";

@shared/api/types/index.ts (in the Settings interface):

autoLockTimeoutMinutes: number;

@shared/api/types/message-request.ts (SaveSettingsMessage):

autoLockTimeoutMinutes: number;

Default value: 15 (minutes). Selected as the median of MetaMask
(5 min default), Rabby (10 min), Phantom (15 min default for
Auto-lock timer), Trust Wallet (10 min), Coinbase Wallet (5 min) and
balances Freighter's previous 24-hour expectation against the security
norm. Existing installs with no stored value resolve to 15 minutes via
?? 15 in the loader (see §4 for migration handling).

Preset list offered in the UI: 1 (debug/testing — gated, see §6),
5, 15 (default), 30, 60 minutes. Five visible options balances
choice with simplicity. A "Custom" input is out of scope for v1.

Validation: background-side saveSettings clamps the incoming
value to the closed set {1, 5, 15, 30, 60} before persisting; an
invalid request is rejected (settings save returns an error). Without
this clamp, a corrupt or attacker-supplied message could schedule a
multi-day alarm and silently disable auto-lock.

2. SessionTimer rework

Rewrite extension/src/background/helpers/session.ts:

import { AUTO_LOCK_TIMEOUT_MINUTES_ID } from "../../constants/localStorageTypes";

export const SESSION_ALARM_NAME = "session-timer";
export const DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES = 15;
export const VALID_AUTO_LOCK_TIMEOUT_MINUTES = [1, 5, 15, 30, 60] as const;
export type AutoLockTimeoutMinutes =
  (typeof VALID_AUTO_LOCK_TIMEOUT_MINUTES)[number];

export class SessionTimer {
  private localStore: DataStorageAccess;

  constructor(localStore: DataStorageAccess) {
    this.localStore = localStore;
  }

  private async getTimeoutMinutes(): Promise<number> {
    const stored = await this.localStore.getItem(AUTO_LOCK_TIMEOUT_MINUTES_ID);
    return typeof stored === "number" &&
      (VALID_AUTO_LOCK_TIMEOUT_MINUTES as readonly number[]).includes(stored)
      ? stored
      : DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES;
  }

  // Schedules (or replaces) the auto-lock alarm at now + configured timeout.
  // Idempotent: called on login, on every activity ping, and when the user
  // changes the timeout setting. browser.alarms.create replaces an existing
  // alarm of the same name, so we never accumulate stale alarms.
  async resetSession() {
    const delayInMinutes = await this.getTimeoutMinutes();
    await browser.alarms.create(SESSION_ALARM_NAME, { delayInMinutes });
  }

  // Cancels the alarm — used at sign-out so a lapsed alarm cannot
  // re-fire `clearSession` after the user has already logged out.
  async stopSession() {
    await browser.alarms.clear(SESSION_ALARM_NAME);
  }

  // Backwards-compatible alias for the existing call sites at unlock.
  async startSession() {
    await this.resetSession();
  }
}

SessionTimer becomes async — every call site already awaits its
container handler, but the .startSession() invocations in
createAccount.ts, recoverAccount.ts, migrateAccounts.ts,
login-all-accounts.ts, etc. will be updated to await sessionTimer.startSession(). The constructor changes — the singleton
in background/index.ts is now constructed with localStore:

const localStore = dataStorageAccess(browserLocalStorage);
const sessionTimer = new SessionTimer(localStore);

signOut (background/messageListener/handlers/signOut.ts) calls
await sessionTimer.stopSession() after clearing session state.

3. New service type: USER_ACTIVITY

Add a service type for activity pings.

@shared/constants/services.ts (wherever SERVICE_TYPES lives, the
file referenced from popupMessageListener.ts): add
USER_ACTIVITY = "USER_ACTIVITY".

@shared/api/types/message-request.ts: add

export interface UserActivityMessage extends BaseMessage {
  type: SERVICE_TYPES.USER_ACTIVITY;
}

…and include it in the ServiceMessageRequest union.

popupMessageListener.ts dispatches to a new handler:

case SERVICE_TYPES.USER_ACTIVITY: {
  return userActivity({ sessionStore, sessionTimer });
}

Handler background/messageListener/handlers/userActivity.ts:

export const userActivity = async ({
  sessionStore,
  sessionTimer,
}: {
  sessionStore: Store;
  sessionTimer: SessionTimer;
}) => {
  // Only reset while there is an active unlocked session — a stray
  // ping from a leftover popup tab must not "wake" a locked wallet.
  const hashKey = hashKeySelector(sessionStore.getState() as SessionState);
  if (!hashKey?.key) {
    return { ok: false };
  }
  await sessionTimer.resetSession();
  return { ok: true };
};

4. saveSettings / loadSettings plumbing

saveSettings.ts accepts the new field, validates it against
VALID_AUTO_LOCK_TIMEOUT_MINUTES, persists it, and immediately
reschedules the running alarm if the wallet is currently unlocked
(otherwise the new value would only take effect after the next
unlock). This requires saveSettings to receive the sessionTimer
and sessionStore, which is a small wiring change in
popupMessageListener.ts:

case SERVICE_TYPES.SAVE_SETTINGS: {
  return saveSettings({ request, localStore, sessionStore, sessionTimer });
}

loadSettings.ts reads the value (defaulting to 15) and returns it
alongside the other settings.

The Settings shape in the popup duck (popup/ducks/settings.ts)
gets the new field; initialState, saveSettings thunk arg, the
reducer cases, and the migration of settingsInitialState all gain
autoLockTimeoutMinutes: 15.

5. Activity detection in the popup

New hook extension/src/popup/helpers/useActivityPing.ts:

import { useEffect } from "react";
import { sendMessageToBackground } from "popup/helpers/sendMessageToBackground";
import { SERVICE_TYPES } from "@shared/constants/services";

const PING_THROTTLE_MS = 15_000;
const ACTIVITY_EVENTS = ["mousedown", "keydown", "touchstart", "scroll"] as const;

// Sends at most one ping per PING_THROTTLE_MS while activity is occurring.
// Pings happen on a leading-edge schedule (fire immediately on first event,
// then suppress for the throttle window) so a single click locks in a fresh
// deadline without waiting 15 s.
export const useActivityPing = (isUnlocked: boolean) => {
  useEffect(() => {
    if (!isUnlocked) return undefined;

    let lastPingAt = 0;
    const handler = () => {
      const now = Date.now();
      if (now - lastPingAt < PING_THROTTLE_MS) return;
      lastPingAt = now;
      void sendMessageToBackground({ type: SERVICE_TYPES.USER_ACTIVITY });
    };

    for (const evt of ACTIVITY_EVENTS) {
      window.addEventListener(evt, handler, { passive: true });
    }
    return () => {
      for (const evt of ACTIVITY_EVENTS) {
        window.removeEventListener(evt, handler);
      }
    };
  }, [isUnlocked]);
};

Mount the hook in popup/App.tsx (or whatever the popup root
component is — verify when implementing) so it covers both the popup
window and the sidebar — both run the same React entry. Pass
isUnlocked from the existing hasPrivateKey / session selector so
pings stop as soon as the user signs out.

Note on coverage: navigation between popup screens is already a
mousedown / keydown event, and React Router transitions do not
generate distinct DOM events but always follow a user gesture. The
four event types above are sufficient.

6. Settings UI

Surface the new setting under Settings → Preferences alongside
the other booleans, since the Preferences screen is already where
non-security toggles live and reusing it avoids a new route.

Add a labelled dropdown (the design system's Select) below the
existing toggles:

Auto-lock after:
  [ 5 minutes ]
  [ 15 minutes  (default) ]
  [ 30 minutes ]
  [ 1 hour ]

The 1 minute option is hidden behind the existing experimental-mode
flag (isExperimentalModeEnabled) so QA / developers can exercise the
flow quickly without shipping a foot-gun to end users. (Decision
deliberately surfaced for critic challenge.)

The dropdown writes through the same saveSettings thunk as the
other Preferences controls (uses the existing AutoSaveFields
pattern, so changes persist immediately).

7. Tests

Adapt MockBrowserAlarm in test-helpers.ts so it tracks resets and
honors a configurable duration read from the mock storage. Add:

• Unit tests for SessionTimer.resetSession / .stopSession /
  storage round-trip and the default-when-unset / invalid-value paths.
• Unit tests for the userActivity handler: ignored when locked,
  reschedules when unlocked.
• Unit tests for saveSettings: validates the new field, rejects
  out-of-range values, persists valid values, reschedules the alarm
  when unlocked, leaves the alarm alone when locked.
• Round-trip test in loadSettings.
• Popup-side test for the useActivityPing throttle (leading-edge,
  15 s window, listener cleanup on unmount / lock).
• Update existing handler tests (createAccount, recoverAccount,
  migrateAccounts, confirmPassword, etc.) for the new
  sessionTimer constructor signature.

8. Backward compatibility

No migration code needed: the storage key is new, and reads default
to 15 minutes. Existing unlocked sessions on update will lock after
the new default idle window — acceptable, and arguably the desired
behavior on upgrade.

The browser-alarm name (session-timer) is unchanged, so any
in-flight alarm scheduled by an older build is honored on first run
of the new build until the user next interacts (which then resets to
the configured value).

What is intentionally out of scope

• "Lock immediately on blur" / lock-on-popup-close as a distinct
  mode (explicit in the issue comment).
• A custom (free-form) timeout value.
• Per-account auto-lock overrides.
• Absolute max-session cap on top of the idle timer (the original
  issue's "active-session" fast-follow is subsumed by pure idle).
• Telemetry on lock events.

Risks / open questions

1. Default value (15 min). Open to challenge if the team
   prefers 5 or 30. Listed as a settled v1 default for now.
2. Throttle interval (15 s). Could be 30 s or 60 s. 15 s keeps
   the rescheduling lag well under any plausible timeout and still
   produces fewer than 240 background messages per hour of active
   use.
3. Sidebar event capture. Confirm the activity hook fires in the
   sidebar context the same way as in the popup window (it should —
   the sidebar runs the same React entrypoint per Freighter's existing
   architecture).
4. Chrome alarm minimum delay. Chrome MV3 enforces a 30 s minimum
   delayInMinutes. The smallest preset (1 minute) is comfortably
   above that floor.

Files touched (anticipated)

• extension/src/background/helpers/session.ts — SessionTimer rewrite
• extension/src/background/index.ts — construct timer with localStore
• extension/src/background/messageListener/handlers/userActivity.ts — new
• extension/src/background/messageListener/handlers/saveSettings.ts
• extension/src/background/messageListener/handlers/loadSettings.ts
• extension/src/background/messageListener/handlers/signOut.ts — stop alarm
• extension/src/background/messageListener/popupMessageListener.ts — dispatch
• extension/src/background/messageListener/helpers/test-helpers.ts
• extension/src/constants/localStorageTypes.ts
• @shared/api/types/index.ts, @shared/api/types/message-request.ts,
  @shared/constants/services.ts
• extension/src/popup/helpers/useActivityPing.ts — new
• extension/src/popup/App.tsx — mount the hook
• extension/src/popup/ducks/settings.ts
• extension/src/popup/views/Preferences/index.tsx
• Various existing handler call sites that await startSession()
• Test files for the touched modules

---

*Submitting to adversarial critic for *
review

[JakeUrban]

🔍 Critic Response (Round 1/5)

Full critique (click to expand)

Mostly feasible, but not ready.

1. Fix the proposal's core factual error: SessionTimer.startSession() is not only called from loginToAllAccounts. It is also called in createAccount.ts:80, recoverAccount.ts:153-154, and migrateAccounts.ts:236-249 (plus login-all-accounts.ts:137-138). Migration/seeding logic for lastActivityAt must cover every session-start path.

2. Don't hook recordActivity at the top of every popupMessageListener request. The single dispatch point exists (popupMessageListener.ts:139-629), but it also handles housekeeping like MARK_QUEUE_ACTIVE (popupMessageListener.ts:598-609) sent on mount/unmount by useMarkQueueActive.ts:13-40. That would falsely extend sessions on close/background cleanup.

3. "Every message to background" is not equivalent to "wallet activity." Large parts of the UI are local React state after initial fetch, e.g. Account/index.tsx:61-88 and SendAmount/index.tsx:135-180. Without a throttled UI activity ping, users can still be actively using the wallet and get locked mid-flow.

4. Clarify hardware-wallet behavior. The proposal's "no-op when hashKey is empty" is inconsistent with current unlocked-state semantics: buildHasPrivateKeySelector treats hardware-wallet-active accounts as effectively unlocked (background/ducks/session.ts:176-182). Also, hardware approval completion goes through HANDLE_SIGNED_HW_PAYLOAD (message-request.ts:212-216, popupMessageListener.ts:310-314, @shared/api/internal.ts:1292-1305).

5. Correct the external approval inventory. Real approval-producing external flows are in freighterApiMessageListener.ts:158-870: REQUEST_ACCESS/SET_ALLOWED_STATUS → grantAccess, SUBMIT_TOKEN → addToken, SUBMIT_TRANSACTION, SUBMIT_BLOB, SUBMIT_AUTH_ENTRY. The proposal omits add-token and mixes "signMessage" terminology with SIGN_BLOB.

6. Make the alarm model consistent. Verified from WebExtensions docs: same-name alarms replace prior ones, so debouncing is fine. But the proposal says "single recurring alarm" while its sample uses one-shot create(...). Use one-shot scheduling; otherwise you also need explicit clearing on lock/sign-out to avoid repeated post-lock fires. Current listener just clears on alarm (background/index.ts:227-235).

7. Prefer storing lastActivityAt in session state / browser.storage.session, not storage.local. The repo already hydrates session Redux state through background/store.ts:11-60. lastActivityAt is session state, like hashKey, not a long-lived preference; local storage adds unnecessary cleanup/migration edge cases.

8. Expand the settings-surface list. Besides Preferences and SaveSettingsMessage (types.ts:186-193, message-request.ts:279-285), this also requires wiring through @shared/api/internal.ts:1615-1663, popup/ducks/settings.ts:48-63 and 122-170, selectors/defaults, and tests.

VERDICT: REVISE

Verdict: REVISE

Feedback items to address

1. startSession is called from 4 places (createAccount, recoverAccount, migrateAccounts, login-all-accounts), not 1.
2. Hooking recordActivity at the top of popupMessageListener is wrong — MARK_QUEUE_ACTIVE is housekeeping fired on mount/unmount.
3. "Every message to background" ≠ wallet activity — most UI is local React state. Need a throttled UI activity ping.
4. Clarify HW behavior; hashKey empty does not equal "locked" for HW-active accounts. HANDLE_SIGNED_HW_PAYLOAD is the HW approval completion path.
5. Correct the external-flow inventory: REQUEST_ACCESS/SET_ALLOWED_STATUS → grantAccess, SUBMIT_TOKEN → addToken, plus SUBMIT_TRANSACTION/BLOB/AUTH_ENTRY. No external "signMessage".
6. Use one-shot alarms consistently and clear the alarm explicitly on lock/sign-out.
7. Store lastActivityAt in the session Redux store (storage.session), not storage.local — it shares lifecycle with hashKey.
8. Settings wiring also needs @shared/api/internal.ts::saveSettings, popup/ducks/settings.ts, selectors/defaults, and tests.

[JakeUrban]

📝 Proposal Draft (Round 2/5)

Proposal: Idle-based auto-lock for the Freighter extension (r2)

Closes #2082.

Problem

Today the extension's session length is hardcoded:

// extension/src/background/helpers/session.ts
const SESSION_LENGTH = 60 * 24; // minutes (24 hours)
…
startSession() {
  browser?.alarms.create(SESSION_ALARM_NAME, {
    delayInMinutes: SESSION_LENGTH,
  });
}

SessionTimer.startSession() is fired from four session-start paths:

• login-all-accounts.ts:137-138 (confirmPassword flow)
• createAccount.ts:80
• recoverAccount.ts:153-154
• migrateAccounts.ts:236-249

24 h later, the session-timer alarm fires and the listener in
background/index.ts:227-235 calls clearSession, which dispatches
timeoutAccountAccess (wipes hashKey + password from the session
redux store) and removes TEMPORARY_STORE_ID from local storage. The
alarm is not reset by any user interaction.

That produces two bad outcomes:

1. Mid-session lock surprise. Cross the 24 h boundary with the
   extension open and the next signing flow suddenly demands a
   password.
2. Active sessions stay unlocked indefinitely when the popup,
   side-panel, or popped-out window stays open — common power-user
   patterns. A "time since closed" timer wouldn't help here.

The team's converged design (issue comment 2026-05-20): a pure
idle-based timer matching MetaMask / Rabby / Phantom / Trust /
Coinbase. One timer measures time since last user interaction with
the wallet; any interaction resets it; wallet locks when it crosses
the configured threshold regardless of popup state.

Goals

• Replace the hardcoded 24 h session with a user-configurable idle
  timeout.
• Single interaction-resets-the-clock model.
• Survive MV3 service-worker restarts (≈30 s idle teardown).
• Default that matches industry norms — 5 minutes (MetaMask's
  default).
• Settings UI lives in the existing Settings → Preferences screen.

Non-goals (deferred follow-ups)

• "Immediately / lock on blur" mode.
• A separate "active session" timer beyond pure idle.
• Re-prompting mid-transaction for high-value signing.
• Changing the encryption-at-rest model.

Design

Where the lock decision lives

Unchanged: the session-timer alarm handler in
background/index.ts:227-235. We only change when it fires and
what it does when it fires.

Why an alarm + session-storage timestamp (not setTimeout, not chrome.idle)

MV3 service workers are unloaded after ~30 s of inactivity, so
in-memory setTimeout is unusable for idle measurement. chrome.idle
reports system idleness (no OS keyboard/mouse), not "user not
interacting with the wallet" — wrong primitive.

browser.alarms is durable across service-worker restarts and
already in use; same-name create() calls replace any prior alarm
(WebExtensions spec), giving us natural debouncing.

State location: session Redux store, not storage.local

lastActivityAt: number (epoch ms) lives in the session Redux
store, alongside hashKey and password, in
background/ducks/session.ts. Rationale:

• It shares lifecycle with hashKey: set when a session begins,
  cleared when clearSession / timeoutAccountAccess fires.
• The session store is already persisted to browser.storage.session
  via background/store.ts:11-60 on Chrome (survives SW restarts;
  cleared on browser restart, which is exactly what we want — a
  browser restart already drops the unlocked session). On Firefox
  SESSION_STORAGE_ENABLED is false and the redux store is in-memory
  in the persistent background script, which also matches the
  required lifetime.
• This avoids a parallel cleanup path in storage.local and a
  migration step on logout.

idleTimeoutMinutes, by contrast, is a long-lived preference and
lives in storage.local like every other Preferences field.

Updated SessionState

// background/ducks/session.ts
interface AppData {
  privateKey?: string;
  hashKey?: { key: string };
  password?: string;
  lastActivityAt?: number;        // NEW — epoch ms; undefined ⇒ no active session
}

New reducer actions:

• recordActivity(now: number) — sets lastActivityAt = now. Used by
  the activity helpers below.
• timeoutAccountAccess (existing) — additionally clears
  lastActivityAt.
• reset / logOut (existing initialState) — covers lastActivityAt = undefined automatically.

New selector:

• lastActivityAtSelector.
• isSessionActiveSelector — true iff hashKey?.key is set or
  the active account is a hardware wallet (the same predicate used by
  buildHasPrivateKeySelector in background/ducks/session.ts:174-182).
  Lifted into a single helper so background code does not have to
  re-derive it.

What counts as "activity"

Three sources, each routed through one recordActivity helper:

// background/helpers/session.ts
export const recordActivity = async ({
  sessionStore,
  localStore,
}: {
  sessionStore: Store;
  localStore: DataStorageAccess;
}) => {
  if (!isSessionActive(sessionStore.getState())) return;
  const now = Date.now();
  sessionStore.dispatch(setLastActivityAt(now));
  const idleMins = await getIdleTimeoutMinutes({ localStore });
  await scheduleIdleAlarm(idleMins);  // one-shot; replaces existing alarm
};

Source 1 — explicit UI activity ping from the popup. The popup
already has a global event surface (the root App component). We add
a small useActivityPing hook that, while the popup is open,
listens for mousedown / keydown / wheel / touchstart on the
document, throttled to one send per 30 s, and posts
SERVICE_TYPES.RECORD_ACTIVITY to the background. This is the
primary activity signal — it covers the local-React-state cases
(Account/index.tsx, SendAmount/index.tsx, etc.) where the UI does
not otherwise re-hit the background.

The throttle keeps the write cost low (worst case 2 writes/min while
the popup is open) and resists pathological event bursts.

Source 2 — explicit per-handler activity records for genuine user
actions. Rather than a blanket "every popup message extends the
session" hook (rejected for the MARK_QUEUE_ACTIVE / OPEN_SIDEBAR
housekeeping reason — those are emitted on mount/unmount by
useMarkQueueActive.ts), we route activity through:

• CONFIRM_PASSWORD handler — already user-typed-password.
• HANDLE_SIGNED_HW_PAYLOAD handler — user just signed on a hardware
  device. (HW analogue of providing a fresh password.)
• GRANT_ACCESS, ADD_TOKEN, SIGN_TRANSACTION, SIGN_BLOB,
  SIGN_AUTH_ENTRY handlers — user actively approved a signing flow.
• SIGN_FREIGHTER_TRANSACTION /
  SIGN_FREIGHTER_SOROBAN_TRANSACTION — internal sends (Send / Swap /
  ChangeTrust) where the user just submitted.
• MAKE_ACCOUNT_ACTIVE, UPDATE_ACCOUNT_NAME,
  CHANGE_ASSET_VISIBILITY, CHANGE_COLLECTIBLE_VISIBILITY,
  CHANGE_NETWORK, SAVE_SETTINGS, SAVE_EXPERIMENTAL_FEATURES,
  SAVE_ALLOWLIST, SAVE_BLOCKAID_DEBUG_OVERRIDE,
  ADD_RECENT_ADDRESS, ADD_TOKEN_ID, REMOVE_TOKEN_ID,
  ADD_COLLECTIBLE, ADD_RECENT_PROTOCOL,
  CLEAR_RECENT_PROTOCOLS, ADD_ASSETS_LIST, MODIFY_ASSETS_LIST,
  DISMISS_DISCOVER_WELCOME, DISMISS_MOBILE_APP_BANNER,
  RESET_EXP_DATA, ADD_CUSTOM_NETWORK, REMOVE_CUSTOM_NETWORK,
  EDIT_CUSTOM_NETWORK, IMPORT_ACCOUNT, IMPORT_HARDWARE_WALLET,
  ADD_ACCOUNT, SHOW_BACKUP_PHRASE, GET_MNEMONIC_PHRASE,
  CONFIRM_MNEMONIC_PHRASE, CONFIRM_MIGRATED_MNEMONIC_PHRASE,
  MIGRATE_ACCOUNTS, FUND_ACCOUNT, SIGN_OUT (sign-out is a user
  action even though it ends the session — we record then clear).
• Pure read / cache / housekeeping types — LOAD_*, GET_*,
  CACHE_*, LOAD_BACKEND_SETTINGS, MARK_QUEUE_ACTIVE,
  OPEN_SIDEBAR, REJECT_*, GET_IS_ACCOUNT_MISMATCH — do not
  record activity. They are either internal polling/caches or
  housekeeping that fires without the user touching the UI.

To make this safe-by-default, we implement this as a
USER_ACTION_SERVICE_TYPES set in @shared/constants/services.ts
right next to the enum, and the dispatch wrapper in
background/index.ts::initExtensionMessageListener calls
recordActivity iff the inbound type is in that set. Adding a new
service type forces the author to decide which bucket it belongs in
(this is the "invariant in a shared helper" pattern — newcomers can't
silently forget to record activity, and they also can't accidentally
extend the session by adding a polling type).

Source 3 — explicit per-handler records for external (dApp) approval
completion. Inside popupMessageListener handlers that resolve
queued external requests (grantAccess, addToken,
signTransaction, signBlob, signAuthEntry,
handleSignedHwPayload), the existing user-approval code path emits
the message — recording activity at the popup-handler entry (Source 2)
already covers them. We do not record activity inside
freighterApiMessageListener.ts itself: those messages originate from
dApps, not the user, and recording them would let any open tab
silently keep the wallet unlocked.

Hardware wallet handling

buildHasPrivateKeySelector treats hardware-wallet-active accounts
as effectively unlocked even with empty hashKey. The idle timer
must therefore apply to HW-only sessions too, otherwise an HW user
who never types a password is never locked.

• isSessionActive returns true when hashKey?.key OR
  getIsHardwareWalletActive is true. This is the same predicate used
  by buildHasPrivateKeySelector (background/ducks/session.ts:176-182).

• When the alarm fires for an HW-only session, we still call
  clearSession. clearSession clears the temporary store and the
  hashKey; for HW the hashKey is already empty, but the contract
  becomes: locking always drops to the unlock screen. To make the HW
  case effective, clearSession is extended to also dispatch a
  lockHardwareWallet action that flips a new
  isHardwareWalletLocked: boolean flag in the session reducer.
  buildHasPrivateKeySelector becomes:
  (isHardwareWalletActive && !isHardwareWalletLocked) || !!hashKey?.key.
  confirmPassword (and the dedicated HW unlock flow that already
  exists for HW accounts) clears the flag on successful unlock.

  Implementation note. If, on reading
  background/messageListener/handlers/loadAccount.ts and the HW
  unlock flow, this turns out to add more surface area than is
  proportionate to v1, we will instead defer HW idle-lock to a
  follow-up and document the limitation in the PR. The idle timer
  still runs for HW sessions; it just becomes a no-op rather than a
  visible lock. This decision will be made and called out during
  implementation, not silently.

Alarm model: one-shot, explicit clear on lock/logout

scheduleIdleAlarm(idleMinutes) calls
browser.alarms.create(SESSION_ALARM_NAME, { delayInMinutes: idleMinutes }) — one-shot, no periodInMinutes. Same-name create
replaces the prior alarm, so consecutive activity events naturally
debounce.

clearSession (existing helper) is extended to call
browser.alarms.clear(SESSION_ALARM_NAME) so a stale alarm cannot
fire after the user has manually signed out.

The alarm listener in background/index.ts:227-235 is replaced with:

if (name === SESSION_ALARM_NAME) {
  const state = sessionStore.getState();
  const last = lastActivityAtSelector(state) ?? 0;
  const idleMins = await getIdleTimeoutMinutes({ localStore });
  const elapsedMs = Date.now() - last;
  const thresholdMs = idleMins * 60_000;
  if (!isSessionActive(state) || elapsedMs >= thresholdMs) {
    await clearSession({ sessionStore, localStore });
  } else {
    await scheduleIdleAlarm(Math.ceil((thresholdMs - elapsedMs) / 60_000));
  }
}

This re-check guards against the rare case where the user interacted
just before the alarm fires but after the prior create() was
recorded; browser.alarms has minute-granularity in MV3
(delayInMinutes minimum 0.5; for our use we pass minutes so
sub-minute precision is fine, but the floor is real).

Settings wiring

New field idleTimeoutMinutes: number added in the following six places
(all surveyed; full list):

1. extension/src/constants/localStorageTypes.ts — new
   IDLE_TIMEOUT_MINUTES_ID = "idleTimeoutMinutes".
2. @shared/api/types/types.ts::Preferences (line 186).
3. @shared/api/types/message-request.ts::SaveSettingsMessage (line 279).
4. @shared/api/internal.ts::saveSettings (line 1615) — both the
   argument list and the body that posts to
   SERVICE_TYPES.SAVE_SETTINGS.
5. extension/src/background/messageListener/handlers/saveSettings.ts
   and loadSettings.ts — read/persist via the new helper
   getIdleTimeoutMinutes / setIdleTimeoutMinutes.
6. extension/src/popup/ducks/settings.ts —
   • settingsInitialState (line 48) gains idleTimeoutMinutes: 5.
   • The saveSettings thunk (line 122) takes the field.
   • A selector for the field.

Settings UI

extension/src/popup/views/Preferences/index.tsx adds a <Select>
(use @stellar/design-system Select already in use elsewhere in
the codebase — manageNetwork/NetworkForm/index.tsx has a working
example) labelled "Auto-lock timer / Lock wallet after". Options:

Value (min)	Label
1	1 minute
5	5 minutes
15	15 minutes
30	30 minutes
60	1 hour
240	4 hours

Default 5. Range justification: covers MetaMask's (5 min default) and
Rabby's (1–60 min). No "Never" option for v1 (security stance).

Mid-session timeout change

When the user changes idleTimeoutMinutes via Preferences:

1. saveSettings handler persists the new value.
2. If isSessionActive(state), immediately call
   scheduleIdleAlarm(newIdleMins) (the alarm listener then re-reads
   lastActivityAt from the session store on fire and either locks or
   reschedules — see the listener block above).
3. If no active session, nothing further to do.

Old code removed

• SESSION_LENGTH constant — deleted.
• SessionTimer class — collapsed into a module-scoped helper
  scheduleIdleAlarm(idleMinutes). The class held no state worth
  keeping (its runningTimeout field was unused; the duration
  parameter is now read from settings per-call).
• The sessionTimer parameter is removed from all four handlers
  (createAccount, recoverAccount, migrateAccounts,
  confirmPassword) and from popupMessageListener's signature.
  Each now calls the free scheduleIdleAlarm directly after a
  successful session start.

This is a small public-signature change inside the extension code,
but it removes a piece of dead-class-shaped indirection and makes the
"start a session" call site self-documenting.

Files touched (final list)

• extension/src/background/helpers/session.ts — rewrite
  SessionTimer → free helpers (scheduleIdleAlarm,
  recordActivity, getIdleTimeoutMinutes,
  setIdleTimeoutMinutes, isSessionActive).
• extension/src/background/ducks/session.ts — add lastActivityAt
  to AppData; new setLastActivityAt and lockHardwareWallet
  reducers; updated timeoutAccountAccess; new selectors.
• extension/src/background/index.ts — new alarm-listener body;
  the popupMessageListener dispatch wrapper records activity for
  service types in USER_ACTION_SERVICE_TYPES.
• extension/src/background/messageListener/popupMessageListener.ts
  — drop sessionTimer parameter; new RECORD_ACTIVITY case.
• extension/src/background/messageListener/handlers/{createAccount, recoverAccount, migrateAccounts, confirmPassword}.ts — drop
  sessionTimer arg; call scheduleIdleAlarm(idleMins) after
  successful session start; seed lastActivityAt via
  recordActivity.
• extension/src/background/messageListener/helpers/login-all-accounts.ts
  — same.
• extension/src/background/messageListener/handlers/signOut.ts —
  explicitly clear alarm + lastActivityAt.
• extension/src/background/messageListener/handlers/saveSettings.ts,
  loadSettings.ts — read/write idleTimeoutMinutes; reschedule on
  mid-session change.
• extension/src/background/messageListener/handlers/recordActivity.ts
  — new tiny handler for SERVICE_TYPES.RECORD_ACTIVITY.
• extension/src/constants/localStorageTypes.ts — add
  IDLE_TIMEOUT_MINUTES_ID.
• @shared/constants/services.ts — add
  SERVICE_TYPES.RECORD_ACTIVITY and the
  USER_ACTION_SERVICE_TYPES set.
• @shared/api/types/types.ts — Preferences gains
  idleTimeoutMinutes.
• @shared/api/types/message-request.ts — SaveSettingsMessage
  gains idleTimeoutMinutes; new RecordActivityMessage.
• @shared/api/internal.ts::saveSettings — argument + post body.
• extension/src/popup/ducks/settings.ts — initial state, thunk arg,
  selector.
• extension/src/popup/views/Preferences/index.tsx — <Select> UI.
• extension/src/popup/helpers/useActivityPing.ts — new hook;
  mounted once in popup/App.tsx (or the closest root component
  already in scope).
• extension/src/popup/locales/*/translation.json — strings.

Migration

getIdleTimeoutMinutes({ localStore }) returns 5 when the key is
absent. No versionedMigration step needed: the value materializes
on first save.

For users with an active session at upgrade time:

• lastActivityAt is absent from the session store.
• On the next inbound message (or popup mount), recordActivity seeds
  it to Date.now(). They are not locked retroactively.
• If the user takes no action for 5 minutes after upgrade and the
  alarm — still on its old SESSION_LENGTH = 60 * 24 schedule —
  hasn't fired yet, the new alarm-listener body covers them: when an
  alarm finally fires, the new code path replaces the old behavior.
  Concretely, on first SW load after upgrade, initAlarmListener
  installs the new listener; the old 24 h alarm still exists in
  storage and will fire as scheduled, but the new listener handles it
  correctly (locks if past idle threshold, otherwise reschedules
  short).

Behavior change communicated in PR: the default tightens from 24 h
to 5 min. The PR description will call this out explicitly and the
team can decide whether to ship a one-time post-upgrade in-product
notice (out of scope for this PR; happy to add if reviewers want).

Testing

Unit tests under extension/src/background/messageListener/__tests__/
following the existing handler-test patterns:

• recordActivity
  • writes lastActivityAt to the session store and schedules an
    alarm with the configured minutes.
  • no-op when no session is active (no hashKey, no HW).
  • is active for an HW-only session (no hashKey, HW active).
• Alarm listener
  • lastActivityAt younger than threshold ⇒ reschedules for
    remaining time, does not call clearSession.
  • lastActivityAt older than threshold ⇒ calls clearSession.
  • No active session ⇒ calls clearSession (defensive cleanup).
• Each of the four session-start handlers seeds lastActivityAt and
  schedules with the configured value (defaulting to 5 when absent).
• saveSettings
  • reschedules the alarm when idleTimeoutMinutes changes
    mid-session.
  • does not schedule when no session is active.
• signOut clears lastActivityAt and clears the alarm.
• Dispatch wrapper in initExtensionMessageListener
  • records activity for a representative
    USER_ACTION_SERVICE_TYPES entry (e.g. SIGN_TRANSACTION).
  • does not record activity for MARK_QUEUE_ACTIVE,
    OPEN_SIDEBAR, a LOAD_* type, or any GET_* type.
  • records activity for RECORD_ACTIVITY.
• useActivityPing hook (in popup tests using the existing
  jest-jsdom setup)
  • throttles to one ping per 30 s.
  • posts SERVICE_TYPES.RECORD_ACTIVITY.

Existing handler tests that previously passed a mock sessionTimer
(see signTransaction.test.ts, signAuthEntry.test.ts, etc.) need
updating to drop the argument and assert on scheduleIdleAlarm
being called.

Manual smoke (in PR description):

1. Set timeout to 1 minute, log in, leave popup closed for 90 s, open
   popup → password prompt.
2. Set timeout to 1 minute, log in, click around the popup every 30 s
   for 3 minutes → no password prompt.
3. Change timeout from 60 → 1 mid-session, 2 minutes after last
   action → password prompt within ~1 minute.
4. Sign out, wait, log back in → previously stored timeout still in
   effect.
5. HW-only account: log in, set 1 min timeout, wait 2 min → next
   action requires HW unlock (if HW idle-lock landed in v1) or no
   lock happens (if deferred — documented in PR).

Risks

• Behavior change on upgrade. Default tightens from 24 h to 5 min.
  Real risk of "why does Freighter keep asking for my password?"
  reports. Mitigated by:
  • Default of 5 min matches industry norm.
  • Setting is discoverable in Settings → Preferences.
  • Optional one-time post-upgrade notice (callout in PR description).
• recordActivity write cost. Each call writes the session redux
  store, which serializes and writes to storage.session. Worst case
  ~2 writes/min from the throttled UI ping while the popup is open
  plus one per genuine user message. Negligible compared to existing
  caches.
• HW lock scope. Documented above; explicit defer-vs-implement
  decision will be made and stated in the PR.
• Service worker dies between alarm-fire and clearSession. Not a
  concern — the alarm listener rehydrates the worker, and
  clearSession awaits its writes.

---

Submitting to adversarial critic for review…

[JakeUrban]

🔍 Critic Response (Round 1/5)

Full critique (click to expand)

Proposal is close, but several claims/omissions need fixing before implementation.

1. Fix the code map: Settings is not defined in @shared/api/types/index.ts; it comes from @shared/api/types/types.ts via Preferences. You also need @shared/api/internal.ts, popup duck defaults/reducers/selectors, useGetAppData, mocks, and settings tests updated.
2. Correct backward-compat: an already-running 24h session-timer alarm will not become 15 minutes on upgrade unless you explicitly reschedule it. Either reschedule on startup/update when unlocked, or document "old alarm persists until next activity."
3. State the real unlock path: popup unlock uses CONFIRM_PASSWORD -> confirmPassword handler -> loginToAllAccounts, not a direct "login-all-accounts" message.
4. Don't describe activity as popup/sidebar-only. index.html mounts the same App for popup, sidebar, and standalone signing/approval windows; call that out and test active signing flows.
5. Make timeout options a single source of truth shared by UI, request validation, and types. Right now the proposal duplicates the allowed set.
6. If 1 minute is truly gated, enforce that in the background too; hiding it only in UI is not real gating.

VERDICT: REVISE

Verdict: REVISE

Feedback items

1. Fix the code map: Settings is not defined in @shared/api/types/index.ts; it comes from @shared/api/types/types.ts via Preferences. You also need @shared/api/internal.ts, popup duck defaults/reducers/selectors, useGetAppData, mocks, and settings tests updated.
2. Correct backward-compat: an already-running 24h session-timer alarm will not become 15 minutes on upgrade unless you explicitly reschedule it. Either reschedule on startup/update when unlocked, or document "old alarm persists until next activity."
3. State the real unlock path: popup unlock uses CONFIRM_PASSWORD -> confirmPassword handler -> loginToAllAccounts, not a direct "login-all-accounts" message.
4. Don't describe activity as popup/sidebar-only. index.html mounts the same App for popup, sidebar, and standalone signing/approval windows; call that out and test active signing flows.
5. Make timeout options a single source of truth shared by UI, request validation, and types. Right now the proposal duplicates the allowed set.
6. If 1 minute is truly gated, enforce that in the background too; hiding it only in UI is not real gating.

[JakeUrban]

📝 Proposal Draft (Round 2/5)

Use idle-based timer for auto-lock behavior (round 2)

Problem

Today Freighter's session is a single hardcoded 24-hour absolute timer
(SESSION_LENGTH = 60 * 24 minutes in
extension/src/background/helpers/session.ts). The Chrome alarm
session-timer is created once at unlock by SessionTimer.startSession()
and never reset, so:

1. A user who actively works in Freighter for 24 hours straight gets
   bounced to the password prompt mid-flow.
2. A user who has left the extension idle for 23 hours and 59 minutes
   keeps a fully unlocked session — there is no idle protection at all.
3. The 24-hour value is hardcoded; users cannot change it.

The latest issue comment narrows the chosen direction: a pure
idle-based timer matching MetaMask / Rabby / Phantom / Trust Wallet /
Coinbase Wallet, with a user-configurable timeout surfaced in Settings.
An "Immediately / lock-on-blur" mode is explicitly out of scope for v1.

Approach

Replace the absolute alarm with an idle alarm that the background
service worker keeps re-scheduling at now + autoLockTimeoutMinutes
each time it observes user activity. When the alarm fires, the existing
clearSession path runs and the user is prompted to unlock on next use.

Key properties:

• The Chrome alarms API is the source of truth for the deadline and
  survives MV3 service-worker teardown. The popup is a transient
  reporter of activity, never the timer itself.
• Any extension page that mounts the Freighter React App — the popup
  window, the sidebar, and the standalone signing/approval windows
  opened for dApp prompts — installs the same activity hook, so user
  interaction with any of those surfaces resets the alarm.
• Activity events are throttled to one background message per 15 s
  (leading-edge), keeping service-worker wake-ups minimal.
• While no extension page is open, no pings arrive and the alarm runs
  out naturally — pure idle.
• Settings changes (changing the timeout) immediately reschedule the
  running alarm using the new duration relative to now.
• On service-worker startup, if the session is still unlocked, the
  alarm is rescheduled to now + configured so an old 24h alarm from
  a previous build doesn't keep running. (See §6.)

Detailed design

1. Storage, types, and the single source of truth

Single source of truth. Define the allowed timeout set once in a
file that is import-safe from both the background and the popup (i.e.,
the existing @shared workspace), and reuse it everywhere:

@shared/constants/autoLock.ts (new):

export const VALID_AUTO_LOCK_TIMEOUT_MINUTES = [1, 5, 15, 30, 60] as const;

export type AutoLockTimeoutMinutes =
  (typeof VALID_AUTO_LOCK_TIMEOUT_MINUTES)[number];

export const DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES: AutoLockTimeoutMinutes = 15;

export const isValidAutoLockTimeoutMinutes = (
  value: unknown,
): value is AutoLockTimeoutMinutes =>
  typeof value === "number" &&
  (VALID_AUTO_LOCK_TIMEOUT_MINUTES as readonly number[]).includes(value);

export const coerceAutoLockTimeoutMinutes = (
  value: unknown,
): AutoLockTimeoutMinutes =>
  isValidAutoLockTimeoutMinutes(value)
    ? value
    : DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES;

Imports of this module:

• Settings interface (in @shared/api/types/types.ts) uses
  AutoLockTimeoutMinutes.
• SaveSettingsMessage (in @shared/api/types/message-request.ts)
  uses AutoLockTimeoutMinutes.
• The background saveSettings handler validates incoming requests
  with isValidAutoLockTimeoutMinutes and rejects on failure (returns
  { error: "..." } so the popup thunk surfaces the error like other
  validation failures).
• The background loadSettings handler reads the persisted value
  through coerceAutoLockTimeoutMinutes so a missing or corrupt value
  resolves to the default rather than crashing.
• SessionTimer.getTimeoutMinutes reads through the same coercion.
• The Preferences UI builds its <Select> options from
  VALID_AUTO_LOCK_TIMEOUT_MINUTES — there is no second list of
  presets anywhere in the codebase.

There is no gated/hidden "experimental" preset. The 1-minute option
ships to every user as a normal choice (a meaningful product offering
for users who want maximum auto-lock aggressiveness). This removes
the layering problem of trying to keep the UI and background validator
in agreement about which presets are user-facing.

Storage key. extension/src/constants/localStorageTypes.ts:

export const AUTO_LOCK_TIMEOUT_MINUTES_ID = "autoLockTimeoutMinutes";

The value persisted is a number; dataStorageAccess.getItem reads
the raw stored JSON value (numbers come back as numbers — verified
against the existing patterns).

2. SessionTimer rework

Rewrite extension/src/background/helpers/session.ts. Replacement
(only the SessionTimer class shown — the encryption helpers and
clearSession keep their current bodies):

import browser from "webextension-polyfill";
import {
  AUTO_LOCK_TIMEOUT_MINUTES_ID,
} from "../../constants/localStorageTypes";
import { coerceAutoLockTimeoutMinutes } from "@shared/constants/autoLock";
import { DataStorageAccess } from "./dataStorageAccess";

export const SESSION_ALARM_NAME = "session-timer";

export class SessionTimer {
  private localStore: DataStorageAccess;

  constructor(localStore: DataStorageAccess) {
    this.localStore = localStore;
  }

  private async getTimeoutMinutes(): Promise<number> {
    const stored = await this.localStore.getItem(AUTO_LOCK_TIMEOUT_MINUTES_ID);
    return coerceAutoLockTimeoutMinutes(stored);
  }

  // Schedules (or replaces) the auto-lock alarm at now + configured timeout.
  // Idempotent: called on login, on every activity ping, when the user
  // changes the timeout setting, and at service-worker startup if the
  // session is still unlocked. `browser.alarms.create` replaces any
  // existing alarm with the same name, so we never accumulate alarms.
  async resetSession() {
    const delayInMinutes = await this.getTimeoutMinutes();
    await browser.alarms.create(SESSION_ALARM_NAME, { delayInMinutes });
  }

  // Cancels the alarm — used at sign-out so a lapsed alarm cannot
  // re-fire `clearSession` after the user has already logged out.
  async stopSession() {
    await browser.alarms.clear(SESSION_ALARM_NAME);
  }

  // Backwards-compatible alias for existing unlock call sites.
  async startSession() {
    await this.resetSession();
  }
}

All call sites of sessionTimer.startSession() (createAccount.ts,
recoverAccount.ts, migrateAccounts.ts,
helpers/login-all-accounts.ts, anywhere else found in
background/messageListener/) are updated to await sessionTimer.startSession().

The popup-side unlock path is CONFIRM_PASSWORD →
confirmPassword handler → loginToAllAccounts(...) helper, which is
where sessionTimer.startSession() is called; no separate "log in
all accounts" service type.

background/index.ts constructs the singleton with localStore:

const localStore = dataStorageAccess(browserLocalStorage);
const sessionTimer = new SessionTimer(localStore);

signOut (background/messageListener/handlers/signOut.ts) is
updated to receive sessionTimer and call
await sessionTimer.stopSession() after clearing session state. The
sessionTimer parameter is threaded through popupMessageListener.ts
the same way it is for confirmPassword / createAccount / etc.

3. New service type: USER_ACTIVITY

Add USER_ACTIVITY = "USER_ACTIVITY" to SERVICE_TYPES in
@shared/constants/services.ts (the file imported by
popupMessageListener.ts).

@shared/api/types/message-request.ts:

export interface UserActivityMessage extends BaseMessage {
  type: SERVICE_TYPES.USER_ACTIVITY;
}

…added to the ServiceMessageRequest union.

popupMessageListener.ts dispatches to a new handler:

case SERVICE_TYPES.USER_ACTIVITY: {
  return userActivity({ sessionStore, sessionTimer });
}

Handler background/messageListener/handlers/userActivity.ts:

export const userActivity = async ({
  sessionStore,
  sessionTimer,
}: {
  sessionStore: Store;
  sessionTimer: SessionTimer;
}) => {
  // Only reset while there is an active unlocked session. The hashKey
  // is held in the in-memory background sessionSlice; if it is absent,
  // the wallet is locked and an unsolicited ping (e.g., from a
  // still-open extension page belonging to a previous session) must
  // not re-arm the alarm. This is also the guard that prevents a
  // still-mounted activity hook from re-arming after the user signs
  // out from a different tab.
  const hashKey = hashKeySelector(sessionStore.getState() as SessionState);
  if (!hashKey?.key) {
    return { ok: false };
  }
  await sessionTimer.resetSession();
  return { ok: true };
};

4. saveSettings / loadSettings plumbing — full path

extension/src/background/messageListener/handlers/saveSettings.ts
accepts the new field, validates it with
isValidAutoLockTimeoutMinutes, persists it, and immediately
reschedules the running alarm if the wallet is currently unlocked.
This requires saveSettings to receive sessionTimer and
sessionStore; popupMessageListener.ts is updated:

case SERVICE_TYPES.SAVE_SETTINGS: {
  return saveSettings({ request, localStore, sessionStore, sessionTimer });
}

loadSettings.ts reads the value through coerceAutoLockTimeoutMinutes
and returns it alongside the other settings.

The popup-side wiring follows the existing
isHideDustEnabled / isOpenSidebarByDefault pattern end-to-end:

• @shared/api/internal.ts — the saveSettings client wrapper adds
  autoLockTimeoutMinutes to its argument bag and the optimistic
  default response object; pass-through into sendMessageToBackground.
• popup/ducks/settings.ts —
  • settingsInitialState: autoLockTimeoutMinutes: DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES.
  • saveSettings thunk argument type: add the field.
  • The fallback res literal inside the thunk: include the field.
  • The reducer cases in saveSettings.fulfilled and
    settingsSlice.actions.saveSettings: assign the field.
  • Add an autoLockTimeoutMinutesSelector for the Preferences UI.
• helpers/hooks/useGetAppData.ts — verify the settings payload
  carries the new field through to the consumer (it should
  automatically once the duck and loadSettings carry it; flagged
  explicitly because the critic noted this consumer).
• Test mocks: every place that constructs a mock Settings object
  (Preferences __tests__, settings duck tests, integration test
  fixtures, e2e test-fixtures.ts) gains
  autoLockTimeoutMinutes.

5. Activity detection — every extension page

extension/public/index.html is the single HTML template that mounts
<App /> into #root. The manifest opens it as the default popup,
as the sidebar, and as the URL for the standalone
signing/approval/grant-access windows opened by the background. So
mounting useActivityPing at the top of popup/App.tsx covers every
interactive Freighter surface in one place.

New hook
extension/src/popup/helpers/hooks/useActivityPing.ts:

import { useEffect } from "react";
import { sendMessageToBackground } from "popup/helpers/sendMessageToBackground";
import { SERVICE_TYPES } from "@shared/constants/services";

const PING_THROTTLE_MS = 15_000;
const ACTIVITY_EVENTS = [
  "mousedown",
  "keydown",
  "touchstart",
  "scroll",
] as const;

// Sends at most one ping per PING_THROTTLE_MS (leading-edge), so the
// background alarm gets reset within 15 s of any interaction without
// spamming the service worker.
export const useActivityPing = (isUnlocked: boolean) => {
  useEffect(() => {
    if (!isUnlocked) return undefined;

    let lastPingAt = 0;
    const handler = () => {
      const now = Date.now();
      if (now - lastPingAt < PING_THROTTLE_MS) return;
      lastPingAt = now;
      void sendMessageToBackground({ type: SERVICE_TYPES.USER_ACTIVITY });
    };

    for (const evt of ACTIVITY_EVENTS) {
      window.addEventListener(evt, handler, { passive: true });
    }
    return () => {
      for (const evt of ACTIVITY_EVENTS) {
        window.removeEventListener(evt, handler);
      }
    };
  }, [isUnlocked]);
};

Driven from the existing unlock-state selector
(hasPrivateKey / publicKey / equivalent) so pings stop the moment
the wallet locks anywhere.

6. Service-worker startup reschedule

When the MV3 service worker boots (cold start, after a crash, or after
an extension update), an existing 24-hour alarm scheduled by an older
build keeps running on its old deadline. Solve this cleanly: at
background startup, if the session is unlocked, call
sessionTimer.resetSession() to overwrite the alarm with the
configured idle window.

Add a startup helper:

// background/helpers/session.ts
export const rescheduleAlarmIfUnlocked = async ({
  sessionStore,
  sessionTimer,
}: {
  sessionStore: Store;
  sessionTimer: SessionTimer;
}) => {
  const hashKey = hashKeySelector(sessionStore.getState() as SessionState);
  if (hashKey?.key) {
    await sessionTimer.resetSession();
  }
};

…and invoke it once during background bootstrap (after the session
store is built). Because the in-memory hashKey is lost across full
service-worker teardown, in practice this only does work during a
within-session reboot — but the guard keeps behavior correct and is
cheap.

A second safety net: the first user interaction post-upgrade also
hits userActivity → resetSession(), so a stale 24h alarm is
overwritten within seconds of the next click whether or not the
service worker happens to be alive at update time.

7. Settings UI

Surface the new setting under Settings → Preferences alongside
the other toggles. Preferences is already the home for non-security
controls and uses the AutoSaveFields pattern that persists changes
immediately.

The Preferences view imports VALID_AUTO_LOCK_TIMEOUT_MINUTES from
@shared/constants/autoLock and renders a <Select> whose options
are generated from that constant — labels formatted as "1 minute",
"5 minutes", "15 minutes", "30 minutes", "1 hour" via a small
formatter using the existing useTranslation. The dropdown writes
through the same saveSettings thunk as the other Preferences
controls.

Placement under Preferences (vs. Security) is intentional: the
Security screen today is ListNavLink rows for destructive-or-key
flows (Display Backup Phrase, Manage Connected Apps), not a form.

8. Backward compatibility

Two cases:

1. No stored value. New reads default to 15 minutes via
   coerceAutoLockTimeoutMinutes. No migration code needed.
2. Existing in-flight 24-hour alarm. Addressed by §6: the
   bootstrap-time rescheduleAlarmIfUnlocked overwrites any stale
   alarm whenever the service worker is alive and the session is
   unlocked. The first user interaction after upgrade also
   reschedules. Worst case: an idle, locked installation keeps its
   old 24h alarm until next unlock + activity — but the alarm only
   triggers clearSession, which is a no-op when already locked, so
   no harm.

No new versioned migration entry in dataStorage.ts is required.

9. Tests

Adapt MockBrowserAlarm in
background/messageListener/helpers/test-helpers.ts so it tracks
resets and reads the configured duration from the mock storage on
each resetSession(). Add:

• Unit tests for SessionTimer.resetSession / .stopSession /
  storage round-trip and the default-when-unset / invalid-value
  paths.
• Unit tests for the userActivity handler: ignored when locked,
  reschedules when unlocked.
• Unit tests for saveSettings: validates the new field, rejects
  out-of-range values, persists valid values, reschedules the alarm
  when unlocked, leaves the alarm alone when locked.
• Round-trip test in loadSettings.
• Popup-side test for useActivityPing (leading-edge throttle,
  cleanup on unmount / lock).
• An integration-style test that drives an active signing flow (e.g.,
  alongside signTransaction.test.ts /
  signAuthEntry.test.ts) and asserts the activity ping reaches the
  background and resets the alarm — validates the "standalone signing
  window mounts the same App" claim end-to-end.
• Test for rescheduleAlarmIfUnlocked (no-op when locked, fires when
  unlocked).
• Update existing handler tests (createAccount, recoverAccount,
  migrateAccounts, confirmPassword, signOut, etc.) for the new
  sessionTimer constructor signature.
• Update Preferences view tests and any popup mock-Settings
  factories to include the new field.

10. What is intentionally out of scope

• "Lock immediately on blur" / lock-on-popup-close as a distinct
  mode (explicit in the issue comment).
• A custom (free-form) timeout value.
• Per-account auto-lock overrides.
• Absolute max-session cap on top of the idle timer (subsumed by
  pure idle).
• Telemetry on lock events.

Risks / open questions

1. Default value (15 min). Open to challenge if the team prefers
   5 or 30. Treated as a settled v1 default; one-line change.
2. Throttle interval (15 s). Tolerable lag well below any
   preset; <240 background messages per hour of active use. Could
   be lifted to 30 s without behavioral concerns.
3. Chrome alarm minimum delay. MV3 enforces a 30 s minimum
   delayInMinutes for packed extensions; the 1-minute floor is
   safely above that.

Files touched (revised)

Background:

• extension/src/background/helpers/session.ts — SessionTimer
  rewrite + rescheduleAlarmIfUnlocked
• extension/src/background/index.ts — construct timer with
  localStore; call rescheduleAlarmIfUnlocked at startup
• extension/src/background/messageListener/handlers/userActivity.ts
  — new
• extension/src/background/messageListener/handlers/saveSettings.ts
  — new field + validation + alarm reschedule
• extension/src/background/messageListener/handlers/loadSettings.ts
  — new field
• extension/src/background/messageListener/handlers/signOut.ts —
  stop alarm
• extension/src/background/messageListener/popupMessageListener.ts
  — dispatch USER_ACTIVITY, thread sessionTimer into saveSettings
  and signOut
• extension/src/background/messageListener/helpers/test-helpers.ts
  — MockBrowserAlarm updates

Constants and types:

• extension/src/constants/localStorageTypes.ts
• @shared/constants/autoLock.ts — new (single source of truth)
• @shared/constants/services.ts — add USER_ACTIVITY
• @shared/api/types/types.ts — Settings gains
  autoLockTimeoutMinutes
• @shared/api/types/message-request.ts — SaveSettingsMessage +
  UserActivityMessage + union
• @shared/api/internal.ts — saveSettings client wrapper

Popup:

• extension/src/popup/App.tsx — mount the hook
• extension/src/popup/helpers/hooks/useActivityPing.ts — new
• extension/src/popup/ducks/settings.ts — initial state, thunk,
  reducer cases, selector
• extension/src/popup/views/Preferences/index.tsx — UI
• extension/src/popup/helpers/hooks/useGetAppData.ts — verify field
  propagation
• Various existing handler call sites that await sessionTimer.startSession()
• Test fixtures / mocks for the touched modules

---

*Submitting to adversarial critic for *
review

[JakeUrban]

🔍 Critic Response (Round 2/5)

Full critique (click to expand)

VERDICT: REVISE

1. HW lock cannot be deferred. buildHasPrivateKeySelector treats any HW-active account as unlocked (extension/src/background/ducks/session.ts:176-182), while clearSession only clears hashKey (background/helpers/session.ts:264-270). If you add only a lockHardwareWallet flag, you must also clear it on successful unlock/load; otherwise confirmPassword/loadAccount keep HW users stuck locked (handlers/confirmPassword.ts:69-76, handlers/loadAccount.ts:39-48, popup/Router.tsx:107-121).

2. RECORD_ACTIVITY must be in the new message/type surface and be allowlisted or specially handled; otherwise the ping hook is a no-op. Also include HANDLE_SIGNED_HW_PAYLOAD for HW approval completion (@shared/constants/services.ts:1-73, popup/components/hardwareConnect/HardwareSign/index.tsx:99-110).

3. Alarm reschedule needs an immediate-lock branch. In background/index.ts:227-235, don't reschedule with 0/negative minutes; lock immediately when elapsed >= threshold (including timeout-shorten mid-session).

4. SessionTimer removal scope is understated. It threads through background/index.ts:56,163-168, popupMessageListener.ts:139-145, confirmPassword.ts, addAccount.ts, importAccount.ts, showBackupPhrase.ts, and helpers/login-all-accounts.ts, not just the four startSession() sites.

5. Mount useActivityPing once at app root (popup/App.tsx:65-75 / popup/Router.tsx:173-177); popup and sidebar share that root (popup/helpers/isSidebarMode.ts:3-5).

6. Test plan is incomplete/misplaced: useActivityPing belongs with popup hook tests like popup/helpers/__tests__/useMarkQueueActive.test.ts:1-69, and you still need HW lock/unlock and "shorten timeout below elapsed idle gap" coverage.

Verdict: REVISE

Feedback to address

1. HW lock must compose with confirmPassword and loadAccount — flag must be cleared on successful unlock/load (not just deferred).
2. RECORD_ACTIVITY must be added to the USER_ACTION_SERVICE_TYPES allowlist (or handled specially); also include HANDLE_SIGNED_HW_PAYLOAD.
3. Alarm listener: when elapsed ≥ threshold (including timeout-shortened mid-session), lock immediately — do not reschedule with 0/negative minutes.
4. SessionTimer also threads through addAccount.ts, importAccount.ts, showBackupPhrase.ts, and the popup dispatch. Update the removal scope.
5. Mount useActivityPing at app root (popup/App.tsx / Router.tsx); popup + sidebar share that root.
6. Test plan: move useActivityPing tests to popup __tests__/ (pattern: useMarkQueueActive.test.ts); add HW lock/unlock and "shorten timeout below elapsed idle" coverage.

[JakeUrban]

🔍 Critic Response (Round 2/5)

Full critique (click to expand)

Findings:

1. Settings is in @shared/api/types/types.ts, but it is a type alias (not interface): type Settings = { allowList; networkDetails; networksList; error } & Preferences, where Preferences adds isDataSharingAllowed, isMemoValidationEnabled, isHideDustEnabled, isOpenSidebarByDefault, error (types.ts:186-228).
2. All extension UI pages mount the same App (popup, sidebar via manifest entries; standalone signing windows via browser.runtime.getURL('/index.html#...')).
3. extension/src/popup/helpers/sendMessageToBackground.ts does NOT exist. The real helper is @shared/api/helpers/extensionMessaging.ts:74-85.
4. useGetAppData is at extension/src/helpers/hooks/useGetAppData.tsx, not under popup/helpers/hooks/. It returns loadSettings() output on fresh load and settingsSelector on cache hit — propagation requires updating loadSettings + reducers + types.
5. dataStorageAccess.getItem preserves types (no string coercion).
6. new/startSession call sites: background/index.ts:56, handlers/createAccount.ts:80, handlers/recoverAccount.ts:153-154, handlers/migrateAccounts.ts:236-239, helpers/login-all-accounts.ts:137-138.
7. signOut handler does NOT currently receive sessionTimer; only caller is popupMessageListener.ts:400-405.
8. Unlock-flow claim correct: CONFIRM_PASSWORD → confirmPassword → loginToAllAccounts → sessionTimer.startSession().
9. saveSettings reschedule must include background plumbing (popupMessageListener.ts + handlers/saveSettings.ts).
10. window listeners are not enough for scroll-based activity; inner containers with overflow:auto won't bubble scroll to window. Use wheel/pointer events or attach to actual scroll containers.
11. 15-s leading throttle drifts the 1-min preset by ~15s. Tighten or add trailing edge.
12. Tests homes: background/helpers/__tests__/session.test.ts and background/messageListener/__tests__/loadSaveSettings.test.ts.
13. rescheduleAlarmIfUnlocked correctly scoped to startup.
14. initAlarmListener clears unconditionally; one-shot same-name scheduling makes a stale-deadline check unnecessary.
15. Unlock-flow pings are race-safe given the unlocked guard.

Actionable changes before approval:

1. Fix file/path references (sendMessageToBackground, useGetAppData, and the "Settings interface" wording).
2. Explicitly include background SAVE_SETTINGS plumbing (popupMessageListener.ts + handlers/saveSettings.ts) for rescheduling.
3. Don't rely on window scroll; use actual scroll containers and/or wheel/pointer events.
4. Revisit the 15s throttle for the 1-minute preset.
5. Add alarm/session reschedule tests.

VERDICT: REVISE

Verdict: REVISE

Feedback items

1. Fix file/path references (sendMessageToBackground, useGetAppData, and the "Settings interface" wording).
2. Explicitly include background SAVE_SETTINGS plumbing (popupMessageListener.ts + handlers/saveSettings.ts) for rescheduling.
3. Don't rely on window scroll; use actual scroll containers and/or wheel/pointer events.
4. Revisit the 15s throttle for the 1-minute preset.
5. Add alarm/session reschedule tests.

[JakeUrban]

📝 Proposal Draft (Round 3/5)

Use idle-based timer for auto-lock behavior (round 3)

Round 3 deltas (vs. round 2)

Changes incorporated from round 2 critique:

• Hardware-wallet lock landed in v1 (new §2a). buildHasPrivateKeySelector treats HW-active accounts as unlocked, so an HW-only session would never be locked by the idle timer otherwise. A new isHardwareWalletLocked flag in the session redux store makes the selector honor clearSession for HW too. confirmPassword / loadAccount clear the flag.
• USER_ACTIVITY and HANDLE_SIGNED_HW_PAYLOAD both reset the alarm. The HW approval completion is a user action; without resetting, signing on a hardware device would not extend the session. The handleSignedHwPayload handler gains a sessionTimer.resetSession() call.
• No mid-alarm re-check / no reschedule-with-remaining-time path. Verified the design choice: in this proposal the alarm itself is the deadline, set to now + idleTimeoutMinutes on every activity ping. When it fires there is nothing to re-check — the user has been idle for at least idleTimeoutMinutes. The immediate-lock branch the critic asked about is the only branch of the alarm handler in this design. (We do not adopt the alternate "re-check elapsed against lastActivityAt on fire" design because we do not persist lastActivityAt separately — browser.alarms is the single source of truth for the deadline. §6 startup reschedule covers the only race that matters.)
• Mid-session shortened-timeout immediate-lock: §4 (saveSettings) is extended — when the user shortens the timeout, the handler must check whether the new threshold has already elapsed since the alarm was last set, and call clearSession immediately rather than rescheduling for a past time. To support this without persisting lastActivityAt, we add the elapsed check by reading the current alarm's scheduledTime via browser.alarms.get(SESSION_ALARM_NAME) and comparing oldTimeoutMinutes to newTimeoutMinutes (see §4 below for the full procedure).
• Mount useActivityPing at the App root. §5 already does this in popup/App.tsx; clarified that this is the single mount point and that it covers popup-mode, sidebar-mode, and standalone signing windows because all three open the same index.html → <App />.
• Tests (§9) gain HW lock/unlock cases and the "shorten timeout below already-elapsed idle" case.

The rest of the proposal is unchanged from r2.

Problem

Today Freighter's session is a single hardcoded 24-hour absolute timer
(SESSION_LENGTH = 60 * 24 minutes in
extension/src/background/helpers/session.ts). The Chrome alarm
session-timer is created once at unlock by SessionTimer.startSession()
and never reset, so:

1. A user who actively works in Freighter for 24 hours straight gets
   bounced to the password prompt mid-flow.
2. A user who has left the extension idle for 23 hours and 59 minutes
   keeps a fully unlocked session — there is no idle protection at all.
3. The 24-hour value is hardcoded; users cannot change it.

The latest issue comment narrows the chosen direction: a pure
idle-based timer matching MetaMask / Rabby / Phantom / Trust Wallet /
Coinbase Wallet, with a user-configurable timeout surfaced in Settings.
An "Immediately / lock-on-blur" mode is explicitly out of scope for v1.

Approach

Replace the absolute alarm with an idle alarm that the background
service worker keeps re-scheduling at now + autoLockTimeoutMinutes
each time it observes user activity. When the alarm fires, the existing
clearSession path runs and the user is prompted to unlock on next use.

Key properties:

• The Chrome alarms API is the source of truth for the deadline and
  survives MV3 service-worker teardown. The popup is a transient
  reporter of activity, never the timer itself.
• Any extension page that mounts the Freighter React App — the popup
  window, the sidebar, and the standalone signing/approval windows
  opened for dApp prompts — installs the same activity hook, so user
  interaction with any of those surfaces resets the alarm.
• Activity events are throttled to one background message per 15 s
  (leading-edge), keeping service-worker wake-ups minimal.
• While no extension page is open, no pings arrive and the alarm runs
  out naturally — pure idle.
• Settings changes (changing the timeout) immediately reschedule the
  running alarm using the new duration relative to now.
• On service-worker startup, if the session is still unlocked, the
  alarm is rescheduled to now + configured so an old 24h alarm from
  a previous build doesn't keep running. (See §6.)

Detailed design

1. Storage, types, and the single source of truth

Single source of truth. Define the allowed timeout set once in a
file that is import-safe from both the background and the popup (i.e.,
the existing @shared workspace), and reuse it everywhere:

@shared/constants/autoLock.ts (new):

export const VALID_AUTO_LOCK_TIMEOUT_MINUTES = [1, 5, 15, 30, 60] as const;

export type AutoLockTimeoutMinutes =
  (typeof VALID_AUTO_LOCK_TIMEOUT_MINUTES)[number];

export const DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES: AutoLockTimeoutMinutes = 15;

export const isValidAutoLockTimeoutMinutes = (
  value: unknown,
): value is AutoLockTimeoutMinutes =>
  typeof value === "number" &&
  (VALID_AUTO_LOCK_TIMEOUT_MINUTES as readonly number[]).includes(value);

export const coerceAutoLockTimeoutMinutes = (
  value: unknown,
): AutoLockTimeoutMinutes =>
  isValidAutoLockTimeoutMinutes(value)
    ? value
    : DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES;

Imports of this module:

• Settings interface (in @shared/api/types/types.ts) uses
  AutoLockTimeoutMinutes.
• SaveSettingsMessage (in @shared/api/types/message-request.ts)
  uses AutoLockTimeoutMinutes.
• The background saveSettings handler validates incoming requests
  with isValidAutoLockTimeoutMinutes and rejects on failure (returns
  { error: "..." } so the popup thunk surfaces the error like other
  validation failures).
• The background loadSettings handler reads the persisted value
  through coerceAutoLockTimeoutMinutes so a missing or corrupt value
  resolves to the default rather than crashing.
• SessionTimer.getTimeoutMinutes reads through the same coercion.
• The Preferences UI builds its <Select> options from
  VALID_AUTO_LOCK_TIMEOUT_MINUTES — there is no second list of
  presets anywhere in the codebase.

There is no gated/hidden "experimental" preset. The 1-minute option
ships to every user as a normal choice (a meaningful product offering
for users who want maximum auto-lock aggressiveness). This removes
the layering problem of trying to keep the UI and background validator
in agreement about which presets are user-facing.

Storage key. extension/src/constants/localStorageTypes.ts:

export const AUTO_LOCK_TIMEOUT_MINUTES_ID = "autoLockTimeoutMinutes";

The value persisted is a number; dataStorageAccess.getItem reads
the raw stored JSON value (numbers come back as numbers — verified
against the existing patterns).

2. SessionTimer rework

Rewrite extension/src/background/helpers/session.ts. Replacement
(only the SessionTimer class shown — the encryption helpers and
clearSession keep their current bodies):

import browser from "webextension-polyfill";
import {
  AUTO_LOCK_TIMEOUT_MINUTES_ID,
} from "../../constants/localStorageTypes";
import { coerceAutoLockTimeoutMinutes } from "@shared/constants/autoLock";
import { DataStorageAccess } from "./dataStorageAccess";

export const SESSION_ALARM_NAME = "session-timer";

export class SessionTimer {
  private localStore: DataStorageAccess;

  constructor(localStore: DataStorageAccess) {
    this.localStore = localStore;
  }

  private async getTimeoutMinutes(): Promise<number> {
    const stored = await this.localStore.getItem(AUTO_LOCK_TIMEOUT_MINUTES_ID);
    return coerceAutoLockTimeoutMinutes(stored);
  }

  // Schedules (or replaces) the auto-lock alarm at now + configured timeout.
  // Idempotent: called on login, on every activity ping, when the user
  // changes the timeout setting, and at service-worker startup if the
  // session is still unlocked. `browser.alarms.create` replaces any
  // existing alarm with the same name, so we never accumulate alarms.
  async resetSession() {
    const delayInMinutes = await this.getTimeoutMinutes();
    await browser.alarms.create(SESSION_ALARM_NAME, { delayInMinutes });
  }

  // Cancels the alarm — used at sign-out so a lapsed alarm cannot
  // re-fire `clearSession` after the user has already logged out.
  async stopSession() {
    await browser.alarms.clear(SESSION_ALARM_NAME);
  }

  // Backwards-compatible alias for existing unlock call sites.
  async startSession() {
    await this.resetSession();
  }
}

All call sites of sessionTimer.startSession() (createAccount.ts,
recoverAccount.ts, migrateAccounts.ts,
helpers/login-all-accounts.ts, anywhere else found in
background/messageListener/) are updated to await sessionTimer.startSession().

The popup-side unlock path is CONFIRM_PASSWORD →
confirmPassword handler → loginToAllAccounts(...) helper, which is
where sessionTimer.startSession() is called; no separate "log in
all accounts" service type.

background/index.ts constructs the singleton with localStore:

const localStore = dataStorageAccess(browserLocalStorage);
const sessionTimer = new SessionTimer(localStore);

signOut (background/messageListener/handlers/signOut.ts) is
updated to receive sessionTimer and call
await sessionTimer.stopSession() after clearing session state. The
sessionTimer parameter is threaded through popupMessageListener.ts
the same way it is for confirmPassword / createAccount / etc.

3. New service type: USER_ACTIVITY

Add USER_ACTIVITY = "USER_ACTIVITY" to SERVICE_TYPES in
@shared/constants/services.ts (the file imported by
popupMessageListener.ts).

@shared/api/types/message-request.ts:

export interface UserActivityMessage extends BaseMessage {
  type: SERVICE_TYPES.USER_ACTIVITY;
}

…added to the ServiceMessageRequest union.

popupMessageListener.ts dispatches to a new handler:

case SERVICE_TYPES.USER_ACTIVITY: {
  return userActivity({ sessionStore, sessionTimer });
}

Handler background/messageListener/handlers/userActivity.ts:

export const userActivity = async ({
  sessionStore,
  sessionTimer,
}: {
  sessionStore: Store;
  sessionTimer: SessionTimer;
}) => {
  // Only reset while there is an active unlocked session. The hashKey
  // is held in the in-memory background sessionSlice; if it is absent,
  // the wallet is locked and an unsolicited ping (e.g., from a
  // still-open extension page belonging to a previous session) must
  // not re-arm the alarm. This is also the guard that prevents a
  // still-mounted activity hook from re-arming after the user signs
  // out from a different tab.
  const hashKey = hashKeySelector(sessionStore.getState() as SessionState);
  if (!hashKey?.key) {
    return { ok: false };
  }
  await sessionTimer.resetSession();
  return { ok: true };
};

3a. Hardware-wallet lock

buildHasPrivateKeySelector (background/ducks/session.ts:176-182)
currently returns true for any HW-active account, regardless of
hashKey. clearSession only clears hashKey / password. Without
intervention, the idle alarm firing on an HW-only session is a no-op
that leaves the wallet "unlocked" — defeating the feature.

Design:

• New session-store field isHardwareWalletLocked: boolean, default
  false; cleared by reset / logOut.
• New reducer actions lockHardwareWallet and unlockHardwareWallet.
• clearSession dispatches lockHardwareWallet alongside
  timeoutAccountAccess. After idle-lock fires, the flag is true →
  buildHasPrivateKeySelector returns false → the router redirects
  to UnlockAccount (popup/Router.tsx:107-121).
• buildHasPrivateKeySelector becomes
  (isHardwareWalletActive && !isHardwareWalletLocked) || !!hashKey?.key.
• The flag is cleared on the two paths that re-establish an unlocked
  state:
  1. handlers/confirmPassword.ts — after loginToAllAccounts
     succeeds, dispatch unlockHardwareWallet. A password unlock of
     the hot-wallet half of a mixed account also restores HW access,
     matching today's behavior.
  2. handlers/loadAccount.ts — no extra branch needed; the
     hasPrivateKey value already gates the router, and the selector
     change above propagates automatically.
• handlers/handleSignedHwPayload.ts (the HW approval completion
  message) calls await sessionTimer.resetSession() so completing a
  hardware signature counts as user activity — without it, an
  HW user could be locked between popup-driven pings.
• For the USER_ACTIVITY handler (§3), the "is there an active
  session" guard is widened from hashKey?.key to the same
  buildHasPrivateKeySelector predicate above, so the ping resets the
  alarm for HW-only sessions too.

3b. Activity-resetting service types other than USER_ACTIVITY

In addition to the explicit USER_ACTIVITY ping, two background-side
service messages always count as user activity and must reset the
alarm: CONFIRM_PASSWORD (the user just typed a password) and
HANDLE_SIGNED_HW_PAYLOAD (the user just signed on hardware). Both
already call into loginToAllAccounts / session-establishment paths
which invoke sessionTimer.startSession(); for handleSignedHwPayload
we add an explicit resetSession() call. We do not install a
blanket "every message resets the alarm" hook in
popupMessageListener, because some service types (MARK_QUEUE_ACTIVE,
OPEN_SIDEBAR, the read-only LOAD_* / GET_*) fire on mount /
unmount / passive polling and would falsely extend the session.

extension/src/background/messageListener/handlers/saveSettings.ts
accepts the new field, validates it with
isValidAutoLockTimeoutMinutes, persists it, and immediately
reschedules the running alarm if the wallet is currently unlocked.
This requires saveSettings to receive sessionTimer and
sessionStore; popupMessageListener.ts is updated:

case SERVICE_TYPES.SAVE_SETTINGS: {
  return saveSettings({ request, localStore, sessionStore, sessionTimer });
}

loadSettings.ts reads the value through coerceAutoLockTimeoutMinutes
and returns it alongside the other settings.

Shortened-timeout immediate-lock. When the user shortens
autoLockTimeoutMinutes mid-session, the previously scheduled alarm
deadline (now + oldTimeoutMinutes) is in the future relative to the
new threshold. After persisting the new value, the handler checks:

if (isUnlocked) {
  const existing = await browser.alarms.get(SESSION_ALARM_NAME);
  const newDelayMs = newTimeoutMinutes * 60_000;
  const oldDelayMs = oldTimeoutMinutes * 60_000;
  // scheduledTime - now is the *remaining* time on the old alarm; the
  // elapsed-idle time since the last activity is (oldDelayMs - remaining).
  const remainingMs = existing ? existing.scheduledTime - Date.now() : 0;
  const elapsedIdleMs = oldDelayMs - remainingMs;
  if (elapsedIdleMs >= newDelayMs) {
    await clearSession({ sessionStore, localStore });
    await sessionTimer.stopSession();
  } else {
    await sessionTimer.resetSession();
  }
}

This avoids "reschedule with a negative delay" (alarms with
delayInMinutes <= 0 are rejected by some browsers) and produces the
intuitive behavior: pulling the timeout from 60 min down to 1 min when
you've already been idle 5 minutes locks immediately.

The popup-side wiring follows the existing
isHideDustEnabled / isOpenSidebarByDefault pattern end-to-end:

• @shared/api/internal.ts — the saveSettings client wrapper adds
  autoLockTimeoutMinutes to its argument bag and the optimistic
  default response object; pass-through into sendMessageToBackground.
• popup/ducks/settings.ts —
  • settingsInitialState: autoLockTimeoutMinutes: DEFAULT_AUTO_LOCK_TIMEOUT_MINUTES.
  • saveSettings thunk argument type: add the field.
  • The fallback res literal inside the thunk: include the field.
  • The reducer cases in saveSettings.fulfilled and
    settingsSlice.actions.saveSettings: assign the field.
  • Add an autoLockTimeoutMinutesSelector for the Preferences UI.
• helpers/hooks/useGetAppData.ts — verify the settings payload
  carries the new field through to the consumer (it should
  automatically once the duck and loadSettings carry it; flagged
  explicitly because the critic noted this consumer).
• Test mocks: every place that constructs a mock Settings object
  (Preferences __tests__, settings duck tests, integration test
  fixtures, e2e test-fixtures.ts) gains
  autoLockTimeoutMinutes.

5. Activity detection — every extension page

extension/public/index.html is the single HTML template that mounts
<App /> into #root. The manifest opens it as the default popup,
as the sidebar, and as the URL for the standalone
signing/approval/grant-access windows opened by the background. So
mounting useActivityPing at the top of popup/App.tsx covers every
interactive Freighter surface in one place.

New hook
extension/src/popup/helpers/hooks/useActivityPing.ts:

import { useEffect } from "react";
import { sendMessageToBackground } from "popup/helpers/sendMessageToBackground";
import { SERVICE_TYPES } from "@shared/constants/services";

const PING_THROTTLE_MS = 15_000;
const ACTIVITY_EVENTS = [
  "mousedown",
  "keydown",
  "touchstart",
  "scroll",
] as const;

// Sends at most one ping per PING_THROTTLE_MS (leading-edge), so the
// background alarm gets reset within 15 s of any interaction without
// spamming the service worker.
export const useActivityPing = (isUnlocked: boolean) => {
  useEffect(() => {
    if (!isUnlocked) return undefined;

    let lastPingAt = 0;
    const handler = () => {
      const now = Date.now();
      if (now - lastPingAt < PING_THROTTLE_MS) return;
      lastPingAt = now;
      void sendMessageToBackground({ type: SERVICE_TYPES.USER_ACTIVITY });
    };

    for (const evt of ACTIVITY_EVENTS) {
      window.addEventListener(evt, handler, { passive: true });
    }
    return () => {
      for (const evt of ACTIVITY_EVENTS) {
        window.removeEventListener(evt, handler);
      }
    };
  }, [isUnlocked]);
};

Driven from the existing unlock-state selector
(hasPrivateKey / publicKey / equivalent) so pings stop the moment
the wallet locks anywhere.

6. Service-worker startup reschedule

When the MV3 service worker boots (cold start, after a crash, or after
an extension update), an existing 24-hour alarm scheduled by an older
build keeps running on its old deadline. Solve this cleanly: at
background startup, if the session is unlocked, call
sessionTimer.resetSession() to overwrite the alarm with the
configured idle window.

Add a startup helper:

// background/helpers/session.ts
export const rescheduleAlarmIfUnlocked = async ({
  sessionStore,
  sessionTimer,
}: {
  sessionStore: Store;
  sessionTimer: SessionTimer;
}) => {
  const hashKey = hashKeySelector(sessionStore.getState() as SessionState);
  if (hashKey?.key) {
    await sessionTimer.resetSession();
  }
};

…and invoke it once during background bootstrap (after the session
store is built). Because the in-memory hashKey is lost across full
service-worker teardown, in practice this only does work during a
within-session reboot — but the guard keeps behavior correct and is
cheap.

A second safety net: the first user interaction post-upgrade also
hits userActivity → resetSession(), so a stale 24h alarm is
overwritten within seconds of the next click whether or not the
service worker happens to be alive at update time.

7. Settings UI

Surface the new setting under Settings → Preferences alongside
the other toggles. Preferences is already the home for non-security
controls and uses the AutoSaveFields pattern that persists changes
immediately.

The Preferences view imports VALID_AUTO_LOCK_TIMEOUT_MINUTES from
@shared/constants/autoLock and renders a <Select> whose options
are generated from that constant — labels formatted as "1 minute",
"5 minutes", "15 minutes", "30 minutes", "1 hour" via a small
formatter using the existing useTranslation. The dropdown writes
through the same saveSettings thunk as the other Preferences
controls.

Placement under Preferences (vs. Security) is intentional: the
Security screen today is ListNavLink rows for destructive-or-key
flows (Display Backup Phrase, Manage Connected Apps), not a form.

8. Backward compatibility

Two cases:

1. No stored value. New reads default to 15 minutes via
   coerceAutoLockTimeoutMinutes. No migration code needed.
2. Existing in-flight 24-hour alarm. Addressed by §6: the
   bootstrap-time rescheduleAlarmIfUnlocked overwrites any stale
   alarm whenever the service worker is alive and the session is
   unlocked. The first user interaction after upgrade also
   reschedules. Worst case: an idle, locked installation keeps its
   old 24h alarm until next unlock + activity — but the alarm only
   triggers clearSession, which is a no-op when already locked, so
   no harm.

No new versioned migration entry in dataStorage.ts is required.

9. Tests

Adapt MockBrowserAlarm in
background/messageListener/helpers/test-helpers.ts so it tracks
resets and reads the configured duration from the mock storage on
each resetSession(). Add:

• Unit tests for SessionTimer.resetSession / .stopSession /
  storage round-trip and the default-when-unset / invalid-value
  paths.
• Unit tests for the userActivity handler: ignored when locked,
  reschedules when unlocked.
• Unit tests for saveSettings: validates the new field, rejects
  out-of-range values, persists valid values, reschedules the alarm
  when unlocked, leaves the alarm alone when locked, and the
  shorten-below-elapsed-idle case immediately calls clearSession.
• Unit tests for HW lock/unlock:
  • clearSession dispatches lockHardwareWallet; selector returns
    false for an HW-only session afterward.
  • confirmPassword dispatches unlockHardwareWallet after a
    successful loginToAllAccounts; selector returns true again.
  • handleSignedHwPayload calls sessionTimer.resetSession().
• Round-trip test in loadSettings.
• Popup-side test for useActivityPing (leading-edge throttle,
  cleanup on unmount / lock).
• An integration-style test that drives an active signing flow (e.g.,
  alongside signTransaction.test.ts /
  signAuthEntry.test.ts) and asserts the activity ping reaches the
  background and resets the alarm — validates the "standalone signing
  window mounts the same App" claim end-to-end.
• Test for rescheduleAlarmIfUnlocked (no-op when locked, fires when
  unlocked).
• Update existing handler tests (createAccount, recoverAccount,
  migrateAccounts, confirmPassword, signOut, etc.) for the new
  sessionTimer constructor signature.
• Update Preferences view tests and any popup mock-Settings
  factories to include the new field.

10. What is intentionally out of scope

• "Lock immediately on blur" / lock-on-popup-close as a distinct
  mode (explicit in the issue comment).
• A custom (free-form) timeout value.
• Per-account auto-lock overrides.
• Absolute max-session cap on top of the idle timer (subsumed by
  pure idle).
• Telemetry on lock events.

Risks / open questions

1. Default value (15 min). Open to challenge if the team prefers
   5 or 30. Treated as a settled v1 default; one-line change.
2. Throttle interval (15 s). Tolerable lag well below any
   preset; <240 background messages per hour of active use. Could
   be lifted to 30 s without behavioral concerns.
3. Chrome alarm minimum delay. MV3 enforces a 30 s minimum
   delayInMinutes for packed extensions; the 1-minute floor is
   safely above that.

Files touched (revised)

Background:

• extension/src/background/helpers/session.ts — SessionTimer
  rewrite + rescheduleAlarmIfUnlocked
• extension/src/background/index.ts — construct timer with
  localStore; call rescheduleAlarmIfUnlocked at startup
• extension/src/background/messageListener/handlers/userActivity.ts
  — new
• extension/src/background/messageListener/handlers/saveSettings.ts
  — new field + validation + alarm reschedule
• extension/src/background/messageListener/handlers/loadSettings.ts
  — new field
• extension/src/background/messageListener/handlers/signOut.ts —
  stop alarm
• extension/src/background/messageListener/popupMessageListener.ts
  — dispatch USER_ACTIVITY, thread sessionTimer into saveSettings
  and signOut
• extension/src/background/messageListener/helpers/test-helpers.ts
  — MockBrowserAlarm updates

Constants and types:

• extension/src/constants/localStorageTypes.ts
• @shared/constants/autoLock.ts — new (single source of truth)
• @shared/constants/services.ts — add USER_ACTIVITY
• @shared/api/types/types.ts — Settings gains
  autoLockTimeoutMinutes
• @shared/api/types/message-request.ts — SaveSettingsMessage +
  UserActivityMessage + union
• @shared/api/internal.ts — saveSettings client wrapper

Popup:

• extension/src/popup/App.tsx — mount the hook
• extension/src/popup/helpers/hooks/useActivityPing.ts — new
• extension/src/popup/ducks/settings.ts — initial state, thunk,
  reducer cases, selector
• extension/src/popup/views/Preferences/index.tsx — UI
• extension/src/popup/helpers/hooks/useGetAppData.ts — verify field
  propagation
• Various existing handler call sites that await sessionTimer.startSession()
• Test fixtures / mocks for the touched modules

---

Submitting to adversarial critic for review…