@open-webapp/drive-sync 0.5.7 → 0.7.0

package/dist/testing/gisFake.js

@@ -19,6 +19,9 @@ export function createGisFake() {
     const popupClosedRaceQueue = [];
     let silenceQueue = 0;
     const calls = [];
+    const codeResponseQueue = [];
+    const codeErrorQueue = [];
+    const codeCalls = [];
     let previousGoogle;
     let hadGoogle = false;
     function nextResponse() {
@@ -28,6 +31,45 @@ export function createGisFake() {
         // Default: a generic successful token response.
         return { access_token: 'fake-access-token', expires_in: 3600, scope: '' };
     }
+    function nextCodeResponse() {
+        const next = codeResponseQueue.shift();
+        if (next)
+            return next;
+        // Default: a generic successful auth-code response.
+        return { code: 'fake-auth-code' };
+    }
+    function initCodeClient(config) {
+        return {
+            requestCode() {
+                const hint = config.hint;
+                const scope = config.scope ?? '';
+                codeCalls.push({ scope, hint });
+                if (silenceQueue > 0) {
+                    silenceQueue -= 1;
+                    return;
+                }
+                const codeError = codeErrorQueue.shift();
+                if (codeError) {
+                    const errorCallback = config.error_callback;
+                    queueMicrotask(() => {
+                        errorCallback?.({ type: codeError });
+                    });
+                    return;
+                }
+                const response = nextCodeResponse();
+                const callback = config.callback;
+                // Deliver asynchronously (microtask), matching the real GIS code
+                // client's callback-based, non-synchronous delivery.
+                queueMicrotask(() => {
+                    if (response.error) {
+                        callback?.({ error: response.error });
+                        return;
+                    }
+                    callback?.(response);
+                });
+            },
+        };
+    }
     function initTokenClient(config) {
         return {
             requestAccessToken(overrideConfig) {
@@ -78,9 +120,16 @@ export function createGisFake() {
     }
     return {
         calls,
+        codeCalls,
         queueResponse(response) {
             responseQueue.push(response);
         },
+        queueCodeResponse(response) {
+            codeResponseQueue.push(response);
+        },
+        queueCodeError(type) {
+            codeErrorQueue.push(type);
+        },
         queuePopupError(type) {
             popupErrorQueue.push(type);
         },
@@ -104,6 +153,7 @@ export function createGisFake() {
                 w.google.accounts.oauth2 = {};
             }
             w.google.accounts.oauth2.initTokenClient = initTokenClient;
+            w.google.accounts.oauth2.initCodeClient = initCodeClient;
         },
         uninstall() {
             const w = globalThis;
@@ -120,6 +170,9 @@ export function createGisFake() {
             popupClosedRaceQueue.length = 0;
             silenceQueue = 0;
             calls.length = 0;
+            codeResponseQueue.length = 0;
+            codeErrorQueue.length = 0;
+            codeCalls.length = 0;
         },
     };
 }

package/dist/testing/index.d.ts

@@ -1,6 +1,8 @@
 export { createGisFake } from './gisFake.js';
-export type { GisFake, GisTokenResponse, GisRecordedCall } from './gisFake.js';
+export type { GisFake, GisTokenResponse, GisRecordedCall, GisCodeResponse, GisCodeRecordedCall, GisCodeClientConfig, GisCodeClient, } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
 export type { DriveFake, DriveFakeFile, DriveFakePermission, StatusOverrideOptions } from './driveFake.js';
 export { createPickerFake } from './pickerFake.js';
 export type { PickerFake, PickerFakeFile, PickerRecordedCall } from './pickerFake.js';
+export { createTokenExchangeFake } from './tokenExchangeFake.js';
+export type { TokenExchangeFake, TokenExchangeRecordedCall, CreateTokenExchangeFakeOptions, } from './tokenExchangeFake.js';

package/dist/testing/index.js

@@ -1,3 +1,4 @@
 export { createGisFake } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
 export { createPickerFake } from './pickerFake.js';
+export { createTokenExchangeFake } from './tokenExchangeFake.js';

package/dist/testing/tokenExchangeFake.d.ts

@@ -0,0 +1,67 @@
+/**
+ * An in-memory fake of the server-mediated token-exchange endpoint that
+ * drive-sync talks to when `DriveSyncOptions.tokenExchangeUrl` is set.
+ *
+ * The real server accepts `POST {tokenExchangeUrl}` with a body that is
+ * EXACTLY one of `{ code }` (new grant) or `{ envelope }` (refresh) and
+ * responds `200 { envelope }`. On a refresh it echoes the envelope
+ * unchanged while it is still fresh (`Date.now() < expiry_date - 60000`),
+ * otherwise it mints a new `payload` + `sig` under the same `guid`.
+ *
+ * Intended use:
+ *
+ * ```ts
+ * const tokenExchange = createTokenExchangeFake({ now: () => clock })
+ * tokenExchange.install()
+ * // ... exercise code under test ...
+ * expect(tokenExchange.calls[0].kind).toBe('code')
+ * tokenExchange.uninstall()
+ * ```
+ *
+ * Only requests whose URL matches the configured endpoint are intercepted;
+ * everything else falls through to whatever `globalThis.fetch` was before
+ * `install()`.
+ */
+import type { Envelope } from '../types.js';
+/** One recorded request against the fake endpoint. */
+export interface TokenExchangeRecordedCall {
+    /** `'code'` for a new-grant body, `'envelope'` for a refresh body. */
+    kind: 'code' | 'envelope';
+    /** The parsed JSON request body, exactly as received. */
+    body: unknown;
+}
+export interface TokenExchangeFake {
+    /** Swap `globalThis.fetch` for the intercepting handler. Idempotent. */
+    install(): void;
+    /** Restore the exact `globalThis.fetch` that was present at `install()`. Idempotent. */
+    uninstall(): void;
+    /** Every intercepted request, in call order. */
+    readonly calls: TokenExchangeRecordedCall[];
+    /** The most recently minted / echoed envelope, or `null` before the first call. */
+    readonly lastEnvelope: Envelope | null;
+    /** Make the next `times` (default 1) calls fail `410 refresh_token_revoked`. */
+    fail410(times?: number): void;
+    /** Make the next `times` (default 1) calls fail `502 google_unavailable`. */
+    fail502(times?: number): void;
+    /** Make the next `times` (default 1) calls fail `400 malformed_request`. */
+    failMalformed(times?: number): void;
+    /** Make the next `times` (default 1) calls fail `401 invalid_envelope_signature`. */
+    failInvalidSig(times?: number): void;
+    /** Make the next `times` (default 1) calls fail `404 unknown_guid`. */
+    failUnknownGuid(times?: number): void;
+    /**
+     * Re-stamp `lastEnvelope`'s expiry to `now() + msFromNow` (and re-sign it),
+     * so a subsequent replay of that envelope is treated as stale. Throws if no
+     * envelope has been minted yet.
+     */
+    setExpiry(msFromNow: number): Promise<void>;
+}
+export interface CreateTokenExchangeFakeOptions {
+    /** HMAC secret used to sign minted envelopes. Defaults to a fixed test value. */
+    secret?: string;
+    /** Injectable clock; defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Which crypto backend the last signing operation used. Exposed for diagnostics. */
+export declare let lastCryptoBackend: 'crypto.subtle' | 'node:crypto' | null;
+export declare function createTokenExchangeFake(opts?: CreateTokenExchangeFakeOptions): TokenExchangeFake;

package/dist/testing/tokenExchangeFake.js

@@ -0,0 +1,253 @@
+/**
+ * An in-memory fake of the server-mediated token-exchange endpoint that
+ * drive-sync talks to when `DriveSyncOptions.tokenExchangeUrl` is set.
+ *
+ * The real server accepts `POST {tokenExchangeUrl}` with a body that is
+ * EXACTLY one of `{ code }` (new grant) or `{ envelope }` (refresh) and
+ * responds `200 { envelope }`. On a refresh it echoes the envelope
+ * unchanged while it is still fresh (`Date.now() < expiry_date - 60000`),
+ * otherwise it mints a new `payload` + `sig` under the same `guid`.
+ *
+ * Intended use:
+ *
+ * ```ts
+ * const tokenExchange = createTokenExchangeFake({ now: () => clock })
+ * tokenExchange.install()
+ * // ... exercise code under test ...
+ * expect(tokenExchange.calls[0].kind).toBe('code')
+ * tokenExchange.uninstall()
+ * ```
+ *
+ * Only requests whose URL matches the configured endpoint are intercepted;
+ * everything else falls through to whatever `globalThis.fetch` was before
+ * `install()`.
+ */
+/** Default endpoint drive-sync ships with. */
+const DEFAULT_TOKEN_EXCHANGE_URL = 'https://open-webapp.duckdns.org/callback';
+/** Scope minted into every fake payload. */
+const FAKE_SCOPE = 'https://www.googleapis.com/auth/drive.file';
+/** Lifetime, in ms, of a freshly minted payload. */
+const TOKEN_LIFETIME_MS = 3_600_000;
+/** Server-side freshness skew: an envelope inside this window is echoed as-is. */
+const REFRESH_SKEW_MS = 60_000;
+/** Canonical JSON: object keys sorted recursively, no insignificant whitespace. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    const entries = Object.keys(value)
+        .sort()
+        .map((key) => JSON.stringify(key) + ':' + canonicalJson(value[key]));
+    return '{' + entries.join(',') + '}';
+}
+function base64UrlFromBytes(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 1)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Which crypto backend the last signing operation used. Exposed for diagnostics. */
+export let lastCryptoBackend = null;
+async function hmacSha256Base64Url(secret, message) {
+    const encoder = new TextEncoder();
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle) {
+        lastCryptoBackend = 'crypto.subtle';
+        const key = await subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
+            'sign',
+        ]);
+        const mac = await subtle.sign('HMAC', key, encoder.encode(message));
+        return base64UrlFromBytes(new Uint8Array(mac));
+    }
+    // Fall back to Node's crypto when Web Crypto is unavailable in the test env.
+    // Computed specifier keeps TS from trying to resolve `node:crypto` types.
+    lastCryptoBackend = 'node:crypto';
+    const specifier = 'node:' + 'crypto';
+    const nodeCrypto = await import(/* @vite-ignore */ specifier);
+    return nodeCrypto.createHmac('sha256', secret).update(message).digest('base64url');
+}
+function randomUuid() {
+    const webCrypto = globalThis.crypto;
+    if (webCrypto?.randomUUID)
+        return webCrypto.randomUUID();
+    // Extremely defensive fallback; the test env always has crypto.randomUUID.
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+function randomAccessToken() {
+    const webCrypto = globalThis.crypto;
+    const bytes = new Uint8Array(24);
+    if (webCrypto?.getRandomValues)
+        webCrypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i += 1)
+            bytes[i] = (Math.random() * 256) | 0;
+    let hex = '';
+    for (let i = 0; i < bytes.length; i += 1)
+        hex += bytes[i].toString(16).padStart(2, '0');
+    return 'ya29.' + hex;
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+function errorResponse(status, code, message) {
+    return jsonResponse(status, { error: { code, message } });
+}
+const OVERRIDE_RESPONSES = {
+    '410': () => errorResponse(410, 'refresh_token_revoked', 'The refresh token has been revoked'),
+    '502': () => errorResponse(502, 'google_unavailable', 'Upstream Google token endpoint is unavailable'),
+    malformed: () => errorResponse(400, 'malformed_request', 'The request body was malformed'),
+    invalidSig: () => errorResponse(401, 'invalid_envelope_signature', 'The envelope signature did not verify'),
+    unknownGuid: () => errorResponse(404, 'unknown_guid', 'No grant exists for that guid'),
+};
+function urlOf(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (typeof Request !== 'undefined' && input instanceof Request)
+        return input.url;
+    return String(input?.url ?? input);
+}
+async function bodyTextOf(input, init) {
+    if (init && typeof init.body === 'string')
+        return init.body;
+    if (init && init.body != null)
+        return String(init.body);
+    if (typeof Request !== 'undefined' && input instanceof Request)
+        return input.clone().text();
+    return '';
+}
+export function createTokenExchangeFake(opts = {}) {
+    const secret = opts.secret ?? 'token-exchange-fake-secret';
+    const now = opts.now ?? (() => Date.now());
+    const calls = [];
+    const overrideQueue = [];
+    let lastEnvelope = null;
+    let installed = false;
+    let previousFetch = globalThis.fetch;
+    function matchesEndpoint(rawUrl) {
+        if (rawUrl === DEFAULT_TOKEN_EXCHANGE_URL)
+            return true;
+        try {
+            return new URL(rawUrl).pathname === '/callback';
+        }
+        catch {
+            return rawUrl.endsWith('/callback');
+        }
+    }
+    async function mintEnvelope(guid) {
+        const payload = {
+            access_token: randomAccessToken(),
+            expiry_date: now() + TOKEN_LIFETIME_MS,
+            token_type: 'Bearer',
+            scope: FAKE_SCOPE,
+        };
+        const sig = await hmacSha256Base64Url(secret, canonicalJson({ v: 2, guid, payload }));
+        return { v: 2, guid, payload, sig };
+    }
+    function enqueue(kind, times) {
+        const n = Math.max(0, Math.floor(times));
+        for (let i = 0; i < n; i += 1)
+            overrideQueue.push(kind);
+    }
+    const handler = (async (input, init) => {
+        const rawUrl = urlOf(input);
+        if (!matchesEndpoint(rawUrl))
+            return previousFetch(input, init);
+        let parsed;
+        try {
+            const text = await bodyTextOf(input, init);
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            return errorResponse(400, 'malformed_request', 'The request body was not valid JSON');
+        }
+        const record = parsed !== null && typeof parsed === 'object' ? parsed : {};
+        const hasCode = record.code != null;
+        const hasEnvelope = record.envelope != null;
+        const kind = hasEnvelope && !hasCode ? 'envelope' : 'code';
+        calls.push({ kind, body: parsed });
+        const override = overrideQueue.shift();
+        if (override)
+            return OVERRIDE_RESPONSES[override]();
+        if (hasCode && hasEnvelope) {
+            return errorResponse(400, 'code_and_envelope_exclusive', 'Provide exactly one of `code` or `envelope`');
+        }
+        if (!hasCode && !hasEnvelope) {
+            return errorResponse(400, 'code_or_envelope_required', 'Provide exactly one of `code` or `envelope`');
+        }
+        if (hasCode) {
+            const minted = await mintEnvelope(randomUuid());
+            lastEnvelope = minted;
+            return jsonResponse(200, { envelope: minted });
+        }
+        const incoming = record.envelope;
+        if (incoming === null ||
+            typeof incoming !== 'object' ||
+            typeof incoming.payload !== 'object' ||
+            incoming.payload === null ||
+            typeof incoming.payload.expiry_date !== 'number' ||
+            typeof incoming.guid !== 'string') {
+            return errorResponse(400, 'malformed_request', 'The `envelope` was not a well-formed envelope');
+        }
+        if (now() < incoming.payload.expiry_date - REFRESH_SKEW_MS) {
+            lastEnvelope = incoming;
+            return jsonResponse(200, { envelope: incoming });
+        }
+        const refreshed = await mintEnvelope(incoming.guid);
+        lastEnvelope = refreshed;
+        return jsonResponse(200, { envelope: refreshed });
+    });
+    return {
+        install() {
+            if (installed)
+                return;
+            previousFetch = globalThis.fetch;
+            globalThis.fetch = handler;
+            installed = true;
+        },
+        uninstall() {
+            if (!installed)
+                return;
+            globalThis.fetch = previousFetch;
+            installed = false;
+        },
+        get calls() {
+            return calls;
+        },
+        get lastEnvelope() {
+            return lastEnvelope;
+        },
+        fail410(times = 1) {
+            enqueue('410', times);
+        },
+        fail502(times = 1) {
+            enqueue('502', times);
+        },
+        failMalformed(times = 1) {
+            enqueue('malformed', times);
+        },
+        failInvalidSig(times = 1) {
+            enqueue('invalidSig', times);
+        },
+        failUnknownGuid(times = 1) {
+            enqueue('unknownGuid', times);
+        },
+        async setExpiry(msFromNow) {
+            if (!lastEnvelope) {
+                throw new Error('createTokenExchangeFake: setExpiry() called before any envelope was minted');
+            }
+            const payload = { ...lastEnvelope.payload, expiry_date: now() + msFromNow };
+            const sig = await hmacSha256Base64Url(secret, canonicalJson({ v: 2, guid: lastEnvelope.guid, payload }));
+            lastEnvelope = { v: 2, guid: lastEnvelope.guid, payload, sig };
+        },
+    };
+}

package/dist/token.d.ts

@@ -31,6 +31,20 @@ export interface AcquireTokenOptions {
  * turns out to already be usable.
  */
 export declare function notifyExternalTokenRefresh(projectId: string): void;
+/**
+ * Records that another tab just persisted a fresh envelope for `projectId`.
+ * The next {@link import('./envelope.js').refreshEnvelope} call for this
+ * project drains the signal and re-reads the stored envelope before deciding
+ * whether a network round-trip is needed.
+ */
+export declare function notifyExternalEnvelopeRefresh(projectId: string): void;
+/**
+ * Consume (one-shot) a pending cross-tab envelope-refresh signal for
+ * `projectId`. Returns `true` when a signal was pending (and clears it),
+ * `false` otherwise. Mirrors the inline `externallyRefreshed.delete(...)`
+ * check the legacy `acquireToken` path performs.
+ */
+export declare function consumeExternalEnvelopeRefresh(projectId: string): boolean;
 /**
  * Single entry point for acquiring a Drive access token, used by BOTH the
  * interactive "connect" path (interactive: true -> prompt: '', i.e. no

package/dist/token.js

@@ -96,6 +96,34 @@ const externallyRefreshed = new Set();
 export function notifyExternalTokenRefresh(projectId) {
     externallyRefreshed.add(projectId);
 }
+/**
+ * Parallel-set mirror of {@link externallyRefreshed} for the server-mediated
+ * token-exchange path (envelope.ts `refreshEnvelope`). Kept deliberately
+ * separate from the legacy set so the two flows never consume each other's
+ * cross-tab signals: a `token` broadcast that originated from an envelope
+ * refresh drains this set, and one from a legacy GIS acquisition drains the
+ * other. Populated by {@link notifyExternalEnvelopeRefresh}, drained by
+ * {@link consumeExternalEnvelopeRefresh}.
+ */
+const externallyRefreshedEnvelope = new Set();
+/**
+ * Records that another tab just persisted a fresh envelope for `projectId`.
+ * The next {@link import('./envelope.js').refreshEnvelope} call for this
+ * project drains the signal and re-reads the stored envelope before deciding
+ * whether a network round-trip is needed.
+ */
+export function notifyExternalEnvelopeRefresh(projectId) {
+    externallyRefreshedEnvelope.add(projectId);
+}
+/**
+ * Consume (one-shot) a pending cross-tab envelope-refresh signal for
+ * `projectId`. Returns `true` when a signal was pending (and clears it),
+ * `false` otherwise. Mirrors the inline `externallyRefreshed.delete(...)`
+ * check the legacy `acquireToken` path performs.
+ */
+export function consumeExternalEnvelopeRefresh(projectId) {
+    return externallyRefreshedEnvelope.delete(projectId);
+}
 /**
  * Single entry point for acquiring a Drive access token, used by BOTH the
  * interactive "connect" path (interactive: true -> prompt: '', i.e. no

package/dist/types.d.ts

@@ -4,6 +4,34 @@ export interface DriveSyncOptions {
     clientId: string;
     folderPath: string[];
     logger?: Logger;
+    /**
+     * Opt-in: when set, connect() runs the server-mediated token-exchange flow
+     * against this URL instead of the legacy GIS implicit flow. When absent,
+     * the legacy implicit flow is used unchanged.
+     */
+    tokenExchangeUrl?: string;
+}
+/**
+ * Decoded contents of an {@link Envelope}'s `payload`. Mirrors the fields of
+ * a Google OAuth token response that drive-sync needs.
+ */
+export interface EnvelopePayload {
+    access_token: string;
+    expiry_date: number;
+    token_type: 'Bearer';
+    scope: string;
+}
+/**
+ * Opaque envelope returned by the server-side token-exchange endpoint. The
+ * `sig` is a server-side signature that is NEVER verified client-side —
+ * drive-sync treats the whole structure as opaque and simply forwards the
+ * decoded `payload` into its normal token storage.
+ */
+export interface Envelope {
+    v: 2;
+    guid: string;
+    payload: EnvelopePayload;
+    sig: string;
 }
 /**
  * Durable connection state returned by getConnection(). Survives token
@@ -31,6 +59,16 @@ export interface FileRef {
     version?: string;
     /** Drive's last-modified timestamp (RFC3339), when the call requested it. */
     modifiedTime?: string;
+    /** Drive MIME type, when the call requested it. */
+    mimeType?: string;
+    /** Short-lived Drive thumbnail URL, when the call requested it and Drive supplied one; may be absent. */
+    thumbnailLink?: string;
+    /** Pixel dimensions (+ `rotation`, 0/90/180/270) for image files, when Drive supplied them. */
+    imageMediaMetadata?: {
+        width?: number;
+        height?: number;
+        rotation?: number;
+    };
 }
 /**
  * Sync state of one file relative to what this client last restored.

package/package.json

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