selfstore 1.8.6 → 1.8.7

package/dist/{local-C52j3DeH.d.ts → local-VLHtF3vT.d.ts}

@@ -21,19 +21,54 @@ declare function changePassword(input: Blob | Uint8Array, opts: {
 
 /**
  * A client-only DriveAuth: the Google Identity Services token flow, no backend.
- * The access token is cached in sessionStorage so a reload reuses it, and a
- * silent re-acquisition is attempted when it lapses; if that fails (the Google
- * session expired, or third-party cookies are blocked) the Drive target reports
- * needs-attention and the user reconnects in one click. For a connection that
- * never re-prompts, back the Drive target with a server that holds a refresh
- * token instead (a broker implementing the same DriveAuth interface).
+ *
+ * What this flow can and cannot do, because it decides how often a user is
+ * interrupted. Google's browser token flow issues an access token that lives
+ * about an hour and NO refresh token - a refresh token requires a client secret,
+ * which requires a server. And `requestAccessToken` always opens a popup, even
+ * with `prompt: ''`: the popup closes by itself when the grant is still on file,
+ * but opening it at all needs a user gesture. So a purely client-side app cannot
+ * silently re-acquire a token on page load. What it CAN do:
+ *
+ *   - reuse a token it already has (`persist: 'session'`), so a reload inside the
+ *     hour asks for nothing at all;
+ *   - name the account (`hint`), so the popup does not ask which one;
+ *   - re-grant without the consent screen (`prompt: ''` before `'consent'`) -
+ *     which is also what stops Google mailing "you granted access" every time.
+ *
+ * For a connection that never re-prompts, back the Drive target with a server
+ * that holds a refresh token instead (a broker implementing this same DriveAuth).
  */
 
-/** Build a client-only DriveAuth for the given OAuth client id (no backend). */
-declare function gisDriveAuth(opts: {
+/** Where the access token survives between requests. */
+type GisTokenPersistence = 'memory' | 'session';
+interface GisDriveAuthOptions {
     clientId: string;
     scope?: string;
-}): DriveAuth;
+    /**
+     * The account to re-grant for, so the popup does not ask which one. Pass the
+     * address the app remembers (`driveTarget.account()` answers it once
+     * connected); a function is read at every request, for a host that only
+     * learns it after the first connect.
+     */
+    hint?: string | (() => string | null | undefined);
+    /**
+     * Where the access token lives between requests.
+     *
+     * `'memory'` (the default) keeps it in a closure and nowhere else: a reload
+     * has to re-acquire it, which needs a click, but no Drive-scoped credential is
+     * ever written to web storage.
+     *
+     * `'session'` also keeps it in `sessionStorage`, so a reload reuses the token
+     * it already has and asks for nothing. That token is a bearer credential for
+     * the `drive.file` scope, readable by any script on the origin; it dies with
+     * the tab and within the hour. Opt in for an app whose users reload often;
+     * leave it alone where an XSS on the origin must find nothing to lift.
+     */
+    persist?: GisTokenPersistence;
+}
+/** Build a client-only DriveAuth for the given OAuth client id (no backend). */
+declare function gisDriveAuth(opts: GisDriveAuthOptions): DriveAuth;
 
 /**
  * Save a backup blob to disk via the File System Access API, else a download.
@@ -62,4 +97,4 @@ declare function datedName(filename: string, when?: Date): string;
 /** Prompt the user to pick a backup file from disk. Resolves null if cancelled. */
 declare function pickFromDisk(): Promise<File | null>;
 
-export { inspect as a, isEncrypted as b, changePassword as c, datedName as d, exportSnapshot as e, gisDriveAuth as g, importSnapshot as i, pickFromDisk as p, saveToDisk as s };
+export { type GisDriveAuthOptions as G, type GisTokenPersistence as a, inspect as b, isEncrypted as c, datedName as d, exportSnapshot as e, changePassword as f, gisDriveAuth as g, importSnapshot as i, pickFromDisk as p, saveToDisk as s };

package/llms.txt

@@ -295,8 +295,16 @@ the store's restoreTarget option):
 - webdavTarget.connect({ kv, config: { url, username, password } }) - the url MUST
   be https (loopback excepted).
 - driveTarget.connect({ auth, kv, fileName }) - Google Drive; auth: DriveAuth
-  (gisDriveAuth({ clientId }) is the client-only reference; a refresh-token
-  broker makes it permanent). Shared-file primitives: driveTarget.preview /
+  (gisDriveAuth({ clientId, hint?, persist? }) is the client-only reference; a
+  refresh-token broker makes it permanent). How often it interrupts: the browser
+  token flow has NO refresh token and requestAccessToken opens a popup even with
+  prompt '' (so it needs a user gesture - no silent re-acquisition on page load).
+  persist: 'session' keeps the ~1h token in sessionStorage so a reload asks
+  nothing (opt-in: it is a drive.file bearer credential in web storage); hint
+  (value or callback, e.g. what driveTarget.account() returned) skips the account
+  chooser; reconnect() tries prompt '' before 'consent', because forcing consent
+  over a live grant re-asks an answered question and makes Google mail the user
+  each time. Shared-file primitives: driveTarget.preview /
   adopt / findOrCreateOwnFile. My-backups ops (metadata, one call each):
   listBackups({ auth, nameContains? }) / createBackup({ auth, fileName }) /
   renameBackup({ auth, fileId, fileName }) / deleteBackup({ auth, fileId }) -

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "selfstore",
-	"version": "1.8.6",
+	"version": "1.8.7",
 	"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",