@johnhenry/wsh 0.17.0 → 0.18.0

package/src/file-transfer.mjs

@@ -3,38 +3,36 @@
  *
  * Uploads and downloads delegate to the underlying client's upload()/
  * download() (FileChunk control messages over a 'file'-kind channel —
- * see client.mjs). list() is a separate helper that runs `ls -la` over
- * a plain exec channel.
+ * see client.mjs). list() (wsh #59) delegates to the client's fileList(),
+ * which sends a structured FileOp{op:"list"} and reads the typed
+ * FileResult.entries -- the same wire path upload/download already use
+ * for moving bytes, now extended to directory listings.
+ *
+ * Before wsh #59, list() ran `ls -la` over a plain exec channel and
+ * parsed the text output client-side -- a private, JS-only convention
+ * the Rust client had no equivalent of at all (see wsh #58/#59, and the
+ * FileEntry nested type in spec/wsh-v1.yaml this now shares with Rust).
  */
 
-import { MSG, open, CHANNEL_KIND } from './messages.mjs';
-import { waitForControlMessage } from './control-listener.mjs';
-
 /** Default timeout for waiting on control messages (30 seconds). */
 const RESPONSE_TIMEOUT_MS = 30_000;
 
 export class WshFileTransfer {
   /**
    * @type {{
-   *   upload: function, download: function,
-   *   sendControl: function, openStream: function, onControl: function,
+   *   upload: function, download: function, fileList: function,
    * }}
    */
   #client;
 
   /**
-   * @param {object} client - A WshClient (or any object exposing upload()/
-   *   download() with the same signatures — those are used directly for
-   *   upload/download). list() additionally needs, for the underlying exec
-   *   channel it runs `ls -la` over:
-   *   - sendControl(msg): send a control message
-   *   - openStream(): open a new bidirectional stream
-   *   - onControl: settable callback for incoming control messages
-   *     (or a method to add a listener — see _waitForMessage)
-   *
-   *   Only `list()` needs the control-channel members, so they are checked
-   *   there rather than here: uploading and downloading through a client
-   *   that has `upload()`/`download()` and nothing else stays valid.
+   * @param {object} client - A WshClient (or any object exposing the same
+   *   methods used below). `upload()`/`download()` are used directly for
+   *   file transfer; `list()` uses `fileList()` (the structured
+   *   FileOp/FileResult request-response helper already on WshClient).
+   *   Each method checks for the members it specifically needs, so a
+   *   client exposing only `upload()`/`download()` (and nothing else)
+   *   stays valid for those two calls.
    */
   constructor(client) {
     if (!client) throw new Error('WshFileTransfer requires a client');
@@ -97,156 +95,47 @@ export class WshFileTransfer {
   }
 
   /**
-   * List files at a remote path by executing `ls -la` via the client.
+   * List files at a remote path over the structured file channel (wsh #59):
+   * sends `FileOp{op:"list"}` via the client's `fileList()` and reads the
+   * typed `FileResult.entries` -- the same `FileEntry` shape
+   * `crates/wsh-core`'s Rust client is generated from, so a symlink can't
+   * be reported as a plain file here and correctly here-and-there.
    *
-   * This uses a standard exec channel rather than the file transfer protocol,
-   * parsing the output of `ls -la` into structured entries.
+   * A refusal (unimplemented op, unauthorized fs capability, no such
+   * directory) throws -- it is never coerced into an empty array, so a
+   * caller can't mistake "refused" for "empty directory" (wsh #58).
    *
    * @param {string} remotePath - Directory path on the remote host
-   * @returns {Promise<Array<{ name: string, size: number, modified: string, type: string }>>}
+   * @param {object} [opts]
+   * @param {number} [opts.timeout] - Timeout in ms for the server response
+   * @returns {Promise<Array<{
+   *   name: string, size: number, modified: Date,
+   *   type: 'file'|'directory'|'symlink'|'device'|'pipe'|'socket',
+   *   symlinkTarget?: string,
+   * }>>}
    */
-  async list(remotePath) {
+  async list(remotePath, { timeout = RESPONSE_TIMEOUT_MS } = {}) {
     if (!remotePath || typeof remotePath !== 'string') {
       throw new Error('remotePath is required');
     }
-    if (typeof this.#client.sendControl !== 'function' || typeof this.#client.openStream !== 'function') {
+    if (typeof this.#client.fileList !== 'function') {
       throw new TypeError(
-        'WshFileTransfer.list() requires a client exposing sendControl() and openStream() (e.g. WshClient)'
+        'WshFileTransfer.list() requires a client exposing fileList() (e.g. WshClient)'
       );
     }
 
-    // Use an exec channel to run ls
-    const openMsg = open({
-      kind: CHANNEL_KIND.EXEC,
-      command: `ls -la ${this._shellEscape(remotePath)}`,
-    });
-
-    await this.#client.sendControl(openMsg);
-
-    const response = await this._waitForMessage(
-      (msg) => msg.type === MSG.OPEN_OK || msg.type === MSG.OPEN_FAIL,
-      RESPONSE_TIMEOUT_MS
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`List failed: ${response.reason || 'unknown reason'}`);
-    }
-
-    // Read the output stream
-    const stream = await this.#client.openStream();
-    const reader = stream.readable.getReader();
-    const chunks = [];
-
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-
-    const output = new TextDecoder().decode(this._concatChunks(chunks));
-    return this._parseLsOutput(output);
-  }
-
-  // ── Internal helpers ──────────────────────────────────────────────
-
-  /**
-   * Wait for a control message matching a predicate.
-   *
-   * Temporarily hooks into the client's control message flow and resolves
-   * when a matching message arrives (or rejects on timeout).
-   *
-   * @param {function(object): boolean} predicate
-   * @param {number} timeoutMs
-   * @returns {Promise<object>}
-   */
-  _waitForMessage(predicate, timeoutMs) {
-    return waitForControlMessage(this.#client, predicate, timeoutMs, 'File transfer response');
-  }
-
-  /**
-   * Concatenate an array of Uint8Arrays into one.
-   *
-   * @param {Uint8Array[]} chunks
-   * @param {number} [totalLength] - Pre-computed total, avoids re-summing
-   * @returns {Uint8Array}
-   */
-  _concatChunks(chunks, totalLength) {
-    if (chunks.length === 0) return new Uint8Array(0);
-    if (chunks.length === 1) return chunks[0];
-
-    const total = totalLength ?? chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return result;
-  }
-
-  /**
-   * Parse the output of `ls -la` into structured entries.
-   *
-   * Expected format per line:
-   *   drwxr-xr-x 2 user group  4096 Jan 15 12:00 dirname
-   *   -rw-r--r-- 1 user group 12345 Jan 15 12:00 filename.txt
-   *
-   * @param {string} output
-   * @returns {Array<{ name: string, size: number, modified: string, type: string }>}
-   */
-  _parseLsOutput(output) {
-    const lines = output.split('\n').filter((l) => l.trim());
-    const entries = [];
-
-    for (const line of lines) {
-      // Skip the "total" header line
-      if (line.startsWith('total ')) continue;
-
-      // ls -la columns: perms links owner group size month day time name
-      const parts = line.split(/\s+/);
-      if (parts.length < 9) continue;
-
-      const perms = parts[0];
-      const size = parseInt(parts[4], 10) || 0;
-      const month = parts[5];
-      const day = parts[6];
-      const time = parts[7];
-      // Name may contain spaces — rejoin everything from column 8 onward
-      const name = parts.slice(8).join(' ');
-
-      // Skip . and .. entries
-      if (name === '.' || name === '..') continue;
+    const result = await this.#client.fileList(remotePath, timeout);
 
-      // Determine type from permission string first character
-      let type = 'file';
-      if (perms.startsWith('d')) type = 'directory';
-      else if (perms.startsWith('l')) type = 'symlink';
-      else if (perms.startsWith('c') || perms.startsWith('b')) type = 'device';
-      else if (perms.startsWith('p')) type = 'pipe';
-      else if (perms.startsWith('s')) type = 'socket';
-
-      entries.push({
-        name,
-        size,
-        modified: `${month} ${day} ${time}`,
-        type,
-      });
+    if (!result.success) {
+      throw new Error(result.error_message || `List failed: refused for ${remotePath}`);
     }
 
-    return entries;
-  }
-
-  /**
-   * Basic shell escaping for a path argument.
-   * @param {string} str
-   * @returns {string}
-   */
-  _shellEscape(str) {
-    // Wrap in single quotes, escaping any embedded single quotes
-    return "'" + str.replace(/'/g, "'\\''") + "'";
+    return (result.entries || []).map((entry) => ({
+      name: entry.name,
+      size: entry.size,
+      modified: new Date(entry.modified * 1000),
+      type: entry.type,
+      ...(entry.symlink_target !== undefined ? { symlinkTarget: entry.symlink_target } : {}),
+    }));
   }
 }

package/src/index.d.ts

@@ -238,6 +238,13 @@ export const PROTOCOL_VERSION: 'wsh-v1';
  */
 export const MCP_CALL_ID_FEATURE: 'mcp-call-id';
 
+/**
+ * ServerHello feature: the host discovers a client-opened exec data stream
+ * without help (the transport announces it), so the client writes no
+ * one-byte primer against it.
+ */
+export const STREAM_ANNOUNCE_FEATURE: 'stream-announce';
+
 /** A wsh protocol control message (all messages have a numeric `type`). */
 export interface WshMessage {
   type: number;
@@ -778,6 +785,14 @@ export function fileResult(opts?: {
   channelId?: number;
   success?: boolean;
   metadata?: Record<string, unknown>;
+  /** wsh #59: typed directory entries for a "list" op (see WshFileListEntry-shaped wire fields). */
+  entries?: Array<{
+    name: string;
+    size: number;
+    modified: number;
+    type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+    symlink_target?: string;
+  }>;
   errorMessage?: string;
 }): WshMessage;
 
@@ -789,6 +804,18 @@ export function fileChunk(opts?: {
   totalSize?: number;
 }): WshMessage;
 
+/** wsh #59: install a public key into the remote's authorized_keys (see WshClient.addAuthorizedKey). */
+export function authorizedKeyAdd(opts?: {
+  publicKey?: Uint8Array;
+  comment?: string;
+}): WshMessage;
+
+export function authorizedKeyResult(opts?: {
+  success?: boolean;
+  added?: boolean;
+  errorMessage?: string;
+}): WshMessage;
+
 export function policyEval(opts?: {
   requestId?: string;
   action?: string;
@@ -875,15 +902,19 @@ export function exportPrivateKeyPKCS8(privateKey: CryptoKey): Promise<Uint8Array
 export function importPrivateKeyPKCS8(pkcs8: Uint8Array, extractable?: boolean): Promise<CryptoKey>;
 
 /**
- * Sign data with an Ed25519 private key.
+ * Sign data with an Ed25519 private key. Positional order mirrors WebCrypto
+ * (`sign(privateKey, message)`) and is the canonical form across wsh, raijin
+ * and browsermesh.
  * @returns 64-byte signature
  */
-export function sign(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+export function sign(privateKey: CryptoKey, message: Uint8Array): Promise<Uint8Array>;
 
 /**
- * Verify an Ed25519 signature.
+ * Verify an Ed25519 signature. Positional order mirrors WebCrypto
+ * (`verify(publicKey, signature, message)`) and is the canonical form across
+ * wsh, raijin and browsermesh.
  */
-export function verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+export function verify(publicKey: CryptoKey, signature: Uint8Array, message: Uint8Array): Promise<boolean>;
 
 /** Options binding extra context into the auth transcript. */
 export interface WshTranscriptOptions {
@@ -1541,6 +1572,13 @@ export interface WshOpenSessionOptions {
   rows?: number;
   env?: Record<string, string>;
   timeout?: number;
+  /**
+   * Stream-mode `exec` only (default `true`): write the one-byte "primer"
+   * that older hosts need to discover the client-opened data stream. Skipped
+   * automatically against a host advertising `stream-announce`; `false`
+   * never sends it.
+   */
+  primer?: boolean;
 }
 
 /** Options for WshClient.attachSession(). */
@@ -1591,6 +1629,8 @@ export interface WshExecOptions {
   keyPair?: CryptoKeyPair;
   password?: string;
   timeout?: number;
+  /** See {@link WshOpenSessionOptions.primer}. */
+  primer?: boolean;
 }
 
 /** Result from WshClient.exec(). */
@@ -1649,6 +1689,28 @@ export interface WshE2EResult {
   hybrid: boolean;
 }
 
+/**
+ * Raw `FileResult` response to a structured file-channel operation
+ * (`WshClient.fileList`/`fileRemove`/etc.), as received off the wire --
+ * wire field names (snake_case), not the camelCase shape the `fileResult()`
+ * message constructor takes as input. `entries` is only populated for a
+ * `"list"` op; `error_message` is only present on failure.
+ */
+export interface WshFileOperationResult {
+  type: number;
+  channel_id: number;
+  success: boolean;
+  metadata: Record<string, unknown>;
+  entries: Array<{
+    name: string;
+    size: number;
+    modified: number;
+    type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+    symlink_target?: string;
+  }>;
+  error_message?: string;
+}
+
 /**
  * WshClient -- manages a wsh connection, authentication, and multiple sessions.
  *
@@ -1764,6 +1826,36 @@ export class WshClient {
    */
   revokeSessionAccess(sessionId: string, principal: string, reason?: string): Promise<void>;
 
+  /**
+   * List a remote directory over the structured file channel (`FileOp`
+   * op `"list"`). Prefer `WshFileTransfer.list()` for a typed
+   * `WshFileListEntry[]` result (with `modified` as a `Date`) -- this is
+   * the raw wire-shaped `FileResult` response `fileOperation()` waits on.
+   */
+  fileList(path: string, timeout?: number): Promise<WshFileOperationResult>;
+
+  /**
+   * Remove a remote file or directory (`FileOp` op `"remove"`). Refused
+   * today by every `wsh-server` release ("not yet implemented" -- see
+   * README's file-op parity table); wired here so clients built against
+   * this SDK don't need to wait on the server to type-check against it.
+   */
+  fileRemove(path: string, timeout?: number): Promise<WshFileOperationResult>;
+
+  /**
+   * Install a raw 32-byte Ed25519 public key into the remote host's
+   * `~/.wsh/authorized_keys` (wsh #59's `AuthorizedKeyAdd` protocol
+   * message -- replaces `wsh copy-id`'s previous CLI-only shell-command
+   * approach with something every implementation, including this one,
+   * can call directly). Idempotent: installing an already-present key
+   * resolves `added: false` rather than duplicating the line or erroring.
+   */
+  addAuthorizedKey(
+    publicKeyRaw: Uint8Array,
+    comment?: string,
+    timeout?: number,
+  ): Promise<{ added: boolean }>;
+
   /**
    * Gracefully disconnect: close all sessions and the transport.
    */
@@ -1993,6 +2085,48 @@ export class WshKeyStore {
   restore(passphrase: string): Promise<WshRestoreResult>;
 }
 
+// ============================================================================
+// known-hosts.mjs -- WshKnownHosts (wsh #59)
+// ============================================================================
+
+/** Minimal storage interface `WshKnownHosts` needs -- `localStorage` already satisfies it. */
+export interface WshKnownHostsStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** Result of verifying a host's fingerprint against the stored record. */
+export interface WshHostVerifyResult {
+  status: 'known' | 'unknown' | 'changed';
+  /** Previously stored fingerprint, present only when status === 'changed'. */
+  expected?: string;
+}
+
+/**
+ * WshKnownHosts -- trust-on-first-use (TOFU) host-identity store, mirroring
+ * Rust's `KnownHosts`/`HostStatus` (`crates/wsh-client/src/known_hosts.rs`).
+ * Pins `ServerHello.host_fingerprint` (spec/wsh-v1.yaml, wsh #59) -- no
+ * `wsh-server` release populates that field yet, so this has nothing
+ * authoritative to verify against for any real server today. See the
+ * class doc comment in `known-hosts.mjs` for the full reasoning.
+ */
+export class WshKnownHosts {
+  constructor(opts?: { storage?: WshKnownHostsStorage; storageKey?: string });
+
+  /** Verify a host's fingerprint against the stored record. */
+  verifyHost(host: string, fingerprint: string): WshHostVerifyResult;
+
+  /** Add or update a host's fingerprint. */
+  addHost(host: string, fingerprint: string): void;
+
+  /** Remove a host entry. Returns true if an entry was removed. */
+  removeHost(host: string): boolean;
+
+  /** List all known hosts and their fingerprints. */
+  list(): Array<{ host: string; fingerprint: string }>;
+}
+
 // ============================================================================
 // file-transfer.mjs -- WshFileTransfer
 // ============================================================================
@@ -2015,12 +2149,21 @@ export interface WshFileUploadResult {
   bytesTransferred: number;
 }
 
-/** File listing entry. */
+/**
+ * File listing entry (wsh #59: generated from spec/wsh-v1.yaml's
+ * `FileEntry` nested type -- the same shape `crates/wsh-core`'s Rust
+ * `FileEntry` struct is generated from, so a directory entry can no longer
+ * describe a symlink as a plain file in one implementation and not the
+ * other). `modified` is converted from the wire's Unix epoch seconds into
+ * a `Date` for JS ergonomics. `symlinkTarget` is only present when
+ * `type === 'symlink'`.
+ */
 export interface WshFileListEntry {
   name: string;
   size: number;
-  modified: string;
+  modified: Date;
   type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+  symlinkTarget?: string;
 }
 
 /**

package/src/index.mjs

@@ -35,6 +35,7 @@ export {
   nodeAnnounce, nodeRedirect,
   sessionGrant, sessionRevoke,
   fileOp, fileResult, fileChunk,
+  authorizedKeyAdd, authorizedKeyResult,
   policyEval, policyResult, policyUpdate,
   terminalConfig,
   msgName, isValidMessage,
@@ -72,11 +73,14 @@ export {
 // Session + Client
 export { WshSession } from './session.mjs';
 export { WshVirtualSessionBackend, normalizeSessionData } from './virtual-session.mjs';
-export { WshClient, MCP_CALL_ID_FEATURE } from './client.mjs';
+export { WshClient, MCP_CALL_ID_FEATURE, STREAM_ANNOUNCE_FEATURE } from './client.mjs';
 
 // Key storage
 export { WshKeyStore } from './keystore.mjs';
 
+// Host identity (TOFU) -- wsh #59
+export { WshKnownHosts } from './known-hosts.mjs';
+
 // File transfer
 export { WshFileTransfer } from './file-transfer.mjs';
 

package/src/known-hosts.mjs

@@ -0,0 +1,139 @@
+/**
+ * WshKnownHosts — trust-on-first-use (TOFU) host-identity store for the
+ * browser SDK (wsh #59).
+ *
+ * ## Why this exists, and why it is not yet load-bearing
+ *
+ * wsh #59 asked for a decision on host identity: TOFU *policy* (when to
+ * prompt, how long to trust) is legitimately per-implementation, but the
+ * *host identity record* -- what a fingerprint covers, how it is computed,
+ * what counts as "the same host" -- must not be invented twice. This class
+ * mirrors Rust's `KnownHosts`/`HostStatus`
+ * (`crates/wsh-client/src/known_hosts.rs`) in shape and semantics --
+ * `verifyHost`/`addHost`/`removeHost`/`list`, keyed by a host label,
+ * storing one fingerprint per host -- so the browser gets the same
+ * mechanism rather than a second, differently-shaped answer arrived at
+ * later under pressure.
+ *
+ * What it pins is `ServerHello.host_fingerprint` (spec/wsh-v1.yaml, added
+ * by this same change): the server's own persistent Ed25519 host-identity
+ * key, SHA-256-fingerprinted the same way `fingerprint()` in `auth.mjs`
+ * already fingerprints user/peer keys. That field is new spec surface,
+ * not new server behavior -- no `wsh-server` release populates it yet.
+ * Minting and persisting a server host keypair is a separate,
+ * security-sensitive feature this change does not implement (see the
+ * wsh #59 PR description for the full reasoning). Until a server
+ * populates it, `verifyHost()` has nothing authoritative to check for any
+ * real deployment -- exactly the same degraded state Rust's own
+ * `verify_host_key` is in today when it falls back to `fingerprints[0]`
+ * (an authorized *client* key, not a host identity -- see that fallback's
+ * comment in `client.rs`). This store does not paper over that; a caller
+ * that gets `'unknown'` back from every real server today is seeing the
+ * honest state of host verification in this protocol version, not a bug
+ * in this class.
+ *
+ * The README's `serverCertificateHashes` pinning
+ * (see "Pinning a Self-Signed Certificate") is a different mechanism: it
+ * pins a certificate supplied *per connection*, decided by the caller in
+ * advance -- it is not a persisted record of what a host presented last
+ * time, so it does not already solve TOFU. `WshKnownHosts` is the
+ * missing persisted-record half.
+ *
+ * ## Storage
+ *
+ * Pluggable (defaults to `localStorage` when available, else an
+ * in-memory `Map` that does not survive a page reload) since "persist
+ * trust across sessions" needs a browser storage API this package has
+ * never assumed before. Pass `{ storage }` with a `getItem`/`setItem`/
+ * `removeItem` interface (the `Storage` interface `localStorage`
+ * already implements) to use IndexedDB-via-adapter, `sessionStorage`,
+ * or anything else.
+ */
+
+const STORAGE_KEY = 'wsh:known-hosts:v1';
+
+/** In-memory fallback storage, used when no persistent storage is available or injected. */
+class MemoryStorage {
+  #map = new Map();
+  getItem(key) { return this.#map.has(key) ? this.#map.get(key) : null; }
+  setItem(key, value) { this.#map.set(key, value); }
+  removeItem(key) { this.#map.delete(key); }
+}
+
+function defaultStorage() {
+  if (typeof localStorage !== 'undefined' && localStorage) return localStorage;
+  return new MemoryStorage();
+}
+
+export class WshKnownHosts {
+  #storage;
+  #storageKey;
+
+  /**
+   * @param {object} [opts]
+   * @param {{getItem: function, setItem: function, removeItem: function}} [opts.storage]
+   *   Storage backend (defaults to `localStorage` if present, else an
+   *   in-memory `Map` scoped to this instance).
+   * @param {string} [opts.storageKey] - Override the storage key (useful
+   *   for isolating multiple instances/tests under one storage backend).
+   */
+  constructor({ storage, storageKey = STORAGE_KEY } = {}) {
+    this.#storage = storage || defaultStorage();
+    this.#storageKey = storageKey;
+  }
+
+  /**
+   * Verify a host's fingerprint against the stored record.
+   *
+   * @param {string} host - Host label (e.g. "example.com:4422")
+   * @param {string} fingerprint - Hex SHA-256 fingerprint to check
+   * @returns {{ status: 'known' | 'unknown' | 'changed', expected?: string }}
+   */
+  verifyHost(host, fingerprint) {
+    const entries = this.#load();
+    if (!(host in entries)) {
+      return { status: 'unknown' };
+    }
+    if (entries[host] === fingerprint) {
+      return { status: 'known' };
+    }
+    return { status: 'changed', expected: entries[host] };
+  }
+
+  /** Add or update a host's fingerprint. */
+  addHost(host, fingerprint) {
+    const entries = this.#load();
+    entries[host] = fingerprint;
+    this.#save(entries);
+  }
+
+  /** Remove a host entry. Returns true if an entry was removed. */
+  removeHost(host) {
+    const entries = this.#load();
+    if (!(host in entries)) return false;
+    delete entries[host];
+    this.#save(entries);
+    return true;
+  }
+
+  /** List all known hosts and their fingerprints. */
+  list() {
+    const entries = this.#load();
+    return Object.entries(entries).map(([host, fingerprint]) => ({ host, fingerprint }));
+  }
+
+  #load() {
+    const raw = this.#storage.getItem(this.#storageKey);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  #save(entries) {
+    this.#storage.setItem(this.#storageKey, JSON.stringify(entries));
+  }
+}