selfstore 1.8.29 → 1.8.31

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "selfstore",
-	"version": "1.8.29",
+	"version": "1.8.31",
 	"description": "Local-first storage for browser apps: an IndexedDB working copy, portable encrypted ZIP backups (AES-256-GCM over Argon2id), durable homes (disk, Google Drive, WebDAV) and a serverless multi-device merge.",
 	"type": "module",
 	"license": "MIT",
@@ -126,7 +126,8 @@
 		"idb": "^8.0.3"
 	},
 	"overrides": {
-		"esbuild": "^0.28.1"
+		"esbuild": "^0.28.1",
+		"zod": "4.6.7"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
@@ -137,13 +138,13 @@
 		"eslint-plugin-sonarjs": "^4.2.0",
 		"fake-indexeddb": "^6.2.5",
 		"globals": "^17.7.0",
-		"happy-dom": "^21.0.1",
+		"happy-dom": "^21.0.4",
 		"jscpd": "^5.0.12",
 		"knip": "^6.29.0",
 		"lint-staged": "^17.2.0",
 		"prettier": "^3.9.6",
 		"simple-git-hooks": "^2.13.1",
-		"tsup": "^8.3.5",
+		"tsup": "^9.0.0",
 		"typescript": "^6.0.3",
 		"typescript-eslint": "^8.65.0",
 		"vitest": "^5.0.0",

package/dist/chunk-2TIRUEXR.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/persistence/targets/desktop.ts","../src/persistence/targets/file.ts"],"names":["connect","openExisting","fromSession"],"mappings":"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","file":"chunk-2TIRUEXR.js","sourcesContent":["/**\n * Disk-file backup target for a desktop shell (Tauri, and anything exposing the\n * same filesystem and dialog calls).\n *\n * The browser's File System Access API is Chromium-only and, inside a native\n * webview, usually absent altogether: on macOS and Linux the shell embeds\n * WebKit, which never shipped it. So the file destination would silently\n * degrade to download-on-demand in the one place where writing a real file is\n * easiest. This target restores it.\n *\n * What changes against the browser target is what gets persisted: a PATH, not a\n * handle. A path survives a restart, an app update and a backup of the profile\n * directory, and it needs no permission to be re-granted at each launch. The\n * store therefore reconnects silently where the browser asks for a click.\n *\n * The shell's own calls are INJECTED, never imported: this library keeps three\n * runtime dependencies, and a desktop toolkit is not going to be the fourth for\n * the sake of the web build that will never call it.\n */\n\nimport type { BackupTarget } from '../target';\nimport type { KV } from '../cache';\nimport { SelfstoreError } from '../../selfstore';\n\nconst PATH_KEY = 'desktopFilePath';\n\n/** Filter shape shared by the save and open dialogs. */\nexport interface DesktopDialogFilter {\n\tname: string;\n\textensions: string[];\n}\n\n/**\n * The filesystem and dialog calls this target needs, shaped so a host can pass\n * its shell's functions straight through with no adapter of its own.\n *\n * With Tauri v2 the whole wiring is the two plugin imports:\n *\n * ```ts\n * import { readFile, writeFile, stat, exists } from '@tauri-apps/plugin-fs';\n * import { save, open } from '@tauri-apps/plugin-dialog';\n * import { useDesktopFiles } from 'selfstore';\n *\n * useDesktopFiles({ readFile, writeFile, stat, exists, save, open });\n * ```\n *\n * Do that once at start-up and every `file` destination in this library runs on\n * a real path. Nothing else in a host changes.\n */\nexport interface DesktopFileBridge {\n\treadFile(path: string): Promise<Uint8Array>;\n\twriteFile(path: string, data: Uint8Array): Promise<void>;\n\t/** File metadata. Only `mtime` is read, and a shell that cannot report it\n\t *  may leave it absent: the store then falls back to its own bookkeeping. */\n\tstat(path: string): Promise<{ mtime?: Date | number | null } | null>;\n\texists(path: string): Promise<boolean>;\n\t/** Save dialog. Resolves to the chosen path, or null when cancelled. */\n\tsave(options: { defaultPath?: string; filters?: DesktopDialogFilter[] }): Promise<string | null>;\n\t/** Open dialog. Resolves to the chosen path, or null when cancelled. The\n\t *  array form is accepted so a host can pass its shell's function unchanged. */\n\topen(options: {\n\t\tmultiple?: boolean;\n\t\tfilters?: DesktopDialogFilter[];\n\t}): Promise<string | string[] | null>;\n}\n\nlet bridge: DesktopFileBridge | null = null;\n\n/**\n * Register the desktop shell's filesystem and dialog calls. Call once at\n * start-up, before opening the store. Passing null unregisters, which is what a\n * test wants between cases.\n */\nexport function useDesktopFiles(b: DesktopFileBridge | null): void {\n\tbridge = b;\n}\n\n/** True once a shell has been registered: the file destination then writes a\n *  real path instead of asking the browser for a handle. */\nexport function hasDesktopFiles(): boolean {\n\treturn bridge != null;\n}\n\nconst FILTERS: DesktopDialogFilter[] = [{ name: 'Backup', extensions: ['zip'] }];\n\n/** Last path segment, for the label. Windows and POSIX separators both, since\n *  the same build runs on either. */\nfunction baseName(path: string): string {\n\tconst parts = path.split(/[\\\\/]/);\n\treturn parts[parts.length - 1] || path;\n}\n\n/** Epoch milliseconds as the version marker, or null when the shell cannot\n *  tell. Never throws: a marker that cannot be read is \"cannot tell\", and the\n *  store treats that as no information rather than as a fault. */\nasync function markerOf(b: DesktopFileBridge, path: string): Promise<string | null> {\n\ttry {\n\t\tconst info = await b.stat(path);\n\t\tconst mtime = info?.mtime;\n\t\tif (mtime == null) return null;\n\t\tconst ms = mtime instanceof Date ? mtime.getTime() : Number(mtime);\n\t\treturn Number.isFinite(ms) ? String(ms) : null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n/** Only the first path, whichever shape the shell's open dialog returns. */\nfunction firstPath(picked: string | string[] | null): string | null {\n\tif (picked == null) return null;\n\treturn Array.isArray(picked) ? (picked[0] ?? null) : picked;\n}\n\nfunction fromPath(path: string, b: DesktopFileBridge, kv: KV): BackupTarget {\n\t// reconnect() can move the destination to another file, so the path the\n\t// closure writes to has to be able to change under the object the store\n\t// already holds.\n\tlet current = path;\n\treturn {\n\t\tkind: 'file',\n\t\tget label(): string {\n\t\t\treturn baseName(current);\n\t\t},\n\t\tasync save(blob: Blob): Promise<string | null> {\n\t\t\ttry {\n\t\t\t\tawait b.writeFile(current, new Uint8Array(await blob.arrayBuffer()));\n\t\t\t} catch (e) {\n\t\t\t\t// No AuthExpiredError here on purpose. A desktop write fails because\n\t\t\t\t// the disk is full, the volume is unplugged or the file is locked by\n\t\t\t\t// another program - all transient, all resolved without the user\n\t\t\t\t// re-granting anything. Raising the reconnect gate would ask them to\n\t\t\t\t// re-pick a file that is exactly where they left it.\n\t\t\t\tthrow new SelfstoreError('TARGET_WRITE_FAILED', `File write failed: ${String(e)}`);\n\t\t\t}\n\t\t\treturn markerOf(b, current);\n\t\t},\n\t\tasync load(): Promise<Blob | null> {\n\t\t\ttry {\n\t\t\t\tconst bytes = await b.readFile(current);\n\t\t\t\treturn new Blob([new Uint8Array(bytes)]);\n\t\t\t} catch {\n\t\t\t\t// A path chosen through the save dialog names a file that does not\n\t\t\t\t// exist yet. \"No backup there\" is the honest answer, not a failure.\n\t\t\t\treturn null;\n\t\t\t}\n\t\t},\n\t\tasync stat(): Promise<string | null> {\n\t\t\treturn markerOf(b, current);\n\t\t},\n\t\tasync isReady(): Promise<boolean> {\n\t\t\t// A desktop write needs no user gesture and no grant that can lapse, so\n\t\t\t// the answer is yes even when the file is not there yet: refusing until\n\t\t\t// it exists would deadlock the very first save, which is what creates\n\t\t\t// it. A volume that went away surfaces when save() throws, and that\n\t\t\t// reads as transient - which is what an unplugged drive is.\n\t\t\treturn true;\n\t\t},\n\t\tasync reconnect(): Promise<boolean> {\n\t\t\tconst picked = await b.save({ defaultPath: current, filters: FILTERS });\n\t\t\tif (!picked) return false;\n\t\t\tcurrent = picked;\n\t\t\tawait kv.set(PATH_KEY, picked);\n\t\t\treturn true;\n\t\t},\n\t\tasync disconnect(): Promise<void> {\n\t\t\tawait kv.del(PATH_KEY);\n\t\t}\n\t};\n}\n\nexport interface DesktopConnectOptions {\n\t/** Where the chosen path is persisted across launches. */\n\tkv: KV;\n\t/** Suggested name for the backup file. */\n\tfileName: string;\n}\n\n/** Ask for a file to write the backup to, and remember it. Null when the user\n *  cancelled, or when no shell is registered. */\nexport async function connect(opts: DesktopConnectOptions): Promise<BackupTarget | null> {\n\tif (!bridge) return null;\n\tconst picked = await bridge.save({ defaultPath: opts.fileName, filters: FILTERS });\n\tif (!picked) return null;\n\tawait opts.kv.set(PATH_KEY, picked);\n\treturn fromPath(picked, bridge, opts.kv);\n}\n\n/** Ask for an EXISTING backup file and adopt it as the destination; the connect\n *  journey then reads it like any backup. Null when cancelled. */\nexport async function openExisting(opts: { kv: KV }): Promise<BackupTarget | null> {\n\tif (!bridge) return null;\n\tconst picked = firstPath(await bridge.open({ multiple: false, filters: FILTERS }));\n\tif (!picked) return null;\n\tawait opts.kv.set(PATH_KEY, picked);\n\treturn fromPath(picked, bridge, opts.kv);\n}\n\n/** Rebuild the target from the path kept in a past launch, or null. Unlike the\n *  browser handle this needs no permission check, so a desktop app reopens on\n *  its file with nothing asked of the user. */\nexport async function fromSession(opts: { kv: KV }): Promise<BackupTarget | null> {\n\tif (!bridge) return null;\n\tconst path = await opts.kv.get<string>(PATH_KEY);\n\treturn path ? fromPath(path, bridge, opts.kv) : null;\n}\n","/**\n * Disk-file backup target (Chromium only). The user picks a backup file once via\n * the File System Access API; the store then re-writes that real file on every\n * change. The handle is persisted through the injected KV, so the target stays\n * storage-agnostic. The browser re-confirms write permission once per session\n * (a one-click reconnect).\n */\n\nimport type { BackupTarget } from '../target';\nimport type { KV } from '../cache';\nimport { AuthExpiredError, SelfstoreError, type SelfstoreErrorCode } from '../../selfstore';\nimport * as desktop from './desktop';\n\nconst HANDLE_KEY = 'fileHandle';\n\ninterface FileHandle {\n\tname: string;\n\tcreateWritable(): Promise<{ write(data: Blob): Promise<void>; close(): Promise<void> }>;\n\tgetFile(): Promise<File>;\n\tqueryPermission(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;\n\trequestPermission(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;\n}\n\ninterface PickerWindow {\n\tshowSaveFilePicker?: (o: {\n\t\tsuggestedName?: string;\n\t\ttypes?: { description: string; accept: Record<string, string[]> }[];\n\t}) => Promise<FileHandle>;\n\tshowOpenFilePicker?: (o: {\n\t\tmultiple?: boolean;\n\t\ttypes?: { description: string; accept: Record<string, string[]> }[];\n\t}) => Promise<FileHandle[]>;\n}\n\nexport interface FileConnectOptions {\n\t/** Where the picked file handle is persisted across sessions. */\n\tkv: KV;\n\t/** Suggested name for the backup file the user creates/picks. */\n\tfileName: string;\n}\n\n/** Set once a picker that EXISTS has refused to open. Presence is not\n *  capability: some browsers ship the methods and throw on call unless a flag\n *  is turned on, so a host that trusts `'showSaveFilePicker' in window` offers\n *  a file mode that can never work, and the button looks broken. The attempt is\n *  the only honest probe there is - it costs one click, once. */\nlet refused = false;\n\n/** Was the call made inside a live user gesture?\n *\n * A picker REQUIRES transient activation, and a call made without one throws\n * the same DOMException as a browser that ships the picker and refuses it. Read\n * as a refusal, one mistimed call condemns the file mode for the whole session:\n * the host then falls back to manual downloads on a Chrome that was never\n * asked properly. A throw only teaches us about the browser when the browser\n * was actually allowed to answer. Undefined support (no userActivation) reads\n * as \"cannot tell\" - and cannot-tell must not accuse. */\nfunction insideGesture(): boolean {\n\tconst ua = typeof navigator !== 'undefined' ? navigator.userActivation : undefined;\n\treturn ua ? ua.isActive : true;\n}\n\n/** True when a re-writable file can be picked: a registered desktop shell, or\n *  a browser that ships the File System Access API (Chromium) and has not\n *  already refused to open a picker in this session.\n *\n *  A desktop shell answers first and unconditionally. Inside a native webview\n *  the browser probe is not merely negative, it is misleading: WebKit never\n *  shipped the API, so the honest capability there is the shell's, and asking\n *  the webview instead would degrade the file mode in the one environment where\n *  writing a real file is easiest. */\nexport function isSupported(): boolean {\n\tif (desktop.hasDesktopFiles()) return true;\n\treturn !refused && typeof window !== 'undefined' && 'showSaveFilePicker' in window;\n}\n\n/** True when the browser can let the user point at an EXISTING file. Hosts must\n *  gate that gesture on this: unlike creating, it has no download fallback, so\n *  offering it where it cannot run leaves a button that answers nothing. The\n *  refusal is shared with `isSupported` - a browser that refuses one picker\n *  refuses the family. */\nexport function isOpenSupported(): boolean {\n\tif (desktop.hasDesktopFiles()) return true;\n\treturn !refused && typeof window !== 'undefined' && 'showOpenFilePicker' in window;\n}\n\n/** Run a picker. Cancelling and refusing both mean \"no file\", but only a\n *  refusal says something about the browser - and it must not surface as an\n *  error, or the host reports a fault where it should offer another way. */\nasync function ask<T>(open: () => Promise<T>): Promise<T | null> {\n\tconst asked = insideGesture();\n\ttry {\n\t\treturn await open();\n\t} catch (e) {\n\t\tif (e instanceof DOMException && e.name === 'AbortError') return null; // user cancelled\n\t\t// Outside a gesture the browser refused the CALL, not the feature: keep\n\t\t// the file mode intact so the host can ask again from a real click.\n\t\trefused = asked;\n\t\treturn null;\n\t}\n}\n\n/** Give a browser exception the stable code the target contract requires, so a\n *  host reads WHICH kind of failure it hit instead of a DOMException name.\n *\n *  Untyped, everything the handle throws lands in the store's default branch -\n *  \"transient, the next save retries\" - and that is the one reading always\n *  wrong here: no amount of retrying re-grants a permission, and a file that\n *  was deleted does not come back on its own. Both then loop forever while the\n *  store keeps reporting the data as saved. */\nfunction asTargetError(e: unknown, transient: SelfstoreErrorCode, what: string): Error {\n\tconst name = e instanceof DOMException ? e.name : '';\n\t// Revoked or denied: only a user gesture re-grants it, which is exactly what\n\t// the reconnect gate asks for.\n\tif (name === 'NotAllowedError' || name === 'SecurityError') {\n\t\treturn new AuthExpiredError('File permission was revoked.');\n\t}\n\t// Deleted, renamed, or on a volume that is no longer mounted. Permanent as\n\t// far as this handle goes: reconnecting means pointing at a file again.\n\tif (name === 'NotFoundError') {\n\t\treturn new SelfstoreError('TARGET_GONE', `${what}: the backup file is no longer there.`);\n\t}\n\treturn new SelfstoreError(transient, `${what}: ${String(e)}`);\n}\n\nfunction fromHandle(handle: FileHandle, kv: KV): BackupTarget {\n\treturn {\n\t\tkind: 'file',\n\t\tlabel: handle.name,\n\t\tasync save(blob: Blob): Promise<string | null> {\n\t\t\ttry {\n\t\t\t\tconst writable = await handle.createWritable();\n\t\t\t\tawait writable.write(blob);\n\t\t\t\tawait writable.close();\n\t\t\t} catch (e) {\n\t\t\t\tthrow asTargetError(e, 'TARGET_WRITE_FAILED', 'File write failed');\n\t\t\t}\n\t\t\ttry {\n\t\t\t\t// The file's new mtime = OUR write's version marker (shared-disk case).\n\t\t\t\treturn String((await handle.getFile()).lastModified);\n\t\t\t} catch {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t},\n\t\tasync load(): Promise<Blob | null> {\n\t\t\t// A read that fails is NOT a destination that is empty: returning null\n\t\t\t// here would tell the store \"no backup there\", and the connect that\n\t\t\t// follows would overwrite the file this read merely failed to open.\n\t\t\ttry {\n\t\t\t\treturn await handle.getFile();\n\t\t\t} catch (e) {\n\t\t\t\tthrow asTargetError(e, 'TARGET_UNAVAILABLE', 'File read failed');\n\t\t\t}\n\t\t},\n\t\tasync stat(): Promise<string | null> {\n\t\t\ttry {\n\t\t\t\treturn String((await handle.getFile()).lastModified);\n\t\t\t} catch {\n\t\t\t\treturn null; // permission not granted yet: \"cannot tell\", never throws\n\t\t\t}\n\t\t},\n\t\tasync isReady(): Promise<boolean> {\n\t\t\treturn (await handle.queryPermission({ mode: 'readwrite' })) === 'granted';\n\t\t},\n\t\tasync reconnect(): Promise<boolean> {\n\t\t\treturn (await handle.requestPermission({ mode: 'readwrite' })) === 'granted';\n\t\t},\n\t\tasync disconnect(): Promise<void> {\n\t\t\tawait kv.del(HANDLE_KEY);\n\t\t}\n\t};\n}\n\n/** Prompt the user to choose/create the backup file. Persists the handle for\n *  next sessions. Returns the target, or null if cancelled - or if the browser\n *  refused to open a picker at all, which `isSupported()` then reports. */\nexport async function connect(opts: FileConnectOptions): Promise<BackupTarget | null> {\n\tif (desktop.hasDesktopFiles()) return desktop.connect(opts);\n\tconst picker = (window as unknown as PickerWindow).showSaveFilePicker;\n\tif (!picker) return null;\n\tconst handle = await ask(() =>\n\t\tpicker({\n\t\t\tsuggestedName: opts.fileName,\n\t\t\ttypes: [{ description: 'Backup', accept: { 'application/zip': ['.zip'] } }]\n\t\t})\n\t);\n\tif (!handle) return null;\n\tawait opts.kv.set(HANDLE_KEY, handle);\n\treturn fromHandle(handle, opts.kv);\n}\n\n/** Prompt the user to pick an EXISTING backup file and adopt it as the\n *  destination (the connect journey then reads it like any backup: password,\n *  conflict, resume). Tries to raise the grant to readwrite up front so the\n *  first save does not stall on a second prompt. Returns null if cancelled. */\nexport async function openExisting(opts: { kv: KV }): Promise<BackupTarget | null> {\n\tif (desktop.hasDesktopFiles()) return desktop.openExisting(opts);\n\tconst picker = (window as unknown as PickerWindow).showOpenFilePicker;\n\tif (!picker) return null;\n\tconst picked = await ask(() =>\n\t\tpicker({\n\t\t\tmultiple: false,\n\t\t\ttypes: [{ description: 'Backup', accept: { 'application/zip': ['.zip'] } }]\n\t\t})\n\t);\n\tconst handle = picked?.[0];\n\tif (!handle) return null;\n\t// The upgrade to readwrite is a COURTESY, not a condition. It can fail for a\n\t// reason that has nothing to do with the file - the open picker consumes the\n\t// transient activation a permission prompt needs, so a browser may answer\n\t// 'prompt' without ever asking anyone. Throwing the picked file away then\n\t// dropped the host back on its own screen with nothing said and nothing\n\t// changed: the user pointed at their file and the app appeared to ignore it.\n\t// So we adopt it either way. Reading works on the grant the picker gave, and\n\t// a write that cannot happen raises the store's own reconnect gate, whose\n\t// one click re-asks from inside a real gesture - the only place it can work.\n\t// Outside `ask`: a refusal here is about THIS file, never about the picker,\n\t// which has just proved it opens.\n\ttry {\n\t\tawait handle.requestPermission({ mode: 'readwrite' });\n\t} catch {\n\t\t/* no prompt was possible: the reconnect gesture will ask for real */\n\t}\n\tawait opts.kv.set(HANDLE_KEY, handle);\n\treturn fromHandle(handle, opts.kv);\n}\n\n/** Rebuild the target from what a past session persisted, or null. On a desktop\n *  shell that is a path and it reconnects silently; in a browser it is a handle\n *  and the first write may still ask for the permission back. */\nexport async function fromSession(opts: { kv: KV }): Promise<BackupTarget | null> {\n\tif (desktop.hasDesktopFiles()) return desktop.fromSession(opts);\n\tconst handle = await opts.kv.get<FileHandle>(HANDLE_KEY);\n\treturn handle ? fromHandle(handle, opts.kv) : null;\n}\n"]}