@open-webapp/drive-sync 0.1.0 → 0.2.0

package/SPEC.md

@@ -32,6 +32,7 @@ await p.connect();                               // interactive; prompt:'consent
 const conn = await p.getConnection();            // { email, needsReauth, expiresAt } | null
 
 const folderId = await p.ensureFolderPath();
+const token = await p.getAccessToken();          // raw token, for Google Picker's setOAuthToken() only
 const files = await p.files.list({ folderId });
 const text = await p.files.read(fileId);         // string | Blob | null (null on 404)
 const ref = await p.files.write({ folderId, name: 'x.json', content, mimeType: 'application/json' });
@@ -44,7 +45,9 @@ dispose();
 
 `createDriveSync()` itself attaches no listeners and makes no network calls. Every Drive-op call site accepts an optional `{ interactive?: boolean }` (default `false`) and resolves its own token internally — no caller ever threads a token or a `projectId` string into an HTTP call by hand.
 
-Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`), `files.ts`, `permissions.ts`, `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
+Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`/`getAccessToken`), `files.ts`, `permissions.ts`, `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
+
+`getAccessToken()` is the one deliberate exception to `Connection` never exposing secret material (types.ts): it exists solely so an app can feed the token to Google Picker (`setOAuthToken()`), which runs outside this library's control and has no other way to read it. Reuses a cached token while it has more than 5 minutes left; otherwise acquires one (interactive by default, since callers use this to drive a UI the user is actively interacting with).
 
 ## 2. The 34 resolved design decisions
 
@@ -84,7 +87,7 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 28. **No `folderId`/`fileId` persistence** — `ensureFolderPath()` and `write()` both return ids to the caller; nothing in `storage.ts`'s schema has a field for either.
 29. **One IndexedDB DB per project** — `storage.ts`'s `dbName(appId, projectId)` → `owa-drive-{appId}-{projectId}`, opened at version `1` with a single object store named `auth`.
 30. **`conn`/`token` split** — `storage.ts` stores a durable `ConnRecord` under key `'conn'` and an ephemeral `StoredToken` under key `'token'` in the same `auth` store; `clearToken` deletes only the `'token'` key.
-31. **Cross-tab BroadcastChannel — partially wired.** `broadcast.ts` implements `createBroadcast(appId)` with `postLogout`, `postToken`, and `onMessage`, channel-named `owa-drive-{appId}`, feature-detected to a no-op where `BroadcastChannel` is absent. In the shipped code, only `postLogout` is actually called (from `connection.ts`'s `disconnect()`). **Deviation from the plan:** nothing in `src/` calls `onMessage` or `postToken` — there is no listener that reacts to a `logout` broadcast in another tab, and no token-sharing path exists. The plumbing for both exists and is exported/testable, but "logout propagation" and "token sharing" as end-to-end behaviors are not wired up by this package itself; a consuming app would need to call `createBroadcast`/`onMessage` itself if it wants that (and `createBroadcast` is not currently exported from `index.ts`).
+31. **Cross-tab BroadcastChannel — fully wired.** `broadcast.ts` implements `createBroadcast(appId)` with `postLogout`, `postToken`, and `onMessage`, channel-named `owa-drive-{appId}`, feature-detected to a no-op where `BroadcastChannel` is absent. `connection.ts`'s `disconnect()` calls `postLogout`; `token.ts`'s `acquireToken` calls `postToken` after every successful acquisition (interactive `connect()`, silent `refreshSilently()`, and the plain warm-up fallback alike — one choke point right after the token lands in IndexedDB). `index.ts`'s `activate()` subscribes via `onMessage`: a `logout` message evicts this tab's cached IDB handle for that project (`evictDbHandle`) so a subsequent read sees the other tab's cleared storage; a `token` message calls `token.ts`'s `notifyExternalTokenRefresh(projectId)`, which lets this tab's next non-interactive `acquireToken` for that project skip its own GIS round-trip and re-read the fresh token from shared storage instead. Both directions are only live between `activate()` and its disposer — a project handle used without ever calling `.activate()` still reads/writes the same IndexedDB, just without the cross-tab shortcut.
 32. **`reconcile`/`dropProject`** — `reconcile.ts`: `reconcile(appId, knownProjectIds)` enumerates via `indexedDB.databases()` and deletes any `owa-drive-{appId}-*` DB not in the known set; `dropProject(appId, projectId)` deletes one DB eagerly and evicts its cached handle.
 33. **No timer; warm-up on `visibilitychange`/`pageshow`** — `refresh.ts`'s `activate()` attaches both listeners (only when called; none at import time), gated on `document.visibilityState === 'visible'` / `event.persisted && !document.hidden`; `warmUpIfNeeded` only fires if a connection exists **and** the token is missing or within a 5-minute buffer (`REFRESH_BUFFER_MS`) of expiry. `index.ts`'s top-level `activate()` also layers a `trackedProjectIds` Set so one global listener pair drives warm-ups for every project ever passed to `.project(id)`.
 34. **`interactive` option, default `false`** — every `BaseCallOptions`-shaped call in `files.ts`/`permissions.ts`/`http.ts` defaults `interactive` to falsy; a non-interactive call with no usable token throws `NeedsReauthError` rather than silently prompting.
@@ -146,5 +149,5 @@ Wrong-account detection therefore covers exactly two silent paths — the 401-re
 - **`reconcile()` degrades to a no-op** where `indexedDB.databases()` is unsupported (Firefox, older Safari at time of writing). On those browsers, orphaned per-project auth databases from deleted projects are never automatically reclaimed unless the app calls `dropProject(id)` eagerly when it deletes the project — `reconcile()` is a safety net, not the primary cleanup mechanism.
 - **`files.ts`'s `read()` returns `null` on 404**, and that single value conflates two different situations: a genuinely wrong/nonexistent `fileId`, and a file that exists but that the currently-authenticated account cannot see (e.g. connected as the wrong Google account). The library cannot distinguish these — Drive itself returns an identical 404 for both — so callers that want to give an honest error message need to account for both cases themselves.
 - **Wrong-account detection is not universal.** As detailed in §4, it is implemented once, inside `connection.ts`'s `refreshSilently`, and is only reached via two call sites: the 401-triggered silent refresh in `http.ts`, and the proactive warm-up in `refresh.ts` (when a `fetchEmail` resolver is supplied — `index.ts` always supplies one). It is **not** checked on the interactive `connect()` path, and the `refresh.ts` fallback branch that calls `acquireToken` directly (used only when no `fetchEmail` is configured) bypasses it entirely. A non-401 Drive call that succeeds against a token silently swapped to the wrong account (rather than expiring first) would not be caught until some later 401 or explicit `getConnection()`/email check.
-- **Cross-tab `BroadcastChannel` support (`broadcast.ts`) is only half-used.** `postLogout` fires on `disconnect()`, but nothing in the package subscribes via `onMessage`, and `postToken` is never called — see decision #31 above. Multi-tab logout propagation and token sharing are not actual end-to-end behaviors of this package as shipped, only exposed building blocks.
+- **Cross-tab token sharing is best-effort, not a guarantee.** `notifyExternalTokenRefresh` (§4, decision #31) only ever skips ONE subsequent GIS round-trip per `token` broadcast received — a one-shot flag, not a durable "this project is externally fresh" cache. If two tabs both attempt a refresh in the same narrow window, both can still end up making their own GIS calls.
 - **`ensureFolderPath()`'s root-level lookup has no anchor.** Because the library only holds the `drive.file` scope, the first path segment is searched for by name/mimeType with no `in parents` constraint (every subsequent level is unambiguous, anchored to the previous level's id). Two folders with the same name at the top level anywhere the app can see are indistinguishable to this lookup; the first match wins.

package/dist/connection.d.ts

@@ -63,6 +63,30 @@ export interface GetConnectionOptions {
  * granted scopes on the stored connection are missing any required scope.
  */
 export declare function getConnection(opts: GetConnectionOptions): Promise<Connection | null>;
+export interface GetAccessTokenOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    scopes: string[];
+    /** Whether an interactive (popup) auth flow may be triggered if no usable cached token exists. */
+    interactive: boolean;
+    logger?: Logger;
+}
+/**
+ * Returns a raw OAuth access token for callers that must hand it directly to
+ * a Google-hosted widget this library does not control (namely Google
+ * Picker, which requires `setOAuthToken()`). This is a deliberate, narrow
+ * exception to Connection's "no secret material" contract documented in
+ * types.ts: Picker runs in Google's own popup/iframe and has no way to read
+ * a token this library keeps private, so the token must leave the library
+ * for that one integration to work at all. Callers should request this only
+ * to feed it straight to Picker, not to make their own Drive API calls
+ * (use `files`/`permissions` for that).
+ *
+ * Reuses a still-valid cached token as-is; otherwise acquires a fresh one
+ * via the normal token flow (interactive per `opts.interactive`).
+ */
+export declare function getAccessToken(opts: GetAccessTokenOptions): Promise<string>;
 export interface DisconnectOptions {
     appId: string;
     projectId: string;

package/dist/connection.js

@@ -2,6 +2,8 @@ import { getConn, setConn, clearConn, getToken, clearToken } from './storage.js'
 import { createBroadcast } from './broadcast.js';
 import { acquireToken } from './token.js';
 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.
@@ -74,6 +76,35 @@ export async function getConnection(opts) {
         expiresAt: token?.expiresAt ?? null,
     };
 }
+/**
+ * Returns a raw OAuth access token for callers that must hand it directly to
+ * a Google-hosted widget this library does not control (namely Google
+ * Picker, which requires `setOAuthToken()`). This is a deliberate, narrow
+ * exception to Connection's "no secret material" contract documented in
+ * types.ts: Picker runs in Google's own popup/iframe and has no way to read
+ * a token this library keeps private, so the token must leave the library
+ * for that one integration to work at all. Callers should request this only
+ * to feed it straight to Picker, not to make their own Drive API calls
+ * (use `files`/`permissions` for that).
+ *
+ * Reuses a still-valid cached token as-is; otherwise acquires a fresh one
+ * via the normal token flow (interactive per `opts.interactive`).
+ */
+export async function getAccessToken(opts) {
+    const cached = await getToken(opts.appId, opts.projectId);
+    if (cached && cached.expiresAt > Date.now() + TOKEN_REUSE_BUFFER_MS) {
+        return cached.accessToken;
+    }
+    const token = await acquireToken({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        scopes: opts.scopes,
+        interactive: opts.interactive,
+        logger: opts.logger,
+    });
+    return token.accessToken;
+}
 /**
  * Disconnects a project: revokes the cached token (if any and if a
  * revokeFn was supplied), then unconditionally clears both the durable

package/dist/index.d.ts

@@ -40,6 +40,14 @@ export interface ProjectHandle {
     getConnection(): Promise<Connection | null>;
     disconnect(): Promise<void>;
     ensureFolderPath(): Promise<string>;
+    /**
+     * Raw OAuth access token, for handing directly to Google Picker
+     * (`setOAuthToken()`) — see connection.ts's `getAccessToken` for why this
+     * is the one exception to this library otherwise never exposing token
+     * material. `interactive` defaults to true since callers use this to
+     * drive a UI the user is actively interacting with.
+     */
+    getAccessToken(callOpts?: CallOptions): Promise<string>;
     files: FilesHandle;
     permissions: PermissionsHandle;
 }

package/dist/index.js

@@ -1,5 +1,5 @@
 import { noOpLogger } from './logger.js';
-import { connect as connectImpl, getConnection as getConnectionImpl, disconnect as disconnectImpl } from './connection.js';
+import { connect as connectImpl, getConnection as getConnectionImpl, disconnect as disconnectImpl, getAccessToken as getAccessTokenImpl } from './connection.js';
 import { reconcile as reconcileImpl, dropProject as dropProjectImpl } from './reconcile.js';
 import * as filesImpl from './files.js';
 import * as permissionsImpl from './permissions.js';
@@ -194,6 +194,16 @@ export function createDriveSync(options) {
             ensureFolderPath() {
                 return filesImpl.ensureFolderPath({ ...base, folderPath });
             },
+            getAccessToken(callOpts) {
+                return getAccessTokenImpl({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: REQUIRED_SCOPES,
+                    interactive: callOpts?.interactive ?? true,
+                    logger,
+                });
+            },
             files,
             permissions,
         };

package/package.json

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