@open-webapp/drive-sync 0.5.7 → 0.7.0

package/dist/files.d.ts

@@ -9,6 +9,12 @@ interface BaseCallOptions {
     interactive?: boolean;
     logger?: Logger;
     fetchEmail?: (accessToken: string) => Promise<string>;
+    /**
+     * Server-mediated token-exchange endpoint. Forwarded verbatim into every
+     * `driveFetch` call so envelope-mode token acquisition / 401 recovery runs
+     * through `refreshEnvelope` (see http.ts). Absent for the legacy GIS path.
+     */
+    tokenExchangeUrl?: string;
 }
 export interface ReadOptions extends BaseCallOptions {
     fileId: string;

package/dist/files.js

@@ -26,6 +26,7 @@ async function fetchRemoteVersion(opts) {
             requiredScopes: REQUIRED_SCOPES,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
         });
         const json = (await res.json());
         if (json.version === undefined)
@@ -76,6 +77,7 @@ export async function read(opts) {
             requiredScopes: REQUIRED_SCOPES,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
         });
         const contentType = res.headers.get('Content-Type') ?? '';
         const isTextual = contentType === '' ||
@@ -107,6 +109,7 @@ export async function remove(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     // The baseline describes a file that no longer exists; leaving it behind
     // would make a later file reusing this id look spuriously in sync.
@@ -159,6 +162,7 @@ async function updateContent(opts, fileId, knownRemoteVersion) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     const json = (await res.json());
     // The version we just produced becomes the new baseline, so back-to-back
@@ -199,6 +203,7 @@ export async function write(opts) {
             interactive: opts.interactive,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
         });
         if (existing.length > 0) {
             return updateContent(opts, existing[0].id, existing[0].version);
@@ -235,6 +240,7 @@ export async function write(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     const json = (await res.json());
     // This client authored the file, so it starts out fully in sync.
@@ -296,8 +302,10 @@ export async function list(opts) {
     // `version` comes back so the name-resolution path in write() can run its
     // staleness check without a follow-up metadata fetch. `modifiedTime` is
     // also requested so callers can get a last-modified timestamp per file
-    // without an extra round trip.
-    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType,version,modifiedTime)')}`;
+    // without an extra round trip. `thumbnailLink` +
+    // `imageMediaMetadata(width,height,rotation)` are also requested so callers
+    // can render/orient low-res image thumbnails without an extra round trip.
+    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType,version,modifiedTime,thumbnailLink,imageMediaMetadata(width,height,rotation))')}`;
     const res = await driveFetch({
         appId: opts.appId,
         projectId: opts.projectId,
@@ -308,6 +316,7 @@ export async function list(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     const json = (await res.json());
     return json.files ?? [];
@@ -333,6 +342,7 @@ async function createFolder(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     const json = (await res.json());
     return json.id;
@@ -363,6 +373,7 @@ export async function ensureFolderPath(opts) {
             interactive: opts.interactive,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
             folderId: parentId,
             mimeType: FOLDER_MIME_TYPE,
             nameEquals: name,
@@ -378,6 +389,7 @@ export async function ensureFolderPath(opts) {
             interactive: opts.interactive,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
             name,
             parentId,
         });

package/dist/gis.d.ts

@@ -1,4 +1,6 @@
 import type { Logger } from './logger.js';
+/** Whether `google.accounts.oauth2.initCodeClient` is present and callable. */
+export declare function isCodeClientAvailable(): boolean;
 /**
  * Resolves once `window.google.accounts.oauth2.initTokenClient` becomes
  * available, polling every 100ms. Rejects with a GisLoadError if it does not
@@ -6,3 +8,27 @@ import type { Logger } from './logger.js';
  * correctly under `vi.useFakeTimers()`.
  */
 export declare function waitForGoogleIdentityServices(logger?: Logger): Promise<void>;
+/**
+ * Envelope-mode counterpart of {@link waitForGoogleIdentityServices}: resolves
+ * once `window.google.accounts.oauth2.initCodeClient` is available, polling
+ * every 100ms, rejecting with a GisLoadError after 10 seconds. Kept separate
+ * from the legacy token-client poll so the legacy path is untouched.
+ */
+export declare function waitForGisCodeClient(logger?: Logger): Promise<void>;
+export interface AcquireAuthCodeOptions {
+    clientId: string;
+    scopes: string[];
+    /** Prior account email, passed to GIS as `hint` to pre-select the account. */
+    hint?: string;
+    logger?: Logger;
+}
+/**
+ * Runs the GIS auth-code (server-side exchange) popup flow once and resolves
+ * with the one-time authorization `code`. No `redirect_uri`, no `state`: the
+ * code is handed straight to the token-exchange endpoint.
+ *
+ * Rejects with a {@link NeedsReauthError} when GIS reports an in-band
+ * `response.error`, fires `error_callback` (blocked/dismissed popup), or never
+ * answers on either channel within {@link ACQUIRE_CODE_TIMEOUT_MS}.
+ */
+export declare function acquireAuthCode(opts: AcquireAuthCodeOptions): Promise<string>;

package/dist/gis.js

@@ -1,10 +1,23 @@
-import { GisLoadError } from './errors.js';
+import { GisLoadError, NeedsReauthError } from './errors.js';
 const POLL_INTERVAL_MS = 100;
 const TIMEOUT_MS = 10_000;
+/**
+ * Hard ceiling on how long `acquireAuthCode` waits for GIS to deliver a result
+ * on EITHER channel (`callback` or `error_callback`). Neither is guaranteed to
+ * fire — a silently swallowed popup leaves the promise pending forever without
+ * this. Mirrors token.ts's `INTERACTIVE_REQUEST_TIMEOUT_MS` (5 minutes): the
+ * user may take a while at the Google consent screen.
+ */
+const ACQUIRE_CODE_TIMEOUT_MS = 5 * 60_000;
 function isGisAvailable() {
     const w = globalThis;
     return typeof w.google?.accounts?.oauth2?.initTokenClient !== 'undefined';
 }
+/** Whether `google.accounts.oauth2.initCodeClient` is present and callable. */
+export function isCodeClientAvailable() {
+    const w = globalThis;
+    return typeof w.google?.accounts?.oauth2?.initCodeClient === 'function';
+}
 /**
  * Resolves once `window.google.accounts.oauth2.initTokenClient` becomes
  * available, polling every 100ms. Rejects with a GisLoadError if it does not
@@ -31,3 +44,107 @@ export function waitForGoogleIdentityServices(logger) {
         }, POLL_INTERVAL_MS);
     });
 }
+/**
+ * Envelope-mode counterpart of {@link waitForGoogleIdentityServices}: resolves
+ * once `window.google.accounts.oauth2.initCodeClient` is available, polling
+ * every 100ms, rejecting with a GisLoadError after 10 seconds. Kept separate
+ * from the legacy token-client poll so the legacy path is untouched.
+ */
+export function waitForGisCodeClient(logger) {
+    if (isCodeClientAvailable()) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const startedAt = Date.now();
+        const interval = setInterval(() => {
+            logger?.debug('drive-sync: polling for Google Identity Services code client...');
+            if (isCodeClientAvailable()) {
+                clearInterval(interval);
+                resolve();
+                return;
+            }
+            if (Date.now() - startedAt >= TIMEOUT_MS) {
+                clearInterval(interval);
+                reject(new GisLoadError());
+            }
+        }, POLL_INTERVAL_MS);
+    });
+}
+/**
+ * Runs the GIS auth-code (server-side exchange) popup flow once and resolves
+ * with the one-time authorization `code`. No `redirect_uri`, no `state`: the
+ * code is handed straight to the token-exchange endpoint.
+ *
+ * Rejects with a {@link NeedsReauthError} when GIS reports an in-band
+ * `response.error`, fires `error_callback` (blocked/dismissed popup), or never
+ * answers on either channel within {@link ACQUIRE_CODE_TIMEOUT_MS}.
+ */
+export async function acquireAuthCode(opts) {
+    await waitForGisCodeClient(opts.logger);
+    const w = globalThis;
+    const initCodeClient = w.google?.accounts?.oauth2?.initCodeClient;
+    if (!initCodeClient) {
+        throw new GisLoadError();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            opts.logger?.warn('drive-sync: GIS never returned an auth code; timing out', {
+                timeoutMs: ACQUIRE_CODE_TIMEOUT_MS,
+            });
+            reject(new NeedsReauthError('Google sign-in did not return an auth code', {
+                reason: 'gis_timeout',
+            }));
+        }, ACQUIRE_CODE_TIMEOUT_MS);
+        const succeed = (code) => {
+            settled = true;
+            clearTimeout(timeout);
+            resolve(code);
+        };
+        const fail = (err) => {
+            settled = true;
+            clearTimeout(timeout);
+            reject(err);
+        };
+        const client = initCodeClient({
+            client_id: opts.clientId,
+            scope: opts.scopes.join(' '),
+            ux_mode: 'popup',
+            hint: opts.hint,
+            callback: (res) => {
+                if (settled)
+                    return;
+                if (res.error) {
+                    fail(new NeedsReauthError(`Google sign-in failed: ${res.error}`, {
+                        reason: res.error,
+                    }));
+                    return;
+                }
+                if (!res.code) {
+                    fail(new NeedsReauthError('Google sign-in returned no auth code', {
+                        reason: 'gis_error',
+                    }));
+                    return;
+                }
+                succeed(res.code);
+            },
+            error_callback: (err) => {
+                opts.logger?.debug('drive-sync: GIS code client error_callback', {
+                    type: err?.type,
+                    message: err?.message,
+                    settled,
+                });
+                if (settled)
+                    return;
+                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' }));
+            },
+        });
+        opts.logger?.debug('drive-sync: requesting auth code');
+        client.requestCode();
+    });
+}

package/dist/http.d.ts

@@ -20,6 +20,15 @@ export interface DriveFetchOptions {
      * this module has no hard dependency on a network implementation.
      */
     fetchEmail?: (accessToken: string) => Promise<string>;
+    /**
+     * Server-mediated token-exchange endpoint. When set, drive-sync is in
+     * "envelope mode": token acquisition and 401 recovery go through
+     * `refreshEnvelope` (envelope.ts) rather than the legacy GIS
+     * `acquireToken`/`refreshSilently` path. Drive calls never drive the
+     * interactive code popup in this mode — only `connect()` does — so an
+     * interactive Drive call with no usable token surfaces `NeedsReauthError`.
+     */
+    tokenExchangeUrl?: string;
 }
 /**
  * Single entry point for all Drive API HTTP calls. Handles token

package/dist/http.js

@@ -1,4 +1,5 @@
 import { acquireToken } from './token.js';
+import { refreshEnvelope } from './envelope.js';
 import { getConnection, refreshSilently } from './connection.js';
 import { clearToken, getToken } from './storage.js';
 import { DriveSyncError, NeedsReauthError, ScopeInsufficientError, NotFoundError, NotDownloadableError, RateLimitedError, TransientError, WrongAccountError, } from './errors.js';
@@ -60,6 +61,22 @@ export async function driveFetch(opts) {
     // NeedsReauthError from acquireToken itself — we deliberately let that
     // propagate rather than pre-emptively short-circuiting here, since
     // acquireToken/GIS is the single source of truth for "can we get a token".
+    // Envelope (server-mediated token-exchange) mode: never touch GIS. A
+    // non-interactive call refreshes through the stored envelope; an
+    // interactive Drive call has no usable token and cannot run the code
+    // popup itself (only connect() does) -> NeedsReauthError.
+    if (opts.tokenExchangeUrl) {
+        if (interactive) {
+            throw new NeedsReauthError('Interactive Drive call in token-exchange mode requires connect()', { status: 401, reason: 'exchange_failed' });
+        }
+        const token = await refreshEnvelope({
+            appId,
+            projectId,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
+            logger,
+        });
+        return performFetch(opts, token.accessToken, /* isRetryAfter401 */ false);
+    }
     const conn = await getConnection({ appId, projectId, requiredScopes });
     const hint = conn?.email;
     const token = await acquireToken({
@@ -130,6 +147,20 @@ async function performFetch(opts, accessToken, isRetryAfter401) {
                 reason: lastBodyText,
             });
         }
+        // Envelope mode: clear only the token key (per decision 4/8) and recover
+        // through the stored envelope. A refreshEnvelope throw — including the 410
+        // that also clears conn+envelope — is already a NeedsReauthError; let it
+        // propagate as-is.
+        if (opts.tokenExchangeUrl) {
+            await clearToken(appId, projectId);
+            const refreshed = await refreshEnvelope({
+                appId,
+                projectId,
+                tokenExchangeUrl: opts.tokenExchangeUrl,
+                logger,
+            });
+            return performFetch(opts, refreshed.accessToken, /* isRetryAfter401 */ true);
+        }
         await clearToken(appId, projectId);
         let refreshed;
         try {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { CallOptions, Connection, DriveSyncOptions, DrivePermission, FileRef, FileState, PickFileOptions, PickedFile } from './types.js';
-export type { DriveSyncOptions, Connection, StoredToken, FileRef, FileState, DrivePermission, CallOptions, WorkspaceMimeShorthand, PickFileOptions, PickedFile } from './types.js';
+export type { DriveSyncOptions, Connection, StoredToken, FileRef, FileState, DrivePermission, CallOptions, WorkspaceMimeShorthand, PickFileOptions, PickedFile, Envelope, EnvelopePayload } from './types.js';
 export * from './errors.js';
 export interface FilesHandle {
     list(opts?: {

package/dist/index.js

@@ -47,7 +47,7 @@ async function revokeToken(accessToken) {
  * returned object's methods are actually called.
  */
 export function createDriveSync(options) {
-    const { appId, clientId, folderPath } = options;
+    const { appId, clientId, folderPath, tokenExchangeUrl } = options;
     const logger = options.logger ?? noOpLogger;
     /**
      * Design choice for `.activate()` (T30): the frozen public API's
@@ -99,7 +99,7 @@ export function createDriveSync(options) {
         }
         const runWarmUps = () => {
             for (const projectId of trackedProjectIds) {
-                void warmUpIfNeeded({ appId, projectId, clientId, fetchEmail, logger });
+                void warmUpIfNeeded({ appId, projectId, clientId, tokenExchangeUrl, fetchEmail, logger });
             }
         };
         const onVisibilityChange = () => {
@@ -131,7 +131,7 @@ export function createDriveSync(options) {
     }
     function project(projectId) {
         trackProject(projectId);
-        const base = { appId, projectId, clientId, logger, fetchEmail };
+        const base = { appId, projectId, clientId, tokenExchangeUrl, logger, fetchEmail };
         const files = {
             list(opts, callOpts) {
                 return filesImpl.list({ ...base, ...opts, interactive: callOpts?.interactive });
@@ -170,6 +170,7 @@ export function createDriveSync(options) {
                     projectId,
                     clientId,
                     scopes: REQUIRED_SCOPES,
+                    tokenExchangeUrl,
                     logger,
                     fetchEmail,
                 });
@@ -182,9 +183,14 @@ export function createDriveSync(options) {
                 });
             },
             async disconnect() {
-                await disconnectImpl({
+                // `tokenExchangeUrl` is threaded via an intermediate object rather
+                // than an inline literal so this compiles while T7's
+                // `DisconnectOptions.tokenExchangeUrl?` field lands in parallel; once
+                // it has, the envelope-mode disconnect branch picks the value up.
+                const disconnectOpts = {
                     appId,
                     projectId,
+                    tokenExchangeUrl,
                     revokeFn: async (accessToken) => {
                         try {
                             await revokeToken(accessToken);
@@ -193,7 +199,8 @@ export function createDriveSync(options) {
                             logger.warn('drive-sync: token revocation failed', { err });
                         }
                     },
-                });
+                };
+                await disconnectImpl(disconnectOpts);
             },
             ensureFolderPath() {
                 return filesImpl.ensureFolderPath({ ...base, folderPath });
@@ -205,6 +212,7 @@ export function createDriveSync(options) {
                     clientId,
                     scopes: REQUIRED_SCOPES,
                     interactive: callOpts?.interactive ?? true,
+                    tokenExchangeUrl,
                     logger,
                 });
             },
@@ -215,6 +223,7 @@ export function createDriveSync(options) {
                     clientId,
                     scopes: REQUIRED_SCOPES,
                     interactive: true,
+                    tokenExchangeUrl,
                     logger,
                 });
                 const picked = await pickerImpl.openPicker({

package/dist/permissions.d.ts

@@ -7,6 +7,12 @@ interface BaseCallOptions {
     interactive?: boolean;
     logger?: Logger;
     fetchEmail?: (accessToken: string) => Promise<string>;
+    /**
+     * Server-mediated token-exchange endpoint. Forwarded verbatim into every
+     * `driveFetch` call so envelope-mode token acquisition / 401 recovery runs
+     * through `refreshEnvelope` (see http.ts). Absent for the legacy GIS path.
+     */
+    tokenExchangeUrl?: string;
 }
 export interface ListPermissionsOptions extends BaseCallOptions {
     fileId: string;

package/dist/permissions.js

@@ -12,6 +12,7 @@ export async function list(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     const json = (await res.json());
     return json.permissions ?? [];
@@ -37,6 +38,7 @@ export async function grant(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     return (await res.json());
 }
@@ -53,6 +55,7 @@ export async function update(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
     return (await res.json());
 }
@@ -67,5 +70,6 @@ export async function revoke(opts) {
         requiredScopes: REQUIRED_SCOPES,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
     });
 }

package/dist/refresh.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from './logger.js';
+export declare const REFRESH_BUFFER_MS: number;
 export interface ActivateOptions {
     appId: string;
     projectId: string;
@@ -11,6 +12,14 @@ export interface ActivateOptions {
      * only being discovered on the next foreground Drive call.
      */
     fetchEmail?: (accessToken: string) => Promise<string>;
+    /**
+     * Server-mediated token-exchange endpoint. When set, the warm-up's
+     * non-interactive refresh goes through `refreshEnvelope` (envelope.ts) —
+     * replaying the stored envelope against this endpoint — instead of the
+     * legacy GIS `refreshSilently` / `acquireToken` path. Absent, the legacy
+     * path runs unchanged.
+     */
+    tokenExchangeUrl?: string;
     logger?: Logger;
 }
 /**

package/dist/refresh.js

@@ -1,8 +1,9 @@
 import { getConnection, refreshSilently } from './connection.js';
 import { getToken } from './storage.js';
 import { acquireToken } from './token.js';
+import { refreshEnvelope } from './envelope.js';
 import { REQUIRED_SCOPES } from './files.js';
-const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+export const REFRESH_BUFFER_MS = 5 * 60 * 1000;
 /**
  * Per-project token warm-up check: if a connection exists AND its cached
  * token is missing or within the refresh buffer of expiring, fires a
@@ -29,7 +30,15 @@ export async function warmUpIfNeeded(opts) {
         if (!isStale) {
             return;
         }
-        if (opts.fetchEmail) {
+        if (opts.tokenExchangeUrl) {
+            await refreshEnvelope({
+                appId: opts.appId,
+                projectId: opts.projectId,
+                tokenExchangeUrl: opts.tokenExchangeUrl,
+                logger: opts.logger,
+            });
+        }
+        else if (opts.fetchEmail) {
             await refreshSilently({
                 appId: opts.appId,
                 projectId: opts.projectId,

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
 import { type IDBPDatabase, type DBSchema } from 'idb';
-import type { StoredToken } from './types.js';
+import type { Envelope, StoredToken } from './types.js';
 /** Durable connection record persisted under the 'conn' key of the auth store. */
 export interface ConnRecord {
     email: string;
@@ -20,7 +20,7 @@ export interface FileStateRecord {
 interface AuthDbSchema extends DBSchema {
     auth: {
         key: string;
-        value: ConnRecord | StoredToken | FileStateRecord;
+        value: ConnRecord | StoredToken | Envelope | FileStateRecord;
     };
 }
 export declare function openAuthDb(appId: string, projectId: string): Promise<IDBPDatabase<AuthDbSchema>>;
@@ -35,6 +35,9 @@ export declare function clearConn(appId: string, projectId: string): Promise<voi
 export declare function getToken(appId: string, projectId: string): Promise<StoredToken | undefined>;
 export declare function setToken(appId: string, projectId: string, token: StoredToken): Promise<void>;
 export declare function clearToken(appId: string, projectId: string): Promise<void>;
+export declare function getEnvelope(appId: string, projectId: string): Promise<Envelope | undefined>;
+export declare function setEnvelope(appId: string, projectId: string, env: Envelope): Promise<void>;
+export declare function clearEnvelope(appId: string, projectId: string): Promise<void>;
 export declare function getFileState(appId: string, projectId: string, fileId: string): Promise<FileStateRecord | undefined>;
 export declare function setFileState(appId: string, projectId: string, state: FileStateRecord): Promise<void>;
 export declare function clearFileState(appId: string, projectId: string, fileId: string): Promise<void>;

package/dist/storage.js

@@ -2,6 +2,7 @@ import { openDB } from 'idb';
 const AUTH_STORE = 'auth';
 const CONN_KEY = 'conn';
 const TOKEN_KEY = 'token';
+const ENVELOPE_KEY = 'envelope';
 /**
  * File baselines live in the existing 'auth' store under a namespaced key
  * rather than in a store of their own, deliberately: adding a store means
@@ -85,6 +86,19 @@ export async function clearToken(appId, projectId) {
     const db = await openAuthDb(appId, projectId);
     await db.delete(AUTH_STORE, TOKEN_KEY);
 }
+export async function getEnvelope(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    const value = await db.get(AUTH_STORE, ENVELOPE_KEY);
+    return value;
+}
+export async function setEnvelope(appId, projectId, env) {
+    const db = await openAuthDb(appId, projectId);
+    await db.put(AUTH_STORE, env, ENVELOPE_KEY);
+}
+export async function clearEnvelope(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    await db.delete(AUTH_STORE, ENVELOPE_KEY);
+}
 export async function getFileState(appId, projectId, fileId) {
     const db = await openAuthDb(appId, projectId);
     const value = await db.get(AUTH_STORE, fileKey(fileId));

package/dist/testing/driveFake.d.ts

@@ -31,6 +31,22 @@ export interface DriveFakeFile {
      * real Drive's `fields`-gated behavior).
      */
     modifiedTime?: string;
+    /**
+     * Drive's CDN thumbnail URL; optional so tests may seed files without it
+     * (omitted from the fake's response in that case, matching real Drive's
+     * `fields`-gated behavior).
+     */
+    thumbnailLink?: string;
+    /**
+     * Drive's image metadata (dimensions/rotation); optional so tests may seed
+     * files without it (omitted from the fake's response in that case, matching
+     * real Drive's `fields`-gated behavior).
+     */
+    imageMediaMetadata?: {
+        width?: number;
+        height?: number;
+        rotation?: number;
+    };
 }
 export interface DriveFakePermission {
     id: string;

package/dist/testing/driveFake.js

@@ -149,6 +149,8 @@ export function createDriveFake() {
             parents: f.parents,
             version: String(f.version ?? 1),
             modifiedTime: f.modifiedTime,
+            thumbnailLink: f.thumbnailLink,
+            imageMediaMetadata: f.imageMediaMetadata,
         };
     }
     async function handleFilesList(url) {

package/dist/testing/gisFake.d.ts

@@ -45,11 +45,55 @@ export interface GisRequestAccessTokenOverride {
 export interface GisTokenClient {
     requestAccessToken(overrideConfig?: GisRequestAccessTokenOverride): void;
 }
+/**
+ * Response delivered to an `initCodeClient` callback — the auth-code
+ * (server-side / PKCE) flow. Mirrors the shape the real GIS code client
+ * passes: `{ code }` on success, `{ error }` on an in-band failure.
+ */
+export interface GisCodeResponse {
+    code?: string;
+    error?: string;
+}
+export interface GisCodeRecordedCall {
+    scope: string;
+    hint?: string;
+}
+export interface GisCodeClientConfig {
+    client_id?: string;
+    scope?: string;
+    hint?: string;
+    ux_mode?: string;
+    redirect_uri?: string;
+    callback?: (response: GisCodeResponse) => void;
+    error_callback?: (error: {
+        type?: string;
+        message?: string;
+    }) => void;
+    [key: string]: unknown;
+}
+export interface GisCodeClient {
+    requestCode(): void;
+}
 export interface GisFake {
     /** All calls made via `requestAccessToken`, in order. */
     calls: GisRecordedCall[];
+    /** All calls made via the code client's `requestCode`, in order. */
+    codeCalls: GisCodeRecordedCall[];
     /** Queue a response to be delivered to the next `requestAccessToken` call. */
     queueResponse(response: GisTokenResponse): void;
+    /**
+     * Queue a response for the next code-client `requestCode()` call, delivered
+     * via `callback` — `{ code }` on success or `{ error }` for an in-band
+     * failure. With nothing queued, `requestCode()` yields `{ code: 'fake-auth-code' }`.
+     */
+    queueCodeResponse(response: GisCodeResponse): void;
+    /**
+     * Queue a popup-level failure for the next `requestCode()` call, delivered
+     * via `error_callback` (e.g. `'popup_closed'`) — the channel the real GIS
+     * code client uses for a blocked/dismissed popup, which never reaches
+     * `callback`.
+     */
+    queueCodeError(type: string): void;
     /**
      * Queue a popup-level failure for the next `requestAccessToken` call,
      * delivered via `error_callback` — the channel the real GIS client uses