@open-webapp/drive-sync 0.5.5 → 0.5.7

package/SPEC.md

@@ -56,10 +56,11 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 1. **Per-request token client, not a module singleton** — `token.ts`'s `acquireToken`/`acquireTokenUncoalesced` creates a fresh `initTokenClient` on every call; nothing closes over the first call's `projectId`.
 2. **Scope honored on every call** — the fresh client is configured with `opts.scopes.join(' ')` per call, not baked in once at init.
-3. **In-flight coalescing keyed by `(projectId, sorted scopes)`** — `token.ts`'s `coalesceKey` + `inFlight` map; concurrent calls for different projects/scopes never collide.
+3. **In-flight coalescing keyed by `(projectId, sorted scopes, interactive)`** — `token.ts`'s `coalesceKey` + `inFlight` map; concurrent calls for different projects/scopes never collide, and a user-initiated `connect()` is never handed the outcome of an in-flight silent refresh (which would settle the click with no OAuth flow shown).
 4. **No clobbered resolvers** — `resolve`/`reject` are captured in each call's own `Promise` closure (`acquireTokenUncoalesced`), never stored on a module-level variable.
 5. **Real expiry** — `persistTokenResponse` reads `response.expires_in` and computes `Date.now() + expiresIn * 1000`; no hardcoded `3600`.
-6. **`grantedScopes` recorded** — `persistTokenResponse` splits `response.scope` and stores it on the token; `connection.ts`'s `connect()` also copies it onto the durable `ConnRecord`.
+6. **Every GIS request is time-bounded** — GIS settles a request only via `callback`/`error_callback`, and sometimes fires neither; `requestGisToken` rejects with `NeedsReauthError` (`reason: 'gis_timeout'`) after 5min interactive / 10s silent / 4s per recovery probe, so a request that is never answered cannot pin `inFlight` forever and kill every later retry.
+7. **`grantedScopes` recorded** — `persistTokenResponse` splits `response.scope` and stores it on the token; `connection.ts`'s `connect()` also copies it onto the durable `ConnRecord`.
 7. **401 handled** — `http.ts`'s `performFetch` clears the token, retries once non-interactively, then throws `NeedsReauthError` (see §4).
 8. **`hint` on silent refresh** — every non-interactive `acquireToken` call is given `hint: <known email>`; wrong-account tokens are caught by `refreshSilently` (see below and §4).
 9. **`response.ok` checked before parsing** — `performFetch` never calls `.json()`/`.text()` on a response without checking `res.ok` first; every status branch is explicit.
@@ -120,7 +121,7 @@ Nothing in this schema stores a Drive `folderId` or `fileId` — those stay app-
 
 ## 4. Refresh state machine
 
-Token acquisition always funnels through `token.ts`'s `acquireToken`, which is coalesced per `(projectId, sorted scopes)` and never keeps module-level mutable state across calls. Four distinct callers drive it, each representing a different "state":
+Token acquisition always funnels through `token.ts`'s `acquireToken`, which is coalesced per `(projectId, sorted scopes, interactive)` and never keeps module-level mutable state across calls. Four distinct callers drive it, each representing a different "state":
 
 ```
 [No connection]

package/dist/connection.d.ts

@@ -15,8 +15,9 @@ export interface ConnectOptions {
     fetchEmail: (accessToken: string) => Promise<string>;
 }
 /**
- * Interactive connection flow: acquires a token with prompt: 'consent',
- * resolves the account email, and persists the durable Connection record.
+ * Interactive connection flow: acquires a token without forcing a consent
+ * screen, resolves the account email, and persists the durable Connection
+ * record.
  */
 export declare function connect(opts: ConnectOptions): Promise<Connection>;
 export interface RefreshSilentlyOptions {

package/dist/connection.js

@@ -5,8 +5,9 @@ import { WrongAccountError } from './errors.js';
 /** Mirrors refresh.ts's own buffer: a cached token this close to expiry is treated as unusable. */
 const TOKEN_REUSE_BUFFER_MS = 5 * 60 * 1000;
 /**
- * Interactive connection flow: acquires a token with prompt: 'consent',
- * resolves the account email, and persists the durable Connection record.
+ * Interactive connection flow: acquires a token without forcing a consent
+ * screen, resolves the account email, and persists the durable Connection
+ * record.
  */
 export async function connect(opts) {
     // On a re-auth the previous connection's email is the account the user is

package/dist/testing/gisFake.d.ts

@@ -62,6 +62,13 @@ export interface GisFake {
      * the popup-closed poll fires before the success message is delivered.
      */
     queuePopupClosedRace(response: GisTokenResponse, delayMs: number): void;
+    /**
+     * Queue a request that GIS never answers at all: neither `callback` nor
+     * `error_callback` is ever invoked. This is the real-world shape of a flow
+     * whose result is never posted back to the page (e.g. a silent
+     * `prompt: 'none'` request in a browser that blocks silent token issuance).
+     */
+    queueSilence(): void;
     /** Stub `window.google.accounts.oauth2.initTokenClient` with this fake. */
     install(): void;
     /** Remove the stub installed by `install()`, restoring prior state. */

package/dist/testing/gisFake.js

@@ -17,6 +17,7 @@ export function createGisFake() {
     const responseQueue = [];
     const popupErrorQueue = [];
     const popupClosedRaceQueue = [];
+    let silenceQueue = 0;
     const calls = [];
     let previousGoogle;
     let hadGoogle = false;
@@ -34,6 +35,10 @@ export function createGisFake() {
                 const hint = overrideConfig?.hint ?? config.hint;
                 const scope = overrideConfig?.scope ?? config.scope ?? '';
                 calls.push({ prompt, hint, scope });
+                if (silenceQueue > 0) {
+                    silenceQueue -= 1;
+                    return;
+                }
                 const popupClosedRace = popupClosedRaceQueue.shift();
                 if (popupClosedRace) {
                     const errorCallback = config.error_callback;
@@ -82,6 +87,9 @@ export function createGisFake() {
         queuePopupClosedRace(response, delayMs) {
             popupClosedRaceQueue.push({ response, delayMs });
         },
+        queueSilence() {
+            silenceQueue += 1;
+        },
         install() {
             const w = globalThis;
             hadGoogle = Object.prototype.hasOwnProperty.call(w, 'google');
@@ -110,6 +118,7 @@ export function createGisFake() {
             responseQueue.length = 0;
             popupErrorQueue.length = 0;
             popupClosedRaceQueue.length = 0;
+            silenceQueue = 0;
             calls.length = 0;
         },
     };

package/dist/token.d.ts

@@ -33,9 +33,10 @@ export interface AcquireTokenOptions {
 export declare function notifyExternalTokenRefresh(projectId: string): void;
 /**
  * Single entry point for acquiring a Drive access token, used by BOTH the
- * interactive "connect" path (interactive: true -> prompt: 'consent', no
- * hint) and the silent "refresh" path (interactive: false -> prompt: 'none',
- * hint: the connection's known email).
+ * interactive "connect" path (interactive: true -> prompt: '', i.e. no
+ * forced consent screen) and the silent "refresh" path (interactive: false
+ * -> prompt: 'none'). Both pass `hint`: the connection's known email, when
+ * there is one.
  *
  * Design contract (see report): if `interactive` is false and GIS reports an
  * error on the silent attempt, this function throws a NeedsReauthError

package/dist/token.js

@@ -24,6 +24,26 @@ const POPUP_CLOSED_GRACE_MS = 2000;
  */
 const PROBE_ATTEMPTS = 3;
 const PROBE_RETRY_DELAY_MS = 350;
+/**
+ * Hard ceiling on a single GIS token request.
+ *
+ * GIS settles a request ONLY by invoking `callback` or `error_callback`, and
+ * in the field it sometimes does neither: a completed flow whose result is
+ * never posted back to this page (most reliably a silent `prompt: 'none'`
+ * request in a browser that blocks silent token issuance) leaves both
+ * callbacks unfired. Without a ceiling that request stays pending forever —
+ * `connect()` never settles, the host app is stuck mid-connect with no error
+ * to show, and the in-flight entry in `inFlight` is never released, so every
+ * later retry joins the same dead promise and no popup ever opens again.
+ *
+ * Interactive requests get a generous ceiling because the user is legitimately
+ * typing a password inside the popup; silent requests have no UI and must
+ * either answer quickly or be treated as failed.
+ */
+const INTERACTIVE_REQUEST_TIMEOUT_MS = 5 * 60_000;
+const SILENT_REQUEST_TIMEOUT_MS = 10_000;
+/** Probes run up to PROBE_ATTEMPTS times, so each one has to fail fast. */
+const PROBE_REQUEST_TIMEOUT_MS = 4_000;
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Persists a freshly-acquired GIS token response as a StoredToken, deriving
@@ -41,12 +61,19 @@ export async function persistTokenResponse(appId, projectId, response) {
     return token;
 }
 /**
- * Key used for in-flight coalescing: per (projectId, sorted-scope-set), NOT
- * global. This is what keeps concurrent calls for different projects (or
- * different scope requirements within the same project) from colliding.
+ * Key used for in-flight coalescing: per (projectId, sorted-scope-set,
+ * interactive), NOT global. This is what keeps concurrent calls for different
+ * projects (or different scope requirements within the same project) from
+ * colliding.
+ *
+ * `interactive` is part of the key because the two modes are not
+ * interchangeable: a user-initiated `connect()` must run its own OAuth flow,
+ * and must never be handed the outcome of a silent background refresh that
+ * happens to be in flight — that resolves (or rejects) the user's click with
+ * no flow shown at all, which is indistinguishable from a dead button.
  */
-function coalesceKey(projectId, scopes) {
-    return `${projectId}|${scopes.slice().sort().join(' ')}`;
+function coalesceKey(projectId, scopes, interactive) {
+    return `${projectId}|${interactive ? 'i' : 's'}|${scopes.slice().sort().join(' ')}`;
 }
 const inFlight = new Map();
 /**
@@ -71,9 +98,10 @@ export function notifyExternalTokenRefresh(projectId) {
 }
 /**
  * Single entry point for acquiring a Drive access token, used by BOTH the
- * interactive "connect" path (interactive: true -> prompt: 'consent', no
- * hint) and the silent "refresh" path (interactive: false -> prompt: 'none',
- * hint: the connection's known email).
+ * interactive "connect" path (interactive: true -> prompt: '', i.e. no
+ * forced consent screen) and the silent "refresh" path (interactive: false
+ * -> prompt: 'none'). Both pass `hint`: the connection's known email, when
+ * there is one.
  *
  * Design contract (see report): if `interactive` is false and GIS reports an
  * error on the silent attempt, this function throws a NeedsReauthError
@@ -100,7 +128,7 @@ export async function acquireToken(opts) {
             return stored;
         }
     }
-    const key = coalesceKey(opts.projectId, opts.scopes);
+    const key = coalesceKey(opts.projectId, opts.scopes, opts.interactive);
     const existing = inFlight.get(key);
     if (existing) {
         return existing;
@@ -139,7 +167,7 @@ async function probeForCompletedGrant(initTokenClient, opts, popupClosedError) {
         try {
             // No grace window: `prompt: 'none'` never opens a popup, so there is no
             // popup-closed poll to race and nothing to wait out on failure.
-            const response = await requestGisToken(initTokenClient, opts, { prompt: 'none', hint: opts.hint }, 0);
+            const response = await requestGisToken(initTokenClient, opts, { prompt: 'none', hint: opts.hint }, 0, PROBE_REQUEST_TIMEOUT_MS);
             opts.logger?.debug('drive-sync: recovered a completed sign-in reported as popup_closed', {
                 projectId: opts.projectId,
                 attempt,
@@ -166,9 +194,33 @@ async function probeForCompletedGrant(initTokenClient, opts, popupClosedError) {
  * captured in THIS call's closure only — never on a module-level variable — so
  * a second concurrent call cannot clobber the first caller's promise.
  */
-function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = POPUP_CLOSED_GRACE_MS) {
+function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = POPUP_CLOSED_GRACE_MS, timeoutMs = INTERACTIVE_REQUEST_TIMEOUT_MS) {
     return new Promise((resolve, reject) => {
         let settled = false;
+        // Neither GIS callback is guaranteed to fire; see the timeout constants.
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            opts.logger?.warn('drive-sync: GIS never returned a result; timing out the request', {
+                projectId: opts.projectId,
+                prompt: override.prompt,
+                timeoutMs,
+            });
+            reject(new NeedsReauthError('Google sign-in did not return a result', {
+                reason: 'gis_timeout',
+            }));
+        }, timeoutMs);
+        const succeed = (res) => {
+            settled = true;
+            clearTimeout(timeout);
+            resolve(res);
+        };
+        const fail = (err) => {
+            settled = true;
+            clearTimeout(timeout);
+            reject(err);
+        };
         const client = initTokenClient({
             client_id: opts.clientId,
             scope: opts.scopes.join(' '),
@@ -184,12 +236,11 @@ function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = P
                     });
                     return;
                 }
-                settled = true;
                 if (res.error) {
-                    reject(new Error(`GIS token request failed: ${res.error}`));
+                    fail(new Error(`GIS token request failed: ${res.error}`));
                     return;
                 }
-                resolve(res);
+                succeed(res);
             },
             // Without this, a popup that the browser blocks or the user closes
             // settles NOTHING: GIS reports those through error_callback only, so
@@ -215,15 +266,13 @@ function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = P
                     setTimeout(() => {
                         if (settled)
                             return;
-                        settled = true;
-                        reject(new NeedsReauthError('Google sign-in popup was closed before completing', {
+                        fail(new NeedsReauthError('Google sign-in popup was closed before completing', {
                             reason: 'popup_closed',
                         }));
                     }, popupClosedGraceMs);
                     return;
                 }
-                settled = true;
-                reject(new NeedsReauthError(err?.type === 'popup_failed_to_open'
+                fail(new NeedsReauthError(err?.type === 'popup_failed_to_open'
                     ? 'Google sign-in popup was blocked by the browser'
                     : `Google sign-in failed: ${err?.type ?? 'unknown error'}`, { reason: err?.type ?? 'gis_error' }));
             },
@@ -248,9 +297,20 @@ async function acquireTokenUncoalesced(opts) {
     let response;
     try {
         response = await requestGisToken(initTokenClient, opts, {
-            prompt: opts.interactive ? 'consent' : 'none',
-            hint: !opts.interactive ? opts.hint : undefined,
-        });
+            // The interactive path deliberately does NOT force `prompt: 'consent'`.
+            // Forcing the full consent screen on every connect buys nothing in the
+            // implicit (token) flow — there is no refresh token to obtain — while
+            // holding a popup open for seconds. That popup lifetime IS the window
+            // in which GIS's popup-closed poll beats delivery of the token, so
+            // forcing consent manufactures the very race the probe below recovers
+            // from. `prompt: ''` lets Google skip straight through when the grant
+            // already exists (and still shows consent on the first grant, or when
+            // new scopes are requested), which closes the race instead of racing
+            // it. The hint goes on both paths so an already-known account can skip
+            // the chooser too.
+            prompt: opts.interactive ? '' : 'none',
+            hint: opts.hint,
+        }, POPUP_CLOSED_GRACE_MS, opts.interactive ? INTERACTIVE_REQUEST_TIMEOUT_MS : SILENT_REQUEST_TIMEOUT_MS);
     }
     catch (err) {
         if (!opts.interactive) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-webapp/drive-sync",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "type": "module",
   "repository": {
     "type": "git",