@open-webapp/drive-sync 0.5.7 → 0.7.0

package/README.md

@@ -42,6 +42,59 @@ See `SPEC.md` for the full design: the 36 resolved decisions, storage layout,
 and refresh state machine. `SPEC.md` is descriptive, written from the shipped
 code — if it ever disagrees with the source, the source wins.
 
+## Server-facilitated token exchange
+
+By default the library runs the legacy GIS flow: an implicit-style access token
+acquired in the browser, refreshed silently through GIS, with no
+`refresh_token` anywhere. Pass `tokenExchangeUrl` to `createDriveSync` to opt in
+to the server-facilitated variant instead:
+
+```ts
+import { createDriveSync } from '@open-webapp/drive-sync'
+
+const drive = createDriveSync({
+  appId: 'my-app',
+  clientId: 'xxx.apps.googleusercontent.com',
+  folderPath: ['MyApp', 'Data'],
+  tokenExchangeUrl: 'https://open-webapp.duckdns.org/callback',
+})
+```
+
+**Code → envelope → replay.** With `tokenExchangeUrl` set, `connect()` uses
+GIS `initCodeClient` (popup) to obtain a one-time authorization **code**, then
+`POST {tokenExchangeUrl}` with `{ code }`. The server does the code→token
+exchange, keeps the `refresh_token` server-side, and returns a signed, opaque
+**envelope** `{ v, guid, payload, sig }` whose `payload` carries the
+`access_token`, `expiry_date`, and `scope`. The client persists the whole
+envelope verbatim and derives its normal `token` record from `payload`.
+
+**Replay for refresh.** When the access token is stale, the client does not
+talk to GIS — it replays the stored envelope byte-for-byte:
+`POST {tokenExchangeUrl}` with `{ envelope }`. The server mints a fresh access
+token from its stored `refresh_token` and returns a new envelope, which
+replaces the stored one. A local freshness check skips the network entirely
+while the current token is still outside the 5-minute refresh buffer, and
+concurrent refreshes for the same `projectId` are coalesced.
+
+**`refresh_token` stays server-side.** The client never sees or stores a
+`refresh_token`; it only ever holds the opaque envelope and replays it. The
+`sig` is a server signature that is **never** verified client-side — the
+envelope is treated as fully opaque.
+
+**Opt-in / legacy path unchanged.** When `tokenExchangeUrl` is absent,
+`connect()`, refresh, and `disconnect()` behave exactly as before (GIS token
+client, silent refresh, no envelope). Nothing about the legacy flow changes.
+
+**CORS.** The reference exchange server's CORS allowlist is
+`https://notesdiary.github.io` and `https://open-webapp.github.io` **only**,
+with credentials disabled. `localhost` is not on the allowlist, so the
+`drive-sync-oauth-tester` app runs its requests through a Vite dev-server proxy
+that rewrites the `Origin` header to `https://open-webapp.github.io` (an
+Origin-spoof proxy) — without it the browser blocks the exchange call.
+
+The full request/response contract is documented at
+`https://open-webapp.duckdns.org/callback-api.md`.
+
 ## Testing
 
 Import fakes for GIS and Drive from the `./testing` subpath:

package/SPEC.md

@@ -50,7 +50,7 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 `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 36 resolved design decisions
+## 2. The 41 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
 
@@ -101,14 +101,23 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 38. **`files.update()` provides metadata-only, baseline-preserving updates** — `files.ts` now exports an `update()` method that rewrites a file's metadata (name, description, mimeType, etc.) without modifying its content or version history. The update is guaranteed to preserve the file's baseline content: if a concurrent write to the same file completes between the read and update, the `update()` call will fail with a conflict error rather than silently clobbering the concurrent change. This gives apps a way to rename/reclassify a file after upload without risking accidental content loss. The method is content-agnostic, accepting only metadata fields and refusing any content-bearing parameter.
 
+39. **Server-facilitated token exchange is opt-in via `tokenExchangeUrl`** — `DriveSyncOptions.tokenExchangeUrl` (`types.ts`). When absent, every path (`connect()`, refresh, `disconnect()`) is the legacy GIS implicit-token flow, unchanged. When set, `connection.ts`'s `connect()` branches to `connectViaEnvelope`: `gis.ts`'s `acquireAuthCode` runs GIS `google.accounts.oauth2.initCodeClient` (popup) to get a one-time authorization **code** — no `redirect_uri`, no `state`, no `prompt` knob — then `envelope.ts`'s `postExchange`/`postExchangeWithRetry` does `POST {tokenExchangeUrl}` with `{ code }` (`Content-Type: application/json`, no credentials, no custom headers) and parses a `{ envelope }` response. The whole `Envelope` (`{ v: 2, guid, payload, sig }`, `types.ts`) is persisted verbatim under a new `envelope` key in the per-project `auth` store; the normal `token` record is derived from `payload` via `deriveToken`. The external request/response contract is the callback API doc at `https://open-webapp.duckdns.org/callback-api.md`.
+
+40. **`refreshEnvelope` — freshness-gated, coalesced, cross-tab envelope replay** — `envelope.ts`'s `refreshEnvelope` is the refresh path when `tokenExchangeUrl` is set; `acquireToken`/GIS is never reached, so no popup can appear. It (1) drains any cross-tab envelope-refresh signal for the project, (2) reads the stored envelope — absent envelope → `NeedsReauthError` (`reason: 'exchange_failed'`), (3) if `payload.expiry_date` is still outside the `REFRESH_BUFFER_MS` (5-minute) window, returns the derived token with **no network call**, (4) otherwise replays the stored envelope byte-for-byte: `POST {tokenExchangeUrl}` with `{ envelope }`, persists the returned envelope + derived token, and fires a cross-tab `token` broadcast. Concurrent calls for the same `projectId` are coalesced onto one in-flight promise (`inFlightEnvelope` map, mirroring `token.ts`'s `inFlight`).
+
+41. **Envelope error mapping, opaque `sig`, no schema bump** — `envelope.ts` maps exchange failures onto typed reauth reasons: `410` → clear conn+token+envelope, then `NeedsReauthError` (`reason: 'refresh_token_revoked'`, surfaced internally as the distinguishable `EnvelopeRevokedError` subclass); `502` / other `5xx` / network throw / unparseable body → up to two retries (500ms, 1500ms) then `NeedsReauthError` (`reason: 'exchange_unavailable'`); other non-2xx (`400`/`401`/`404`/`403`/`409`) → `NeedsReauthError` (`reason: 'exchange_failed'`), no retry. The envelope's `sig` is a server signature that is **never** verified client-side — the structure is treated as fully opaque and only `payload` is read. The `envelope` key is added to the existing `auth` store with **no IndexedDB version bump** (still version 1).
+
+42. **`list()` passes through `thumbnailLink` + `imageMediaMetadata`, unfiltered and verbatim** — `files.ts`'s `list()` extends the same `fields` mask touched in #36's `modifiedTime` change to also request `thumbnailLink` and `imageMediaMetadata(width,height,rotation)`; `FileRef` (`types.ts`) gains three optional fields — `mimeType?` (already fetched, previously just untyped), `thumbnailLink?`, and `imageMediaMetadata?: { width?; height?; rotation? }` — all `fields`-gated and may be absent on older or partial responses. `list()` stays unfiltered: it returns every file of any MIME type with no `image/` check and no opt-in flag, and `thumbnailLink` is passed through exactly as Drive returns it — no blob fetch, no URL rewrite, no `=s220` size munging, and no `files.thumbnail()` helper. Caveat: `thumbnailLink` is a short-lived URL (good for only ~hours) that can require the browser to be carrying Google auth context for the file's owning account, so a cross-origin bare `<img src>` may 403; rendering is the consuming app's responsibility, and it can fall back to `getAccessToken()` + fetch-to-blob itself. (Label is `42` though this is only the 41st entry — the section carries a duplicate `7.` label and a merged `25–27.` entry, so the labels have always run one ahead of the item count; no existing entry is renumbered.)
+
 ## 3. Storage layout
 
-Each project gets its own IndexedDB database: **`owa-drive-{appId}-{projectId}`**, version 1, containing one object store, `auth` (`storage.ts`). The store holds exactly two keys:
+Each project gets its own IndexedDB database: **`owa-drive-{appId}-{projectId}`**, version 1, containing one object store, `auth` (`storage.ts`). The store holds up to three keys (`conn`/`token` always; `envelope` only in server-facilitated token-exchange mode):
 
 | Key | Shape | Lifetime |
 |---|---|---|
-| `conn` | `{ email, grantedScopes: string[], connectedAt: number }` | Durable — survives token expiry. Written by `connect()`. Cleared only by `disconnect()`. |
-| `token` | `{ accessToken, expiresAt, grantedScopes: string[] }` | Ephemeral. Written by `persistTokenResponse()` on every successful token acquisition. Cleared on 401 (`http.ts`), on `ScopeInsufficientError` (`http.ts`), on a detected wrong-account mismatch (`connection.ts`'s `refreshSilently`), and by `disconnect()`. |
+| `conn` | `{ email, grantedScopes: string[], connectedAt: number }` | Durable — survives token expiry. Written by `connect()`. Cleared only by `disconnect()` (and by the `410` envelope-revoked path). |
+| `token` | `{ accessToken, expiresAt, grantedScopes: string[] }` | Ephemeral. Written by `persistTokenResponse()` on every successful token acquisition, and by `refreshEnvelope`/`connectViaEnvelope` (derived from the envelope `payload`) in token-exchange mode. Cleared on 401 (`http.ts`), on `ScopeInsufficientError` (`http.ts`), on a detected wrong-account mismatch (`connection.ts`'s `refreshSilently`), on the `410` envelope-revoked path, and by `disconnect()`. |
+| `envelope` | `{ v: 2, guid, payload, sig }` (the whole opaque `Envelope`) | Present only when `tokenExchangeUrl` is configured. Written verbatim by `connectViaEnvelope()` and replaced on every successful `refreshEnvelope()`. Cleared by `disconnect()` (unconditionally) and on the `410` envelope-revoked path. Never version-bumps the store. |
 
 Open handles are cached in-process in a `Map<string, Promise<IDBPDatabase>>` keyed by `${appId}:${projectId}` (`storage.ts`'s `dbCache`), so repeated calls for the same project reuse one connection. `evictDbHandle` closes and drops that cache entry without deleting the underlying database — the deletion itself only happens in `reconcile.ts`.
 
@@ -156,6 +165,8 @@ Concretely, by module:
 - **`refresh.ts`**'s `warmUpIfNeeded` is the proactive path: fired from `visibilitychange`→`visible` and `pageshow`(persisted, not hidden) listeners attached by `activate()`. It only acts if a `conn` record exists **and** the cached token is missing or within `REFRESH_BUFFER_MS` (5 minutes) of `expiresAt`. When a `fetchEmail` is configured it goes through `refreshSilently` (so wrong-account detection also covers this path); otherwise it falls back to a bare `acquireToken`. It never *starts* a new attempt while the document is hidden — visibility is checked before it is ever called, so an attempt already in flight from before the tab hid is left to finish on its own.
 - **`index.ts`**'s top-level `activate()` layers one global listener pair over `refresh.ts`'s per-call logic: it tracks every `projectId` ever passed to `.project(id)` in a `Set` and, on each visibility/pageshow event, calls `warmUpIfNeeded` for all of them (read live at fire time, so late-registered projects are still covered).
 
+**Envelope branch (server-facilitated token-exchange mode).** When `tokenExchangeUrl` is configured, `connection.ts`'s `refreshSilently` short-circuits to `envelope.ts`'s `refreshEnvelope` and the entire GIS state machine above is bypassed — no `initTokenClient`, no `prompt:'none'`, no popup. `refreshEnvelope` does a local freshness check against the stored envelope's `payload.expiry_date` (± `REFRESH_BUFFER_MS`); if fresh it returns the derived token with no network call, otherwise it echoes-or-replays the stored envelope via `POST {tokenExchangeUrl}` with `{ envelope }`, persists the new envelope + derived `token`, and broadcasts a cross-tab `token` message. A `410` (server-side refresh token revoked) clears `conn` + `token` + `envelope` and throws `NeedsReauthError` (`reason: 'refresh_token_revoked'`); `502`/`5xx`/network → retried then `exchange_unavailable`; a missing envelope or other `4xx` → `exchange_failed`. In this mode there is no wrong-account check (the server owns the identity) and the interactive `connect()` path is `connectViaEnvelope` (auth-code leg + `POST { code }`) rather than an implicit token grant.
+
 Wrong-account detection therefore covers exactly two silent paths — the 401-retry-once in `http.ts` and the proactive warm-up in `refresh.ts`/`index.ts` — both of which are wired through `refreshSilently`. It does **not** cover the interactive `connect()` path (a user consenting is trusted at face value) nor any refresh path where the caller omitted `fetchEmail` (the `refresh.ts` fallback branch and any hand-rolled use of `acquireToken` directly).
 
 ## 5. Known limitations / accepted tradeoffs
@@ -165,3 +176,10 @@ Wrong-account detection therefore covers exactly two silent paths — the 401-re
 - **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 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.
+
+**Server-facilitated token-exchange mode (`tokenExchangeUrl` set):**
+
+- **Orphaned server-side `<guid>/perm-token.json` is never cleaned up.** The exchange server persists one `refresh_token` file per envelope `guid`, and there is no revoke endpoint. `disconnect()` only revokes the current *access* token (killing the live grant); it cannot tell the server to delete the stored `refresh_token`. Every `connect()` that mints a new `guid` leaves the previous server-side record behind indefinitely.
+- **A re-`connect()` may be un-refreshable server-side.** Google returns a `refresh_token` only on the *first* consent per (user, client), and GIS `initCodeClient` exposes no `prompt` knob to force re-consent. If a later `connect()` produces a fresh `guid` but Google returns no `refresh_token` for it, the server has nothing to replay and that envelope cannot be refreshed — the user is stuck on the access token's lifetime until a consent screen is shown by some other means.
+- **The tester needs an Origin-spoof proxy.** The reference server's CORS allowlist is `https://notesdiary.github.io` and `https://open-webapp.github.io` only, with credentials disabled; `localhost` is not allowed. `apps/drive-sync-oauth-tester` therefore routes exchange requests through a Vite dev-server proxy that rewrites the `Origin` header to `https://open-webapp.github.io`. See `https://open-webapp.duckdns.org/callback-api.md` for the contract.
+- **The server's `GOOGLE_REDIRECT_URI` is assumed to be `postmessage`.** Popup-mode code exchange (`initCodeClient` → `POST { code }`) only works if the server exchanges the code against `redirect_uri = 'postmessage'`. This is a server-side assumption that has not been verified against the deployed server; a mismatch would make `connectViaEnvelope` fail at the exchange step.

package/dist/connection.d.ts

@@ -13,11 +13,22 @@ export interface ConnectOptions {
      * against the Google userinfo endpoint once http.ts exists.
      */
     fetchEmail: (accessToken: string) => Promise<string>;
+    /**
+     * When set, `connect()` takes the server-mediated token-exchange path:
+     * it acquires a one-time auth CODE via GIS (never an access token) and
+     * POSTs it to this endpoint, which returns a signed {@link Envelope}. The
+     * durable refresh token stays server-side. Absent, `connect()` runs the
+     * legacy client-side `initTokenClient` flow unchanged.
+     */
+    tokenExchangeUrl?: string;
 }
 /**
  * Interactive connection flow: acquires a token without forcing a consent
  * screen, resolves the account email, and persists the durable Connection
  * record.
+ *
+ * With `opts.tokenExchangeUrl` set, runs the envelope (server-mediated
+ * token-exchange) variant instead — see {@link connectViaEnvelope}.
  */
 export declare function connect(opts: ConnectOptions): Promise<Connection>;
 export interface RefreshSilentlyOptions {
@@ -72,6 +83,15 @@ export interface GetAccessTokenOptions {
     /** Whether an interactive (popup) auth flow may be triggered if no usable cached token exists. */
     interactive: boolean;
     logger?: Logger;
+    /**
+     * When set, `getAccessToken()` takes the server-mediated token-exchange
+     * path: a stale/absent cached token is renewed via {@link refreshEnvelope}
+     * (which POSTs the stored envelope to this endpoint) rather than an
+     * interactive GIS code/token flow. A missing envelope surfaces as a
+     * `NeedsReauthError` from `refreshEnvelope` — no popup is ever shown.
+     * Absent, the legacy client-side flow runs unchanged.
+     */
+    tokenExchangeUrl?: string;
 }
 /**
  * Returns a raw OAuth access token for callers that must hand it directly to
@@ -100,10 +120,17 @@ export interface DisconnectOptions {
      * revoke.
      */
     revokeFn?: (accessToken: string) => Promise<void>;
+    /**
+     * Accepted for symmetry with the other flows (connect / getAccessToken).
+     * `disconnect` clears the `envelope` key unconditionally regardless of
+     * whether this is set, so this field is currently informational only.
+     */
+    tokenExchangeUrl?: string;
 }
 /**
  * Disconnects a project: revokes the cached token (if any and if a
- * revokeFn was supplied), then unconditionally clears both the durable
- * connection and the cached token, and broadcasts a logout to other tabs.
+ * revokeFn was supplied), then unconditionally clears the durable
+ * connection, the cached token, and the stored envelope key, and
+ * broadcasts a logout to other tabs.
  */
 export declare function disconnect(opts: DisconnectOptions): Promise<void>;

package/dist/connection.js

@@ -1,15 +1,23 @@
-import { getConn, setConn, clearConn, getToken, clearToken } from './storage.js';
+import { getConn, setConn, clearConn, getToken, clearToken, setEnvelope, setToken, clearEnvelope, } from './storage.js';
 import { createBroadcast } from './broadcast.js';
 import { acquireToken } from './token.js';
-import { WrongAccountError } from './errors.js';
+import { acquireAuthCode } from './gis.js';
+import { deriveToken, postExchange, postExchangeWithRetry, refreshEnvelope, EnvelopeRevokedError, } from './envelope.js';
+import { NeedsReauthError, 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 without forcing a consent
  * screen, resolves the account email, and persists the durable Connection
  * record.
+ *
+ * With `opts.tokenExchangeUrl` set, runs the envelope (server-mediated
+ * token-exchange) variant instead — see {@link connectViaEnvelope}.
  */
 export async function connect(opts) {
+    if (opts.tokenExchangeUrl) {
+        return connectViaEnvelope(opts, opts.tokenExchangeUrl);
+    }
     // On a re-auth the previous connection's email is the account the user is
     // expected to consent as again; pass it as a hint so the popup_closed
     // recovery probe (token.ts) can resolve a completed grant silently even
@@ -37,6 +45,63 @@ export async function connect(opts) {
         expiresAt: token.expiresAt,
     };
 }
+/**
+ * Server-mediated token-exchange connect:
+ *  1. read the stored conn (for the account `hint` only);
+ *  2. acquire a one-time auth CODE via GIS (never touches `acquireToken` /
+ *     `initTokenClient`);
+ *  3. POST the code to the exchange endpoint for a signed envelope, retrying
+ *     transient failures via `postExchangeWithRetry`;
+ *  4. persist envelope + derived token + durable conn;
+ *  5. resolve the email once (no wrong-account compare — a fresh interactive
+ *     grant is authoritative about which account it belongs to).
+ *
+ * An {@link EnvelopeRevokedError} (410) additionally clears conn+token+envelope
+ * before propagating; every other {@link NeedsReauthError} propagates as-is.
+ */
+async function connectViaEnvelope(opts, tokenExchangeUrl) {
+    const existing = await getConn(opts.appId, opts.projectId);
+    const code = await acquireAuthCode({
+        clientId: opts.clientId,
+        scopes: opts.scopes,
+        hint: existing?.email,
+        logger: opts.logger,
+    });
+    let envelope;
+    try {
+        envelope = await postExchange(tokenExchangeUrl, { code }, opts.logger);
+    }
+    catch (err) {
+        if (err instanceof EnvelopeRevokedError) {
+            await clearConn(opts.appId, opts.projectId);
+            await clearToken(opts.appId, opts.projectId);
+            await clearEnvelope(opts.appId, opts.projectId);
+            throw err;
+        }
+        // A non-retryable rejection (400/401/404) surfaces as a plain
+        // NeedsReauthError from postExchange — propagate it untouched.
+        if (err instanceof NeedsReauthError) {
+            throw err;
+        }
+        // Anything else is a transient (network / 502 / unparseable) failure:
+        // fall through to the retrying variant.
+        envelope = await postExchangeWithRetry(tokenExchangeUrl, { code }, opts.logger);
+    }
+    await setEnvelope(opts.appId, opts.projectId, envelope);
+    const token = deriveToken(envelope.payload);
+    await setToken(opts.appId, opts.projectId, token);
+    const email = await opts.fetchEmail(token.accessToken);
+    await setConn(opts.appId, opts.projectId, {
+        email,
+        grantedScopes: token.grantedScopes,
+        connectedAt: Date.now(),
+    });
+    return {
+        email,
+        needsReauth: false,
+        expiresAt: token.expiresAt,
+    };
+}
 /**
  * Wraps a non-interactive `acquireToken` call with account-identity
  * verification: after GIS hands back a token, resolves the email it
@@ -103,6 +168,18 @@ export async function getAccessToken(opts) {
     if (cached && cached.expiresAt > Date.now() + TOKEN_REUSE_BUFFER_MS) {
         return cached.accessToken;
     }
+    // Server-mediated token-exchange mode: renew via the stored envelope, never
+    // an interactive code/token flow. A missing envelope surfaces as a
+    // NeedsReauthError from refreshEnvelope — acquireToken is never reached.
+    if (opts.tokenExchangeUrl) {
+        const token = await refreshEnvelope({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            tokenExchangeUrl: opts.tokenExchangeUrl,
+            logger: opts.logger,
+        });
+        return token.accessToken;
+    }
     // Same rationale as connect(): hand the known account email to the
     // popup_closed recovery probe so it can pick up a completed grant silently.
     const existing = await getConn(opts.appId, opts.projectId);
@@ -119,8 +196,9 @@ export async function getAccessToken(opts) {
 }
 /**
  * Disconnects a project: revokes the cached token (if any and if a
- * revokeFn was supplied), then unconditionally clears both the durable
- * connection and the cached token, and broadcasts a logout to other tabs.
+ * revokeFn was supplied), then unconditionally clears the durable
+ * connection, the cached token, and the stored envelope key, and
+ * broadcasts a logout to other tabs.
  */
 export async function disconnect(opts) {
     const token = await getToken(opts.appId, opts.projectId);
@@ -129,5 +207,6 @@ export async function disconnect(opts) {
     }
     await clearConn(opts.appId, opts.projectId);
     await clearToken(opts.appId, opts.projectId);
+    await clearEnvelope(opts.appId, opts.projectId);
     createBroadcast(opts.appId).postLogout(opts.projectId);
 }

package/dist/envelope.d.ts

@@ -0,0 +1,73 @@
+import { NeedsReauthError } from './errors.js';
+import type { Logger } from './logger.js';
+import type { Envelope, EnvelopePayload, StoredToken } from './types.js';
+/**
+ * Distinguishable 410 sentinel: the server-side refresh token was revoked, so
+ * every stored credential for this project is now worthless. It IS a
+ * `NeedsReauthError` (`reason: 'refresh_token_revoked'`) so a caller that does
+ * not special-case it still does the right, if lossy, thing; callers that want
+ * to also wipe conn+token+envelope test `err instanceof EnvelopeRevokedError`.
+ */
+export declare class EnvelopeRevokedError extends NeedsReauthError {
+    constructor(message?: string);
+}
+/**
+ * Project an {@link EnvelopePayload} onto the {@link StoredToken} shape the
+ * rest of drive-sync persists. Pure; no I/O.
+ */
+export declare function deriveToken(payload: EnvelopePayload): StoredToken;
+/**
+ * POST `body` to the token-exchange endpoint once and return the `envelope`
+ * from a 2xx `{ envelope }` response.
+ *
+ * Throws:
+ *  - {@link EnvelopeRevokedError} on a 410 (`code === 'refresh_token_revoked'`
+ *    or a bare 410) — no retry.
+ *  - {@link EnvelopeRetryableError} on a 502 / 5xx / network throw / unparseable
+ *    body — the retry wrapper handles these.
+ *  - {@link NeedsReauthError} (`reason: 'exchange_failed'`) on a 400 / 401 / 404
+ *    — logs and does not retry.
+ */
+export declare function postExchange(url: string, body: {
+    code: string;
+} | {
+    envelope: Envelope;
+}, logger?: Logger): Promise<Envelope>;
+/**
+ * {@link postExchange} with transient-failure retries: on a retryable error
+ * wait 500ms and retry, on a second retryable error wait 1500ms and retry,
+ * then give up with {@link NeedsReauthError} (`reason: 'exchange_unavailable'`).
+ *
+ * Non-retryable errors ({@link EnvelopeRevokedError}, the `exchange_failed`
+ * {@link NeedsReauthError}) propagate immediately, unretried.
+ */
+export declare function postExchangeWithRetry(url: string, body: {
+    code: string;
+} | {
+    envelope: Envelope;
+}, logger?: Logger): Promise<Envelope>;
+export interface RefreshEnvelopeOptions {
+    appId: string;
+    projectId: string;
+    tokenExchangeUrl: string;
+    logger?: Logger;
+}
+/**
+ * Freshness-gated, coalesced envelope refresh for the server-mediated
+ * token-exchange mode.
+ *
+ * 1. Drains any pending cross-tab envelope-refresh signal for this project
+ *    (so a fresh envelope another tab just persisted is picked up here).
+ * 2. Reads the stored envelope. No envelope means "not connected in this
+ *    mode" -> {@link NeedsReauthError} (`reason: 'exchange_failed'`).
+ * 3. If the stored access token is still outside the {@link REFRESH_BUFFER_MS}
+ *    window, returns {@link deriveToken}(payload) with NO network call.
+ * 4. Otherwise POSTs `{ envelope }` via {@link postExchangeWithRetry}. On the
+ *    410 {@link EnvelopeRevokedError} sentinel it clears conn + token +
+ *    envelope and re-throws a plain `NeedsReauthError`
+ *    (`reason: 'refresh_token_revoked'`); on success it persists the new
+ *    envelope + derived token, fires a cross-tab `token` broadcast, and
+ *    returns the derived token.
+ * 5. Concurrent calls for the same `projectId` are coalesced onto one promise.
+ */
+export declare function refreshEnvelope(opts: RefreshEnvelopeOptions): Promise<StoredToken>;

package/dist/envelope.js

@@ -0,0 +1,231 @@
+/**
+ * Server-mediated token-exchange transport.
+ *
+ * This module owns the HTTP conversation with the token-exchange endpoint
+ * (`DriveSyncOptions.tokenExchangeUrl`): POSTing an auth `code` or a stored
+ * `envelope`, parsing the `{ envelope }` response, mapping failures onto typed
+ * {@link NeedsReauthError}s, and retrying the transient ones.
+ *
+ * It deliberately has NO knowledge of storage: it never clears the connection,
+ * token, or envelope records. The one failure that requires a clear — a `410`
+ * saying the server-side refresh token was revoked — is surfaced as a
+ * distinguishable {@link EnvelopeRevokedError} (a tagged subclass of
+ * `NeedsReauthError`, `reason: 'refresh_token_revoked'`). T4/T6 callers detect
+ * it with `instanceof EnvelopeRevokedError` and run the
+ * clear-conn+token+envelope themselves.
+ */
+import { createBroadcast } from './broadcast.js';
+import { NeedsReauthError } from './errors.js';
+import { REFRESH_BUFFER_MS } from './refresh.js';
+import { clearConn, clearEnvelope, clearToken, getEnvelope, setEnvelope, setToken, } from './storage.js';
+import { consumeExternalEnvelopeRefresh } from './token.js';
+/**
+ * Distinguishable 410 sentinel: the server-side refresh token was revoked, so
+ * every stored credential for this project is now worthless. It IS a
+ * `NeedsReauthError` (`reason: 'refresh_token_revoked'`) so a caller that does
+ * not special-case it still does the right, if lossy, thing; callers that want
+ * to also wipe conn+token+envelope test `err instanceof EnvelopeRevokedError`.
+ */
+export class EnvelopeRevokedError extends NeedsReauthError {
+    constructor(message = 'Server-side refresh token was revoked') {
+        super(message, { status: 410, reason: 'refresh_token_revoked' });
+        this.name = 'EnvelopeRevokedError';
+    }
+}
+/**
+ * Internal marker for a failure worth retrying (a 502, a 5xx, a network-level
+ * throw, or an unparseable body). Never escapes this module: the retry wrapper
+ * either retries past it or converts it to `NeedsReauthError`
+ * (`reason: 'exchange_unavailable'`).
+ */
+class EnvelopeRetryableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvelopeRetryableError';
+    }
+}
+/** Real-timer delay. Vitest fake timers still drive this via advanceTimersByTimeAsync. */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const RETRY_DELAYS_MS = [500, 1500];
+/**
+ * Project an {@link EnvelopePayload} onto the {@link StoredToken} shape the
+ * rest of drive-sync persists. Pure; no I/O.
+ */
+export function deriveToken(payload) {
+    return {
+        accessToken: payload.access_token,
+        expiresAt: payload.expiry_date,
+        grantedScopes: payload.scope.split(' ').filter(Boolean),
+    };
+}
+/**
+ * POST `body` to the token-exchange endpoint once and return the `envelope`
+ * from a 2xx `{ envelope }` response.
+ *
+ * Throws:
+ *  - {@link EnvelopeRevokedError} on a 410 (`code === 'refresh_token_revoked'`
+ *    or a bare 410) — no retry.
+ *  - {@link EnvelopeRetryableError} on a 502 / 5xx / network throw / unparseable
+ *    body — the retry wrapper handles these.
+ *  - {@link NeedsReauthError} (`reason: 'exchange_failed'`) on a 400 / 401 / 404
+ *    — logs and does not retry.
+ */
+export async function postExchange(url, body, logger) {
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        // Network-level failure (DNS, offline, connection reset, CORS abort).
+        throw new EnvelopeRetryableError(`token exchange request failed: ${err?.message ?? String(err)}`);
+    }
+    if (res.ok) {
+        let parsed;
+        try {
+            parsed = (await res.json());
+        }
+        catch {
+            throw new EnvelopeRetryableError('token exchange returned a non-JSON 2xx body');
+        }
+        return parsed.envelope;
+    }
+    // Non-2xx: try to read a structured { error: { code } }.
+    let errBody;
+    let bodyParsed = false;
+    try {
+        errBody = (await res.json());
+        bodyParsed = true;
+    }
+    catch {
+        bodyParsed = false;
+    }
+    const code = errBody?.error?.code;
+    if (res.status === 410) {
+        // Revoked server-side refresh token — everything stored is dead.
+        throw new EnvelopeRevokedError(code === 'refresh_token_revoked'
+            ? 'Server reported the refresh token was revoked (410)'
+            : 'Token exchange endpoint returned 410');
+    }
+    if (res.status === 400 || res.status === 401 || res.status === 404) {
+        logger?.error(`drive-sync: token exchange failed (${res.status}${code ? ` ${code}` : ''}); reauth required`);
+        throw new NeedsReauthError('Token exchange rejected the request', {
+            status: res.status,
+            reason: 'exchange_failed',
+        });
+    }
+    // 502, other 5xx, or an unreadable body: worth another try.
+    if (res.status === 502 || res.status >= 500 || !bodyParsed) {
+        throw new EnvelopeRetryableError(`token exchange transient failure (${res.status})`);
+    }
+    // Any other unexpected non-2xx (e.g. 403, 409): treat as non-retryable reauth.
+    logger?.error(`drive-sync: token exchange failed (${res.status}${code ? ` ${code}` : ''}); reauth required`);
+    throw new NeedsReauthError('Token exchange rejected the request', {
+        status: res.status,
+        reason: 'exchange_failed',
+    });
+}
+/**
+ * {@link postExchange} with transient-failure retries: on a retryable error
+ * wait 500ms and retry, on a second retryable error wait 1500ms and retry,
+ * then give up with {@link NeedsReauthError} (`reason: 'exchange_unavailable'`).
+ *
+ * Non-retryable errors ({@link EnvelopeRevokedError}, the `exchange_failed`
+ * {@link NeedsReauthError}) propagate immediately, unretried.
+ */
+export async function postExchangeWithRetry(url, body, logger) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await postExchange(url, body, logger);
+        }
+        catch (err) {
+            if (!(err instanceof EnvelopeRetryableError))
+                throw err;
+            if (attempt >= RETRY_DELAYS_MS.length) {
+                throw new NeedsReauthError('Token exchange service is unavailable', {
+                    reason: 'exchange_unavailable',
+                });
+            }
+            await delay(RETRY_DELAYS_MS[attempt]);
+        }
+    }
+}
+/**
+ * Per-`projectId` coalescing map for {@link refreshEnvelope}, mirroring the
+ * `inFlight` pattern in token.ts: concurrent callers for the same project
+ * share a single in-flight promise, and the entry is removed in a `finally`
+ * once it settles (success or failure) so the next call starts fresh.
+ */
+const inFlightEnvelope = new Map();
+/**
+ * Freshness-gated, coalesced envelope refresh for the server-mediated
+ * token-exchange mode.
+ *
+ * 1. Drains any pending cross-tab envelope-refresh signal for this project
+ *    (so a fresh envelope another tab just persisted is picked up here).
+ * 2. Reads the stored envelope. No envelope means "not connected in this
+ *    mode" -> {@link NeedsReauthError} (`reason: 'exchange_failed'`).
+ * 3. If the stored access token is still outside the {@link REFRESH_BUFFER_MS}
+ *    window, returns {@link deriveToken}(payload) with NO network call.
+ * 4. Otherwise POSTs `{ envelope }` via {@link postExchangeWithRetry}. On the
+ *    410 {@link EnvelopeRevokedError} sentinel it clears conn + token +
+ *    envelope and re-throws a plain `NeedsReauthError`
+ *    (`reason: 'refresh_token_revoked'`); on success it persists the new
+ *    envelope + derived token, fires a cross-tab `token` broadcast, and
+ *    returns the derived token.
+ * 5. Concurrent calls for the same `projectId` are coalesced onto one promise.
+ */
+export async function refreshEnvelope(opts) {
+    const existing = inFlightEnvelope.get(opts.projectId);
+    if (existing) {
+        return existing;
+    }
+    const promise = refreshEnvelopeUncoalesced(opts);
+    inFlightEnvelope.set(opts.projectId, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        inFlightEnvelope.delete(opts.projectId);
+    }
+}
+async function refreshEnvelopeUncoalesced(opts) {
+    const { appId, projectId, tokenExchangeUrl, logger } = opts;
+    // A cross-tab signal only tells us to re-read storage; the durable copy is
+    // IndexedDB. Draining it here is a no-op beyond the getEnvelope() below,
+    // but keeps the "consume the one-shot signal" contract explicit.
+    consumeExternalEnvelopeRefresh(projectId);
+    const envelope = await getEnvelope(appId, projectId);
+    if (!envelope) {
+        throw new NeedsReauthError('No stored envelope; connect is required', {
+            reason: 'exchange_failed',
+        });
+    }
+    if (Date.now() < envelope.payload.expiry_date - REFRESH_BUFFER_MS) {
+        return deriveToken(envelope.payload);
+    }
+    let refreshed;
+    try {
+        refreshed = await postExchangeWithRetry(tokenExchangeUrl, { envelope }, logger);
+    }
+    catch (err) {
+        if (err instanceof EnvelopeRevokedError) {
+            await clearConn(appId, projectId);
+            await clearToken(appId, projectId);
+            await clearEnvelope(appId, projectId);
+            throw new NeedsReauthError('Server-side refresh token was revoked', {
+                status: 410,
+                reason: 'refresh_token_revoked',
+            });
+        }
+        throw err;
+    }
+    const token = deriveToken(refreshed.payload);
+    await setEnvelope(appId, projectId, refreshed);
+    await setToken(appId, projectId, token);
+    createBroadcast(appId).postToken(projectId);
+    return token;
+}

package/dist/errors.d.ts

@@ -16,6 +16,14 @@ export declare class DriveSyncError extends Error {
 /**
  * Thrown when no usable token exists and the requested call is
  * non-interactive (so no popup/redirect flow may be triggered to obtain one).
+ *
+ * Known `reason` values:
+ *  - `popup_closed`, `gis_timeout`, `gis_error` — legacy GIS implicit flow (token.ts).
+ *  - `refresh_token_revoked` — server-mediated exchange, 410; carried by the
+ *    `EnvelopeRevokedError` subclass (envelope.ts). Caller must additionally
+ *    clear conn+token+envelope.
+ *  - `exchange_failed` — server-mediated exchange, 400/401/404; not retryable.
+ *  - `exchange_unavailable` — server-mediated exchange, still 502/5xx after retries.
  */
 export declare class NeedsReauthError extends DriveSyncError {
     constructor(message?: string, opts?: DriveSyncErrorOptions);

package/dist/errors.js

@@ -17,6 +17,14 @@ export class DriveSyncError extends Error {
 /**
  * Thrown when no usable token exists and the requested call is
  * non-interactive (so no popup/redirect flow may be triggered to obtain one).
+ *
+ * Known `reason` values:
+ *  - `popup_closed`, `gis_timeout`, `gis_error` — legacy GIS implicit flow (token.ts).
+ *  - `refresh_token_revoked` — server-mediated exchange, 410; carried by the
+ *    `EnvelopeRevokedError` subclass (envelope.ts). Caller must additionally
+ *    clear conn+token+envelope.
+ *  - `exchange_failed` — server-mediated exchange, 400/401/404; not retryable.
+ *  - `exchange_unavailable` — server-mediated exchange, still 502/5xx after retries.
  */
 export class NeedsReauthError extends DriveSyncError {
     constructor(message = 'Reauthentication required', opts) {